Skip to content

fix(cli): keep JSON argument failures machine-readable - #331

Merged
sunsunsun-java merged 1 commit into
tt-a1i:mainfrom
QiuLsG:codex/fix-json-argument-receipts
Sep 7, 2026
Merged

sunsunsun-java merged 1 commit into
tt-a1i:mainfrom
QiuLsG:codex/fix-json-argument-receipts

Conversation

@QiuLsG

@QiuLsG QiuLsG commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Problem and value

validate --json and deliver --json promise one JSON receipt on every failure, but argument parsing errors still used the human-only failure path: exit status 2, empty stdout, and plain-text stderr. This breaks callers that unconditionally parse stdout.

Closes #330.

Scope

  • What changed: route validate --json and deliver --json argument failures through a versioned stage: "arguments" receipt; add stable CLI diagnostics for invalid or missing values, unknown options and diagram types, unsupported combinations, and usage errors; add table-driven regression coverage.
  • What deliberately did not change: human-mode stderr, exit status 2, command signatures, renderer validation, diagram schemas, output geometry, and Viewer behavior.
  • No unrelated changes: confirmed.

Stability impact

  • Compatibility and migration risk: non-JSON behavior is unchanged. JSON callers now receive the documented parseable stdout instead of plain text for argument-stage failures.
  • Renderer, validator, package, or generated-artifact risk: limited to CLI dispatch and the rebuilt Skill archive; no renderer, schema, example, or public-page changes.
  • Failure behavior and rollback path: errors still occur before input reads or output writes and retain exit status 2. Reverting this commit restores the previous human-only argument error path.

Tests run

From archify/, each command passed with 1 target test, 0 failures:

  • npx --yes node@18.20.8 --test --test-name-pattern "validate and deliver keep argument failures machine-readable with --json" test/cli.test.mjs
  • npx --yes node@20.20.2 --test --test-name-pattern "validate and deliver keep argument failures machine-readable with --json" test/cli.test.mjs
  • npx --yes node@22.23.2 --test --test-name-pattern "validate and deliver keep argument failures machine-readable with --json" test/cli.test.mjs
  • npx --yes node@24.20.0 --test --test-name-pattern "validate and deliver keep argument failures machine-readable with --json" test/cli.test.mjs

Additional results:

  • node --check archify/bin/archify.mjs: passed.
  • git diff --check: passed.
  • node --test test/cli.test.mjs: 40 passed, 1 failed, 3 skipped on each tested Node version on Windows. The sole failure is the existing installed-preview shutdown assertion: Windows reports { code: null, signal: "SIGTERM" } after the test sends SIGTERM, while the test expects a clean code 0 exit.
  • Independent extracted-package smoke with Node 22: passed on Windows. Packaged validate --json and deliver --json argument failures both returned exit status 2, valid JSON stdout, stage: "arguments", and empty stderr.
  • npm test: the brand-mark, validator, release-identity, golden-render, and new CLI regression checks passed; the overall Windows run exited 1 on existing platform/environment cases including unavailable symlinks, Bash not being on PATH, preview SIGTERM semantics, a Windows ESM drive-path fixture, and timing-sensitive notifier cases. The repository's full CI test matrix runs on Ubuntu; the Windows CI lane runs the package smoke exercised above.

Visual evidence

  • Evidence provided: Not applicable; this changes CLI failure serialization only.
  • Comparison conditions, when applicable: Not applicable.
  • Automated or browser checks: deterministic CLI assertions and extracted-package smoke listed above.
  • Perceptual visual review: Not applicable.

Generated artifacts

  • Rebuilt archify.zip with the canonical Node 22 toolchain.
  • No Gallery, guide, README proof, or example artifact changed because the patch does not affect rendering or public pages.

Checklist

  • I used a minimal focused change and preserved existing typed JSON behavior unless the issue requires a contract change.
  • I ran the relevant targeted tests and npm test in archify/.
  • I added or updated a regression test for behavioral changes.
  • I checked generated artifacts and package freshness when their sources changed.
  • I removed secrets, private repository content, and customer data from fixtures and screenshots.

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.

[Bug]: validate --json and deliver --json emit plain-text argument errors

2 participants