Implement greenfield Akua CLI public MVP

[robinbraemer]

Context

This is the implementation follow-up for #12 after the captain accepted the greenfield Akua CLI direction.

The old akua-dev/cli codebase is CNAP-era Go code. Do not treat this as a module-path rename. Build the first akua CLI as a Bun/TypeScript, codegen-heavy CLI in this separate open-source repo.

Decisions Already Made

• Binary: akua.
• Runtime: Bun + TypeScript.
• Packaging goal: self-contained CLI artifact produced by Bun.
• Repository: akua-dev/cli.
• First release: public API commands only.
• Default output: adaptive.
  • Agent/automation mode when well-known coding-agent environment variables, non-TTY, or CI-style signals are present.
  • Human-friendly output otherwise.
• Legacy compatibility: no support required for old cnap or github.com/cnap-tech/cli.
• Live spec source: https://api.akua.dev/v1/openapi.json.
• Include a mise task to fetch the latest production OpenAPI spec for codegen.

Implementation Plan

Phase 1: Scaffold And Spec Fetch

• Replace or quarantine the old Go CLI entrypoint so the repo builds the new akua CLI.
• Add Bun/TypeScript project scaffolding.
• Add a mise task such as spec:fetch that downloads https://api.akua.dev/v1/openapi.json into a committed or generated spec location.
• Add a repeatable codegen task for API/client/command artifacts.
• Add CI checks for spec/codegen drift.

Phase 2: CLI Runtime Contract

• Implement output mode detection for known coding-agent environment variables, non-TTY, and CI signals.
• Implement human, JSON, and compact agent-friendly output modes.
• Define stdout/stderr rules.
• Define documented exit codes.
• Implement structured errors preserving API request IDs, status/code, validation paths, retry hints, and next-step commands.
• Implement prompt refusal rules for agent/CI/non-TTY modes.

Phase 3: Public Command MVP

• Generate or scaffold command definitions from the public OpenAPI spec plus a curated CLI overlay.
• Implement akua auth.
• Implement workspace/context commands.
• Implement read-only list/get commands for the highest-value public resources.
• Implement operation status/watch commands if the public API exposes operation resources.
• Add golden tests for human/default, JSON, quiet, and agent-mode output.

Phase 4: Mutations And Safety

• Add selected public create/update/delete commands.
• Enforce --yes/--force for destructive noninteractive actions.
• Add idempotency-key handling where the API supports it.
• Add --dry-run, --wait, and streaming/NDJSON behavior where relevant.
• Add safety tests for destructive commands and automation modes.

Phase 5: Release

• Produce a self-contained CLI artifact.
• Add install documentation for akua.
• Add smoke tests for clean install and akua --help.
• Update docs only after the new install path works from a clean environment.

Acceptance Criteria

• akua --help works from the self-contained artifact.
• mise run spec:fetch fetches https://api.akua.dev/v1/openapi.json.
• Codegen is deterministic and checked in CI.
• Agent/automation output is compact, structured, and stable.
• Human output is readable by default.
• Structured errors include actionable next steps and request IDs when available.
• First release exposes public API commands only.
• No legacy cnap compatibility is required or implemented unless a later captain decision changes that.

Related

• Planning/spec anchor: Plan greenfield Akua CLI architecture and AXI UX #12
• Prior scout report: data/akua-cli-greenfield-plan-scout/report.md in the Akua secondmate home.