Conversation
Spec for #383: settles the open questions (shared OutputFormat enum, `text` default, stdout/stderr discipline, error envelopes, schema versioning, bundled stubs) and defines the per-command JSON schema. Also corrects the docs/.prettierignore comment: design docs are tracked in git.
active-version, auth status, build, config gc, config validate, deploy, healthcheck, provision and rollback accept --format text|json. JSON mode writes one versioned envelope to stdout and routes logs and child-process stdout to stderr; text mode is byte-identical to before. Adapters now return typed outcomes (ActionOutcome, ProvisionReport, GcReport) instead of printing their results, and every inheriting child spawn goes through edgezero_adapter::process::status, enforced by a clippy disallowed-methods lint. Closes #383
This branch has not been deployed
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.
Summary
key=valuelog lines that were never a stable contract. Nine commands now accept--format json:active-version,auth status,build,config gc,config validate,deploy,healthcheck,provisionandrollback. Each one writes a single versioned envelope,{ schema_version, command, ok, result, error }, to stdout, on success and on failure.cargo,fastly,wrangler,spin, manifest commands) go to stderr. A new clippydisallowed-methodslint means future code can't bypass this.--format textis the default, and its output is byte-identical tomain.docs/superpowers/specs/2026-09-25-cli-format-json-design.md.config diff --format jsonis unchanged.Changes
edgezero-adapter(registry.rs)Adapter::executereturnsActionOutcome,provisionreturnsProvisionReport,gc_config_entriesreturnsGcReport, instead of()or prose lines. A negative result that was still measured (unhealthy probe, unauthenticated session, partly failed gc) is anOkoutcome carrying afailuremessage.edgezero-adapter(process.rs, new)process::status, the one sanctioned inheriting spawn.edgezero-adapter(cli_support.rs)native_auth_status.run_native_cligoes throughprocess::status.edgezero-adapter-{fastly,cloudflare,spin,axum}version=/healthy=/status-code=/rolled-back-to=data lines; the CLI prints the same bytes. All inheriting spawns go throughprocess::status.edgezero-cli(output.rs, new)OutputScope(routes stdout while alive),Failure/Outcome, the envelope, and the serde wire schema, kept separate from the adapter types so internal refactors can't change the JSON.edgezero-cli(args.rs)OutputFormat { Text, Json }and a--formatflag on the nine commands.DiffFormatis unchanged.edgezero-cli(lib.rs,auth.rs,provision.rs,config.rs,adapter.rs)run_*keeps its public signature and emits the envelope itself, so CLIs already generated from the template get JSON without regeneratingmain.rs. The logger'sinfooutput moves to stderr under JSON.clippy.tomldisallowed-methodsforCommand::status/Command::spawn. Piped spawns carry a documented#[expect].edgezero-cli/tests/format_json.rs(new)docs/guide/cli-reference.md--formaton each command, plus a new "Machine-readable output" section covering the envelope, streams, exit codes, compatibility policy, per-command schemas and changelog.docs/superpowers/specs/…-cli-format-json-design.mdCloses
Closes #383
Test plan
cargo test --workspace --all-targetscargo clippy --workspace --all-targets --all-features -- -D warningscargo fmt --all -- --checkcargo check --workspace --all-targets --features "fastly cloudflare spin"wasm32-wasip1(Fastly) /wasm32-wasip2(Spin) /wasm32-unknown-unknown(Cloudflare), via the fullformat.ymlwasm clippy matrix andcargo check -p edgezero-adapter-spin --target wasm32-wasip2 --features spinexamples/app-demoworkspace:cd examples/app-demo && cargo test --workspace --all-targets(--locked), plus its fmt and clippycd docs && npm run lint && npm run format && npm run buildedgezero serve --adapter axum(not applicable:serveis out of scope)main: both binaries ran 21 hermetic scenarios (success and failure paths for every in-scope command, a usage error, the bundled stub), with stdout, stderr and exit codes identical in all of them.cargo test -p edgezero-cli --test generated_project_builds -- --ignored,cargo test -p edgezero-adapter-fastly --features cli, and thecheck_no_nested_app_configsteps.Checklist
{id}syntax (not:id)edgezero_core(nothttpcrate)KvRegistry/ConfigRegistry/SecretRegistry(not the legacy single-handle setters) — see spec §6.6