Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(cli): keep manifest CLI-special — record the decision (#4464)

Joey4732caddf20b
diff --git a/packages/cli/cli/index.mjs b/packages/cli/cli/index.mjs
index 48b979c087..13a9827592 100644
--- a/packages/cli/cli/index.mjs
+++ b/packages/cli/cli/index.mjs
@@ -340,6 +340,9 @@ export async function createProgram() {
// agents can discover every command, argument, flag, and response type without
// scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare
// `xds --json` embeds the same payload under data.manifest for convenience.
+ // Intentionally CLI-special — no `api/manifest`. It introspects the live
+ // Commander `program`, so extracting it to `api/` would create the `api → cli`
+ // cycle from #4302. `buildManifest(program)` lives in lib/; see its header.
program
.command('manifest')
.description('Print the full CLI capability manifest (use with --json)')
diff --git a/packages/cli/lib/manifest.mjs b/packages/cli/lib/manifest.mjs
index 36873c830f..41ddcead35 100644
--- a/packages/cli/lib/manifest.mjs
+++ b/packages/cli/lib/manifest.mjs
@@ -20,6 +20,15 @@
* appears in the manifest and every JSON-supported command has a response-type
* entry, so adding a command without describing it fails CI.
*
+ * DESIGN DECISION — manifest stays CLI-special; there is intentionally NO
+ * `api/manifest`. It describes the CLI's own Commander tree, so it takes the live
+ * `program` as a parameter and lives in `lib/` (shared infra the CLI can import
+ * without a cycle). An `api/manifest` entry would have to import the program from
+ * `cli/index.mjs` — the `api → cli` cycle that bit #4302 — or force programmatic
+ * callers to construct a program themselves. So `buildManifest(program)` is the
+ * intended shape, and the bare `astryx --json` / `astryx manifest --json` handlers
+ * are its only consumers. Do not "extract" this to `api/` in the reorg.
+ *
* @input a configured Commander `program` + the JSON_SUPPORTED allowlist
* @output a `{ name, version, globalOptions, commands, responseTypes }` object
* @position consumed by the bare `astryx --json` action and the `manifest` command