@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1,141 @@
+import { CliInternalError, CliSnapshotAmbiguousError, CliSnapshotNotFoundError, CliUsageError, isCliError } from "../errors.mjs";
+import { takePositional, takeValueFlag } from "../flags.mjs";
+import { emitSuccess } from "../output.mjs";
+import { confirmDestructive } from "./confirm.mjs";
+import { Effect } from "effect";
+//#region src/surfaces/cli/commands/snapshot.ts
+/** Snapshot subcommand dispatcher. `ctx.flags.rest` holds the
+*  sub-verb + verb-local arguments. */
+const runSnapshot = (deps, ctx) => Effect.gen(function* () {
+	const [sub, ...rest] = ctx.flags.rest;
+	switch (sub) {
+		case "save": return yield* runSnapshotSave(deps, ctx, rest);
+		case "restore": return yield* runSnapshotRestore(deps, ctx, rest);
+		case "list": return yield* runSnapshotList(deps, ctx);
+		case "delete": return yield* runSnapshotDelete(deps, ctx, rest);
+		default: return yield* Effect.fail(new CliUsageError({
+			message: `unknown snapshot subcommand: ${sub ?? "(missing)"}`,
+			hint: "try: snapshot save [name] | restore <name-or-id> | list | delete <name-or-id>"
+		}));
+	}
+}).pipe(Effect.withSpan("cli.snapshot"));
+const runSnapshotSave = (deps, ctx, rest) => Effect.gen(function* () {
+	const started = Date.now();
+	const { value: flagName, tail: afterName } = takeValueFlag(rest, "name");
+	const { head: positionalName, tail: afterSnapshotName } = takePositional(afterName);
+	const extra = afterSnapshotName.find((tok) => !tok.startsWith("-"));
+	if (extra !== void 0) return yield* Effect.fail(new CliUsageError({
+		message: `unexpected snapshot save argument: ${extra}`,
+		hint: "try: snapshot save [name]"
+	}));
+	if (flagName !== void 0 && positionalName !== void 0) return yield* Effect.fail(new CliUsageError({
+		message: "snapshot save accepts a name either positionally or with --name, not both",
+		hint: "try: snapshot save [name]"
+	}));
+	const name = flagName ?? positionalName;
+	const captured = yield* deps.capture({
+		...name === void 0 ? {} : { name },
+		...ctx.flags.configPath === void 0 ? {} : { configPath: ctx.flags.configPath }
+	}).pipe(Effect.catch((cause) => isCliError(cause) ? Effect.fail(cause) : isSnapshotInputError(cause) ? Effect.fail(snapshotInputCliError(cause)) : Effect.fail(new CliInternalError({
+		message: "snapshot capture failed",
+		cause
+	}))));
+	yield* emitSuccess(ctx.io, ctx.flags.outputMode, {
+		command: "snapshot save",
+		elapsedMs: Date.now() - started,
+		data: {
+			snapshotId: captured.snapshotId,
+			name: captured.name
+		},
+		humanLines: [`snapshot saved ${captured.name} (${captured.snapshotId})`]
+	});
+	return { exitCode: 0 };
+});
+const runSnapshotRestore = (deps, ctx, rest) => Effect.gen(function* () {
+	const started = Date.now();
+	const snapshotRef = rest.find((tok) => !tok.startsWith("-"));
+	if (snapshotRef === void 0) return yield* Effect.fail(new CliUsageError({
+		message: "snapshot restore requires a snapshot name or id",
+		hint: "snapshot list to enumerate available names and ids"
+	}));
+	const resolved = yield* deps.reader.resolve(snapshotRef);
+	if (resolved.tag === "not-found") return yield* Effect.fail(new CliSnapshotNotFoundError({ snapshotRef }));
+	if (resolved.tag === "ambiguous") return yield* Effect.fail(new CliSnapshotAmbiguousError({
+		snapshotRef,
+		matches: resolved.matches.map((entry) => entry.snapshotId)
+	}));
+	const entry = resolved.entry;
+	const snapshotId = entry.snapshotId;
+	yield* confirmDestructive(deps.confirm, ctx, {
+		verb: "snapshot restore",
+		prompt: entry.name === null ? `Restore snapshot ${snapshotId} and replace current stack state?` : `Restore snapshot ${entry.name} (${snapshotId}) and replace current stack state?`,
+		skipWhenDryRun: false
+	});
+	yield* deps.restore(snapshotId).pipe(Effect.catch((cause) => isCliError(cause) ? Effect.fail(cause) : Effect.fail(new CliInternalError({
+		message: "snapshot restore failed",
+		cause
+	}))));
+	yield* emitSuccess(ctx.io, ctx.flags.outputMode, {
+		command: "snapshot restore",
+		elapsedMs: Date.now() - started,
+		data: {
+			snapshotId,
+			name: entry.name
+		},
+		humanLines: [entry.name === null ? `snapshot restored ${snapshotId}` : `snapshot restored ${entry.name} (${snapshotId})`]
+	});
+	return { exitCode: 0 };
+});
+const runSnapshotList = (deps, ctx) => Effect.gen(function* () {
+	const started = Date.now();
+	const entries = yield* deps.reader.list();
+	const humanLines = entries.length === 0 ? ["(no snapshots)"] : entries.map((e) => `${e.name ?? "(unnamed)"}  ${e.snapshotId}  ${new Date(e.createdAt).toISOString()}`);
+	yield* emitSuccess(ctx.io, ctx.flags.outputMode, {
+		command: "snapshot list",
+		elapsedMs: Date.now() - started,
+		data: { entries },
+		humanLines
+	});
+	return { exitCode: 0 };
+});
+const runSnapshotDelete = (deps, ctx, rest) => Effect.gen(function* () {
+	const started = Date.now();
+	const snapshotRef = rest.find((tok) => !tok.startsWith("-"));
+	if (snapshotRef === void 0) return yield* Effect.fail(new CliUsageError({ message: "snapshot delete requires a snapshot name or id" }));
+	const resolved = yield* deps.reader.resolve(snapshotRef);
+	if (resolved.tag === "not-found") return yield* Effect.fail(new CliSnapshotNotFoundError({ snapshotRef }));
+	if (resolved.tag === "ambiguous") return yield* Effect.fail(new CliSnapshotAmbiguousError({
+		snapshotRef,
+		matches: resolved.matches.map((entry) => entry.snapshotId)
+	}));
+	const entry = resolved.entry;
+	const snapshotId = entry.snapshotId;
+	yield* confirmDestructive(deps.confirm, ctx, {
+		verb: "snapshot delete",
+		prompt: entry.name === null ? `Delete snapshot ${snapshotId}?` : `Delete snapshot ${entry.name} (${snapshotId})?`,
+		skipWhenDryRun: false
+	});
+	yield* deps.delete(snapshotId).pipe(Effect.catch((cause) => isCliError(cause) ? Effect.fail(cause) : Effect.fail(new CliInternalError({
+		message: "snapshot delete failed",
+		cause
+	}))));
+	yield* emitSuccess(ctx.io, ctx.flags.outputMode, {
+		command: "snapshot delete",
+		elapsedMs: Date.now() - started,
+		data: {
+			snapshotId,
+			name: entry.name
+		},
+		humanLines: [entry.name === null ? `snapshot deleted ${snapshotId}` : `snapshot deleted ${entry.name} (${snapshotId})`]
+	});
+	return { exitCode: 0 };
+});
+const isSnapshotInputError = (value) => typeof value === "object" && value !== null && value._tag === "SnapshotIdError";
+const snapshotInputCliError = (error) => new CliUsageError({
+	message: `invalid snapshot ${error.field} for ${error.operation}: ${error.value}`,
+	hint: error.detail
+});
+//#endregion
+export { runSnapshot };
+
+//# sourceMappingURL=snapshot.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/snapshot.ts"],"sourcesContent":["// CLI verb: `devstack snapshot {save|restore|list|delete}`.\n//\n// Architecture (distilled/20-cli.md § Subcommands § Persistence):\n//   \"snapshot save / restore / list / delete — capture, rehydrate,\n//    enumerate, remove point-in-time captures of a stack.\"\n//\n// Surface-equality: snapshot is a peer command on the typed command\n// channel (`snapshot.capture` / `restore` / `list` / `delete`). The\n// CLI publishes; the L3 snapshot orchestrator (architecture § L3)\n// consumes — same code path for TUI / programmable API.\n\nimport { Effect } from 'effect';\n\nimport {\n\ttype CliError,\n\tCliSnapshotAmbiguousError,\n\tCliInternalError,\n\tCliSnapshotNotFoundError,\n\tCliUsageError,\n\tisCliError,\n} from '../errors.ts';\nimport { takePositional, takeValueFlag } from '../flags.ts';\nimport { emitSuccess } from '../output.ts';\nimport { confirmDestructive, type ConfirmPrompt } from './confirm.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\n/** Snapshot read seam. The list verb reads the catalog without going\n *  through the command channel — same observation discipline as\n *  `status`: read-only views are equal across surfaces. */\nexport interface SnapshotReader {\n\treadonly list: () => Effect.Effect<ReadonlyArray<SnapshotEntry>>;\n\treadonly resolve: (snapshotRef: string) => Effect.Effect<SnapshotResolveResult>;\n}\n\nexport interface SnapshotEntry {\n\treadonly snapshotId: string;\n\treadonly name: string | null;\n\treadonly createdAt: number;\n\treadonly size: number | null;\n}\n\nexport type SnapshotResolveResult =\n\t| { readonly tag: 'found'; readonly entry: SnapshotEntry }\n\t| { readonly tag: 'not-found' }\n\t| {\n\t\t\treadonly tag: 'ambiguous';\n\t\t\treadonly snapshotRef: string;\n\t\t\treadonly matches: ReadonlyArray<SnapshotEntry>;\n\t  };\n\nexport interface SnapshotCaptureResult {\n\treadonly snapshotId: string;\n\treadonly name: string;\n}\n\nexport interface SnapshotDeps {\n\treadonly reader: SnapshotReader;\n\treadonly capture: (args: {\n\t\treadonly snapshotId?: string;\n\t\treadonly name?: string;\n\t\treadonly configPath?: string;\n\t}) => Effect.Effect<SnapshotCaptureResult, unknown>;\n\treadonly restore: (snapshotId: string) => Effect.Effect<void, unknown>;\n\treadonly delete: (snapshotId: string) => Effect.Effect<void, unknown>;\n\treadonly confirm: ConfirmPrompt;\n}\n\n/** Snapshot subcommand dispatcher. `ctx.flags.rest` holds the\n *  sub-verb + verb-local arguments. */\nexport const runSnapshot = (\n\tdeps: SnapshotDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst [sub, ...rest] = ctx.flags.rest;\n\t\tswitch (sub) {\n\t\t\tcase 'save':\n\t\t\t\treturn yield* runSnapshotSave(deps, ctx, rest);\n\t\t\tcase 'restore':\n\t\t\t\treturn yield* runSnapshotRestore(deps, ctx, rest);\n\t\t\tcase 'list':\n\t\t\t\treturn yield* runSnapshotList(deps, ctx);\n\t\t\tcase 'delete':\n\t\t\t\treturn yield* runSnapshotDelete(deps, ctx, rest);\n\t\t\tdefault:\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew CliUsageError({\n\t\t\t\t\t\tmessage: `unknown snapshot subcommand: ${sub ?? '(missing)'}`,\n\t\t\t\t\t\thint: 'try: snapshot save [name] | restore <name-or-id> | list | delete <name-or-id>',\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t}\n\t}).pipe(Effect.withSpan('cli.snapshot'));\n\nconst runSnapshotSave = (\n\tdeps: SnapshotDeps,\n\tctx: CommandContext,\n\trest: ReadonlyArray<string>,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst { value: flagName, tail: afterName } = takeValueFlag(rest, 'name');\n\t\tconst { head: positionalName, tail: afterSnapshotName } = takePositional(afterName);\n\t\tconst extra = afterSnapshotName.find((tok) => !tok.startsWith('-'));\n\t\tif (extra !== undefined) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliUsageError({\n\t\t\t\t\tmessage: `unexpected snapshot save argument: ${extra}`,\n\t\t\t\t\thint: 'try: snapshot save [name]',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tif (flagName !== undefined && positionalName !== undefined) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliUsageError({\n\t\t\t\t\tmessage: 'snapshot save accepts a name either positionally or with --name, not both',\n\t\t\t\t\thint: 'try: snapshot save [name]',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst name = flagName ?? positionalName;\n\t\tconst captured = yield* deps\n\t\t\t.capture({\n\t\t\t\t...(name === undefined ? {} : { name }),\n\t\t\t\t...(ctx.flags.configPath === undefined ? {} : { configPath: ctx.flags.configPath }),\n\t\t\t})\n\t\t\t.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: isSnapshotInputError(cause)\n\t\t\t\t\t\t\t? Effect.fail(snapshotInputCliError(cause))\n\t\t\t\t\t\t\t: Effect.fail(new CliInternalError({ message: 'snapshot capture failed', cause })),\n\t\t\t\t),\n\t\t\t);\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'snapshot save',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata: {\n\t\t\t\tsnapshotId: captured.snapshotId,\n\t\t\t\tname: captured.name,\n\t\t\t},\n\t\t\thumanLines: [`snapshot saved ${captured.name} (${captured.snapshotId})`],\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t});\n\nconst runSnapshotRestore = (\n\tdeps: SnapshotDeps,\n\tctx: CommandContext,\n\trest: ReadonlyArray<string>,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst snapshotRef = rest.find((tok) => !tok.startsWith('-'));\n\t\tif (snapshotRef === undefined) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliUsageError({\n\t\t\t\t\tmessage: 'snapshot restore requires a snapshot name or id',\n\t\t\t\t\thint: 'snapshot list to enumerate available names and ids',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst resolved = yield* deps.reader.resolve(snapshotRef);\n\t\tif (resolved.tag === 'not-found') {\n\t\t\treturn yield* Effect.fail(new CliSnapshotNotFoundError({ snapshotRef }));\n\t\t}\n\t\tif (resolved.tag === 'ambiguous') {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliSnapshotAmbiguousError({\n\t\t\t\t\tsnapshotRef,\n\t\t\t\t\tmatches: resolved.matches.map((entry) => entry.snapshotId),\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst entry = resolved.entry;\n\t\tconst snapshotId = entry.snapshotId;\n\t\tyield* confirmDestructive(deps.confirm, ctx, {\n\t\t\tverb: 'snapshot restore',\n\t\t\tprompt:\n\t\t\t\tentry.name === null\n\t\t\t\t\t? `Restore snapshot ${snapshotId} and replace current stack state?`\n\t\t\t\t\t: `Restore snapshot ${entry.name} (${snapshotId}) and replace current stack state?`,\n\t\t\tskipWhenDryRun: false,\n\t\t});\n\t\tyield* deps\n\t\t\t.restore(snapshotId)\n\t\t\t.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(new CliInternalError({ message: 'snapshot restore failed', cause })),\n\t\t\t\t),\n\t\t\t);\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'snapshot restore',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata: { snapshotId, name: entry.name },\n\t\t\thumanLines: [\n\t\t\t\tentry.name === null\n\t\t\t\t\t? `snapshot restored ${snapshotId}`\n\t\t\t\t\t: `snapshot restored ${entry.name} (${snapshotId})`,\n\t\t\t],\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t});\n\nconst runSnapshotList = (\n\tdeps: SnapshotDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst entries = yield* deps.reader.list();\n\t\tconst humanLines =\n\t\t\tentries.length === 0\n\t\t\t\t? ['(no snapshots)']\n\t\t\t\t: entries.map(\n\t\t\t\t\t\t(e) =>\n\t\t\t\t\t\t\t`${e.name ?? '(unnamed)'}  ${e.snapshotId}  ${new Date(e.createdAt).toISOString()}`,\n\t\t\t\t\t);\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'snapshot list',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata: { entries },\n\t\t\thumanLines,\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t});\n\nconst runSnapshotDelete = (\n\tdeps: SnapshotDeps,\n\tctx: CommandContext,\n\trest: ReadonlyArray<string>,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst snapshotRef = rest.find((tok) => !tok.startsWith('-'));\n\t\tif (snapshotRef === undefined) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliUsageError({ message: 'snapshot delete requires a snapshot name or id' }),\n\t\t\t);\n\t\t}\n\t\tconst resolved = yield* deps.reader.resolve(snapshotRef);\n\t\tif (resolved.tag === 'not-found') {\n\t\t\treturn yield* Effect.fail(new CliSnapshotNotFoundError({ snapshotRef }));\n\t\t}\n\t\tif (resolved.tag === 'ambiguous') {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliSnapshotAmbiguousError({\n\t\t\t\t\tsnapshotRef,\n\t\t\t\t\tmatches: resolved.matches.map((entry) => entry.snapshotId),\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst entry = resolved.entry;\n\t\tconst snapshotId = entry.snapshotId;\n\t\tyield* confirmDestructive(deps.confirm, ctx, {\n\t\t\tverb: 'snapshot delete',\n\t\t\tprompt:\n\t\t\t\tentry.name === null\n\t\t\t\t\t? `Delete snapshot ${snapshotId}?`\n\t\t\t\t\t: `Delete snapshot ${entry.name} (${snapshotId})?`,\n\t\t\tskipWhenDryRun: false,\n\t\t});\n\t\tyield* deps\n\t\t\t.delete(snapshotId)\n\t\t\t.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(new CliInternalError({ message: 'snapshot delete failed', cause })),\n\t\t\t\t),\n\t\t\t);\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'snapshot delete',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata: { snapshotId, name: entry.name },\n\t\t\thumanLines: [\n\t\t\t\tentry.name === null\n\t\t\t\t\t? `snapshot deleted ${snapshotId}`\n\t\t\t\t\t: `snapshot deleted ${entry.name} (${snapshotId})`,\n\t\t\t],\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t});\n\ninterface SnapshotInputErrorShape {\n\treadonly _tag: 'SnapshotIdError';\n\treadonly operation: string;\n\treadonly field: string;\n\treadonly value: string;\n\treadonly detail: string;\n}\n\nconst isSnapshotInputError = (value: unknown): value is SnapshotInputErrorShape =>\n\ttypeof value === 'object' &&\n\tvalue !== null &&\n\t(value as { readonly _tag?: unknown })._tag === 'SnapshotIdError';\n\nconst snapshotInputCliError = (error: SnapshotInputErrorShape): CliUsageError =>\n\tnew CliUsageError({\n\t\tmessage: `invalid snapshot ${error.field} for ${error.operation}: ${error.value}`,\n\t\thint: error.detail,\n\t});\n"],"mappings":"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"}

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

@@ -0,0 +1,95 @@
+import { emitSuccess } from "../output.mjs";
+import { Effect } from "effect";
+//#region src/surfaces/cli/commands/status.ts
+/** Pure projection: `SubscribableState` → JSON-safe status blob.
+*  Never leaks substrate types. */
+const buildStatusPayload = (state) => {
+	if (state === null) return {
+		present: false,
+		identity: null,
+		cycle: null,
+		rowCount: 0,
+		endpointCount: 0,
+		accountCount: 0,
+		packageCount: 0,
+		errorCount: 0
+	};
+	return {
+		present: true,
+		identity: { ...state.identity },
+		cycle: { ...state.cycle },
+		rowCount: state.rows.length,
+		endpointCount: state.endpoints.length,
+		accountCount: state.accounts.length,
+		packageCount: state.packages.length,
+		errorCount: state.errors.length,
+		rows: state.rows.map((r) => ({
+			key: r.key,
+			role: r.role,
+			status: r.status,
+			phase: r.phase,
+			lastErrorTag: r.lastError?.tag ?? null
+		})),
+		endpoints: state.endpoints.map((e) => ({
+			endpointKey: e.endpointKey,
+			name: e.name,
+			url: e.displayUrl ?? e.url
+		})),
+		accounts: state.accounts.map((account) => ({
+			key: account.key,
+			rowKey: account.rowKey,
+			name: account.name,
+			address: account.address,
+			scheme: account.scheme,
+			source: account.source,
+			funding: { ...account.funding },
+			walletVisible: account.walletVisible
+		})),
+		packages: state.packages.map((pkg) => ({
+			key: pkg.key,
+			rowKey: pkg.rowKey,
+			name: pkg.name,
+			kind: pkg.kind,
+			packageId: pkg.packageId,
+			upgradeCapId: pkg.upgradeCapId,
+			mvrPlaceholder: pkg.mvrPlaceholder,
+			sourcePath: pkg.sourcePath
+		}))
+	};
+};
+/**
+* Run `devstack status`. Tolerant of missing state. Always succeeds
+* (returns ok=true) unless the projection read itself raises (which
+* the reader contractually swallows for missing files).
+*/
+const runStatus = (deps, ctx) => Effect.gen(function* () {
+	const started = Date.now();
+	const app = ctx.flags.app ?? "";
+	const stack = ctx.flags.stack ?? "";
+	const data = buildStatusPayload(yield* deps.reader.readState(app, stack));
+	const elapsedMs = Date.now() - started;
+	const humanLines = [];
+	if (!data.present) humanLines.push(`status: no state present for ${app || "(no app)"} / ${stack || "(no stack)"}`);
+	else {
+		humanLines.push(`app:     ${data.identity.app}`);
+		humanLines.push(`stack:   ${data.identity.stack}`);
+		humanLines.push(`network: ${data.identity.network}`);
+		humanLines.push(`cycle:   #${data.cycle.id} ${data.cycle.phase}`);
+		humanLines.push(`rows:    ${data.rowCount}`);
+		humanLines.push(`endpoints: ${data.endpointCount}`);
+		humanLines.push(`accounts: ${data.accountCount}`);
+		humanLines.push(`packages: ${data.packageCount}`);
+		humanLines.push(`errors:  ${data.errorCount}`);
+	}
+	yield* emitSuccess(ctx.io, ctx.flags.outputMode, {
+		command: "status",
+		elapsedMs,
+		data,
+		humanLines
+	});
+	return { exitCode: 0 };
+}).pipe(Effect.withSpan("cli.status"));
+//#endregion
+export { runStatus };
+
+//# sourceMappingURL=status.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/status.ts"],"sourcesContent":["// CLI verb: `devstack status` — observational read of stack state.\n//\n// Architecture (distilled/20-cli.md § Subcommands § Lifecycle):\n//   \"status — observational read of stack state, manifest, and (if\n//    present) fork meta.\"\n//\n// Surface invariant: status MUST tolerate missing/malformed state\n// files. It describes what IS, not what should be. The architecture\n// explicitly calls this out — throwing on a stack that hasn't been\n// brought up would be a regression.\n\nimport { Effect } from 'effect';\n\nimport type { SubscribableState } from '../../../substrate/projection.ts';\nimport type { CliError } from '../errors.ts';\nimport { emitSuccess } from '../output.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\n/** Pure projection: `SubscribableState` → JSON-safe status blob.\n *  Never leaks substrate types. */\nexport const buildStatusPayload = (state: SubscribableState | null) => {\n\tif (state === null) {\n\t\treturn {\n\t\t\tpresent: false as const,\n\t\t\tidentity: null,\n\t\t\tcycle: null,\n\t\t\trowCount: 0,\n\t\t\tendpointCount: 0,\n\t\t\taccountCount: 0,\n\t\t\tpackageCount: 0,\n\t\t\terrorCount: 0,\n\t\t};\n\t}\n\treturn {\n\t\tpresent: true as const,\n\t\tidentity: { ...state.identity },\n\t\tcycle: { ...state.cycle },\n\t\trowCount: state.rows.length,\n\t\tendpointCount: state.endpoints.length,\n\t\taccountCount: state.accounts.length,\n\t\tpackageCount: state.packages.length,\n\t\terrorCount: state.errors.length,\n\t\trows: state.rows.map((r) => ({\n\t\t\tkey: r.key as string,\n\t\t\trole: r.role,\n\t\t\tstatus: r.status,\n\t\t\tphase: r.phase,\n\t\t\tlastErrorTag: r.lastError?.tag ?? null,\n\t\t})),\n\t\tendpoints: state.endpoints.map((e) => ({\n\t\t\tendpointKey: e.endpointKey as string,\n\t\t\tname: e.name,\n\t\t\turl: e.displayUrl ?? e.url,\n\t\t})),\n\t\taccounts: state.accounts.map((account) => ({\n\t\t\tkey: account.key,\n\t\t\trowKey: account.rowKey,\n\t\t\tname: account.name,\n\t\t\taddress: account.address,\n\t\t\tscheme: account.scheme,\n\t\t\tsource: account.source,\n\t\t\tfunding: { ...account.funding },\n\t\t\twalletVisible: account.walletVisible,\n\t\t})),\n\t\tpackages: state.packages.map((pkg) => ({\n\t\t\tkey: pkg.key,\n\t\t\trowKey: pkg.rowKey,\n\t\t\tname: pkg.name,\n\t\t\tkind: pkg.kind,\n\t\t\tpackageId: pkg.packageId,\n\t\t\tupgradeCapId: pkg.upgradeCapId,\n\t\t\tmvrPlaceholder: pkg.mvrPlaceholder,\n\t\t\tsourcePath: pkg.sourcePath,\n\t\t})),\n\t};\n};\n\n/**\n * Status reader interface. The dispatcher wires this to the\n * substrate's projection ref via a thin reader; tests pass a stub.\n * The CLI never calls engine methods directly — it reads the same\n * projection any peer surface (TUI, programmable API) sees.\n */\nexport interface StatusReader {\n\t/** Resolve current projection for `(app, stack)`. Returns `null`\n\t *  if no state has been written yet — that is a normal, tolerated\n\t *  state for a freshly-defined stack. */\n\treadonly readState: (app: string, stack: string) => Effect.Effect<SubscribableState | null>;\n}\n\nexport interface StatusDeps {\n\treadonly reader: StatusReader;\n}\n\n/**\n * Run `devstack status`. Tolerant of missing state. Always succeeds\n * (returns ok=true) unless the projection read itself raises (which\n * the reader contractually swallows for missing files).\n */\nexport const runStatus = (\n\tdeps: StatusDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\t// Resolve `(app, stack)` from flags. The dispatcher seeds these\n\t\t// from the precedence chain; if both are absent we still render\n\t\t// (the projection reader returns `null`).\n\t\tconst app = ctx.flags.app ?? '';\n\t\tconst stack = ctx.flags.stack ?? '';\n\t\tconst state = yield* deps.reader.readState(app, stack);\n\t\tconst data = buildStatusPayload(state);\n\t\tconst elapsedMs = Date.now() - started;\n\n\t\tconst humanLines: Array<string> = [];\n\t\tif (!data.present) {\n\t\t\thumanLines.push(\n\t\t\t\t`status: no state present for ${app || '(no app)'} / ${stack || '(no stack)'}`,\n\t\t\t);\n\t\t} else {\n\t\t\thumanLines.push(`app:     ${data.identity!.app}`);\n\t\t\thumanLines.push(`stack:   ${data.identity!.stack}`);\n\t\t\thumanLines.push(`network: ${data.identity!.network}`);\n\t\t\thumanLines.push(`cycle:   #${data.cycle!.id} ${data.cycle!.phase}`);\n\t\t\thumanLines.push(`rows:    ${data.rowCount}`);\n\t\t\thumanLines.push(`endpoints: ${data.endpointCount}`);\n\t\t\thumanLines.push(`accounts: ${data.accountCount}`);\n\t\t\thumanLines.push(`packages: ${data.packageCount}`);\n\t\t\thumanLines.push(`errors:  ${data.errorCount}`);\n\t\t}\n\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'status',\n\t\t\telapsedMs,\n\t\t\tdata,\n\t\t\thumanLines,\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t}).pipe(Effect.withSpan('cli.status'));\n"],"mappings":";;;;;AAoBA,MAAa,sBAAsB,UAAoC;AACtE,KAAI,UAAU,KACb,QAAO;EACN,SAAS;EACT,UAAU;EACV,OAAO;EACP,UAAU;EACV,eAAe;EACf,cAAc;EACd,cAAc;EACd,YAAY;EACZ;AAEF,QAAO;EACN,SAAS;EACT,UAAU,EAAE,GAAG,MAAM,UAAU;EAC/B,OAAO,EAAE,GAAG,MAAM,OAAO;EACzB,UAAU,MAAM,KAAK;EACrB,eAAe,MAAM,UAAU;EAC/B,cAAc,MAAM,SAAS;EAC7B,cAAc,MAAM,SAAS;EAC7B,YAAY,MAAM,OAAO;EACzB,MAAM,MAAM,KAAK,KAAK,OAAO;GAC5B,KAAK,EAAE;GACP,MAAM,EAAE;GACR,QAAQ,EAAE;GACV,OAAO,EAAE;GACT,cAAc,EAAE,WAAW,OAAO;GAClC,EAAE;EACH,WAAW,MAAM,UAAU,KAAK,OAAO;GACtC,aAAa,EAAE;GACf,MAAM,EAAE;GACR,KAAK,EAAE,cAAc,EAAE;GACvB,EAAE;EACH,UAAU,MAAM,SAAS,KAAK,aAAa;GAC1C,KAAK,QAAQ;GACb,QAAQ,QAAQ;GAChB,MAAM,QAAQ;GACd,SAAS,QAAQ;GACjB,QAAQ,QAAQ;GAChB,QAAQ,QAAQ;GAChB,SAAS,EAAE,GAAG,QAAQ,SAAS;GAC/B,eAAe,QAAQ;GACvB,EAAE;EACH,UAAU,MAAM,SAAS,KAAK,SAAS;GACtC,KAAK,IAAI;GACT,QAAQ,IAAI;GACZ,MAAM,IAAI;GACV,MAAM,IAAI;GACV,WAAW,IAAI;GACf,cAAc,IAAI;GAClB,gBAAgB,IAAI;GACpB,YAAY,IAAI;GAChB,EAAE;EACH;;;;;;;AAyBF,MAAa,aACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,KAAK,KAAK;CAI1B,MAAM,MAAM,IAAI,MAAM,OAAO;CAC7B,MAAM,QAAQ,IAAI,MAAM,SAAS;CAEjC,MAAM,OAAO,mBAAmB,OADX,KAAK,OAAO,UAAU,KAAK,MAAM,CAChB;CACtC,MAAM,YAAY,KAAK,KAAK,GAAG;CAE/B,MAAM,aAA4B,EAAE;AACpC,KAAI,CAAC,KAAK,QACT,YAAW,KACV,gCAAgC,OAAO,WAAW,KAAK,SAAS,eAChE;MACK;AACN,aAAW,KAAK,YAAY,KAAK,SAAU,MAAM;AACjD,aAAW,KAAK,YAAY,KAAK,SAAU,QAAQ;AACnD,aAAW,KAAK,YAAY,KAAK,SAAU,UAAU;AACrD,aAAW,KAAK,aAAa,KAAK,MAAO,GAAG,GAAG,KAAK,MAAO,QAAQ;AACnE,aAAW,KAAK,YAAY,KAAK,WAAW;AAC5C,aAAW,KAAK,cAAc,KAAK,gBAAgB;AACnD,aAAW,KAAK,aAAa,KAAK,eAAe;AACjD,aAAW,KAAK,aAAa,KAAK,eAAe;AACjD,aAAW,KAAK,YAAY,KAAK,aAAa;;AAG/C,QAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;EAChD,SAAS;EACT;EACA;EACA;EACA,CAAC;AACF,QAAO,EAAE,UAAU,GAAG;EACrB,CAAC,KAAK,OAAO,SAAS,aAAa,CAAC"}

package/dist/surfaces/cli/commands/supervisor-presence.mjs

@@ -0,0 +1,33 @@
+import { checkHolderLiveness } from "../../../substrate/runtime/cross-process/liveness.mjs";
+import { readRoster } from "../../../substrate/runtime/cross-process/roster.mjs";
+import { Effect } from "effect";
+//#region src/surfaces/cli/commands/supervisor-presence.ts
+/**
+* Read `rosterFile` and report whether at least one live holder
+* remains. Returns `{ live: false, pid: null }` when the roster is
+* missing OR all holders are dead-by-liveness-check.
+*
+* Tolerates corrupt rosters: a malformed file is treated as "no
+* live supervisor" — the worst case is the CLI refusing a publish
+* the user could have buffered.
+*/
+const probeSupervisorPresence = (rosterFile) => Effect.gen(function* () {
+	const doc = yield* readRoster(rosterFile).pipe(Effect.catchTag("RosterCorruptError", () => Effect.succeed({
+		version: 1,
+		holders: []
+	})));
+	for (const holder of doc.holders) if ((yield* checkHolderLiveness(holder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") return {
+		live: true,
+		pid: holder.pid,
+		hostname: holder.hostname
+	};
+	return {
+		live: false,
+		pid: null,
+		hostname: null
+	};
+});
+//#endregion
+export { probeSupervisorPresence };
+
+//# sourceMappingURL=supervisor-presence.mjs.map

package/dist/surfaces/cli/commands/supervisor-presence.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-presence.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/supervisor-presence.ts"],"sourcesContent":["// Detect whether a supervisor is currently live for a given stack.\n//\n// The CLI uses this to decide whether a verb should publish via the\n// cross-process command channel (live supervisor: publish + await ack)\n// or use its direct/offline fallback.\n//\n// Detection reads the existing `roster.json` (architecture § Cross-\n// process safety protocol § Roster) and walks holders. A same-host\n// holder with a live PID + matching start-time → supervisor live.\n// Foreign-host holders are conservatively treated as live (NFS-safe\n// default; matches `liveness.ts` discipline).\n\nimport { Effect } from 'effect';\n\nimport {\n\tcheckHolderLiveness,\n\treadRoster,\n\ttype RosterError,\n} from '../../../substrate/runtime/cross-process/index.ts';\n\nexport interface SupervisorPresence {\n\treadonly live: boolean;\n\treadonly pid: number | null;\n\treadonly hostname: string | null;\n}\n\n/**\n * Read `rosterFile` and report whether at least one live holder\n * remains. Returns `{ live: false, pid: null }` when the roster is\n * missing OR all holders are dead-by-liveness-check.\n *\n * Tolerates corrupt rosters: a malformed file is treated as \"no\n * live supervisor\" — the worst case is the CLI refusing a publish\n * the user could have buffered.\n */\nexport const probeSupervisorPresence = (\n\trosterFile: string,\n): Effect.Effect<SupervisorPresence, RosterError> =>\n\tEffect.gen(function* () {\n\t\tconst doc = yield* readRoster(rosterFile).pipe(\n\t\t\tEffect.catchTag('RosterCorruptError', () =>\n\t\t\t\tEffect.succeed({ version: 1 as const, holders: [] }),\n\t\t\t),\n\t\t);\n\t\tfor (const holder of doc.holders) {\n\t\t\tconst liveness = yield* checkHolderLiveness(holder).pipe(\n\t\t\t\tEffect.catch(() => Effect.succeed('alive' as const)),\n\t\t\t);\n\t\t\tif (liveness === 'alive') {\n\t\t\t\treturn { live: true, pid: holder.pid, hostname: holder.hostname };\n\t\t\t}\n\t\t}\n\t\treturn { live: false, pid: null, hostname: null };\n\t});\n"],"mappings":";;;;;;;;;;;;;AAmCA,MAAa,2BACZ,eAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,OAAO,WAAW,WAAW,CAAC,KACzC,OAAO,SAAS,4BACf,OAAO,QAAQ;EAAE,SAAS;EAAY,SAAS,EAAE;EAAE,CAAC,CACpD,CACD;AACD,MAAK,MAAM,UAAU,IAAI,QAIxB,MAAI,OAHoB,oBAAoB,OAAO,CAAC,KACnD,OAAO,YAAY,OAAO,QAAQ,QAAiB,CAAC,CACpD,MACgB,QAChB,QAAO;EAAE,MAAM;EAAM,KAAK,OAAO;EAAK,UAAU,OAAO;EAAU;AAGnE,QAAO;EAAE,MAAM;EAAO,KAAK;EAAM,UAAU;EAAM;EAChD"}

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

@@ -0,0 +1,28 @@
+import { CliInternalError, isCliError } from "../errors.mjs";
+import { emitSuccess } from "../output.mjs";
+import { confirmDestructive } from "./confirm.mjs";
+import { Effect } from "effect";
+//#region src/surfaces/cli/commands/wipe.ts
+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({
+		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"]
+	});
+	return { exitCode: 0 };
+}).pipe(Effect.withSpan("cli.wipe"));
+//#endregion
+export { runWipe };
+
+//# sourceMappingURL=wipe.mjs.map

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

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

package/dist/surfaces/cli/envelope.mjs

@@ -0,0 +1,43 @@
+import { exitCodeName } from "./sysexits.mjs";
+/** Build a success envelope. Optional fields collapse cleanly when
+*  absent — the JSON serializer in `output.ts` strips them. */
+const successEnvelope = (params) => {
+	const env = {
+		schemaVersion: 1,
+		ok: true,
+		command: params.command,
+		elapsedMs: params.elapsedMs
+	};
+	if (params.data !== void 0) env.data = params.data;
+	if (params.hints !== void 0 && params.hints.length > 0) env.hints = params.hints;
+	if (params.dryRun === true) env.dryRun = true;
+	return env;
+};
+/** Build a failure envelope. The numeric `exitCode` is BOTH the
+*  envelope's `error.exitCode` AND the OS exit code the CLI propagates
+*  via `process.exitCode`. */
+const failureEnvelope = (params) => {
+	const error = {
+		code: exitCodeName(params.exitCode),
+		exitCode: params.exitCode,
+		summary: params.summary
+	};
+	if (params.hint !== void 0) error.hint = params.hint;
+	if (params.recipe !== void 0) error.recipe = params.recipe;
+	if (params.chain !== void 0 && params.chain.length > 0) error.chain = params.chain;
+	if (params.context !== void 0) error.context = params.context;
+	const env = {
+		schemaVersion: 1,
+		ok: false,
+		command: params.command,
+		elapsedMs: params.elapsedMs,
+		error
+	};
+	if (params.hints !== void 0 && params.hints.length > 0) env.hints = params.hints;
+	if (params.dryRun === true) env.dryRun = true;
+	return env;
+};
+//#endregion
+export { failureEnvelope, successEnvelope };
+
+//# sourceMappingURL=envelope.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.mjs","names":[],"sources":["../../../src/surfaces/cli/envelope.ts"],"sourcesContent":["// CLI surface — stable JSON envelope.\n//\n// Architecture (distilled/20-cli.md § Output formats / Invariants):\n//   - Exactly one envelope per command on stdout in `--json` mode.\n//   - Schema version pinned; bumped intentionally on breaking changes.\n//   - Absent fields are OMITTED from serialized output (no\n//     `undefined`).\n//   - Envelope must never carry devstack-internal types — no engine\n//     class instances, no raw Effect Causes, no plugin error objects.\n//     The cascade formatter projects causes into the flat error block;\n//     `data` is a JSON-safe blob.\n//\n// The envelope is the CLI's contract with downstream automation\n// (CI, agents, examples). Treat it as a public schema: ANY field-name\n// change is a major version bump.\n\nimport { ExitCode, exitCodeName } from './sysexits.ts';\n\n/**\n * Current envelope schema version. Bump on any incompatible field\n * rename / shape change. Additive fields (omitted-when-absent) do NOT\n * require a bump.\n *\n * Semantic: integer, monotonically increasing. Consumers MAY refuse to\n * parse an envelope whose `schemaVersion` exceeds their pinned\n * maximum.\n */\nexport const ENVELOPE_SCHEMA_VERSION = 1 as const;\n\n/** Flat error block carried inside the envelope. NEVER a raw Effect\n *  Cause — the cascade formatter projects causes into `chain[]`. */\nexport interface EnvelopeError {\n\t/** Sysexits name, e.g. `'CONFIG'`. */\n\treadonly code: string;\n\t/** Sysexits numeric, e.g. 78. Mirrors the OS exit code. */\n\treadonly exitCode: number;\n\t/** Single-line summary fit for a TTY one-liner. */\n\treadonly summary: string;\n\t/** Optional remediation hint (\"run `devstack doctor` to verify\n\t *  Docker is reachable\"). */\n\treadonly hint?: string;\n\t/** Optional copy-pasteable recipe block (multi-line). */\n\treadonly recipe?: string;\n\t/** Cascade lines, deepest-first. Each entry is a rendered line\n\t *  from the cause walker; consumers never see Effect internals. */\n\treadonly chain?: ReadonlyArray<string>;\n\t/** Optional structured context (string-keyed primitives only). */\n\treadonly context?: Readonly<Record<string, string | number | boolean | null>>;\n}\n\n/** The envelope shape itself. Required fields surface always. Optional\n *  fields are omitted when not relevant (the builder enforces this).\n *\n *  Streaming verbs (`logs`) use `StreamingEvent` for each tick; the\n *  closing envelope is one final `Envelope`. The `kind` discriminator\n *  on the streaming shape lets `jq` distinguish per-event records\n *  from the closing summary (surfaces review §1). */\nexport interface Envelope<Data = unknown> {\n\treadonly schemaVersion: typeof ENVELOPE_SCHEMA_VERSION;\n\treadonly ok: boolean;\n\treadonly command: string;\n\treadonly elapsedMs: number;\n\treadonly data?: Data;\n\treadonly hints?: ReadonlyArray<string>;\n\treadonly error?: EnvelopeError;\n\treadonly dryRun?: true;\n}\n\n/** Per-event streaming record. Carries `kind: 'event'` so a consumer\n *  piping through `jq` can filter event records from the closing\n *  `Envelope` by `.kind`. Streaming verbs emit zero-or-more\n *  `StreamingEvent` records followed by exactly one closing `Envelope`. */\nexport interface StreamingEvent<Data = unknown> {\n\treadonly schemaVersion: typeof ENVELOPE_SCHEMA_VERSION;\n\treadonly kind: 'event';\n\treadonly command: string;\n\treadonly at: string;\n\treadonly data: Data;\n}\n\n/** Build a streaming-event record. The closing envelope is produced via\n *  `successEnvelope` as usual. */\nexport const streamingEvent = <Data>(params: {\n\treadonly command: string;\n\treadonly at: number;\n\treadonly data: Data;\n}): StreamingEvent<Data> => ({\n\tschemaVersion: ENVELOPE_SCHEMA_VERSION,\n\tkind: 'event',\n\tcommand: params.command,\n\tat: new Date(params.at).toISOString(),\n\tdata: params.data,\n});\n\n// -----------------------------------------------------------------------------\n// Builders\n// -----------------------------------------------------------------------------\n\nexport interface SuccessParams<Data = unknown> {\n\treadonly command: string;\n\treadonly elapsedMs: number;\n\treadonly data?: Data;\n\treadonly hints?: ReadonlyArray<string>;\n\treadonly dryRun?: boolean;\n}\n\n/** Build a success envelope. Optional fields collapse cleanly when\n *  absent — the JSON serializer in `output.ts` strips them. */\nexport const successEnvelope = <Data>(params: SuccessParams<Data>): Envelope<Data> => {\n\tconst env: Mutable<Envelope<Data>> = {\n\t\tschemaVersion: ENVELOPE_SCHEMA_VERSION,\n\t\tok: true,\n\t\tcommand: params.command,\n\t\telapsedMs: params.elapsedMs,\n\t};\n\tif (params.data !== undefined) env.data = params.data;\n\tif (params.hints !== undefined && params.hints.length > 0) env.hints = params.hints;\n\tif (params.dryRun === true) env.dryRun = true;\n\treturn env as Envelope<Data>;\n};\n\nexport interface FailureParams {\n\treadonly command: string;\n\treadonly elapsedMs: number;\n\treadonly exitCode: ExitCode;\n\treadonly summary: string;\n\treadonly hint?: string;\n\treadonly recipe?: string;\n\treadonly chain?: ReadonlyArray<string>;\n\treadonly context?: EnvelopeError['context'];\n\treadonly hints?: ReadonlyArray<string>;\n\treadonly dryRun?: boolean;\n}\n\n/** Build a failure envelope. The numeric `exitCode` is BOTH the\n *  envelope's `error.exitCode` AND the OS exit code the CLI propagates\n *  via `process.exitCode`. */\nexport const failureEnvelope = (params: FailureParams): Envelope<never> => {\n\tconst error: Mutable<EnvelopeError> = {\n\t\tcode: exitCodeName(params.exitCode),\n\t\texitCode: params.exitCode,\n\t\tsummary: params.summary,\n\t};\n\tif (params.hint !== undefined) error.hint = params.hint;\n\tif (params.recipe !== undefined) error.recipe = params.recipe;\n\tif (params.chain !== undefined && params.chain.length > 0) error.chain = params.chain;\n\tif (params.context !== undefined) error.context = params.context;\n\n\tconst env: Mutable<Envelope<never>> = {\n\t\tschemaVersion: ENVELOPE_SCHEMA_VERSION,\n\t\tok: false,\n\t\tcommand: params.command,\n\t\telapsedMs: params.elapsedMs,\n\t\terror: error as EnvelopeError,\n\t};\n\tif (params.hints !== undefined && params.hints.length > 0) env.hints = params.hints;\n\tif (params.dryRun === true) env.dryRun = true;\n\treturn env as Envelope<never>;\n};\n\n// -----------------------------------------------------------------------------\n// Internal helpers\n// -----------------------------------------------------------------------------\n\n/** Local `Mutable<T>` — the envelope is built mutably, then frozen by\n *  the caller via `as`. We don't mutate after publish. */\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] };\n"],"mappings":";;;AA4GA,MAAa,mBAAyB,WAAgD;CACrF,MAAM,MAA+B;EACpC,eAAA;EACA,IAAI;EACJ,SAAS,OAAO;EAChB,WAAW,OAAO;EAClB;AACD,KAAI,OAAO,SAAS,KAAA,EAAW,KAAI,OAAO,OAAO;AACjD,KAAI,OAAO,UAAU,KAAA,KAAa,OAAO,MAAM,SAAS,EAAG,KAAI,QAAQ,OAAO;AAC9E,KAAI,OAAO,WAAW,KAAM,KAAI,SAAS;AACzC,QAAO;;;;;AAmBR,MAAa,mBAAmB,WAA2C;CAC1E,MAAM,QAAgC;EACrC,MAAM,aAAa,OAAO,SAAS;EACnC,UAAU,OAAO;EACjB,SAAS,OAAO;EAChB;AACD,KAAI,OAAO,SAAS,KAAA,EAAW,OAAM,OAAO,OAAO;AACnD,KAAI,OAAO,WAAW,KAAA,EAAW,OAAM,SAAS,OAAO;AACvD,KAAI,OAAO,UAAU,KAAA,KAAa,OAAO,MAAM,SAAS,EAAG,OAAM,QAAQ,OAAO;AAChF,KAAI,OAAO,YAAY,KAAA,EAAW,OAAM,UAAU,OAAO;CAEzD,MAAM,MAAgC;EACrC,eAAA;EACA,IAAI;EACJ,SAAS,OAAO;EAChB,WAAW,OAAO;EACX;EACP;AACD,KAAI,OAAO,UAAU,KAAA,KAAa,OAAO,MAAM,SAAS,EAAG,KAAI,QAAQ,OAAO;AAC9E,KAAI,OAAO,WAAW,KAAM,KAAI,SAAS;AACzC,QAAO"}

package/dist/surfaces/cli/errors.mjs

@@ -0,0 +1,110 @@
+import { ExitCode } from "./sysexits.mjs";
+import { Data } from "effect";
+//#region src/surfaces/cli/errors.ts
+/** Argv parsing produced an error — unknown subcommand, malformed
+*  flag value, missing required positional. */
+var CliUsageError = class extends Data.TaggedError("CliUsageError") {};
+/** The user's `devstack.config.ts` could not be located (path probe
+*  exhausted) or could not be imported. */
+var CliConfigNotFoundError = class extends Data.TaggedError("CliConfigNotFoundError") {};
+/** The config imported successfully but its default export is not a
+*  `Stack` value (failed brand check, missing required field). */
+var CliConfigInvalidError = class extends Data.TaggedError("CliConfigInvalidError") {};
+/** A required service (Docker daemon, network) is unavailable. */
+var CliUnavailableError = class extends Data.TaggedError("CliUnavailableError") {};
+/** Snapshot name/id not found. Carries the reference the caller
+*  used so the failure renderer can echo it back. */
+var CliSnapshotNotFoundError = class extends Data.TaggedError("CliSnapshotNotFoundError") {};
+var CliSnapshotAmbiguousError = class extends Data.TaggedError("CliSnapshotAmbiguousError") {};
+/** Destructive verb refused because `--yes` was absent and prompting
+*  was forbidden (non-TTY stdin or `--no-input`). */
+var CliConfirmRequiredError = class extends Data.TaggedError("CliConfirmRequiredError") {};
+/** Destructive verb was prompted interactively and the user declined. */
+var CliConfirmDeclinedError = class extends Data.TaggedError("CliConfirmDeclinedError") {};
+/** Engine reports a live supervisor for the target stack; the verb
+*  refused to mutate shared state. */
+var CliSupervisorLiveError = class extends Data.TaggedError("CliSupervisorLiveError") {};
+Data.TaggedError("CliNoSupervisorError");
+/** Internal/unexpected failure. Wraps an arbitrary cause; the cascade
+*  formatter renders the inner. */
+var CliInternalError = class extends Data.TaggedError("CliInternalError") {};
+Data.TaggedError("CliAlreadyReportedError");
+const isCliError = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	switch (value._tag) {
+		case "CliUsageError":
+		case "CliConfigNotFoundError":
+		case "CliConfigInvalidError":
+		case "CliUnavailableError":
+		case "CliSnapshotNotFoundError":
+		case "CliSnapshotAmbiguousError":
+		case "CliConfirmRequiredError":
+		case "CliConfirmDeclinedError":
+		case "CliSupervisorLiveError":
+		case "CliNoSupervisorError":
+		case "CliInternalError":
+		case "CliAlreadyReportedError": return true;
+		default: return false;
+	}
+};
+/** Project a tagged error to its sysexit code. The dispatcher reads
+*  this to set `process.exitCode` — there is exactly one place in the
+*  surface where tag → numeric mapping happens. */
+const exitCodeFor = (error) => {
+	switch (error._tag) {
+		case "CliUsageError": return ExitCode.USAGE;
+		case "CliConfigNotFoundError": return ExitCode.NO_INPUT;
+		case "CliConfigInvalidError": return ExitCode.CONFIG;
+		case "CliUnavailableError": return ExitCode.UNAVAILABLE;
+		case "CliSnapshotNotFoundError": return ExitCode.SNAPSHOT_NOT_FOUND;
+		case "CliSnapshotAmbiguousError": return ExitCode.USAGE;
+		case "CliConfirmRequiredError":
+		case "CliConfirmDeclinedError": return ExitCode.CONFIRM_REQUIRED;
+		case "CliSupervisorLiveError": return ExitCode.SUPERVISOR_LIVE;
+		case "CliNoSupervisorError": return ExitCode.UNAVAILABLE;
+		case "CliInternalError": return ExitCode.SOFTWARE;
+		case "CliAlreadyReportedError": return error.exitCode;
+		default: return ExitCode.SOFTWARE;
+	}
+};
+/** Short single-line summary for the envelope's `error.summary`
+*  field. Cascade detail lives in `error.chain[]`. */
+const summaryFor = (error) => {
+	switch (error._tag) {
+		case "CliUsageError": return error.message;
+		case "CliConfigNotFoundError": return error.message;
+		case "CliConfigInvalidError": return error.message;
+		case "CliUnavailableError": return `${error.service} unavailable: ${error.message}`;
+		case "CliSnapshotNotFoundError": return `snapshot not found: ${error.snapshotRef}`;
+		case "CliSnapshotAmbiguousError": return `snapshot reference is ambiguous: ${error.snapshotRef}`;
+		case "CliConfirmRequiredError": return `${error.verb} requires confirmation`;
+		case "CliConfirmDeclinedError": return `${error.verb} confirmation declined`;
+		case "CliSupervisorLiveError": return `supervisor live for ${error.app}/${error.stack}`;
+		case "CliNoSupervisorError": return `no supervisor running for ${error.app}/${error.stack}`;
+		case "CliInternalError": return error.message;
+		case "CliAlreadyReportedError": return "(already reported)";
+		default: return "(unknown error)";
+	}
+};
+/** Optional hint for the envelope's `error.hint` field. */
+const hintFor = (error) => {
+	switch (error._tag) {
+		case "CliUsageError": return error.hint;
+		case "CliSnapshotAmbiguousError": return `use one of these ids instead: ${error.matches.join(", ")}`;
+		case "CliUnavailableError":
+		case "CliConfirmRequiredError":
+		case "CliConfirmDeclinedError":
+		case "CliSupervisorLiveError":
+		case "CliNoSupervisorError": return error.hint;
+		case "CliConfigNotFoundError":
+		case "CliConfigInvalidError":
+		case "CliSnapshotNotFoundError":
+		case "CliInternalError":
+		case "CliAlreadyReportedError": return;
+		default: return;
+	}
+};
+//#endregion
+export { CliConfigInvalidError, CliConfigNotFoundError, CliConfirmDeclinedError, CliConfirmRequiredError, CliInternalError, CliSnapshotAmbiguousError, CliSnapshotNotFoundError, CliSupervisorLiveError, CliUnavailableError, CliUsageError, exitCodeFor, hintFor, isCliError, summaryFor };
+
+//# sourceMappingURL=errors.mjs.map

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

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

package/dist/surfaces/cli/flags.mjs

@@ -0,0 +1,56 @@
+import { CliUsageError } from "./errors.mjs";
+//#region src/surfaces/cli/flags.ts
+/** Environment-variable names the CLI consults. Centralized so the
+*  `schema --json` command can enumerate them. */
+const ENV_VARS = {
+	JSON: "DEVSTACK_JSON",
+	NO_INPUT: "DEVSTACK_NO_INPUT",
+	APP: "DEVSTACK_APP",
+	STACK: "DEVSTACK_STACK",
+	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
+*  none remain. */
+const takePositional = (rest) => {
+	const idx = rest.findIndex((tok) => !tok.startsWith("-"));
+	if (idx === -1) return {
+		head: void 0,
+		tail: rest
+	};
+	const tail = [...rest.slice(0, idx), ...rest.slice(idx + 1)];
+	return {
+		head: rest[idx],
+		tail
+	};
+};
+/** Look up a value flag (`--name=val` or `--name val`). */
+const takeValueFlag = (rest, name) => {
+	const prefix = `--${name}=`;
+	for (let i = 0; i < rest.length; i++) {
+		const tok = rest[i];
+		if (tok.startsWith(prefix)) return {
+			value: tok.slice(prefix.length),
+			tail: [...rest.slice(0, i), ...rest.slice(i + 1)]
+		};
+		if (tok === `--${name}`) {
+			const next = rest[i + 1];
+			if (next === void 0 || next.startsWith("-")) throw new CliUsageError({ message: `flag --${name} requires a value` });
+			return {
+				value: next,
+				tail: [...rest.slice(0, i), ...rest.slice(i + 2)]
+			};
+		}
+	}
+	return {
+		value: void 0,
+		tail: rest
+	};
+};
+//#endregion
+export { ENV_VARS, takePositional, takeValueFlag };
+
+//# sourceMappingURL=flags.mjs.map