feat(cli): scaffold greenfield Akua CLI prototype#14
Merged
Conversation
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
1 participant
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.
Intent
Start the greenfield Akua Cloud CLI spec/prototype work in akua-dev/cli. Replace the old CNAP-era Go build surface with a Bun/TypeScript scaffold for the canonical akua binary, with no cnap or github.com/cnap-tech/cli compatibility requirement. Include a polished architecture/spec, a mise task to fetch the production OpenAPI spec from https://api.akua.dev/v1/openapi.json, an operationId-driven public command registry generator, adaptive AXI-style output mode detection and rendering for coding agents versus humans, structured errors and deterministic exit codes, focused tests, and a self-contained Bun binary packaging path. Keep API execution intentionally narrow/stubbed for this first PR, expose public API commands only, avoid live infrastructure mutations beyond read-only spec fetch, open a PR but do not merge.
What Changed
akuaCLI scaffold, including runtime mode detection, adaptive rendering, structured errors, deterministic exit codes, and generated public command routing.openapi/and generated command metadata undersrc/generated/.Risk Assessment
Testing
Inspected the change scope, ran the Bun test suite and registry generation check, fetched the production OpenAPI spec read-only into the evidence directory and confirmed it matches the checked-in snapshot, then exercised the CLI as an end user in human, agent, JSON, stub-error, and compiled-binary modes; all checks passed and no actionable issues were found.
Evidence: CLI human commands transcript
Evidence: CLI agent commands transcript
Evidence: CLI JSON filter transcript
Evidence: CLI stubbed command error transcript
Evidence: Compiled binary version transcript
Evidence: Live OpenAPI fetch summary
{"url":"https://api.akua.dev/v1/openapi.json","openapi":"3.1.0","path_count":215,"snapshot_matches_live":true}Evidence: Fetched live OpenAPI document
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 2 issues found → auto-fixed (3) ✅
src/runtime/mode.ts:78- Invalid or missing--outputvalues are silently ignored, then stripped before routing, so commands likeakua --output yaml --versionexit 0 with non-requested output instead of a usage error. This breaks the deterministic local-argument contract for automation that explicitly requests an output mode.src/bin/akua.ts:59-commandsfilter flags are not validated for required value/type:akua commands --operation-idlists the default first page, andakua commands --limit banana --jsonexits 0 with the default limit. These should fail as usage errors so scripts do not treat malformed filters as successful filtered queries.🔧 Fix: Validate CLI output and command filters
1 warning still open:
src/bin/akua.ts:134-commandsignores unexpected positional arguments, so malformed invocations likeakua commands workspaces --jsonorakua commands --limit 5 extra --jsonstill exit 0 with the default/listed results instead of failing as usage errors. Reject non-flag tokens after values consumed by known filters so typos do not look like successful filtered queries.🔧 Fix: Reject unexpected commands arguments
1 warning still open:
src/runtime/mode.ts:110-parseOutputModestill accepts the undocumented valuetoon, soakua --output toon --versionandAKUA_OUTPUT=toonsucceed even though help/errors advertise onlyhuman|agent|json|quiet. Remove the alias or make it an explicitly documented/tested mode; otherwise invalid output validation remains incomplete.🔧 Fix: Reject undocumented output alias
✅ Re-checked - no issues remain.
✅ **Test** - passed
✅ No issues found.
git diff --stat e4e6472620226d1a10947fdefeaef9395322381e...0e84bc8822353d7ad04b2cefc07a9a87c88989b2bun testbun run generate:checkbun -e 'const out="/var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KX302NYK1R9AJ7K9G8NRW6NF/openapi-live.json"; const mod=await import("./scripts/fetch-openapi.ts"); const url=mod.resolveSpecUrl(undefined); await mod.fetchOpenApi(url,out); const spec=await Bun.file(out).json(); console.log(JSON.stringify({url:url.href, openapi:spec.openapi, path_count:Object.keys(spec.paths).length}, null, 2));'cmp -s openapi/public.json /var/folders/1y/cjgf53nj31n_dxsspqnjfjvc0000gn/T/no-mistakes-evidence/01KX302NYK1R9AJ7K9G8NRW6NF/openapi-live.jsonbun run build:binaryenv -u AKUA_OUTPUT bun src/bin/akua.ts --output human commands --resource workspaces --limit 3env -u AKUA_OUTPUT CODEX_CLI=1 bun src/bin/akua.ts commands --limit 2env -u AKUA_OUTPUT bun src/bin/akua.ts commands --operation-id workspaces.list --jsonenv -u AKUA_OUTPUT bun src/bin/akua.ts workspaces list --json./dist/akua --output json --versionrm -f dist/akua && git status --short✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.