Skip to content

feat: agent-native CLI fixes (F1, F7, F8)#190

Merged
AlephNotation merged 5 commits intomainfrom
feat/agent-native-cli-fixes
May 8, 2026
Merged

feat: agent-native CLI fixes (F1, F7, F8)#190
AlephNotation merged 5 commits intomainfrom
feat/agent-native-cli-fixes

Conversation

@AlephNotation
Copy link
Copy Markdown
Contributor

@AlephNotation AlephNotation commented May 8, 2026

Three top-priority agent-native-CLI fixes, sourced from Trevin Chow's 10 Principles for Agent-Native CLIs and Cloudflare's Wrangler vocabulary rules. Implemented by three Opus 4.7 subagents in parallel git worktrees, then merged onto this integration branch.

What changed

--format json--json (canonical Cloudflare/Wrangler vocabulary)

19 cobra --format string flags now have a sibling --json BoolVar. The old --format flag is preserved as a hidden, deprecated alias for backwards compat.

  • New presenters.ParseFormat(quiet, json, format) centralizes precedence: quiet > json > format > default.
  • Invalid --format values now error with an enumerated message instead of silently falling through:
    Error: --format must be "json" (got: "yaml"). Note: --format is deprecated, use --json instead
    
  • vers status --format json still works but emits Flag --format has been deprecated, use --json instead to stderr (cobra MarkDeprecated).

vers infovers get (verb consistency)

repo get and tag get already use the canonical verb. The top-level vers info was the inconsistent outlier. Renamed cmd/info.gocmd/get.go via git mv; info is preserved as a cobra alias so existing scripts and integration tests keep working.

Pagination + truncation hints on every list command

Added --limit N (default 50; 0 = unbounded) and --offset N to status, commit list, repo list, repo tag list, tag list, env list, and alias (no-arg list mode).

JSON output shapes:

  • Not truncated — bare items array (backwards-compatible).
  • Truncated — envelope with hint:
    {
      "items": [...],
      "total": 11, "limit": 3, "offset": 0,
      "truncated": true, "next_offset": 3,
      "hint": "showing 3 of 11 — use --limit=N (0 for all) or --offset=3 for the next page"
    }

Text/quiet modes print the truncation hint to stderr so stdout stays clean for piping. New internal/presenters/pagination.go exposes PageInfo, ApplyPaging, PrintListJSON, PrintTruncationHint. Unit tested with 10 sub-cases.

Caveats and follow-ups

  1. Pagination is client-side. vers-sdk-go v0.1.0-alpha.32 does not yet expose Limit/Offset query params (the response shapes include them). Inline // TODO: comments at every call site mark the migration path.
  2. env list JSON shape changes only when truncated: {items: [{key, value}, ...]} to preserve order across pages. Bare object map is preserved when not truncated. MCP/agent consumers depending strictly on the map form will see the new shape only on the truncated branch.
  3. Pre-existing integration tests in test/single-action/ fail on both this branch and main (verified via stash). Failures are unrelated to this PR — TestCommitAndList rejects vers commit <vm-id> because cobra treats the positional VM-ID as an unknown subcommand. Worth a separate finding/fix.

Validation

  • make build — clean
  • go vet ./... — clean
  • go test ./internal/... ./cmd/... — all packages pass (including new format_test.go and pagination_test.go cases)
  • Live smoke tests against an authenticated environment confirm --json, --limit/--offset, deprecation warnings, and the info alias all behave correctly.

Addresses F1 from AGENT_NATIVE_AUDIT.md.
Addresses F8 from AGENT_NATIVE_AUDIT.md. Aligns with the canonical
get/list/create/update/delete vocabulary already used by 'repo get'
and 'tag get'. The 'info' alias is preserved for backwards compatibility.
Addresses F7 from AGENT_NATIVE_AUDIT.md.

Adds --limit (default 50; 0=unbounded) and --offset to every list-style
command on top of the F1 --json flag layout:

  vers status, vers alias (no arg), vers commit list, vers repo list,
  vers repo tag list, vers tag list, vers env list

Output shapes:
- JSON, not truncated: bare items array (backwards-compat).
- JSON, truncated: envelope with items, total, limit, offset, truncated,
  next_offset, and hint.
- Text/quiet: data on stdout, single-line truncation hint on stderr.

env list special-cases the historical map shape ({KEY: VALUE, ...}) when
not truncated and switches to an ordered envelope ({items: [{key, value}]})
when truncated, since Go map iteration is unstable.

Pagination is currently client-side because the SDK does not yet expose
typed Limit/Offset query params. Inline TODO comments at every call site
mark where to plumb the flags through once the SDK supports them.
@AlephNotation AlephNotation force-pushed the feat/agent-native-cli-fixes branch from a876215 to 858a439 Compare May 8, 2026 01:44
@AlephNotation AlephNotation merged commit 0f49490 into main May 8, 2026
11 of 12 checks passed
@AlephNotation AlephNotation deleted the feat/agent-native-cli-fixes branch May 8, 2026 03:33
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