@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +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"}

package/dist/surfaces/cli/index.mjs

@@ -0,0 +1,418 @@
+import { parseDevstackNetworkName } from "../../api/inference-network.mjs";
+import "./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 { 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 { Effect } from "effect";
+import { buildApplication, buildChoiceParser, buildCommand, buildRouteMap, run, text_en } from "@stricli/core";
+//#region src/surfaces/cli/index.ts
+const makeBufferedProcess = (env) => {
+	const stdoutBuffer = [];
+	const stderrBuffer = [];
+	return {
+		stdoutBuffer,
+		stderrBuffer,
+		env,
+		stdout: { write: (str) => {
+			stdoutBuffer.push(str);
+		} },
+		stderr: { write: (str) => {
+			stderrBuffer.push(str);
+		} }
+	};
+};
+const trackIO = (io) => {
+	let touched = false;
+	let lastExitCode = null;
+	return {
+		touched: () => touched,
+		lastExitCode: () => lastExitCode,
+		writeStdout: (line) => io.writeStdout(line).pipe(Effect.tap(() => Effect.sync(() => {
+			touched = true;
+		}))),
+		writeStderr: (line) => io.writeStderr(line).pipe(Effect.tap(() => Effect.sync(() => {
+			touched = true;
+		}))),
+		setExitCode: (code) => io.setExitCode(code).pipe(Effect.tap(() => Effect.sync(() => {
+			touched = true;
+			lastExitCode = code;
+		})))
+	};
+};
+const textParser = (input) => input;
+const stringFlag = (brief, placeholder) => ({
+	kind: "parsed",
+	parse: textParser,
+	optional: true,
+	placeholder,
+	brief
+});
+const boolFlag = (brief) => ({
+	kind: "boolean",
+	optional: true,
+	brief
+});
+const identityFlagParams = {
+	json: boolFlag("Emit JSON envelope output"),
+	app: stringFlag("Override app name", "name"),
+	stack: stringFlag("Override stack name", "name"),
+	stateDir: stringFlag("Override state directory", "path"),
+	verbose: boolFlag("Enable more verbose logging")
+};
+const configFlagParams = {
+	...identityFlagParams,
+	config: stringFlag("Override devstack.config.ts path", "path"),
+	network: stringFlag("Override network before config import", "name")
+};
+const destructiveFlagParams = {
+	...identityFlagParams,
+	dryRun: boolFlag("Skip mutating effects"),
+	yes: boolFlag("Assume yes on prompts"),
+	noInput: boolFlag("Forbid prompts")
+};
+const globalMaintenanceFlagParams = {
+	json: identityFlagParams.json,
+	stateDir: identityFlagParams.stateDir,
+	verbose: identityFlagParams.verbose
+};
+const confirmFlagParams = {
+	...identityFlagParams,
+	yes: boolFlag("Assume yes on prompts"),
+	noInput: boolFlag("Forbid prompts")
+};
+const pruneFlagParams = {
+	...globalMaintenanceFlagParams,
+	dryRun: destructiveFlagParams.dryRun,
+	yes: destructiveFlagParams.yes,
+	noInput: destructiveFlagParams.noInput,
+	list: boolFlag("List devstack-labelled Docker resources without pruning"),
+	all: boolFlag("Prune every idle non-shared resource group"),
+	noContainers: boolFlag("Do not remove containers"),
+	noNetworks: boolFlag("Do not remove networks"),
+	noVolumes: boolFlag("Do not remove volumes"),
+	includeImages: boolFlag("Also remove devstack-labelled images for selected groups")
+};
+const rendererParser = buildChoiceParser([
+	"tui",
+	"plain",
+	"silent"
+]);
+const outputModeFrom = (flags, env) => flags.json === true || env[ENV_VARS.JSON] === "1" ? "json" : "human";
+const pruneResourcesFromFlags = (flags) => ({
+	containers: flags.noContainers !== true,
+	networks: flags.noNetworks !== true,
+	volumes: flags.noVolumes !== true,
+	images: flags.includeImages === true
+});
+const optionalEnv = (value, env, key) => value ?? env[key];
+const makeGlobalFlags = (ctx, flags, rest) => {
+	const networkRaw = optionalEnv(flags.network, ctx.env, ENV_VARS.NETWORK);
+	let network;
+	if (networkRaw !== void 0) try {
+		network = parseDevstackNetworkName(networkRaw, flags.network === void 0 ? ENV_VARS.NETWORK : "--network");
+	} catch (cause) {
+		throw cause instanceof Error ? new CliUsageError({ message: cause.message }) : new CliInternalError({
+			message: "failed to parse network flag",
+			cause
+		});
+	}
+	return {
+		outputMode: outputModeFrom(flags, ctx.env),
+		app: optionalEnv(flags.app, ctx.env, ENV_VARS.APP),
+		stack: optionalEnv(flags.stack, ctx.env, ENV_VARS.STACK),
+		stateDir: optionalEnv(flags.stateDir, ctx.env, ENV_VARS.STATE_DIR),
+		configPath: optionalEnv(flags.config, ctx.env, ENV_VARS.CONFIG_PATH),
+		network,
+		renderer: flags.renderer,
+		dryRun: flags.dryRun === true,
+		confirm: {
+			assumeYes: flags.yes === true,
+			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;
+});
+const runCommandEffect = async (ctx, command, flags, effect) => {
+	const program = setNetworkEnv(flags).pipe(Effect.andThen(effect), Effect.catch((error) => emitFailure(ctx.io, flags.outputMode, {
+		command,
+		elapsedMs: 0,
+		error
+	}).pipe(Effect.as({ exitCode: exitCodeFor(error) }))), Effect.catchCause((cause) => emitFailure(ctx.io, flags.outputMode, {
+		command,
+		elapsedMs: 0,
+		error: new CliInternalError({ message: "unexpected internal failure" }),
+		cause
+	}).pipe(Effect.as({ exitCode: 70 }))));
+	const result = await Effect.runPromise(program);
+	if (ctx.io.lastExitCode() === null) await Effect.runPromise(ctx.io.setExitCode(result.exitCode));
+};
+const runWithFlags = async (ctx, command, rawFlags, rest, effect) => {
+	let flags;
+	try {
+		flags = makeGlobalFlags(ctx, rawFlags, rest);
+	} catch (cause) {
+		const error = cause instanceof CliUsageError ? cause : new CliInternalError({
+			message: "failed to resolve CLI flags",
+			cause
+		});
+		const mode = outputModeFrom(rawFlags, ctx.env);
+		await Effect.runPromise(emitFailure(ctx.io, mode, {
+			command,
+			elapsedMs: 0,
+			error
+		}));
+		return;
+	}
+	await runCommandEffect(ctx, command, flags, effect(flags));
+};
+const requiredPositional = (placeholder, brief) => ({
+	parse: textParser,
+	placeholder,
+	brief
+});
+const optionalPositional = (placeholder, brief) => ({
+	parse: textParser,
+	placeholder,
+	brief,
+	optional: true
+});
+const app = buildApplication(buildRouteMap({
+	routes: {
+		up: buildCommand({
+			parameters: { flags: {
+				...configFlagParams,
+				renderer: {
+					kind: "parsed",
+					parse: rendererParser,
+					optional: true,
+					placeholder: "tui|plain|silent",
+					brief: "Select the attached renderer"
+				}
+			} },
+			docs: { brief: "Boot a stack and stay attached until interrupted" },
+			func: function(flags) {
+				return runWithFlags(this, "up", flags, [], (global) => this.deps.up.run(global));
+			}
+		}),
+		apply: buildCommand({
+			parameters: { flags: configFlagParams },
+			docs: { brief: "Reconcile a live stack or run one-shot setup" },
+			func: function(flags) {
+				return runWithFlags(this, "apply", flags, [], (global) => this.deps.apply.run(global));
+			}
+		}),
+		status: buildCommand({
+			parameters: { flags: identityFlagParams },
+			docs: { brief: "Show the persisted stack projection" },
+			func: function(flags) {
+				return runWithFlags(this, "status", flags, [], (global) => runStatus(this.deps.status, {
+					flags: global,
+					io: this.io
+				}));
+			}
+		}),
+		doctor: buildCommand({
+			parameters: { flags: identityFlagParams },
+			docs: { brief: "Run host and stack preflight checks" },
+			func: function(flags) {
+				return runWithFlags(this, "doctor", flags, [], (global) => runDoctor(this.deps.doctor, {
+					flags: global,
+					io: this.io
+				}));
+			}
+		}),
+		config: buildCommand({
+			parameters: { flags: configFlagParams },
+			docs: { brief: "Print resolved config inputs" },
+			func: function(flags) {
+				return runWithFlags(this, "config", flags, [], (global) => runConfig(this.deps.config, {
+					flags: global,
+					io: this.io
+				}));
+			}
+		}),
+		schema: buildCommand({
+			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))));
+			}
+		}),
+		snapshot: buildRouteMap({
+			routes: {
+				save: buildCommand({
+					parameters: {
+						flags: {
+							...configFlagParams,
+							name: stringFlag("Human-readable snapshot name", "name")
+						},
+						positional: {
+							kind: "tuple",
+							parameters: [optionalPositional("name", "snapshot name")]
+						}
+					},
+					docs: { brief: "Capture a snapshot" },
+					func: function(flags, snapshotName) {
+						const rest = [
+							"save",
+							...snapshotName === void 0 ? [] : [snapshotName],
+							...flags.name === void 0 ? [] : ["--name", flags.name]
+						];
+						return runWithFlags(this, "snapshot save", flags, rest, (global) => runSnapshot(this.deps.snapshot, {
+							flags: global,
+							io: this.io
+						}));
+					}
+				}),
+				restore: buildCommand({
+					parameters: {
+						flags: confirmFlagParams,
+						positional: {
+							kind: "tuple",
+							parameters: [requiredPositional("name-or-id", "snapshot name or id")]
+						}
+					},
+					docs: { brief: "Restore a snapshot" },
+					func: function(flags, snapshotRef) {
+						return runWithFlags(this, "snapshot restore", flags, ["restore", snapshotRef], (global) => runSnapshot(this.deps.snapshot, {
+							flags: global,
+							io: this.io
+						}));
+					}
+				}),
+				list: buildCommand({
+					parameters: { flags: identityFlagParams },
+					docs: { brief: "List snapshots" },
+					func: function(flags) {
+						return runWithFlags(this, "snapshot list", flags, ["list"], (global) => runSnapshot(this.deps.snapshot, {
+							flags: global,
+							io: this.io
+						}));
+					}
+				}),
+				delete: buildCommand({
+					parameters: {
+						flags: confirmFlagParams,
+						positional: {
+							kind: "tuple",
+							parameters: [requiredPositional("name-or-id", "snapshot name or id")]
+						}
+					},
+					docs: { brief: "Delete a snapshot" },
+					func: function(flags, snapshotRef) {
+						return runWithFlags(this, "snapshot delete", flags, ["delete", snapshotRef], (global) => runSnapshot(this.deps.snapshot, {
+							flags: global,
+							io: this.io
+						}));
+					}
+				})
+			},
+			docs: { brief: "Capture, restore, list, or delete stack snapshots" }
+		}),
+		prune: buildCommand({
+			parameters: { flags: pruneFlagParams },
+			docs: { brief: "Inventory and prune devstack-labelled Docker resources" },
+			func: function(flags) {
+				return runWithFlags(this, "prune", flags, [], (global) => runPrune(this.deps.prune, {
+					flags: global,
+					io: this.io
+				}, {
+					mode: flags.list === true ? "list" : flags.all === true ? "all" : "auto",
+					resources: pruneResourcesFromFlags(flags)
+				}));
+			}
+		}),
+		wipe: buildCommand({
+			parameters: { flags: destructiveFlagParams },
+			docs: { brief: "Destroy all state for the selected stack" },
+			func: function(flags) {
+				return runWithFlags(this, "wipe", flags, [], (global) => runWipe(this.deps.wipe, {
+					flags: global,
+					io: this.io
+				}));
+			}
+		})
+	},
+	docs: { brief: "Sui development stack CLI" }
+}), {
+	name: "devstack",
+	versionInfo: { currentVersion: "0.0.0" },
+	scanner: { caseStyle: "allow-kebab-for-camel" },
+	documentation: {
+		caseStyle: "convert-camel-to-kebab",
+		disableAnsiColor: true,
+		onlyRequiredInUsageLine: true
+	},
+	localization: { loadText: () => ({
+		...text_en,
+		exceptionWhileParsingArguments: (error) => error instanceof Error ? error.message : String(error)
+	}) }
+});
+const jsonRequested = (argv, env) => env[ENV_VARS.JSON] === "1" || argv.includes("--json");
+const normalizeStricliExitCode = (code) => {
+	if (typeof code === "number" && code !== 0) return 64;
+	return 0;
+};
+const flushBufferedProcess = (process, io, argv, env) => Effect.gen(function* () {
+	const exitCode = normalizeStricliExitCode(process.exitCode);
+	const stdout = process.stdoutBuffer.join("");
+	const stderr = process.stderrBuffer.join("").trim();
+	if (exitCode !== 0 && jsonRequested(argv, env)) {
+		yield* emitFailure(io, "json", {
+			command: "(parse)",
+			elapsedMs: 0,
+			error: new CliUsageError({ message: stderr.length > 0 ? stderr : "invalid command line" })
+		});
+		return;
+	}
+	if (stdout.length > 0) yield* io.writeStdout(stdout.endsWith("\n") ? stdout.slice(0, -1) : stdout);
+	if (stderr.length > 0) yield* io.writeStderr(stderr);
+	yield* io.setExitCode(exitCode);
+});
+const dispatch = (deps, dispatchEnv) => Effect.gen(function* () {
+	const io = trackIO(dispatchEnv.io ?? nodeProcessIO);
+	const process = makeBufferedProcess(dispatchEnv.env);
+	const ctx = {
+		process,
+		deps,
+		env: dispatchEnv.env,
+		stdinIsTty: dispatchEnv.stdinIsTty,
+		io
+	};
+	yield* Effect.tryPromise({
+		try: () => run(app, dispatchEnv.argv, ctx),
+		catch: (cause) => new CliInternalError({
+			message: "CLI dispatcher failed",
+			cause
+		})
+	}).pipe(Effect.catch((error) => emitFailure(io, jsonRequested(dispatchEnv.argv, dispatchEnv.env) ? "json" : "human", {
+		command: "(dispatch)",
+		elapsedMs: 0,
+		error
+	})));
+	if (!io.touched()) yield* flushBufferedProcess(process, io, dispatchEnv.argv, dispatchEnv.env);
+});
+//#endregion
+export { dispatch };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +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":"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"}

package/dist/surfaces/cli/output.mjs

@@ -0,0 +1,115 @@
+import { formatCause, formatValue } from "../../substrate/runtime/observability/cascade-formatter.mjs";
+import { exitCodeFor, hintFor, summaryFor } from "./errors.mjs";
+import { failureEnvelope, successEnvelope } from "./envelope.mjs";
+import { Effect } from "effect";
+//#region src/surfaces/cli/output.ts
+/** Default IO bound to the Node process. */
+const nodeProcessIO = {
+	writeStdout: (line) => Effect.sync(() => {
+		process.stdout.write(line.endsWith("\n") ? line : `${line}\n`);
+	}),
+	writeStderr: (line) => Effect.sync(() => {
+		process.stderr.write(line.endsWith("\n") ? line : `${line}\n`);
+	}),
+	setExitCode: (code) => Effect.sync(() => {
+		process.exitCode = code;
+	})
+};
+/**
+* `JSON.stringify` strips `undefined` from objects but NOT from
+* arrays (replaces with `null`). The envelope builders already omit
+* absent keys, but we add a guard so a future builder bug doesn't
+* leak `undefined` into automation output.
+*
+* Architecture: "Absent fields are OMITTED from serialized output (no
+* `undefined`)." This function enforces that promise.
+*/
+const serializeEnvelope = (env) => {
+	const cleaned = stripUndefined(env);
+	return JSON.stringify(cleaned);
+};
+const stripUndefined = (value) => {
+	if (value === void 0) return void 0;
+	if (value === null) return null;
+	if (Array.isArray(value)) return value.map(stripUndefined);
+	if (typeof value !== "object") return value;
+	const out = {};
+	for (const [k, v] of Object.entries(value)) {
+		if (v === void 0) continue;
+		out[k] = stripUndefined(v);
+	}
+	return out;
+};
+/**
+* Emit a success envelope OR a human-mode line block. Sets exit code
+* 0 unless a streaming success path supplies its own process code.
+*
+* In JSON mode: one envelope on stdout, nothing on stderr.
+* In human mode: each `humanLines` entry on stdout; hints rendered
+* after; no envelope.
+*/
+const emitSuccess = (io, mode, params) => Effect.gen(function* () {
+	if (mode === "json") {
+		const env = successEnvelope({
+			command: params.command,
+			elapsedMs: params.elapsedMs,
+			data: params.data,
+			hints: params.hints,
+			dryRun: params.dryRun
+		});
+		yield* io.writeStdout(serializeEnvelope(env));
+	} else {
+		for (const line of params.humanLines ?? []) yield* io.writeStdout(line);
+		for (const hint of params.hints ?? []) yield* io.writeStdout(`hint: ${hint}`);
+	}
+	yield* io.setExitCode(params.exitCode ?? 0);
+});
+/**
+* Emit a failure for a `CliError`. Threads the sysexit code through
+* to `process.exitCode`. Honors the already-reported sentinel.
+*
+* Architecture invariant: "Top-level error rendering must not
+* double-print when a subcommand already rendered." — we still set the
+* exit code but skip the envelope/stderr write.
+*/
+const emitFailure = (io, mode, params) => Effect.gen(function* () {
+	const exitCode = exitCodeFor(params.error);
+	if (params.error._tag === "CliAlreadyReportedError") {
+		yield* io.setExitCode(exitCode);
+		return;
+	}
+	yield* renderFailure(io, mode, {
+		command: params.command,
+		elapsedMs: params.elapsedMs,
+		exitCode,
+		summary: summaryFor(params.error),
+		hint: hintFor(params.error),
+		cause: params.cause,
+		errorCause: "cause" in params.error ? params.error.cause : void 0,
+		dryRun: params.dryRun
+	});
+	yield* io.setExitCode(exitCode);
+});
+const renderFailure = (io, mode, p) => Effect.gen(function* () {
+	const chain = (p.cause !== void 0 ? formatCause(p.cause) : p.errorCause !== void 0 ? formatValue(p.errorCause) : void 0)?.split("\n").filter((l) => l.length > 0);
+	if (mode === "json") {
+		const fp = {
+			command: p.command,
+			elapsedMs: p.elapsedMs,
+			exitCode: p.exitCode,
+			summary: p.summary,
+			hint: p.hint,
+			chain,
+			dryRun: p.dryRun
+		};
+		yield* io.writeStdout(serializeEnvelope(failureEnvelope(fp)));
+		return;
+	}
+	yield* io.writeStderr(`error: ${p.summary}`);
+	if (p.hint !== void 0) yield* io.writeStderr(`hint: ${p.hint}`);
+	if (chain !== void 0 && chain.length > 0) for (const line of chain) yield* io.writeStderr(`  ${line}`);
+});
+//#endregion
+export { emitFailure, emitSuccess, nodeProcessIO };
+
+//# sourceMappingURL=output.mjs.map

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

@@ -0,0 +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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"}