@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/substrate/runtime/tar/reader.mjs

@@ -0,0 +1,216 @@
+//#region src/substrate/runtime/tar/reader.ts
+const TAR_BLOCK_SIZE = 512;
+/** Max bytes a single pax/gnu extended-header record may declare. A
+*  larger declared size is rejected so a malicious archive cannot force
+*  unbounded in-memory buffering of an "extended path". */
+const MAX_TAR_EXTENDED_PATH_BYTES = 1024 * 1024;
+const bytesToString = (bytes) => {
+	const nul = bytes.indexOf(0);
+	const end = nul === -1 ? bytes.length : nul;
+	return Buffer.from(bytes.subarray(0, end)).toString("utf8");
+};
+const concatBytes = (a, b) => {
+	if (a.length === 0) return b;
+	if (b.length === 0) return a;
+	const out = new Uint8Array(a.length + b.length);
+	out.set(a, 0);
+	out.set(b, a.length);
+	return out;
+};
+const consumeBytes = (buffer, count) => buffer.subarray(count);
+const isZeroBlock = (block) => block.every((byte) => byte === 0);
+const parseTarSize = (header) => {
+	const raw = bytesToString(header.subarray(124, 136)).trim();
+	if (raw === "") return 0;
+	if (!/^[0-7]+$/.test(raw)) return null;
+	const parsed = Number.parseInt(raw, 8);
+	return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+};
+const tarPathFromHeader = (header) => {
+	const name = bytesToString(header.subarray(0, 100));
+	const prefix = bytesToString(header.subarray(345, 500));
+	return prefix === "" ? name : `${prefix}/${name}`;
+};
+const tarLinkPathFromHeader = (header) => bytesToString(header.subarray(157, 257));
+const trimExtendedPath = (bytes) => {
+	const value = Buffer.from(bytes).toString("utf8").replace(/\n$/g, "");
+	let end = value.length;
+	while (end > 0 && value.charCodeAt(end - 1) === 0) end -= 1;
+	return value.slice(0, end);
+};
+/** Reject paths that would escape the extraction target: absolute,
+*  drive-qualified, NUL- or backslash-bearing, `.`-only, or carrying a
+*  `..` segment. Applied producer-side (relPaths) and consumer-side
+*  (every resolved entry path + hardlink/symlink target). */
+const isSafeArchivePath = (entryPath) => {
+	if (entryPath === "" || entryPath === "." || entryPath.includes("\0") || entryPath.includes("\\") || entryPath.startsWith("/") || /^[A-Za-z]:/.test(entryPath)) return false;
+	const meaningfulSegments = entryPath.split("/").filter((segment) => segment !== "" && segment !== ".");
+	return meaningfulSegments.length > 0 && !meaningfulSegments.includes("..");
+};
+const parsePaxRecords = (bytes) => {
+	const text = Buffer.from(bytes).toString("utf8");
+	const records = {};
+	let offset = 0;
+	while (offset < text.length) {
+		const space = text.indexOf(" ", offset);
+		if (space === -1) break;
+		const lengthText = text.slice(offset, space);
+		const recordLength = Number.parseInt(lengthText, 10);
+		if (!Number.isSafeInteger(recordLength) || recordLength <= 0) break;
+		const record = text.slice(space + 1, offset + recordLength).replace(/\n$/g, "");
+		const eq = record.indexOf("=");
+		if (eq > 0) records[record.slice(0, eq)] = record.slice(eq + 1);
+		offset += recordLength;
+	}
+	return records;
+};
+const SKIP = { disposition: "skip" };
+const STOP = { disposition: "stop" };
+const skipEntry = () => SKIP;
+const captureEntry = () => ({ disposition: "capture" });
+const stopScan = () => STOP;
+const makeTarReaderState = () => ({
+	buffer: new Uint8Array(0),
+	skipRemaining: 0,
+	content: null,
+	pendingPath: null,
+	pendingLinkPath: null,
+	stopped: false
+});
+const isDirective = (value) => typeof value === "object" && value !== null && "disposition" in value && (value.disposition === "skip" || value.disposition === "capture" || value.disposition === "stop");
+const flattenChunks = (chunks) => chunks.length === 1 ? chunks[0] : Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+const applyExtended = (state, content, hooks) => {
+	const bytes = flattenChunks(content.chunks);
+	if (content.extendedKind === "gnu-path") {
+		state.pendingPath = trimExtendedPath(bytes);
+		return null;
+	}
+	if (content.extendedKind === "gnu-link") {
+		state.pendingLinkPath = trimExtendedPath(bytes);
+		return null;
+	}
+	const records = parsePaxRecords(bytes);
+	if (content.extendedKind === "pax-global" && (records.path !== void 0 || records.linkpath !== void 0)) return hooks.onExtendedError("global pax path/linkpath records are not supported");
+	if (content.extendedKind === "pax-local") {
+		if (records.path !== void 0) state.pendingPath = records.path;
+		if (records.linkpath !== void 0) state.pendingLinkPath = records.linkpath;
+	}
+	return null;
+};
+/**
+* Feed one stream chunk to the reader. Resolves as many complete entries
+* as the accumulated buffer allows, invoking `hooks.onEntry` (and
+* `hooks.onContent` for captured bodies). Returns a caller-typed error
+* on the first hook failure or invalid extended record, else `null`.
+*
+* Returns once `state.stopped` is set (a `'stop'` directive) so callers
+* draining via a `takeUntil`-style stream can short-circuit.
+*/
+const processTarChunk = (state, chunk, hooks) => {
+	if (state.stopped) return null;
+	if (state.content === null && state.skipRemaining >= chunk.length && state.buffer.length === 0) {
+		state.skipRemaining -= chunk.length;
+		return null;
+	}
+	state.buffer = concatBytes(state.buffer, chunk);
+	while (state.buffer.length > 0) {
+		if (state.content !== null) {
+			const content = state.content;
+			const remaining = content.paddedSize - content.totalBytesRead;
+			const take = Math.min(remaining, state.buffer.length);
+			const contentTake = Math.max(0, Math.min(take, content.size - content.contentBytesRead));
+			if (contentTake > 0) content.chunks.push(state.buffer.subarray(0, contentTake));
+			state.content = {
+				...content,
+				contentBytesRead: content.contentBytesRead + contentTake,
+				totalBytesRead: content.totalBytesRead + take
+			};
+			state.buffer = consumeBytes(state.buffer, take);
+			if (state.content.totalBytesRead === state.content.paddedSize) {
+				const completed = state.content;
+				state.content = null;
+				if (completed.kind === "extended") {
+					const error = applyExtended(state, completed, hooks);
+					if (error !== null) return error;
+				} else if (hooks.onContent !== void 0 && completed.entry !== null) {
+					const error = hooks.onContent(completed.entry, flattenChunks(completed.chunks));
+					if (error !== null) return error;
+				}
+			}
+			continue;
+		}
+		if (state.skipRemaining > 0) {
+			const take = Math.min(state.skipRemaining, state.buffer.length);
+			state.skipRemaining -= take;
+			state.buffer = consumeBytes(state.buffer, take);
+			continue;
+		}
+		if (state.buffer.length < TAR_BLOCK_SIZE) return null;
+		const header = state.buffer.subarray(0, TAR_BLOCK_SIZE);
+		state.buffer = consumeBytes(state.buffer, TAR_BLOCK_SIZE);
+		if (isZeroBlock(header)) continue;
+		const size = parseTarSize(header);
+		if (size === null) return hooks.onExtendedError("tar entry has an invalid size header");
+		const paddedSize = Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+		const typeflag = String.fromCharCode(header[156] ?? 0).replace("\0", "");
+		if (typeflag === "x" || typeflag === "g" || typeflag === "L" || typeflag === "K") {
+			if (size > MAX_TAR_EXTENDED_PATH_BYTES) return hooks.onExtendedError("tar extended path record is too large");
+			state.content = {
+				kind: "extended",
+				extendedKind: typeflag === "x" ? "pax-local" : typeflag === "g" ? "pax-global" : typeflag === "L" ? "gnu-path" : "gnu-link",
+				entry: null,
+				size,
+				paddedSize,
+				chunks: [],
+				contentBytesRead: 0,
+				totalBytesRead: 0
+			};
+			continue;
+		}
+		const entryPath = state.pendingPath ?? tarPathFromHeader(header);
+		state.pendingPath = null;
+		const linkPath = state.pendingLinkPath ?? tarLinkPathFromHeader(header);
+		state.pendingLinkPath = null;
+		const entry = {
+			path: entryPath,
+			linkPath,
+			typeflag,
+			size
+		};
+		const directiveOrError = hooks.onEntry(entry);
+		if (!isDirective(directiveOrError)) return directiveOrError;
+		if (directiveOrError.disposition === "stop") {
+			state.stopped = true;
+			return null;
+		}
+		if (directiveOrError.disposition === "capture") {
+			state.content = {
+				kind: "captured",
+				extendedKind: null,
+				entry,
+				size,
+				paddedSize,
+				chunks: [],
+				contentBytesRead: 0,
+				totalBytesRead: 0
+			};
+			continue;
+		}
+		state.skipRemaining = paddedSize;
+	}
+	return null;
+};
+/** Post-EOF structural check. Returns a caller-typed error if the
+*  stream ended mid-extended-header, mid-body, or with a partial header
+*  block (a trailing zero block tail is fine). */
+const finishTarReader = (state, mkError) => {
+	if (state.stopped) return null;
+	if (state.content !== null) return mkError(state.content.kind === "extended" ? "tar ended inside an extended header" : "tar ended inside file content");
+	if (state.skipRemaining !== 0) return mkError("tar ended inside file content");
+	if (state.buffer.length !== 0 && !isZeroBlock(state.buffer)) return mkError("tar ended with a partial header");
+	return null;
+};
+//#endregion
+export { captureEntry, finishTarReader, isSafeArchivePath, makeTarReaderState, processTarChunk, skipEntry, stopScan };
+
+//# sourceMappingURL=reader.mjs.map

package/dist/substrate/runtime/tar/reader.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.mjs","names":[],"sources":["../../../../src/substrate/runtime/tar/reader.ts"],"sourcesContent":["// tar/reader — shared low-level TAR block reader.\n//\n// Two devstack surfaces parse TAR byte streams: the host-tree snapshot\n// validator (`substrate/runtime/host-tree-tar`) and the Docker image\n// bundle tag scanner (`orchestrators/snapshot/image-bundle-tags`). This\n// module is the single source of truth for the block iterator, header\n// parse, pax/gnu extended-header handling, and the `isSafeArchivePath`\n// path-escape guard, so a pax/gnu fix lands on both surfaces at once.\n//\n// Shape:\n//   - `processTarChunk` is a stateful, streaming block iterator. The\n//     caller feeds chunks; the reader resolves complete entries (after\n//     applying any preceding pax `x` / gnu `L`/`K` extended-header that\n//     overrides the path / linkpath) and invokes the caller's `onEntry`\n//     hook. The hook returns a `TarEntryDirective` that tells the reader\n//     whether to CAPTURE the entry body (returned via `onContent`), SKIP\n//     it, or STOP the scan early.\n//   - The reader owns pax/gnu parsing, body buffering, and the\n//     512-byte block discipline; callers own their domain validation\n//     and metadata extraction.\n//\n// Security note: `isSafeArchivePath` rejects absolute paths, `..`\n// segments, backslashes, and NUL — applied to BOTH the entry path and\n// (for hardlink/symlink typeflags) the link target. Symlink targets are\n// NOT canonicalized here; relative targets are caught by `..` rejection,\n// and native `tar -x` refuses escaping paths as a second layer.\n\nconst TAR_BLOCK_SIZE = 512;\n\n/** Max bytes a single pax/gnu extended-header record may declare. A\n *  larger declared size is rejected so a malicious archive cannot force\n *  unbounded in-memory buffering of an \"extended path\". */\nconst MAX_TAR_EXTENDED_PATH_BYTES = 1024 * 1024;\n\n// ---------------------------------------------------------------------------\n// Byte helpers — shared by both header parse and content buffering.\n// ---------------------------------------------------------------------------\n\nconst bytesToString = (bytes: Uint8Array): string => {\n\tconst nul = bytes.indexOf(0);\n\tconst end = nul === -1 ? bytes.length : nul;\n\treturn Buffer.from(bytes.subarray(0, end)).toString('utf8');\n};\n\nconst concatBytes = (a: Uint8Array, b: Uint8Array): Uint8Array => {\n\tif (a.length === 0) return b;\n\tif (b.length === 0) return a;\n\tconst out = new Uint8Array(a.length + b.length);\n\tout.set(a, 0);\n\tout.set(b, a.length);\n\treturn out;\n};\n\nconst consumeBytes = (buffer: Uint8Array, count: number): Uint8Array => buffer.subarray(count);\n\nconst isZeroBlock = (block: Uint8Array): boolean => block.every((byte) => byte === 0);\n\nconst parseTarSize = (header: Uint8Array): number | null => {\n\tconst raw = bytesToString(header.subarray(124, 136)).trim();\n\tif (raw === '') return 0;\n\tif (!/^[0-7]+$/.test(raw)) return null;\n\tconst parsed = Number.parseInt(raw, 8);\n\treturn Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;\n};\n\nconst tarPathFromHeader = (header: Uint8Array): string => {\n\tconst name = bytesToString(header.subarray(0, 100));\n\tconst prefix = bytesToString(header.subarray(345, 500));\n\treturn prefix === '' ? name : `${prefix}/${name}`;\n};\n\nconst tarLinkPathFromHeader = (header: Uint8Array): string =>\n\tbytesToString(header.subarray(157, 257));\n\nconst trimExtendedPath = (bytes: Uint8Array): string => {\n\tconst value = Buffer.from(bytes).toString('utf8').replace(/\\n$/g, '');\n\tlet end = value.length;\n\twhile (end > 0 && value.charCodeAt(end - 1) === 0) end -= 1;\n\treturn value.slice(0, end);\n};\n\n/** Reject paths that would escape the extraction target: absolute,\n *  drive-qualified, NUL- or backslash-bearing, `.`-only, or carrying a\n *  `..` segment. Applied producer-side (relPaths) and consumer-side\n *  (every resolved entry path + hardlink/symlink target). */\nexport const isSafeArchivePath = (entryPath: string): boolean => {\n\tif (\n\t\tentryPath === '' ||\n\t\tentryPath === '.' ||\n\t\tentryPath.includes('\\0') ||\n\t\tentryPath.includes('\\\\') ||\n\t\tentryPath.startsWith('/') ||\n\t\t/^[A-Za-z]:/.test(entryPath)\n\t) {\n\t\treturn false;\n\t}\n\tconst meaningfulSegments = entryPath\n\t\t.split('/')\n\t\t.filter((segment) => segment !== '' && segment !== '.');\n\treturn meaningfulSegments.length > 0 && !meaningfulSegments.includes('..');\n};\n\nconst parsePaxRecords = (bytes: Uint8Array): Record<string, string> => {\n\tconst text = Buffer.from(bytes).toString('utf8');\n\tconst records: Record<string, string> = {};\n\tlet offset = 0;\n\twhile (offset < text.length) {\n\t\tconst space = text.indexOf(' ', offset);\n\t\tif (space === -1) break;\n\t\tconst lengthText = text.slice(offset, space);\n\t\tconst recordLength = Number.parseInt(lengthText, 10);\n\t\tif (!Number.isSafeInteger(recordLength) || recordLength <= 0) break;\n\t\tconst record = text.slice(space + 1, offset + recordLength).replace(/\\n$/g, '');\n\t\tconst eq = record.indexOf('=');\n\t\tif (eq > 0) {\n\t\t\trecords[record.slice(0, eq)] = record.slice(eq + 1);\n\t\t}\n\t\toffset += recordLength;\n\t}\n\treturn records;\n};\n\n// ---------------------------------------------------------------------------\n// Streaming block reader.\n// ---------------------------------------------------------------------------\n\n/** A resolved tar entry, after any pax `x` / gnu `L`/`K`\n *  extended-header has been applied to its path and link target. */\nexport interface TarEntry {\n\t/** Effective entry path (pax/gnu-overridden when present). */\n\treadonly path: string;\n\t/** Effective hardlink/symlink target (pax/gnu-overridden when\n\t *  present); empty for non-link entries. */\n\treadonly linkPath: string;\n\t/** One-character ustar typeflag (`'0'` regular, `'1'` hardlink,\n\t *  `'2'` symlink, `'5'` directory, …). */\n\treadonly typeflag: string;\n\t/** Declared content size in bytes (unpadded). */\n\treadonly size: number;\n}\n\ntype TarEntryDisposition = 'skip' | 'capture' | 'stop';\n\n/** What the reader should do with one resolved entry's body. `'skip'`\n *  advances past the (padded) body without buffering; `'capture'`\n *  buffers the body and invokes `onContent(entry, body)` when complete;\n *  `'stop'` ends the scan immediately (the body is not consumed). */\nexport interface TarEntryDirective {\n\treadonly disposition: TarEntryDisposition;\n}\n\nconst SKIP: TarEntryDirective = { disposition: 'skip' };\nconst STOP: TarEntryDirective = { disposition: 'stop' };\nexport const skipEntry = (): TarEntryDirective => SKIP;\nexport const captureEntry = (): TarEntryDirective => ({ disposition: 'capture' });\nexport const stopScan = (): TarEntryDirective => STOP;\n\ntype ExtendedKind = 'pax-local' | 'pax-global' | 'gnu-path' | 'gnu-link';\n\ninterface BufferingContent {\n\treadonly kind: 'extended' | 'captured';\n\treadonly extendedKind: ExtendedKind | null;\n\treadonly entry: TarEntry | null;\n\treadonly size: number;\n\treadonly paddedSize: number;\n\treadonly chunks: Array<Uint8Array>;\n\treadonly contentBytesRead: number;\n\treadonly totalBytesRead: number;\n}\n\n/** Streaming parser state. Construct once per stream via\n *  `makeTarReaderState`, feed every chunk to `processTarChunk`, then\n *  call `finishTarReader` after EOF. */\ninterface TarReaderState {\n\tbuffer: Uint8Array;\n\tskipRemaining: number;\n\tcontent: BufferingContent | null;\n\tpendingPath: string | null;\n\tpendingLinkPath: string | null;\n\tstopped: boolean;\n}\n\nexport const makeTarReaderState = (): TarReaderState => ({\n\tbuffer: new Uint8Array(0),\n\tskipRemaining: 0,\n\tcontent: null,\n\tpendingPath: null,\n\tpendingLinkPath: null,\n\tstopped: false,\n});\n\n/** Caller hooks. `onEntry` decides the per-entry directive; `onContent`\n *  receives the buffered body for `'capture'` entries. Both may return\n *  an error of the caller's `E` type to abort the scan. */\ninterface TarReaderHooks<E> {\n\treadonly onEntry: (entry: TarEntry) => TarEntryDirective | E;\n\treadonly onContent?: (entry: TarEntry, body: Uint8Array) => null | E;\n\t/** Raised when a pax/gnu extended record is invalid (oversized, or a\n\t *  global pax path/linkpath which is not honored). Lets the caller\n\t *  brand the failure with its own tagged-error type. */\n\treadonly onExtendedError: (detail: string) => E;\n}\n\nconst isDirective = (value: unknown): value is TarEntryDirective =>\n\ttypeof value === 'object' &&\n\tvalue !== null &&\n\t'disposition' in value &&\n\t((value as { disposition: unknown }).disposition === 'skip' ||\n\t\t(value as { disposition: unknown }).disposition === 'capture' ||\n\t\t(value as { disposition: unknown }).disposition === 'stop');\n\nconst flattenChunks = (chunks: ReadonlyArray<Uint8Array>): Uint8Array =>\n\tchunks.length === 1 ? chunks[0]! : Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));\n\nconst applyExtended = <E>(\n\tstate: TarReaderState,\n\tcontent: BufferingContent,\n\thooks: TarReaderHooks<E>,\n): E | null => {\n\tconst bytes = flattenChunks(content.chunks);\n\tif (content.extendedKind === 'gnu-path') {\n\t\tstate.pendingPath = trimExtendedPath(bytes);\n\t\treturn null;\n\t}\n\tif (content.extendedKind === 'gnu-link') {\n\t\tstate.pendingLinkPath = trimExtendedPath(bytes);\n\t\treturn null;\n\t}\n\tconst records = parsePaxRecords(bytes);\n\tif (\n\t\tcontent.extendedKind === 'pax-global' &&\n\t\t(records.path !== undefined || records.linkpath !== undefined)\n\t) {\n\t\treturn hooks.onExtendedError('global pax path/linkpath records are not supported');\n\t}\n\tif (content.extendedKind === 'pax-local') {\n\t\tif (records.path !== undefined) state.pendingPath = records.path;\n\t\tif (records.linkpath !== undefined) state.pendingLinkPath = records.linkpath;\n\t}\n\treturn null;\n};\n\n/**\n * Feed one stream chunk to the reader. Resolves as many complete entries\n * as the accumulated buffer allows, invoking `hooks.onEntry` (and\n * `hooks.onContent` for captured bodies). Returns a caller-typed error\n * on the first hook failure or invalid extended record, else `null`.\n *\n * Returns once `state.stopped` is set (a `'stop'` directive) so callers\n * draining via a `takeUntil`-style stream can short-circuit.\n */\nexport const processTarChunk = <E>(\n\tstate: TarReaderState,\n\tchunk: Uint8Array,\n\thooks: TarReaderHooks<E>,\n): E | null => {\n\tif (state.stopped) return null;\n\t// Fast path: mid-skip over a large body and this whole chunk is\n\t// consumed by the skip. Avoids O(N²) concat across a multi-MB body\n\t// streamed in small chunks. The buffer must be empty so byte order\n\t// is preserved relative to the parser.\n\tif (state.content === null && state.skipRemaining >= chunk.length && state.buffer.length === 0) {\n\t\tstate.skipRemaining -= chunk.length;\n\t\treturn null;\n\t}\n\tstate.buffer = concatBytes(state.buffer, chunk);\n\twhile (state.buffer.length > 0) {\n\t\tif (state.content !== null) {\n\t\t\tconst content = state.content;\n\t\t\tconst remaining = content.paddedSize - content.totalBytesRead;\n\t\t\tconst take = Math.min(remaining, state.buffer.length);\n\t\t\tconst contentTake = Math.max(0, Math.min(take, content.size - content.contentBytesRead));\n\t\t\tif (contentTake > 0) {\n\t\t\t\tcontent.chunks.push(state.buffer.subarray(0, contentTake));\n\t\t\t}\n\t\t\tstate.content = {\n\t\t\t\t...content,\n\t\t\t\tcontentBytesRead: content.contentBytesRead + contentTake,\n\t\t\t\ttotalBytesRead: content.totalBytesRead + take,\n\t\t\t};\n\t\t\tstate.buffer = consumeBytes(state.buffer, take);\n\t\t\tif (state.content.totalBytesRead === state.content.paddedSize) {\n\t\t\t\tconst completed = state.content;\n\t\t\t\tstate.content = null;\n\t\t\t\tif (completed.kind === 'extended') {\n\t\t\t\t\tconst error = applyExtended(state, completed, hooks);\n\t\t\t\t\tif (error !== null) return error;\n\t\t\t\t} else if (hooks.onContent !== undefined && completed.entry !== null) {\n\t\t\t\t\tconst error = hooks.onContent(completed.entry, flattenChunks(completed.chunks));\n\t\t\t\t\tif (error !== null) return error;\n\t\t\t\t}\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (state.skipRemaining > 0) {\n\t\t\tconst take = Math.min(state.skipRemaining, state.buffer.length);\n\t\t\tstate.skipRemaining -= take;\n\t\t\tstate.buffer = consumeBytes(state.buffer, take);\n\t\t\tcontinue;\n\t\t}\n\t\tif (state.buffer.length < TAR_BLOCK_SIZE) return null;\n\t\tconst header = state.buffer.subarray(0, TAR_BLOCK_SIZE);\n\t\tstate.buffer = consumeBytes(state.buffer, TAR_BLOCK_SIZE);\n\t\tif (isZeroBlock(header)) continue;\n\n\t\tconst size = parseTarSize(header);\n\t\tif (size === null) return hooks.onExtendedError('tar entry has an invalid size header');\n\t\tconst paddedSize = Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;\n\t\tconst typeflag = String.fromCharCode(header[156] ?? 0).replace('\\0', '');\n\t\tif (typeflag === 'x' || typeflag === 'g' || typeflag === 'L' || typeflag === 'K') {\n\t\t\tif (size > MAX_TAR_EXTENDED_PATH_BYTES) {\n\t\t\t\treturn hooks.onExtendedError('tar extended path record is too large');\n\t\t\t}\n\t\t\tstate.content = {\n\t\t\t\tkind: 'extended',\n\t\t\t\textendedKind:\n\t\t\t\t\ttypeflag === 'x'\n\t\t\t\t\t\t? 'pax-local'\n\t\t\t\t\t\t: typeflag === 'g'\n\t\t\t\t\t\t\t? 'pax-global'\n\t\t\t\t\t\t\t: typeflag === 'L'\n\t\t\t\t\t\t\t\t? 'gnu-path'\n\t\t\t\t\t\t\t\t: 'gnu-link',\n\t\t\t\tentry: null,\n\t\t\t\tsize,\n\t\t\t\tpaddedSize,\n\t\t\t\tchunks: [],\n\t\t\t\tcontentBytesRead: 0,\n\t\t\t\ttotalBytesRead: 0,\n\t\t\t};\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst entryPath = state.pendingPath ?? tarPathFromHeader(header);\n\t\tstate.pendingPath = null;\n\t\tconst linkPath = state.pendingLinkPath ?? tarLinkPathFromHeader(header);\n\t\tstate.pendingLinkPath = null;\n\t\tconst entry: TarEntry = { path: entryPath, linkPath, typeflag, size };\n\n\t\tconst directiveOrError = hooks.onEntry(entry);\n\t\tif (!isDirective(directiveOrError)) return directiveOrError;\n\t\tif (directiveOrError.disposition === 'stop') {\n\t\t\tstate.stopped = true;\n\t\t\treturn null;\n\t\t}\n\t\tif (directiveOrError.disposition === 'capture') {\n\t\t\tstate.content = {\n\t\t\t\tkind: 'captured',\n\t\t\t\textendedKind: null,\n\t\t\t\tentry,\n\t\t\t\tsize,\n\t\t\t\tpaddedSize,\n\t\t\t\tchunks: [],\n\t\t\t\tcontentBytesRead: 0,\n\t\t\t\ttotalBytesRead: 0,\n\t\t\t};\n\t\t\tcontinue;\n\t\t}\n\t\tstate.skipRemaining = paddedSize;\n\t}\n\treturn null;\n};\n\n/** Post-EOF structural check. Returns a caller-typed error if the\n *  stream ended mid-extended-header, mid-body, or with a partial header\n *  block (a trailing zero block tail is fine). */\nexport const finishTarReader = <E>(\n\tstate: TarReaderState,\n\tmkError: (detail: string) => E,\n): E | null => {\n\tif (state.stopped) return null;\n\tif (state.content !== null) {\n\t\treturn mkError(\n\t\t\tstate.content.kind === 'extended'\n\t\t\t\t? 'tar ended inside an extended header'\n\t\t\t\t: 'tar ended inside file content',\n\t\t);\n\t}\n\tif (state.skipRemaining !== 0) return mkError('tar ended inside file content');\n\tif (state.buffer.length !== 0 && !isZeroBlock(state.buffer)) {\n\t\treturn mkError('tar ended with a partial header');\n\t}\n\treturn null;\n};\n"],"mappings":"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"}

package/dist/substrate/runtime/typed-env.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"typed-env.mjs","names":[],"sources":["../../../src/substrate/runtime/typed-env.ts"],"sourcesContent":["// Typed `process.env` accessor.\n//\n// The devstack package is consumed from both Node and browser-like\n// runtimes (Playwright fixtures, vitest browser mode), so we can't\n// reach for `process.env` directly — TypeScript with `\"types\": []`\n// rejects the global. Callers used to inline a one-off\n// `globalThis as { process?: { env?: ... } }` cast every time they\n// needed to read an env var. This centralises the cast so the rest of\n// the code reads `readEnv('FOO')` cleanly.\n//\n// Returns `undefined` when the runtime has no `process.env` (browser),\n// or when the env var is unset. Callers treat `undefined` and `''` as\n// equivalent \"absent\" sentinels.\n\nexport const readEnv = (name: string): string | undefined => {\n\tconst process = (\n\t\tglobalThis as { process?: { env?: Record<string, string | undefined> } }\n\t).process;\n\treturn process?.env?.[name];\n};\n"],"mappings":";AAcA,MAAa,WAAW,SAAqC;AAI5D,QAFC,WACC,SACc,MAAM"}
+{"version":3,"file":"typed-env.mjs","names":[],"sources":["../../../src/substrate/runtime/typed-env.ts"],"sourcesContent":["// Typed `process.env` accessor.\n//\n// The devstack package is consumed from both Node and browser-like\n// runtimes (Playwright fixtures, vitest browser mode), so we can't\n// reach for `process.env` directly — TypeScript with `\"types\": []`\n// rejects the global. This centralises the\n// `globalThis as { process?: { env?: ... } }` cast so the rest of the\n// code reads `readEnv('FOO')` cleanly.\n//\n// Returns `undefined` when the runtime has no `process.env` (browser),\n// or when the env var is unset. Callers treat `undefined` and `''` as\n// equivalent \"absent\" sentinels.\n\nexport const readEnv = (name: string): string | undefined => {\n\tconst process = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n\t\t.process;\n\treturn process?.env?.[name];\n};\n"],"mappings":";AAaA,MAAa,WAAW,SAAqC;CAG5D,OAFiB,WACf,SACc,MAAM;AACvB"}

package/dist/substrate/versioned-doc-schema.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"versioned-doc-schema.mjs","names":[],"sources":["../../src/substrate/versioned-doc-schema.ts"],"sourcesContent":["// Versioned cross-process document schema helper.\n//\n// Centralizes the `{ version: Literal<N>, ...payload }` discriminator\n// shape that every cross-process document the substrate persists shares\n// (roster, container claim, snapshot reservation, port reservation).\n//\n// Future v2 migration becomes mechanical: replace the call with\n// `Schema.Union(versionedDocSchema(1, ...), versionedDocSchema(2, ...))`\n// at exactly one site per document, rather than hand-rolling the\n// discriminator field in each consumer.\n//\n// Lives at substrate L0 (depends only on `effect`'s Schema) so L0\n// declarations such as `substrate/cross-process.ts` can use it without\n// reaching into the L1 runtime tree.\n\nimport { Schema } from 'effect';\n\n/** Construct a versioned cross-process document schema —\n *  `{ version: Literal<N>, ...payloadFields }` in one call.\n *\n *  The resulting schema is structurally identical to a hand-written\n *  `Schema.Struct({ version: Schema.Literal(N), ...payload })`; the\n *  `version` field becomes a literal-typed discriminator suitable for\n *  forward-compatible `Schema.Union`s. */\nexport const versionedDocSchema = <const V extends number, Fields extends Schema.Struct.Fields>(\n\tversion: V,\n\tpayload: Fields,\n): Schema.Struct<{ readonly version: Schema.Literal<V> } & Fields> =>\n\t// Cast is load-bearing: spreading a generic `Fields` into an object\n\t// literal makes TS infer the resulting `Schema.Struct` over a widened\n\t// field type, not the precise `{ version } & Fields` intersection, so\n\t// the literal-typed `version` discriminator would be lost without it.\n\tSchema.Struct({\n\t\tversion: Schema.Literal(version),\n\t\t...payload,\n\t}) as unknown as Schema.Struct<{ readonly version: Schema.Literal<V> } & Fields>;\n"],"mappings":";;;;;;;;;AAwBA,MAAa,sBACZ,SACA,YAMA,OAAO,OAAO;CACb,SAAS,OAAO,QAAQ,QAAQ;CAChC,GAAG;CACH,CAAC"}
+{"version":3,"file":"versioned-doc-schema.mjs","names":[],"sources":["../../src/substrate/versioned-doc-schema.ts"],"sourcesContent":["// Versioned cross-process document schema helper.\n//\n// Centralizes the `{ version: Literal<N>, ...payload }` discriminator\n// shape that every cross-process document the substrate persists shares\n// (roster, container claim, port reservation).\n//\n// Future v2 migration becomes mechanical: replace the call with\n// `Schema.Union(versionedDocSchema(1, ...), versionedDocSchema(2, ...))`\n// at exactly one site per document, rather than hand-rolling the\n// discriminator field in each consumer.\n//\n// Lives at substrate L0 (depends only on `effect`'s Schema) so L0\n// declarations such as `substrate/cross-process.ts` can use it without\n// reaching into the L1 runtime tree.\n\nimport { Schema } from 'effect';\n\n/** Construct a versioned cross-process document schema —\n *  `{ version: Literal<N>, ...payloadFields }` in one call.\n *\n *  The resulting schema is structurally identical to a hand-written\n *  `Schema.Struct({ version: Schema.Literal(N), ...payload })`; the\n *  `version` field becomes a literal-typed discriminator suitable for\n *  forward-compatible `Schema.Union`s. */\nexport const versionedDocSchema = <const V extends number, Fields extends Schema.Struct.Fields>(\n\tversion: V,\n\tpayload: Fields,\n): Schema.Struct<{ readonly version: Schema.Literal<V> } & Fields> =>\n\t// Cast is load-bearing: spreading a generic `Fields` into an object\n\t// literal makes TS infer the resulting `Schema.Struct` over a widened\n\t// field type, not the precise `{ version } & Fields` intersection, so\n\t// the literal-typed `version` discriminator would be lost without it.\n\tSchema.Struct({\n\t\tversion: Schema.Literal(version),\n\t\t...payload,\n\t}) as unknown as Schema.Struct<{ readonly version: Schema.Literal<V> } & Fields>;\n"],"mappings":";;;;;;;;;AAwBA,MAAa,sBACZ,SACA,YAMA,OAAO,OAAO;CACb,SAAS,OAAO,QAAQ,OAAO;CAC/B,GAAG;AACJ,CAAC"}

package/dist/substrate/versioned-doc-sync.mjs

@@ -1,5 +1,5 @@
-import { atomicWriteJsonSync } from "./runtime/atomic-write.mjs";
 import { decodeJsonText, decodeJsonTextSync } from "./runtime/runtime-decode.mjs";
+import { atomicWriteJsonSync } from "./runtime/atomic-write.mjs";
 import { Effect } from "effect";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/substrate/versioned-doc-sync.ts
@@ -41,7 +41,7 @@ const readVersionedDocumentSync = (path, schema, errors, whenAbsent) => Effect.g
 * Sync parse-or-null variant of `readVersionedDocumentSync`. Decodes a
 * raw JSON body against `schema`; returns `null` on parse or decode
 * failure. Use this when a malformed body should be treated the same as
-* a missing body (e.g. half-written reservation by a crashed creator,
+* a missing body (e.g. a half-written roster entry by a crashed creator,
 * stack-lock body interrupted mid-write) — the call site swaps a
 * try/catch around `decodeJsonTextSync` for one helper call.
 *
@@ -65,8 +65,8 @@ const parseVersionedDocumentBodyOrNull = (raw, schema, source) => {
 * Write a versioned cross-process document atomically.
 *
 * Routes through the canonical `atomicWriteJsonSync` primitive — the
-* NFS-safe mkdir-parent → O_EXCL temp → write → fsync → rename dance
-* with one owner of the tempfile cleanup. The version stamp lives in
+* crash-atomic mkdir-parent → O_EXCL temp → write → fsync → rename
+* dance with one owner of the tempfile cleanup. The version stamp lives in
 * the caller-supplied `value` (every versioned-doc schema carries a
 * literal `version` field via `versionedDocSchema`); this helper does
 * NOT inject a version — it just ensures the typed write envelope
@@ -76,7 +76,7 @@ const parseVersionedDocumentBodyOrNull = (raw, schema, source) => {
 * cross-process docs are `Schema.Struct` of primitives that round-trip
 * cleanly through plain `JSON.stringify`. The `value` is typed as a
 * generic `D` so the caller's document interface (`RosterDocument`,
-* `ContainerClaimDocument`, ...) is what gets serialized.
+* ...) is what gets serialized.
 *
 * This is the SYNC surface — used by callers that hold `stack.lock`
 * and must keep their critical section non-yielding.

package/dist/substrate/versioned-doc-sync.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"versioned-doc-sync.mjs","names":[],"sources":["../../src/substrate/versioned-doc-sync.ts"],"sourcesContent":["// Versioned cross-process document — read / write envelope helpers.\n//\n// Three cross-process modules (`runtime/cross-process/{roster,\n// snapshot-reservation, stack-lock}.ts`) historically re-implemented the\n// same `Effect.try(readFileSync) → decodeJsonText → mkIoError|\n// mkCorruptError` envelope and the same `Effect.try(atomicWriteJsonSync)\n// → mkIoError` envelope, each with a different typed-error pair. This\n// file centralizes both envelopes around the versioned-doc schemas\n// constructed via `versionedDocSchema` (the sibling file). The caller\n// supplies the error constructors so its typed error channel is\n// preserved end-to-end; nothing about NFS-safe atomicity, fsync\n// ordering, or version-stamp handling moves out of the underlying\n// primitives.\n//\n// Lives at substrate L0+ — depends on `effect`, `node:fs`, the\n// runtime-decode helpers, and the canonical atomic-write primitive.\n// Kept as a sibling of `versioned-doc-schema.ts` rather than absorbed\n// into it so the schema constructor remains pure-Schema (callable from\n// any L0 declaration site such as `substrate/cross-process.ts`); only\n// callers that actually round-trip a versioned doc to disk pay the\n// fs/runtime-decode import cost.\n\nimport { existsSync, readFileSync } from 'node:fs';\n\nimport { Effect, Schema } from 'effect';\n\nimport { atomicWriteJsonSync } from './runtime/atomic-write.ts';\nimport { decodeJsonText, decodeJsonTextSync } from './runtime/runtime-decode.ts';\n\n/** Constructor pair the caller supplies so its typed error channel is\n *  preserved through the envelope. `mkIo` wraps any node:fs / disk\n *  failure (read OR write); `mkCorrupt` wraps any JSON-parse / Schema-\n *  decode failure (read only). Both helpers thread the on-disk `path`\n *  and — for `mkCorrupt` — the raw bytes that failed to decode so\n *  diagnostics can echo what was actually on disk. */\nexport interface VersionedDocErrors<IoErr, CorruptErr> {\n\treadonly mkIo: (input: { readonly path: string; readonly cause: unknown }) => IoErr;\n\treadonly mkCorrupt: (input: {\n\t\treadonly path: string;\n\t\treadonly raw: string;\n\t\treadonly cause: unknown;\n\t}) => CorruptErr;\n}\n\n/** Constructor for the IO-only case (write path — no decode failure\n *  mode). Split into its own interface so `writeVersionedDocumentSync`\n *  callers don't have to supply a `mkCorrupt` they would never invoke. */\nexport interface VersionedDocIoError<IoErr> {\n\treadonly mkIo: (input: { readonly path: string; readonly cause: unknown }) => IoErr;\n}\n\n/**\n * Read + decode a versioned cross-process document from disk.\n *\n *  - Missing file (`!existsSync`) → returns the caller-supplied\n *    `whenAbsent` default. This is the \"no peer has ever written yet\"\n *    path; the caller decides whether that's an empty document or a\n *    failure.\n *  - Read failure (any `node:fs` error other than ENOENT) → `mkIo`.\n *  - JSON-parse OR Schema-decode failure → `mkCorrupt` with the raw\n *    bytes echoed so callers can log the offending content.\n *\n *  The decode runs through `decodeJsonText`, so the on-disk JSON is\n *  parsed and Schema-validated in one envelope. No atomicity, fsync, or\n *  lock-ordering concerns at the read site — this is pure read-and-\n *  validate.\n */\nexport const readVersionedDocumentSync = <\n\tS extends Schema.Decoder<unknown>,\n\tIoErr,\n\tCorruptErr,\n>(\n\tpath: string,\n\tschema: S,\n\terrors: VersionedDocErrors<IoErr, CorruptErr>,\n\twhenAbsent: S['Type'],\n): Effect.Effect<S['Type'], IoErr | CorruptErr> =>\n\tEffect.gen(function* () {\n\t\tif (!existsSync(path)) return whenAbsent;\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => errors.mkIo({ path, cause }),\n\t\t});\n\t\treturn yield* decodeJsonText(schema, raw, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) => errors.mkCorrupt({ path, raw, cause: issue.cause ?? issue }),\n\t\t});\n\t});\n\n/**\n * Sync parse-or-null variant of `readVersionedDocumentSync`. Decodes a\n * raw JSON body against `schema`; returns `null` on parse or decode\n * failure. Use this when a malformed body should be treated the same as\n * a missing body (e.g. half-written reservation by a crashed creator,\n * stack-lock body interrupted mid-write) — the call site swaps a\n * try/catch around `decodeJsonTextSync` for one helper call.\n *\n * `source` is purely a diagnostic label for the synthesized error\n * inside `decodeJsonTextSync`'s throw; it is consumed by the catch and\n * discarded along with the error. The caller does not need to thread a\n * typed error constructor — the contract here is \"null means\n * unreadable/malformed; the caller decides what to do next\".\n */\nexport const parseVersionedDocumentBodyOrNull = <S extends Schema.Decoder<unknown>>(\n\traw: string,\n\tschema: S,\n\tsource: string,\n): S['Type'] | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(schema, raw, {\n\t\t\tsource,\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/**\n * Write a versioned cross-process document atomically.\n *\n * Routes through the canonical `atomicWriteJsonSync` primitive — the\n * NFS-safe mkdir-parent → O_EXCL temp → write → fsync → rename dance\n * with one owner of the tempfile cleanup. The version stamp lives in\n * the caller-supplied `value` (every versioned-doc schema carries a\n * literal `version` field via `versionedDocSchema`); this helper does\n * NOT inject a version — it just ensures the typed write envelope\n * (Effect.try → mkIo) is consistent across cross-process sites.\n *\n * No Schema-encode step here: matching `atomicWriteJsonSync`'s contract,\n * cross-process docs are `Schema.Struct` of primitives that round-trip\n * cleanly through plain `JSON.stringify`. The `value` is typed as a\n * generic `D` so the caller's document interface (`RosterDocument`,\n * `ContainerClaimDocument`, ...) is what gets serialized.\n *\n * This is the SYNC surface — used by callers that hold `stack.lock`\n * and must keep their critical section non-yielding.\n */\nexport const writeVersionedDocumentSync = <D, IoErr>(\n\tpath: string,\n\tvalue: D,\n\terrors: VersionedDocIoError<IoErr>,\n): Effect.Effect<void, IoErr> =>\n\tEffect.try({\n\t\ttry: () => atomicWriteJsonSync(path, value),\n\t\tcatch: (cause) => errors.mkIo({ path, cause }),\n\t});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAmEA,MAAa,6BAKZ,MACA,QACA,QACA,eAEA,OAAO,IAAI,aAAa;AACvB,KAAI,CAAC,WAAW,KAAK,CAAE,QAAO;CAC9B,MAAM,MAAM,OAAO,OAAO,IAAI;EAC7B,WAAW,aAAa,MAAM,OAAO;EACrC,QAAQ,UAAU,OAAO,KAAK;GAAE;GAAM;GAAO,CAAC;EAC9C,CAAC;AACF,QAAO,OAAO,eAAe,QAAQ,KAAK;EACzC,QAAQ;EACR,UAAU,UAAU,OAAO,UAAU;GAAE;GAAM;GAAK,OAAO,MAAM,SAAS;GAAO,CAAC;EAChF,CAAC;EACD;;;;;;;;;;;;;;;AAgBH,MAAa,oCACZ,KACA,QACA,WACsB;AACtB,KAAI;AACH,SAAO,mBAAmB,QAAQ,KAAK;GACtC;GACA,UAAU,UAAU;GACpB,CAAC;SACK;AACP,SAAO;;;;;;;;;;;;;;;;;;;;;;;AAwBT,MAAa,8BACZ,MACA,OACA,WAEA,OAAO,IAAI;CACV,WAAW,oBAAoB,MAAM,MAAM;CAC3C,QAAQ,UAAU,OAAO,KAAK;EAAE;EAAM;EAAO,CAAC;CAC9C,CAAC"}
+{"version":3,"file":"versioned-doc-sync.mjs","names":[],"sources":["../../src/substrate/versioned-doc-sync.ts"],"sourcesContent":["// Versioned cross-process document — read / write envelope helpers.\n//\n// The cross-process modules (`runtime/cross-process/{roster,\n// stack-lock}.ts`) share one `Effect.try(readFileSync) → decodeJsonText →\n// mkIoError|mkCorruptError` read envelope and one\n// `Effect.try(atomicWriteJsonSync) → mkIoError` write envelope, each\n// parameterised by a typed-error pair. This file centralizes both\n// envelopes around the versioned-doc schemas constructed via\n// `versionedDocSchema` (the sibling file). The caller supplies the error\n// constructors so its typed error channel is preserved end-to-end;\n// crash-atomicity, fsync ordering, and version-stamp handling all live\n// in the underlying primitives.\n//\n// Lives at substrate L0+ — depends on `effect`, `node:fs`, the\n// runtime-decode helpers, and the canonical atomic-write primitive.\n// Kept as a sibling of `versioned-doc-schema.ts` rather than absorbed\n// into it so the schema constructor remains pure-Schema (callable from\n// any L0 declaration site such as `substrate/cross-process.ts`); only\n// callers that actually round-trip a versioned doc to disk pay the\n// fs/runtime-decode import cost.\n\nimport { existsSync, readFileSync } from 'node:fs';\n\nimport { Effect, Schema } from 'effect';\n\nimport { atomicWriteJsonSync } from './runtime/atomic-write.ts';\nimport { decodeJsonText, decodeJsonTextSync } from './runtime/runtime-decode.ts';\n\n/** Constructor pair the caller supplies so its typed error channel is\n *  preserved through the envelope. `mkIo` wraps any node:fs / disk\n *  failure (read OR write); `mkCorrupt` wraps any JSON-parse / Schema-\n *  decode failure (read only). Both helpers thread the on-disk `path`\n *  and — for `mkCorrupt` — the raw bytes that failed to decode so\n *  diagnostics can echo what was actually on disk. */\nexport interface VersionedDocErrors<IoErr, CorruptErr> {\n\treadonly mkIo: (input: { readonly path: string; readonly cause: unknown }) => IoErr;\n\treadonly mkCorrupt: (input: {\n\t\treadonly path: string;\n\t\treadonly raw: string;\n\t\treadonly cause: unknown;\n\t}) => CorruptErr;\n}\n\n/** Constructor for the IO-only case (write path — no decode failure\n *  mode). Split into its own interface so `writeVersionedDocumentSync`\n *  callers don't have to supply a `mkCorrupt` they would never invoke. */\nexport interface VersionedDocIoError<IoErr> {\n\treadonly mkIo: (input: { readonly path: string; readonly cause: unknown }) => IoErr;\n}\n\n/**\n * Read + decode a versioned cross-process document from disk.\n *\n *  - Missing file (`!existsSync`) → returns the caller-supplied\n *    `whenAbsent` default. This is the \"no peer has ever written yet\"\n *    path; the caller decides whether that's an empty document or a\n *    failure.\n *  - Read failure (any `node:fs` error other than ENOENT) → `mkIo`.\n *  - JSON-parse OR Schema-decode failure → `mkCorrupt` with the raw\n *    bytes echoed so callers can log the offending content.\n *\n *  The decode runs through `decodeJsonText`, so the on-disk JSON is\n *  parsed and Schema-validated in one envelope. No atomicity, fsync, or\n *  lock-ordering concerns at the read site — this is pure read-and-\n *  validate.\n */\nexport const readVersionedDocumentSync = <S extends Schema.Decoder<unknown>, IoErr, CorruptErr>(\n\tpath: string,\n\tschema: S,\n\terrors: VersionedDocErrors<IoErr, CorruptErr>,\n\twhenAbsent: S['Type'],\n): Effect.Effect<S['Type'], IoErr | CorruptErr> =>\n\tEffect.gen(function* () {\n\t\tif (!existsSync(path)) return whenAbsent;\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => readFileSync(path, 'utf8'),\n\t\t\tcatch: (cause) => errors.mkIo({ path, cause }),\n\t\t});\n\t\treturn yield* decodeJsonText(schema, raw, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) => errors.mkCorrupt({ path, raw, cause: issue.cause ?? issue }),\n\t\t});\n\t});\n\n/**\n * Sync parse-or-null variant of `readVersionedDocumentSync`. Decodes a\n * raw JSON body against `schema`; returns `null` on parse or decode\n * failure. Use this when a malformed body should be treated the same as\n * a missing body (e.g. a half-written roster entry by a crashed creator,\n * stack-lock body interrupted mid-write) — the call site swaps a\n * try/catch around `decodeJsonTextSync` for one helper call.\n *\n * `source` is purely a diagnostic label for the synthesized error\n * inside `decodeJsonTextSync`'s throw; it is consumed by the catch and\n * discarded along with the error. The caller does not need to thread a\n * typed error constructor — the contract here is \"null means\n * unreadable/malformed; the caller decides what to do next\".\n */\nexport const parseVersionedDocumentBodyOrNull = <S extends Schema.Decoder<unknown>>(\n\traw: string,\n\tschema: S,\n\tsource: string,\n): S['Type'] | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(schema, raw, {\n\t\t\tsource,\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/**\n * Write a versioned cross-process document atomically.\n *\n * Routes through the canonical `atomicWriteJsonSync` primitive — the\n * crash-atomic mkdir-parent → O_EXCL temp → write → fsync → rename\n * dance with one owner of the tempfile cleanup. The version stamp lives in\n * the caller-supplied `value` (every versioned-doc schema carries a\n * literal `version` field via `versionedDocSchema`); this helper does\n * NOT inject a version — it just ensures the typed write envelope\n * (Effect.try → mkIo) is consistent across cross-process sites.\n *\n * No Schema-encode step here: matching `atomicWriteJsonSync`'s contract,\n * cross-process docs are `Schema.Struct` of primitives that round-trip\n * cleanly through plain `JSON.stringify`. The `value` is typed as a\n * generic `D` so the caller's document interface (`RosterDocument`,\n * ...) is what gets serialized.\n *\n * This is the SYNC surface — used by callers that hold `stack.lock`\n * and must keep their critical section non-yielding.\n */\nexport const writeVersionedDocumentSync = <D, IoErr>(\n\tpath: string,\n\tvalue: D,\n\terrors: VersionedDocIoError<IoErr>,\n): Effect.Effect<void, IoErr> =>\n\tEffect.try({\n\t\ttry: () => atomicWriteJsonSync(path, value),\n\t\tcatch: (cause) => errors.mkIo({ path, cause }),\n\t});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAkEA,MAAa,6BACZ,MACA,QACA,QACA,eAEA,OAAO,IAAI,aAAa;CACvB,IAAI,CAAC,WAAW,IAAI,GAAG,OAAO;CAC9B,MAAM,MAAM,OAAO,OAAO,IAAI;EAC7B,WAAW,aAAa,MAAM,MAAM;EACpC,QAAQ,UAAU,OAAO,KAAK;GAAE;GAAM;EAAM,CAAC;CAC9C,CAAC;CACD,OAAO,OAAO,eAAe,QAAQ,KAAK;EACzC,QAAQ;EACR,UAAU,UAAU,OAAO,UAAU;GAAE;GAAM;GAAK,OAAO,MAAM,SAAS;EAAM,CAAC;CAChF,CAAC;AACF,CAAC;;;;;;;;;;;;;;;AAgBF,MAAa,oCACZ,KACA,QACA,WACsB;CACtB,IAAI;EACH,OAAO,mBAAmB,QAAQ,KAAK;GACtC;GACA,UAAU,UAAU;EACrB,CAAC;CACF,QAAQ;EACP,OAAO;CACR;AACD;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,8BACZ,MACA,OACA,WAEA,OAAO,IAAI;CACV,WAAW,oBAAoB,MAAM,KAAK;CAC1C,QAAQ,UAAU,OAAO,KAAK;EAAE;EAAM;CAAM,CAAC;AAC9C,CAAC"}

package/dist/surfaces/cli/command-tree.mjs

@@ -74,24 +74,66 @@ const commands = [
 		sideEffects: "write",
 		requiresDocker: true,
 		description: "Starts the supervisor and renders the attached operator surface.",
-		options: [...configOptions, {
-			name: "renderer",
-			value: "tui|plain|silent",
-			description: "Select the attached renderer."
-		}]
+		options: [
+			...configOptions,
+			{
+				name: "renderer",
+				value: "tui|plain|silent",
+				description: "Select the attached renderer."
+			},
+			{
+				name: "from-snapshot",
+				value: "name-or-id",
+				description: "Start by restoring a snapshot before the initial acquire."
+			},
+			{
+				name: "snapshot-cache",
+				value: "name",
+				description: "Use a named snapshot as a startup cache and refresh it when stale."
+			},
+			{
+				name: "snapshot-stale",
+				value: "warn|block|clean-start",
+				description: "Policy when --from-snapshot inputs differ from the current stack."
+			}
+		]
 	},
 	{
 		name: "apply",
-		summary: "Reconcile through a live supervisor when present; otherwise run one-shot setup.",
+		summary: "Re-emit the per-stack ids file and dev extras from a live or one-shot stack.",
 		usage: "devstack apply [options]",
 		lifecycle: "live-aware",
 		sideEffects: "write",
 		requiresDocker: true,
 		options: configOptions
 	},
+	{
+		name: "codegen",
+		summary: "Regenerate committed bindings from Move source (no stack boot).",
+		usage: "devstack codegen [options]",
+		lifecycle: "one-shot",
+		sideEffects: "write",
+		requiresDocker: false,
+		description: "Move-compiles local package sources and emits the committed src/generated tree (type bindings + sentinel-id config stubs) without booting a stack.",
+		options: configOptions
+	},
+	{
+		name: "dump-ids",
+		summary: "Emit the stack id-config (devstack-ids.json) for a real-network deploy.",
+		usage: "devstack dump-ids [options]",
+		lifecycle: "live-aware",
+		sideEffects: "write",
+		requiresDocker: true,
+		description: "Emits the stack devstack-ids.json id-config to --out (or stdout). Reads the existing file when a supervisor is live; otherwise runs a one-shot boot to produce it, then tears down. The supported way to obtain a committed id-config file for a real-network deploy.",
+		options: [...configOptions, {
+			name: "out",
+			value: "path",
+			description: "Write the id-config JSON to this file instead of stdout."
+		}]
+	},
 	{
 		name: "status",
-		summary: "Show the persisted stack projection.",
+		summary: "Show the current stack projection (offline: from the manifest).",
 		usage: "devstack status [options]",
 		lifecycle: "offline",
 		sideEffects: "read",

package/dist/surfaces/cli/command-tree.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"command-tree.mjs","names":[],"sources":["../../../src/surfaces/cli/command-tree.ts"],"sourcesContent":["import { ENV_VARS } from './flags.ts';\nimport { exitCodeTable } from './sysexits.ts';\n\nexport type CommandLifecycle = 'attached' | 'live-aware' | 'one-shot' | 'offline';\n\nexport interface CommandOption {\n\treadonly name: string;\n\treadonly value?: string;\n\treadonly description: string;\n}\n\nexport interface CommandNode {\n\treadonly name: string;\n\treadonly summary: string;\n\treadonly usage: string;\n\treadonly lifecycle: CommandLifecycle;\n\treadonly sideEffects: 'none' | 'read' | 'write' | 'destructive';\n\treadonly requiresDocker: boolean;\n\treadonly description?: string;\n\treadonly arguments?: ReadonlyArray<string>;\n\treadonly options?: ReadonlyArray<CommandOption>;\n\treadonly subcommands?: ReadonlyArray<CommandNode>;\n}\n\nconst identityOptions = [\n\t{ name: 'json', description: 'Emit JSON envelope output.' },\n\t{ name: 'app', value: 'name', description: 'Override app name.' },\n\t{ name: 'stack', value: 'name', description: 'Override stack name.' },\n\t{ name: 'state-dir', value: 'path', description: 'Override state directory.' },\n\t{ name: 'verbose', description: 'Enable more verbose logging.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst configOptions = [\n\t...identityOptions,\n\t{ name: 'config', value: 'path', description: 'Override devstack.config.ts path.' },\n\t{ name: 'network', value: 'name', description: 'Override network before config import.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst confirmOptions = [\n\t...identityOptions,\n\t{ name: 'yes', description: 'Assume yes on prompts.' },\n\t{ name: 'no-input', description: 'Forbid prompts.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst globalMaintenanceOptions = [\n\t{ name: 'json', description: 'Emit JSON envelope output.' },\n\t{ name: 'state-dir', value: 'path', description: 'Override state directory.' },\n\t{ name: 'verbose', description: 'Enable more verbose logging.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst commands = [\n\t{\n\t\tname: 'up',\n\t\tsummary: 'Boot a stack and stay attached until interrupted.',\n\t\tusage: 'devstack up [options]',\n\t\tlifecycle: 'attached',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: true,\n\t\tdescription: 'Starts the supervisor and renders the attached operator surface.',\n\t\toptions: [\n\t\t\t...configOptions,\n\t\t\t{\n\t\t\t\tname: 'renderer',\n\t\t\t\tvalue: 'tui|plain|silent',\n\t\t\t\tdescription: 'Select the attached renderer.',\n\t\t\t},\n\t\t],\n\t},\n\t{\n\t\tname: 'apply',\n\t\tsummary: 'Reconcile through a live supervisor when present; otherwise run one-shot setup.',\n\t\tusage: 'devstack apply [options]',\n\t\tlifecycle: 'live-aware',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: true,\n\t\toptions: configOptions,\n\t},\n\t{\n\t\tname: 'status',\n\t\tsummary: 'Show the persisted stack projection.',\n\t\tusage: 'devstack status [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'read',\n\t\trequiresDocker: false,\n\t\toptions: identityOptions,\n\t},\n\t{\n\t\tname: 'doctor',\n\t\tsummary: 'Run host and stack preflight checks.',\n\t\tusage: 'devstack doctor [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'read',\n\t\trequiresDocker: true,\n\t\toptions: identityOptions,\n\t},\n\t{\n\t\tname: 'config',\n\t\tsummary: 'Print resolved config inputs.',\n\t\tusage: 'devstack config [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'read',\n\t\trequiresDocker: false,\n\t\toptions: configOptions,\n\t},\n\t{\n\t\tname: 'schema',\n\t\tsummary: 'Emit the CLI schema.',\n\t\tusage: 'devstack schema --json',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'none',\n\t\trequiresDocker: false,\n\t\toptions: [{ name: 'json', description: 'Emit JSON schema output.' }],\n\t},\n\t{\n\t\tname: 'snapshot',\n\t\tsummary: 'Capture, restore, list, or delete stack snapshots.',\n\t\tusage: 'devstack snapshot <command> [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: true,\n\t\tsubcommands: [\n\t\t\t{\n\t\t\t\tname: 'save',\n\t\t\t\tsummary: 'Capture a snapshot through a one-shot stack boot.',\n\t\t\t\tusage: 'devstack snapshot save [name] [options]',\n\t\t\t\tlifecycle: 'one-shot',\n\t\t\t\tsideEffects: 'write',\n\t\t\t\trequiresDocker: true,\n\t\t\t\targuments: ['name'],\n\t\t\t\toptions: [\n\t\t\t\t\t...configOptions,\n\t\t\t\t\t{ name: 'name', value: 'name', description: 'Human-readable snapshot name.' },\n\t\t\t\t],\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'restore',\n\t\t\t\tsummary: 'Restore a snapshot by name or id.',\n\t\t\t\tusage: 'devstack snapshot restore <name-or-id> [options]',\n\t\t\t\tlifecycle: 'offline',\n\t\t\t\tsideEffects: 'destructive',\n\t\t\t\trequiresDocker: true,\n\t\t\t\targuments: ['name-or-id'],\n\t\t\t\toptions: confirmOptions,\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'list',\n\t\t\t\tsummary: 'List snapshots for the selected stack.',\n\t\t\t\tusage: 'devstack snapshot list [options]',\n\t\t\t\tlifecycle: 'offline',\n\t\t\t\tsideEffects: 'read',\n\t\t\t\trequiresDocker: false,\n\t\t\t\toptions: identityOptions,\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'delete',\n\t\t\t\tsummary: 'Delete a snapshot by name or id.',\n\t\t\t\tusage: 'devstack snapshot delete <name-or-id> [options]',\n\t\t\t\tlifecycle: 'offline',\n\t\t\t\tsideEffects: 'destructive',\n\t\t\t\trequiresDocker: false,\n\t\t\t\targuments: ['name-or-id'],\n\t\t\t\toptions: confirmOptions,\n\t\t\t},\n\t\t],\n\t},\n\t{\n\t\tname: 'prune',\n\t\tsummary: 'Inventory and prune devstack-labelled Docker resources.',\n\t\tusage: 'devstack prune [--list | --dry-run | --all --yes] [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'destructive',\n\t\trequiresDocker: true,\n\t\toptions: [\n\t\t\t...globalMaintenanceOptions,\n\t\t\t{ name: 'list', description: 'List resource groups without pruning.' },\n\t\t\t{ name: 'all', description: 'Prune every idle non-shared resource group.' },\n\t\t\t{ name: 'no-containers', description: 'Do not remove containers.' },\n\t\t\t{ name: 'no-networks', description: 'Do not remove networks.' },\n\t\t\t{ name: 'no-volumes', description: 'Do not remove volumes.' },\n\t\t\t{ name: 'include-images', description: 'Also remove devstack-labelled images.' },\n\t\t\t{ name: 'dry-run', description: 'Skip mutating effects.' },\n\t\t\t{ name: 'yes', description: 'Assume yes on prompts.' },\n\t\t\t{ name: 'no-input', description: 'Forbid prompts.' },\n\t\t],\n\t},\n\t{\n\t\tname: 'wipe',\n\t\tsummary: 'Destroy all state for the selected stack.',\n\t\tusage: 'devstack wipe [--dry-run] [--yes] [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'destructive',\n\t\trequiresDocker: true,\n\t\toptions: [\n\t\t\t...identityOptions,\n\t\t\t{ name: 'dry-run', description: 'Skip mutating effects.' },\n\t\t\t{ name: 'yes', description: 'Assume yes on prompts.' },\n\t\t\t{ name: 'no-input', description: 'Forbid prompts.' },\n\t\t],\n\t},\n] as const satisfies ReadonlyArray<CommandNode>;\n\nexport const COMMAND_TREE: CommandNode = {\n\tname: 'devstack',\n\tsummary: 'Sui development stack CLI.',\n\tusage: 'devstack <command> [options]',\n\tlifecycle: 'offline',\n\tsideEffects: 'none',\n\trequiresDocker: false,\n\tdescription: 'Boot, inspect, snapshot, and manage local Sui development stacks.',\n\tsubcommands: commands,\n};\n\nexport type Verb = (typeof commands)[number]['name'];\n\nexport const VERBS: ReadonlyArray<Verb> = commands.map((command) => command.name);\n\nexport const commandSchema = () => ({\n\tschemaVersion: 1,\n\tverbs: VERBS,\n\tcommands: COMMAND_TREE,\n\texitCodes: exitCodeTable,\n\tenvVars: Object.values(ENV_VARS),\n});\n"],"mappings":"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"}
+{"version":3,"file":"command-tree.mjs","names":[],"sources":["../../../src/surfaces/cli/command-tree.ts"],"sourcesContent":["import { ENV_VARS } from './flags.ts';\nimport { exitCodeTable } from './sysexits.ts';\n\nexport type CommandLifecycle = 'attached' | 'live-aware' | 'one-shot' | 'offline';\n\nexport interface CommandOption {\n\treadonly name: string;\n\treadonly value?: string;\n\treadonly description: string;\n}\n\nexport interface CommandNode {\n\treadonly name: string;\n\treadonly summary: string;\n\treadonly usage: string;\n\treadonly lifecycle: CommandLifecycle;\n\treadonly sideEffects: 'none' | 'read' | 'write' | 'destructive';\n\treadonly requiresDocker: boolean;\n\treadonly description?: string;\n\treadonly arguments?: ReadonlyArray<string>;\n\treadonly options?: ReadonlyArray<CommandOption>;\n\treadonly subcommands?: ReadonlyArray<CommandNode>;\n}\n\nconst identityOptions = [\n\t{ name: 'json', description: 'Emit JSON envelope output.' },\n\t{ name: 'app', value: 'name', description: 'Override app name.' },\n\t{ name: 'stack', value: 'name', description: 'Override stack name.' },\n\t{ name: 'state-dir', value: 'path', description: 'Override state directory.' },\n\t{ name: 'verbose', description: 'Enable more verbose logging.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst configOptions = [\n\t...identityOptions,\n\t{ name: 'config', value: 'path', description: 'Override devstack.config.ts path.' },\n\t{ name: 'network', value: 'name', description: 'Override network before config import.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst confirmOptions = [\n\t...identityOptions,\n\t{ name: 'yes', description: 'Assume yes on prompts.' },\n\t{ name: 'no-input', description: 'Forbid prompts.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst globalMaintenanceOptions = [\n\t{ name: 'json', description: 'Emit JSON envelope output.' },\n\t{ name: 'state-dir', value: 'path', description: 'Override state directory.' },\n\t{ name: 'verbose', description: 'Enable more verbose logging.' },\n] as const satisfies ReadonlyArray<CommandOption>;\n\nconst commands = [\n\t{\n\t\tname: 'up',\n\t\tsummary: 'Boot a stack and stay attached until interrupted.',\n\t\tusage: 'devstack up [options]',\n\t\tlifecycle: 'attached',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: true,\n\t\tdescription: 'Starts the supervisor and renders the attached operator surface.',\n\t\toptions: [\n\t\t\t...configOptions,\n\t\t\t{\n\t\t\t\tname: 'renderer',\n\t\t\t\tvalue: 'tui|plain|silent',\n\t\t\t\tdescription: 'Select the attached renderer.',\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'from-snapshot',\n\t\t\t\tvalue: 'name-or-id',\n\t\t\t\tdescription: 'Start by restoring a snapshot before the initial acquire.',\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'snapshot-cache',\n\t\t\t\tvalue: 'name',\n\t\t\t\tdescription: 'Use a named snapshot as a startup cache and refresh it when stale.',\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'snapshot-stale',\n\t\t\t\tvalue: 'warn|block|clean-start',\n\t\t\t\tdescription: 'Policy when --from-snapshot inputs differ from the current stack.',\n\t\t\t},\n\t\t],\n\t},\n\t{\n\t\tname: 'apply',\n\t\tsummary: 'Re-emit the per-stack ids file and dev extras from a live or one-shot stack.',\n\t\tusage: 'devstack apply [options]',\n\t\tlifecycle: 'live-aware',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: true,\n\t\toptions: configOptions,\n\t},\n\t{\n\t\tname: 'codegen',\n\t\tsummary: 'Regenerate committed bindings from Move source (no stack boot).',\n\t\tusage: 'devstack codegen [options]',\n\t\tlifecycle: 'one-shot',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: false,\n\t\tdescription:\n\t\t\t'Move-compiles local package sources and emits the committed src/generated tree (type bindings + sentinel-id config stubs) without booting a stack.',\n\t\toptions: configOptions,\n\t},\n\t{\n\t\tname: 'dump-ids',\n\t\tsummary: 'Emit the stack id-config (devstack-ids.json) for a real-network deploy.',\n\t\tusage: 'devstack dump-ids [options]',\n\t\tlifecycle: 'live-aware',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: true,\n\t\tdescription:\n\t\t\t'Emits the stack devstack-ids.json id-config to --out (or stdout). Reads the existing file when a supervisor is live; otherwise runs a one-shot boot to produce it, then tears down. The supported way to obtain a committed id-config file for a real-network deploy.',\n\t\toptions: [\n\t\t\t...configOptions,\n\t\t\t{\n\t\t\t\tname: 'out',\n\t\t\t\tvalue: 'path',\n\t\t\t\tdescription: 'Write the id-config JSON to this file instead of stdout.',\n\t\t\t},\n\t\t],\n\t},\n\t{\n\t\tname: 'status',\n\t\tsummary: 'Show the current stack projection (offline: from the manifest).',\n\t\tusage: 'devstack status [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'read',\n\t\trequiresDocker: false,\n\t\toptions: identityOptions,\n\t},\n\t{\n\t\tname: 'doctor',\n\t\tsummary: 'Run host and stack preflight checks.',\n\t\tusage: 'devstack doctor [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'read',\n\t\trequiresDocker: true,\n\t\toptions: identityOptions,\n\t},\n\t{\n\t\tname: 'config',\n\t\tsummary: 'Print resolved config inputs.',\n\t\tusage: 'devstack config [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'read',\n\t\trequiresDocker: false,\n\t\toptions: configOptions,\n\t},\n\t{\n\t\tname: 'schema',\n\t\tsummary: 'Emit the CLI schema.',\n\t\tusage: 'devstack schema --json',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'none',\n\t\trequiresDocker: false,\n\t\toptions: [{ name: 'json', description: 'Emit JSON schema output.' }],\n\t},\n\t{\n\t\tname: 'snapshot',\n\t\tsummary: 'Capture, restore, list, or delete stack snapshots.',\n\t\tusage: 'devstack snapshot <command> [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'write',\n\t\trequiresDocker: true,\n\t\tsubcommands: [\n\t\t\t{\n\t\t\t\tname: 'save',\n\t\t\t\tsummary: 'Capture a snapshot through a one-shot stack boot.',\n\t\t\t\tusage: 'devstack snapshot save [name] [options]',\n\t\t\t\tlifecycle: 'one-shot',\n\t\t\t\tsideEffects: 'write',\n\t\t\t\trequiresDocker: true,\n\t\t\t\targuments: ['name'],\n\t\t\t\toptions: [\n\t\t\t\t\t...configOptions,\n\t\t\t\t\t{ name: 'name', value: 'name', description: 'Human-readable snapshot name.' },\n\t\t\t\t],\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'restore',\n\t\t\t\tsummary: 'Restore a snapshot by name or id.',\n\t\t\t\tusage: 'devstack snapshot restore <name-or-id> [options]',\n\t\t\t\tlifecycle: 'offline',\n\t\t\t\tsideEffects: 'destructive',\n\t\t\t\trequiresDocker: true,\n\t\t\t\targuments: ['name-or-id'],\n\t\t\t\toptions: confirmOptions,\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'list',\n\t\t\t\tsummary: 'List snapshots for the selected stack.',\n\t\t\t\tusage: 'devstack snapshot list [options]',\n\t\t\t\tlifecycle: 'offline',\n\t\t\t\tsideEffects: 'read',\n\t\t\t\trequiresDocker: false,\n\t\t\t\toptions: identityOptions,\n\t\t\t},\n\t\t\t{\n\t\t\t\tname: 'delete',\n\t\t\t\tsummary: 'Delete a snapshot by name or id.',\n\t\t\t\tusage: 'devstack snapshot delete <name-or-id> [options]',\n\t\t\t\tlifecycle: 'offline',\n\t\t\t\tsideEffects: 'destructive',\n\t\t\t\trequiresDocker: false,\n\t\t\t\targuments: ['name-or-id'],\n\t\t\t\toptions: confirmOptions,\n\t\t\t},\n\t\t],\n\t},\n\t{\n\t\tname: 'prune',\n\t\tsummary: 'Inventory and prune devstack-labelled Docker resources.',\n\t\tusage: 'devstack prune [--list | --dry-run | --all --yes] [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'destructive',\n\t\trequiresDocker: true,\n\t\toptions: [\n\t\t\t...globalMaintenanceOptions,\n\t\t\t{ name: 'list', description: 'List resource groups without pruning.' },\n\t\t\t{ name: 'all', description: 'Prune every idle non-shared resource group.' },\n\t\t\t{ name: 'no-containers', description: 'Do not remove containers.' },\n\t\t\t{ name: 'no-networks', description: 'Do not remove networks.' },\n\t\t\t{ name: 'no-volumes', description: 'Do not remove volumes.' },\n\t\t\t{ name: 'include-images', description: 'Also remove devstack-labelled images.' },\n\t\t\t{ name: 'dry-run', description: 'Skip mutating effects.' },\n\t\t\t{ name: 'yes', description: 'Assume yes on prompts.' },\n\t\t\t{ name: 'no-input', description: 'Forbid prompts.' },\n\t\t],\n\t},\n\t{\n\t\tname: 'wipe',\n\t\tsummary: 'Destroy all state for the selected stack.',\n\t\tusage: 'devstack wipe [--dry-run] [--yes] [options]',\n\t\tlifecycle: 'offline',\n\t\tsideEffects: 'destructive',\n\t\trequiresDocker: true,\n\t\toptions: [\n\t\t\t...identityOptions,\n\t\t\t{ name: 'dry-run', description: 'Skip mutating effects.' },\n\t\t\t{ name: 'yes', description: 'Assume yes on prompts.' },\n\t\t\t{ name: 'no-input', description: 'Forbid prompts.' },\n\t\t],\n\t},\n] as const satisfies ReadonlyArray<CommandNode>;\n\nexport const COMMAND_TREE: CommandNode = {\n\tname: 'devstack',\n\tsummary: 'Sui development stack CLI.',\n\tusage: 'devstack <command> [options]',\n\tlifecycle: 'offline',\n\tsideEffects: 'none',\n\trequiresDocker: false,\n\tdescription: 'Boot, inspect, snapshot, and manage local Sui development stacks.',\n\tsubcommands: commands,\n};\n\nexport type Verb = (typeof commands)[number]['name'];\n\nexport const VERBS: ReadonlyArray<Verb> = commands.map((command) => command.name);\n\nexport const commandSchema = () => ({\n\tschemaVersion: 1,\n\tverbs: VERBS,\n\tcommands: COMMAND_TREE,\n\texitCodes: exitCodeTable,\n\tenvVars: Object.values(ENV_VARS),\n});\n"],"mappings":"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"}

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

@@ -24,7 +24,7 @@ const runConfig = (deps, ctx) => Effect.gen(function* () {
 		humanLines
 	});
 	return { exitCode: 0 };
-}).pipe(Effect.withSpan("cli.config"));
+});
 //#endregion
 export { runConfig };
 

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

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/config.ts"],"sourcesContent":["// CLI verb: `devstack config` — print resolved config.\n//\n// Observational. Loads the user's `devstack.config.ts`, resolves all\n// active overrides (flag > env > active-stack > default), and emits\n// the projection. Never publishes a command.\n//\n// JSON output is canonical: it is the same shape the programmable\n// API exposes for \"what is my config right now?\", so build\n// integrations can pin against it.\n\nimport { Effect } from 'effect';\n\nimport type { ConfigLoader, LoadedConfig } from './config-loader.ts';\nimport type { CliError } from '../errors.ts';\nimport { emitSuccess } from '../output.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\nexport interface ConfigDeps {\n\treadonly loader: ConfigLoader;\n}\n\nexport const runConfig = (\n\tdeps: ConfigDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst loaded: LoadedConfig = yield* deps.loader.load(ctx.flags.configPath);\n\t\tconst data = {\n\t\t\tresolvedConfigPath: loaded.resolvedConfigPath,\n\t\t\tapp: ctx.flags.app ?? null,\n\t\t\tstack: ctx.flags.stack ?? null,\n\t\t\tstateDir: ctx.flags.stateDir ?? null,\n\t\t\tnetwork: ctx.flags.network ?? null,\n\t\t};\n\t\tconst humanLines = [\n\t\t\t`config:    ${data.resolvedConfigPath}`,\n\t\t\t`app:       ${data.app ?? '(default)'}`,\n\t\t\t`stack:     ${data.stack ?? '(default)'}`,\n\t\t\t`stateDir:  ${data.stateDir ?? '(default)'}`,\n\t\t\t`network:   ${data.network ?? '(default)'}`,\n\t\t];\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'config',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata,\n\t\t\thumanLines,\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t}).pipe(Effect.withSpan('cli.config'));\n"],"mappings":";;;AAqBA,MAAa,aACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,KAAK,KAAK;CAE1B,MAAM,OAAO;EACZ,qBAAoB,OAFe,KAAK,OAAO,KAAK,IAAI,MAAM,WAAW,EAE9C;EAC3B,KAAK,IAAI,MAAM,OAAO;EACtB,OAAO,IAAI,MAAM,SAAS;EAC1B,UAAU,IAAI,MAAM,YAAY;EAChC,SAAS,IAAI,MAAM,WAAW;EAC9B;CACD,MAAM,aAAa;EAClB,cAAc,KAAK;EACnB,cAAc,KAAK,OAAO;EAC1B,cAAc,KAAK,SAAS;EAC5B,cAAc,KAAK,YAAY;EAC/B,cAAc,KAAK,WAAW;EAC9B;AACD,QAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;EAChD,SAAS;EACT,WAAW,KAAK,KAAK,GAAG;EACxB;EACA;EACA,CAAC;AACF,QAAO,EAAE,UAAU,GAAG;EACrB,CAAC,KAAK,OAAO,SAAS,aAAa,CAAC"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/config.ts"],"sourcesContent":["// CLI verb: `devstack config` — print resolved config.\n//\n// Observational. Loads the user's `devstack.config.ts`, resolves all\n// active overrides (flag > env > active-stack > default), and emits\n// the projection. Never publishes a command.\n//\n// JSON output is canonical: it is the same shape the programmable\n// API exposes for \"what is my config right now?\", so build\n// integrations can pin against it.\n\nimport { Effect } from 'effect';\n\nimport type { ConfigLoader, LoadedConfig } from './config-loader.ts';\nimport type { CliError } from '../errors.ts';\nimport { emitSuccess } from '../output.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\nexport interface ConfigDeps {\n\treadonly loader: ConfigLoader;\n}\n\nexport const runConfig = (\n\tdeps: ConfigDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst loaded: LoadedConfig = yield* deps.loader.load(ctx.flags.configPath);\n\t\tconst data = {\n\t\t\tresolvedConfigPath: loaded.resolvedConfigPath,\n\t\t\tapp: ctx.flags.app ?? null,\n\t\t\tstack: ctx.flags.stack ?? null,\n\t\t\tstateDir: ctx.flags.stateDir ?? null,\n\t\t\tnetwork: ctx.flags.network ?? null,\n\t\t};\n\t\tconst humanLines = [\n\t\t\t`config:    ${data.resolvedConfigPath}`,\n\t\t\t`app:       ${data.app ?? '(default)'}`,\n\t\t\t`stack:     ${data.stack ?? '(default)'}`,\n\t\t\t`stateDir:  ${data.stateDir ?? '(default)'}`,\n\t\t\t`network:   ${data.network ?? '(default)'}`,\n\t\t];\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'config',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata,\n\t\t\thumanLines,\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t});\n"],"mappings":";;;AAqBA,MAAa,aACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,KAAK,IAAI;CAEzB,MAAM,OAAO;EACZ,qBAAoB,OAFe,KAAK,OAAO,KAAK,IAAI,MAAM,UAAU,EAAA,CAE7C;EAC3B,KAAK,IAAI,MAAM,OAAO;EACtB,OAAO,IAAI,MAAM,SAAS;EAC1B,UAAU,IAAI,MAAM,YAAY;EAChC,SAAS,IAAI,MAAM,WAAW;CAC/B;CACA,MAAM,aAAa;EAClB,cAAc,KAAK;EACnB,cAAc,KAAK,OAAO;EAC1B,cAAc,KAAK,SAAS;EAC5B,cAAc,KAAK,YAAY;EAC/B,cAAc,KAAK,WAAW;CAC/B;CACA,OAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;EAChD,SAAS;EACT,WAAW,KAAK,IAAI,IAAI;EACxB;EACA;CACD,CAAC;CACD,OAAO,EAAE,UAAU,EAAE;AACtB,CAAC"}

package/dist/surfaces/cli/commands/confirm-node.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"confirm-node.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/confirm-node.ts"],"sourcesContent":["import { stderr, stdin } from 'node:process';\nimport { createInterface } from 'node:readline/promises';\n\nimport { Effect } from 'effect';\n\nimport { CliInternalError } from '../errors.ts';\nimport type { ConfirmPrompt } from './confirm.ts';\n\nexport const nodeConfirmPrompt: ConfirmPrompt = (input) =>\n\tEffect.tryPromise({\n\t\ttry: async () => {\n\t\t\tconst rl = createInterface({ input: stdin, output: stderr });\n\t\t\ttry {\n\t\t\t\tconst answer = await rl.question(`${input.prompt} Type y to continue: `);\n\t\t\t\treturn answer.trim().toLowerCase() === 'y';\n\t\t\t} finally {\n\t\t\t\trl.close();\n\t\t\t}\n\t\t},\n\t\tcatch: (cause) =>\n\t\t\tnew CliInternalError({\n\t\t\t\tmessage: `${input.verb} confirmation prompt failed`,\n\t\t\t\tcause,\n\t\t\t}),\n\t});\n"],"mappings":";;;;;AAQA,MAAa,qBAAoC,UAChD,OAAO,WAAW;CACjB,KAAK,YAAY;EAChB,MAAM,KAAK,gBAAgB;GAAE,OAAO;GAAO,QAAQ;GAAQ,CAAC;AAC5D,MAAI;AAEH,WAAO,MADc,GAAG,SAAS,GAAG,MAAM,OAAO,uBAAuB,EAC1D,MAAM,CAAC,aAAa,KAAK;YAC9B;AACT,MAAG,OAAO;;;CAGZ,QAAQ,UACP,IAAI,iBAAiB;EACpB,SAAS,GAAG,MAAM,KAAK;EACvB;EACA,CAAC;CACH,CAAC"}
+{"version":3,"file":"confirm-node.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/confirm-node.ts"],"sourcesContent":["import { stderr, stdin } from 'node:process';\nimport { createInterface } from 'node:readline/promises';\n\nimport { Effect } from 'effect';\n\nimport { CliInternalError } from '../errors.ts';\nimport type { ConfirmPrompt } from './confirm.ts';\n\nexport const nodeConfirmPrompt: ConfirmPrompt = (input) =>\n\tEffect.tryPromise({\n\t\ttry: async () => {\n\t\t\tconst rl = createInterface({ input: stdin, output: stderr });\n\t\t\ttry {\n\t\t\t\tconst answer = await rl.question(`${input.prompt} Type y to continue: `);\n\t\t\t\treturn answer.trim().toLowerCase() === 'y';\n\t\t\t} finally {\n\t\t\t\trl.close();\n\t\t\t}\n\t\t},\n\t\tcatch: (cause) =>\n\t\t\tnew CliInternalError({\n\t\t\t\tmessage: `${input.verb} confirmation prompt failed`,\n\t\t\t\tcause,\n\t\t\t}),\n\t});\n"],"mappings":";;;;;AAQA,MAAa,qBAAoC,UAChD,OAAO,WAAW;CACjB,KAAK,YAAY;EAChB,MAAM,KAAK,gBAAgB;GAAE,OAAO;GAAO,QAAQ;EAAO,CAAC;EAC3D,IAAI;GAEH,QAAO,MADc,GAAG,SAAS,GAAG,MAAM,OAAO,sBAAsB,EAAA,CACzD,KAAK,CAAC,CAAC,YAAY,MAAM;EACxC,UAAU;GACT,GAAG,MAAM;EACV;CACD;CACA,QAAQ,UACP,IAAI,iBAAiB;EACpB,SAAS,GAAG,MAAM,KAAK;EACvB;CACD,CAAC;AACH,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"confirm.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/confirm.ts"],"sourcesContent":["import { Effect } from 'effect';\n\nimport {\n\ttype CliError,\n\tCliConfirmDeclinedError,\n\tCliConfirmRequiredError,\n\tCliInternalError,\n\tisCliError,\n} from '../errors.ts';\nimport type { CommandContext } from './index.ts';\n\nexport interface ConfirmPromptInput {\n\treadonly verb: string;\n\treadonly prompt: string;\n}\n\nexport type ConfirmPrompt = (input: ConfirmPromptInput) => Effect.Effect<boolean, unknown>;\n\nexport const confirmDestructive = (\n\tconfirm: ConfirmPrompt,\n\tctx: CommandContext,\n\tinput: ConfirmPromptInput & { readonly skipWhenDryRun?: boolean },\n): Effect.Effect<void, CliError> =>\n\tEffect.gen(function* () {\n\t\tif (input.skipWhenDryRun !== false && ctx.flags.dryRun) return;\n\t\tconst { assumeYes, forbidPrompt, stdinIsTty } = ctx.flags.confirm;\n\t\tif (assumeYes) return;\n\t\tif (forbidPrompt || !stdinIsTty) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliConfirmRequiredError({\n\t\t\t\t\tverb: input.verb,\n\t\t\t\t\thint: 'rerun with --yes or run in a TTY to confirm interactively',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst confirmed = yield* confirm({ verb: input.verb, prompt: input.prompt }).pipe(\n\t\t\tEffect.catch((cause: unknown) =>\n\t\t\t\tisCliError(cause)\n\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t: Effect.fail(\n\t\t\t\t\t\t\tnew CliInternalError({\n\t\t\t\t\t\t\t\tmessage: `${input.verb} confirmation prompt failed`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\tif (!confirmed) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliConfirmDeclinedError({\n\t\t\t\t\tverb: input.verb,\n\t\t\t\t\thint: 'rerun with --yes to skip interactive confirmation',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t});\n"],"mappings":";;;AAkBA,MAAa,sBACZ,SACA,KACA,UAEA,OAAO,IAAI,aAAa;AACvB,KAAI,MAAM,mBAAmB,SAAS,IAAI,MAAM,OAAQ;CACxD,MAAM,EAAE,WAAW,cAAc,eAAe,IAAI,MAAM;AAC1D,KAAI,UAAW;AACf,KAAI,gBAAgB,CAAC,WACpB,QAAO,OAAO,OAAO,KACpB,IAAI,wBAAwB;EAC3B,MAAM,MAAM;EACZ,MAAM;EACN,CAAC,CACF;AAcF,KAAI,EAAC,OAZoB,QAAQ;EAAE,MAAM,MAAM;EAAM,QAAQ,MAAM;EAAQ,CAAC,CAAC,KAC5E,OAAO,OAAO,UACb,WAAW,MAAM,GACd,OAAO,KAAK,MAAM,GAClB,OAAO,KACP,IAAI,iBAAiB;EACpB,SAAS,GAAG,MAAM,KAAK;EACvB;EACA,CAAC,CACF,CACH,CACD,EAEA,QAAO,OAAO,OAAO,KACpB,IAAI,wBAAwB;EAC3B,MAAM,MAAM;EACZ,MAAM;EACN,CAAC,CACF;EAED"}
+{"version":3,"file":"confirm.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/confirm.ts"],"sourcesContent":["import { Effect } from 'effect';\n\nimport {\n\ttype CliError,\n\tCliConfirmDeclinedError,\n\tCliConfirmRequiredError,\n\tCliInternalError,\n\tisCliError,\n} from '../errors.ts';\nimport type { CommandContext } from './index.ts';\n\nexport interface ConfirmPromptInput {\n\treadonly verb: string;\n\treadonly prompt: string;\n}\n\nexport type ConfirmPrompt = (input: ConfirmPromptInput) => Effect.Effect<boolean, unknown>;\n\nexport const confirmDestructive = (\n\tconfirm: ConfirmPrompt,\n\tctx: CommandContext,\n\tinput: ConfirmPromptInput & { readonly skipWhenDryRun?: boolean },\n): Effect.Effect<void, CliError> =>\n\tEffect.gen(function* () {\n\t\tif (input.skipWhenDryRun !== false && ctx.flags.dryRun) return;\n\t\tconst { assumeYes, forbidPrompt, stdinIsTty } = ctx.flags.confirm;\n\t\tif (assumeYes) return;\n\t\tif (forbidPrompt || !stdinIsTty) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliConfirmRequiredError({\n\t\t\t\t\tverb: input.verb,\n\t\t\t\t\thint: 'rerun with --yes or run in a TTY to confirm interactively',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst confirmed = yield* confirm({ verb: input.verb, prompt: input.prompt }).pipe(\n\t\t\tEffect.catch((cause: unknown) =>\n\t\t\t\tisCliError(cause)\n\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t: Effect.fail(\n\t\t\t\t\t\t\tnew CliInternalError({\n\t\t\t\t\t\t\t\tmessage: `${input.verb} confirmation prompt failed`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\tif (!confirmed) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliConfirmDeclinedError({\n\t\t\t\t\tverb: input.verb,\n\t\t\t\t\thint: 'rerun with --yes to skip interactive confirmation',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t});\n"],"mappings":";;;AAkBA,MAAa,sBACZ,SACA,KACA,UAEA,OAAO,IAAI,aAAa;CACvB,IAAI,MAAM,mBAAmB,SAAS,IAAI,MAAM,QAAQ;CACxD,MAAM,EAAE,WAAW,cAAc,eAAe,IAAI,MAAM;CAC1D,IAAI,WAAW;CACf,IAAI,gBAAgB,CAAC,YACpB,OAAO,OAAO,OAAO,KACpB,IAAI,wBAAwB;EAC3B,MAAM,MAAM;EACZ,MAAM;CACP,CAAC,CACF;CAcD,IAAI,EAAC,OAZoB,QAAQ;EAAE,MAAM,MAAM;EAAM,QAAQ,MAAM;CAAO,CAAC,CAAC,CAAC,KAC5E,OAAO,OAAO,UACb,WAAW,KAAK,IACb,OAAO,KAAK,KAAK,IACjB,OAAO,KACP,IAAI,iBAAiB;EACpB,SAAS,GAAG,MAAM,KAAK;EACvB;CACD,CAAC,CACF,CACH,CACD,IAEC,OAAO,OAAO,OAAO,KACpB,IAAI,wBAAwB;EAC3B,MAAM,MAAM;EACZ,MAAM;CACP,CAAC,CACF;AAEF,CAAC"}

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

@@ -31,7 +31,7 @@ const runDoctor = (deps, ctx) => Effect.gen(function* () {
 		humanLines
 	});
 	return { exitCode: 0 };
-}).pipe(Effect.withSpan("cli.doctor"));
+});
 //#endregion
 export { runDoctor };
 

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/doctor.ts"],"sourcesContent":["// CLI verb: `devstack doctor` — health check / lint of the user's\n// stack.\n//\n// Architecture (distilled/20-cli.md § Subcommands § Diagnostic):\n//   \"doctor — preflight check matrix + environment inventory,\n//    optionally cleaning stale locks.\"\n//\n// Doctor runs a fixed set of probes. Each probe returns a typed\n// outcome (ok | warn | fail | unavailable); the verb projects them\n// into the JSON data block / human table. Probes are pluggable —\n// the dispatcher composes the L1 docker probe, the move-build-lock\n// probe, the port-allocator probe, etc. The CLI just orchestrates.\n//\n// Surface invariant (architecture § Learnings): \"Doctor's port probe\n// must mirror the engine.\" — the probes themselves must be wired to\n// the same primitives the engine uses.\n\nimport { Effect } from 'effect';\n\nimport { type CliError, CliUnavailableError } from '../errors.ts';\nimport { emitSuccess } from '../output.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\nexport type ProbeOutcome =\n\t| { readonly status: 'ok'; readonly detail?: string }\n\t| { readonly status: 'warn'; readonly detail: string }\n\t| { readonly status: 'fail'; readonly detail: string }\n\t| { readonly status: 'unavailable'; readonly detail: string };\n\nexport interface Probe {\n\treadonly name: string;\n\treadonly description: string;\n\treadonly required: boolean;\n\treadonly run: () => Effect.Effect<ProbeOutcome>;\n}\n\nexport interface ProbeReport {\n\treadonly name: string;\n\treadonly description: string;\n\treadonly required: boolean;\n\treadonly outcome: ProbeOutcome;\n}\n\nexport interface DoctorDeps {\n\treadonly probes: ReadonlyArray<Probe>;\n}\n\nexport const runDoctor = (\n\tdeps: DoctorDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst reports: Array<ProbeReport> = [];\n\t\tfor (const probe of deps.probes) {\n\t\t\tconst outcome = yield* probe.run();\n\t\t\treports.push({\n\t\t\t\tname: probe.name,\n\t\t\t\tdescription: probe.description,\n\t\t\t\trequired: probe.required,\n\t\t\t\toutcome,\n\t\t\t});\n\t\t}\n\t\tconst requiredFailures = reports.filter(\n\t\t\t(\n\t\t\t\tr,\n\t\t\t): r is ProbeReport & {\n\t\t\t\toutcome: Extract<ProbeOutcome, { status: 'fail' | 'unavailable' }>;\n\t\t\t} => r.required && (r.outcome.status === 'fail' || r.outcome.status === 'unavailable'),\n\t\t);\n\t\tif (requiredFailures.length > 0) {\n\t\t\t// Surface the first required-failure as an `Unavailable`\n\t\t\t// error so the exit code is `EX_UNAVAILABLE` (architecture\n\t\t\t// edge-case: \"Docker daemon unreachable → doctor surfaces a\n\t\t\t// required-check failure with the unavailable exit code\").\n\t\t\tconst first = requiredFailures[0]!;\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliUnavailableError({\n\t\t\t\t\tmessage: first.outcome.detail,\n\t\t\t\t\tservice: first.name,\n\t\t\t\t\thint: first.outcome.detail,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst humanLines = reports.map(\n\t\t\t(r) =>\n\t\t\t\t`${r.outcome.status.padEnd(11, ' ')} ${r.name}${\n\t\t\t\t\tr.outcome.status !== 'ok' && 'detail' in r.outcome ? ` — ${r.outcome.detail ?? ''}` : ''\n\t\t\t\t}`,\n\t\t);\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'doctor',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata: { reports },\n\t\t\thumanLines,\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t}).pipe(Effect.withSpan('cli.doctor'));\n"],"mappings":";;;;AA+CA,MAAa,aACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,KAAK,KAAK;CAC1B,MAAM,UAA8B,EAAE;AACtC,MAAK,MAAM,SAAS,KAAK,QAAQ;EAChC,MAAM,UAAU,OAAO,MAAM,KAAK;AAClC,UAAQ,KAAK;GACZ,MAAM,MAAM;GACZ,aAAa,MAAM;GACnB,UAAU,MAAM;GAChB;GACA,CAAC;;CAEH,MAAM,mBAAmB,QAAQ,QAE/B,MAGI,EAAE,aAAa,EAAE,QAAQ,WAAW,UAAU,EAAE,QAAQ,WAAW,eACxE;AACD,KAAI,iBAAiB,SAAS,GAAG;EAKhC,MAAM,QAAQ,iBAAiB;AAC/B,SAAO,OAAO,OAAO,KACpB,IAAI,oBAAoB;GACvB,SAAS,MAAM,QAAQ;GACvB,SAAS,MAAM;GACf,MAAM,MAAM,QAAQ;GACpB,CAAC,CACF;;CAEF,MAAM,aAAa,QAAQ,KACzB,MACA,GAAG,EAAE,QAAQ,OAAO,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,OACxC,EAAE,QAAQ,WAAW,QAAQ,YAAY,EAAE,UAAU,MAAM,EAAE,QAAQ,UAAU,OAAO,KAExF;AACD,QAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;EAChD,SAAS;EACT,WAAW,KAAK,KAAK,GAAG;EACxB,MAAM,EAAE,SAAS;EACjB;EACA,CAAC;AACF,QAAO,EAAE,UAAU,GAAG;EACrB,CAAC,KAAK,OAAO,SAAS,aAAa,CAAC"}
+{"version":3,"file":"doctor.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/doctor.ts"],"sourcesContent":["// CLI verb: `devstack doctor` — health check / lint of the user's\n// stack.\n//\n// Architecture (distilled/20-cli.md § Subcommands § Diagnostic):\n//   \"doctor — preflight check matrix + environment inventory,\n//    optionally cleaning stale locks.\"\n//\n// Doctor runs a fixed set of probes. Each probe returns a typed\n// outcome (ok | warn | fail | unavailable); the verb projects them\n// into the JSON data block / human table. Probes are pluggable —\n// the dispatcher composes the L1 docker probe, the move-build-lock\n// probe, the port-allocator probe, etc. The CLI just orchestrates.\n//\n// Surface invariant (architecture § Learnings): \"Doctor's port probe\n// must mirror the engine.\" — the probes themselves must be wired to\n// the same primitives the engine uses.\n\nimport { Effect } from 'effect';\n\nimport { type CliError, CliUnavailableError } from '../errors.ts';\nimport { emitSuccess } from '../output.ts';\nimport type { CommandContext, CommandResult } from './index.ts';\n\nexport type ProbeOutcome =\n\t| { readonly status: 'ok'; readonly detail?: string }\n\t| { readonly status: 'warn'; readonly detail: string }\n\t| { readonly status: 'fail'; readonly detail: string }\n\t| { readonly status: 'unavailable'; readonly detail: string };\n\nexport interface Probe {\n\treadonly name: string;\n\treadonly description: string;\n\treadonly required: boolean;\n\treadonly run: () => Effect.Effect<ProbeOutcome>;\n}\n\nexport interface ProbeReport {\n\treadonly name: string;\n\treadonly description: string;\n\treadonly required: boolean;\n\treadonly outcome: ProbeOutcome;\n}\n\nexport interface DoctorDeps {\n\treadonly probes: ReadonlyArray<Probe>;\n}\n\nexport const runDoctor = (\n\tdeps: DoctorDeps,\n\tctx: CommandContext,\n): Effect.Effect<CommandResult, CliError> =>\n\tEffect.gen(function* () {\n\t\tconst started = Date.now();\n\t\tconst reports: Array<ProbeReport> = [];\n\t\tfor (const probe of deps.probes) {\n\t\t\tconst outcome = yield* probe.run();\n\t\t\treports.push({\n\t\t\t\tname: probe.name,\n\t\t\t\tdescription: probe.description,\n\t\t\t\trequired: probe.required,\n\t\t\t\toutcome,\n\t\t\t});\n\t\t}\n\t\tconst requiredFailures = reports.filter(\n\t\t\t(\n\t\t\t\tr,\n\t\t\t): r is ProbeReport & {\n\t\t\t\toutcome: Extract<ProbeOutcome, { status: 'fail' | 'unavailable' }>;\n\t\t\t} => r.required && (r.outcome.status === 'fail' || r.outcome.status === 'unavailable'),\n\t\t);\n\t\tif (requiredFailures.length > 0) {\n\t\t\t// Surface the first required-failure as an `Unavailable`\n\t\t\t// error so the exit code is `EX_UNAVAILABLE` (architecture\n\t\t\t// edge-case: \"Docker daemon unreachable → doctor surfaces a\n\t\t\t// required-check failure with the unavailable exit code\").\n\t\t\tconst first = requiredFailures[0]!;\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew CliUnavailableError({\n\t\t\t\t\tmessage: first.outcome.detail,\n\t\t\t\t\tservice: first.name,\n\t\t\t\t\thint: first.outcome.detail,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst humanLines = reports.map(\n\t\t\t(r) =>\n\t\t\t\t`${r.outcome.status.padEnd(11, ' ')} ${r.name}${\n\t\t\t\t\tr.outcome.status !== 'ok' && 'detail' in r.outcome ? ` — ${r.outcome.detail ?? ''}` : ''\n\t\t\t\t}`,\n\t\t);\n\t\tyield* emitSuccess(ctx.io, ctx.flags.outputMode, {\n\t\t\tcommand: 'doctor',\n\t\t\telapsedMs: Date.now() - started,\n\t\t\tdata: { reports },\n\t\t\thumanLines,\n\t\t});\n\t\treturn { exitCode: 0 } as CommandResult;\n\t});\n"],"mappings":";;;;AA+CA,MAAa,aACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAU,KAAK,IAAI;CACzB,MAAM,UAA8B,CAAC;CACrC,KAAK,MAAM,SAAS,KAAK,QAAQ;EAChC,MAAM,UAAU,OAAO,MAAM,IAAI;EACjC,QAAQ,KAAK;GACZ,MAAM,MAAM;GACZ,aAAa,MAAM;GACnB,UAAU,MAAM;GAChB;EACD,CAAC;CACF;CACA,MAAM,mBAAmB,QAAQ,QAE/B,MAGI,EAAE,aAAa,EAAE,QAAQ,WAAW,UAAU,EAAE,QAAQ,WAAW,cACzE;CACA,IAAI,iBAAiB,SAAS,GAAG;EAKhC,MAAM,QAAQ,iBAAiB;EAC/B,OAAO,OAAO,OAAO,KACpB,IAAI,oBAAoB;GACvB,SAAS,MAAM,QAAQ;GACvB,SAAS,MAAM;GACf,MAAM,MAAM,QAAQ;EACrB,CAAC,CACF;CACD;CACA,MAAM,aAAa,QAAQ,KACzB,MACA,GAAG,EAAE,QAAQ,OAAO,OAAO,IAAI,GAAG,EAAE,GAAG,EAAE,OACxC,EAAE,QAAQ,WAAW,QAAQ,YAAY,EAAE,UAAU,MAAM,EAAE,QAAQ,UAAU,OAAO,IAEzF;CACA,OAAO,YAAY,IAAI,IAAI,IAAI,MAAM,YAAY;EAChD,SAAS;EACT,WAAW,KAAK,IAAI,IAAI;EACxB,MAAM,EAAE,QAAQ;EAChB;CACD,CAAC;CACD,OAAO,EAAE,UAAU,EAAE;AACtB,CAAC"}

package/dist/surfaces/cli/commands/prune-picker-entry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"prune-picker-entry.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/prune-picker-entry.ts"],"sourcesContent":["// Lazy seam for the ink/react-based prune-picker UI.\n//\n// `cli/prune-direct.ts` is on every `devstack` CLI invocation path, so\n// the picker entry MUST NOT eagerly pull `ink` + `react` (~ several MB\n// of cold-start cost). Mirrors the `surfaces/tui/index.ts:dynamic\n// import('./mount-ink.tsx')` lazy-import pattern.\n\nimport { Effect } from 'effect';\n\nimport type { PruneInventory, PruneResourceScope, PruneTargetSelection } from './prune.ts';\n\nexport const selectPruneTargets = (\n\tinventory: PruneInventory,\n\tresources: PruneResourceScope,\n): Effect.Effect<PruneTargetSelection> => {\n\tif (inventory.groups.length === 0) return Effect.succeed({ groupKeys: [], resources });\n\treturn Effect.promise(() => import('./prune-picker.tsx')).pipe(\n\t\tEffect.flatMap((mod) => mod.selectPruneTargets(inventory, resources)),\n\t);\n};\n"],"mappings":";;AAWA,MAAa,sBACZ,WACA,cACyC;AACzC,KAAI,UAAU,OAAO,WAAW,EAAG,QAAO,OAAO,QAAQ;EAAE,WAAW,EAAE;EAAE;EAAW,CAAC;AACtF,QAAO,OAAO,cAAc,OAAO,sBAAsB,CAAC,KACzD,OAAO,SAAS,QAAQ,IAAI,mBAAmB,WAAW,UAAU,CAAC,CACrE"}
+{"version":3,"file":"prune-picker-entry.mjs","names":[],"sources":["../../../../src/surfaces/cli/commands/prune-picker-entry.ts"],"sourcesContent":["// Lazy seam for the ink/react-based prune-picker UI.\n//\n// `cli/prune-direct.ts` is on every `devstack` CLI invocation path, so\n// the picker entry MUST NOT eagerly pull `ink` + `react` (~ several MB\n// of cold-start cost). Mirrors the `surfaces/tui/index.ts:dynamic\n// import('./mount-ink.tsx')` lazy-import pattern.\n\nimport { Effect } from 'effect';\n\nimport type { PruneInventory, PruneResourceScope, PruneTargetSelection } from './prune.ts';\n\nexport const selectPruneTargets = (\n\tinventory: PruneInventory,\n\tresources: PruneResourceScope,\n): Effect.Effect<PruneTargetSelection> => {\n\tif (inventory.groups.length === 0) return Effect.succeed({ groupKeys: [], resources });\n\treturn Effect.promise(() => import('./prune-picker.tsx')).pipe(\n\t\tEffect.flatMap((mod) => mod.selectPruneTargets(inventory, resources)),\n\t);\n};\n"],"mappings":";;AAWA,MAAa,sBACZ,WACA,cACyC;CACzC,IAAI,UAAU,OAAO,WAAW,GAAG,OAAO,OAAO,QAAQ;EAAE,WAAW,CAAC;EAAG;CAAU,CAAC;CACrF,OAAO,OAAO,cAAc,OAAO,qBAAqB,CAAC,CAAC,KACzD,OAAO,SAAS,QAAQ,IAAI,mBAAmB,WAAW,SAAS,CAAC,CACrE;AACD"}