@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/surfaces/cli/commands/wipe.mjs

@@ -3,22 +3,56 @@ import { emitSuccess } from "../output.mjs";
 import { confirmDestructive } from "./confirm.mjs";
 import { Effect } from "effect";
 //#region src/surfaces/cli/commands/wipe.ts
+/** Human-readable preview of what a real wipe would delete. Mirrors the
+*  orchestrator's teardown order (containers → networks/volumes →
+*  state.json → runtime tree) so the operator reads the plan in the same
+*  sequence the wipe executes. */
+const dryRunLines = (targets) => {
+	const lines = [`[dry-run] would wipe ${targets.app}/${targets.stack}:`];
+	if (targets.containers.length > 0) {
+		lines.push(`  containers (${targets.containers.length}):`);
+		for (const name of targets.containers) lines.push(`    - ${name}`);
+	} else lines.push("  containers: (none running/created)");
+	lines.push(`  networks: all managed (label devstack.app=${targets.networkLabelMatch.app},devstack.stack=${targets.networkLabelMatch.stack})`);
+	lines.push(`  volumes: all managed (label devstack.app=${targets.volumeLabelMatch.app},devstack.stack=${targets.volumeLabelMatch.stack})`);
+	lines.push(`  state file: ${targets.stateFile}`);
+	if (targets.onDiskPaths.length > 0) {
+		lines.push(`  on-disk (${targets.onDiskPaths.length}):`);
+		for (const path of targets.onDiskPaths) lines.push(`    - ${path}`);
+	} else lines.push(`  on-disk: (stack root ${targets.stackRoot} has no removable state)`);
+	if (targets.preserved.length > 0) lines.push(`  preserved: ${targets.preserved.join(", ")}`);
+	return lines;
+};
 const runWipe = (deps, ctx) => Effect.gen(function* () {
 	const started = Date.now();
 	yield* confirmDestructive(deps.confirm, ctx, {
 		verb: "wipe",
 		prompt: "Wipe all devstack state for the selected stack?"
 	});
-	if (!ctx.flags.dryRun) yield* deps.wipe().pipe(Effect.catch((cause) => isCliError(cause) ? Effect.fail(cause) : Effect.fail(new CliInternalError({
+	if (ctx.flags.dryRun) {
+		const targets = deps.plan === void 0 ? null : yield* deps.plan().pipe(Effect.catch(() => Effect.succeed(null)));
+		yield* emitSuccess(ctx.io, ctx.flags.outputMode, {
+			command: "wipe",
+			elapsedMs: Date.now() - started,
+			dryRun: true,
+			data: {
+				dryRun: true,
+				...targets === null ? {} : { targets }
+			},
+			humanLines: targets === null ? ["[dry-run] would wipe selected stack state"] : dryRunLines(targets)
+		});
+		return { exitCode: 0 };
+	}
+	yield* deps.wipe().pipe(Effect.catch((cause) => isCliError(cause) ? Effect.fail(cause) : Effect.fail(new CliInternalError({
 		message: "wipe failed",
 		cause
 	}))));
 	yield* emitSuccess(ctx.io, ctx.flags.outputMode, {
 		command: "wipe",
 		elapsedMs: Date.now() - started,
-		dryRun: ctx.flags.dryRun,
-		data: { dryRun: ctx.flags.dryRun },
-		humanLines: ctx.flags.dryRun ? ["[dry-run] would wipe selected stack state"] : ["stack state wiped"]
+		dryRun: false,
+		data: { dryRun: false },
+		humanLines: ["stack state wiped"]
 	});
 	return { exitCode: 0 };
 }).pipe(Effect.withSpan("cli.wipe"));

package/dist/surfaces/cli/commands/wipe.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"wipe.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/wipe.ts"],"sourcesContent":["// CLI verb: `devstack wipe` — destroy all state for a stack.\n//\n// Architecture (distilled/20-cli.md § Subcommands § Teardown):\n//   \"wipe — destroy all state for a stack.\"\n//\n// `wipe` is the recovery flow `apply` points users at on\n// `SeedManifestMismatchError`. It is tier-2 destructive (requires\n// `--yes` or an interactive TTY confirmation) and refuses to run while\n// a supervisor is live for the target stack (writes to disk while\n// a peer is acquiring a container would race).\n//\n// Surface-equality: `wipe` publishes `wipe.requested`; the L3 snapshot\n// orchestrator consumes (it owns the `wipe.ts` body that rmdir's the\n// stack root + container labels).\n\nimport { Effect } from 'effect';\n\nimport { type CliError, CliInternalError, isCliError } from '../errors.ts';\nimport { emitSuccess } from '../output.ts';\nimport { confirmDestructive, type ConfirmPrompt } from './confirm.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\nexport interface WipeDeps {\n\treadonly wipe: () => Effect.Effect<void, unknown>;\n\treadonly confirm: ConfirmPrompt;\n}\n\nexport const runWipe = (\n\tdeps: WipeDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tyield* confirmDestructive(deps.confirm, ctx, {\n\t\t\tverb: 'wipe',\n\t\t\tprompt: 'Wipe all devstack state for the selected stack?',\n\t\t});\n\t\tif (!ctx.flags.dryRun) {\n\t\t\tyield* deps.wipe().pipe(\n\t\t\t\tEffect.catch((cause: unknown) =>\n\t\t\t\t\tisCliError(cause)\n\t\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t\t: Effect.fail(\n\t\t\t\t\t\t\t\tnew CliInternalError({\n\t\t\t\t\t\t\t\t\tmessage: 'wipe failed',\n\t\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'wipe',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdryRun: ctx.flags.dryRun,\n\t\t\tdata: {\n\t\t\t\tdryRun: ctx.flags.dryRun,\n\t\t\t},\n\t\t\thumanLines: ctx.flags.dryRun\n\t\t\t\t? ['[dry-run] would wipe selected stack state']\n\t\t\t\t: ['stack state wiped'],\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t}).pipe(Effect.withSpan('cli.wipe'));\n"],"mappings":";;;;;AA2BA,MAAa,WACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,KAAK,KAAK;AAC1B,QAAO,mBAAmB,KAAK,SAAS,KAAK;EAC5C,MAAM;EACN,QAAQ;EACR,CAAC;AACF,KAAI,CAAC,IAAI,MAAM,OACd,QAAO,KAAK,MAAM,CAAC,KAClB,OAAO,OAAO,UACb,WAAW,MAAM,GACd,OAAO,KAAK,MAAM,GAClB,OAAO,KACP,IAAI,iBAAiB;EACpB,SAAS;EACT;EACA,CAAC,CACF,CACH,CACD;AAEF,QAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;EAChD,SAAS;EACT,WAAW,KAAK,KAAK,GAAG;EACxB,QAAQ,IAAI,MAAM;EAClB,MAAM,EACL,QAAQ,IAAI,MAAM,QAClB;EACD,YAAY,IAAI,MAAM,SACnB,CAAC,4CAA4C,GAC7C,CAAC,oBAAoB;EACxB,CAAC;AACF,QAAO,EAAE,UAAU,GAAG;EACrB,CAAC,KAAK,OAAO,SAAS,WAAW,CAAC"}
+{"version":3,"file":"wipe.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/wipe.ts"],"sourcesContent":["// CLI verb: `devstack wipe` — destroy all state for a stack.\n//\n// Architecture (distilled/20-cli.md § Subcommands § Teardown):\n//   \"wipe — destroy all state for a stack.\"\n//\n// `wipe` is the recovery flow `apply` points users at when stale\n// on-disk state needs a clean reset. It is tier-2 destructive (requires\n// `--yes` or an interactive TTY confirmation) and refuses to run while\n// a supervisor is live for the target stack (writes to disk while\n// a peer is acquiring a container would race).\n//\n// Surface-equality: `wipe` publishes `wipe.requested`; the L3 snapshot\n// orchestrator consumes (it owns the `wipe.ts` body that rmdir's the\n// stack root + container labels).\n\nimport { Effect } from 'effect';\n\nimport type { WipeTargets } from '../../../orchestrators/snapshot/index.ts';\nimport { type CliError, CliInternalError, isCliError } from '../errors.ts';\nimport { emitSuccess } from '../output.ts';\nimport { confirmDestructive, type ConfirmPrompt } from './confirm.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\nexport type { WipeTargets } from '../../../orchestrators/snapshot/index.ts';\n\nexport interface WipeDeps {\n\treadonly wipe: () => Effect.Effect<void, unknown>;\n\t/** Read-only enumeration of the concrete targets a real wipe would\n\t *  remove (containers, network/volume label scope, state file, the\n\t *  on-disk stack tree). Drives `--dry-run`. Optional so a deps\n\t *  builder that cannot enumerate (or a test fixture) still works —\n\t *  the dry-run then falls back to a generic preview line. */\n\treadonly plan?: () => Effect.Effect<WipeTargets, unknown>;\n\treadonly confirm: ConfirmPrompt;\n}\n\n/** Human-readable preview of what a real wipe would delete. Mirrors the\n *  orchestrator's teardown order (containers → networks/volumes →\n *  state.json → runtime tree) so the operator reads the plan in the same\n *  sequence the wipe executes. */\nconst dryRunLines = (targets: WipeTargets): ReadonlyArray<string> => {\n\tconst lines: Array<string> = [`[dry-run] would wipe ${targets.app}/${targets.stack}:`];\n\tif (targets.containers.length > 0) {\n\t\tlines.push(`  containers (${targets.containers.length}):`);\n\t\tfor (const name of targets.containers) lines.push(`    - ${name}`);\n\t} else {\n\t\tlines.push('  containers: (none running/created)');\n\t}\n\tlines.push(\n\t\t`  networks: all managed (label devstack.app=${targets.networkLabelMatch.app},devstack.stack=${targets.networkLabelMatch.stack})`,\n\t);\n\tlines.push(\n\t\t`  volumes: all managed (label devstack.app=${targets.volumeLabelMatch.app},devstack.stack=${targets.volumeLabelMatch.stack})`,\n\t);\n\tlines.push(`  state file: ${targets.stateFile}`);\n\tif (targets.onDiskPaths.length > 0) {\n\t\tlines.push(`  on-disk (${targets.onDiskPaths.length}):`);\n\t\tfor (const path of targets.onDiskPaths) lines.push(`    - ${path}`);\n\t} else {\n\t\tlines.push(`  on-disk: (stack root ${targets.stackRoot} has no removable state)`);\n\t}\n\tif (targets.preserved.length > 0) {\n\t\tlines.push(`  preserved: ${targets.preserved.join(', ')}`);\n\t}\n\treturn lines;\n};\n\nexport const runWipe = (\n\tdeps: WipeDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tyield* confirmDestructive(deps.confirm, ctx, {\n\t\t\tverb: 'wipe',\n\t\t\tprompt: 'Wipe all devstack state for the selected stack?',\n\t\t});\n\n\t\tif (ctx.flags.dryRun) {\n\t\t\t// Enumerate (read-only) so the preview lists the concrete\n\t\t\t// containers / networks / volumes / on-disk state a real wipe\n\t\t\t// would remove. A plan failure is non-fatal for a dry-run — the\n\t\t\t// worst case is a less-detailed preview — so it degrades to the\n\t\t\t// generic line rather than failing the command.\n\t\t\tconst targets =\n\t\t\t\tdeps.plan === undefined\n\t\t\t\t\t? null\n\t\t\t\t\t: yield* deps.plan().pipe(Effect.catch(() => Effect.succeed(null)));\n\t\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\t\tcommand: 'wipe',\n\t\t\t\telapsedMs: Date.now() - started,\n\t\t\t\tdryRun: true,\n\t\t\t\tdata: {\n\t\t\t\t\tdryRun: true,\n\t\t\t\t\t...(targets === null ? {} : { targets }),\n\t\t\t\t},\n\t\t\t\thumanLines:\n\t\t\t\t\ttargets === null ? ['[dry-run] would wipe selected stack state'] : dryRunLines(targets),\n\t\t\t});\n\t\t\treturn { exitCode: 0 } as CommandResult;\n\t\t}\n\n\t\tyield* deps.wipe().pipe(\n\t\t\tEffect.catch((cause: unknown) =>\n\t\t\t\tisCliError(cause)\n\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t: Effect.fail(\n\t\t\t\t\t\t\tnew CliInternalError({\n\t\t\t\t\t\t\t\tmessage: 'wipe failed',\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'wipe',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdryRun: false,\n\t\t\tdata: {\n\t\t\t\tdryRun: false,\n\t\t\t},\n\t\t\thumanLines: ['stack state wiped'],\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t}).pipe(Effect.withSpan('cli.wipe'));\n"],"mappings":";;;;;;;;;AAwCA,MAAM,eAAe,YAAgD;CACpE,MAAM,QAAuB,CAAC,wBAAwB,QAAQ,IAAI,GAAG,QAAQ,MAAM,GAAG;AACtF,KAAI,QAAQ,WAAW,SAAS,GAAG;AAClC,QAAM,KAAK,iBAAiB,QAAQ,WAAW,OAAO,IAAI;AAC1D,OAAK,MAAM,QAAQ,QAAQ,WAAY,OAAM,KAAK,SAAS,OAAO;OAElE,OAAM,KAAK,uCAAuC;AAEnD,OAAM,KACL,+CAA+C,QAAQ,kBAAkB,IAAI,kBAAkB,QAAQ,kBAAkB,MAAM,GAC/H;AACD,OAAM,KACL,8CAA8C,QAAQ,iBAAiB,IAAI,kBAAkB,QAAQ,iBAAiB,MAAM,GAC5H;AACD,OAAM,KAAK,iBAAiB,QAAQ,YAAY;AAChD,KAAI,QAAQ,YAAY,SAAS,GAAG;AACnC,QAAM,KAAK,cAAc,QAAQ,YAAY,OAAO,IAAI;AACxD,OAAK,MAAM,QAAQ,QAAQ,YAAa,OAAM,KAAK,SAAS,OAAO;OAEnE,OAAM,KAAK,0BAA0B,QAAQ,UAAU,0BAA0B;AAElF,KAAI,QAAQ,UAAU,SAAS,EAC9B,OAAM,KAAK,gBAAgB,QAAQ,UAAU,KAAK,KAAK,GAAG;AAE3D,QAAO;;AAGR,MAAa,WACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,KAAK,KAAK;AAC1B,QAAO,mBAAmB,KAAK,SAAS,KAAK;EAC5C,MAAM;EACN,QAAQ;EACR,CAAC;AAEF,KAAI,IAAI,MAAM,QAAQ;EAMrB,MAAM,UACL,KAAK,SAAS,KAAA,IACX,OACA,OAAO,KAAK,MAAM,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CAAC;AACrE,SAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;GAChD,SAAS;GACT,WAAW,KAAK,KAAK,GAAG;GACxB,QAAQ;GACR,MAAM;IACL,QAAQ;IACR,GAAI,YAAY,OAAO,EAAE,GAAG,EAAE,SAAS;IACvC;GACD,YACC,YAAY,OAAO,CAAC,4CAA4C,GAAG,YAAY,QAAQ;GACxF,CAAC;AACF,SAAO,EAAE,UAAU,GAAG;;AAGvB,QAAO,KAAK,MAAM,CAAC,KAClB,OAAO,OAAO,UACb,WAAW,MAAM,GACd,OAAO,KAAK,MAAM,GAClB,OAAO,KACP,IAAI,iBAAiB;EACpB,SAAS;EACT;EACA,CAAC,CACF,CACH,CACD;AACD,QAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;EAChD,SAAS;EACT,WAAW,KAAK,KAAK,GAAG;EACxB,QAAQ;EACR,MAAM,EACL,QAAQ,OACR;EACD,YAAY,CAAC,oBAAoB;EACjC,CAAC;AACF,QAAO,EAAE,UAAU,GAAG;EACrB,CAAC,KAAK,OAAO,SAAS,WAAW,CAAC"}

package/dist/surfaces/cli/errors.mjs

@@ -96,7 +96,7 @@ const hintFor = (error) => {
 		case "CliConfirmDeclinedError":
 		case "CliSupervisorLiveError":
 		case "CliNoSupervisorError": return error.hint;
-		case "CliConfigNotFoundError":
+		case "CliConfigNotFoundError": return "config file not found; run `devstack init` or pass `--config <path>`";
 		case "CliConfigInvalidError":
 		case "CliSnapshotNotFoundError":
 		case "CliInternalError":

package/dist/surfaces/cli/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":["XC"],"sources":["../../../src/surfaces/cli/errors.ts"],"sourcesContent":["// CLI surface — typed errors carried up to the top-level renderer.\n//\n// Architecture (distilled/20-cli.md § Edge cases) enumerates the\n// surface's failure modes. Each one MUST resolve to a stable sysexit\n// code; the error tag here carries that mapping so the dispatcher\n// doesn't sprinkle exit codes through every command.\n//\n// Why tagged errors and not plain `Effect.fail(string)`?\n//   - `catchTag` in commands can pick out the precise tag without\n//     stringly matching.\n//   - The cascade formatter (substrate/runtime/observability/\n//     cascade-formatter.ts) renders these natively via their `_tag`.\n//   - The `schema --json` command enumerates the tag table.\n\nimport { Data } from 'effect';\n\nimport { type ExitCode, ExitCode as XC } from './sysexits.ts';\n\n// -----------------------------------------------------------------------------\n// Tagged errors\n// -----------------------------------------------------------------------------\n\n/** Argv parsing produced an error — unknown subcommand, malformed\n *  flag value, missing required positional. */\nexport class CliUsageError extends Data.TaggedError('CliUsageError')<{\n\treadonly message: string;\n\treadonly hint?: string;\n}> {}\n\n/** The user's `devstack.config.ts` could not be located (path probe\n *  exhausted) or could not be imported. */\nexport class CliConfigNotFoundError extends Data.TaggedError('CliConfigNotFoundError')<{\n\treadonly message: string;\n\treadonly searchedPaths?: ReadonlyArray<string>;\n}> {}\n\n/** The config imported successfully but its default export is not a\n *  `Stack` value (failed brand check, missing required field). */\nexport class CliConfigInvalidError extends Data.TaggedError('CliConfigInvalidError')<{\n\treadonly message: string;\n\treadonly cause?: unknown;\n}> {}\n\n/** A required service (Docker daemon, network) is unavailable. */\nexport class CliUnavailableError extends Data.TaggedError('CliUnavailableError')<{\n\treadonly message: string;\n\treadonly service: string;\n\treadonly hint?: string;\n}> {}\n\n/** Snapshot name/id not found. Carries the reference the caller\n *  used so the failure renderer can echo it back. */\nexport class CliSnapshotNotFoundError extends Data.TaggedError('CliSnapshotNotFoundError')<{\n\treadonly snapshotRef: string;\n}> {}\n\nexport class CliSnapshotAmbiguousError extends Data.TaggedError('CliSnapshotAmbiguousError')<{\n\treadonly snapshotRef: string;\n\treadonly matches: ReadonlyArray<string>;\n}> {}\n\n/** Destructive verb refused because `--yes` was absent and prompting\n *  was forbidden (non-TTY stdin or `--no-input`). */\nexport class CliConfirmRequiredError extends Data.TaggedError('CliConfirmRequiredError')<{\n\treadonly verb: string;\n\treadonly hint?: string;\n}> {}\n\n/** Destructive verb was prompted interactively and the user declined. */\nexport class CliConfirmDeclinedError extends Data.TaggedError('CliConfirmDeclinedError')<{\n\treadonly verb: string;\n\treadonly hint?: string;\n}> {}\n\n/** Engine reports a live supervisor for the target stack; the verb\n *  refused to mutate shared state. */\nexport class CliSupervisorLiveError extends Data.TaggedError('CliSupervisorLiveError')<{\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hint?: string;\n}> {}\n\n/** The verb requires a live supervisor (a stack must be `up`) but\n *  none is running for `(app, stack)`. Distinguished from\n *  `CliSupervisorLiveError` (the inverse case where the verb refused\n *  because one IS live). */\nexport class CliNoSupervisorError extends Data.TaggedError('CliNoSupervisorError')<{\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hint?: string;\n}> {}\n\n/** Internal/unexpected failure. Wraps an arbitrary cause; the cascade\n *  formatter renders the inner. */\nexport class CliInternalError extends Data.TaggedError('CliInternalError')<{\n\treadonly message: string;\n\treadonly cause?: unknown;\n}> {}\n\n/** Sentinel: subcommand already pretty-rendered its failure. The\n *  top-level renderer recognizes this tag and skips re-rendering, but\n *  still propagates `exitCode` to the OS exit code.\n *\n *  Architecture § Learnings: \"Already-reported sentinel pattern\" — the\n *  marker traverses the cause structure used by the Effect runtime, so\n *  the top-level `Effect.catchAll` sees it. */\nexport class CliAlreadyReportedError extends Data.TaggedError('CliAlreadyReportedError')<{\n\treadonly exitCode: ExitCode;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Union + sysexit projection\n// -----------------------------------------------------------------------------\n\nexport type CliError =\n\t| CliUsageError\n\t| CliConfigNotFoundError\n\t| CliConfigInvalidError\n\t| CliUnavailableError\n\t| CliSnapshotNotFoundError\n\t| CliSnapshotAmbiguousError\n\t| CliConfirmRequiredError\n\t| CliConfirmDeclinedError\n\t| CliSupervisorLiveError\n\t| CliNoSupervisorError\n\t| CliInternalError\n\t| CliAlreadyReportedError;\n\nexport const isCliError = (value: unknown): value is CliError => {\n\tif (typeof value !== 'object' || value === null) return false;\n\tconst tag = (value as { readonly _tag?: unknown })._tag;\n\tswitch (tag) {\n\t\tcase 'CliUsageError':\n\t\tcase 'CliConfigNotFoundError':\n\t\tcase 'CliConfigInvalidError':\n\t\tcase 'CliUnavailableError':\n\t\tcase 'CliSnapshotNotFoundError':\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\tcase 'CliConfirmRequiredError':\n\t\tcase 'CliConfirmDeclinedError':\n\t\tcase 'CliSupervisorLiveError':\n\t\tcase 'CliNoSupervisorError':\n\t\tcase 'CliInternalError':\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn true;\n\t\tdefault:\n\t\t\treturn false;\n\t}\n};\n\n/** Project a tagged error to its sysexit code. The dispatcher reads\n *  this to set `process.exitCode` — there is exactly one place in the\n *  surface where tag → numeric mapping happens. */\nexport const exitCodeFor = (error: CliError): ExitCode => {\n\tswitch (error._tag) {\n\t\tcase 'CliUsageError':\n\t\t\treturn XC.USAGE;\n\t\tcase 'CliConfigNotFoundError':\n\t\t\treturn XC.NO_INPUT;\n\t\tcase 'CliConfigInvalidError':\n\t\t\treturn XC.CONFIG;\n\t\tcase 'CliUnavailableError':\n\t\t\treturn XC.UNAVAILABLE;\n\t\tcase 'CliSnapshotNotFoundError':\n\t\t\treturn XC.SNAPSHOT_NOT_FOUND;\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\t\treturn XC.USAGE;\n\t\tcase 'CliConfirmRequiredError':\n\t\tcase 'CliConfirmDeclinedError':\n\t\t\treturn XC.CONFIRM_REQUIRED;\n\t\tcase 'CliSupervisorLiveError':\n\t\t\treturn XC.SUPERVISOR_LIVE;\n\t\tcase 'CliNoSupervisorError':\n\t\t\treturn XC.UNAVAILABLE;\n\t\tcase 'CliInternalError':\n\t\t\treturn XC.SOFTWARE;\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn error.exitCode;\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = error;\n\t\t\tvoid _exhaustive;\n\t\t\treturn XC.SOFTWARE;\n\t\t}\n\t}\n};\n\n/** Short single-line summary for the envelope's `error.summary`\n *  field. Cascade detail lives in `error.chain[]`. */\nexport const summaryFor = (error: CliError): string => {\n\tswitch (error._tag) {\n\t\tcase 'CliUsageError':\n\t\t\treturn error.message;\n\t\tcase 'CliConfigNotFoundError':\n\t\t\treturn error.message;\n\t\tcase 'CliConfigInvalidError':\n\t\t\treturn error.message;\n\t\tcase 'CliUnavailableError':\n\t\t\treturn `${error.service} unavailable: ${error.message}`;\n\t\tcase 'CliSnapshotNotFoundError':\n\t\t\treturn `snapshot not found: ${error.snapshotRef}`;\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\t\treturn `snapshot reference is ambiguous: ${error.snapshotRef}`;\n\t\tcase 'CliConfirmRequiredError':\n\t\t\treturn `${error.verb} requires confirmation`;\n\t\tcase 'CliConfirmDeclinedError':\n\t\t\treturn `${error.verb} confirmation declined`;\n\t\tcase 'CliSupervisorLiveError':\n\t\t\treturn `supervisor live for ${error.app}/${error.stack}`;\n\t\tcase 'CliNoSupervisorError':\n\t\t\treturn `no supervisor running for ${error.app}/${error.stack}`;\n\t\tcase 'CliInternalError':\n\t\t\treturn error.message;\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn '(already reported)';\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = error;\n\t\t\tvoid _exhaustive;\n\t\t\treturn '(unknown error)';\n\t\t}\n\t}\n};\n\n/** Optional hint for the envelope's `error.hint` field. */\nexport const hintFor = (error: CliError): string | undefined => {\n\tswitch (error._tag) {\n\t\tcase 'CliUsageError':\n\t\t\treturn error.hint;\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\t\treturn `use one of these ids instead: ${error.matches.join(', ')}`;\n\t\tcase 'CliUnavailableError':\n\t\tcase 'CliConfirmRequiredError':\n\t\tcase 'CliConfirmDeclinedError':\n\t\tcase 'CliSupervisorLiveError':\n\t\tcase 'CliNoSupervisorError':\n\t\t\treturn error.hint;\n\t\tcase 'CliConfigNotFoundError':\n\t\tcase 'CliConfigInvalidError':\n\t\tcase 'CliSnapshotNotFoundError':\n\t\tcase 'CliInternalError':\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn undefined;\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = error;\n\t\t\tvoid _exhaustive;\n\t\t\treturn undefined;\n\t\t}\n\t}\n};\n"],"mappings":";;;;;AAwBA,IAAa,gBAAb,cAAmC,KAAK,YAAY,gBAAgB,CAGjE;;;AAIH,IAAa,yBAAb,cAA4C,KAAK,YAAY,yBAAyB,CAGnF;;;AAIH,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAGjF;;AAGH,IAAa,sBAAb,cAAyC,KAAK,YAAY,sBAAsB,CAI7E;;;AAIH,IAAa,2BAAb,cAA8C,KAAK,YAAY,2BAA2B,CAEvF;AAEH,IAAa,4BAAb,cAA+C,KAAK,YAAY,4BAA4B,CAGzF;;;AAIH,IAAa,0BAAb,cAA6C,KAAK,YAAY,0BAA0B,CAGrF;;AAGH,IAAa,0BAAb,cAA6C,KAAK,YAAY,0BAA0B,CAGrF;;;AAIH,IAAa,yBAAb,cAA4C,KAAK,YAAY,yBAAyB,CAInF;AAMuC,KAAK,YAAY,uBAAuB;;;AAQlF,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAGvE;AAS0C,KAAK,YAAY,0BAA0B;AAsBxF,MAAa,cAAc,UAAsC;AAChE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AAExD,SADa,MAAsC,MACnD;EACC,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,0BACJ,QAAO;EACR,QACC,QAAO;;;;;;AAOV,MAAa,eAAe,UAA8B;AACzD,SAAQ,MAAM,MAAd;EACC,KAAK,gBACJ,QAAOA,SAAG;EACX,KAAK,yBACJ,QAAOA,SAAG;EACX,KAAK,wBACJ,QAAOA,SAAG;EACX,KAAK,sBACJ,QAAOA,SAAG;EACX,KAAK,2BACJ,QAAOA,SAAG;EACX,KAAK,4BACJ,QAAOA,SAAG;EACX,KAAK;EACL,KAAK,0BACJ,QAAOA,SAAG;EACX,KAAK,yBACJ,QAAOA,SAAG;EACX,KAAK,uBACJ,QAAOA,SAAG;EACX,KAAK,mBACJ,QAAOA,SAAG;EACX,KAAK,0BACJ,QAAO,MAAM;EACd,QAGC,QAAOA,SAAG;;;;;AAOb,MAAa,cAAc,UAA4B;AACtD,SAAQ,MAAM,MAAd;EACC,KAAK,gBACJ,QAAO,MAAM;EACd,KAAK,yBACJ,QAAO,MAAM;EACd,KAAK,wBACJ,QAAO,MAAM;EACd,KAAK,sBACJ,QAAO,GAAG,MAAM,QAAQ,gBAAgB,MAAM;EAC/C,KAAK,2BACJ,QAAO,uBAAuB,MAAM;EACrC,KAAK,4BACJ,QAAO,oCAAoC,MAAM;EAClD,KAAK,0BACJ,QAAO,GAAG,MAAM,KAAK;EACtB,KAAK,0BACJ,QAAO,GAAG,MAAM,KAAK;EACtB,KAAK,yBACJ,QAAO,uBAAuB,MAAM,IAAI,GAAG,MAAM;EAClD,KAAK,uBACJ,QAAO,6BAA6B,MAAM,IAAI,GAAG,MAAM;EACxD,KAAK,mBACJ,QAAO,MAAM;EACd,KAAK,0BACJ,QAAO;EACR,QAGC,QAAO;;;;AAMV,MAAa,WAAW,UAAwC;AAC/D,SAAQ,MAAM,MAAd;EACC,KAAK,gBACJ,QAAO,MAAM;EACd,KAAK,4BACJ,QAAO,iCAAiC,MAAM,QAAQ,KAAK,KAAK;EACjE,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,uBACJ,QAAO,MAAM;EACd,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,0BACJ;EACD,QAGC"}
+{"version":3,"file":"errors.mjs","names":["XC"],"sources":["../../../src/surfaces/cli/errors.ts"],"sourcesContent":["// CLI surface — typed errors carried up to the top-level renderer.\n//\n// Architecture (distilled/20-cli.md § Edge cases) enumerates the\n// surface's failure modes. Each one MUST resolve to a stable sysexit\n// code; the error tag here carries that mapping so the dispatcher\n// doesn't sprinkle exit codes through every command.\n//\n// Why tagged errors and not plain `Effect.fail(string)`?\n//   - `catchTag` in commands can pick out the precise tag without\n//     stringly matching.\n//   - The cascade formatter (substrate/runtime/observability/\n//     cascade-formatter.ts) renders these natively via their `_tag`.\n//   - The `schema --json` command enumerates the tag table.\n\nimport { Data } from 'effect';\n\nimport { type ExitCode, ExitCode as XC } from './sysexits.ts';\n\n// -----------------------------------------------------------------------------\n// Tagged errors\n// -----------------------------------------------------------------------------\n\n/** Argv parsing produced an error — unknown subcommand, malformed\n *  flag value, missing required positional. */\nexport class CliUsageError extends Data.TaggedError('CliUsageError')<{\n\treadonly message: string;\n\treadonly hint?: string;\n}> {}\n\n/** The user's `devstack.config.ts` could not be located (path probe\n *  exhausted) or could not be imported. */\nexport class CliConfigNotFoundError extends Data.TaggedError('CliConfigNotFoundError')<{\n\treadonly message: string;\n\treadonly searchedPaths?: ReadonlyArray<string>;\n}> {}\n\n/** The config imported successfully but its default export is not a\n *  `Stack` value (failed brand check, missing required field). */\nexport class CliConfigInvalidError extends Data.TaggedError('CliConfigInvalidError')<{\n\treadonly message: string;\n\treadonly cause?: unknown;\n}> {}\n\n/** A required service (Docker daemon, network) is unavailable. */\nexport class CliUnavailableError extends Data.TaggedError('CliUnavailableError')<{\n\treadonly message: string;\n\treadonly service: string;\n\treadonly hint?: string;\n}> {}\n\n/** Snapshot name/id not found. Carries the reference the caller\n *  used so the failure renderer can echo it back. */\nexport class CliSnapshotNotFoundError extends Data.TaggedError('CliSnapshotNotFoundError')<{\n\treadonly snapshotRef: string;\n}> {}\n\nexport class CliSnapshotAmbiguousError extends Data.TaggedError('CliSnapshotAmbiguousError')<{\n\treadonly snapshotRef: string;\n\treadonly matches: ReadonlyArray<string>;\n}> {}\n\n/** Destructive verb refused because `--yes` was absent and prompting\n *  was forbidden (non-TTY stdin or `--no-input`). */\nexport class CliConfirmRequiredError extends Data.TaggedError('CliConfirmRequiredError')<{\n\treadonly verb: string;\n\treadonly hint?: string;\n}> {}\n\n/** Destructive verb was prompted interactively and the user declined. */\nexport class CliConfirmDeclinedError extends Data.TaggedError('CliConfirmDeclinedError')<{\n\treadonly verb: string;\n\treadonly hint?: string;\n}> {}\n\n/** Engine reports a live supervisor for the target stack; the verb\n *  refused to mutate shared state. */\nexport class CliSupervisorLiveError extends Data.TaggedError('CliSupervisorLiveError')<{\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hint?: string;\n}> {}\n\n/** The verb requires a live supervisor (a stack must be `up`) but\n *  none is running for `(app, stack)`. Distinguished from\n *  `CliSupervisorLiveError` (the inverse case where the verb refused\n *  because one IS live). */\nexport class CliNoSupervisorError extends Data.TaggedError('CliNoSupervisorError')<{\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hint?: string;\n}> {}\n\n/** Internal/unexpected failure. Wraps an arbitrary cause; the cascade\n *  formatter renders the inner. */\nexport class CliInternalError extends Data.TaggedError('CliInternalError')<{\n\treadonly message: string;\n\treadonly cause?: unknown;\n}> {}\n\n/** Sentinel: subcommand already pretty-rendered its failure. The\n *  top-level renderer recognizes this tag and skips re-rendering, but\n *  still propagates `exitCode` to the OS exit code.\n *\n *  Architecture § Learnings: \"Already-reported sentinel pattern\" — the\n *  marker traverses the cause structure used by the Effect runtime, so\n *  the top-level `Effect.catch` sees it. */\nexport class CliAlreadyReportedError extends Data.TaggedError('CliAlreadyReportedError')<{\n\treadonly exitCode: ExitCode;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Union + sysexit projection\n// -----------------------------------------------------------------------------\n\nexport type CliError =\n\t| CliUsageError\n\t| CliConfigNotFoundError\n\t| CliConfigInvalidError\n\t| CliUnavailableError\n\t| CliSnapshotNotFoundError\n\t| CliSnapshotAmbiguousError\n\t| CliConfirmRequiredError\n\t| CliConfirmDeclinedError\n\t| CliSupervisorLiveError\n\t| CliNoSupervisorError\n\t| CliInternalError\n\t| CliAlreadyReportedError;\n\nexport const isCliError = (value: unknown): value is CliError => {\n\tif (typeof value !== 'object' || value === null) return false;\n\tconst tag = (value as { readonly _tag?: unknown })._tag;\n\tswitch (tag) {\n\t\tcase 'CliUsageError':\n\t\tcase 'CliConfigNotFoundError':\n\t\tcase 'CliConfigInvalidError':\n\t\tcase 'CliUnavailableError':\n\t\tcase 'CliSnapshotNotFoundError':\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\tcase 'CliConfirmRequiredError':\n\t\tcase 'CliConfirmDeclinedError':\n\t\tcase 'CliSupervisorLiveError':\n\t\tcase 'CliNoSupervisorError':\n\t\tcase 'CliInternalError':\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn true;\n\t\tdefault:\n\t\t\treturn false;\n\t}\n};\n\n/** Project a tagged error to its sysexit code. The dispatcher reads\n *  this to set `process.exitCode` — there is exactly one place in the\n *  surface where tag → numeric mapping happens. */\nexport const exitCodeFor = (error: CliError): ExitCode => {\n\tswitch (error._tag) {\n\t\tcase 'CliUsageError':\n\t\t\treturn XC.USAGE;\n\t\tcase 'CliConfigNotFoundError':\n\t\t\treturn XC.NO_INPUT;\n\t\tcase 'CliConfigInvalidError':\n\t\t\treturn XC.CONFIG;\n\t\tcase 'CliUnavailableError':\n\t\t\treturn XC.UNAVAILABLE;\n\t\tcase 'CliSnapshotNotFoundError':\n\t\t\treturn XC.SNAPSHOT_NOT_FOUND;\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\t\treturn XC.USAGE;\n\t\tcase 'CliConfirmRequiredError':\n\t\tcase 'CliConfirmDeclinedError':\n\t\t\treturn XC.CONFIRM_REQUIRED;\n\t\tcase 'CliSupervisorLiveError':\n\t\t\treturn XC.SUPERVISOR_LIVE;\n\t\tcase 'CliNoSupervisorError':\n\t\t\treturn XC.UNAVAILABLE;\n\t\tcase 'CliInternalError':\n\t\t\treturn XC.SOFTWARE;\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn error.exitCode;\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = error;\n\t\t\tvoid _exhaustive;\n\t\t\treturn XC.SOFTWARE;\n\t\t}\n\t}\n};\n\n/** Short single-line summary for the envelope's `error.summary`\n *  field. Cascade detail lives in `error.chain[]`. */\nexport const summaryFor = (error: CliError): string => {\n\tswitch (error._tag) {\n\t\tcase 'CliUsageError':\n\t\t\treturn error.message;\n\t\tcase 'CliConfigNotFoundError':\n\t\t\treturn error.message;\n\t\tcase 'CliConfigInvalidError':\n\t\t\treturn error.message;\n\t\tcase 'CliUnavailableError':\n\t\t\treturn `${error.service} unavailable: ${error.message}`;\n\t\tcase 'CliSnapshotNotFoundError':\n\t\t\treturn `snapshot not found: ${error.snapshotRef}`;\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\t\treturn `snapshot reference is ambiguous: ${error.snapshotRef}`;\n\t\tcase 'CliConfirmRequiredError':\n\t\t\treturn `${error.verb} requires confirmation`;\n\t\tcase 'CliConfirmDeclinedError':\n\t\t\treturn `${error.verb} confirmation declined`;\n\t\tcase 'CliSupervisorLiveError':\n\t\t\treturn `supervisor live for ${error.app}/${error.stack}`;\n\t\tcase 'CliNoSupervisorError':\n\t\t\treturn `no supervisor running for ${error.app}/${error.stack}`;\n\t\tcase 'CliInternalError':\n\t\t\treturn error.message;\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn '(already reported)';\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = error;\n\t\t\tvoid _exhaustive;\n\t\t\treturn '(unknown error)';\n\t\t}\n\t}\n};\n\n/** Optional hint for the envelope's `error.hint` field. */\nexport const hintFor = (error: CliError): string | undefined => {\n\tswitch (error._tag) {\n\t\tcase 'CliUsageError':\n\t\t\treturn error.hint;\n\t\tcase 'CliSnapshotAmbiguousError':\n\t\t\treturn `use one of these ids instead: ${error.matches.join(', ')}`;\n\t\tcase 'CliUnavailableError':\n\t\tcase 'CliConfirmRequiredError':\n\t\tcase 'CliConfirmDeclinedError':\n\t\tcase 'CliSupervisorLiveError':\n\t\tcase 'CliNoSupervisorError':\n\t\t\treturn error.hint;\n\t\tcase 'CliConfigNotFoundError':\n\t\t\t// Operator-facing hint: the most common cause is running a\n\t\t\t// devstack verb in a directory whose ancestors don't contain a\n\t\t\t// `devstack.config.ts`. Two actions resolve it — either\n\t\t\t// initialize one in the current tree, or point the loader at\n\t\t\t// an explicit path. We surface both so the envelope renderer\n\t\t\t// (JSON `error.hint`, human stderr line) can render one short\n\t\t\t// line instead of forcing the caller to remember the recipe.\n\t\t\treturn 'config file not found; run `devstack init` or pass `--config <path>`';\n\t\tcase 'CliConfigInvalidError':\n\t\tcase 'CliSnapshotNotFoundError':\n\t\tcase 'CliInternalError':\n\t\tcase 'CliAlreadyReportedError':\n\t\t\treturn undefined;\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = error;\n\t\t\tvoid _exhaustive;\n\t\t\treturn undefined;\n\t\t}\n\t}\n};\n"],"mappings":";;;;;AAwBA,IAAa,gBAAb,cAAmC,KAAK,YAAY,gBAAgB,CAGjE;;;AAIH,IAAa,yBAAb,cAA4C,KAAK,YAAY,yBAAyB,CAGnF;;;AAIH,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAGjF;;AAGH,IAAa,sBAAb,cAAyC,KAAK,YAAY,sBAAsB,CAI7E;;;AAIH,IAAa,2BAAb,cAA8C,KAAK,YAAY,2BAA2B,CAEvF;AAEH,IAAa,4BAAb,cAA+C,KAAK,YAAY,4BAA4B,CAGzF;;;AAIH,IAAa,0BAAb,cAA6C,KAAK,YAAY,0BAA0B,CAGrF;;AAGH,IAAa,0BAAb,cAA6C,KAAK,YAAY,0BAA0B,CAGrF;;;AAIH,IAAa,yBAAb,cAA4C,KAAK,YAAY,yBAAyB,CAInF;AAMuC,KAAK,YAAY,uBAAuB;;;AAQlF,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAGvE;AAS0C,KAAK,YAAY,0BAA0B;AAsBxF,MAAa,cAAc,UAAsC;AAChE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AAExD,SADa,MAAsC,MACnD;EACC,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,0BACJ,QAAO;EACR,QACC,QAAO;;;;;;AAOV,MAAa,eAAe,UAA8B;AACzD,SAAQ,MAAM,MAAd;EACC,KAAK,gBACJ,QAAOA,SAAG;EACX,KAAK,yBACJ,QAAOA,SAAG;EACX,KAAK,wBACJ,QAAOA,SAAG;EACX,KAAK,sBACJ,QAAOA,SAAG;EACX,KAAK,2BACJ,QAAOA,SAAG;EACX,KAAK,4BACJ,QAAOA,SAAG;EACX,KAAK;EACL,KAAK,0BACJ,QAAOA,SAAG;EACX,KAAK,yBACJ,QAAOA,SAAG;EACX,KAAK,uBACJ,QAAOA,SAAG;EACX,KAAK,mBACJ,QAAOA,SAAG;EACX,KAAK,0BACJ,QAAO,MAAM;EACd,QAGC,QAAOA,SAAG;;;;;AAOb,MAAa,cAAc,UAA4B;AACtD,SAAQ,MAAM,MAAd;EACC,KAAK,gBACJ,QAAO,MAAM;EACd,KAAK,yBACJ,QAAO,MAAM;EACd,KAAK,wBACJ,QAAO,MAAM;EACd,KAAK,sBACJ,QAAO,GAAG,MAAM,QAAQ,gBAAgB,MAAM;EAC/C,KAAK,2BACJ,QAAO,uBAAuB,MAAM;EACrC,KAAK,4BACJ,QAAO,oCAAoC,MAAM;EAClD,KAAK,0BACJ,QAAO,GAAG,MAAM,KAAK;EACtB,KAAK,0BACJ,QAAO,GAAG,MAAM,KAAK;EACtB,KAAK,yBACJ,QAAO,uBAAuB,MAAM,IAAI,GAAG,MAAM;EAClD,KAAK,uBACJ,QAAO,6BAA6B,MAAM,IAAI,GAAG,MAAM;EACxD,KAAK,mBACJ,QAAO,MAAM;EACd,KAAK,0BACJ,QAAO;EACR,QAGC,QAAO;;;;AAMV,MAAa,WAAW,UAAwC;AAC/D,SAAQ,MAAM,MAAd;EACC,KAAK,gBACJ,QAAO,MAAM;EACd,KAAK,4BACJ,QAAO,iCAAiC,MAAM,QAAQ,KAAK,KAAK;EACjE,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,uBACJ,QAAO,MAAM;EACd,KAAK,yBAQJ,QAAO;EACR,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,0BACJ;EACD,QAGC"}

package/dist/surfaces/cli/flags.mjs

@@ -10,7 +10,6 @@ const ENV_VARS = {
 	STATE_DIR: "DEVSTACK_STATE_DIR",
 	CONFIG_PATH: "DEVSTACK_CONFIG",
 	NETWORK: "DEVSTACK_NETWORK",
-	RENDERER: "DEVSTACK_RENDERER",
 	NO_COLOR: "NO_COLOR"
 };
 /** Pop the next positional argument from `rest`. Returns undefined if

package/dist/surfaces/cli/flags.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"flags.mjs","names":[],"sources":["../../../src/surfaces/cli/flags.ts"],"sourcesContent":["// CLI surface — shared flag types and subcommand helpers.\n//\n// Stricli owns argv parsing in `surfaces/cli/index.ts`. This file\n// keeps the resolved flag shape and the tiny helpers used by nested\n// command implementations that still receive a typed `rest` tail\n// (currently snapshot subcommands).\n\nimport { CliUsageError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Global flag definitions (shared across every verb)\n// -----------------------------------------------------------------------------\n\n/** Output mode resolved from `--json` (or `DEVSTACK_JSON=1`). */\nexport type OutputMode = 'human' | 'json';\n\n/** Renderer selected by the CLI. `tui` maps to the Ink-backed live\n * dashboard; `plain` is line-oriented stderr output; `silent` mounts no\n * visible renderer. */\nexport type CliRendererMode = 'tui' | 'plain' | 'silent';\n\n/** Confirmation policy resolved from `--yes` + `--no-input` + TTY\n *  state of stdin. */\nexport interface ConfirmPolicy {\n\treadonly assumeYes: boolean;\n\treadonly forbidPrompt: boolean;\n\treadonly stdinIsTty: boolean;\n}\n\n/** Bundle of command-scoped flags after Stricli parsing plus env\n *  fallback resolution. */\nexport interface GlobalFlags {\n\treadonly outputMode: OutputMode;\n\treadonly app: string | undefined;\n\treadonly stack: string | undefined;\n\treadonly stateDir: string | undefined;\n\treadonly configPath: string | undefined;\n\treadonly network: string | undefined;\n\treadonly renderer: CliRendererMode | undefined;\n\treadonly dryRun: boolean;\n\treadonly confirm: ConfirmPolicy;\n\t/** Legacy field kept in the internal shape; schema is now the\n\t *  explicit `devstack schema --json` command. */\n\treadonly schemaEmit: boolean;\n\t/** Verbosity bump; primarily affects logger filter. */\n\treadonly verbose: boolean;\n\t/** Print help instead of running. */\n\treadonly help: boolean;\n\t/** Print version one-liner and exit. */\n\treadonly version: boolean;\n\t/** Argv tail after the global-flag pass; subcommand parsers slice\n\t *  positional arguments and verb-specific flags out of this. */\n\treadonly rest: ReadonlyArray<string>;\n}\n\n/** Environment-variable names the CLI consults. Centralized so the\n *  `schema --json` command can enumerate them. */\nexport const ENV_VARS = {\n\tJSON: 'DEVSTACK_JSON',\n\tNO_INPUT: 'DEVSTACK_NO_INPUT',\n\tAPP: 'DEVSTACK_APP',\n\tSTACK: 'DEVSTACK_STACK',\n\tSTATE_DIR: 'DEVSTACK_STATE_DIR',\n\tCONFIG_PATH: 'DEVSTACK_CONFIG',\n\tNETWORK: 'DEVSTACK_NETWORK',\n\tRENDERER: 'DEVSTACK_RENDERER',\n\tNO_COLOR: 'NO_COLOR',\n} as const;\n\nexport type EnvVarName = (typeof ENV_VARS)[keyof typeof ENV_VARS];\n\n// -----------------------------------------------------------------------------\n// Subcommand-flag helpers\n// -----------------------------------------------------------------------------\n\n/** Pop the next positional argument from `rest`. Returns undefined if\n *  none remain. */\nexport const takePositional = (\n\trest: ReadonlyArray<string>,\n): { readonly head: string | undefined; readonly tail: ReadonlyArray<string> } => {\n\tconst idx = rest.findIndex((tok) => !tok.startsWith('-'));\n\tif (idx === -1) return { head: undefined, tail: rest };\n\tconst tail = [...rest.slice(0, idx), ...rest.slice(idx + 1)];\n\treturn { head: rest[idx], tail };\n};\n\n/** Look up a boolean flag in `rest` by name (long form only). Returns\n *  the matched flag plus the remaining tokens. */\nexport const takeBoolFlag = (\n\trest: ReadonlyArray<string>,\n\tname: string,\n): { readonly present: boolean; readonly tail: ReadonlyArray<string> } => {\n\tconst flag = `--${name}`;\n\tconst idx = rest.indexOf(flag);\n\tif (idx === -1) return { present: false, tail: rest };\n\tconst tail = [...rest.slice(0, idx), ...rest.slice(idx + 1)];\n\treturn { present: true, tail };\n};\n\n/** Look up a value flag (`--name=val` or `--name val`). */\nexport const takeValueFlag = (\n\trest: ReadonlyArray<string>,\n\tname: string,\n): { readonly value: string | undefined; readonly tail: ReadonlyArray<string> } => {\n\tconst prefix = `--${name}=`;\n\tfor (let i = 0; i < rest.length; i++) {\n\t\tconst tok = rest[i]!;\n\t\tif (tok.startsWith(prefix)) {\n\t\t\treturn {\n\t\t\t\tvalue: tok.slice(prefix.length),\n\t\t\t\ttail: [...rest.slice(0, i), ...rest.slice(i + 1)],\n\t\t\t};\n\t\t}\n\t\tif (tok === `--${name}`) {\n\t\t\tconst next = rest[i + 1];\n\t\t\tif (next === undefined || next.startsWith('-')) {\n\t\t\t\tthrow new CliUsageError({ message: `flag --${name} requires a value` });\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tvalue: next,\n\t\t\t\ttail: [...rest.slice(0, i), ...rest.slice(i + 2)],\n\t\t\t};\n\t\t}\n\t}\n\treturn { value: undefined, tail: rest };\n};\n"],"mappings":";;;;AAyDA,MAAa,WAAW;CACvB,MAAM;CACN,UAAU;CACV,KAAK;CACL,OAAO;CACP,WAAW;CACX,aAAa;CACb,SAAS;CACT,UAAU;CACV,UAAU;CACV;;;AAUD,MAAa,kBACZ,SACiF;CACjF,MAAM,MAAM,KAAK,WAAW,QAAQ,CAAC,IAAI,WAAW,IAAI,CAAC;AACzD,KAAI,QAAQ,GAAI,QAAO;EAAE,MAAM,KAAA;EAAW,MAAM;EAAM;CACtD,MAAM,OAAO,CAAC,GAAG,KAAK,MAAM,GAAG,IAAI,EAAE,GAAG,KAAK,MAAM,MAAM,EAAE,CAAC;AAC5D,QAAO;EAAE,MAAM,KAAK;EAAM;EAAM;;;AAiBjC,MAAa,iBACZ,MACA,SACkF;CAClF,MAAM,SAAS,KAAK,KAAK;AACzB,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACrC,MAAM,MAAM,KAAK;AACjB,MAAI,IAAI,WAAW,OAAO,CACzB,QAAO;GACN,OAAO,IAAI,MAAM,OAAO,OAAO;GAC/B,MAAM,CAAC,GAAG,KAAK,MAAM,GAAG,EAAE,EAAE,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC;GACjD;AAEF,MAAI,QAAQ,KAAK,QAAQ;GACxB,MAAM,OAAO,KAAK,IAAI;AACtB,OAAI,SAAS,KAAA,KAAa,KAAK,WAAW,IAAI,CAC7C,OAAM,IAAI,cAAc,EAAE,SAAS,UAAU,KAAK,oBAAoB,CAAC;AAExE,UAAO;IACN,OAAO;IACP,MAAM,CAAC,GAAG,KAAK,MAAM,GAAG,EAAE,EAAE,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC;IACjD;;;AAGH,QAAO;EAAE,OAAO,KAAA;EAAW,MAAM;EAAM"}
+{"version":3,"file":"flags.mjs","names":[],"sources":["../../../src/surfaces/cli/flags.ts"],"sourcesContent":["// CLI surface — shared flag types and subcommand helpers.\n//\n// Stricli owns argv parsing in `surfaces/cli/index.ts`. This file\n// keeps the resolved flag shape and the tiny helpers used by nested\n// command implementations that still receive a typed `rest` tail\n// (currently snapshot subcommands).\n\nimport { CliUsageError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Global flag definitions (shared across every verb)\n// -----------------------------------------------------------------------------\n\n/** Output mode resolved from `--json` (or `DEVSTACK_JSON=1`). */\nexport type OutputMode = 'human' | 'json';\n\n/** Renderer selected by the CLI. `tui` maps to the Ink-backed live\n * dashboard; `plain` is line-oriented stderr output; `silent` mounts no\n * visible renderer. */\nexport type CliRendererMode = 'tui' | 'plain' | 'silent';\n\n/** Confirmation policy resolved from `--yes` + `--no-input` + TTY\n *  state of stdin. */\nexport interface ConfirmPolicy {\n\treadonly assumeYes: boolean;\n\treadonly forbidPrompt: boolean;\n\treadonly stdinIsTty: boolean;\n}\n\n/** Bundle of command-scoped flags after Stricli parsing plus env\n *  fallback resolution. */\nexport interface GlobalFlags {\n\treadonly outputMode: OutputMode;\n\treadonly app: string | undefined;\n\treadonly stack: string | undefined;\n\treadonly stateDir: string | undefined;\n\treadonly configPath: string | undefined;\n\treadonly network: string | undefined;\n\treadonly renderer: CliRendererMode | undefined;\n\treadonly dryRun: boolean;\n\treadonly confirm: ConfirmPolicy;\n\t/** Verbosity bump; primarily affects logger filter. */\n\treadonly verbose: boolean;\n\t/** Argv tail after the global-flag pass; subcommand parsers slice\n\t *  positional arguments and verb-specific flags out of this. */\n\treadonly rest: ReadonlyArray<string>;\n}\n\n/** Environment-variable names the CLI consults. Centralized so the\n *  `schema --json` command can enumerate them. */\nexport const ENV_VARS = {\n\tJSON: 'DEVSTACK_JSON',\n\tNO_INPUT: 'DEVSTACK_NO_INPUT',\n\tAPP: 'DEVSTACK_APP',\n\tSTACK: 'DEVSTACK_STACK',\n\tSTATE_DIR: 'DEVSTACK_STATE_DIR',\n\tCONFIG_PATH: 'DEVSTACK_CONFIG',\n\tNETWORK: 'DEVSTACK_NETWORK',\n\tNO_COLOR: 'NO_COLOR',\n} as const;\n\nexport type EnvVarName = (typeof ENV_VARS)[keyof typeof ENV_VARS];\n\n// -----------------------------------------------------------------------------\n// Subcommand-flag helpers\n// -----------------------------------------------------------------------------\n\n/** Pop the next positional argument from `rest`. Returns undefined if\n *  none remain. */\nexport const takePositional = (\n\trest: ReadonlyArray<string>,\n): { readonly head: string | undefined; readonly tail: ReadonlyArray<string> } => {\n\tconst idx = rest.findIndex((tok) => !tok.startsWith('-'));\n\tif (idx === -1) return { head: undefined, tail: rest };\n\tconst tail = [...rest.slice(0, idx), ...rest.slice(idx + 1)];\n\treturn { head: rest[idx], tail };\n};\n\n/** Look up a value flag (`--name=val` or `--name val`). */\nexport const takeValueFlag = (\n\trest: ReadonlyArray<string>,\n\tname: string,\n): { readonly value: string | undefined; readonly tail: ReadonlyArray<string> } => {\n\tconst prefix = `--${name}=`;\n\tfor (let i = 0; i < rest.length; i++) {\n\t\tconst tok = rest[i]!;\n\t\tif (tok.startsWith(prefix)) {\n\t\t\treturn {\n\t\t\t\tvalue: tok.slice(prefix.length),\n\t\t\t\ttail: [...rest.slice(0, i), ...rest.slice(i + 1)],\n\t\t\t};\n\t\t}\n\t\tif (tok === `--${name}`) {\n\t\t\tconst next = rest[i + 1];\n\t\t\tif (next === undefined || next.startsWith('-')) {\n\t\t\t\tthrow new CliUsageError({ message: `flag --${name} requires a value` });\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tvalue: next,\n\t\t\t\ttail: [...rest.slice(0, i), ...rest.slice(i + 2)],\n\t\t\t};\n\t\t}\n\t}\n\treturn { value: undefined, tail: rest };\n};\n"],"mappings":";;;;AAkDA,MAAa,WAAW;CACvB,MAAM;CACN,UAAU;CACV,KAAK;CACL,OAAO;CACP,WAAW;CACX,aAAa;CACb,SAAS;CACT,UAAU;CACV;;;AAUD,MAAa,kBACZ,SACiF;CACjF,MAAM,MAAM,KAAK,WAAW,QAAQ,CAAC,IAAI,WAAW,IAAI,CAAC;AACzD,KAAI,QAAQ,GAAI,QAAO;EAAE,MAAM,KAAA;EAAW,MAAM;EAAM;CACtD,MAAM,OAAO,CAAC,GAAG,KAAK,MAAM,GAAG,IAAI,EAAE,GAAG,KAAK,MAAM,MAAM,EAAE,CAAC;AAC5D,QAAO;EAAE,MAAM,KAAK;EAAM;EAAM;;;AAIjC,MAAa,iBACZ,MACA,SACkF;CAClF,MAAM,SAAS,KAAK,KAAK;AACzB,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACrC,MAAM,MAAM,KAAK;AACjB,MAAI,IAAI,WAAW,OAAO,CACzB,QAAO;GACN,OAAO,IAAI,MAAM,OAAO,OAAO;GAC/B,MAAM,CAAC,GAAG,KAAK,MAAM,GAAG,EAAE,EAAE,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC;GACjD;AAEF,MAAI,QAAQ,KAAK,QAAQ;GACxB,MAAM,OAAO,KAAK,IAAI;AACtB,OAAI,SAAS,KAAA,KAAa,KAAK,WAAW,IAAI,CAC7C,OAAM,IAAI,cAAc,EAAE,SAAS,UAAU,KAAK,oBAAoB,CAAC;AAExE,UAAO;IACN,OAAO;IACP,MAAM,CAAC,GAAG,KAAK,MAAM,GAAG,EAAE,EAAE,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC;IACjD;;;AAGH,QAAO;EAAE,OAAO,KAAA;EAAW,MAAM;EAAM"}

package/dist/surfaces/cli/index.mjs

@@ -1,19 +1,27 @@
 import { parseDevstackNetworkName } from "../../api/inference-network.mjs";
-import "./sysexits.mjs";
+import { ExitCode } from "./sysexits.mjs";
 import { CliInternalError, CliUsageError, exitCodeFor } from "./errors.mjs";
 import { ENV_VARS } from "./flags.mjs";
 import { commandSchema } from "./command-tree.mjs";
 import "./envelope.mjs";
-import { emitFailure, nodeProcessIO } from "./output.mjs";
+import { emitFailure, emitSuccess, nodeProcessIO } from "./output.mjs";
 import { runConfig } from "./commands/config.mjs";
 import { runDoctor } from "./commands/doctor.mjs";
 import { runPrune } from "./commands/prune.mjs";
 import { runSnapshot } from "./commands/snapshot.mjs";
 import { runStatus } from "./commands/status.mjs";
 import { runWipe } from "./commands/wipe.mjs";
+import "./commands/index.mjs";
 import { Effect } from "effect";
+import { readFileSync } from "node:fs";
 import { buildApplication, buildChoiceParser, buildCommand, buildRouteMap, run, text_en } from "@stricli/core";
 //#region src/surfaces/cli/index.ts
+const readPackageVersion = () => {
+	const raw = readFileSync(new URL("../../../package.json", import.meta.url), "utf8");
+	const pkg = JSON.parse(raw);
+	if (typeof pkg.version !== "string") throw new Error("devstack package.json is missing a string version");
+	return pkg.version;
+};
 const makeBufferedProcess = (env) => {
 	const stdoutBuffer = [];
 	const stderrBuffer = [];
@@ -138,18 +146,46 @@ const makeGlobalFlags = (ctx, flags, rest) => {
 			forbidPrompt: flags.noInput === true || ctx.env[ENV_VARS.NO_INPUT] === "1",
 			stdinIsTty: ctx.stdinIsTty
 		},
-		schemaEmit: false,
 		verbose: flags.verbose === true,
-		help: false,
-		version: false,
 		rest
 	};
 };
-const setNetworkEnv = (flags) => flags.network === void 0 ? Effect.void : Effect.sync(() => {
-	process.env[ENV_VARS.NETWORK] = flags.network;
-});
+/**
+* Bridge the CLI `--network` flag through `process.env` so config-load-time
+* factory reads pick it up. This indirection is deliberate, not a leak.
+*
+* Why the mutation exists:
+*   The `deepbook()` factory (`plugins/deepbook/index.ts`) defaults its mode
+*   by reading `process.env.DEVSTACK_NETWORK` at config import time — before
+*   any flag value has reached the orchestrator. To make `--network` affect
+*   the same default, we must mutate the env BEFORE the user's
+*   `devstack.config.ts` is loaded. The chain is:
+*     `--network=<net>` flag  →  setNetworkEnv  →  `process.env.DEVSTACK_NETWORK`
+*                              →  `deepbook()` factory's env read at import.
+*
+* Why save/restore (and a scoped finalizer) matters:
+*   The CLI is also invoked from tests and embedded harnesses inside a single
+*   process. An unscoped mutation leaks across invocations: a test that runs
+*   `dispatch(['up','--network=testnet'])` followed by `dispatch(['up'])`
+*   would see the second call inherit `testnet` from the first. The
+*   finalizer restores the prior value (or deletes the key if it was unset)
+*   on success, failure, AND interrupt — `Effect.addFinalizer` guarantees
+*   the cleanup runs regardless of how the scope closes.
+*/
+const setNetworkEnv = (flags) => {
+	if (flags.network === void 0) return Effect.void;
+	const next = flags.network;
+	return Effect.gen(function* () {
+		const prior = process.env[ENV_VARS.NETWORK];
+		process.env[ENV_VARS.NETWORK] = next;
+		yield* Effect.addFinalizer(() => Effect.sync(() => {
+			if (prior === void 0) delete process.env[ENV_VARS.NETWORK];
+			else process.env[ENV_VARS.NETWORK] = prior;
+		}));
+	});
+};
 const runCommandEffect = async (ctx, command, flags, effect) => {
-	const program = setNetworkEnv(flags).pipe(Effect.andThen(effect), Effect.catch((error) => emitFailure(ctx.io, flags.outputMode, {
+	const program = Effect.scoped(setNetworkEnv(flags).pipe(Effect.andThen(effect), Effect.catch((error) => emitFailure(ctx.io, flags.outputMode, {
 		command,
 		elapsedMs: 0,
 		error
@@ -158,7 +194,7 @@ const runCommandEffect = async (ctx, command, flags, effect) => {
 		elapsedMs: 0,
 		error: new CliInternalError({ message: "unexpected internal failure" }),
 		cause
-	}).pipe(Effect.as({ exitCode: 70 }))));
+	}).pipe(Effect.as({ exitCode: ExitCode.SOFTWARE })))));
 	const result = await Effect.runPromise(program);
 	if (ctx.io.lastExitCode() === null) await Effect.runPromise(ctx.io.setExitCode(result.exitCode));
 };
@@ -251,11 +287,18 @@ const app = buildApplication(buildRouteMap({
 			parameters: { flags: { json: identityFlagParams.json } },
 			docs: { brief: "Emit the CLI schema" },
 			func: function(flags) {
-				const mode = outputModeFrom(flags, this.env);
-				return Effect.runPromise(this.io.writeStdout(JSON.stringify({
-					...commandSchema(),
-					outputMode: mode
-				})).pipe(Effect.andThen(this.io.setExitCode(0))));
+				return runWithFlags(this, "schema", flags, [], (global) => {
+					const data = {
+						...commandSchema(),
+						outputMode: global.outputMode
+					};
+					return emitSuccess(this.io, global.outputMode, {
+						command: "schema",
+						elapsedMs: 0,
+						data,
+						humanLines: [JSON.stringify(data, null, 2)]
+					}).pipe(Effect.as({ exitCode: 0 }));
+				});
 			}
 		}),
 		snapshot: buildRouteMap({
@@ -356,7 +399,7 @@ const app = buildApplication(buildRouteMap({
 	docs: { brief: "Sui development stack CLI" }
 }), {
 	name: "devstack",
-	versionInfo: { currentVersion: "0.0.0" },
+	versionInfo: { currentVersion: readPackageVersion() },
 	scanner: { caseStyle: "allow-kebab-for-camel" },
 	documentation: {
 		caseStyle: "convert-camel-to-kebab",
@@ -369,10 +412,47 @@ const app = buildApplication(buildRouteMap({
 	}) }
 });
 const jsonRequested = (argv, env) => env[ENV_VARS.JSON] === "1" || argv.includes("--json");
+/**
+* Project a `BufferedProcess.exitCode` to a sysexit code AT THE
+* STRICLI-PARSE BOUNDARY ONLY.
+*
+* Contract: `BufferedProcess.exitCode` is mutated ONLY by Stricli's
+* argv-parser when an argv parse step fails (unknown subcommand,
+* malformed flag value, missing required positional). Verbs route
+* their own outcomes through `ctx.io.setExitCode`, which marks
+* `io.touched()` and short-circuits this projection in `dispatch`
+* before `flushBufferedProcess` is reached.
+*
+* The historic implementation collapsed ANY non-zero `code` to
+* `USAGE` (64), but that was wrong: it could only ever observe a
+* Stricli parse failure (the only writer to this field), so the
+* `USAGE` mapping holds by construction. Kept as a named function
+* so the invariant is documented at the call site.
+*/
 const normalizeStricliExitCode = (code) => {
-	if (typeof code === "number" && code !== 0) return 64;
-	return 0;
+	if (typeof code === "number" && code !== 0) return ExitCode.USAGE;
+	return ExitCode.OK;
 };
+/**
+* Bridge Stricli's synchronous `StricliProcess.{stdout,stderr}.write`
+* shape to our async (Effect-based) `CliIO` surface.
+*
+* The indirection is load-bearing for the JSON-envelope contract:
+* Stricli writes argv-parse errors to stderr the moment the parser
+* trips, but `--json` mode demands the failure be EMITTED as a
+* structured envelope on stdout (not raw text on stderr) with exit
+* code `EX_USAGE`. We can't wire Stricli's `stderr.write` directly to
+* `nodeProcessIO.writeStderr` because:
+*
+*   1. The stderr bytes are the raw parser error text; in `--json`
+*      mode we need to transform them into a failure envelope.
+*   2. We don't know whether the verb handler "touched" the IO
+*      (rendered its own envelope) until after Stricli returns.
+*
+* Buffering lets us delay the decision until both signals are
+* available. Tests substitute a `BufferedProcess` whose buffers are
+* later inspected, mirroring the prod flush behavior.
+*/
 const flushBufferedProcess = (process, io, argv, env) => Effect.gen(function* () {
 	const exitCode = normalizeStricliExitCode(process.exitCode);
 	const stdout = process.stdoutBuffer.join("");

package/dist/surfaces/cli/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["runStricli"],"sources":["../../../src/surfaces/cli/index.ts"],"sourcesContent":["// CLI surface — top-level entry point.\n//\n// The public CLI is intentionally small: `up` is the attached operator\n// surface, `apply` is live-aware reconcile (publish to `up` when it is\n// running, one-shot otherwise), and every other command is offline/direct.\n\nimport {\n\tbuildApplication,\n\tbuildChoiceParser,\n\tbuildCommand,\n\tbuildRouteMap,\n\trun as runStricli,\n\ttext_en,\n\ttype CommandContext as StricliCommandContext,\n\ttype StricliProcess,\n} from '@stricli/core';\nimport { Effect } from 'effect';\n\nimport { commandSchema } from './command-tree.ts';\nimport { type CliError, CliInternalError, CliUsageError, exitCodeFor } from './errors.ts';\nimport { type CliRendererMode, ENV_VARS, type GlobalFlags, type OutputMode } from './flags.ts';\nimport { parseDevstackNetworkName } from '../../api/inference-network.ts';\nimport { type CliIO, emitFailure, nodeProcessIO } from './output.ts';\nimport {\n\ttype CommandResult,\n\ttype ConfigDeps,\n\ttype DoctorDeps,\n\ttype PruneDeps,\n\ttype PruneResourceScope,\n\ttype SnapshotDeps,\n\ttype StatusDeps,\n\ttype WipeDeps,\n\trunConfig,\n\trunDoctor,\n\trunPrune,\n\trunSnapshot,\n\trunStatus,\n\trunWipe,\n} from './commands/index.ts';\n\n// -----------------------------------------------------------------------------\n// Deps bundle\n// -----------------------------------------------------------------------------\n\nexport interface LifecycleCommandDeps {\n\treadonly run: (flags: GlobalFlags) => Effect.Effect<CommandResult, CliError>;\n}\n\nexport interface CliDeps {\n\treadonly up: LifecycleCommandDeps;\n\treadonly apply: LifecycleCommandDeps;\n\treadonly status: StatusDeps;\n\treadonly snapshot: SnapshotDeps;\n\treadonly prune: PruneDeps;\n\treadonly doctor: DoctorDeps;\n\treadonly config: ConfigDeps;\n\treadonly wipe: WipeDeps;\n}\n\nexport interface DispatchEnv {\n\treadonly argv: ReadonlyArray<string>;\n\treadonly env: Readonly<Record<string, string | undefined>>;\n\treadonly stdinIsTty: boolean;\n\treadonly io?: CliIO;\n}\n\n// -----------------------------------------------------------------------------\n// Stricli context + buffered process\n// -----------------------------------------------------------------------------\n\ninterface BufferedProcess extends StricliProcess {\n\treadonly stdoutBuffer: Array<string>;\n\treadonly stderrBuffer: Array<string>;\n\texitCode?: number | string | null;\n}\n\ninterface TrackedIO extends CliIO {\n\treadonly touched: () => boolean;\n\treadonly lastExitCode: () => number | null;\n}\n\ninterface DevstackCliContext extends StricliCommandContext {\n\treadonly deps: CliDeps;\n\treadonly env: Readonly<Record<string, string | undefined>>;\n\treadonly stdinIsTty: boolean;\n\treadonly io: TrackedIO;\n\treadonly process: BufferedProcess;\n}\n\nconst makeBufferedProcess = (\n\tenv: Readonly<Record<string, string | undefined>>,\n): BufferedProcess => {\n\tconst stdoutBuffer: Array<string> = [];\n\tconst stderrBuffer: Array<string> = [];\n\treturn {\n\t\tstdoutBuffer,\n\t\tstderrBuffer,\n\t\tenv,\n\t\tstdout: {\n\t\t\twrite: (str) => {\n\t\t\t\tstdoutBuffer.push(str);\n\t\t\t},\n\t\t},\n\t\tstderr: {\n\t\t\twrite: (str) => {\n\t\t\t\tstderrBuffer.push(str);\n\t\t\t},\n\t\t},\n\t};\n};\n\nconst trackIO = (io: CliIO): TrackedIO => {\n\tlet touched = false;\n\tlet lastExitCode: number | null = null;\n\treturn {\n\t\ttouched: () => touched,\n\t\tlastExitCode: () => lastExitCode,\n\t\twriteStdout: (line) =>\n\t\t\tio.writeStdout(line).pipe(\n\t\t\t\tEffect.tap(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\twriteStderr: (line) =>\n\t\t\tio.writeStderr(line).pipe(\n\t\t\t\tEffect.tap(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\tsetExitCode: (code) =>\n\t\t\tio.setExitCode(code).pipe(\n\t\t\t\tEffect.tap(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t\tlastExitCode = code;\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// Flag models\n// -----------------------------------------------------------------------------\n\ninterface IdentityFlags {\n\treadonly json?: boolean;\n\treadonly app?: string;\n\treadonly stack?: string;\n\treadonly stateDir?: string;\n\treadonly verbose?: boolean;\n}\n\ninterface ConfigFlags extends IdentityFlags {\n\treadonly config?: string;\n\treadonly network?: string;\n}\n\ninterface UpFlags extends ConfigFlags {\n\treadonly renderer?: CliRendererMode;\n}\n\ninterface DestructiveFlags extends IdentityFlags {\n\treadonly dryRun?: boolean;\n\treadonly yes?: boolean;\n\treadonly noInput?: boolean;\n}\n\ninterface ConfirmFlags extends IdentityFlags {\n\treadonly yes?: boolean;\n\treadonly noInput?: boolean;\n}\n\ninterface PruneFlags {\n\treadonly json?: boolean;\n\treadonly stateDir?: string;\n\treadonly verbose?: boolean;\n\treadonly dryRun?: boolean;\n\treadonly yes?: boolean;\n\treadonly noInput?: boolean;\n\treadonly list?: boolean;\n\treadonly all?: boolean;\n\treadonly noContainers?: boolean;\n\treadonly noNetworks?: boolean;\n\treadonly noVolumes?: boolean;\n\treadonly includeImages?: boolean;\n}\n\ninterface SnapshotSaveFlags extends ConfigFlags {\n\treadonly name?: string;\n}\n\nconst textParser = (input: string): string => input;\n\nconst stringFlag = (brief: string, placeholder: string) =>\n\t({\n\t\tkind: 'parsed',\n\t\tparse: textParser,\n\t\toptional: true,\n\t\tplaceholder,\n\t\tbrief,\n\t}) as const;\n\nconst boolFlag = (brief: string) =>\n\t({\n\t\tkind: 'boolean',\n\t\toptional: true,\n\t\tbrief,\n\t}) as const;\n\nconst identityFlagParams = {\n\tjson: boolFlag('Emit JSON envelope output'),\n\tapp: stringFlag('Override app name', 'name'),\n\tstack: stringFlag('Override stack name', 'name'),\n\tstateDir: stringFlag('Override state directory', 'path'),\n\tverbose: boolFlag('Enable more verbose logging'),\n} as const;\n\nconst configFlagParams = {\n\t...identityFlagParams,\n\tconfig: stringFlag('Override devstack.config.ts path', 'path'),\n\tnetwork: stringFlag('Override network before config import', 'name'),\n} as const;\n\nconst destructiveFlagParams = {\n\t...identityFlagParams,\n\tdryRun: boolFlag('Skip mutating effects'),\n\tyes: boolFlag('Assume yes on prompts'),\n\tnoInput: boolFlag('Forbid prompts'),\n} as const;\n\nconst globalMaintenanceFlagParams = {\n\tjson: identityFlagParams.json,\n\tstateDir: identityFlagParams.stateDir,\n\tverbose: identityFlagParams.verbose,\n} as const;\n\nconst confirmFlagParams = {\n\t...identityFlagParams,\n\tyes: boolFlag('Assume yes on prompts'),\n\tnoInput: boolFlag('Forbid prompts'),\n} as const;\n\nconst pruneFlagParams = {\n\t...globalMaintenanceFlagParams,\n\tdryRun: destructiveFlagParams.dryRun,\n\tyes: destructiveFlagParams.yes,\n\tnoInput: destructiveFlagParams.noInput,\n\tlist: boolFlag('List devstack-labelled Docker resources without pruning'),\n\tall: boolFlag('Prune every idle non-shared resource group'),\n\tnoContainers: boolFlag('Do not remove containers'),\n\tnoNetworks: boolFlag('Do not remove networks'),\n\tnoVolumes: boolFlag('Do not remove volumes'),\n\tincludeImages: boolFlag('Also remove devstack-labelled images for selected groups'),\n} as const;\n\nconst rendererParser = buildChoiceParser(['tui', 'plain', 'silent'] as const);\n\nconst outputModeFrom = (\n\tflags: Pick<IdentityFlags, 'json'>,\n\tenv: Readonly<Record<string, string | undefined>>,\n): OutputMode => (flags.json === true || env[ENV_VARS.JSON] === '1' ? 'json' : 'human');\n\nconst pruneResourcesFromFlags = (flags: PruneFlags): PruneResourceScope => ({\n\tcontainers: flags.noContainers !== true,\n\tnetworks: flags.noNetworks !== true,\n\tvolumes: flags.noVolumes !== true,\n\timages: flags.includeImages === true,\n});\n\nconst optionalEnv = (\n\tvalue: string | undefined,\n\tenv: Readonly<Record<string, string | undefined>>,\n\tkey: string,\n): string | undefined => value ?? env[key];\n\nconst makeGlobalFlags = (\n\tctx: DevstackCliContext,\n\tflags: IdentityFlags & Partial<ConfigFlags & UpFlags & DestructiveFlags>,\n\trest: ReadonlyArray<string>,\n): GlobalFlags => {\n\tconst networkRaw = optionalEnv(flags.network, ctx.env, ENV_VARS.NETWORK);\n\tlet network: string | undefined;\n\tif (networkRaw !== undefined) {\n\t\ttry {\n\t\t\tnetwork = parseDevstackNetworkName(\n\t\t\t\tnetworkRaw,\n\t\t\t\tflags.network === undefined ? ENV_VARS.NETWORK : '--network',\n\t\t\t);\n\t\t} catch (cause) {\n\t\t\tthrow cause instanceof Error\n\t\t\t\t? new CliUsageError({ message: cause.message })\n\t\t\t\t: new CliInternalError({ message: 'failed to parse network flag', cause });\n\t\t}\n\t}\n\treturn {\n\t\toutputMode: outputModeFrom(flags, ctx.env),\n\t\tapp: optionalEnv(flags.app, ctx.env, ENV_VARS.APP),\n\t\tstack: optionalEnv(flags.stack, ctx.env, ENV_VARS.STACK),\n\t\tstateDir: optionalEnv(flags.stateDir, ctx.env, ENV_VARS.STATE_DIR),\n\t\tconfigPath: optionalEnv(flags.config, ctx.env, ENV_VARS.CONFIG_PATH),\n\t\tnetwork,\n\t\trenderer: flags.renderer,\n\t\tdryRun: flags.dryRun === true,\n\t\tconfirm: {\n\t\t\tassumeYes: flags.yes === true,\n\t\t\tforbidPrompt: flags.noInput === true || ctx.env[ENV_VARS.NO_INPUT] === '1',\n\t\t\tstdinIsTty: ctx.stdinIsTty,\n\t\t},\n\t\tschemaEmit: false,\n\t\tverbose: flags.verbose === true,\n\t\thelp: false,\n\t\tversion: false,\n\t\trest,\n\t};\n};\n\nconst setNetworkEnv = (flags: GlobalFlags): Effect.Effect<void> =>\n\tflags.network === undefined\n\t\t? Effect.void\n\t\t: Effect.sync(() => {\n\t\t\t\tprocess.env[ENV_VARS.NETWORK] = flags.network;\n\t\t\t});\n\n// -----------------------------------------------------------------------------\n// Command execution helpers\n// -----------------------------------------------------------------------------\n\nconst runCommandEffect = async (\n\tctx: DevstackCliContext,\n\tcommand: string,\n\tflags: GlobalFlags,\n\teffect: Effect.Effect<CommandResult, CliError>,\n): Promise<void> => {\n\tconst program = setNetworkEnv(flags).pipe(\n\t\tEffect.andThen(effect),\n\t\tEffect.catch((error: CliError) =>\n\t\t\temitFailure(ctx.io, flags.outputMode, {\n\t\t\t\tcommand,\n\t\t\t\telapsedMs: 0,\n\t\t\t\terror,\n\t\t\t}).pipe(Effect.as({ exitCode: exitCodeFor(error) })),\n\t\t),\n\t\tEffect.catchCause((cause) =>\n\t\t\temitFailure(ctx.io, flags.outputMode, {\n\t\t\t\tcommand,\n\t\t\t\telapsedMs: 0,\n\t\t\t\terror: new CliInternalError({ message: 'unexpected internal failure' }),\n\t\t\t\tcause,\n\t\t\t}).pipe(Effect.as({ exitCode: 70 })),\n\t\t),\n\t);\n\tconst result = await Effect.runPromise(program);\n\tif (ctx.io.lastExitCode() === null) {\n\t\tawait Effect.runPromise(ctx.io.setExitCode(result.exitCode));\n\t}\n};\n\nconst runWithFlags = async (\n\tctx: DevstackCliContext,\n\tcommand: string,\n\trawFlags: IdentityFlags & Partial<ConfigFlags & UpFlags & DestructiveFlags>,\n\trest: ReadonlyArray<string>,\n\teffect: (flags: GlobalFlags) => Effect.Effect<CommandResult, CliError>,\n): Promise<void> => {\n\tlet flags: GlobalFlags;\n\ttry {\n\t\tflags = makeGlobalFlags(ctx, rawFlags, rest);\n\t} catch (cause) {\n\t\tconst error =\n\t\t\tcause instanceof CliUsageError\n\t\t\t\t? cause\n\t\t\t\t: new CliInternalError({ message: 'failed to resolve CLI flags', cause });\n\t\tconst mode = outputModeFrom(rawFlags, ctx.env);\n\t\tawait Effect.runPromise(\n\t\t\temitFailure(ctx.io, mode, {\n\t\t\t\tcommand,\n\t\t\t\telapsedMs: 0,\n\t\t\t\terror,\n\t\t\t}),\n\t\t);\n\t\treturn;\n\t}\n\tawait runCommandEffect(ctx, command, flags, effect(flags));\n};\n\nconst requiredPositional = (placeholder: string, brief: string) =>\n\t({\n\t\tparse: textParser,\n\t\tplaceholder,\n\t\tbrief,\n\t}) as const;\n\nconst optionalPositional = (placeholder: string, brief: string) =>\n\t({\n\t\tparse: textParser,\n\t\tplaceholder,\n\t\tbrief,\n\t\toptional: true as const,\n\t}) as const;\n\n// -----------------------------------------------------------------------------\n// Commands\n// -----------------------------------------------------------------------------\n\nconst upCommand = buildCommand<UpFlags, [], DevstackCliContext>({\n\tparameters: {\n\t\tflags: {\n\t\t\t...configFlagParams,\n\t\t\trenderer: {\n\t\t\t\tkind: 'parsed',\n\t\t\t\tparse: rendererParser,\n\t\t\t\toptional: true,\n\t\t\t\tplaceholder: 'tui|plain|silent',\n\t\t\t\tbrief: 'Select the attached renderer',\n\t\t\t},\n\t\t},\n\t},\n\tdocs: {\n\t\tbrief: 'Boot a stack and stay attached until interrupted',\n\t},\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'up', flags, [], (global) => this.deps.up.run(global));\n\t},\n});\n\nconst applyCommand = buildCommand<ConfigFlags, [], DevstackCliContext>({\n\tparameters: { flags: configFlagParams },\n\tdocs: {\n\t\tbrief: 'Reconcile a live stack or run one-shot setup',\n\t},\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'apply', flags, [], (global) => this.deps.apply.run(global));\n\t},\n});\n\nconst statusCommand = buildCommand<IdentityFlags, [], DevstackCliContext>({\n\tparameters: { flags: identityFlagParams },\n\tdocs: { brief: 'Show the persisted stack projection' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'status', flags, [], (global) =>\n\t\t\trunStatus(this.deps.status, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst doctorCommand = buildCommand<IdentityFlags, [], DevstackCliContext>({\n\tparameters: { flags: identityFlagParams },\n\tdocs: { brief: 'Run host and stack preflight checks' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'doctor', flags, [], (global) =>\n\t\t\trunDoctor(this.deps.doctor, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst configCommand = buildCommand<ConfigFlags, [], DevstackCliContext>({\n\tparameters: { flags: configFlagParams },\n\tdocs: { brief: 'Print resolved config inputs' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'config', flags, [], (global) =>\n\t\t\trunConfig(this.deps.config, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst schemaCommand = buildCommand<Pick<IdentityFlags, 'json'>, [], DevstackCliContext>({\n\tparameters: { flags: { json: identityFlagParams.json } },\n\tdocs: { brief: 'Emit the CLI schema' },\n\tfunc: function (flags) {\n\t\tconst mode = outputModeFrom(flags, this.env);\n\t\treturn Effect.runPromise(\n\t\t\tthis.io\n\t\t\t\t.writeStdout(JSON.stringify({ ...commandSchema(), outputMode: mode }))\n\t\t\t\t.pipe(Effect.andThen(this.io.setExitCode(0))),\n\t\t);\n\t},\n});\n\nconst snapshotSaveCommand = buildCommand<\n\tSnapshotSaveFlags,\n\t[string | undefined],\n\tDevstackCliContext\n>({\n\tparameters: {\n\t\tflags: {\n\t\t\t...configFlagParams,\n\t\t\tname: stringFlag('Human-readable snapshot name', 'name'),\n\t\t},\n\t\tpositional: { kind: 'tuple', parameters: [optionalPositional('name', 'snapshot name')] },\n\t},\n\tdocs: { brief: 'Capture a snapshot' },\n\tfunc: function (flags, snapshotName) {\n\t\tconst rest = [\n\t\t\t'save',\n\t\t\t...(snapshotName === undefined ? [] : [snapshotName]),\n\t\t\t...(flags.name === undefined ? [] : ['--name', flags.name]),\n\t\t];\n\t\treturn runWithFlags(this, 'snapshot save', flags, rest, (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotRestoreCommand = buildCommand<ConfirmFlags, [string], DevstackCliContext>({\n\tparameters: {\n\t\tflags: confirmFlagParams,\n\t\tpositional: {\n\t\t\tkind: 'tuple',\n\t\t\tparameters: [requiredPositional('name-or-id', 'snapshot name or id')],\n\t\t},\n\t},\n\tdocs: { brief: 'Restore a snapshot' },\n\tfunc: function (flags, snapshotRef) {\n\t\treturn runWithFlags(this, 'snapshot restore', flags, ['restore', snapshotRef], (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotListCommand = buildCommand<IdentityFlags, [], DevstackCliContext>({\n\tparameters: { flags: identityFlagParams },\n\tdocs: { brief: 'List snapshots' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'snapshot list', flags, ['list'], (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotDeleteCommand = buildCommand<ConfirmFlags, [string], DevstackCliContext>({\n\tparameters: {\n\t\tflags: confirmFlagParams,\n\t\tpositional: {\n\t\t\tkind: 'tuple',\n\t\t\tparameters: [requiredPositional('name-or-id', 'snapshot name or id')],\n\t\t},\n\t},\n\tdocs: { brief: 'Delete a snapshot' },\n\tfunc: function (flags, snapshotRef) {\n\t\treturn runWithFlags(this, 'snapshot delete', flags, ['delete', snapshotRef], (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotCommands = buildRouteMap({\n\troutes: {\n\t\tsave: snapshotSaveCommand,\n\t\trestore: snapshotRestoreCommand,\n\t\tlist: snapshotListCommand,\n\t\tdelete: snapshotDeleteCommand,\n\t},\n\tdocs: { brief: 'Capture, restore, list, or delete stack snapshots' },\n});\n\nconst pruneCommand = buildCommand<PruneFlags, [], DevstackCliContext>({\n\tparameters: { flags: pruneFlagParams },\n\tdocs: { brief: 'Inventory and prune devstack-labelled Docker resources' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'prune', flags, [], (global) =>\n\t\t\trunPrune(\n\t\t\t\tthis.deps.prune,\n\t\t\t\t{ flags: global, io: this.io },\n\t\t\t\t{\n\t\t\t\t\tmode: flags.list === true ? 'list' : flags.all === true ? 'all' : 'auto',\n\t\t\t\t\tresources: pruneResourcesFromFlags(flags),\n\t\t\t\t},\n\t\t\t),\n\t\t);\n\t},\n});\n\nconst wipeCommand = buildCommand<DestructiveFlags, [], DevstackCliContext>({\n\tparameters: { flags: destructiveFlagParams },\n\tdocs: { brief: 'Destroy all state for the selected stack' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'wipe', flags, [], (global) =>\n\t\t\trunWipe(this.deps.wipe, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst root = buildRouteMap({\n\troutes: {\n\t\tup: upCommand,\n\t\tapply: applyCommand,\n\t\tstatus: statusCommand,\n\t\tdoctor: doctorCommand,\n\t\tconfig: configCommand,\n\t\tschema: schemaCommand,\n\t\tsnapshot: snapshotCommands,\n\t\tprune: pruneCommand,\n\t\twipe: wipeCommand,\n\t},\n\tdocs: {\n\t\tbrief: 'Sui development stack CLI',\n\t},\n});\n\nconst app = buildApplication(root, {\n\tname: 'devstack',\n\tversionInfo: { currentVersion: '0.0.0' },\n\tscanner: { caseStyle: 'allow-kebab-for-camel' },\n\tdocumentation: {\n\t\tcaseStyle: 'convert-camel-to-kebab',\n\t\tdisableAnsiColor: true,\n\t\tonlyRequiredInUsageLine: true,\n\t},\n\tlocalization: {\n\t\tloadText: () => ({\n\t\t\t...text_en,\n\t\t\texceptionWhileParsingArguments: (error) =>\n\t\t\t\terror instanceof Error ? error.message : String(error),\n\t\t}),\n\t},\n});\n\nconst jsonRequested = (\n\targv: ReadonlyArray<string>,\n\tenv: Readonly<Record<string, string | undefined>>,\n): boolean => env[ENV_VARS.JSON] === '1' || argv.includes('--json');\n\nconst normalizeStricliExitCode = (code: number | string | null | undefined): number => {\n\tif (typeof code === 'number' && code !== 0) return 64;\n\treturn 0;\n};\n\nconst flushBufferedProcess = (\n\tprocess: BufferedProcess,\n\tio: CliIO,\n\targv: ReadonlyArray<string>,\n\tenv: Readonly<Record<string, string | undefined>>,\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst exitCode = normalizeStricliExitCode(process.exitCode);\n\t\tconst stdout = process.stdoutBuffer.join('');\n\t\tconst stderr = process.stderrBuffer.join('').trim();\n\t\tif (exitCode !== 0 && jsonRequested(argv, env)) {\n\t\t\tyield* emitFailure(io, 'json', {\n\t\t\t\tcommand: '(parse)',\n\t\t\t\telapsedMs: 0,\n\t\t\t\terror: new CliUsageError({\n\t\t\t\t\tmessage: stderr.length > 0 ? stderr : 'invalid command line',\n\t\t\t\t}),\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tif (stdout.length > 0)\n\t\t\tyield* io.writeStdout(stdout.endsWith('\\n') ? stdout.slice(0, -1) : stdout);\n\t\tif (stderr.length > 0) yield* io.writeStderr(stderr);\n\t\tyield* io.setExitCode(exitCode);\n\t});\n\nexport const dispatch = (deps: CliDeps, dispatchEnv: DispatchEnv): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst io = trackIO(dispatchEnv.io ?? nodeProcessIO);\n\t\tconst process = makeBufferedProcess(dispatchEnv.env);\n\t\tconst ctx: DevstackCliContext = {\n\t\t\tprocess,\n\t\t\tdeps,\n\t\t\tenv: dispatchEnv.env,\n\t\t\tstdinIsTty: dispatchEnv.stdinIsTty,\n\t\t\tio,\n\t\t};\n\t\tyield* Effect.tryPromise({\n\t\t\ttry: () => runStricli(app, dispatchEnv.argv, ctx),\n\t\t\tcatch: (cause) => new CliInternalError({ message: 'CLI dispatcher failed', cause }),\n\t\t}).pipe(\n\t\t\tEffect.catch((error: CliError) =>\n\t\t\t\temitFailure(io, jsonRequested(dispatchEnv.argv, dispatchEnv.env) ? 'json' : 'human', {\n\t\t\t\t\tcommand: '(dispatch)',\n\t\t\t\t\telapsedMs: 0,\n\t\t\t\t\terror,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t\tif (!io.touched()) {\n\t\t\tyield* flushBufferedProcess(process, io, dispatchEnv.argv, dispatchEnv.env);\n\t\t}\n\t});\n\n// -----------------------------------------------------------------------------\n// Re-exports\n// -----------------------------------------------------------------------------\n\nexport type { CliIO } from './output.ts';\nexport type { GlobalFlags } from './flags.ts';\nexport {\n\tCOMMAND_TREE,\n\tcommandSchema,\n\tformatCommandHelp,\n\tVERBS,\n\ttype Verb,\n} from './command-tree.ts';\nexport type { Envelope, EnvelopeError } from './envelope.ts';\nexport {\n\tENVELOPE_SCHEMA_VERSION,\n\tfailureEnvelope,\n\tstreamingEvent,\n\tsuccessEnvelope,\n\ttype StreamingEvent,\n} from './envelope.ts';\nexport { ExitCode, exitCodeName } from './sysexits.ts';\nexport {\n\ttype CliError,\n\tCliAlreadyReportedError,\n\tCliConfigInvalidError,\n\tCliConfigNotFoundError,\n\tCliConfirmDeclinedError,\n\tCliConfirmRequiredError,\n\tCliInternalError,\n\tCliSnapshotNotFoundError,\n\tCliSupervisorLiveError,\n\tCliUnavailableError,\n\tCliUsageError,\n} from './errors.ts';\n"],"mappings":";;;;;;;;;;;;;;;;AAyFA,MAAM,uBACL,QACqB;CACrB,MAAM,eAA8B,EAAE;CACtC,MAAM,eAA8B,EAAE;AACtC,QAAO;EACN;EACA;EACA;EACA,QAAQ,EACP,QAAQ,QAAQ;AACf,gBAAa,KAAK,IAAI;KAEvB;EACD,QAAQ,EACP,QAAQ,QAAQ;AACf,gBAAa,KAAK,IAAI;KAEvB;EACD;;AAGF,MAAM,WAAW,OAAyB;CACzC,IAAI,UAAU;CACd,IAAI,eAA8B;AAClC,QAAO;EACN,eAAe;EACf,oBAAoB;EACpB,cAAc,SACb,GAAG,YAAY,KAAK,CAAC,KACpB,OAAO,UACN,OAAO,WAAW;AACjB,aAAU;IACT,CACF,CACD;EACF,cAAc,SACb,GAAG,YAAY,KAAK,CAAC,KACpB,OAAO,UACN,OAAO,WAAW;AACjB,aAAU;IACT,CACF,CACD;EACF,cAAc,SACb,GAAG,YAAY,KAAK,CAAC,KACpB,OAAO,UACN,OAAO,WAAW;AACjB,aAAU;AACV,kBAAe;IACd,CACF,CACD;EACF;;AAsDF,MAAM,cAAc,UAA0B;AAE9C,MAAM,cAAc,OAAe,iBACjC;CACA,MAAM;CACN,OAAO;CACP,UAAU;CACV;CACA;CACA;AAEF,MAAM,YAAY,WAChB;CACA,MAAM;CACN,UAAU;CACV;CACA;AAEF,MAAM,qBAAqB;CAC1B,MAAM,SAAS,4BAA4B;CAC3C,KAAK,WAAW,qBAAqB,OAAO;CAC5C,OAAO,WAAW,uBAAuB,OAAO;CAChD,UAAU,WAAW,4BAA4B,OAAO;CACxD,SAAS,SAAS,8BAA8B;CAChD;AAED,MAAM,mBAAmB;CACxB,GAAG;CACH,QAAQ,WAAW,oCAAoC,OAAO;CAC9D,SAAS,WAAW,yCAAyC,OAAO;CACpE;AAED,MAAM,wBAAwB;CAC7B,GAAG;CACH,QAAQ,SAAS,wBAAwB;CACzC,KAAK,SAAS,wBAAwB;CACtC,SAAS,SAAS,iBAAiB;CACnC;AAED,MAAM,8BAA8B;CACnC,MAAM,mBAAmB;CACzB,UAAU,mBAAmB;CAC7B,SAAS,mBAAmB;CAC5B;AAED,MAAM,oBAAoB;CACzB,GAAG;CACH,KAAK,SAAS,wBAAwB;CACtC,SAAS,SAAS,iBAAiB;CACnC;AAED,MAAM,kBAAkB;CACvB,GAAG;CACH,QAAQ,sBAAsB;CAC9B,KAAK,sBAAsB;CAC3B,SAAS,sBAAsB;CAC/B,MAAM,SAAS,0DAA0D;CACzE,KAAK,SAAS,6CAA6C;CAC3D,cAAc,SAAS,2BAA2B;CAClD,YAAY,SAAS,yBAAyB;CAC9C,WAAW,SAAS,wBAAwB;CAC5C,eAAe,SAAS,2DAA2D;CACnF;AAED,MAAM,iBAAiB,kBAAkB;CAAC;CAAO;CAAS;CAAS,CAAU;AAE7E,MAAM,kBACL,OACA,QACiB,MAAM,SAAS,QAAQ,IAAI,SAAS,UAAU,MAAM,SAAS;AAE/E,MAAM,2BAA2B,WAA2C;CAC3E,YAAY,MAAM,iBAAiB;CACnC,UAAU,MAAM,eAAe;CAC/B,SAAS,MAAM,cAAc;CAC7B,QAAQ,MAAM,kBAAkB;CAChC;AAED,MAAM,eACL,OACA,KACA,QACwB,SAAS,IAAI;AAEtC,MAAM,mBACL,KACA,OACA,SACiB;CACjB,MAAM,aAAa,YAAY,MAAM,SAAS,IAAI,KAAK,SAAS,QAAQ;CACxE,IAAI;AACJ,KAAI,eAAe,KAAA,EAClB,KAAI;AACH,YAAU,yBACT,YACA,MAAM,YAAY,KAAA,IAAY,SAAS,UAAU,YACjD;UACO,OAAO;AACf,QAAM,iBAAiB,QACpB,IAAI,cAAc,EAAE,SAAS,MAAM,SAAS,CAAC,GAC7C,IAAI,iBAAiB;GAAE,SAAS;GAAgC;GAAO,CAAC;;AAG7E,QAAO;EACN,YAAY,eAAe,OAAO,IAAI,IAAI;EAC1C,KAAK,YAAY,MAAM,KAAK,IAAI,KAAK,SAAS,IAAI;EAClD,OAAO,YAAY,MAAM,OAAO,IAAI,KAAK,SAAS,MAAM;EACxD,UAAU,YAAY,MAAM,UAAU,IAAI,KAAK,SAAS,UAAU;EAClE,YAAY,YAAY,MAAM,QAAQ,IAAI,KAAK,SAAS,YAAY;EACpE;EACA,UAAU,MAAM;EAChB,QAAQ,MAAM,WAAW;EACzB,SAAS;GACR,WAAW,MAAM,QAAQ;GACzB,cAAc,MAAM,YAAY,QAAQ,IAAI,IAAI,SAAS,cAAc;GACvE,YAAY,IAAI;GAChB;EACD,YAAY;EACZ,SAAS,MAAM,YAAY;EAC3B,MAAM;EACN,SAAS;EACT;EACA;;AAGF,MAAM,iBAAiB,UACtB,MAAM,YAAY,KAAA,IACf,OAAO,OACP,OAAO,WAAW;AAClB,SAAQ,IAAI,SAAS,WAAW,MAAM;EACrC;AAML,MAAM,mBAAmB,OACxB,KACA,SACA,OACA,WACmB;CACnB,MAAM,UAAU,cAAc,MAAM,CAAC,KACpC,OAAO,QAAQ,OAAO,EACtB,OAAO,OAAO,UACb,YAAY,IAAI,IAAI,MAAM,YAAY;EACrC;EACA,WAAW;EACX;EACA,CAAC,CAAC,KAAK,OAAO,GAAG,EAAE,UAAU,YAAY,MAAM,EAAE,CAAC,CAAC,CACpD,EACD,OAAO,YAAY,UAClB,YAAY,IAAI,IAAI,MAAM,YAAY;EACrC;EACA,WAAW;EACX,OAAO,IAAI,iBAAiB,EAAE,SAAS,+BAA+B,CAAC;EACvE;EACA,CAAC,CAAC,KAAK,OAAO,GAAG,EAAE,UAAU,IAAI,CAAC,CAAC,CACpC,CACD;CACD,MAAM,SAAS,MAAM,OAAO,WAAW,QAAQ;AAC/C,KAAI,IAAI,GAAG,cAAc,KAAK,KAC7B,OAAM,OAAO,WAAW,IAAI,GAAG,YAAY,OAAO,SAAS,CAAC;;AAI9D,MAAM,eAAe,OACpB,KACA,SACA,UACA,MACA,WACmB;CACnB,IAAI;AACJ,KAAI;AACH,UAAQ,gBAAgB,KAAK,UAAU,KAAK;UACpC,OAAO;EACf,MAAM,QACL,iBAAiB,gBACd,QACA,IAAI,iBAAiB;GAAE,SAAS;GAA+B;GAAO,CAAC;EAC3E,MAAM,OAAO,eAAe,UAAU,IAAI,IAAI;AAC9C,QAAM,OAAO,WACZ,YAAY,IAAI,IAAI,MAAM;GACzB;GACA,WAAW;GACX;GACA,CAAC,CACF;AACD;;AAED,OAAM,iBAAiB,KAAK,SAAS,OAAO,OAAO,MAAM,CAAC;;AAG3D,MAAM,sBAAsB,aAAqB,WAC/C;CACA,OAAO;CACP;CACA;CACA;AAEF,MAAM,sBAAsB,aAAqB,WAC/C;CACA,OAAO;CACP;CACA;CACA,UAAU;CACV;AAyMF,MAAM,MAAM,iBAjBC,cAAc;CAC1B,QAAQ;EACP,IApLgB,aAA8C;GAC/D,YAAY,EACX,OAAO;IACN,GAAG;IACH,UAAU;KACT,MAAM;KACN,OAAO;KACP,UAAU;KACV,aAAa;KACb,OAAO;KACP;IACD,EACD;GACD,MAAM,EACL,OAAO,oDACP;GACD,MAAM,SAAU,OAAO;AACtB,WAAO,aAAa,MAAM,MAAM,OAAO,EAAE,GAAG,WAAW,KAAK,KAAK,GAAG,IAAI,OAAO,CAAC;;GAEjF,CAiKc;EACb,OAhKmB,aAAkD;GACtE,YAAY,EAAE,OAAO,kBAAkB;GACvC,MAAM,EACL,OAAO,gDACP;GACD,MAAM,SAAU,OAAO;AACtB,WAAO,aAAa,MAAM,SAAS,OAAO,EAAE,GAAG,WAAW,KAAK,KAAK,MAAM,IAAI,OAAO,CAAC;;GAEvF,CAwJoB;EACnB,QAvJoB,aAAoD;GACzE,YAAY,EAAE,OAAO,oBAAoB;GACzC,MAAM,EAAE,OAAO,uCAAuC;GACtD,MAAM,SAAU,OAAO;AACtB,WAAO,aAAa,MAAM,UAAU,OAAO,EAAE,GAAG,WAC/C,UAAU,KAAK,KAAK,QAAQ;KAAE,OAAO;KAAQ,IAAI,KAAK;KAAI,CAAC,CAC3D;;GAEF,CA+IsB;EACrB,QA9IoB,aAAoD;GACzE,YAAY,EAAE,OAAO,oBAAoB;GACzC,MAAM,EAAE,OAAO,uCAAuC;GACtD,MAAM,SAAU,OAAO;AACtB,WAAO,aAAa,MAAM,UAAU,OAAO,EAAE,GAAG,WAC/C,UAAU,KAAK,KAAK,QAAQ;KAAE,OAAO;KAAQ,IAAI,KAAK;KAAI,CAAC,CAC3D;;GAEF,CAsIsB;EACrB,QArIoB,aAAkD;GACvE,YAAY,EAAE,OAAO,kBAAkB;GACvC,MAAM,EAAE,OAAO,gCAAgC;GAC/C,MAAM,SAAU,OAAO;AACtB,WAAO,aAAa,MAAM,UAAU,OAAO,EAAE,GAAG,WAC/C,UAAU,KAAK,KAAK,QAAQ;KAAE,OAAO;KAAQ,IAAI,KAAK;KAAI,CAAC,CAC3D;;GAEF,CA6HsB;EACrB,QA5HoB,aAAkE;GACvF,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,MAAM,EAAE;GACxD,MAAM,EAAE,OAAO,uBAAuB;GACtC,MAAM,SAAU,OAAO;IACtB,MAAM,OAAO,eAAe,OAAO,KAAK,IAAI;AAC5C,WAAO,OAAO,WACb,KAAK,GACH,YAAY,KAAK,UAAU;KAAE,GAAG,eAAe;KAAE,YAAY;KAAM,CAAC,CAAC,CACrE,KAAK,OAAO,QAAQ,KAAK,GAAG,YAAY,EAAE,CAAC,CAAC,CAC9C;;GAEF,CAiHsB;EACrB,UA7CuB,cAAc;GACtC,QAAQ;IACP,MArE0B,aAI1B;KACD,YAAY;MACX,OAAO;OACN,GAAG;OACH,MAAM,WAAW,gCAAgC,OAAO;OACxD;MACD,YAAY;OAAE,MAAM;OAAS,YAAY,CAAC,mBAAmB,QAAQ,gBAAgB,CAAC;OAAE;MACxF;KACD,MAAM,EAAE,OAAO,sBAAsB;KACrC,MAAM,SAAU,OAAO,cAAc;MACpC,MAAM,OAAO;OACZ;OACA,GAAI,iBAAiB,KAAA,IAAY,EAAE,GAAG,CAAC,aAAa;OACpD,GAAI,MAAM,SAAS,KAAA,IAAY,EAAE,GAAG,CAAC,UAAU,MAAM,KAAK;OAC1D;AACD,aAAO,aAAa,MAAM,iBAAiB,OAAO,OAAO,WACxD,YAAY,KAAK,KAAK,UAAU;OAAE,OAAO;OAAQ,IAAI,KAAK;OAAI,CAAC,CAC/D;;KAEF,CA8C0B;IACzB,SA7C6B,aAAyD;KACvF,YAAY;MACX,OAAO;MACP,YAAY;OACX,MAAM;OACN,YAAY,CAAC,mBAAmB,cAAc,sBAAsB,CAAC;OACrE;MACD;KACD,MAAM,EAAE,OAAO,sBAAsB;KACrC,MAAM,SAAU,OAAO,aAAa;AACnC,aAAO,aAAa,MAAM,oBAAoB,OAAO,CAAC,WAAW,YAAY,GAAG,WAC/E,YAAY,KAAK,KAAK,UAAU;OAAE,OAAO;OAAQ,IAAI,KAAK;OAAI,CAAC,CAC/D;;KAEF,CA+BgC;IAC/B,MA9B0B,aAAoD;KAC/E,YAAY,EAAE,OAAO,oBAAoB;KACzC,MAAM,EAAE,OAAO,kBAAkB;KACjC,MAAM,SAAU,OAAO;AACtB,aAAO,aAAa,MAAM,iBAAiB,OAAO,CAAC,OAAO,GAAG,WAC5D,YAAY,KAAK,KAAK,UAAU;OAAE,OAAO;OAAQ,IAAI,KAAK;OAAI,CAAC,CAC/D;;KAEF,CAsB0B;IACzB,QArB4B,aAAyD;KACtF,YAAY;MACX,OAAO;MACP,YAAY;OACX,MAAM;OACN,YAAY,CAAC,mBAAmB,cAAc,sBAAsB,CAAC;OACrE;MACD;KACD,MAAM,EAAE,OAAO,qBAAqB;KACpC,MAAM,SAAU,OAAO,aAAa;AACnC,aAAO,aAAa,MAAM,mBAAmB,OAAO,CAAC,UAAU,YAAY,GAAG,WAC7E,YAAY,KAAK,KAAK,UAAU;OAAE,OAAO;OAAQ,IAAI,KAAK;OAAI,CAAC,CAC/D;;KAEF,CAO8B;IAC7B;GACD,MAAM,EAAE,OAAO,qDAAqD;GACpE,CAqC2B;EAC1B,OApCmB,aAAiD;GACrE,YAAY,EAAE,OAAO,iBAAiB;GACtC,MAAM,EAAE,OAAO,0DAA0D;GACzE,MAAM,SAAU,OAAO;AACtB,WAAO,aAAa,MAAM,SAAS,OAAO,EAAE,GAAG,WAC9C,SACC,KAAK,KAAK,OACV;KAAE,OAAO;KAAQ,IAAI,KAAK;KAAI,EAC9B;KACC,MAAM,MAAM,SAAS,OAAO,SAAS,MAAM,QAAQ,OAAO,QAAQ;KAClE,WAAW,wBAAwB,MAAM;KACzC,CACD,CACD;;GAEF,CAqBoB;EACnB,MApBkB,aAAuD;GAC1E,YAAY,EAAE,OAAO,uBAAuB;GAC5C,MAAM,EAAE,OAAO,4CAA4C;GAC3D,MAAM,SAAU,OAAO;AACtB,WAAO,aAAa,MAAM,QAAQ,OAAO,EAAE,GAAG,WAC7C,QAAQ,KAAK,KAAK,MAAM;KAAE,OAAO;KAAQ,IAAI,KAAK;KAAI,CAAC,CACvD;;GAEF,CAYkB;EACjB;CACD,MAAM,EACL,OAAO,6BACP;CACD,CAEgC,EAAE;CAClC,MAAM;CACN,aAAa,EAAE,gBAAgB,SAAS;CACxC,SAAS,EAAE,WAAW,yBAAyB;CAC/C,eAAe;EACd,WAAW;EACX,kBAAkB;EAClB,yBAAyB;EACzB;CACD,cAAc,EACb,iBAAiB;EAChB,GAAG;EACH,iCAAiC,UAChC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;EACvD,GACD;CACD,CAAC;AAEF,MAAM,iBACL,MACA,QACa,IAAI,SAAS,UAAU,OAAO,KAAK,SAAS,SAAS;AAEnE,MAAM,4BAA4B,SAAqD;AACtF,KAAI,OAAO,SAAS,YAAY,SAAS,EAAG,QAAO;AACnD,QAAO;;AAGR,MAAM,wBACL,SACA,IACA,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,yBAAyB,QAAQ,SAAS;CAC3D,MAAM,SAAS,QAAQ,aAAa,KAAK,GAAG;CAC5C,MAAM,SAAS,QAAQ,aAAa,KAAK,GAAG,CAAC,MAAM;AACnD,KAAI,aAAa,KAAK,cAAc,MAAM,IAAI,EAAE;AAC/C,SAAO,YAAY,IAAI,QAAQ;GAC9B,SAAS;GACT,WAAW;GACX,OAAO,IAAI,cAAc,EACxB,SAAS,OAAO,SAAS,IAAI,SAAS,wBACtC,CAAC;GACF,CAAC;AACF;;AAED,KAAI,OAAO,SAAS,EACnB,QAAO,GAAG,YAAY,OAAO,SAAS,KAAK,GAAG,OAAO,MAAM,GAAG,GAAG,GAAG,OAAO;AAC5E,KAAI,OAAO,SAAS,EAAG,QAAO,GAAG,YAAY,OAAO;AACpD,QAAO,GAAG,YAAY,SAAS;EAC9B;AAEH,MAAa,YAAY,MAAe,gBACvC,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,QAAQ,YAAY,MAAM,cAAc;CACnD,MAAM,UAAU,oBAAoB,YAAY,IAAI;CACpD,MAAM,MAA0B;EAC/B;EACA;EACA,KAAK,YAAY;EACjB,YAAY,YAAY;EACxB;EACA;AACD,QAAO,OAAO,WAAW;EACxB,WAAWA,IAAW,KAAK,YAAY,MAAM,IAAI;EACjD,QAAQ,UAAU,IAAI,iBAAiB;GAAE,SAAS;GAAyB;GAAO,CAAC;EACnF,CAAC,CAAC,KACF,OAAO,OAAO,UACb,YAAY,IAAI,cAAc,YAAY,MAAM,YAAY,IAAI,GAAG,SAAS,SAAS;EACpF,SAAS;EACT,WAAW;EACX;EACA,CAAC,CACF,CACD;AACD,KAAI,CAAC,GAAG,SAAS,CAChB,QAAO,qBAAqB,SAAS,IAAI,YAAY,MAAM,YAAY,IAAI;EAE3E"}
+{"version":3,"file":"index.mjs","names":["runStricli"],"sources":["../../../src/surfaces/cli/index.ts"],"sourcesContent":["// CLI surface — top-level entry point.\n//\n// The public CLI is intentionally small: `up` is the attached operator\n// surface, `apply` is live-aware reconcile (publish to `up` when it is\n// running, one-shot otherwise), and every other command is offline/direct.\n\nimport {\n\tbuildApplication,\n\tbuildChoiceParser,\n\tbuildCommand,\n\tbuildRouteMap,\n\trun as runStricli,\n\ttext_en,\n\ttype CommandContext as StricliCommandContext,\n\ttype StricliProcess,\n} from '@stricli/core';\nimport { Effect, type Scope } from 'effect';\nimport { readFileSync } from 'node:fs';\n\nimport { commandSchema } from './command-tree.ts';\nimport { type CliError, CliInternalError, CliUsageError, exitCodeFor } from './errors.ts';\nimport { type CliRendererMode, ENV_VARS, type GlobalFlags, type OutputMode } from './flags.ts';\nimport { ExitCode } from './sysexits.ts';\nimport { parseDevstackNetworkName } from '../../api/inference-network.ts';\nimport { type CliIO, emitFailure, emitSuccess, nodeProcessIO } from './output.ts';\nimport {\n\ttype CommandResult,\n\ttype ConfigDeps,\n\ttype DoctorDeps,\n\ttype PruneDeps,\n\ttype PruneResourceScope,\n\ttype SnapshotDeps,\n\ttype StatusDeps,\n\ttype WipeDeps,\n\trunConfig,\n\trunDoctor,\n\trunPrune,\n\trunSnapshot,\n\trunStatus,\n\trunWipe,\n} from './commands/index.ts';\n\nconst readPackageVersion = (): string => {\n\tconst raw = readFileSync(new URL('../../../package.json', import.meta.url), 'utf8');\n\tconst pkg = JSON.parse(raw) as { readonly version?: unknown };\n\tif (typeof pkg.version !== 'string') {\n\t\tthrow new Error('devstack package.json is missing a string version');\n\t}\n\treturn pkg.version;\n};\n\n// -----------------------------------------------------------------------------\n// Deps bundle\n// -----------------------------------------------------------------------------\n\nexport interface LifecycleCommandDeps {\n\treadonly run: (flags: GlobalFlags) => Effect.Effect<CommandResult, CliError>;\n}\n\nexport interface CliDeps {\n\treadonly up: LifecycleCommandDeps;\n\treadonly apply: LifecycleCommandDeps;\n\treadonly status: StatusDeps;\n\treadonly snapshot: SnapshotDeps;\n\treadonly prune: PruneDeps;\n\treadonly doctor: DoctorDeps;\n\treadonly config: ConfigDeps;\n\treadonly wipe: WipeDeps;\n}\n\nexport interface DispatchEnv {\n\treadonly argv: ReadonlyArray<string>;\n\treadonly env: Readonly<Record<string, string | undefined>>;\n\treadonly stdinIsTty: boolean;\n\treadonly io?: CliIO;\n}\n\n// -----------------------------------------------------------------------------\n// Stricli context + buffered process\n// -----------------------------------------------------------------------------\n\ninterface BufferedProcess extends StricliProcess {\n\treadonly stdoutBuffer: Array<string>;\n\treadonly stderrBuffer: Array<string>;\n\texitCode?: number | string | null;\n}\n\ninterface TrackedIO extends CliIO {\n\treadonly touched: () => boolean;\n\treadonly lastExitCode: () => number | null;\n}\n\ninterface DevstackCliContext extends StricliCommandContext {\n\treadonly deps: CliDeps;\n\treadonly env: Readonly<Record<string, string | undefined>>;\n\treadonly stdinIsTty: boolean;\n\treadonly io: TrackedIO;\n\treadonly process: BufferedProcess;\n}\n\nconst makeBufferedProcess = (\n\tenv: Readonly<Record<string, string | undefined>>,\n): BufferedProcess => {\n\tconst stdoutBuffer: Array<string> = [];\n\tconst stderrBuffer: Array<string> = [];\n\treturn {\n\t\tstdoutBuffer,\n\t\tstderrBuffer,\n\t\tenv,\n\t\tstdout: {\n\t\t\twrite: (str) => {\n\t\t\t\tstdoutBuffer.push(str);\n\t\t\t},\n\t\t},\n\t\tstderr: {\n\t\t\twrite: (str) => {\n\t\t\t\tstderrBuffer.push(str);\n\t\t\t},\n\t\t},\n\t};\n};\n\nconst trackIO = (io: CliIO): TrackedIO => {\n\tlet touched = false;\n\tlet lastExitCode: number | null = null;\n\treturn {\n\t\ttouched: () => touched,\n\t\tlastExitCode: () => lastExitCode,\n\t\twriteStdout: (line) =>\n\t\t\tio.writeStdout(line).pipe(\n\t\t\t\tEffect.tap(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\twriteStderr: (line) =>\n\t\t\tio.writeStderr(line).pipe(\n\t\t\t\tEffect.tap(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\tsetExitCode: (code) =>\n\t\t\tio.setExitCode(code).pipe(\n\t\t\t\tEffect.tap(() =>\n\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\ttouched = true;\n\t\t\t\t\t\tlastExitCode = code;\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// Flag models\n// -----------------------------------------------------------------------------\n\ninterface IdentityFlags {\n\treadonly json?: boolean;\n\treadonly app?: string;\n\treadonly stack?: string;\n\treadonly stateDir?: string;\n\treadonly verbose?: boolean;\n}\n\ninterface ConfigFlags extends IdentityFlags {\n\treadonly config?: string;\n\treadonly network?: string;\n}\n\ninterface UpFlags extends ConfigFlags {\n\treadonly renderer?: CliRendererMode;\n}\n\ninterface DestructiveFlags extends IdentityFlags {\n\treadonly dryRun?: boolean;\n\treadonly yes?: boolean;\n\treadonly noInput?: boolean;\n}\n\ninterface ConfirmFlags extends IdentityFlags {\n\treadonly yes?: boolean;\n\treadonly noInput?: boolean;\n}\n\ninterface PruneFlags {\n\treadonly json?: boolean;\n\treadonly stateDir?: string;\n\treadonly verbose?: boolean;\n\treadonly dryRun?: boolean;\n\treadonly yes?: boolean;\n\treadonly noInput?: boolean;\n\treadonly list?: boolean;\n\treadonly all?: boolean;\n\treadonly noContainers?: boolean;\n\treadonly noNetworks?: boolean;\n\treadonly noVolumes?: boolean;\n\treadonly includeImages?: boolean;\n}\n\ninterface SnapshotSaveFlags extends ConfigFlags {\n\treadonly name?: string;\n}\n\nconst textParser = (input: string): string => input;\n\nconst stringFlag = (brief: string, placeholder: string) =>\n\t({\n\t\tkind: 'parsed',\n\t\tparse: textParser,\n\t\toptional: true,\n\t\tplaceholder,\n\t\tbrief,\n\t}) as const;\n\nconst boolFlag = (brief: string) =>\n\t({\n\t\tkind: 'boolean',\n\t\toptional: true,\n\t\tbrief,\n\t}) as const;\n\nconst identityFlagParams = {\n\tjson: boolFlag('Emit JSON envelope output'),\n\tapp: stringFlag('Override app name', 'name'),\n\tstack: stringFlag('Override stack name', 'name'),\n\tstateDir: stringFlag('Override state directory', 'path'),\n\tverbose: boolFlag('Enable more verbose logging'),\n} as const;\n\nconst configFlagParams = {\n\t...identityFlagParams,\n\tconfig: stringFlag('Override devstack.config.ts path', 'path'),\n\tnetwork: stringFlag('Override network before config import', 'name'),\n} as const;\n\nconst destructiveFlagParams = {\n\t...identityFlagParams,\n\tdryRun: boolFlag('Skip mutating effects'),\n\tyes: boolFlag('Assume yes on prompts'),\n\tnoInput: boolFlag('Forbid prompts'),\n} as const;\n\nconst globalMaintenanceFlagParams = {\n\tjson: identityFlagParams.json,\n\tstateDir: identityFlagParams.stateDir,\n\tverbose: identityFlagParams.verbose,\n} as const;\n\nconst confirmFlagParams = {\n\t...identityFlagParams,\n\tyes: boolFlag('Assume yes on prompts'),\n\tnoInput: boolFlag('Forbid prompts'),\n} as const;\n\nconst pruneFlagParams = {\n\t...globalMaintenanceFlagParams,\n\tdryRun: destructiveFlagParams.dryRun,\n\tyes: destructiveFlagParams.yes,\n\tnoInput: destructiveFlagParams.noInput,\n\tlist: boolFlag('List devstack-labelled Docker resources without pruning'),\n\tall: boolFlag('Prune every idle non-shared resource group'),\n\tnoContainers: boolFlag('Do not remove containers'),\n\tnoNetworks: boolFlag('Do not remove networks'),\n\tnoVolumes: boolFlag('Do not remove volumes'),\n\tincludeImages: boolFlag('Also remove devstack-labelled images for selected groups'),\n} as const;\n\nconst rendererParser = buildChoiceParser(['tui', 'plain', 'silent'] as const);\n\nconst outputModeFrom = (\n\tflags: Pick<IdentityFlags, 'json'>,\n\tenv: Readonly<Record<string, string | undefined>>,\n): OutputMode => (flags.json === true || env[ENV_VARS.JSON] === '1' ? 'json' : 'human');\n\nconst pruneResourcesFromFlags = (flags: PruneFlags): PruneResourceScope => ({\n\tcontainers: flags.noContainers !== true,\n\tnetworks: flags.noNetworks !== true,\n\tvolumes: flags.noVolumes !== true,\n\timages: flags.includeImages === true,\n});\n\nconst optionalEnv = (\n\tvalue: string | undefined,\n\tenv: Readonly<Record<string, string | undefined>>,\n\tkey: string,\n): string | undefined => value ?? env[key];\n\nconst makeGlobalFlags = (\n\tctx: DevstackCliContext,\n\tflags: IdentityFlags & Partial<ConfigFlags & UpFlags & DestructiveFlags>,\n\trest: ReadonlyArray<string>,\n): GlobalFlags => {\n\tconst networkRaw = optionalEnv(flags.network, ctx.env, ENV_VARS.NETWORK);\n\tlet network: string | undefined;\n\tif (networkRaw !== undefined) {\n\t\ttry {\n\t\t\tnetwork = parseDevstackNetworkName(\n\t\t\t\tnetworkRaw,\n\t\t\t\tflags.network === undefined ? ENV_VARS.NETWORK : '--network',\n\t\t\t);\n\t\t} catch (cause) {\n\t\t\tthrow cause instanceof Error\n\t\t\t\t? new CliUsageError({ message: cause.message })\n\t\t\t\t: new CliInternalError({ message: 'failed to parse network flag', cause });\n\t\t}\n\t}\n\treturn {\n\t\toutputMode: outputModeFrom(flags, ctx.env),\n\t\tapp: optionalEnv(flags.app, ctx.env, ENV_VARS.APP),\n\t\tstack: optionalEnv(flags.stack, ctx.env, ENV_VARS.STACK),\n\t\tstateDir: optionalEnv(flags.stateDir, ctx.env, ENV_VARS.STATE_DIR),\n\t\tconfigPath: optionalEnv(flags.config, ctx.env, ENV_VARS.CONFIG_PATH),\n\t\tnetwork,\n\t\trenderer: flags.renderer,\n\t\tdryRun: flags.dryRun === true,\n\t\tconfirm: {\n\t\t\tassumeYes: flags.yes === true,\n\t\t\tforbidPrompt: flags.noInput === true || ctx.env[ENV_VARS.NO_INPUT] === '1',\n\t\t\tstdinIsTty: ctx.stdinIsTty,\n\t\t},\n\t\tverbose: flags.verbose === true,\n\t\trest,\n\t};\n};\n\n/**\n * Bridge the CLI `--network` flag through `process.env` so config-load-time\n * factory reads pick it up. This indirection is deliberate, not a leak.\n *\n * Why the mutation exists:\n *   The `deepbook()` factory (`plugins/deepbook/index.ts`) defaults its mode\n *   by reading `process.env.DEVSTACK_NETWORK` at config import time — before\n *   any flag value has reached the orchestrator. To make `--network` affect\n *   the same default, we must mutate the env BEFORE the user's\n *   `devstack.config.ts` is loaded. The chain is:\n *     `--network=<net>` flag  →  setNetworkEnv  →  `process.env.DEVSTACK_NETWORK`\n *                              →  `deepbook()` factory's env read at import.\n *\n * Why save/restore (and a scoped finalizer) matters:\n *   The CLI is also invoked from tests and embedded harnesses inside a single\n *   process. An unscoped mutation leaks across invocations: a test that runs\n *   `dispatch(['up','--network=testnet'])` followed by `dispatch(['up'])`\n *   would see the second call inherit `testnet` from the first. The\n *   finalizer restores the prior value (or deletes the key if it was unset)\n *   on success, failure, AND interrupt — `Effect.addFinalizer` guarantees\n *   the cleanup runs regardless of how the scope closes.\n */\nconst setNetworkEnv = (flags: GlobalFlags): Effect.Effect<void, never, Scope.Scope> => {\n\tif (flags.network === undefined) return Effect.void;\n\tconst next = flags.network;\n\treturn Effect.gen(function* () {\n\t\tconst prior = process.env[ENV_VARS.NETWORK];\n\t\tprocess.env[ENV_VARS.NETWORK] = next;\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\tEffect.sync(() => {\n\t\t\t\tif (prior === undefined) {\n\t\t\t\t\tdelete process.env[ENV_VARS.NETWORK];\n\t\t\t\t} else {\n\t\t\t\t\tprocess.env[ENV_VARS.NETWORK] = prior;\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n\t});\n};\n\n// -----------------------------------------------------------------------------\n// Command execution helpers\n// -----------------------------------------------------------------------------\n\nconst runCommandEffect = async (\n\tctx: DevstackCliContext,\n\tcommand: string,\n\tflags: GlobalFlags,\n\teffect: Effect.Effect<CommandResult, CliError>,\n): Promise<void> => {\n\t// `setNetworkEnv` registers a `process.env[ENV_VARS.NETWORK]` restore as a\n\t// scope finalizer; the outer `Effect.scoped` closes that scope after the\n\t// command completes (success, failure, or interrupt), preventing env leaks\n\t// between concurrent CLI invocations in the same process.\n\tconst program = Effect.scoped(\n\t\tsetNetworkEnv(flags).pipe(\n\t\t\tEffect.andThen(effect),\n\t\t\tEffect.catch((error: CliError) =>\n\t\t\t\temitFailure(ctx.io, flags.outputMode, {\n\t\t\t\t\tcommand,\n\t\t\t\t\telapsedMs: 0,\n\t\t\t\t\terror,\n\t\t\t\t}).pipe(Effect.as({ exitCode: exitCodeFor(error) })),\n\t\t\t),\n\t\t\tEffect.catchCause((cause) =>\n\t\t\t\temitFailure(ctx.io, flags.outputMode, {\n\t\t\t\t\tcommand,\n\t\t\t\t\telapsedMs: 0,\n\t\t\t\t\terror: new CliInternalError({ message: 'unexpected internal failure' }),\n\t\t\t\t\tcause,\n\t\t\t\t}).pipe(Effect.as({ exitCode: ExitCode.SOFTWARE })),\n\t\t\t),\n\t\t),\n\t);\n\tconst result = await Effect.runPromise(program);\n\tif (ctx.io.lastExitCode() === null) {\n\t\tawait Effect.runPromise(ctx.io.setExitCode(result.exitCode));\n\t}\n};\n\nconst runWithFlags = async (\n\tctx: DevstackCliContext,\n\tcommand: string,\n\trawFlags: IdentityFlags & Partial<ConfigFlags & UpFlags & DestructiveFlags>,\n\trest: ReadonlyArray<string>,\n\teffect: (flags: GlobalFlags) => Effect.Effect<CommandResult, CliError>,\n): Promise<void> => {\n\tlet flags: GlobalFlags;\n\ttry {\n\t\tflags = makeGlobalFlags(ctx, rawFlags, rest);\n\t} catch (cause) {\n\t\tconst error =\n\t\t\tcause instanceof CliUsageError\n\t\t\t\t? cause\n\t\t\t\t: new CliInternalError({ message: 'failed to resolve CLI flags', cause });\n\t\tconst mode = outputModeFrom(rawFlags, ctx.env);\n\t\tawait Effect.runPromise(\n\t\t\temitFailure(ctx.io, mode, {\n\t\t\t\tcommand,\n\t\t\t\telapsedMs: 0,\n\t\t\t\terror,\n\t\t\t}),\n\t\t);\n\t\treturn;\n\t}\n\tawait runCommandEffect(ctx, command, flags, effect(flags));\n};\n\nconst requiredPositional = (placeholder: string, brief: string) =>\n\t({\n\t\tparse: textParser,\n\t\tplaceholder,\n\t\tbrief,\n\t}) as const;\n\nconst optionalPositional = (placeholder: string, brief: string) =>\n\t({\n\t\tparse: textParser,\n\t\tplaceholder,\n\t\tbrief,\n\t\toptional: true as const,\n\t}) as const;\n\n// -----------------------------------------------------------------------------\n// Commands\n// -----------------------------------------------------------------------------\n\nconst upCommand = buildCommand<UpFlags, [], DevstackCliContext>({\n\tparameters: {\n\t\tflags: {\n\t\t\t...configFlagParams,\n\t\t\trenderer: {\n\t\t\t\tkind: 'parsed',\n\t\t\t\tparse: rendererParser,\n\t\t\t\toptional: true,\n\t\t\t\tplaceholder: 'tui|plain|silent',\n\t\t\t\tbrief: 'Select the attached renderer',\n\t\t\t},\n\t\t},\n\t},\n\tdocs: {\n\t\tbrief: 'Boot a stack and stay attached until interrupted',\n\t},\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'up', flags, [], (global) => this.deps.up.run(global));\n\t},\n});\n\nconst applyCommand = buildCommand<ConfigFlags, [], DevstackCliContext>({\n\tparameters: { flags: configFlagParams },\n\tdocs: {\n\t\tbrief: 'Reconcile a live stack or run one-shot setup',\n\t},\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'apply', flags, [], (global) => this.deps.apply.run(global));\n\t},\n});\n\nconst statusCommand = buildCommand<IdentityFlags, [], DevstackCliContext>({\n\tparameters: { flags: identityFlagParams },\n\tdocs: { brief: 'Show the persisted stack projection' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'status', flags, [], (global) =>\n\t\t\trunStatus(this.deps.status, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst doctorCommand = buildCommand<IdentityFlags, [], DevstackCliContext>({\n\tparameters: { flags: identityFlagParams },\n\tdocs: { brief: 'Run host and stack preflight checks' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'doctor', flags, [], (global) =>\n\t\t\trunDoctor(this.deps.doctor, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst configCommand = buildCommand<ConfigFlags, [], DevstackCliContext>({\n\tparameters: { flags: configFlagParams },\n\tdocs: { brief: 'Print resolved config inputs' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'config', flags, [], (global) =>\n\t\t\trunConfig(this.deps.config, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst schemaCommand = buildCommand<Pick<IdentityFlags, 'json'>, [], DevstackCliContext>({\n\tparameters: { flags: { json: identityFlagParams.json } },\n\tdocs: { brief: 'Emit the CLI schema' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'schema', flags, [], (global) => {\n\t\t\tconst data = { ...commandSchema(), outputMode: global.outputMode };\n\t\t\treturn emitSuccess(this.io, global.outputMode, {\n\t\t\t\tcommand: 'schema',\n\t\t\t\telapsedMs: 0,\n\t\t\t\tdata,\n\t\t\t\thumanLines: [JSON.stringify(data, null, 2)],\n\t\t\t}).pipe(Effect.as({ exitCode: 0 }));\n\t\t});\n\t},\n});\n\nconst snapshotSaveCommand = buildCommand<\n\tSnapshotSaveFlags,\n\t[string | undefined],\n\tDevstackCliContext\n>({\n\tparameters: {\n\t\tflags: {\n\t\t\t...configFlagParams,\n\t\t\tname: stringFlag('Human-readable snapshot name', 'name'),\n\t\t},\n\t\tpositional: { kind: 'tuple', parameters: [optionalPositional('name', 'snapshot name')] },\n\t},\n\tdocs: { brief: 'Capture a snapshot' },\n\tfunc: function (flags, snapshotName) {\n\t\tconst rest = [\n\t\t\t'save',\n\t\t\t...(snapshotName === undefined ? [] : [snapshotName]),\n\t\t\t...(flags.name === undefined ? [] : ['--name', flags.name]),\n\t\t];\n\t\treturn runWithFlags(this, 'snapshot save', flags, rest, (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotRestoreCommand = buildCommand<ConfirmFlags, [string], DevstackCliContext>({\n\tparameters: {\n\t\tflags: confirmFlagParams,\n\t\tpositional: {\n\t\t\tkind: 'tuple',\n\t\t\tparameters: [requiredPositional('name-or-id', 'snapshot name or id')],\n\t\t},\n\t},\n\tdocs: { brief: 'Restore a snapshot' },\n\tfunc: function (flags, snapshotRef) {\n\t\treturn runWithFlags(this, 'snapshot restore', flags, ['restore', snapshotRef], (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotListCommand = buildCommand<IdentityFlags, [], DevstackCliContext>({\n\tparameters: { flags: identityFlagParams },\n\tdocs: { brief: 'List snapshots' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'snapshot list', flags, ['list'], (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotDeleteCommand = buildCommand<ConfirmFlags, [string], DevstackCliContext>({\n\tparameters: {\n\t\tflags: confirmFlagParams,\n\t\tpositional: {\n\t\t\tkind: 'tuple',\n\t\t\tparameters: [requiredPositional('name-or-id', 'snapshot name or id')],\n\t\t},\n\t},\n\tdocs: { brief: 'Delete a snapshot' },\n\tfunc: function (flags, snapshotRef) {\n\t\treturn runWithFlags(this, 'snapshot delete', flags, ['delete', snapshotRef], (global) =>\n\t\t\trunSnapshot(this.deps.snapshot, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst snapshotCommands = buildRouteMap({\n\troutes: {\n\t\tsave: snapshotSaveCommand,\n\t\trestore: snapshotRestoreCommand,\n\t\tlist: snapshotListCommand,\n\t\tdelete: snapshotDeleteCommand,\n\t},\n\tdocs: { brief: 'Capture, restore, list, or delete stack snapshots' },\n});\n\nconst pruneCommand = buildCommand<PruneFlags, [], DevstackCliContext>({\n\tparameters: { flags: pruneFlagParams },\n\tdocs: { brief: 'Inventory and prune devstack-labelled Docker resources' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'prune', flags, [], (global) =>\n\t\t\trunPrune(\n\t\t\t\tthis.deps.prune,\n\t\t\t\t{ flags: global, io: this.io },\n\t\t\t\t{\n\t\t\t\t\tmode: flags.list === true ? 'list' : flags.all === true ? 'all' : 'auto',\n\t\t\t\t\tresources: pruneResourcesFromFlags(flags),\n\t\t\t\t},\n\t\t\t),\n\t\t);\n\t},\n});\n\nconst wipeCommand = buildCommand<DestructiveFlags, [], DevstackCliContext>({\n\tparameters: { flags: destructiveFlagParams },\n\tdocs: { brief: 'Destroy all state for the selected stack' },\n\tfunc: function (flags) {\n\t\treturn runWithFlags(this, 'wipe', flags, [], (global) =>\n\t\t\trunWipe(this.deps.wipe, { flags: global, io: this.io }),\n\t\t);\n\t},\n});\n\nconst root = buildRouteMap({\n\troutes: {\n\t\tup: upCommand,\n\t\tapply: applyCommand,\n\t\tstatus: statusCommand,\n\t\tdoctor: doctorCommand,\n\t\tconfig: configCommand,\n\t\tschema: schemaCommand,\n\t\tsnapshot: snapshotCommands,\n\t\tprune: pruneCommand,\n\t\twipe: wipeCommand,\n\t},\n\tdocs: {\n\t\tbrief: 'Sui development stack CLI',\n\t},\n});\n\nconst app = buildApplication(root, {\n\tname: 'devstack',\n\tversionInfo: { currentVersion: readPackageVersion() },\n\tscanner: { caseStyle: 'allow-kebab-for-camel' },\n\tdocumentation: {\n\t\tcaseStyle: 'convert-camel-to-kebab',\n\t\tdisableAnsiColor: true,\n\t\tonlyRequiredInUsageLine: true,\n\t},\n\tlocalization: {\n\t\tloadText: () => ({\n\t\t\t...text_en,\n\t\t\texceptionWhileParsingArguments: (error) =>\n\t\t\t\terror instanceof Error ? error.message : String(error),\n\t\t}),\n\t},\n});\n\nconst jsonRequested = (\n\targv: ReadonlyArray<string>,\n\tenv: Readonly<Record<string, string | undefined>>,\n): boolean => env[ENV_VARS.JSON] === '1' || argv.includes('--json');\n\n/**\n * Project a `BufferedProcess.exitCode` to a sysexit code AT THE\n * STRICLI-PARSE BOUNDARY ONLY.\n *\n * Contract: `BufferedProcess.exitCode` is mutated ONLY by Stricli's\n * argv-parser when an argv parse step fails (unknown subcommand,\n * malformed flag value, missing required positional). Verbs route\n * their own outcomes through `ctx.io.setExitCode`, which marks\n * `io.touched()` and short-circuits this projection in `dispatch`\n * before `flushBufferedProcess` is reached.\n *\n * The historic implementation collapsed ANY non-zero `code` to\n * `USAGE` (64), but that was wrong: it could only ever observe a\n * Stricli parse failure (the only writer to this field), so the\n * `USAGE` mapping holds by construction. Kept as a named function\n * so the invariant is documented at the call site.\n */\nconst normalizeStricliExitCode = (code: number | string | null | undefined): number => {\n\tif (typeof code === 'number' && code !== 0) return ExitCode.USAGE;\n\treturn ExitCode.OK;\n};\n\n/**\n * Bridge Stricli's synchronous `StricliProcess.{stdout,stderr}.write`\n * shape to our async (Effect-based) `CliIO` surface.\n *\n * The indirection is load-bearing for the JSON-envelope contract:\n * Stricli writes argv-parse errors to stderr the moment the parser\n * trips, but `--json` mode demands the failure be EMITTED as a\n * structured envelope on stdout (not raw text on stderr) with exit\n * code `EX_USAGE`. We can't wire Stricli's `stderr.write` directly to\n * `nodeProcessIO.writeStderr` because:\n *\n *   1. The stderr bytes are the raw parser error text; in `--json`\n *      mode we need to transform them into a failure envelope.\n *   2. We don't know whether the verb handler \"touched\" the IO\n *      (rendered its own envelope) until after Stricli returns.\n *\n * Buffering lets us delay the decision until both signals are\n * available. Tests substitute a `BufferedProcess` whose buffers are\n * later inspected, mirroring the prod flush behavior.\n */\nconst flushBufferedProcess = (\n\tprocess: BufferedProcess,\n\tio: CliIO,\n\targv: ReadonlyArray<string>,\n\tenv: Readonly<Record<string, string | undefined>>,\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst exitCode = normalizeStricliExitCode(process.exitCode);\n\t\tconst stdout = process.stdoutBuffer.join('');\n\t\tconst stderr = process.stderrBuffer.join('').trim();\n\t\tif (exitCode !== 0 && jsonRequested(argv, env)) {\n\t\t\tyield* emitFailure(io, 'json', {\n\t\t\t\tcommand: '(parse)',\n\t\t\t\telapsedMs: 0,\n\t\t\t\terror: new CliUsageError({\n\t\t\t\t\tmessage: stderr.length > 0 ? stderr : 'invalid command line',\n\t\t\t\t}),\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tif (stdout.length > 0)\n\t\t\tyield* io.writeStdout(stdout.endsWith('\\n') ? stdout.slice(0, -1) : stdout);\n\t\tif (stderr.length > 0) yield* io.writeStderr(stderr);\n\t\tyield* io.setExitCode(exitCode);\n\t});\n\nexport const dispatch = (deps: CliDeps, dispatchEnv: DispatchEnv): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst io = trackIO(dispatchEnv.io ?? nodeProcessIO);\n\t\tconst process = makeBufferedProcess(dispatchEnv.env);\n\t\tconst ctx: DevstackCliContext = {\n\t\t\tprocess,\n\t\t\tdeps,\n\t\t\tenv: dispatchEnv.env,\n\t\t\tstdinIsTty: dispatchEnv.stdinIsTty,\n\t\t\tio,\n\t\t};\n\t\tyield* Effect.tryPromise({\n\t\t\ttry: () => runStricli(app, dispatchEnv.argv, ctx),\n\t\t\tcatch: (cause) => new CliInternalError({ message: 'CLI dispatcher failed', cause }),\n\t\t}).pipe(\n\t\t\tEffect.catch((error: CliError) =>\n\t\t\t\temitFailure(io, jsonRequested(dispatchEnv.argv, dispatchEnv.env) ? 'json' : 'human', {\n\t\t\t\t\tcommand: '(dispatch)',\n\t\t\t\t\telapsedMs: 0,\n\t\t\t\t\terror,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t\tif (!io.touched()) {\n\t\t\tyield* flushBufferedProcess(process, io, dispatchEnv.argv, dispatchEnv.env);\n\t\t}\n\t});\n\n// -----------------------------------------------------------------------------\n// Re-exports\n// -----------------------------------------------------------------------------\n\nexport type { CliIO } from './output.ts';\nexport type { GlobalFlags } from './flags.ts';\nexport { COMMAND_TREE, commandSchema, VERBS, type Verb } from './command-tree.ts';\nexport type { Envelope, EnvelopeError } from './envelope.ts';\nexport {\n\tENVELOPE_SCHEMA_VERSION,\n\tfailureEnvelope,\n\tstreamingEvent,\n\tsuccessEnvelope,\n\ttype StreamingEvent,\n} from './envelope.ts';\nexport { ExitCode, exitCodeName } from './sysexits.ts';\nexport {\n\ttype CliError,\n\tCliAlreadyReportedError,\n\tCliConfigInvalidError,\n\tCliConfigNotFoundError,\n\tCliConfirmDeclinedError,\n\tCliConfirmRequiredError,\n\tCliInternalError,\n\tCliSnapshotNotFoundError,\n\tCliSupervisorLiveError,\n\tCliUnavailableError,\n\tCliUsageError,\n} from './errors.ts';\n"],"mappings":"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"}

package/dist/surfaces/cli/output.mjs

@@ -1,4 +1,5 @@
 import { formatCause, formatValue } from "../../substrate/runtime/observability/cascade-formatter.mjs";
+import "./sysexits.mjs";
 import { exitCodeFor, hintFor, summaryFor } from "./errors.mjs";
 import { failureEnvelope, successEnvelope } from "./envelope.mjs";
 import { Effect } from "effect";

package/dist/surfaces/cli/output.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"output.mjs","names":[],"sources":["../../../src/surfaces/cli/output.ts"],"sourcesContent":["// CLI surface — output rendering (human / JSON envelope / structured\n// pretty error).\n//\n// Architecture (distilled/20-cli.md § Output formats):\n//   - JSON envelope on stdout EXACTLY ONCE per command in `--json`\n//     mode; stderr never receives the envelope.\n//   - Human text on stdout otherwise.\n//   - Pretty error tree on stderr only on failure — and only if the\n//     subcommand hasn't already rendered (the `CliAlreadyReportedError`\n//     sentinel suppresses).\n//\n// This module owns all stdout/stderr writes for the CLI. Subcommands\n// build envelope params; this module serializes and emits.\n\nimport { Effect } from 'effect';\nimport type { Cause } from 'effect';\n\nimport {\n\tformatCause,\n\tformatValue,\n} from '../../substrate/runtime/observability/cascade-formatter.ts';\nimport {\n\ttype Envelope,\n\tfailureEnvelope,\n\ttype FailureParams,\n\ttype StreamingEvent,\n\tsuccessEnvelope,\n\ttype SuccessParams,\n} from './envelope.ts';\nimport {\n\ttype CliError,\n\tCliAlreadyReportedError,\n\texitCodeFor,\n\thintFor,\n\tsummaryFor,\n} from './errors.ts';\nimport type { OutputMode } from './flags.ts';\nimport { type ExitCode } from './sysexits.ts';\n\n// -----------------------------------------------------------------------------\n// I/O service abstraction\n// -----------------------------------------------------------------------------\n\n/** Surface-level IO. Tests substitute a buffered impl. */\nexport interface CliIO {\n\treadonly writeStdout: (line: string) => Effect.Effect<void>;\n\treadonly writeStderr: (line: string) => Effect.Effect<void>;\n\treadonly setExitCode: (code: number) => Effect.Effect<void>;\n}\n\n/** Default IO bound to the Node process. */\nexport const nodeProcessIO: CliIO = {\n\twriteStdout: (line) =>\n\t\tEffect.sync(() => {\n\t\t\tprocess.stdout.write(line.endsWith('\\n') ? line : `${line}\\n`);\n\t\t}),\n\twriteStderr: (line) =>\n\t\tEffect.sync(() => {\n\t\t\tprocess.stderr.write(line.endsWith('\\n') ? line : `${line}\\n`);\n\t\t}),\n\tsetExitCode: (code) =>\n\t\tEffect.sync(() => {\n\t\t\tprocess.exitCode = code;\n\t\t}),\n};\n\n// -----------------------------------------------------------------------------\n// Stable JSON serialization\n// -----------------------------------------------------------------------------\n\n/**\n * `JSON.stringify` strips `undefined` from objects but NOT from\n * arrays (replaces with `null`). The envelope builders already omit\n * absent keys, but we add a guard so a future builder bug doesn't\n * leak `undefined` into automation output.\n *\n * Architecture: \"Absent fields are OMITTED from serialized output (no\n * `undefined`).\" This function enforces that promise.\n */\nexport const serializeEnvelope = (env: Envelope<unknown> | StreamingEvent<unknown>): string => {\n\tconst cleaned = stripUndefined(env);\n\treturn JSON.stringify(cleaned);\n};\n\nconst stripUndefined = (value: unknown): unknown => {\n\tif (value === undefined) return undefined;\n\tif (value === null) return null;\n\tif (Array.isArray(value)) return value.map(stripUndefined);\n\tif (typeof value !== 'object') return value;\n\tconst out: Record<string, unknown> = {};\n\tfor (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n\t\tif (v === undefined) continue;\n\t\tout[k] = stripUndefined(v);\n\t}\n\treturn out;\n};\n\n// -----------------------------------------------------------------------------\n// Success path\n// -----------------------------------------------------------------------------\n\n/**\n * Emit a success envelope OR a human-mode line block. Sets exit code\n * 0 unless a streaming success path supplies its own process code.\n *\n * In JSON mode: one envelope on stdout, nothing on stderr.\n * In human mode: each `humanLines` entry on stdout; hints rendered\n * after; no envelope.\n */\nexport const emitSuccess = <Data>(\n\tio: CliIO,\n\tmode: OutputMode,\n\tparams: SuccessParams<Data> & {\n\t\treadonly humanLines?: ReadonlyArray<string>;\n\t\t/** Override the OS exit code for commands whose transport\n\t\t *  succeeded but whose payload carries a process-style status. */\n\t\treadonly exitCode?: number;\n\t},\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tif (mode === 'json') {\n\t\t\tconst env = successEnvelope({\n\t\t\t\tcommand: params.command,\n\t\t\t\telapsedMs: params.elapsedMs,\n\t\t\t\tdata: params.data,\n\t\t\t\thints: params.hints,\n\t\t\t\tdryRun: params.dryRun,\n\t\t\t});\n\t\t\tyield* io.writeStdout(serializeEnvelope(env));\n\t\t} else {\n\t\t\tfor (const line of params.humanLines ?? []) {\n\t\t\t\tyield* io.writeStdout(line);\n\t\t\t}\n\t\t\tfor (const hint of params.hints ?? []) {\n\t\t\t\tyield* io.writeStdout(`hint: ${hint}`);\n\t\t\t}\n\t\t}\n\t\tyield* io.setExitCode(params.exitCode ?? 0);\n\t});\n\n// -----------------------------------------------------------------------------\n// Failure path\n// -----------------------------------------------------------------------------\n\n/**\n * Emit a failure for a `CliError`. Threads the sysexit code through\n * to `process.exitCode`. Honors the already-reported sentinel.\n *\n * Architecture invariant: \"Top-level error rendering must not\n * double-print when a subcommand already rendered.\" — we still set the\n * exit code but skip the envelope/stderr write.\n */\nexport const emitFailure = (\n\tio: CliIO,\n\tmode: OutputMode,\n\tparams: {\n\t\treadonly command: string;\n\t\treadonly elapsedMs: number;\n\t\treadonly error: CliError;\n\t\treadonly cause?: Cause.Cause<unknown>;\n\t\treadonly dryRun?: boolean;\n\t},\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst exitCode = exitCodeFor(params.error);\n\t\tif (params.error._tag === 'CliAlreadyReportedError') {\n\t\t\tyield* io.setExitCode(exitCode);\n\t\t\treturn;\n\t\t}\n\t\tyield* renderFailure(io, mode, {\n\t\t\tcommand: params.command,\n\t\t\telapsedMs: params.elapsedMs,\n\t\t\texitCode,\n\t\t\tsummary: summaryFor(params.error),\n\t\t\thint: hintFor(params.error),\n\t\t\tcause: params.cause,\n\t\t\terrorCause:\n\t\t\t\t'cause' in params.error ? (params.error as { readonly cause?: unknown }).cause : undefined,\n\t\t\tdryRun: params.dryRun,\n\t\t});\n\t\tyield* io.setExitCode(exitCode);\n\t});\n\ninterface RenderFailureParams {\n\treadonly command: string;\n\treadonly elapsedMs: number;\n\treadonly exitCode: ExitCode;\n\treadonly summary: string;\n\treadonly hint?: string;\n\treadonly cause?: Cause.Cause<unknown>;\n\treadonly errorCause?: unknown;\n\treadonly dryRun?: boolean;\n}\n\nconst renderFailure = (io: CliIO, mode: OutputMode, p: RenderFailureParams): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst rawChain =\n\t\t\tp.cause !== undefined\n\t\t\t\t? formatCause(p.cause)\n\t\t\t\t: p.errorCause !== undefined\n\t\t\t\t\t? formatValue(p.errorCause)\n\t\t\t\t\t: undefined;\n\t\tconst chain = rawChain?.split('\\n').filter((l) => l.length > 0);\n\n\t\tif (mode === 'json') {\n\t\t\tconst fp: FailureParams = {\n\t\t\t\tcommand: p.command,\n\t\t\t\telapsedMs: p.elapsedMs,\n\t\t\t\texitCode: p.exitCode,\n\t\t\t\tsummary: p.summary,\n\t\t\t\thint: p.hint,\n\t\t\t\tchain,\n\t\t\t\tdryRun: p.dryRun,\n\t\t\t};\n\t\t\tyield* io.writeStdout(serializeEnvelope(failureEnvelope(fp)));\n\t\t\treturn;\n\t\t}\n\n\t\t// Human mode: one-line summary on stderr, then optional hint and\n\t\t// the cascade chain (if present), all on stderr.\n\t\tyield* io.writeStderr(`error: ${p.summary}`);\n\t\tif (p.hint !== undefined) {\n\t\t\tyield* io.writeStderr(`hint: ${p.hint}`);\n\t\t}\n\t\tif (chain !== undefined && chain.length > 0) {\n\t\t\tfor (const line of chain) {\n\t\t\t\tyield* io.writeStderr(`  ${line}`);\n\t\t\t}\n\t\t}\n\t});\n\n// -----------------------------------------------------------------------------\n// Already-reported helper\n// -----------------------------------------------------------------------------\n\n/** A subcommand that pretty-renders its own failure (e.g. an\n *  interactive picker that already drew an error panel) returns this\n *  sentinel so the top-level renderer skips re-rendering but still\n *  propagates the right exit code. */\nexport const alreadyReported = (exitCode: ExitCode): CliAlreadyReportedError =>\n\tnew CliAlreadyReportedError({ exitCode });\n"],"mappings":"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"}
+{"version":3,"file":"output.mjs","names":[],"sources":["../../../src/surfaces/cli/output.ts"],"sourcesContent":["// CLI surface — output rendering (human / JSON envelope / structured\n// pretty error).\n//\n// Architecture (distilled/20-cli.md § Output formats):\n//   - JSON envelope on stdout EXACTLY ONCE per command in `--json`\n//     mode; stderr never receives the envelope.\n//   - Human text on stdout otherwise.\n//   - Pretty error tree on stderr only on failure — and only if the\n//     subcommand hasn't already rendered (the `CliAlreadyReportedError`\n//     sentinel suppresses).\n//\n// This module owns all stdout/stderr writes for the CLI. Subcommands\n// build envelope params; this module serializes and emits.\n\nimport { Effect } from 'effect';\nimport type { Cause } from 'effect';\n\nimport {\n\tformatCause,\n\tformatValue,\n} from '../../substrate/runtime/observability/cascade-formatter.ts';\nimport {\n\ttype Envelope,\n\tfailureEnvelope,\n\ttype FailureParams,\n\ttype StreamingEvent,\n\tsuccessEnvelope,\n\ttype SuccessParams,\n} from './envelope.ts';\nimport {\n\ttype CliError,\n\tCliAlreadyReportedError,\n\texitCodeFor,\n\thintFor,\n\tsummaryFor,\n} from './errors.ts';\nimport type { OutputMode } from './flags.ts';\nimport { type ExitCode } from './sysexits.ts';\n\n// -----------------------------------------------------------------------------\n// I/O service abstraction\n// -----------------------------------------------------------------------------\n\n/** Surface-level IO. Tests substitute a buffered impl. */\nexport interface CliIO {\n\treadonly writeStdout: (line: string) => Effect.Effect<void>;\n\treadonly writeStderr: (line: string) => Effect.Effect<void>;\n\treadonly setExitCode: (code: number) => Effect.Effect<void>;\n}\n\n/** Default IO bound to the Node process. */\nexport const nodeProcessIO: CliIO = {\n\twriteStdout: (line) =>\n\t\tEffect.sync(() => {\n\t\t\tprocess.stdout.write(line.endsWith('\\n') ? line : `${line}\\n`);\n\t\t}),\n\twriteStderr: (line) =>\n\t\tEffect.sync(() => {\n\t\t\tprocess.stderr.write(line.endsWith('\\n') ? line : `${line}\\n`);\n\t\t}),\n\tsetExitCode: (code) =>\n\t\tEffect.sync(() => {\n\t\t\tprocess.exitCode = code;\n\t\t}),\n};\n\n// -----------------------------------------------------------------------------\n// Stable JSON serialization\n// -----------------------------------------------------------------------------\n\n/**\n * `JSON.stringify` strips `undefined` from objects but NOT from\n * arrays (replaces with `null`). The envelope builders already omit\n * absent keys, but we add a guard so a future builder bug doesn't\n * leak `undefined` into automation output.\n *\n * Architecture: \"Absent fields are OMITTED from serialized output (no\n * `undefined`).\" This function enforces that promise.\n */\nexport const serializeEnvelope = (env: Envelope<unknown> | StreamingEvent<unknown>): string => {\n\tconst cleaned = stripUndefined(env);\n\treturn JSON.stringify(cleaned);\n};\n\nconst stripUndefined = (value: unknown): unknown => {\n\tif (value === undefined) return undefined;\n\tif (value === null) return null;\n\tif (Array.isArray(value)) return value.map(stripUndefined);\n\tif (typeof value !== 'object') return value;\n\tconst out: Record<string, unknown> = {};\n\tfor (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n\t\tif (v === undefined) continue;\n\t\tout[k] = stripUndefined(v);\n\t}\n\treturn out;\n};\n\n// -----------------------------------------------------------------------------\n// Success path\n// -----------------------------------------------------------------------------\n\n/**\n * Emit a success envelope OR a human-mode line block. Sets exit code\n * 0 unless a streaming success path supplies its own process code.\n *\n * In JSON mode: one envelope on stdout, nothing on stderr.\n * In human mode: each `humanLines` entry on stdout; hints rendered\n * after; no envelope.\n */\nexport const emitSuccess = <Data>(\n\tio: CliIO,\n\tmode: OutputMode,\n\tparams: SuccessParams<Data> & {\n\t\treadonly humanLines?: ReadonlyArray<string>;\n\t\t/** Override the OS exit code for commands whose transport\n\t\t *  succeeded but whose payload carries a process-style status. */\n\t\treadonly exitCode?: number;\n\t},\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tif (mode === 'json') {\n\t\t\tconst env = successEnvelope({\n\t\t\t\tcommand: params.command,\n\t\t\t\telapsedMs: params.elapsedMs,\n\t\t\t\tdata: params.data,\n\t\t\t\thints: params.hints,\n\t\t\t\tdryRun: params.dryRun,\n\t\t\t});\n\t\t\tyield* io.writeStdout(serializeEnvelope(env));\n\t\t} else {\n\t\t\tfor (const line of params.humanLines ?? []) {\n\t\t\t\tyield* io.writeStdout(line);\n\t\t\t}\n\t\t\tfor (const hint of params.hints ?? []) {\n\t\t\t\tyield* io.writeStdout(`hint: ${hint}`);\n\t\t\t}\n\t\t}\n\t\tyield* io.setExitCode(params.exitCode ?? 0);\n\t});\n\n// -----------------------------------------------------------------------------\n// Failure path\n// -----------------------------------------------------------------------------\n\n/**\n * Emit a failure for a `CliError`. Threads the sysexit code through\n * to `process.exitCode`. Honors the already-reported sentinel.\n *\n * Architecture invariant: \"Top-level error rendering must not\n * double-print when a subcommand already rendered.\" — we still set the\n * exit code but skip the envelope/stderr write.\n */\nexport const emitFailure = (\n\tio: CliIO,\n\tmode: OutputMode,\n\tparams: {\n\t\treadonly command: string;\n\t\treadonly elapsedMs: number;\n\t\treadonly error: CliError;\n\t\treadonly cause?: Cause.Cause<unknown>;\n\t\treadonly dryRun?: boolean;\n\t},\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst exitCode = exitCodeFor(params.error);\n\t\tif (params.error._tag === 'CliAlreadyReportedError') {\n\t\t\tyield* io.setExitCode(exitCode);\n\t\t\treturn;\n\t\t}\n\t\tyield* renderFailure(io, mode, {\n\t\t\tcommand: params.command,\n\t\t\telapsedMs: params.elapsedMs,\n\t\t\texitCode,\n\t\t\tsummary: summaryFor(params.error),\n\t\t\thint: hintFor(params.error),\n\t\t\tcause: params.cause,\n\t\t\terrorCause:\n\t\t\t\t'cause' in params.error ? (params.error as { readonly cause?: unknown }).cause : undefined,\n\t\t\tdryRun: params.dryRun,\n\t\t});\n\t\tyield* io.setExitCode(exitCode);\n\t});\n\ninterface RenderFailureParams {\n\treadonly command: string;\n\treadonly elapsedMs: number;\n\treadonly exitCode: ExitCode;\n\treadonly summary: string;\n\treadonly hint?: string;\n\treadonly cause?: Cause.Cause<unknown>;\n\treadonly errorCause?: unknown;\n\treadonly dryRun?: boolean;\n}\n\nconst renderFailure = (io: CliIO, mode: OutputMode, p: RenderFailureParams): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst rawChain =\n\t\t\tp.cause !== undefined\n\t\t\t\t? formatCause(p.cause)\n\t\t\t\t: p.errorCause !== undefined\n\t\t\t\t\t? formatValue(p.errorCause)\n\t\t\t\t\t: undefined;\n\t\tconst chain = rawChain?.split('\\n').filter((l) => l.length > 0);\n\n\t\tif (mode === 'json') {\n\t\t\tconst fp: FailureParams = {\n\t\t\t\tcommand: p.command,\n\t\t\t\telapsedMs: p.elapsedMs,\n\t\t\t\texitCode: p.exitCode,\n\t\t\t\tsummary: p.summary,\n\t\t\t\thint: p.hint,\n\t\t\t\tchain,\n\t\t\t\tdryRun: p.dryRun,\n\t\t\t};\n\t\t\tyield* io.writeStdout(serializeEnvelope(failureEnvelope(fp)));\n\t\t\treturn;\n\t\t}\n\n\t\t// Human mode: one-line summary on stderr, then optional hint and\n\t\t// the cascade chain (if present), all on stderr.\n\t\tyield* io.writeStderr(`error: ${p.summary}`);\n\t\tif (p.hint !== undefined) {\n\t\t\tyield* io.writeStderr(`hint: ${p.hint}`);\n\t\t}\n\t\tif (chain !== undefined && chain.length > 0) {\n\t\t\tfor (const line of chain) {\n\t\t\t\tyield* io.writeStderr(`  ${line}`);\n\t\t\t}\n\t\t}\n\t});\n\n// -----------------------------------------------------------------------------\n// Already-reported helper\n// -----------------------------------------------------------------------------\n\n/** A subcommand that pretty-renders its own failure (e.g. an\n *  interactive picker that already drew an error panel) returns this\n *  sentinel so the top-level renderer skips re-rendering but still\n *  propagates the right exit code. */\nexport const alreadyReported = (exitCode: ExitCode): CliAlreadyReportedError =>\n\tnew CliAlreadyReportedError({ exitCode });\n"],"mappings":"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"}

package/dist/surfaces/cli/sysexits.mjs

@@ -26,7 +26,7 @@ const ExitCode = {
 	/** Cannot open input (config not found, snapshot file missing). */
 	NO_INPUT: 66,
 	/** Internal software error / unhandled defect. Default for
-	*  defects that escape Effect.catchAll. */
+	*  defects that escape Effect.catch. */
 	SOFTWARE: 70,
 	/** Service required by the CLI is unavailable (Docker daemon
 	*  unreachable, network down). */
@@ -59,6 +59,7 @@ const exitCodeName = (code) => {
 		case ExitCode.CANT_CREATE: return "CANT_CREATE";
 		case ExitCode.TEMP_FAIL: return "TEMP_FAIL";
 		case ExitCode.CONFIG: return "CONFIG";
+		default: throw new Error(`Unknown ExitCode: ${String(code)}`);
 	}
 };
 const exitCodeTable = [