feat: add CLI --version, help command, and input validation (sprint e2e-s1.1-26544203024)

.gitattributes

@@ -1,2 +1,3 @@
 # Force LF line endings for shell scripts — CRLF breaks bash on Windows
 *.sh text eol=lf
+tool text eol=lf

feedback.md

@@ -0,0 +1,72 @@
+# fleet-e2e-toy e2e-s1.1-26544203024 - Code Review
+
+**Reviewer:** reviewer
+**Date:** 2026-05-27 18:30:00+00:00
+**Verdict:** APPROVED
+
+---
+
+## 1. Tests and Quality Gates
+
+All 29 tests pass (8 validation, 11 notes API, 8 CLI). Lint is clean. TypeScript build succeeds with no errors. **PASS.**
+
+---
+
+## 2. Feature: --version / -v (Issue gh-toy-4ef)
+
+`src/cli.ts:22-27` correctly detects `--version` and `-v`, reads version from `package.json` at runtime (avoiding drift), prints `fleet-e2e-toy v1.0.0`, and exits 0. Version check runs before command dispatch as specified. Tests verify both flags, output string, and exit code. **PASS.**
+
+---
+
+## 3. Feature: help / --help / -h (Issue gh-toy-kbk)
+
+`src/cli.ts:30-33` handles all three triggers. Help text lists both subcommands (`help`, `add`) and both flag pairs (`--version/-v`, `--help/-h`). Exit code 0. Tests verify all three triggers and assert presence of every subcommand and flag in output. **PASS.**
+
+---
+
+## 4. Feature: Input Validation (Issue gh-toy-v6z)
+
+**Previously FAIL — now PASS.** The doer fixed the deviation from plan T1.4 in commit `df4a52f`. `cli.ts:7` imports `validateCliArg` from `./utils/validation`, and `cli.ts:40` calls it with `validateCliArg(title ?? "")`. The inline duplication is gone. The error message now flows from the shared helper in `validation.ts:14`. No dead code remains. Tests still pass — the error message format changed slightly (from hardcoded to helper-provided) but tests assert `"Error"` substring which matches both. **PASS.**
+
+---
+
+## 5. Wrapper Scripts (tool, tool.cmd)
+
+**Previously FAIL — now PASS.** The doer fixed the CRLF issue in commit `9444946`. `.gitattributes` now contains `tool text eol=lf` alongside the existing `*.sh text eol=lf` rule. Verified: `git show HEAD:tool | xxd` confirms the git blob stores LF endings (`0a`, no `0d0a`). The working copy on Windows shows CRLF due to checkout normalization, which is expected and correct — on Linux/macOS CI, git will check out LF as specified. **PASS.**
+
+---
+
+## 6. Test Quality
+
+Tests use `spawnSync` for true end-to-end CLI testing — correct approach. Platform handling uses `node -r ts-node/register` directly rather than the wrapper scripts, which avoids platform-specific wrapper issues in tests but means the wrapper scripts themselves are untested. The wrappers are thin enough (2 lines each) that this is acceptable. **NOTE** — not a blocking issue.
+
+The `NODE_OPTIONS: "--loader ts-node/esm"` env var in the test helper is redundant since `-r ts-node/register` handles module loading, but it causes no failures. Minor cleanup opportunity for a future sprint.
+
+---
+
+## 7. File Hygiene
+
+Changed files from `git diff --name-only main..HEAD`: `src/cli.ts`, `src/utils/validation.ts`, `tests/cli.test.ts`, `tool`, `tool.cmd`, `.gitattributes`, `plan.md`, `requirements.md`, `progress.json`, `feedback.md`. All justified by sprint requirements or review process. No spurious files. No CLAUDE.md committed. **PASS.**
+
+---
+
+## 8. Existing Behavior Regression
+
+No existing API routes, exports, or tests were modified. All 21 pre-existing tests still pass. `src/cli.ts` is a new entry point with no coupling to the REST API. The addition of `validateCliArg` and `CliArgValidationResult` to `validation.ts` are additive exports that don't affect existing consumers. **PASS.**
+
+---
+
+## 9. Security
+
+No injection vectors — CLI args are used for string comparison only, not interpolated into shell commands or eval'd. `fs.readFileSync` reads a known local file (`package.json`). No secrets in code. **PASS.**
+
+---
+
+## Summary
+
+Both issues from the prior review have been resolved:
+
+1. **CRLF on `tool` script** — fixed via `.gitattributes` rule and re-normalization. Git blob confirmed LF.
+2. **`validateCliArg` not used** — fixed by importing and calling the shared helper, eliminating inline duplication.
+
+All 29 tests pass. Lint clean. Build clean. All three sprint requirements (--version, help, input validation) are implemented per plan and requirements. No regressions, no security issues, clean file hygiene. **APPROVED.**

plan.md

@@ -1,32 +1,95 @@
-# Feature: NoteAPI v2 — Search, Pagination, and Archiving
-
-## Problem Statement
-The API supports basic CRUD but lacks the query features users need for real use: filtering by tag, searching content, paginating large result sets, and archiving old notes without deleting them.
-
-## Approach
-Add four features incrementally. Each feature is independent — no ordering dependencies. All use the existing in-memory store (no database changes). Each feature must have tests before it's considered done.
-
-## Phases
-
-### Phase 1: Tag Filtering
-- [ ] GET /api/notes?tag=work returns only notes with that tag
-- [ ] Tests: single tag, no match, multiple tags on same note
-- Integration test: `curl localhost:3000/api/notes?tag=work`
-
-### Phase 2: Full-Text Search
-- [ ] GET /api/notes?q=meeting searches title and content (case-insensitive)
-- [ ] Tests: match in title, match in content, no match, empty query returns all
-- Integration test: `curl localhost:3000/api/notes?q=meeting`
-
-### Phase 3: Pagination
-- [ ] GET /api/notes?page=1&limit=10 returns paginated results
-- [ ] Response format: `{ data: [...], total: N, page: N, limit: N }`
-- [ ] Default: page 1, limit 20
-- Integration test: create 25 notes, verify page 1 has 20, page 2 has 5
-
-### Phase 4: Note Archiving
-- [ ] Add `archived: boolean` field to Note model (default: false)
-- [ ] POST /api/notes/:id/archive and /api/notes/:id/unarchive endpoints
-- [ ] GET /api/notes excludes archived by default
-- [ ] GET /api/notes?include_archived=true includes them
-- Integration test: archive a note, verify it's hidden, unarchive, verify it's back
+# fleet-e2e-toy CLI Features — Implementation Plan
+
+> Add three CLI capabilities to the NoteAPI project: a --version flag, a help command, and input validation for empty/blank string arguments. All three features share the CLI entry point (src/cli.ts) and are delivered in one cohesive phase.
+
+---
+
+## Phase 0 — Exploration Findings
+
+### What exists on main (verified)
+- `src/app.ts`, `src/api/notes.ts`, `src/models/note.ts`, `src/utils/validation.ts` — REST API only, no CLI entry point
+- `src/index.ts` — Express server start, not a CLI dispatcher
+- `tests/notes.test.ts`, `tests/validation.test.ts` — Jest + supertest tests, no CLI tests
+- `package.json` — version `"1.0.0"`, `ts-node` in devDependencies, no `bin` field
+- No `./tool` wrapper script exists anywhere
+
+### Assumptions verified
+| Assumption | How verified | Result |
+|------------|-------------|--------|
+| No existing CLI entry point | `git ls-tree origin/main -r` — no src/cli.ts | Confirmed absent |
+| ts-node available for CLI execution | package.json devDependencies includes ts-node | Confirmed present |
+| Project version is "1.0.0" | package.json `"version": "1.0.0"` | Confirmed |
+| Tests use Jest with no special CLI runner | jest.config.ts, existing test files | Confirmed Jest |
+| No "bin" field in package.json | Read package.json | Confirmed absent |
+
+### Unverified assumptions (risk register)
+- Whether `./tool` wrapper script (Unix shebang) executes correctly on Windows CI — moved to risk register
+- Whether reading version from package.json at runtime via `require` works with ts-node — moved to risk register
+
+---
+
+## Tasks
+
+### Phase 1: CLI Entry Point and All Three Features
+
+All three issues (--version, input validation, help) share `src/cli.ts`. Splitting them would require touching the same file multiple times and produce non-functional intermediate commits. They belong in one phase.
+
+#### Task T1.1: Create CLI entry point and wrapper scripts
+- **Change:** Create `fleet-e2e-toy/src/cli.ts` with argument parsing skeleton (process.argv). Create `fleet-e2e-toy/tool` (Unix shell wrapper invoking `ts-node src/cli.ts`) and `fleet-e2e-toy/tool.cmd` (Windows equivalent). Make wrapper scripts executable. Enforce LF line endings via `.gitattributes`.
+- **Files:** `fleet-e2e-toy/src/cli.ts` (new), `fleet-e2e-toy/tool` (new), `fleet-e2e-toy/tool.cmd` (new)
+- **Tier:** cheap
+- **Done when:** `./tool` executes without error on Unix; `tool.cmd` executes on Windows; no flags yet — exit 0 with no output is acceptable
+- **Blockers:** None — ts-node is present; no new dependencies required
+
+#### Task T1.2: Implement --version / -v flag
+- **Change:** In `fleet-e2e-toy/src/cli.ts`, detect `--version` or `-v` in argv, print `fleet-e2e-toy v1.0.0` (read from package.json at runtime to avoid drift), then `process.exit(0)`. Version check runs before any command dispatch so it works alongside other flags.
+- **Files:** `fleet-e2e-toy/src/cli.ts`
+- **Tier:** cheap
+- **Done when:** `./tool --version` prints `fleet-e2e-toy v1.0.0` and exits 0; `./tool -v` does the same
+- **Blockers:** `require('../package.json')` needs `resolveJsonModule: true` in tsconfig — check before implementing; if missing, add it or hardcode the version string
+
+#### Task T1.3: Implement help subcommand and --help / -h flag
+- **Change:** In `fleet-e2e-toy/src/cli.ts`, handle the `help` subcommand, `--help`, and `-h`. Print usage text listing all subcommands (`help`, `add`) and all flags (`--version / -v`, `--help / -h`). Exit code 0.
+- **Files:** `fleet-e2e-toy/src/cli.ts`
+- **Tier:** standard
+- **Done when:** `./tool help`, `./tool --help`, and `./tool -h` all print usage text covering every flag and subcommand; exit code is 0 in all three cases
+- **Blockers:** None
+
+#### Task T1.4: Add input validation for empty/blank string arguments
+- **Change:** Add `validateCliArg(value: string): { valid: boolean; error?: string }` to `fleet-e2e-toy/src/utils/validation.ts`. Add a minimal `add <title>` subcommand to `fleet-e2e-toy/src/cli.ts` that accepts a title argument and calls this helper — if empty or whitespace-only, print a user-friendly error to stderr and `process.exit(1)`. This gives the validator a real CLI caller so acceptance criteria can be tested end-to-end.
+- **Files:** `fleet-e2e-toy/src/utils/validation.ts`, `fleet-e2e-toy/src/cli.ts`
+- **Tier:** standard
+- **Done when:** `./tool add ""` prints a user-friendly error and exits non-zero; `./tool add "   "` (whitespace-only) does the same; `./tool add "My Note"` proceeds without error
+- **Blockers:** None — validation.ts already exists and can be extended without changing existing exports
+
+#### Task T1.5: Add CLI unit tests
+- **Change:** Create `fleet-e2e-toy/tests/cli.test.ts`. Use `child_process.spawnSync` to invoke the tool for end-to-end behavior tests. Cover: `--version` output and exit code 0, `-v` alias, `--help` / `-h` / `help` each exits 0 and includes expected strings, empty-string arg exits non-zero, whitespace-only arg exits non-zero, valid title arg exits 0.
+- **Files:** `fleet-e2e-toy/tests/cli.test.ts` (new)
+- **Tier:** standard
+- **Done when:** `npm test` passes all new tests with zero failures; existing `notes.test.ts` and `validation.test.ts` still pass
+- **Blockers:** Windows CI path for `./tool` differs — use platform-conditional invocation in test (invoke `tool.cmd` on win32, `./tool` on others)
+
+#### VERIFY: Phase 1 — CLI Features
+- Run `npm test` from `fleet-e2e-toy/` — all tests must pass (new CLI tests + existing notes and validation tests)
+- Manually invoke `./tool --version`, `./tool --help`, `./tool add ""`, `./tool add "Valid Title"` and confirm output matches acceptance criteria
+- Confirm exit codes: 0 for version/help, non-zero for invalid input
+- Report: tests passing, any regressions, any issues found
+
+---
+
+## Risk Register
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| `./tool` Unix wrapper doesn't run on Windows CI | med | Add `tool.cmd` Windows wrapper; tests use platform-conditional invocation (spawnSync with `tool.cmd` on win32) |
+| `require('../package.json')` fails if `resolveJsonModule` not in tsconfig | med | Check tsconfig before implementing T1.2; add flag if missing or hardcode version string |
+| Shell script CRLF line endings (created on Windows) | high | Run `sed -i 's/\r$//' tool` before committing; enforce via `.gitattributes text eol=lf` for wrapper scripts |
+| Backward compat: existing REST API behavior | low | CLI is a new entry point (src/cli.ts); no existing API routes or exports are touched |
+| Partial failure: --version works but help output is incomplete | low | T1.5 tests assert specific strings appear in help output — incomplete output causes test failure |
+
+## Notes
+- Each task results in one git commit
+- VERIFY is a checkpoint — stop and report after completing Phase 1
+- Base branch: `main`
+- Implementation branch: `e2e-s1.1-26544203024-cli-features`
+- Work directory: `fleet-e2e-toy/` subdirectory

progress.json

@@ -0,0 +1,67 @@
+{
+  "project": "fleet-e2e-toy",
+  "sprint": "e2e-s1.1-26544203024",
+  "plan_file": "plan.md",
+  "created": "2026-05-27",
+  "tasks": [
+    {
+      "id": "T1.1",
+      "phase": 1,
+      "step": "Create CLI entry point and wrapper scripts",
+      "type": "work",
+      "status": "completed",
+      "tier": "cheap",
+      "commit": "f62c91d",
+      "notes": "Created src/cli.ts with argument parsing skeleton, tool (Unix wrapper), and tool.cmd (Windows wrapper). LF line endings enforced via .gitattributes."
+    },
+    {
+      "id": "T1.2",
+      "phase": 1,
+      "step": "Implement --version / -v flag",
+      "type": "work",
+      "status": "completed",
+      "tier": "cheap",
+      "commit": "ea7ca86",
+      "notes": "Reads version from package.json, prints 'fleet-e2e-toy vX.X.X', exits 0. Handles both --version and -v."
+    },
+    {
+      "id": "T1.3",
+      "phase": 1,
+      "step": "Implement help subcommand and --help / -h flag",
+      "type": "work",
+      "status": "completed",
+      "tier": "standard",
+      "commit": "e55a85a",
+      "notes": "Handles help subcommand, --help, and -h flags. Prints usage text with all commands and flags. Exits 0."
+    },
+    {
+      "id": "T1.4",
+      "phase": 1,
+      "step": "Add input validation for empty/blank string arguments",
+      "type": "work",
+      "status": "completed",
+      "tier": "standard",
+      "commit": "0e61bac",
+      "notes": "Added validateCliArg to validation.ts. Implemented 'add <title>' subcommand with validation. Rejects empty/whitespace strings, exits non-zero on error."
+    },
+    {
+      "id": "T1.5",
+      "phase": 1,
+      "step": "Add CLI unit tests",
+      "type": "work",
+      "status": "completed",
+      "tier": "standard",
+      "commit": "664e5ad",
+      "notes": "Created tests/cli.test.ts with end-to-end tests using spawnSync. Tests cover --version, -v, help, --help, -h, and add validation."
+    },
+    {
+      "id": "VERIFY-1",
+      "phase": 1,
+      "step": "VERIFY: Phase 1 - CLI Features",
+      "type": "verify",
+      "status": "completed",
+      "commit": "62da8cd",
+      "notes": "All tests passing (29/29). CLI features implemented: --version/-v, help/--help/-h, input validation for 'add' command."
+    }
+  ]
+}

requirements.md

@@ -0,0 +1,41 @@
+# Sprint Requirements — fleet-e2e-toy (e2e-s1.1-26544203024)
+
+Three P1 issues selected from `bd ready` for this sprint.
+
+## Issue 1 — gh-toy-4ef: Add --version flag to CLI
+
+**Goal:** The CLI tool should support a `--version` (or `-v`) flag that prints the current version string and exits with code 0.
+
+**Acceptance criteria:**
+- Running `./tool --version` prints `fleet-e2e-toy v1.0.0`
+- Exit code 0
+- Works alongside other flags
+
+**External:** gh-1
+
+---
+
+## Issue 2 — gh-toy-v6z: [bug] Add input validation for empty or blank strings
+
+**Goal:** When a user passes an empty string or whitespace-only string as an argument, the tool should reject it with a clear error message instead of silently proceeding or crashing.
+
+**Acceptance criteria:**
+- Passing empty or whitespace string prints user-friendly error message
+- Non-zero exit code on invalid input
+- Unit test added
+
+**External:** gh-2
+
+---
+
+## Issue 3 — gh-toy-kbk: Implement a help command
+
+**Goal:** Add a help subcommand (and `--help` / `-h` flag) that prints usage information for all available commands and flags.
+
+**Acceptance criteria:**
+- `./tool help` works
+- `./tool --help` works
+- Lists every subcommand and flag
+- Exit code 0
+
+**External:** gh-3

src/cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// CLI entry point for fleet-e2e-toy
+
+import * as fs from "fs";
+import * as path from "path";
+import { validateCliArg } from "./utils/validation";
+
+const args = process.argv.slice(2);
+
+const helpText = `Usage: fleet-e2e-toy [command] [options]
+
+Commands:
+  help        Show this help message
+  add         Add a new note
+
+Options:
+  --version, -v    Show version information
+  --help, -h       Show this help message`;
+
+// Check for --version or -v flag
+if (args.includes("--version") || args.includes("-v")) {
+  const packagePath = path.join(__dirname, "../package.json");
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+  console.log(`fleet-e2e-toy v${packageJson.version}`);
+  process.exit(0);
+}
+
+// Check for help subcommand or --help / -h flags
+if (args.includes("help") || args.includes("--help") || args.includes("-h")) {
+  console.log(helpText);
+  process.exit(0);
+}
+
+// Handle add subcommand
+if (args.length > 0 && args[0] === "add") {
+  const title = args[1];
+
+  // Validate title argument
+  const validation = validateCliArg(title ?? "");
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    process.exit(1);
+  }
+
+  // If validation passes, continue (placeholder for actual add logic)
+  process.exit(0);
+}
+
+if (args.length === 0) {
+  process.exit(0);
+}

src/utils/validation.ts

@@ -5,6 +5,18 @@ export interface ValidationError {
   message: string;
 }
 
+export interface CliArgValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+export function validateCliArg(value: string): CliArgValidationResult {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return { valid: false, error: "Argument must be a non-empty string" };
+  }
+  return { valid: true };
+}
+
 export function validateCreateInput(
   body: unknown
 ): { valid: true; data: CreateNoteInput } | { valid: false; errors: ValidationError[] } {