@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/cli/main.mjs

@@ -1,149 +1,72 @@
 #!/usr/bin/env node
-import { StackPathsService } from "../substrate/runtime/paths.mjs";
-import { appName, chainId, stackName } from "../substrate/brand.mjs";
-import { claim, heartbeatFiber, release } from "../substrate/runtime/cross-process/roster.mjs";
-import { readStackEngine } from "../api/define-devstack.mjs";
-import { makeProjectionRef } from "../substrate/runtime/projection/state-ref.mjs";
-import { persistProjectionChanges, readProjectionSnapshot, writeProjectionSnapshot } from "../substrate/runtime/projection/persisted.mjs";
-import { buildSubstrateLayers, superviseStackEffect } from "../substrate/runtime/run.mjs";
-import { commandChannelPaths, makeCommandChannelPublisher, makeCommandChannelSubscriber } from "../substrate/runtime/cross-process/command-channel/channel.mjs";
-import { SnapshotOrchestratorService } from "../orchestrators/snapshot/service.mjs";
-import { buildProductionOrchestratorSinks, buildProductionPostAcquireHook, layerProductionOrchestrators } from "../orchestrators/runtime-composition.mjs";
-import { extendBuiltInPluginContext, layerBuiltInPluginRuntime } from "../runtime/built-in-plugin-layers.mjs";
-import { resolveAppName, resolveStackName } from "../api/inference-network.mjs";
+import { readProjectionSnapshot } from "../substrate/runtime/projection/persisted.mjs";
+import "../substrate/runtime/index.mjs";
+import { DevstackNetworkParseError, resolveAppName, resolveNetworkSync, resolveStackName, resolveStateDir } from "../api/inference-network.mjs";
 import { ExitCode } from "../surfaces/cli/sysexits.mjs";
-import { CliConfigInvalidError, CliConfigNotFoundError, CliSupervisorLiveError } from "../surfaces/cli/errors.mjs";
-import { removeRouterDispatchFilesForStack } from "../orchestrators/router/cleanup.mjs";
-import { probeSupervisorPresence } from "../surfaces/cli/commands/supervisor-presence.mjs";
-import { defaultProbes } from "../surfaces/cli/commands/doctor-probes.mjs";
+import { CliUsageError } from "../surfaces/cli/errors.mjs";
+import { ENV_VARS } from "../surfaces/cli/flags.mjs";
+import { emitFailure, nodeProcessIO } from "../surfaces/cli/output.mjs";
 import { dispatch } from "../surfaces/cli/index.mjs";
+import { defaultProbes } from "./doctor-probes.mjs";
 import { nodeConfirmPrompt } from "../surfaces/cli/commands/confirm-node.mjs";
-import { makeTuiSurface } from "../surfaces/tui/index.mjs";
 import { makeSnapshotReader } from "./snapshot-reader.mjs";
-import { makeQueueCommandPublisher, resolveUpRendererMode } from "./up-lifecycle.mjs";
 import { makeDirectPruneDeps } from "./prune-direct.mjs";
-import { Cause, Effect, Exit, FileSystem, Layer, Logger, Queue, Stream, SubscriptionRef } from "effect";
-import { existsSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { makeConfigLoader, resolveConfigPath } from "./wirings/config-loader.mjs";
+import { runUpLive } from "./wirings/up.mjs";
+import { runApplyLive } from "./wirings/apply.mjs";
+import { runSnapshotCaptureLiveAware, runSnapshotDeleteDirect, runSnapshotRestoreDirect } from "./wirings/snapshot.mjs";
+import { runWipeDirect, runWipePlanDirect } from "./wirings/wipe.mjs";
+import { Effect } from "effect";
+import { realpathSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/cli/main.ts
-const DEFAULT_CONFIG_PATH = "./devstack.config.ts";
-const LIVE_APPLY_ACK_TIMEOUT_MILLIS = 600 * 1e3;
-const stackRootFor = (runtimeRoot, stack) => resolve(runtimeRoot, "stacks", stack);
-const rosterPathsFor = (stackRoot) => ({
-	stackLockFile: resolve(stackRoot, "stack.lock"),
-	rosterFile: resolve(stackRoot, "roster.json")
-});
-const ENGINE_COMMAND_TAGS = new Set([
-	"stack.start",
-	"stack.stop",
-	"stack.restart",
-	"apply.requested",
-	"codegen.requested",
-	"snapshot.capture",
-	"snapshot.restore",
-	"snapshot.list",
-	"snapshot.delete",
-	"wipe.requested",
-	"prune.requested",
-	"advance-clock.requested",
-	"shutdown.requested",
-	"shutdown.hardKillRequested",
-	"selective-restart.requested"
-]);
-const hasString = (value, key) => typeof value[key] === "string";
-const isEngineCommand = (value) => {
-	if (typeof value !== "object" || value === null) return false;
-	const record = value;
-	if (typeof record.tag !== "string" || !ENGINE_COMMAND_TAGS.has(record.tag)) return false;
-	switch (record.tag) {
-		case "snapshot.restore":
-		case "snapshot.delete": return hasString(record, "snapshotId");
-		case "advance-clock.requested": return typeof record.toMillis === "number";
-		case "shutdown.hardKillRequested": return (record.signal === "SIGINT" || record.signal === "SIGTERM") && typeof record.exitCode === "number" && typeof record.at === "number";
-		case "selective-restart.requested": return hasString(record, "pluginKey");
-		case "apply.requested": return record.pluginKey === void 0 || typeof record.pluginKey === "string";
-		case "snapshot.capture": return (record.snapshotId === void 0 || typeof record.snapshotId === "string") && (record.name === void 0 || typeof record.name === "string");
-		default: return true;
-	}
-};
-const findCliSupervisorLiveError = (cause) => {
-	for (const reason of cause.reasons) {
-		if (!Cause.isFailReason(reason)) continue;
-		const error = reason.error;
-		if (error instanceof CliSupervisorLiveError) return error;
-		if (typeof error === "object" && error !== null && error._tag === "CliSupervisorLiveError") return error;
-	}
-	return null;
-};
-const resolveConfigPath = (configPath) => {
-	const target = configPath ?? DEFAULT_CONFIG_PATH;
-	const explicit = isAbsolute(target) ? target : resolve(process.cwd(), target);
-	if (existsSync(explicit)) return explicit;
-	if (configPath !== void 0 && configPath !== DEFAULT_CONFIG_PATH) return null;
-	let dir = process.cwd();
-	for (;;) {
-		const candidate = resolve(dir, "devstack.config.ts");
-		if (existsSync(candidate)) return candidate;
-		const parent = resolve(dir, "..");
-		if (parent === dir) return null;
-		dir = parent;
-	}
-};
-const validateStackModule = (resolvedConfigPath, mod) => {
-	const def = mod.default;
-	if (def === null || typeof def !== "object" || def._tag !== "Stack") throw new CliConfigInvalidError({ message: `config at ${resolvedConfigPath} does not default-export a Stack value (got _tag=${String(def?._tag)})` });
-	let stack;
-	try {
-		stack = readStackEngine(def);
-	} catch (cause) {
-		throw new CliConfigInvalidError({ message: `config at ${resolvedConfigPath} default-exported an invalid Stack handle: ${cause instanceof Error ? cause.message : String(cause)}` });
-	}
-	return {
-		stack,
-		resolvedConfigPath
-	};
-};
-const makeConfigLoader = () => ({ load: (configPath) => Effect.gen(function* () {
-	const abs = resolveConfigPath(configPath);
-	if (abs === null) {
-		const attempted = configPath !== void 0 ? resolve(process.cwd(), configPath) : resolve(process.cwd(), DEFAULT_CONFIG_PATH);
-		return yield* Effect.fail(new CliConfigNotFoundError({
-			message: `devstack config not found at ${attempted}`,
-			searchedPaths: [attempted]
-		}));
-	}
-	const url = pathToFileURL(abs).href;
-	const mod = yield* Effect.tryPromise({
-		try: () => import(url),
-		catch: (cause) => new CliConfigInvalidError({
-			message: `failed to import ${abs}: ${cause instanceof Error ? cause.message : String(cause)}`,
-			cause
-		})
-	});
-	return yield* Effect.try({
-		try: () => validateStackModule(abs, mod),
-		catch: (cause) => cause instanceof CliConfigInvalidError ? cause : new CliConfigInvalidError({
-			message: `invalid config at ${abs}`,
-			cause
-		})
-	});
-}) });
 /** Resolve identity from flags + env. App and stack fall through the
-*  shared cwd/package metadata resolver before their defaults. */
+*  shared cwd/package metadata resolver before their defaults.
+*
+*  State-dir precedence ladder:
+*    `--state-dir` flag (`stateDir`) > `config.options.stateDir`
+*    (`configStateDir`) > `$DEVSTACK_STATE_DIR` > `<cwd>/.devstack`.
+*  The flag maps to `resolveStateDir`'s top `runtimeRoot` rung and the
+*  config value to its `stateDir` rung so the flag always wins over a
+*  config-declared `defineDevstack({ stateDir })`.
+*
+*  Stack-name precedence ladder (the SAME flag-beats-config shape as
+*  state-dir, so the two are consistent and reviewable side-by-side):
+*    `--stack` flag / `$DEVSTACK_STACK` (`params.stack`)
+*      > config's `defineDevstack({ stackName })`
+*      > cwd/package inference (default `'main'`).
+*  Config-vs-explicit resolution can't happen here (the config isn't
+*  loaded yet for the no-config verbs), so we record the explicit value
+*  on `ResolvedIdentity.explicitStack` and let the verb wirings apply
+*  `config.stackName` ONLY when no explicit stack was given — see
+*  `effectiveStackName` in `cli/wirings/identity.ts`. `params.stack` is
+*  exactly the explicit `--stack`-or-`$DEVSTACK_STACK` value (the argv
+*  pre-parser seeds it from env, then lets the flag overwrite it), and
+*  is `undefined` when neither was provided. */
 const resolveIdentity = (params) => {
 	const cwd = params.cwd ?? process.cwd();
 	const app = resolveAppName({
 		explicit: params.app,
 		cwd
 	});
-	const runtimeRoot = resolve(params.stateDir ?? process.env.DEVSTACK_STATE_DIR ?? resolve(process.env.HOME ?? process.cwd(), ".devstack"));
+	const runtimeRoot = resolveStateDir({
+		runtimeRoot: params.stateDir,
+		stateDir: params.configStateDir,
+		env: process.env.DEVSTACK_STATE_DIR,
+		cwd
+	});
 	const stacksRoot = resolve(runtimeRoot, "stacks");
+	const explicitStack = params.stack !== void 0 && params.stack.length > 0 ? params.stack : void 0;
 	const stack = resolveStackName({
 		explicit: params.stack,
 		cwd
 	});
-	const network = params.network ?? process.env.DEVSTACK_NETWORK ?? "sui:local";
+	const network = resolveNetworkSync({
+		explicit: params.network,
+		env: process.env.DEVSTACK_NETWORK,
+		explicitSource: "--network"
+	}).raw;
 	const stackRoot = resolve(stacksRoot, stack);
 	return {
 		app,
@@ -152,377 +75,68 @@ const resolveIdentity = (params) => {
 		runtimeRoot,
 		stacksRoot,
 		stackRoot,
-		rosterFile: resolve(stackRoot, "roster.json")
+		rosterFile: resolve(stackRoot, "roster.json"),
+		explicitStack
 	};
 };
-const projectionStatusReader = (identity) => ({ readState: (_app, _stack) => Effect.sync(() => readProjectionSnapshot(identity.stackRoot)) });
-const commandResultFromProcess = () => ({ exitCode: typeof process.exitCode === "number" ? process.exitCode : 0 });
+const projectionStatusReader = (identity) => ({ readState: () => Effect.sync(() => readProjectionSnapshot(identity.stackRoot)) });
 const buildDirectDeps = (identity) => {
-	const loader = makeConfigLoader();
 	return {
 		up: { run: (flags) => runUpLive(flags.configPath, identity, {
 			renderer: flags.renderer,
 			stdoutIsTty: Boolean(process.stdout.isTTY)
-		}).pipe(Effect.map(() => commandResultFromProcess())) },
-		apply: { run: (flags) => runApplyLive(flags.configPath, identity).pipe(Effect.map(() => commandResultFromProcess())) },
+		}) },
+		apply: { run: (flags) => runApplyLive(flags.configPath, identity) },
 		status: { reader: projectionStatusReader(identity) },
-		snapshot: makeDirectSnapshotDeps(identity),
+		snapshot: {
+			reader: makeSnapshotReader(identity),
+			capture: (args) => runSnapshotCaptureLiveAware(identity, args),
+			restore: (snapshotId) => runSnapshotRestoreDirect(identity, snapshotId),
+			delete: (snapshotId) => runSnapshotDeleteDirect(identity, snapshotId),
+			confirm: nodeConfirmPrompt
+		},
 		prune: makeDirectPruneDeps({ runtimeRoot: identity.runtimeRoot }),
 		doctor: { probes: defaultProbes({
 			stateDir: identity.runtimeRoot,
 			appRoot: identity.stacksRoot
 		}) },
-		config: { loader },
+		config: { loader: makeConfigLoader() },
 		wipe: {
 			wipe: () => runWipeDirect(identity),
+			plan: () => runWipePlanDirect(identity),
 			confirm: nodeConfirmPrompt
 		}
 	};
 };
-const makeSnapshotCommandHandler = (params) => {
-	const provideFileSystem = (effect) => effect.pipe(Effect.provideService(FileSystem.FileSystem, params.fs));
-	return (cmd, handlerCtx) => {
-		switch (cmd.tag) {
-			case "snapshot.capture": return provideFileSystem(params.snapshot.capture({
-				id: cmd.snapshotId,
-				label: cmd.name,
-				onProgress: (progress) => handlerCtx.publish({
-					tag: "snapshot.captureProgress",
-					...cmd.snapshotId === void 0 ? {} : { snapshotId: cmd.snapshotId },
-					...cmd.name === void 0 ? {} : { name: cmd.name },
-					phase: progress.phase,
-					...progress.detail === void 0 ? {} : { detail: progress.detail },
-					...progress.pausedContainers === void 0 ? {} : { pausedContainers: progress.pausedContainers },
-					...progress.totalContainers === void 0 ? {} : { totalContainers: progress.totalContainers },
-					at: Date.now()
-				})
-			})).pipe(Effect.map((meta) => [{
-				tag: "snapshot.captured",
-				snapshotId: meta.id,
-				...meta.label === null ? {} : { name: meta.label },
-				at: Date.now()
-			}]));
-			case "snapshot.restore": return provideFileSystem(params.snapshot.restore({ id: cmd.snapshotId })).pipe(Effect.map((meta) => [{
-				tag: "snapshot.restored",
-				snapshotId: meta.id,
-				at: Date.now()
-			}]));
-			case "snapshot.list": return provideFileSystem(params.snapshot.list).pipe(Effect.as([]));
-			case "snapshot.delete": return provideFileSystem(params.snapshot.delete(cmd.snapshotId)).pipe(Effect.as([]));
-			case "wipe.requested": return provideFileSystem(params.snapshot.wipe({})).pipe(Effect.as([]));
-			case "prune.requested": return provideFileSystem(params.snapshot.prune({})).pipe(Effect.as([]));
-			default: return Effect.succeed([]);
-		}
-	};
-};
-const installLiveSupervisorRoster = (params) => Effect.gen(function* () {
-	const paths = rosterPathsFor(params.stackRoot);
-	if (!(yield* claim(paths)).soleHolder) {
-		yield* release(paths).pipe(Effect.catch(() => Effect.void));
-		return yield* Effect.fail(new CliSupervisorLiveError({
-			app: params.app,
-			stack: params.stack,
-			hint: "use `devstack apply` from another shell, or choose a different --stack name"
-		}));
-	}
-	yield* Effect.addFinalizer(() => release(paths).pipe(Effect.catch(() => Effect.void)));
-	yield* Effect.forkScoped(heartbeatFiber(paths));
-});
-const installCommandChannelBridge = (params) => Effect.gen(function* () {
-	const subscriber = yield* makeCommandChannelSubscriber(commandChannelPaths(params.stackRoot), { fromOffset: "current" });
-	yield* Effect.forkScoped(subscriber.commands.pipe(Stream.runForEach((record) => Effect.gen(function* () {
-		if (!isEngineCommand(record.command)) {
-			yield* subscriber.fail(record.id, "invalid command", "command payload did not match EngineCommand").pipe(Effect.catch(() => Effect.void));
-			return;
-		}
-		yield* params.handle.runCommand(record.command).pipe(Effect.andThen(subscriber.ack(record.id)), Effect.catchCause((cause) => subscriber.fail(record.id, "command failed", Cause.pretty(cause)).pipe(Effect.catch(() => Effect.void))));
-	})), Effect.catchCause((cause) => Effect.sync(() => {
-		process.stderr.write(`command channel failed: ${Cause.pretty(cause)}\n`);
-	}))));
-	return { publishEvent: (event) => subscriber.publishEvent(event).pipe(Effect.catch(() => Effect.void)) };
-});
-/**
-* Run `devstack up`. Wires the substrate Layer stack, supervisor,
-* attached renderer, and in-process TUI command queue. The Effect runs
-* as the outer Node fiber so SIGINT reaches scope finalizers.
-*/
-const runUpLive = (configPath, identity, options) => {
-	const loader = makeConfigLoader();
-	return Effect.gen(function* () {
-		const loaded = yield* loader.load(configPath).pipe(Effect.catch((err) => Effect.sync(() => {
-			process.stderr.write(`error: ${err.message}\n`);
-			process.exitCode = err._tag === "CliConfigNotFoundError" ? 66 : 78;
-			return null;
-		})));
-		if (loaded === null) return;
-		const stack = loaded.stack;
-		const identityValue = {
-			app: appName(identity.app),
-			stack: stackName(stack.options.stackName ?? identity.stack),
-			chain: chainId(identity.network)
-		};
-		const appRoot = dirname(loaded.resolvedConfigPath);
-		const rendererMode = resolveUpRendererMode({
-			cliRenderer: options.renderer,
-			stackRenderer: stack.options.renderer,
-			stdoutIsTty: options.stdoutIsTty
-		});
-		const substrateLayers = layerProductionOrchestrators({ codegen: {
-			appRoot,
-			outputDir: stack.options.codegen?.outputDir,
-			stackSubdir: stack.options.codegen?.stackSubdir ?? null
-		} }).pipe(Layer.provideMerge(buildSubstrateLayers(identityValue, identity.runtimeRoot)));
-		yield* Effect.gen(function* () {
-			const state = yield* makeProjectionRef();
-			const snapshotCommandHandler = makeSnapshotCommandHandler({
-				snapshot: yield* SnapshotOrchestratorService,
-				fs: yield* FileSystem.FileSystem
-			});
-			const orchestratorSinks = yield* buildProductionOrchestratorSinks();
-			const postAcquireHook = yield* buildProductionPostAcquireHook({ extras: stack.options.extras });
-			yield* superviseStackEffect({
-				_tag: "Stack",
-				members: stack.members,
-				options: stack.options
-			}, identityValue, state, {
-				orchestratorSinks,
-				commandHandler: snapshotCommandHandler,
-				postAcquireHook,
-				extendContext: extendBuiltInPluginContext,
-				beforeInitialAcquire: (handle) => Effect.gen(function* () {
-					const stackPaths = yield* StackPathsService;
-					const commandChannel = yield* installCommandChannelBridge({
-						stackRoot: stackPaths.stackRoot,
-						handle
-					});
-					yield* installLiveSupervisorRoster({
-						stackRoot: stackPaths.stackRoot,
-						app: String(identityValue.app),
-						stack: String(identityValue.stack)
-					});
-					const rendererEvents = yield* Queue.unbounded();
-					const renderer = makeTuiSurface({
-						mode: rendererMode,
-						publishCommand: makeQueueCommandPublisher(handle.commands)
-					});
-					yield* Effect.addFinalizer(() => renderer.flush.pipe(Effect.catch(() => Effect.void)));
-					yield* Effect.forkScoped(renderer.mount(handle.state, Stream.fromQueue(rendererEvents)).pipe(Effect.catch((cause) => Effect.sync(() => {
-						process.stderr.write(`renderer failed: ${cause.detail ?? String(cause)}\n`);
-					}))));
-					yield* Effect.forkScoped(persistProjectionChanges(stackPaths.stackRoot, handle.state));
-					yield* Effect.forkScoped(Stream.fromQueue(handle.events).pipe(Stream.runForEach((event) => Effect.gen(function* () {
-						yield* Queue.offer(rendererEvents, event);
-						yield* commandChannel.publishEvent(event);
-					}))));
-				})
-			}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));
-		}).pipe(Effect.provide(substrateLayers), Effect.provide(Logger.layer([])), Effect.matchCauseEffect({
-			onFailure: (cause) => Effect.sync(() => {
-				const live = findCliSupervisorLiveError(cause);
-				if (live !== null) {
-					process.stderr.write(`error: supervisor live for ${live.app}/${live.stack}\n`);
-					if (live.hint !== void 0) process.stderr.write(`hint: ${live.hint}\n`);
-					process.exitCode = ExitCode.SUPERVISOR_LIVE;
-					return;
-				}
-				process.stderr.write(`\nerror: stack failed\n${Cause.pretty(cause)}\n`);
-				process.exitCode = 1;
-			}),
-			onSuccess: () => Effect.sync(() => {
-				process.exitCode ??= 0;
-			})
-		}));
-	});
-};
-const runApplyAgainstLiveSupervisor = (identity, identityValue) => Effect.gen(function* () {
-	const stackRoot = stackRootFor(identity.runtimeRoot, String(identityValue.stack));
-	if (!(yield* probeSupervisorPresence(resolve(stackRoot, "roster.json")).pipe(Effect.catch(() => Effect.succeed({
-		live: false,
-		pid: null,
-		hostname: null
-	})))).live) return false;
-	const exit = yield* Effect.exit(Effect.gen(function* () {
-		const publisher = yield* makeCommandChannelPublisher(commandChannelPaths(stackRoot));
-		const published = yield* publisher.publish({ tag: "apply.requested" });
-		const reply = yield* publisher.awaitCompletion(published.id, { timeoutMillis: LIVE_APPLY_ACK_TIMEOUT_MILLIS });
-		if (!reply.ok) return yield* Effect.fail(reply.message);
-	}));
-	if (Exit.isFailure(exit)) {
-		process.stderr.write(`\nerror: live stack apply failed\n${Cause.pretty(exit.cause)}\n`);
-		process.exitCode = 1;
-		return true;
-	}
-	process.exitCode ??= 0;
-	return true;
-});
-const runApplyLive = (configPath, identity) => {
-	const loader = makeConfigLoader();
-	return Effect.gen(function* () {
-		const loaded = yield* loader.load(configPath).pipe(Effect.matchEffect({
-			onFailure: (err) => Effect.gen(function* () {
-				process.stderr.write(`error: ${err.message}\n`);
-				process.exitCode = err._tag === "CliConfigNotFoundError" ? 66 : 78;
-				return yield* Effect.fail("config-load-failed");
-			}),
-			onSuccess: (v) => Effect.succeed(v)
-		}));
-		const stack = loaded.stack;
-		const identityValue = {
-			app: appName(identity.app),
-			stack: stackName(stack.options.stackName ?? identity.stack),
-			chain: chainId(identity.network)
-		};
-		if (yield* runApplyAgainstLiveSupervisor(identity, identityValue)) return;
-		const substrateLayers = layerProductionOrchestrators({ codegen: {
-			appRoot: dirname(loaded.resolvedConfigPath),
-			outputDir: stack.options.codegen?.outputDir,
-			stackSubdir: stack.options.codegen?.stackSubdir ?? null
-		} }).pipe(Layer.provideMerge(buildSubstrateLayers(identityValue, identity.runtimeRoot)));
-		yield* Effect.gen(function* () {
-			const state = yield* makeProjectionRef();
-			const orchestratorSinks = yield* buildProductionOrchestratorSinks();
-			const postAcquireHook = yield* buildProductionPostAcquireHook({ extras: stack.options.extras });
-			yield* superviseStackEffect({
-				_tag: "Stack",
-				members: stack.members,
-				options: stack.options
-			}, identityValue, state, {
-				orchestratorSinks,
-				postAcquireHook,
-				lifetime: "one-shot",
-				extendContext: extendBuiltInPluginContext
-			}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));
-			yield* writeProjectionSnapshot((yield* StackPathsService).stackRoot, yield* SubscriptionRef.get(state));
-		}).pipe(Effect.provide(substrateLayers), Effect.provide(Logger.layer([Logger.consolePretty()])), Effect.matchCauseEffect({
-			onFailure: (cause) => Effect.sync(() => {
-				process.stderr.write(`\nerror: stack apply failed\n${Cause.pretty(cause)}\n`);
-				process.exitCode = 1;
-			}),
-			onSuccess: () => Effect.sync(() => {
-				process.exitCode ??= 0;
-			})
-		}));
-	}).pipe(Effect.catch(() => Effect.void));
-};
-const snapshotIdentityParticipants = (meta) => Object.entries(meta.identity).map(([plugin, value]) => ({
-	plugin,
-	liveIdentity: Effect.succeed({ [plugin]: value })
-}));
-const identityValueFor = (identity, stack) => ({
-	app: appName(identity.app),
-	stack: stackName(stack?.options.stackName ?? identity.stack),
-	chain: chainId(identity.network)
-});
-const directSnapshotLayers = (identity) => layerProductionOrchestrators().pipe(Layer.provideMerge(buildSubstrateLayers(identityValueFor(identity), identity.runtimeRoot)));
-const provideFileSystem = (fs, effect) => effect.pipe(Effect.provideService(FileSystem.FileSystem, fs));
-const ensureNoLiveSupervisor = (identity, hint) => Effect.gen(function* () {
-	if ((yield* probeSupervisorPresence(identity.rosterFile).pipe(Effect.catch(() => Effect.succeed({
-		live: false,
-		pid: null,
-		hostname: null
-	})))).live) return yield* Effect.fail(new CliSupervisorLiveError({
-		app: identity.app,
-		stack: identity.stack,
-		hint
-	}));
-});
-const runSnapshotRestoreDirect = (identity, snapshotId) => {
-	const restored = Effect.gen(function* () {
-		const snapshot = yield* SnapshotOrchestratorService;
-		const fs = yield* FileSystem.FileSystem;
-		const meta = (yield* provideFileSystem(fs, snapshot.list)).find((entry) => entry.id === snapshotId)?.metadata ?? null;
-		const participants = meta === null ? [] : snapshotIdentityParticipants(meta);
-		yield* provideFileSystem(fs, snapshot.restore({
-			id: snapshotId,
-			participants
-		}));
-	}).pipe(Effect.provide(directSnapshotLayers(identity)), Effect.provide(Logger.layer([Logger.consolePretty()])));
-	return ensureNoLiveSupervisor(identity, "shut down the attached `devstack up` session before restoring a snapshot").pipe(Effect.andThen(restored));
-};
-const runSnapshotDeleteDirect = (identity, snapshotId) => {
-	return Effect.gen(function* () {
-		const snapshot = yield* SnapshotOrchestratorService;
-		yield* provideFileSystem(yield* FileSystem.FileSystem, snapshot.delete(snapshotId));
-	}).pipe(Effect.provide(directSnapshotLayers(identity)), Effect.provide(Logger.layer([Logger.consolePretty()])));
-};
-const runSnapshotCaptureDirect = (identity, args) => {
-	const loader = makeConfigLoader();
-	return Effect.gen(function* () {
-		const loaded = yield* loader.load(args.configPath);
-		const stack = loaded.stack;
-		const identityValue = identityValueFor(identity, stack);
-		const substrateLayers = layerProductionOrchestrators({ codegen: {
-			appRoot: dirname(loaded.resolvedConfigPath),
-			outputDir: stack.options.codegen?.outputDir,
-			stackSubdir: stack.options.codegen?.stackSubdir ?? null
-		} }).pipe(Layer.provideMerge(buildSubstrateLayers(identityValue, identity.runtimeRoot)));
-		return yield* Effect.gen(function* () {
-			const state = yield* makeProjectionRef();
-			const snapshot = yield* SnapshotOrchestratorService;
-			const fs = yield* FileSystem.FileSystem;
-			const orchestratorSinks = yield* buildProductionOrchestratorSinks();
-			const postAcquireHook = yield* buildProductionPostAcquireHook({ extras: stack.options.extras });
-			let captureExit = Exit.succeed(void 0);
-			const capturedMeta = { current: null };
-			yield* superviseStackEffect({
-				_tag: "Stack",
-				members: stack.members,
-				options: stack.options
-			}, identityValue, state, {
-				orchestratorSinks,
-				postAcquireHook,
-				lifetime: "one-shot",
-				extendContext: extendBuiltInPluginContext,
-				withinScope: () => provideFileSystem(fs, snapshot.capture({
-					id: args.snapshotId,
-					label: args.name
-				})).pipe(Effect.tap((meta) => Effect.sync(() => {
-					capturedMeta.current = meta;
-				})), Effect.asVoid, Effect.exit, Effect.tap((exit) => Effect.sync(() => {
-					captureExit = exit;
-				})), Effect.asVoid)
-			}).pipe(Effect.provide(layerBuiltInPluginRuntime(orchestratorSinks)));
-			if (Exit.isFailure(captureExit)) yield* Effect.failCause(captureExit.cause);
-			if (capturedMeta.current === null) return yield* Effect.die("snapshot capture completed without metadata");
-			const meta = capturedMeta.current;
-			yield* writeProjectionSnapshot((yield* StackPathsService).stackRoot, yield* SubscriptionRef.get(state));
-			return {
-				snapshotId: meta.id,
-				name: meta.label ?? meta.id
-			};
-		}).pipe(Effect.provide(substrateLayers), Effect.provide(Logger.layer([Logger.consolePretty()])));
-	});
-};
-const makeDirectSnapshotDeps = (identity) => ({
-	reader: makeSnapshotReader(identity),
-	capture: (args) => runSnapshotCaptureDirect(identity, args),
-	restore: (snapshotId) => runSnapshotRestoreDirect(identity, snapshotId),
-	delete: (snapshotId) => runSnapshotDeleteDirect(identity, snapshotId),
-	confirm: nodeConfirmPrompt
-});
-const runWipeDirect = (identity) => Effect.gen(function* () {
-	yield* ensureNoLiveSupervisor(identity, "shut down the attached `devstack up` session first");
-	return yield* Effect.gen(function* () {
-		const snapshot = yield* SnapshotOrchestratorService;
-		yield* provideFileSystem(yield* FileSystem.FileSystem, snapshot.wipe({}));
-		yield* removeRouterDispatchFilesForStack({
-			runtimeRoot: identity.runtimeRoot,
-			app: identity.app,
-			stack: identity.stack
-		});
-	}).pipe(Effect.provide(directSnapshotLayers(identity)), Effect.provide(Logger.layer([Logger.consolePretty()])));
-});
+/** @internal Exported for tests. Resolves identity flag inputs from a
+*  `--app <x>` / `--stack <x>` / `--network <x>` / `--state-dir <x>` /
+*  `--config <x>` argv, falling back to `DEVSTACK_*` env vars. Throws
+*  on a missing or flag-shaped value so a typo doesn't silently demote
+*  a downstream flag, and on a duplicate flag (`--app a --app b`) so
+*  the pre-parser does not silently last-write-wins a value that
+*  Stricli will later reject outright. */
 const identityInputsFromArgv = (argv, env) => {
 	let app = env.DEVSTACK_APP;
 	let stack = env.DEVSTACK_STACK;
 	let network = env.DEVSTACK_NETWORK;
-	let stateDir = env.DEVSTACK_STATE_DIR;
+	let stateDir;
 	let configPath = env.DEVSTACK_CONFIG;
+	const seenArgvFlags = /* @__PURE__ */ new Set();
 	for (let i = 0; i < argv.length; i += 1) {
 		const token = argv[i];
 		const readValue = (name) => {
-			if (token.startsWith(`--${name}=`)) return token.slice(name.length + 3);
-			if (token === `--${name}`) return argv[i + 1];
+			let value;
+			if (token.startsWith(`--${name}=`)) value = token.slice(name.length + 3);
+			else if (token === `--${name}`) {
+				const next = argv[i + 1];
+				if (next === void 0) throw new CliUsageError({ message: `flag --${name} requires a value` });
+				if (next.startsWith("--")) throw new CliUsageError({ message: `flag --${name} requires a value; got "${next}" which looks like a flag` });
+				value = next;
+			}
+			if (value === void 0) return void 0;
+			if (seenArgvFlags.has(name)) throw new CliUsageError({ message: `flag --${name} given more than once` });
+			seenArgvFlags.add(name);
+			return value;
 		};
 		app = readValue("app") ?? app;
 		stack = readValue("stack") ?? stack;
@@ -542,17 +156,89 @@ const identityCwdFromConfig = (configPath) => {
 	const resolved = resolveConfigPath(configPath);
 	return resolved === null ? process.cwd() : dirname(resolved);
 };
+/** Whether the resolved argv is a purely-informational invocation that
+*  never consumes `identity.runtimeRoot` (the only value the config
+*  pre-load feeds). For these we SKIP `configStateDirBestEffort` so we
+*  don't dynamic-import (and run the top-level side effects of) the
+*  user's `devstack.config.ts` — plus walk parent dirs — for commands
+*  the file header itself says must stay cheap:
+*
+*   - empty argv  → Stricli prints root help
+*   - `--help`/`-h` or `--version`/`-v` anywhere → Stricli short-circuits
+*   - first token `schema` → emits the static CLI schema (no state dir)
+*
+*  An unknown verb also never reaches a state-dir consumer (Stricli
+*  fails the parse), but we keep pre-loading on the general path: the
+*  pre-parser already accepted the identity flags, and gating on a
+*  closed verb set here would duplicate the dispatcher's route table.
+*  The two flagged-as-wasteful informational paths (help/version/schema)
+*  are the ones with a registered short-circuit, so skipping exactly
+*  those removes the eager-import surprise without re-deriving routes. */
+const argvSkipsConfigPreload = (argv) => {
+	if (argv.length === 0) return true;
+	for (const token of argv) if (token === "--help" || token === "-h" || token === "--version" || token === "-v") return true;
+	return argv.find((token) => !token.startsWith("-")) === "schema";
+};
+/** Best-effort read of `config.options.stateDir` (the value a program
+*  sets via `defineDevstack({ stateDir })`) for the state-dir precedence
+*  ladder in `resolveIdentity`. Swallows EVERY config-loader failure
+*  (not-found AND evaluation errors) and returns `undefined`:
+*
+*   - No-config verbs (`prune`, `wipe`) MUST keep resolving identity
+*     without a config, so a missing config silently falls through to
+*     the flag > env > cwd ladder.
+*   - A genuinely malformed config is NOT surfaced here — the verbs that
+*     actually consume config (`up` / `apply` via `makeConfigLoader`)
+*     re-load it and surface the typed `CliConfig*` error through the
+*     normal envelope path, so behavior for those verbs is unchanged.
+*
+*  This is one redundant config evaluation for `up` / `apply` (the verb
+*  wiring re-loads via its own loader); threading the loaded value into
+*  the verb dispatch would require touching the off-limits `wirings/up.ts`
+*  signature, so the duplicate import is accepted deliberately. */
+const configStateDirBestEffort = async (configPath) => {
+	const loaded = await Effect.runPromise(makeConfigLoader().load(configPath).pipe(Effect.option));
+	if (loaded._tag === "None") return void 0;
+	const stateDir = loaded.value.stack.options?.stateDir;
+	return stateDir !== void 0 && stateDir.length > 0 ? stateDir : void 0;
+};
 const runCli = async (argv = process.argv.slice(2)) => {
 	const stdinIsTty = Boolean(process.stdin.isTTY);
 	const env = { ...process.env };
-	const identityInputs = identityInputsFromArgv(argv, env);
-	const identity = resolveIdentity({
-		app: identityInputs.app,
-		stack: identityInputs.stack,
-		network: identityInputs.network,
-		stateDir: identityInputs.stateDir,
-		cwd: identityCwdFromConfig(identityInputs.configPath)
-	});
+	let identityInputs;
+	try {
+		identityInputs = identityInputsFromArgv(argv, env);
+	} catch (cause) {
+		const error = cause instanceof CliUsageError ? cause : new CliUsageError({ message: cause instanceof Error ? cause.message : String(cause) });
+		const jsonMode = env[ENV_VARS.JSON] === "1" || argv.includes("--json");
+		await Effect.runPromise(emitFailure(nodeProcessIO, jsonMode ? "json" : "human", {
+			command: "(parse-argv)",
+			elapsedMs: 0,
+			error
+		}));
+		return;
+	}
+	const configStateDir = argvSkipsConfigPreload(argv) ? void 0 : await configStateDirBestEffort(identityInputs.configPath);
+	let identity;
+	try {
+		identity = resolveIdentity({
+			app: identityInputs.app,
+			stack: identityInputs.stack,
+			network: identityInputs.network,
+			stateDir: identityInputs.stateDir,
+			configStateDir,
+			cwd: identityCwdFromConfig(identityInputs.configPath)
+		});
+	} catch (cause) {
+		const error = cause instanceof DevstackNetworkParseError ? new CliUsageError({ message: cause.message }) : cause instanceof CliUsageError ? cause : new CliUsageError({ message: cause instanceof Error ? cause.message : String(cause) });
+		const jsonMode = env[ENV_VARS.JSON] === "1" || argv.includes("--json");
+		await Effect.runPromise(emitFailure(nodeProcessIO, jsonMode ? "json" : "human", {
+			command: "(resolve-identity)",
+			elapsedMs: 0,
+			error
+		}));
+		return;
+	}
 	const deps = buildDirectDeps(identity);
 	await Effect.runPromise(dispatch(deps, {
 		argv,
@@ -576,11 +262,9 @@ const isMainEntrypoint = () => {
 };
 if (isMainEntrypoint()) runCli().catch((err) => {
 	process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
-	process.exitCode = 1;
-}).then(() => {
-	process.exit(process.exitCode ?? 0);
+	process.exitCode = ExitCode.GENERIC;
 });
 //#endregion
-export { runCli };
+export { identityInputsFromArgv, runCli };
 
 //# sourceMappingURL=main.mjs.map