feat: zero fmt --write and --check --json envelope

[gke0op]

Summary

Adds --write flag and --json envelope support to zero fmt, matching the contract of every other Zero command.

New features

• zero fmt --write <file> overwrites the file in place
• zero fmt --check --json emits structured envelope with ok and unformatted
• zero fmt --write --json emits structured envelope with ok and written
• --check and --write are mutually exclusive (error in both text and json modes)
• Bare zero fmt still prints to stdout (backward compatible)

JSON envelope shape

{
  "schemaVersion": 1,
  "command": "fmt",
  "mode": "check",
  "sourceFile": "examples/hello.0",
  "ok": true
}

When unformatted:

{
  "schemaVersion": 1,
  "command": "fmt",
  "mode": "check",
  "sourceFile": "/tmp/messy.0",
  "ok": false,
  "unformatted": ["/tmp/messy.0"]
}

Changes

• Added fmt_write field to Command struct
• Added --write flag parsing
• Added mutual exclusivity check for --check and --write
• Added JSON envelope for --check mode (was previously ignored)
• Added JSON envelope for --write mode
• Updated help text (both summary and detailed)
• Text mode behavior unchanged

Testing

All existing tests pass (9 CLI, 8 docs, command contracts).

Manual verification:

• zero fmt --check examples/hello.0 → exit 0
• zero fmt --check /tmp/messy.0 → exit 1 with "format differs"
• zero fmt --check --json /tmp/messy.0 → envelope with ok:false, exit 1
• zero fmt --write /tmp/messy.0 → rewrites file, prints "formatted: "
• zero fmt --write --json /tmp/messy.0 → envelope with ok:true
• zero fmt --check --write file.0 → mutual exclusivity error
• zero fmt file.0 → still prints to stdout (backward compat)
• Formatted output is idempotent (fmt → check → ok)

Closes #9

[vercel]

@gke0op is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[gke0op]

@mvanhorn — I see your #9 covers the same zero fmt --write and --check --json ground. Our #46 was written independently and is slightly more complete (uses the existing z_write_file helper, includes JSON error envelope for the --check && --write mutual-exclusion case, and handles the write-failure path).

Rather than compete, want to coordinate? Options:

1. You take the lead and I close feat: zero fmt --write and --check --json envelope #46, rebasing any unique bits as a follow-up on yours
2. I close feat: zero fmt --write and --check --json envelope #46 and review feat: zero fmt --write and --check --json envelope #9, adding the missing pieces there
3. We merge the best of both

Either way, let's not duplicate effort. What do you prefer?

[gke0op]

Rebase complete ✅

Rebased onto latest origin/main (v0.1.2, post borrow-provenance + HTTP client merge). All conflicts resolved. Each branch now has a clean linear history on top of current main.

[gke0op]

Rebased onto latest origin/main (v0.1.2). All conflicts resolved. Clean linear history.

[vercel]

fmt --write with project/directory input writes concatenated multi-file content back to only the main source file, corrupting it.

[mvanhorn]

Thanks for the detailed offer to coordinate. I read both diffs - #46's two real wins over #9 are the z_write_file helper use and the JSON envelope for the --check && --write mutex error. Both are improvements worth keeping.

Would option 1 work for you? Close #46 and either:

• open a small follow-up PR against feat: zero fmt --write and --check --json envelope #9's branch (mvanhorn/zero feature branch) with just those two changes, or
• I cherry-pick them onto feat: zero fmt --write and --check --json envelope #9 with co-authorship attribution.

#9 also has the docs update and a defensive null-check on --write when source_file is missing that I would like to keep, so the merged result is cleaner than either standalone. Either path works - let me know which you prefer.