feat: standardize on --json flag (deprecate --format json)

Addresses F1 from AGENT_NATIVE_AUDIT.md.

Author: AlephNotation

F1-json-flag.md

@@ -0,0 +1,78 @@
+# F1: --format json → --json (completed)
+
+Implemented finding F1 from `AGENT_NATIVE_AUDIT.md`. vers-cli now standardizes on `--json` across the entire command surface, with `--format` retained as a hidden, deprecated alias.
+
+## Changed files
+
+```
+ README.md                          | 12 +++---
+ cmd/branch.go                      | 12 ++++--
+ cmd/commit.go                      | 36 ++++++++++++----
+ cmd/deploy.go                      | 12 ++++--
+ cmd/env.go                         | 10 +++--
+ cmd/info.go                        | 12 ++++--
+ cmd/pause.go                       | 12 ++++--
+ cmd/repo.go                        | 48 ++++++++++++++++-----
+ cmd/resize.go                      | 12 ++++--
+ cmd/resume.go                      | 12 ++++--
+ cmd/run.go                         | 12 ++++--
+ cmd/run_commit.go                  | 12 ++++--
+ cmd/status.go                      | 12 ++++--
+ cmd/tag.go                         | 24 +++++++----
+ internal/presenters/format.go      | 24 +++++++++--
+ internal/presenters/format_test.go | 37 +++++++++++++----
+ 16 files changed, 224 insertions(+), 75 deletions(-)
+```
+
+19 cobra `--format` registrations now have a sibling `--json` BoolVar; 19 `pres.ParseFormat` call sites now pass the JSON flag and propagate the validation error.
+
+Commit: `6744100 feat: standardize on --json flag (deprecate --format json)` on branch `pi-parallel-d95f3d3f-0`.
+
+## Design choices
+
+1. **Centralized validation in `presenters.ParseFormat`.** New signature: `ParseFormat(quiet, jsonFlag bool, formatStr string) (OutputFormat, error)`. Precedence is `quiet > json > format > default`. Invalid `--format` values return an enumerated error rather than silently falling through to default-format (which was the previous behavior — a P3 violation).
+2. **Cobra's `MarkDeprecated` handles the warning.** It prints `Flag --format has been deprecated, use --json instead` to stderr automatically when the flag is used, and hides the flag from `--help`. No custom warning code needed.
+3. **Stdout/stderr separation preserved.** Deprecation warnings go to stderr; JSON data continues to land cleanly on stdout. `vers status --format json | jq` still works without contamination.
+
+## Validation
+
+- `go build ./...` — clean
+- `go vet ./...` — clean
+- `go test ./...` — all packages pass (including expanded `format_test.go` with 9 cases covering the new precedence and error semantics)
+
+Smoke tests against built binary:
+
+```
+$ vers status --json
+[]                                            # exit 0, clean stdout
+
+$ vers status --format json 2>/tmp/err
+[]                                            # exit 0, JSON on stdout
+$ cat /tmp/err
+Flag --format has been deprecated, use --json instead
+
+$ vers status --format yaml
+Flag --format has been deprecated, use --json instead
+Error: --format must be "json" (got: "yaml"). Note: --format is deprecated, use --json instead
+                                              # exit 1
+```
+
+`vers status --help` no longer lists `--format`; long descriptions everywhere now read "Use --json for machine-readable output."
+
+## Risks / open questions
+
+- **Usage banner printed on RunE error.** When `--format yaml` is rejected, cobra prints the command's usage block after the error. This is pre-existing behavior — `SilenceUsage = true` is only set in the auth path in `cmd/root.go:210`. Out of scope for F1, but worth a follow-up if cleaner agent-facing errors are wanted (set `SilenceUsage = true` on the root command).
+- **`alias` command is still missing JSON output entirely.** This is finding F2, separate task.
+- **No tests assert deprecation warning emission to stderr.** The cobra `MarkDeprecated` behavior is library-provided and stable, so I didn't add an integration test capturing stderr; the unit tests exercise only the validation path. If desired, a small `cmd/`-level test could capture stderr from a `--format json` invocation.
+
+## Recommended next step
+
+Hand off to F2 (info → get) and F3 (pagination) as planned. After both land, audit the few commands that have a `--quiet` flag but no `--json` (`alias`, possibly `head`, `checkout`) and unify those — the `ParseFormat` machinery is already in place to extend them cheaply.
+
+---
+
+Implemented F1 (canonical `--json` flag).
+Changed files: 16 (13 cmd files, presenters package, README).
+Validation: `go build`, `go vet`, `go test ./...` all clean; manual smoke tests confirm `--json` works, legacy `--format json` works with stderr deprecation, invalid `--format` values error with the enumerated message.
+Open risks/questions: usage banner on error is pre-existing; no integration test for deprecation warning.
+Recommended next step: proceed with F2 and F3 as planned.

README.md

@@ -54,11 +54,11 @@ vers status
 vers status -q
 
 # Full JSON output
-vers status --format json
+vers status --json
 
 # Detailed metadata for a VM (IP, lineage, timestamps)
 vers info <vm-id>
-vers info --format json
+vers info --json
 
 # Execute a command on a VM
 vers execute <vm-id> <command> [args...]
@@ -91,7 +91,7 @@ vers commit <vm-id>
 # List your commits
 vers commit list
 vers commit list -q               # just IDs
-vers commit list --format json
+vers commit list --json
 vers commit list --public         # public commits
 
 # View commit history (parent chain)
@@ -118,7 +118,7 @@ vers tag create production abc-123 -d "stable release"
 # List all tags
 vers tag list
 vers tag list -q                  # just names
-vers tag list --format json
+vers tag list --json
 
 # Get tag details
 vers tag get <name>
@@ -150,8 +150,8 @@ vers tag delete $(vers tag list -q)
 vers info $(vers status -q | head -1)
 
 # JSON piped to jq
-vers status --format json | jq '.[].vm_id'
-vers info <vm-id> --format json | jq '.ip'
+vers status --json | jq '.[].vm_id'
+vers info <vm-id> --json | jq '.ip'
 ```
 
 `ps` is an alias for `status`:

cmd/branch.go

@@ -11,6 +11,7 @@ import (
 var (
 	alias        string
 	branchCount  int
+	branchJSON bool
 	branchFormat string
 	branchWait   bool
 )
@@ -21,7 +22,7 @@ var branchCmd = &cobra.Command{
 	Short: "Create a new VM from an existing VM",
 	Long: `Create a new VM (branch) from the state of an existing VM. If no VM ID or alias is provided, uses the current HEAD.
 
-Use --format json for machine-readable output.
+Use --json for machine-readable output.
 Use --wait to block until new VMs are running.`,
 	Args: cobra.MaximumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -45,7 +46,10 @@ Use --wait to block until new VMs are running.`,
 			return err
 		}
 
-		format := pres.ParseFormat(false, branchFormat)
+		format, err := pres.ParseFormat(false, branchJSON, branchFormat)
+		if err != nil {
+			return err
+		}
 		switch format {
 		case pres.FormatJSON:
 			pres.PrintJSON(res)
@@ -62,6 +66,8 @@ func init() {
 	branchCmd.Flags().StringVarP(&alias, "alias", "n", "", "Alias for the new VM")
 	branchCmd.Flags().BoolP("checkout", "c", false, "Switch to the new VM after creation")
 	branchCmd.Flags().IntVar(&branchCount, "count", 1, "Number of branches to create")
-	branchCmd.Flags().StringVar(&branchFormat, "format", "", "Output format (json)")
+	branchCmd.Flags().BoolVar(&branchJSON, "json", false, "Output as JSON")
+	branchCmd.Flags().StringVar(&branchFormat, "format", "", "Output format (json) [deprecated: use --json]")
+	_ = branchCmd.Flags().MarkDeprecated("format", "use --json instead")
 	branchCmd.Flags().BoolVar(&branchWait, "wait", false, "Wait until new VMs are running")
 }

cmd/commit.go

@@ -9,6 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+var commitJSON bool
 var commitFormat string
 
 // commitCmd is the parent command for commit operations.
@@ -42,7 +43,7 @@ var commitCreateCmd = &cobra.Command{
 	Long: `Save the current state of a VM as a commit.
 If no VM ID or alias is provided, commits the current HEAD VM.
 
-Use --format json for machine-readable output.`,
+Use --json for machine-readable output.`,
 	Args: cobra.MaximumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		target := ""
@@ -60,7 +61,10 @@ Use --format json for machine-readable output.`,
 			return err
 		}
 
-		format := pres.ParseFormat(false, commitFormat)
+		format, err := pres.ParseFormat(false, commitJSON, commitFormat)
+		if err != nil {
+			return err
+		}
 		switch format {
 		case pres.FormatJSON:
 			pres.PrintJSON(res)
@@ -78,6 +82,7 @@ Use --format json for machine-readable output.`,
 var (
 	commitListPublic bool
 	commitListQuiet  bool
+	commitListJSON bool
 	commitListFormat string
 )
 
@@ -89,7 +94,7 @@ var commitListCmd = &cobra.Command{
 Use -q/--quiet to output just commit IDs (one per line), useful for scripting:
   vers commit delete $(vers commit list -q)   # delete all commits
 
-Use --format json for machine-readable output.`,
+Use --json for machine-readable output.`,
 	Args: cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		apiCtx, cancel := context.WithTimeout(context.Background(), application.Timeouts.APIMedium)
@@ -102,7 +107,10 @@ Use --format json for machine-readable output.`,
 			return err
 		}
 
-		format := pres.ParseFormat(commitListQuiet, commitListFormat)
+		format, err := pres.ParseFormat(commitListQuiet, commitListJSON, commitListFormat)
+		if err != nil {
+			return err
+		}
 		switch format {
 		case pres.FormatQuiet:
 			ids := make([]string, len(res.Commits))
@@ -151,14 +159,15 @@ Examples:
 	},
 }
 
+var commitHistoryJSON bool
 var commitHistoryFormat string
 
 var commitHistoryCmd = &cobra.Command{
 	Use:   "history <commit-id>",
 	Short: "Show the parent commit chain",
 	Long: `Display the chain of parent commits leading up to a given commit.
 
-Use --format json for machine-readable output.`,
+Use --json for machine-readable output.`,
 	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		apiCtx, cancel := context.WithTimeout(context.Background(), application.Timeouts.APIMedium)
@@ -171,7 +180,10 @@ Use --format json for machine-readable output.`,
 			return err
 		}
 
-		format := pres.ParseFormat(false, commitHistoryFormat)
+		format, err := pres.ParseFormat(false, commitHistoryJSON, commitHistoryFormat)
+		if err != nil {
+			return err
+		}
 		switch format {
 		case pres.FormatJSON:
 			pres.PrintJSON(res.Parents)
@@ -227,16 +239,22 @@ var commitUnpublishCmd = &cobra.Command{
 func init() {
 	rootCmd.AddCommand(commitCmd)
 
-	commitCreateCmd.Flags().StringVar(&commitFormat, "format", "", "Output format (json)")
+	commitCreateCmd.Flags().BoolVar(&commitJSON, "json", false, "Output as JSON")
+	commitCreateCmd.Flags().StringVar(&commitFormat, "format", "", "Output format (json) [deprecated: use --json]")
+	_ = commitCreateCmd.Flags().MarkDeprecated("format", "use --json instead")
 	commitCmd.AddCommand(commitCreateCmd)
 
 	commitListCmd.Flags().BoolVar(&commitListPublic, "public", false, "List public commits instead of your own")
 	commitListCmd.Flags().BoolVarP(&commitListQuiet, "quiet", "q", false, "Only display commit IDs")
-	commitListCmd.Flags().StringVar(&commitListFormat, "format", "", "Output format (json)")
+	commitListCmd.Flags().BoolVar(&commitListJSON, "json", false, "Output as JSON")
+	commitListCmd.Flags().StringVar(&commitListFormat, "format", "", "Output format (json) [deprecated: use --json]")
+	_ = commitListCmd.Flags().MarkDeprecated("format", "use --json instead")
 	commitCmd.AddCommand(commitListCmd)
 	commitCmd.AddCommand(commitDeleteCmd)
 
-	commitHistoryCmd.Flags().StringVar(&commitHistoryFormat, "format", "", "Output format (json)")
+	commitHistoryCmd.Flags().BoolVar(&commitHistoryJSON, "json", false, "Output as JSON")
+	commitHistoryCmd.Flags().StringVar(&commitHistoryFormat, "format", "", "Output format (json) [deprecated: use --json]")
+	_ = commitHistoryCmd.Flags().MarkDeprecated("format", "use --json instead")
 	commitCmd.AddCommand(commitHistoryCmd)
 	commitCmd.AddCommand(commitPublishCmd)
 	commitCmd.AddCommand(commitUnpublishCmd)

cmd/deploy.go

@@ -15,6 +15,7 @@ var (
 	deployBuildCommand     string
 	deployRunCommand       string
 	deployWorkingDirectory string
+	deployJSON           bool
 	deployFormat           string
 	deployWait             bool
 )
@@ -38,7 +39,7 @@ Examples:
   vers deploy hdresearch/my-app --branch develop
   vers deploy hdresearch/my-app --name my-project --install "npm install" --build "npm run build" --run "npm start"
   vers deploy hdresearch/my-app --working-dir packages/web
-  vers deploy hdresearch/my-app --format json`,
+  vers deploy hdresearch/my-app --json`,
 	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		apiCtx, cancel := context.WithTimeout(context.Background(), application.Timeouts.APILong)
@@ -60,7 +61,10 @@ Examples:
 			return err
 		}
 
-		format := pres.ParseFormat(false, deployFormat)
+		format, err := pres.ParseFormat(false, deployJSON, deployFormat)
+		if err != nil {
+			return err
+		}
 		switch format {
 		case pres.FormatJSON:
 			pres.PrintJSON(view)
@@ -80,6 +84,8 @@ func init() {
 	deployCmd.Flags().StringVar(&deployBuildCommand, "build", "", "Build command (e.g. \"npm run build\")")
 	deployCmd.Flags().StringVar(&deployRunCommand, "run", "", "Run command (e.g. \"npm start\")")
 	deployCmd.Flags().StringVar(&deployWorkingDirectory, "working-dir", "", "Working directory relative to repo root")
-	deployCmd.Flags().StringVar(&deployFormat, "format", "", "Output format (json)")
+	deployCmd.Flags().BoolVar(&deployJSON, "json", false, "Output as JSON")
+	deployCmd.Flags().StringVar(&deployFormat, "format", "", "Output format (json) [deprecated: use --json]")
+	_ = deployCmd.Flags().MarkDeprecated("format", "use --json instead")
 	deployCmd.Flags().BoolVar(&deployWait, "wait", false, "Wait until the VM is running before returning")
 }

cmd/env.go

@@ -12,6 +12,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+var envJSON bool
 var envFormat string
 
 // envCmd represents the env command
@@ -43,7 +44,10 @@ These variables will be injected into newly created VMs at boot time.`,
 			return err
 		}
 
-		format := pres.ParseFormat(false, envFormat)
+		format, err := pres.ParseFormat(false, envJSON, envFormat)
+		if err != nil {
+			return err
+		}
 		switch format {
 		case pres.FormatJSON:
 			pres.PrintJSON(vars)
@@ -188,5 +192,7 @@ func init() {
 	envCmd.AddCommand(envDeleteCmd)
 
 	// Add flags
-	envListCmd.Flags().StringVar(&envFormat, "format", "", "Output format (json)")
+	envListCmd.Flags().BoolVar(&envJSON, "json", false, "Output as JSON")
+	envListCmd.Flags().StringVar(&envFormat, "format", "", "Output format (json) [deprecated: use --json]")
+	_ = envListCmd.Flags().MarkDeprecated("format", "use --json instead")
 }

cmd/info.go

@@ -10,6 +10,7 @@ import (
 
 var (
 	infoQuiet  bool
+	infoJSON bool
 	infoFormat string
 )
 
@@ -20,7 +21,7 @@ var infoCmd = &cobra.Command{
 grandparent VM), and timestamps. If no VM is specified, uses the current HEAD.
 
 Use -q/--quiet to output just the VM ID.
-Use --format json for machine-readable output.`,
+Use --json for machine-readable output.`,
 	Args: cobra.MaximumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		target := ""
@@ -36,7 +37,10 @@ Use --format json for machine-readable output.`,
 			return err
 		}
 
-		format := pres.ParseFormat(infoQuiet, infoFormat)
+		format, err := pres.ParseFormat(infoQuiet, infoJSON, infoFormat)
+		if err != nil {
+			return err
+		}
 		switch format {
 		case pres.FormatQuiet:
 			pres.PrintQuiet([]string{res.Metadata.VmID})
@@ -52,5 +56,7 @@ Use --format json for machine-readable output.`,
 func init() {
 	rootCmd.AddCommand(infoCmd)
 	infoCmd.Flags().BoolVarP(&infoQuiet, "quiet", "q", false, "Only display VM ID")
-	infoCmd.Flags().StringVar(&infoFormat, "format", "", "Output format (json)")
+	infoCmd.Flags().BoolVar(&infoJSON, "json", false, "Output as JSON")
+	infoCmd.Flags().StringVar(&infoFormat, "format", "", "Output format (json) [deprecated: use --json]")
+	_ = infoCmd.Flags().MarkDeprecated("format", "use --json instead")
 }