Skip to content

feat: add ataegina up --json (one-shot slot + readiness)#30

Merged
noahhyden merged 1 commit into
mainfrom
feat/up-json
Jul 20, 2026
Merged

feat: add ataegina up --json (one-shot slot + readiness)#30
noahhyden merged 1 commit into
mainfrom
feat/up-json

Conversation

@noahhyden

Copy link
Copy Markdown
Owner

What & why

Fourth of five agent-native additions (docs/design/agent-native.md). Closes the "run up, then separately run ports to learn the slot" round-trip: up --json prints one JSON line — the ports --json slot shape plus started (surfaces launched) and a per-surface ready:

{"index":0,"repo_root":"","frontend":{"port":5173,"url":""},"backend":{"port":8000,"url":""},"log_dir":"","db":null,"started":["backend"],"ready":{"backend":true}}
  • All human log/hook output goes to stderr (fd-3 swap), so stdout is pure JSON.
  • ready honors --wait: with --wait it reflects the wait outcome and the exit code follows --wait (0, or 75 on a not-ready deadline); a plain --json does a single immediate check and stays exit 0 (fire-and-forget).
  • restart --json works too — its stop-phase chatter is routed to stderr (fd-4 swap) so stdout is a single JSON line.
  • The readiness section is unified (strict ate_wait_ready for --json/--wait, best-effort ate_report_ready otherwise); plain up behavior is unchanged.

Discipline

  • Spec: docs/design/agent-native.md.
  • Tests-first: tests/up_json.bats — 10 hermetic tests. Stdout purity proven by capturing stdout/stderr into separate vars (no run --separate-stderr, so no bats-1.5 dependency across CI runners); started/ready for backend/both/none; ready=true via a fake ss; the --wait 75 + ready-false path; db object; restart --json purity.
  • Live verification: real python backend → up --wait --json gives ready:{backend:true} exit 0; never-binds → --wait=1 --json exit 75 ready:false; restart --json emits a single clean JSON line.
  • Mutation red-teaming: drop-stdout-restore (JSON leaks to stderr), ready-always-false, and started-omits-frontend — each caught by distinct tests.
  • Docs: README, man page, CHANGELOG, bash+zsh completion, in-script --help. Checksum regenerated. No new dependencies.

🤖 Generated with Claude Code

After starting the resolved scope, print one machine-readable JSON line on
stdout — the ports --json slot shape plus `started` (the surfaces this
invocation launched) and a per-surface `ready` boolean — so an agent learns
the slot and readiness in a single call instead of running up then ports.
All human log/hook output is routed to stderr (fd 3 swap) so stdout stays
pure JSON.

`ready` honors --wait's polling: with --wait it reflects the wait outcome
(and the exit code still follows --wait: 0, or 75 on a not-ready deadline);
a plain --json does a single immediate check and stays exit 0
(fire-and-forget). `restart --json` also works — its stop-phase chatter is
routed to stderr (fd 4 swap) so stdout is a single JSON line. The readiness
section is unified (strict ate_wait_ready path for --json/--wait, best-effort
ate_report_ready otherwise) with the plain-`up` behavior unchanged.

Spec: docs/design/agent-native.md. Completion (bash+zsh), man page, README,
CHANGELOG, and in-script --help updated. New hermetic suite tests/up_json.bats
(10 tests) proves stdout purity (stdout/stderr captured separately, no bats
1.5 dependency), started/ready for backend|both|none, ready=true via a fake
`ss`, the --wait 75/ready-false path, db object, and restart --json purity.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@noahhyden
noahhyden merged commit 938221f into main Jul 20, 2026
8 checks passed
@noahhyden
noahhyden deleted the feat/up-json branch July 20, 2026 00:20
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