feat(cli): restore --json on pick/stats/diff for read-command parity#59
Merged
Merged
Conversation
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._
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this is needed
The CLI surface had drifted out of consistency:
tasks list --json(PR #54) round-tripped throughJSON.parse, buttasks pick,tasks stats, andtasks difflost their--jsonflag in commit ccf1360 (2026-03-17, "remove unused features"). One read command was JSON-scriptable, three were not.The justification for
tasks list --jsondocumented inpackages/cli/README.md:42("round-trips throughJSON.parsefor 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. Closescli-restore-json-on-read-commands(P1 hardening from PR #58).Summary
Restoring
--jsonacross all four read commands so any script can choose a command and parse its output with the sameJSON.parse(stdout)call.--jsonshapepick --json{picked: false}when empty, else{picked: true, summary, priority, file, line, metadata, candidates, unblocks}(matches commit a567140)list --json{id, summary, priority, tags, blocked, claimed, file, line}stats --jsonQueueStatsobject (total,byPriority,blocked,claimed,available,fileCount,throughput,topAgents)diff --jsonQueueDiffobject (ref,added,removed,claimed,hasChanges)Tests
Five new test cases in
packages/cli/src/cli.test.tspin the parity contract so the same drift fails CI next time:pick --json outputs structured JSONpick --json outputs {picked: false} for empty queuestats --json outputs structured JSONdiff --json outputs structured JSON(usesgit add -fto bypass any global gitignore that excludesTASKS.mdin 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
🤖 Written by an agent, not Fyodor. Ping me if this looks off.