Skip to content

feat(cli): restore --json on pick/stats/diff for read-command parity#59

Merged
fyodoriv merged 1 commit into
mainfrom
feat/cli-restore-json-pick-stats-diff
May 3, 2026
Merged

feat(cli): restore --json on pick/stats/diff for read-command parity#59
fyodoriv merged 1 commit into
mainfrom
feat/cli-restore-json-pick-stats-diff

Conversation

@fyodoriv
Copy link
Copy Markdown
Collaborator

@fyodoriv fyodoriv commented May 3, 2026

Why this is needed

The CLI surface had drifted out of consistency: tasks list --json (PR #54) round-tripped through JSON.parse, but tasks pick, tasks stats, and tasks diff lost their --json flag in commit ccf1360 (2026-03-17, "remove unused features"). One read command was JSON-scriptable, three were not.

The justification for tasks list --json documented in packages/cli/README.md:42 ("round-trips through JSON.parse for scripting") applies equally to pick/stats/diff. Scripts and CI integrations expect the four read commands to share one flag shape so they can switch between commands without re-plumbing parsing. Closes cli-restore-json-on-read-commands (P1 hardening from PR #58).

Summary

Restoring --json across all four read commands so any script can choose a command and parse its output with the same JSON.parse(stdout) call.

Command --json shape
pick --json {picked: false} when empty, else {picked: true, summary, priority, file, line, metadata, candidates, unblocks} (matches commit a567140)
list --json Unchanged — array of {id, summary, priority, tags, blocked, claimed, file, line}
stats --json Full QueueStats object (total, byPriority, blocked, claimed, available, fileCount, throughput, topAgents)
diff --json Full QueueDiff object (ref, added, removed, claimed, hasChanges)

Tests

Five new test cases in packages/cli/src/cli.test.ts pin the parity contract so the same drift fails CI next time:

  • pick --json outputs structured JSON
  • pick --json outputs {picked: false} for empty queue
  • stats --json outputs structured JSON
  • diff --json outputs structured JSON (uses git add -f to bypass any global gitignore that excludes TASKS.md in the test temp dir)
  • --help advertises --json for every read command (pick, list, stats, diff) — fails CI if any of the four read commands stops listing `--json`

Test plan

  • `npm run build` — clean
  • `npm test` — 402 tests pass (was 397, +5 new)
  • `npm run lint` — 0 errors
  • `npx -y @tasks-md/lint TASKS.md` — 0 errors
  • Manual smoke: `tasks pick --help`, `tasks stats --help`, `tasks diff --help` all list `--json`

🤖 Written by an agent, not Fyodor. Ping me if this looks off.

closes cli-restore-json-on-read-commands

Commit ccf1360 (2026-03-17, "remove unused features") dropped the
--json flag from tasks pick/stats/diff, but PR #54 (2026-05-03) added
--json to the new tasks list command. The CLI surface ended up
inconsistent: one read command was JSON-scriptable, three were not.

Restoring --json across all four read commands (pick / list / stats /
diff) so any script can choose a command and parse its output with the
same `JSON.parse(stdout)` call.

Behavior:
- pick --json: emits {picked: false} when the queue is empty,
  otherwise {picked: true, summary, priority, file, line, metadata,
  candidates, unblocks}. Same shape as the historical implementation
  in commit a567140.
- stats --json: full QueueStats object (same type the lib already
  exports — total, byPriority, blocked, claimed, available, fileCount,
  throughput, topAgents).
- diff --json: full QueueDiff object (ref, added, removed, claimed,
  hasChanges).
- list --json: unchanged.

Tests added in cli.test.ts pinning all four JSON paths plus a --help
parity check that fails CI if any read command stops advertising
--json:
- pick --json outputs structured JSON
- pick --json outputs {picked: false} for empty queue
- stats --json outputs structured JSON
- diff --json outputs structured JSON (uses git add -f to bypass any
  global gitignore that excludes TASKS.md in the test temp dir)
- --help advertises --json for every read command

Verified: npm run build, npm test (402 tests pass, +5 new), npm run
lint, npx -y @tasks-md/lint TASKS.md.

---
_🤖 Written by an agent, not Fyodor. Ping me if this looks off._
@fyodoriv fyodoriv merged commit 6c68090 into main May 3, 2026
4 checks passed
@fyodoriv fyodoriv deleted the feat/cli-restore-json-pick-stats-diff branch May 3, 2026 16:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant