heximon 0.0.1 → 0.1.1

package/dist/bin.mjs

@@ -0,0 +1,2912 @@
+#!/usr/bin/env node
+import { c as RegistryAccess, d as ClackPrompter, f as PromptCancelledError, l as RegistryAccessStatus, n as CreateDefaults, r as createCommand, t as skillsCommand, u as CliEnvironment } from "./skills-command-W72zUEYD.mjs";
+import { createRequire, register } from "node:module";
+import { cancel, confirm, intro, isCancel, log, outro, select, spinner } from "@clack/prompts";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { defineCommand, runMain } from "citty";
+import { basename, dirname, join, relative, resolve } from "pathe";
+import tab from "@bomb.sh/tab/citty";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { CompileMode, DiagnosticCode, DiagnosticRenderMode, DiagnosticRenderer, DiagnosticSeverity, RuntimeSingletons, TerminalStyle, UpgradeBaselineFile } from "@heximon/compiler";
+import { ConfigLoader, LibraryEmitter, ProjectCompiler } from "@heximon/compiler/project";
+import { NodeCompileSeam } from "@heximon/node/compiler";
+import { TransactionCensus, TransactionCensusPolicy } from "@heximon/cqrs/compiler";
+import { BoundaryProvenanceAuditor, BoundaryProvenanceStatus, CredentialSelection, DatabaseConfigDetector, DeployDiagnosticSeverity, DeployLedger, DeployManifestStore, DeployRunner, DeployStrategyUnavailableError, DeployTargetResolver, DeployableServiceReader, DotenvCascade, DrizzleKitRunner, EnvFileReader, EnvFileUnreadableError, HostManagedDeployUnsupportedError, ImportScanner, MigrationInspector, MigrationTargetComposer, PackageCopyAuditor, PeerClosureAuditor, PlatformTracingAuditor, PlatformTracingStatus, WorkspaceConsumerLocator } from "@heximon/deploy";
+import { RouteCensus, RouteScopeGap } from "@heximon/http/compiler";
+import { pathToFileURL } from "node:url";
+//#region src/compile-diagnostics.ts
+/**
+* Renders compile diagnostics to stderr with the same codeframe layout the dev server shows — a box-drawing
+* frame on a TTY, a compact one-liner for CI/editor problem-matchers. Shared by the compile-driven commands.
+*/
+var CompileDiagnostics = class {
+	/** Render `diagnostics` to stderr, displaying each source path relative to `rootDir`. */
+	static renderToStderr(rootDir, diagnostics) {
+		const renderer = new DiagnosticRenderer({
+			mode: process.stderr.isTTY ? DiagnosticRenderMode.Rich : DiagnosticRenderMode.Compact,
+			style: TerminalStyle.forStream(process.stderr),
+			sourceTextFor: (sourceFile) => {
+				try {
+					return readFileSync(sourceFile, "utf8");
+				} catch {
+					return;
+				}
+			},
+			displayPath: (sourceFile) => relative(rootDir, sourceFile) || sourceFile
+		});
+		process.stderr.write(`${renderer.renderAll(diagnostics)}\n`);
+	}
+};
+//#endregion
+//#region src/compile-mode.ts
+/**
+* Resolves whether an inspection command (`check`, `routes`, `graph`) reads a project as an APP or as a
+* published module package, and refuses the two argument combinations no mode can honour.
+*
+* Detection is by package shape ({@link LibraryEmitter.isLibraryPackage}), overridable with `--library` /
+* `--app`. Every command states the outcome in its intro line rather than resolving it silently: a library
+* read as an app reports failures its own `vp pack` never raises, and an app read as a library skips the
+* verdict mirror the whole `pnpm check` chain depends on — neither is discoverable from the output alone.
+*/
+var CompileModeResolver = class {
+	/** The two flags every inspection command declares, so the three verbs never drift apart. */
+	static flags = {
+		library: {
+			type: "boolean",
+			description: "Force the library compile (a published module package), overriding the detected project shape."
+		},
+		app: {
+			type: "boolean",
+			description: "Force the app compile, overriding the detected project shape."
+		}
+	};
+	/**
+	* Resolve one command's compile mode.
+	*
+	* @param commandName - The verb, for the refusal messages (`routes`, `graph`, `check`).
+	* @param rootDir - The absolute project root the shape is detected from.
+	* @param args - The parsed `--library` / `--app` flags.
+	* @param sourceDirectories - The resolved `--src` directories, checked against the library single-root rule.
+	* @returns The resolved mode, or `undefined` when the command must stop — the reason is already on stderr
+	*   and `process.exitCode` is set.
+	*/
+	static resolve(commandName, rootDir, args, sourceDirectories) {
+		if (args.library === true && args.app === true) {
+			process.stderr.write(`heximon ${commandName}: --library and --app are mutually exclusive — pass at most one.\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const forcedMode = args.library === true ? CompileMode.Library : args.app === true ? CompileMode.App : void 0;
+		const mode = forcedMode ?? (LibraryEmitter.isLibraryPackage(rootDir) ? CompileMode.Library : CompileMode.App);
+		if (mode === CompileMode.Library && (sourceDirectories?.length ?? 0) > 1) {
+			process.stderr.write(`heximon ${commandName}: a library compile reads a single source directory, so it cannot honour a multi-directory --src. Pass one directory, or --app to read this project as an application.
+`);
+			process.exitCode = 1;
+			return;
+		}
+		return {
+			mode,
+			forced: forcedMode !== void 0
+		};
+	}
+	/** The mode stamp every command's intro line carries — `library mode`, or `app mode (forced)`. */
+	static stamp(resolved) {
+		return `${resolved.mode} mode${resolved.forced ? " (forced)" : ""}`;
+	}
+};
+//#endregion
+//#region src/project-compile-session.ts
+/**
+* The from-disk compile prologue every inspection command shares (`check`, `graph`, `routes`, `workflows`):
+* resolve the source directories, load the `heximon.config.ts` sidecar for the requested `$env`, derive the
+* platform compile strategy, and merge the plugin set the compile runs with.
+*
+* The `.env` cascade is deliberately NOT loaded here. Only `heximon routes` loads it (so a booted app and its
+* config sidecar read the environment `vp dev` would give them); the compile-only verbs must not pick up a
+* developer's `.env` just by inspecting a project. A caller that wants it loads it before calling
+* {@link open}, so the sidecar read still sees it.
+*/
+var ProjectCompileSession = class ProjectCompileSession {
+	/** The gitignored directory the compile anchors its generated paths at. */
+	static outputDirectoryName = ".heximon";
+	/** The absolute project root the compile runs against. */
+	rootDir;
+	/** The warm compiler — reused by a caller that also prunes or writes type verdicts. */
+	compiler;
+	/** The resolved sidecar, or `undefined` when the project ships none. */
+	config;
+	/** The absolute source directories to scan, or `undefined` for the compiler's own `<rootDir>/src`. */
+	sourceDirectories;
+	/** The absolute `.heximon/` directory the compile anchors its generated paths at. */
+	outputDirectory;
+	/** The compiler plugins the sidecar declares, merged with the platform strategy's own. */
+	plugins;
+	strategy;
+	constructor(options) {
+		this.rootDir = options.rootDir;
+		this.compiler = options.compiler;
+		this.config = options.config;
+		this.sourceDirectories = options.sourceDirectories;
+		this.plugins = options.plugins;
+		this.strategy = options.strategy;
+		this.outputDirectory = join(options.rootDir, ProjectCompileSession.outputDirectoryName);
+	}
+	/**
+	* Resolve one project's compile inputs.
+	*
+	* @param options - The project root, the `$env` name, and the resolved source directories.
+	* @returns The session the caller compiles through.
+	*/
+	static async open(options) {
+		const config = await ConfigLoader.load(options.rootDir, options.environment);
+		const strategy = NodeCompileSeam.resolveStrategy(config?.platform);
+		return new ProjectCompileSession({
+			rootDir: options.rootDir,
+			compiler: new ProjectCompiler(),
+			config,
+			sourceDirectories: options.sourceDirectories,
+			plugins: NodeCompileSeam.mergePlugins(config?.plugins ?? [], strategy),
+			strategy
+		});
+	}
+	/**
+	* Run the app-mode compile.
+	*
+	* @param typeVerdicts - Whether to emit the editor-verdict typegen file (only `heximon check` writes it).
+	* @param options - `verifyBaseline` makes every durable concept also report the records the committed
+	*   `heximon.upgrade.json` never acknowledged. Nothing is written either way.
+	* @returns The compile output, diagnostics included.
+	*/
+	compile(typeVerdicts = false, options = {}) {
+		return this.compiler.compile({
+			rootDir: this.rootDir,
+			outputDirectory: this.outputDirectory,
+			plugins: this.plugins,
+			strategy: this.strategy,
+			...this.sourceDirectories === void 0 ? {} : { sourceDirectories: this.sourceDirectories },
+			...this.config === void 0 ? {} : { config: this.config },
+			...this.config?.root === void 0 ? {} : { apps: { main: this.config.root } },
+			...typeVerdicts ? { typeVerdicts: true } : {},
+			...options.verifyBaseline === true ? { verifyBaseline: true } : {}
+		});
+	}
+	/**
+	* Run the library-mode compile — a published module package goes through the same {@link LibraryEmitter}
+	* its own `vp pack` build uses, rather than being compiled as an app. Not a byte-for-byte replay of that
+	* build: the pack host supplies its own plugin set, wiring mode and `pack.entry`-derived publication set,
+	* while this reads plugins from the config sidecar and falls back to the committed `exports` map.
+	*
+	* Two things make the app-mode compile wrong here, not merely noisy. It enforces every `requires` hop-by-hop
+	* against a host binding, while a library leaves that seam open on purpose (the published factory reads a
+	* required token as a constructor input); and it looks for one root module, while a multi-root package
+	* publishes several. Both surface as errors a `vp pack` of the same source never raises.
+	*
+	* @param options - `pruneVerdicts` also removes a verdict mirror an EARLIER app-mode run wrote. Library
+	*   mode emits none to replace it, so nothing would ever overwrite those app-mode-only errors — only
+	*   `heximon check`, which owns the mirror, asks for it. Every other verb stays write-free.
+	* @returns The compile's diagnostics, files and graph projections; a throwing emit becomes one diagnostic.
+	*/
+	compileLibrary(options = {}) {
+		const sourceDirectory = this.sourceDirectories?.[0] ?? (this.config?.sourceDirectory === void 0 ? void 0 : resolve(this.rootDir, this.config.sourceDirectory));
+		const prunedVerdicts = options.pruneVerdicts === true ? this.compiler.pruneTypeVerdicts({
+			rootDir: this.rootDir,
+			...sourceDirectory === void 0 ? {} : { sourceDirectories: [sourceDirectory] }
+		}) : void 0;
+		try {
+			const emitted = new LibraryEmitter(this.compiler).compile({
+				rootDir: this.rootDir,
+				plugins: this.plugins,
+				...sourceDirectory === void 0 ? {} : { sourceDirectory },
+				...this.config === void 0 ? {} : { config: this.config }
+			});
+			return {
+				diagnostics: emitted.diagnostics,
+				files: emitted.files,
+				moduleGraph: emitted.moduleGraph,
+				boundaryNodes: emitted.boundaryNodes,
+				...prunedVerdicts === void 0 ? {} : { prunedVerdicts }
+			};
+		} catch (error) {
+			return {
+				diagnostics: [{
+					severity: DiagnosticSeverity.Error,
+					message: `The library compile of this package failed: ${error instanceof Error ? error.message : String(error)}`,
+					location: this.rootDir
+				}],
+				files: [],
+				moduleGraph: void 0,
+				boundaryNodes: [],
+				...prunedVerdicts === void 0 ? {} : { prunedVerdicts }
+			};
+		}
+	}
+	/** The `rootDir` + `sourceDirectories` pair the type-verdict write path keys on. */
+	typeVerdictTarget() {
+		return {
+			rootDir: this.rootDir,
+			...this.sourceDirectories === void 0 ? {} : { sourceDirectories: this.sourceDirectories }
+		};
+	}
+};
+//#endregion
+//#region src/source-directories.ts
+/**
+* Resolves which directories the host-agnostic compile commands (`check`, `graph`, `routes`) scan for Heximon
+* source. The compiler's own default is `<rootDir>/src`; a Nitro/Nuxt host instead keeps its modules under
+* `server/` and passes that directory to the compiler from its own build. The standalone CLI is just another
+* host, so it detects that layout and passes `server/` too — otherwise its compile finds no modules.
+*/
+var SourceDirectories = class SourceDirectories {
+	/** Host-framework config basenames whose presence marks a project that roots its modules under `server/`. */
+	static serverHostConfigNames = [
+		"nuxt.config.ts",
+		"nuxt.config.mts",
+		"nuxt.config.js",
+		"nuxt.config.mjs",
+		"nitro.config.ts",
+		"nitro.config.mts",
+		"nitro.config.js",
+		"nitro.config.mjs"
+	];
+	/**
+	* The absolute source directories to scan, or `undefined` to accept the compiler's own `<rootDir>/src`
+	* default. An explicit `--src` (comma-separated) always wins; otherwise, when the project has no `src/` but
+	* is a Nitro/Nuxt host carrying a `server/` directory, that directory is scanned.
+	*
+	* @param rootDir - The absolute project root.
+	* @param sourceOption - The raw `--src` argument, when the caller passed one.
+	* @returns Absolute directories, or `undefined` for the compiler default.
+	*/
+	static resolve(rootDir, sourceOption) {
+		if (sourceOption !== void 0 && sourceOption.trim() !== "") {
+			const directories = sourceOption.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0).map((entry) => resolve(rootDir, entry));
+			if (directories.length > 0) return directories;
+		}
+		if (SourceDirectories.isDirectory(join(rootDir, "src"))) return;
+		if (SourceDirectories.isServerHost(rootDir) && SourceDirectories.isDirectory(join(rootDir, "server"))) return [join(rootDir, "server")];
+	}
+	/** Whether the root carries a Nitro/Nuxt host config, which roots Heximon modules under `server/`. */
+	static isServerHost(rootDir) {
+		return SourceDirectories.serverHostConfigNames.some((name) => existsSync(join(rootDir, name)));
+	}
+	/** Whether `path` exists and is a directory. */
+	static isDirectory(path) {
+		try {
+			return statSync(path).isDirectory();
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+//#region src/transaction-census-report.ts
+/**
+* Renders the compile-time transaction census — which commands are wrapped in a transaction, on which
+* database, and the `app.cqrs.autoTransaction` policy that decided it.
+*
+* The wrap is stated rather than inferred, but a stated policy still does not show what it RESOLVED to: a
+* module that binds nothing for the named token ends up unwrapped anyway. This is that answer, without
+* reading generated wiring or booting the app.
+*/
+var TransactionCensusReport = class TransactionCensusReport {
+	/**
+	* Read the census a compile emitted, or `undefined` when the app declares no command handlers.
+	*
+	* The document's `version` is the producer's own compatibility signal, so it is CHECKED rather than cast
+	* past: a future version could reorder or re-mean a field, and rendering it anyway would print a confident
+	* transaction verdict from data this build does not understand. A shape that does not match reads as no
+	* census — the same silence an app with no commands gets — which is the honest answer here.
+	*/
+	static read(files) {
+		const file = files.find((candidate) => candidate.path === TransactionCensus.fileName);
+		if (file === void 0) return;
+		let parsed;
+		try {
+			parsed = JSON.parse(file.content);
+		} catch {
+			return;
+		}
+		if (typeof parsed !== "object" || parsed === null) return;
+		const document = parsed;
+		if (document.version !== TransactionCensus.version || typeof document.policy !== "string" || !Array.isArray(document.rows)) return;
+		return document;
+	}
+	/**
+	* One summary line, or `undefined` when there is nothing worth saying (no commands at all).
+	*
+	* Reports the unwrapped count too: with the policy unset that number is the size of the migration, and with
+	* a token named it is the set of modules that resolve nothing for it. A composed boundary's commands are
+	* counted alongside the app's own — they dispatch through the same registry and the same policy gates them.
+	*/
+	static summarize(document) {
+		if (document.rows.length === 0) return;
+		const wrapped = document.rows.filter((row) => row.wrapped);
+		const composed = document.rows.filter((row) => row.boundary !== void 0);
+		const policy = TransactionCensusReport.describePolicy(document.policy);
+		const fromPackages = composed.length === 0 ? "" : ` ${String(composed.length)} of them composed from a package.`;
+		return `${String(wrapped.length)}/${String(document.rows.length)} command(s) run in a transaction (${policy}).${fromPackages}`;
+	}
+	/**
+	* The unwrapped commands, one `Command — Module` line each, for the detail under {@link summarize}. A
+	* composed boundary's row names its package instead of a module — the app declares no module for it.
+	*/
+	static unwrapped(document) {
+		return document.rows.filter((row) => !row.wrapped).map((row) => TransactionCensusReport.describeRow(row));
+	}
+	/**
+	* The WRAPPED boundary commands, one line each naming the package and the database its wrap opens on.
+	*
+	* This is the disclosure the summary line cannot make: across a package seam the app's policy GATES the
+	* wrap but does not SELECT its target — the database rides the boundary's own thunk — so an app that named
+	* a concrete `Database` subclass still has these commands wrapped on a connection the package chose, and
+	* an `internal` origin is one nothing in the app can reach.
+	*/
+	static composedWraps(document) {
+		return document.rows.filter((row) => row.wrapped && row.boundary !== void 0).map((row) => `${row.command} — ${String(row.boundary)} → ${row.database ?? "unknown"}${row.origin === void 0 ? "" : ` (${row.origin})`}`);
+	}
+	/** The census header rendered for the summary line — the reserved values named, any other read as a token. */
+	static describePolicy(policy) {
+		if (policy === TransactionCensusPolicy.Unset) return "no app.cqrs.autoTransaction policy";
+		if (policy === TransactionCensusPolicy.Invalid) return "app.cqrs.autoTransaction rejected by the build";
+		if (policy === TransactionCensusPolicy.Off) return "app.cqrs.autoTransaction: false";
+		return `app.cqrs.autoTransaction: ${policy}`;
+	}
+	/** One row as a detail line: the command, attributed to its owning module or its producing package. */
+	static describeRow(row) {
+		const attribution = row.boundary ?? row.module;
+		return `${row.command}${attribution === void 0 ? "" : ` — ${attribution}`}`;
+	}
+};
+//#endregion
+//#region src/upgrade-baseline.ts
+/**
+* The upgrade-safety baseline's command-side helpers. Every one of them is CONCEPT-NEUTRAL: the committed file
+* carries one section per durable concept, so a command that special-cased workflows would leave every other
+* concept's gate half-wired — unacknowledgeable by `--update`, or unarmed with no nudge.
+*/
+var UpgradeBaseline = class UpgradeBaseline {
+	/**
+	* The breaking-verdict codes `--update` acknowledges. Each concept contributes one; a code missing here would
+	* survive its own acknowledgement and fail the command that just rewrote the baseline.
+	*/
+	static breakingCodes = /* @__PURE__ */ new Set([
+		DiagnosticCode.WorkflowUpgradeBreaking,
+		DiagnosticCode.QueueUpgradeBreaking,
+		DiagnosticCode.IntegrationUpgradeBreaking,
+		DiagnosticCode.SagaUpgradeBreaking
+	]);
+	/** Whether a diagnostic is a breaking upgrade verdict that `--update` acknowledges. */
+	static isBreaking(code) {
+		return code !== void 0 && UpgradeBaseline.breakingCodes.has(code);
+	}
+	/** Whether this compile emitted ANY concept's baseline section — i.e. whether the project has a durable surface. */
+	static hasDurableSurface(files) {
+		return files.some((file) => UpgradeBaselineFile.sectionOfGeneratedPath(file.path) !== void 0);
+	}
+	/**
+	* `--update`: recompose the committed baseline from every concept section this compile emitted
+	* (write-if-changed) — the explicit acknowledgement that clears the breaking-change gate. Returns the target +
+	* whether it changed, or `undefined` when the project has no durable surface to baseline.
+	*
+	* Composing rather than copying is what lets a further concept join the file without touching this command:
+	* each plugin emits its own section, and the envelope is assembled here from whatever was emitted.
+	*/
+	static update(rootDir, files) {
+		const sections = /* @__PURE__ */ new Map();
+		for (const file of files) {
+			const section = UpgradeBaselineFile.sectionOfGeneratedPath(file.path);
+			if (section === void 0) continue;
+			try {
+				sections.set(section, JSON.parse(file.content));
+			} catch {
+				continue;
+			}
+		}
+		if (sections.size === 0) return;
+		const content = UpgradeBaselineFile.compose(sections);
+		const target = join(rootDir, UpgradeBaselineFile.fileName);
+		let changed = true;
+		try {
+			changed = readFileSync(target, "utf8") !== content;
+		} catch {
+			changed = true;
+		}
+		if (changed) writeFileSync(target, content);
+		return {
+			target,
+			changed
+		};
+	}
+};
+//#endregion
+//#region src/check-command.ts
+/**
+* `heximon check` — the headless, compile-only gate. In an APP it runs the from-disk Heximon compile with
+* `typeVerdicts: true`, refreshes the editor-verdict mirror (`writeTypeVerdicts` + `healTsconfigInclude` — the
+* same write path the dev server runs), reports the compile diagnostics, and exits non-zero on any error
+* (`--strict` also fails on warnings). Starters wire `"check": "heximon check && vp check"` so `pnpm check`
+* refreshes the DI verdicts *before* tsgo reads them — `vp check`/`tsgo` never run the Heximon compiler, so
+* without this step a stale verdict survives the type-check.
+*
+* Two opt-in passes ride the same compile. `--emit` (and the sidecar's own `debug: true`) writes the generated
+* wiring to `.heximon/` and reformats it in place, so what the compiler produced can be read; a bare run writes
+* only the verdict mirror. `--verify-baseline` makes every durable concept ALSO report the records the
+* committed `heximon.upgrade.json` never acknowledged — the direction the diff does not walk, since adding a
+* record is safe to deploy. It writes nothing, and is refused alongside `--update`, which acknowledges exactly
+* what it exists to show.
+*
+* In a PUBLISHED MODULE PACKAGE it compiles the library the way `vp pack` does instead
+* ({@link ProjectCompileSession.compileLibrary}),
+* because the app-mode compile of a library reports failures its own pack never raises. The mode is detected
+* from the package shape ({@link LibraryEmitter.isLibraryPackage}), overridable with `--library` / `--app`, and
+* always stated in the intro line — a wrongly suppressed verdict mirror in a real app would be worse than the
+* miscompile it fixes, so the resolution is never silent.
+*/
+const checkCommand = defineCommand({
+	meta: {
+		name: "check",
+		description: "Compile the project headlessly, refresh the DI type-verdict mirror, and report compile diagnostics."
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		format: {
+			type: "string",
+			description: "Output format: 'pretty' (default) or 'json'.",
+			default: "pretty"
+		},
+		strict: {
+			type: "boolean",
+			description: "Fail (exit 1) on warnings as well as errors.",
+			default: false
+		},
+		env: {
+			type: "string",
+			description: "The heximon.config.ts `$env` name to resolve (matches `vp dev`).",
+			default: "development"
+		},
+		src: {
+			type: "string",
+			description: "Source directories to scan, comma-separated (a library compile takes a single directory). Defaults to `src/`, or `server/` for a Nitro/Nuxt host."
+		},
+		update: {
+			type: "boolean",
+			description: "Regenerate + write the committed `heximon.upgrade.json` upgrade-safety baseline — the acknowledgement that clears a breaking durable-surface change (drain the in-flight work first).",
+			default: false
+		},
+		library: CompileModeResolver.flags.library,
+		app: CompileModeResolver.flags.app,
+		"verify-baseline": {
+			type: "boolean",
+			description: "Also report every durable record the committed `heximon.upgrade.json` never acknowledged (workflows, saga timeouts, queue channels, integration subscriptions). Writes nothing; pair with --strict to fail on them.",
+			default: false
+		},
+		emit: {
+			type: "boolean",
+			description: "Write the generated wiring to `.heximon/` and prettify it, for inspection. The sidecar's `debug: true` turns this on for every run.",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const rootDir = resolve(process.cwd(), args.cwd);
+		const asJson = args.format === "json";
+		const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+		const resolved = CompileModeResolver.resolve("check", rootDir, args, sourceDirectories);
+		if (resolved === void 0) return;
+		const { mode } = resolved;
+		const verifyBaseline = args["verify-baseline"] === true;
+		if (verifyBaseline && args.update === true) {
+			process.stderr.write("heximon check: --verify-baseline reports what the committed baseline has not acknowledged, and --update acknowledges everything — pass one or the other.\n");
+			process.exitCode = 1;
+			return;
+		}
+		if (!asJson) intro(`heximon check — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
+		const session = await ProjectCompileSession.open({
+			rootDir,
+			environment: args.env,
+			...sourceDirectories === void 0 ? {} : { sourceDirectories }
+		});
+		let checked;
+		if (mode === CompileMode.Library) {
+			const emitted = session.compileLibrary({ pruneVerdicts: true });
+			checked = {
+				diagnostics: emitted.diagnostics,
+				files: emitted.files,
+				...emitted.prunedVerdicts === void 0 ? {} : { prunedVerdicts: emitted.prunedVerdicts }
+			};
+		} else {
+			const output = session.compile(true, { verifyBaseline });
+			session.compiler.writeTypeVerdicts(output);
+			session.compiler.healTsconfigInclude(session.typeVerdictTarget());
+			const emitted = args.emit || session.config?.debug === true;
+			if (emitted) {
+				session.compiler.write(session.outputDirectory, output.files);
+				await session.compiler.formatOnDisk(rootDir, session.outputDirectory, output.files);
+			}
+			checked = {
+				diagnostics: output.diagnostics,
+				files: output.files,
+				...emitted ? { emittedTo: session.outputDirectory } : {}
+			};
+		}
+		const blockingErrors = checked.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error && diagnostic.escalatedFrom === void 0 && !UpgradeBaseline.isBreaking(diagnostic.code)).length;
+		const rebaselined = mode === CompileMode.App && args.update && blockingErrors === 0 ? UpgradeBaseline.update(rootDir, checked.files) : void 0;
+		if (rebaselined?.changed === true && checked.diagnostics.some((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code))) session.compiler.writeTypeVerdicts(session.compile(true, { verifyBaseline }));
+		const diagnostics = rebaselined !== void 0 ? checked.diagnostics.filter((diagnostic) => !UpgradeBaseline.isBreaking(diagnostic.code)) : checked.diagnostics;
+		const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error).length;
+		const warningCount = diagnostics.length - errorCount;
+		const failed = errorCount > 0 || args.strict && warningCount > 0;
+		if (asJson) {
+			const census = TransactionCensusReport.read(checked.files);
+			process.stdout.write(`${JSON.stringify({
+				ok: !failed,
+				mode,
+				errors: errorCount,
+				warnings: warningCount,
+				diagnostics,
+				...census === void 0 ? {} : { transactionCensus: census },
+				...checked.prunedVerdicts === void 0 ? {} : { prunedVerdicts: checked.prunedVerdicts },
+				...checked.emittedTo === void 0 ? {} : { emittedTo: checked.emittedTo },
+				...args.update === true ? { upgradeBaseline: rebaselined === void 0 ? {
+					written: false,
+					blockingErrors
+				} : {
+					written: true,
+					changed: rebaselined.changed,
+					path: rebaselined.target
+				} } : {}
+			})}\n`);
+		} else {
+			if (checked.emittedTo !== void 0) log.info(`Wrote the generated wiring to ${checked.emittedTo}`);
+			if (checked.prunedVerdicts !== void 0) log.info(`Removed the stale DI verdict mirror ${checked.prunedVerdicts} — it was written by an app-mode compile of this package, and a library compile emits none to replace it.`);
+			if (mode === CompileMode.Library && verifyBaseline) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is verified by each app that composes it, so there is nothing here to verify.`);
+			if (mode === CompileMode.Library && args.update === true) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is baselined by each app that composes it, so there is nothing here to update.`);
+			else if (rebaselined !== void 0) log.success(rebaselined.changed ? `Updated ${UpgradeBaselineFile.fileName} — commit it to acknowledge the durable-surface changes.` : `${UpgradeBaselineFile.fileName} already up to date.`);
+			else if (args.update === true && blockingErrors > 0) log.warn(`${UpgradeBaselineFile.fileName} NOT updated — this compile has ${blockingErrors} unrelated error${blockingErrors === 1 ? "" : "s"}, so its durable surface is only partly analyzed and baselining it would acknowledge less than the app really has. Fix those first, then re-run.`);
+			else if (args.update === true) log.info("Nothing durable to baseline — no workflows, queue channels or other durable surface found.");
+			const census = TransactionCensusReport.read(checked.files);
+			const censusSummary = census === void 0 ? void 0 : TransactionCensusReport.summarize(census);
+			if (census !== void 0 && censusSummary !== void 0) {
+				const sections = [censusSummary];
+				const composed = TransactionCensusReport.composedWraps(census);
+				const unwrapped = TransactionCensusReport.unwrapped(census);
+				if (composed.length > 0) sections.push(`Composed, wrapped on the database the package handed over:\n${composed.map((line) => `  ${line}`).join("\n")}`);
+				if (unwrapped.length > 0) sections.push(`Not wrapped:\n${unwrapped.map((line) => `  ${line}`).join("\n")}`);
+				log.info(sections.join("\n"));
+			}
+			if (mode === CompileMode.App && UpgradeBaseline.hasDurableSurface(checked.files) && !existsSync(join(rootDir, UpgradeBaselineFile.fileName))) log.info(`Durable surface found but no committed ${UpgradeBaselineFile.fileName} — run \`heximon check --update\` once and commit it to arm the upgrade-safety gate.`);
+			if (diagnostics.length > 0) CompileDiagnostics.renderToStderr(rootDir, diagnostics);
+			if (failed) {
+				const parts = [`${errorCount} error${errorCount === 1 ? "" : "s"}`];
+				if (warningCount > 0) parts.push(`${warningCount} warning${warningCount === 1 ? "" : "s"}`);
+				outro(`Check failed — ${parts.join(", ")}.`);
+			} else {
+				const closing = mode === CompileMode.Library ? "Library compiled." : "Verdicts refreshed.";
+				if (warningCount > 0) {
+					log.warn(`${warningCount} warning${warningCount === 1 ? "" : "s"} — not failing (pass --strict to fail on warnings too).`);
+					outro(closing);
+				} else outro(`No issues — ${closing.toLowerCase()}`);
+			}
+		}
+		if (failed) process.exitCode = 1;
+	}
+});
+//#endregion
+//#region src/cli-spinner.ts
+/** The animated phase indicator the slow verbs (deploy, provision, migrations) show while they work. */
+var CliSpinner = class {
+	/**
+	* Start a clack spinner with a blank row reserved beneath it, so the animated line never sits flush
+	* against the terminal's bottom edge. clack redraws the spinner line in place — each frame does
+	* `erase.down()` from the spinner line, which clears only downward and leaves blank rows intact — so
+	* writing two newlines (which scroll the viewport up when the terminal is full) then moving the cursor
+	* back up two rows leaves a clear row below the spinner that persists for the run.
+	*
+	* Returns `undefined` when there is no in-place spinner to draw — a non-TTY / CI run, or a run whose
+	* STDOUT is redirected while stdin is still a terminal. The cursor escapes are written to stdout, so
+	* gating on stdin alone would bake them into a captured file; the caller logs each phase as its own line
+	* instead.
+	*
+	* @param interactive - Whether this is an interactive session ({@link CliEnvironment.isInteractive}).
+	* @param label - The first phase message.
+	*/
+	static begin(interactive, label) {
+		if (!interactive || process.stdout.isTTY !== true) return;
+		const active = spinner();
+		process.stdout.write("\n\n\x1B[2A");
+		active.start(label);
+		return active;
+	}
+};
+//#endregion
+//#region src/credential-resolver.ts
+/**
+* The CLI's credential-resolution strategy: **environment variable → interactive prompt → skip**. A value already
+* in the environment is used; otherwise a **required** spec is prompted for in an interactive session (masked for a
+* secret); an optional spec (or any spec in a non-interactive run) is left out of the map. The resolver does
+* **not** decide what is "missing" — it produces the map of what it could resolve, and `@heximon/deploy`'s
+* `DeployRunner` reports any required spec the map fails to cover (so a non-interactive run halts with a clear
+* message rather than hanging on a prompt no one can answer). Optional creds (e.g. a Cloudflare token when
+* `wrangler login` already authenticates) are never prompted, so a logged-in deploy is not interrupted.
+*
+* This whole ladder is CLI-specific. A non-CLI caller (a dashboard) resolves the same `CredentialSpec`s its own way
+* — from a vault / secret store — and hands `DeployRunner` an equivalent map; it never constructs this resolver.
+*/
+var CredentialResolver = class {
+	/**
+	* Resolve the given credential specs into a value map.
+	*
+	* @param specs - The credentials the platform requires.
+	* @param options - Interactivity, the prompter, and the environment source.
+	* @returns The resolved `envVar → value` map (holds secrets — never log it).
+	* @throws PromptCancelledError when the operator cancels an interactive prompt.
+	*/
+	static async resolve(specs, options) {
+		const env = options.env ?? process.env;
+		const values = /* @__PURE__ */ new Map();
+		for (const spec of specs) {
+			const fromEnv = env[spec.envVar];
+			if (fromEnv !== void 0 && fromEnv.length > 0) {
+				values.set(spec.envVar, fromEnv);
+				continue;
+			}
+			if (spec.required && options.interactive && options.prompter !== void 0) {
+				const label = `${spec.name} (${spec.envVar})`;
+				const prompted = spec.secret ? await options.prompter.secret(label) : await options.prompter.text(label);
+				if (prompted.length > 0) values.set(spec.envVar, prompted);
+			}
+		}
+		return values;
+	}
+};
+//#endregion
+//#region src/deploy-command-failure.ts
+/**
+* The failure tail `heximon deploy` and `heximon provision` share: four expected errors that are an
+* actionable halt rather than a bug — a cancelled prompt, an unreadable `--env-file`, a platform whose
+* deploy strategy is not installed, and a host-managed (Nitro/Nuxt) build whose preset has no vendor
+* ship. Anything else is rethrown, because a stack trace is the honest report for a defect.
+*/
+var DeployCommandFailure = class {
+	/**
+	* Report one caught error when it is an expected halt.
+	*
+	* @param error - The error the command's `try` caught.
+	* @returns Whether it was reported (and the exit code set); `false` means the caller must rethrow.
+	*/
+	static report(error) {
+		if (error instanceof PromptCancelledError || error instanceof DeployStrategyUnavailableError || error instanceof EnvFileUnreadableError || error instanceof HostManagedDeployUnsupportedError) {
+			cancel(error instanceof PromptCancelledError ? "Cancelled — nothing changed." : error.message);
+			process.exitCode = 1;
+			return true;
+		}
+		return false;
+	}
+};
+//#endregion
+//#region src/deploy-command.ts
+/**
+* The `heximon deploy` flag cross-checks — a flag whose effect depends on another flag being set.
+*
+* Every one of them runs BEFORE any resolution or side effect, `--destroy` included: a teardown that
+* silently swallowed `--env-file` / `--team` would tell the operator nothing about the flag it ignored.
+*/
+var DeployArgumentGuards = class DeployArgumentGuards {
+	/**
+	* The first flag-coherence failure, or `undefined` when the combination is usable.
+	*
+	* @param args - The parsed deploy flags.
+	* @returns The operator-facing message, ready to `cancel`.
+	*/
+	static incoherence(args) {
+		if (args["env-file"] !== void 0 && !args.provision && !args.migrate) return "--env-file needs --provision (to push secrets) or --migrate (to supply the migration connection env).";
+		if (args.team !== void 0 && args.create === void 0) return "--team needs --create <name> (it scopes the target bootstrap).";
+		if (args.destroy) {
+			const shipOnly = DeployArgumentGuards.shipOnlyFlags(args);
+			if (shipOnly.length > 0) return `--destroy removes the deployed app, so ${shipOnly.join(", ")} would do nothing — drop them, or drop --destroy.`;
+		}
+	}
+	/**
+	* The `--profile` / platform mismatch message, or `undefined`. `--profile` names a wrangler auth profile,
+	* so any other platform would ship with an ambient login the operator did not select.
+	*/
+	static profileMismatch(profile, platformName) {
+		if (profile === void 0 || platformName === "cloudflare") return;
+		return `--profile selects a wrangler auth profile, which only the cloudflare platform supports — the resolved platform is ${platformName ?? "node (default)"}.`;
+	}
+	/** The ship-shaping flags this run passed, by name — every one of them inert under `--destroy`. */
+	static shipOnlyFlags(args) {
+		const named = [];
+		if (args["env-file"] !== void 0) named.push("--env-file");
+		if (args.create !== void 0) named.push("--create");
+		if (args.migrate) named.push("--migrate");
+		if (args.migrations !== void 0) named.push("--migrations");
+		if (args.provision) named.push("--provision");
+		if (args.team !== void 0) named.push("--team");
+		if (args.verify) named.push("--verify");
+		return named;
+	}
+};
+/**
+* The `heximon deploy` outcome tail: everything the run reports AFTER `DeployRunner` returns — the
+* diagnostics, the migration applies, the target bootstrap, the provision phase, the missing credentials,
+* the ship result, and the post-ship liveness probe.
+*
+* Exported for the command's own tests: a partial-completion outcome is reached only through a real vendor
+* failure, which a local test cannot stage.
+*/
+var DeployReport = class DeployReport {
+	/**
+	* Print the whole outcome and decide the command's exit.
+	*
+	* @param outcome - What the runner reported.
+	* @param interactive - Whether a prompt could have run (shapes the missing-credential hint).
+	* @returns Whether the run succeeded; `false` means the caller sets a non-zero exit code.
+	*/
+	static render(outcome, interactive) {
+		DeployReport.logDiagnostics(outcome.diagnostics);
+		DeployReport.logMigrations(outcome);
+		DeployReport.logTargetEnsure(outcome);
+		DeployReport.logProvision(outcome);
+		DeployReport.logMissingCredentials(outcome, interactive);
+		if (outcome.result?.failed === true) {
+			for (const message of outcome.result.messages) log.message(message);
+			cancel(`The ship to ${outcome.result.platform} failed — see above.`);
+			return false;
+		}
+		if (outcome.halted || outcome.result === void 0) {
+			const completed = DeployReport.completedBeforeHalt(outcome);
+			cancel(completed.length === 0 ? "Halted before ship — nothing changed." : `Halted before ship — nothing was uploaded, but earlier work already completed and was NOT rolled back: ${completed.join("; ")}.`);
+			return false;
+		}
+		for (const message of outcome.result.messages) log.message(message);
+		if (!DeployReport.logVerification(outcome)) return false;
+		if (DeployReport.hasFailedMigration(outcome)) {
+			cancel(`Deployed to ${outcome.result.platform}, but a migration failed to apply — see above.`);
+			return false;
+		}
+		outro(outcome.result.shipped ? `Deployed to ${outcome.result.platform}.` : `No vendor upload step for ${outcome.result.platform} — see above.`);
+		return true;
+	}
+	/**
+	* The work a halted run already finished: the created target, the provisioned resources, and the
+	* migrations that applied. Empty when the run stopped before any of it.
+	*/
+	static completedBeforeHalt(outcome) {
+		const completed = [];
+		if (outcome.targetEnsure !== void 0 && outcome.targetEnsure.created.length > 0) completed.push(`target bootstrap (${outcome.targetEnsure.created.join(", ")})`);
+		if (outcome.provision !== void 0 && outcome.provision.created.length > 0) completed.push(`provisioned resources (${outcome.provision.created.join(", ")})`);
+		const applied = (outcome.migrations ?? []).filter((migration) => migration.applied.length > 0);
+		if (applied.length > 0) completed.push(`applied migrations (${applied.map((migration) => `${migration.target}: ${migration.applied.join(", ")}`).join(" · ")})`);
+		return completed;
+	}
+	/** Whether any migration outcome carries an apply-time error. */
+	static hasFailedMigration(outcome) {
+		return (outcome.migrations ?? []).some((migrated) => migrated.diagnostics.some((diagnostic) => diagnostic.severity === DeployDiagnosticSeverity.Error));
+	}
+	/** The runner's own findings, at the severity each carries. */
+	static logDiagnostics(diagnostics) {
+		for (const diagnostic of diagnostics ?? []) if (diagnostic.severity === DeployDiagnosticSeverity.Error) log.error(diagnostic.message);
+		else log.warn(diagnostic.message);
+	}
+	/**
+	* Which databases the tool migrated, and in which phase. drizzle-kit reports no per-migration ids, so a
+	* per-database success line is the honest signal; a runner that DOES report ids (a probed
+	* `MigrationRunner`) gets them appended.
+	*/
+	static logMigrations(outcome) {
+		for (const migrated of outcome.migrations ?? []) if (!migrated.diagnostics.some((diagnostic) => diagnostic.severity === DeployDiagnosticSeverity.Error)) {
+			const ids = migrated.applied.length > 0 ? `: ${migrated.applied.join(", ")}` : "";
+			log.success(`Database migrations applied [${migrated.phase}] — ${migrated.target}${ids}.`);
+		}
+	}
+	/** The target bootstrap (`--create`): the project/site + local link the tool ensured before the build. */
+	static logTargetEnsure(outcome) {
+		if (outcome.targetEnsure === void 0) return;
+		for (const message of outcome.targetEnsure.messages) log.message(message);
+		if (outcome.targetEnsure.created.length > 0) log.success(`Target bootstrap: ${outcome.targetEnsure.created.join(", ")}.`);
+		if (outcome.targetEnsure.existing.length > 0) log.info(`Target already present: ${outcome.targetEnsure.existing.join(", ")}.`);
+		if (outcome.targetEnsure.failed.length > 0) log.error(`Target bootstrap failed: ${outcome.targetEnsure.failed.join(", ")}.`);
+	}
+	/** The provision phase (`--provision`): what the tool created / found / failed before the ship. */
+	static logProvision(outcome) {
+		if (outcome.provision === void 0) return;
+		for (const message of outcome.provision.messages) log.message(message);
+		if (outcome.provision.created.length > 0) log.success(`Provisioned: ${outcome.provision.created.join(", ")}.`);
+		if (outcome.provision.existing.length > 0) log.info(`Already present: ${outcome.provision.existing.join(", ")}.`);
+		if (outcome.provision.failed.length > 0) log.error(`Failed to provision: ${outcome.provision.failed.join(", ")}.`);
+	}
+	/** A real ship halts on a missing credential (error); a dry run only previews it (would-need). */
+	static logMissingCredentials(outcome, interactive) {
+		for (const credential of outcome.missingCredentials) {
+			const hint = `set ${credential.envVar}${interactive ? "" : " (no TTY to prompt)"}`;
+			if (outcome.halted) log.error(`Missing ${credential.name} — ${hint}.`);
+			else log.warn(`Would need ${credential.name} — ${hint}.`);
+		}
+	}
+	/**
+	* The post-ship liveness probe (`--verify`): the artifact uploaded, but did the app come up?
+	*
+	* @returns Whether the app answered (or no probe ran); `false` is shipped-but-dead.
+	*/
+	static logVerification(outcome) {
+		if (outcome.verification === void 0) return true;
+		for (const diagnostic of outcome.verification.diagnostics) if (diagnostic.severity === DeployDiagnosticSeverity.Error) log.error(diagnostic.message);
+		else log.warn(diagnostic.message);
+		if (outcome.verification.live) {
+			log.success(`Liveness OK — ${outcome.verification.url} returned 2xx.`);
+			return true;
+		}
+		cancel(`Deployed to ${outcome.result?.platform ?? "the platform"}, but the app is not responding — see above.`);
+		return false;
+	}
+};
+/** The `--destroy` teardown and the pre-ship discovery/migration composition the ship path runs. */
+var DeployPhases = class {
+	/**
+	* Confirm and run the teardown.
+	*
+	* @returns Whether the command should exit non-zero.
+	*/
+	static async destroy(args, target, rootDir, credentials, interactive) {
+		const platformName = target.platformName ?? "node";
+		if (interactive) {
+			const answer = await confirm({
+				message: `Remove the deployed app on ${platformName} (env: ${args.env})? This cannot be undone.`,
+				initialValue: false
+			});
+			if (isCancel(answer)) {
+				cancel("Cancelled — nothing removed.");
+				return true;
+			}
+			if (!answer) {
+				cancel("Aborted — nothing removed.");
+				return false;
+			}
+		} else if (!args.yes) {
+			cancel("Refusing to --destroy non-interactively without --yes.");
+			return true;
+		}
+		const removing = CliSpinner.begin(interactive, `Removing the deployed app on ${platformName} (${args.env})…`);
+		let teardown;
+		try {
+			teardown = await DeployRunner.destroy({
+				target,
+				rootDir,
+				environment: args.env,
+				credentials,
+				dryRun: args["dry-run"],
+				...args.profile === void 0 ? {} : { profile: args.profile }
+			});
+		} catch (teardownError) {
+			removing?.stop("Teardown failed — see the error below.");
+			throw teardownError;
+		}
+		removing?.stop(args["dry-run"] ? "Dry run — nothing removed." : "Teardown step complete.");
+		if (teardown.unsupported) {
+			cancel(`Platform ${teardown.platformName ?? "node (default)"} has nothing to remove (no destroy step).`);
+			return true;
+		}
+		for (const message of teardown.result?.messages ?? []) log.message(message);
+		outro(teardown.result?.destroyed === true ? `Removed from ${teardown.result.platform}.` : `Dry run — nothing removed (${teardown.result?.platform ?? target.platformName ?? "node"}).`);
+		return false;
+	}
+	/**
+	* Harvest the deploy metadata each vendor class co-locates on its `DeployableService` marker — what to
+	* configure/provision, with no central registry to maintain. The primary path reads the ACTUAL provider
+	* graph (a plugin-less compile surfaces every provider's cross-package ancestry), so it catches a marker
+	* the app never names in its own source — e.g. one bound inside a composed library boundary. It falls back
+	* to the whole-source import scan when the compile cannot run, and writes a `deploy.manifest.json` build
+	* artifact. Purely informational.
+	*/
+	static async harvest(rootDir) {
+		try {
+			const harvested = await DeployableServiceReader.harvestProject(rootDir);
+			DeployManifestStore.write(resolve(rootDir, ".heximon"), harvested);
+			return harvested;
+		} catch (harvestError) {
+			log.warn(`Reading the provider graph for deploy metadata failed, falling back to the import scan (a marker bound only inside a composed boundary may go unreported): ${harvestError instanceof Error ? harvestError.message : String(harvestError)}`);
+			const scanned = await ImportScanner.scan(rootDir);
+			return DeployableServiceReader.fromProjectRoot(rootDir).harvest(scanned);
+		}
+	}
+	/** Report the harvested external services and, under `--migrate`, each harvested migration recipe. */
+	static logHarvest(harvested, migrate) {
+		const services = harvested.filter((entry) => (entry.meta.requiredInputs?.length ?? 0) > 0);
+		if (services.length > 0) {
+			log.info(`Detected ${services.length} external service(s) from your imports:`);
+			for (const service of services) {
+				const needs = (service.meta.requiredInputs ?? []).map((input) => `${input.name}${process.env[input.name] === void 0 ? " (not set here)" : ""}`).join(", ");
+				const label = service.meta.resource ? `${service.meta.resource.vendor} (${service.meta.resource.kind})` : service.forSatisfier;
+				log.message(`· ${label} — needs ${needs}`);
+			}
+			log.message("Ensure each is configured in your platform's secret store before deploying.");
+		}
+		if (!migrate) return;
+		for (const entry of harvested) if (entry.meta.migration !== void 0) {
+			const recipe = entry.meta.migration.guidance ?? entry.meta.migration.mode;
+			log.info(`Migration recipe (${entry.forSatisfier.split("#")[0]}): ${recipe}`);
+		}
+	}
+	/**
+	* Compose the run's migration targets: `--migrate` applies every auto-detected database via its local
+	* drizzle-kit, sequenced around the ship; a bare `--migrations <dir>` stays the read-only report over that
+	* directory. The deploy deliberately does NOT load the app's dev `.env` cascade — a dev `DATABASE_URL`
+	* would silently migrate the dev database during a production deploy. The drizzle-kit child inherits this
+	* process's env overlaid by the `--env-file` entries (the operator's curated env for THIS deploy beats a
+	* lingering dev shell export).
+	*
+	* @returns The composed migrations, or `null` when `--migrate` found no config to apply (a halt).
+	*/
+	static async composeMigrations(args, rootDir, secrets) {
+		if (!args.migrate) {
+			if (args.migrations === void 0) return;
+			const migrationsDir = resolve(rootDir, args.migrations);
+			return { targets: [{
+				name: basename(migrationsDir),
+				migrationsDirectory: migrationsDir
+			}] };
+		}
+		const detection = await DatabaseConfigDetector.detect(rootDir);
+		const migrateEnv = secrets === void 0 ? void 0 : Object.fromEntries(secrets);
+		const composed = MigrationTargetComposer.fromDetectedConfigs(detection.configs, {
+			rootDir,
+			...migrateEnv === void 0 ? {} : { env: migrateEnv }
+		});
+		for (const note of composed.notes) log.info(note);
+		let migrations;
+		if (composed.targets.length > 0) {
+			log.info(`Applying migrations for ${composed.targets.length} database(s): ${composed.targets.map((migrationTarget) => migrationTarget.name).join(", ")}.`);
+			migrations = {
+				targets: composed.targets,
+				apply: true,
+				allowDestructive: args["allow-destructive"]
+			};
+		} else if (composed.notes.length > 0) log.warn("--migrate will apply 0 databases this run — every detected database config is applied by its own mechanism (see the notes above). Nothing is migrated by this deploy.");
+		else {
+			cancel("--migrate found no database config to apply — expected a `*.config.ts` that `export default`s a Drizzle config (see `heximon migrations status`), or apply migrations manually before deploying.");
+			return null;
+		}
+		if (args.migrations !== void 0) log.info("--migrations <dir> is superseded by the auto-detected database config(s) under --migrate.");
+		return migrations;
+	}
+};
+/**
+* `heximon deploy` — resolve the deploy target from `heximon.config.ts` (or the host-managed Nitro/Nuxt
+* build), resolve the platform's credentials, then hand the run to `@heximon/deploy`'s `DeployRunner`, which
+* validates, builds and ships. The command owns the operator conversation — the flag guards, the prompts,
+* the progress surface and the exit code — and never reimplements a vendor's upload.
+*/
+const deployCommand = defineCommand({
+	meta: {
+		name: "deploy",
+		description: "Build-and-ship a Heximon app to its configured platform (resolve, validate, ship the artifact)."
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		env: {
+			type: "string",
+			description: "Deploy environment (production / staging / preview:<id>).",
+			default: "production"
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Build + report the ship command, but do not ship.",
+			default: false
+		},
+		"skip-build": {
+			type: "boolean",
+			description: "Ship the existing build output without running `vp build` first.",
+			default: false
+		},
+		provision: {
+			type: "boolean",
+			description: "Before the ship, create the resources the vendor CLI does not auto-create (e.g. Cloudflare Queues) and push --env-file secrets to the platform's secret store.",
+			default: false
+		},
+		"env-file": {
+			type: "string",
+			description: "A dotenv file of the app's runtime secrets: pushed to the platform's native secret store during --provision, and/or supplied to the drizzle-kit child during --migrate (values ride stdin / a private temp file / the child env, never argv)."
+		},
+		create: {
+			type: "string",
+			description: "Create the vendor-side project/site under this NAME (Vercel/Netlify) and link this directory to it, before shipping — the one-time fresh-account bootstrap. Idempotent: an existing target is linked, never re-created."
+		},
+		team: {
+			type: "string",
+			description: "The team scope (Vercel team slug / Netlify account slug) to create the --create target under, for multi-team accounts."
+		},
+		verify: {
+			type: "boolean",
+			description: "After a real ship, GET the deployed URL and assert a 2xx (post-deploy liveness probe).",
+			default: false
+		},
+		migrations: {
+			type: "string",
+			description: "The app's migrations directory — reports on pending migrations (--migrate applies via the auto-detected database config(s) instead)."
+		},
+		migrate: {
+			type: "boolean",
+			description: "Apply pending migrations via the app's local drizzle-kit against every auto-detected database config — before the ship (pass --allow-destructive to apply after it instead). Supply the connection env via the shell or --env-file.",
+			default: false
+		},
+		"allow-destructive": {
+			type: "boolean",
+			description: "Acknowledge that --migrate's pending batch may be destructive (drop/narrow) — a database whose migrations the scan flags as destructive then applies after the ship. Forward-only; no DB rollback.",
+			default: false
+		},
+		platform: {
+			type: "string",
+			description: "Override the deploy platform (e.g. cloudflare) when heximon.config.ts does not declare it."
+		},
+		profile: {
+			type: "string",
+			description: "Deploy as a named wrangler auth profile (Cloudflare only; wrangler >= 4.106 — see `wrangler auth`). Appended to every wrangler call this run; a directory-bound profile needs no flag, and CLOUDFLARE_API_TOKEN still takes precedence."
+		},
+		destroy: {
+			type: "boolean",
+			description: "Remove the deployed app from its platform instead of shipping (destructive).",
+			default: false
+		},
+		yes: {
+			type: "boolean",
+			description: "Skip the --destroy confirmation prompt (required to --destroy non-interactively).",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const deployArgs = args;
+		const rootDir = resolve(process.cwd(), deployArgs.cwd);
+		const environment = deployArgs.env;
+		const interactive = CliEnvironment.isInteractive();
+		intro(`heximon deploy · ${environment}`);
+		const incoherence = DeployArgumentGuards.incoherence(deployArgs);
+		if (incoherence !== void 0) {
+			cancel(incoherence);
+			process.exitCode = 1;
+			return;
+		}
+		try {
+			const target = await DeployTargetResolver.resolve(rootDir, environment, deployArgs.platform);
+			log.info(`Platform: ${target.platformName ?? "node (default)"} · target class: ${target.targetClass}`);
+			if (target.hostManaged) log.info(`Host-managed build detected (${target.artifactDir}) — shipping it, skipping \`vp build\`.`);
+			const profileMismatch = DeployArgumentGuards.profileMismatch(deployArgs.profile, target.platformName);
+			if (profileMismatch !== void 0) {
+				cancel(profileMismatch);
+				process.exitCode = 1;
+				return;
+			}
+			const specs = CredentialSelection.inPlay(target.strategy.requiredCredentials(), { provisioning: deployArgs.provision });
+			const credentials = await CredentialResolver.resolve(specs, {
+				interactive,
+				prompter: interactive ? new ClackPrompter() : void 0
+			});
+			if (credentials.size > 0) log.success(`Resolved ${credentials.size} credential(s).`);
+			if (deployArgs.destroy) {
+				if (await DeployPhases.destroy(deployArgs, target, rootDir, credentials, interactive)) process.exitCode = 1;
+				return;
+			}
+			let secrets;
+			if (deployArgs["env-file"] !== void 0) {
+				secrets = await EnvFileReader.read(resolve(rootDir, deployArgs["env-file"]));
+				log.info(`Loaded ${secrets.size} secret(s) from ${deployArgs["env-file"]}.`);
+			}
+			if (!(deployArgs["skip-build"] || target.hostManaged === true)) {
+				const injectable = DeployLedger.injectableEntries(await DeployLedger.read(rootDir, environment));
+				if (injectable.size > 0) log.info(`Injecting ${injectable.size} deploy-ledger value(s) into the build: ${[...injectable.keys()].join(", ")}.`);
+			}
+			DeployPhases.logHarvest(await DeployPhases.harvest(rootDir), deployArgs.migrate);
+			const migrations = await DeployPhases.composeMigrations(deployArgs, rootDir, secrets);
+			if (migrations === null) {
+				process.exitCode = 1;
+				return;
+			}
+			const progress = CliSpinner.begin(interactive, "Preparing the deploy…");
+			const onProgress = (event) => {
+				if (progress === void 0) log.info(event.message);
+				else progress.message(event.message);
+			};
+			let outcome;
+			try {
+				outcome = await DeployRunner.run({
+					target,
+					rootDir,
+					environment,
+					credentials,
+					dryRun: deployArgs["dry-run"],
+					skipBuild: deployArgs["skip-build"] || target.hostManaged === true,
+					...target.artifactDir === void 0 ? {} : { artifactDir: target.artifactDir },
+					provision: deployArgs.provision,
+					...secrets === void 0 ? {} : { secrets },
+					...deployArgs.create === void 0 ? {} : { createTarget: {
+						name: deployArgs.create,
+						...deployArgs.team === void 0 ? {} : { team: deployArgs.team }
+					} },
+					verify: deployArgs.verify,
+					...deployArgs.profile === void 0 ? {} : { profile: deployArgs.profile },
+					onProgress,
+					...migrations === void 0 ? {} : { migrations }
+				});
+			} catch (runError) {
+				progress?.stop("Deploy failed — see the error below.");
+				throw runError;
+			}
+			progress?.stop(outcome.halted ? "Stopped — details below." : "Deploy steps complete.");
+			if (!DeployReport.render(outcome, interactive)) process.exitCode = 1;
+		} catch (error) {
+			if (DeployCommandFailure.report(error)) return;
+			throw error;
+		}
+	}
+});
+//#endregion
+//#region src/doctor-command.ts
+/** The rendering layer behind {@link doctorCommand}: every audit's output, and the verdicts the exit reads. */
+var DoctorReport = class DoctorReport {
+	/** Renders one audited boundary as a status line. `self` reframes the wording for the current package. */
+	static boundaryLine(report, self = false) {
+		const name = self ? `${report.specifier} (this package)` : report.specifier;
+		const version = report.packageVersion === void 0 ? "" : ` v${report.packageVersion}`;
+		switch (report.status) {
+			case BoundaryProvenanceStatus.Fresh: return self ? `✔ ${name}${version} — dist is current with src/ (${report.manifestSourceHash})` : `✔ ${name}${version} — up to date (${report.manifestSourceHash})`;
+			case BoundaryProvenanceStatus.Stale: return self ? `✖ ${name}${version} — STALE: your src/ (${report.recomputedSourceHash}) no longer matches your own dist manifest (${report.manifestSourceHash}). Repack (\`vp pack\`) before publishing or consuming it.` : `✖ ${name}${version} — STALE: its src/ (${report.recomputedSourceHash}) no longer matches the packed manifest (${report.manifestSourceHash}). Rebuild it (\`vp pack\` in ${report.packageDirectory}) before trusting this app's build.`;
+			case BoundaryProvenanceStatus.NoProvenance: return `● ${name}${version} — manifest predates the provenance stamp; repack to enable the check.`;
+			case BoundaryProvenanceStatus.NoSource: return `● ${name}${version} — published package (no local src/); provenance is display-only.`;
+		}
+	}
+	/** Logs one report at the severity its status warrants (error for stale, success for fresh, info otherwise). */
+	static logBoundary(report, self = false) {
+		const line = DoctorReport.boundaryLine(report, self);
+		if (report.status === BoundaryProvenanceStatus.Stale) log.error(line);
+		else if (report.status === BoundaryProvenanceStatus.Fresh) log.success(line);
+		else log.info(line);
+	}
+	/**
+	* The `--self` outro sentence for a NON-stale own-dist verdict.
+	*
+	* Only {@link BoundaryProvenanceStatus.Fresh} actually compared anything. The other two verdicts mean the
+	* comparison did not run at all, and summarising them as "dist is current with its src/" would report a
+	* check that never happened as a pass — the one thing a pre-publish gate must never do.
+	*/
+	static selfProvenanceSummary(report) {
+		switch (report.status) {
+			case BoundaryProvenanceStatus.Fresh: return "This package's dist is current with its src/.";
+			case BoundaryProvenanceStatus.NoProvenance: return "Its packed manifest predates the provenance stamp, so nothing was compared — repack (`vp pack`) to enable the staleness check.";
+			case BoundaryProvenanceStatus.NoSource: return "It ships no local src/, so its packed manifest was not compared with anything.";
+			case BoundaryProvenanceStatus.Stale: return "Your dist is STALE — repack (`vp pack`) before publishing or consuming this package.";
+		}
+	}
+	/**
+	* Logs the physical-copy census: a line per forked package naming every copy and who resolves to it, or one
+	* summary line when nothing forked. The summary always states how many origins were probed — an audit that
+	* could not look at anything must not read as a clean bill of health. `gatingPackages`, when given, scopes
+	* which forks count as GATING ({@link DoctorReport.runtimeReachablePackageNames}) — every fork is still
+	* printed above either way, and a fork outside the set gets one extra line noting it is reported, not gated.
+	*
+	* @returns Whether any GATING fork was found (any fork at all, when `gatingPackages` is omitted).
+	*/
+	static logCopyAudit(audit, gatingPackages) {
+		const forked = audit.reports.filter((report) => report.copies.length > 1);
+		if (audit.originsProbed === 0) {
+			log.warn("Package copies — nothing probed (no resolvable node_modules from this directory), so no fork check ran.");
+			return false;
+		}
+		if (forked.length === 0) {
+			log.success(`Package copies — ${String(audit.packagesProbed)} package(s) probed from ${String(audit.originsProbed)} origin(s); each resolves to a single copy.`);
+			return false;
+		}
+		for (const report of forked) {
+			const copies = report.copies.map((copy) => {
+				return `      ${copy.version === void 0 ? "" : `v${copy.version} `}${copy.directory}\n        ← ${copy.origins.join(", ")}`;
+			}).join("\n");
+			log.error(`${report.packageName} — ${String(report.copies.length)} physical copies:\n${copies}\n    Class identity is the DI token, so these bind nominally yet split at runtime. Deduplicate to one copy (align versions, or hoist it).`);
+		}
+		const gatingForks = gatingPackages === void 0 ? forked : forked.filter((report) => gatingPackages.has(report.packageName));
+		if (gatingPackages !== void 0 && gatingForks.length === 0) {
+			log.info(`${String(forked.length)} forked package(s) across ${String(audit.originsProbed)} origin(s) sit outside this package's runtime closure (build-time tooling) — reported, not gated.`);
+			return false;
+		}
+		if (gatingPackages === void 0) {
+			log.info(`${String(forked.length)} forked package(s) across ${String(audit.originsProbed)} origin(s). Reported, not gated — this does not fail the command.`);
+			return true;
+		}
+		log.info(`${String(forked.length)} forked package(s) across ${String(audit.originsProbed)} origin(s), ${String(gatingForks.length)} within this package's runtime closure — reported, and gating this command's exit code.`);
+		return true;
+	}
+	/**
+	* Logs the `@heximon/*` peer-pivot roster ({@link PeerClosureAuditor}): an info line for pivots acknowledged
+	* as expected-open, a warn for stale acknowledgements, a warn block naming every remaining undeclared pivot,
+	* a success line when nothing is left open, or nothing when the roster is empty or the manifest could not be
+	* read. Advisory only — never sets the exit code, since covering a pivot unilaterally can flip a fork's
+	* direction rather than remove it.
+	*/
+	static logPeerClosureRoster(report) {
+		if (report === null || report.pivots.length === 0) return;
+		if (report.expectedOpen.length > 0) {
+			const names = report.expectedOpen.map((pivot) => pivot.packageName).join(", ");
+			log.info(`Peer closure — ${String(report.expectedOpen.length)} pivot(s) expected to stay open (acknowledged in expectedOpenPeers): ${names}.`);
+		}
+		if (report.staleExpectedOpen.length > 0) log.warn(`Peer closure — ${String(report.staleExpectedOpen.length)} expectedOpenPeers name(s) no longer match an undeclared pivot: ${report.staleExpectedOpen.join(", ")}. Remove them so the acknowledgement list only silences pivots that actually exist.`);
+		if (report.uncovered.length === 0) {
+			log.success(report.expectedOpen.length === 0 ? `Peer closure — ${String(report.pivots.length)} pivot(s), all declared here.` : `Peer closure — no unacknowledged open pivots (${String(report.pivots.length)} total).`);
+			return;
+		}
+		const pivotLines = report.uncovered.map((pivot) => `    ${pivot.packageName} ← peer of ${pivot.declaredBy.join(", ")}`).join("\n");
+		log.warn(`Peer closure — ${String(report.uncovered.length)} @heximon/* peer(s) of this package's dependency closure are declared nowhere in its package.json:\n${pivotLines}\nA consumer whose installation satisfies these resolves DIFFERENT physical instances of the packages that peer on them — and class identity is the DI token. The fix is peer-context EQUALITY with your consumers, not coverage: in a pnpm workspace a peer declaration is never inert (pnpm installs a workspace importer's peerDependencies into its own context, \`optional\` or not), so adding these unilaterally can flip which side forks. Equalize the consumers' installed peer sets; if consumers sit on different platforms the roster cannot close — acknowledge these names in \`expectedOpenPeers\` (heximon.config.ts).`);
+	}
+	/**
+	* Logs the platform-tracing verdict ({@link PlatformTracingAuditor}): a warn block naming what the deployed
+	* wrangler config must carry by hand, a success line when it already does, or nothing when the audit had no
+	* evidence to judge. Advisory only — the build is correct either way, so this never sets the exit code.
+	*/
+	static logPlatformTracing(report) {
+		if (report.status === PlatformTracingStatus.NotApplicable) return;
+		const target = report.wranglerConfigPath === void 0 ? "this project commits no wrangler config" : `wrangler reads ${report.wranglerConfigPath} directly`;
+		if (report.status === PlatformTracingStatus.Carried) {
+			log.success(`Platform tracing — ${target}, and it carries the observability directives the platform exporter needs.`);
+			return;
+		}
+		const lines = [`Platform tracing — \`otel.exporter: "platform"\` turns tracing on by writing \`observability.traces.enabled: true\` into a GENERATED wrangler config, but this host-managed Cloudflare build produced none, so ${target}.`];
+		if (report.tracingNotEnabled) lines.push("    It does not enable traces, so the deploy runs with the tracing pipeline OFF. Add `\"observability\": { \"traces\": { \"enabled\": true } }` to it by hand.");
+		if (report.droppedSamplerRatio !== void 0) lines.push(`    \`otel.samplerRatio\` (${String(report.droppedSamplerRatio)}) maps onto the generated config's \`observability.traces.head_sampling_rate\` only, so it does nothing here — carry it in the same section by hand.`);
+		log.warn(lines.join("\n"));
+	}
+	/**
+	* The package names a fork of which is RUNTIME-reachable from the library at `rootDir`: the library itself,
+	* every package its installed `@heximon/*` dependency closure actually resolved
+	* ({@link PeerClosureReport.closurePackages}), every named peer pivot of that closure
+	* ({@link PeerClosureReport.pivots}), the curated {@link RuntimeSingletons}, and every installed boundary
+	* package ({@link PackageCopyAuditor.installedBoundaryPackages}) — a fork of a non-`@heximon` boundary
+	* package (e.g. a consumed `@acme/*` library) is exactly as much a DI-identity split as a fork of a
+	* framework package, since the rule is not scope-specific. A fork of a name outside this set is confined to
+	* build-time tooling (e.g. a devDependency-only bundler/pack plugin) and must be reported, never gated.
+	*/
+	static runtimeReachablePackageNames(rootDir, closureReport) {
+		const names = new Set(RuntimeSingletons.all());
+		const libraryName = DoctorReport.readPackageName(rootDir);
+		if (libraryName !== null) names.add(libraryName);
+		for (const packageName of PackageCopyAuditor.installedBoundaryPackages(rootDir)) names.add(packageName);
+		if (closureReport !== null) {
+			for (const packageName of closureReport.closurePackages) names.add(packageName);
+			for (const pivot of closureReport.pivots) names.add(pivot.packageName);
+		}
+		return names;
+	}
+	/** The `name` field of a directory's `package.json`, or `null` when absent/unreadable/malformed. */
+	static readPackageName(directory) {
+		try {
+			const parsed = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+			if (typeof parsed === "object" && parsed !== null && "name" in parsed) {
+				const { name } = parsed;
+				return typeof name === "string" ? name : null;
+			}
+		} catch {
+			return null;
+		}
+		return null;
+	}
+};
+/**
+* `heximon doctor` — three read-only audits.
+*
+* Registry access ({@link RegistryAccess}) is probed first, in both modes: it runs `npm view` against
+* GitHub Packages, the private registry `@heximon/*` publishes to, and reports whether the `.npmrc` scope
+* line plus a user-level auth token are in place. Exits non-zero on a non-Ok verdict, same as the audits
+* below.
+*
+* The physical-copy census ({@link PackageCopyAuditor}) runs next and always: it resolves every
+* identity-bearing package from every origin that reaches it and reports any name with more than one physical
+* copy. Compile-free, so it still answers on a project that does not build, and it is the only check an app
+* with no consumed boundaries gets. Reported, never gated — the remedy is the dependency tree, not this run.
+*
+* The platform-tracing audit ({@link PlatformTracingAuditor}) then reports when an app compiled with the
+* OpenTelemetry platform exporter would deploy untraced, because the host writes no generated wrangler config
+* for the exporter's directives to land in. Advisory only — the build is correct; the deployment context is
+* what drops them.
+*
+* The staleness audit then compares every consumed boundary package's local `src/` fingerprint against its
+* installed manifest's pack-time provenance ({@link BoundaryProvenanceAuditor}). Exits non-zero when any
+* boundary is stale, so CI can gate on it.
+*
+* `--self` flips onto the CURRENT package's own perspective — the library author's pre-publish check — and
+* runs three legs in order:
+* 1. the `@heximon/*` peer-pivot roster ({@link PeerClosureAuditor}), predicted from this package's own
+*    installed dependency closure. Advisory only, never gates — a one-sided fix can flip a fork rather than
+*    remove it. Pivots acknowledged in the sidecar's `expectedOpenPeers` are reported as expected-open
+*    rather than warned.
+* 2. the library-side physical-copy census ({@link PackageCopyAuditor.auditLibrary}), run from this package
+*    plus every in-workspace consumer ({@link WorkspaceConsumerLocator}). Every fork is reported, but only a
+*    fork of a package RUNTIME-reachable from this one — its own name, its dependency closure
+*    ({@link PeerClosureReport.closurePackages}), a named peer pivot ({@link PeerClosureReport.pivots}), a
+*    curated {@link RuntimeSingletons}, or an installed boundary package
+*    ({@link PackageCopyAuditor.installedBoundaryPackages}) — exits non-zero; a fork confined to build-time
+*    tooling (e.g. a devDependency-only bundler) is reported and does not gate.
+* 3. the staleness check ({@link BoundaryProvenanceAuditor.auditSelf}) — this package's own
+*    `dist/heximon.manifest.json` against its own `src/`. Stale exits non-zero.
+*
+* Compile-free and filesystem-local (the `heximon.config.ts` sidecar is loaded only to read
+* `expectedOpenPeers`); exits non-zero when this package forks a runtime-reachable package against a
+* workspace consumer OR its own dist is stale.
+*/
+const doctorCommand = defineCommand({
+	meta: {
+		name: "doctor",
+		description: "Registry access (can @heximon/* be read from GitHub Packages), plus three read-only audits: the physical-copy census (forked identity-bearing packages), the platform-tracing check, and the staleness audit of consumed Heximon libraries (local src vs packed manifest provenance). `--self` runs the library author's pre-publish check instead."
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		self: {
+			type: "boolean",
+			description: "Library pre-publish check: this package's own peer-closure roster (advisory), its copy census against workspace consumers, and its packed manifest vs its own src/. Exits non-zero on a fork of a runtime-reachable package (its dependency closure, a named pivot, a curated runtime singleton, an installed boundary package, or itself) or a stale dist — a fork confined to build-time tooling is reported but does not gate.",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const rootDir = resolve(process.cwd(), args.cwd);
+		intro(`heximon doctor — ${basename(rootDir)}`);
+		const registryReport = await new RegistryAccess().probe();
+		const registryFailed = registryReport.status !== RegistryAccessStatus.Ok;
+		if (registryFailed) log.error(RegistryAccess.fixInstructions(registryReport.status));
+		else log.success("✔ GitHub Packages — @heximon/* readable");
+		if (args.self) {
+			const expectedOpenPeers = await ConfigLoader.load(rootDir).then((sidecar) => sidecar?.expectedOpenPeers ?? []).catch((error) => {
+				log.warn(`heximon.config.ts could not be loaded, so its \`expectedOpenPeers\` acknowledgements are not applied — every open pivot below is reported: ${error instanceof Error ? error.message : String(error)}`);
+				return [];
+			});
+			const closureReport = PeerClosureAuditor.audit(rootDir, expectedOpenPeers);
+			DoctorReport.logPeerClosureRoster(closureReport);
+			const workspaceConsumers = WorkspaceConsumerLocator.locate(rootDir);
+			let forked = false;
+			if (workspaceConsumers === null) log.info("Package copies — no pnpm workspace found from this directory; census not run.");
+			else forked = DoctorReport.logCopyAudit(PackageCopyAuditor.auditLibrary(rootDir, workspaceConsumers.consumers), DoctorReport.runtimeReachablePackageNames(rootDir, closureReport));
+			const selfReport = BoundaryProvenanceAuditor.auditSelf(rootDir);
+			const outroParts = [];
+			let exitFailure = forked || registryFailed;
+			if (forked) {
+				const hasConsumers = (workspaceConsumers?.consumers.length ?? 0) > 0;
+				outroParts.push(hasConsumers ? "Forked against a workspace consumer — equalize the two packages' installed peer contexts (a one-sided cover can flip the fork, not remove it) and reinstall." : "Forked within this package's own resolution (no workspace consumers found to compare against) — align the versions its own dependency tree resolves and reinstall.");
+			}
+			if (selfReport === null) outroParts.push("This directory is not a packed Heximon library (no dist/heximon.manifest.json) — the peer-closure and copy census above still ran; run `vp pack` to enable the staleness check too.");
+			else {
+				DoctorReport.logBoundary(selfReport, true);
+				if (selfReport.status === BoundaryProvenanceStatus.Stale) {
+					exitFailure = true;
+					outroParts.push(DoctorReport.selfProvenanceSummary(selfReport));
+				} else if (!forked) outroParts.push(DoctorReport.selfProvenanceSummary(selfReport));
+			}
+			if (exitFailure) process.exitCode = 1;
+			outro(outroParts.join(" "));
+			return;
+		}
+		DoctorReport.logCopyAudit(PackageCopyAuditor.audit(rootDir));
+		DoctorReport.logPlatformTracing(await PlatformTracingAuditor.audit(rootDir));
+		const reports = await BoundaryProvenanceAuditor.audit(rootDir);
+		if (reports.length === 0) {
+			if (registryFailed) process.exitCode = 1;
+			outro("No consumed Heximon library packages found — no staleness audit to run.");
+			return;
+		}
+		for (const report of reports) DoctorReport.logBoundary(report);
+		const staleCount = reports.filter((report) => report.status === BoundaryProvenanceStatus.Stale).length;
+		if (staleCount > 0 || registryFailed) process.exitCode = 1;
+		if (staleCount > 0) outro(`${staleCount} stale package(s) — rebuild them before trusting this app's build.`);
+		else outro(`${reports.length} package(s) audited — no staleness detected.`);
+	}
+});
+//#endregion
+//#region src/json-output-target.ts
+/**
+* Where a JSON-emitting inspection command (`routes`, `graph`) sends its payload: an `--out` file, stdout under
+* `--json`, or nowhere when neither flag was passed. One owner for that whole decision — both commands hand it
+* a payload and never branch on the flags themselves.
+*/
+var JsonOutputTarget = class JsonOutputTarget {
+	filePath;
+	toStdout;
+	/**
+	* @param filePath - The absolute `--out` path, or `undefined` when no file was requested.
+	* @param toStdout - Whether the payload is printed on stdout instead.
+	*/
+	constructor(filePath, toStdout) {
+		this.filePath = filePath;
+		this.toStdout = toStdout;
+	}
+	/**
+	* Resolve the destination. `--out` wins and redirects the payload off stdout into a file; a relative path
+	* resolves against the current directory (where the command was typed), not the `--cwd` project root.
+	*
+	* @param outOption - The raw `--out` argument, when the caller passed one.
+	* @param asJson - Whether `--json` was passed, i.e. whether stdout should carry the payload.
+	*/
+	static resolve(outOption, asJson) {
+		const requested = outOption?.trim();
+		const filePath = requested === void 0 || requested === "" ? void 0 : resolve(process.cwd(), requested);
+		return new JsonOutputTarget(filePath, filePath === void 0 && asJson);
+	}
+	/** Whether the payload goes to a file — the caller's cue to report where it landed. */
+	isFile() {
+		return this.filePath !== void 0;
+	}
+	/**
+	* Emit the payload. A file gets indented JSON with its parent directory created, so a run can target a
+	* not-yet-existing CI artifact directory and consecutive runs diff line by line; stdout gets the compact
+	* single line `jq` and pipes expect.
+	*
+	* @returns `false` only when a requested file write failed (the reason is reported on stderr) — the caller's
+	* cue to exit non-zero. A target that emits nowhere reports success.
+	*/
+	emit(payload) {
+		if (this.filePath === void 0) {
+			if (this.toStdout) process.stdout.write(`${JSON.stringify(payload)}\n`);
+			return true;
+		}
+		try {
+			mkdirSync(dirname(this.filePath), { recursive: true });
+			writeFileSync(this.filePath, `${JSON.stringify(payload, null, 2)}\n`);
+			return true;
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`Could not write ${this.filePath} — ${reason}\n`);
+			return false;
+		}
+	}
+};
+//#endregion
+//#region src/module-graph-report.ts
+/**
+* Renders a {@link ModuleGraphView} (and, optionally, the cross-package {@link BoundarySummary} nodes) as a
+* module-nested tree for the terminal, and as a serializable object for `--json`. Every module is a top-level
+* node over its imports/exports and its providers, and each provider over its resolved dependency tokens.
+*/
+var ModuleGraphReport = class ModuleGraphReport {
+	static indent = "  ";
+	/** Render the module tree, appending a `boundaries` section when boundary nodes are supplied. */
+	static renderTree(view, boundaries = []) {
+		const lines = [];
+		if (view.modules.length === 0) lines.push("(no modules)");
+		const seenByIdentity = /* @__PURE__ */ new Map();
+		for (const module of view.modules) {
+			const identity = `${module.reference.sourceFile}#${module.reference.className}`;
+			const ordinal = (seenByIdentity.get(identity) ?? 0) + 1;
+			seenByIdentity.set(identity, ordinal);
+			ModuleGraphReport.appendModule(lines, module, ordinal);
+		}
+		if (boundaries.length > 0) {
+			lines.push("", "boundaries:");
+			for (const boundary of boundaries) {
+				lines.push(`${ModuleGraphReport.indent}${boundary.specifier} → ${boundary.factory}`);
+				if (boundary.requires.length > 0) lines.push(`${ModuleGraphReport.indent.repeat(2)}requires: ${boundary.requires.join(", ")}`);
+				if (boundary.exports.length > 0) lines.push(`${ModuleGraphReport.indent.repeat(2)}exports: ${boundary.exports.join(", ")}`);
+			}
+		}
+		return lines.join("\n");
+	}
+	/**
+	* The serializable `--json` shape: the raw module view plus (when present) the boundary summaries.
+	*
+	* @param view - The compile's module-graph projection.
+	* @param boundaries - The cross-package boundary summaries, when `--boundaries` asked for them.
+	* @param ok - Whether the compile that produced `view` was clean. A graph built from a failed compile has
+	*   unresolved edges, so a consumer reading only `ok` must not read it as a complete answer.
+	*/
+	static toJson(view, boundaries = [], ok = true) {
+		return {
+			ok,
+			modules: view.modules,
+			...boundaries.length > 0 ? { boundaries } : {}
+		};
+	}
+	/**
+	* Append one module's lines: its name (annotated with its fork ordinal when it composes to more than one
+	* instance in the app), its imports/exports, then each provider over its dependencies.
+	*/
+	static appendModule(lines, module, forkOrdinal) {
+		const indent = ModuleGraphReport.indent;
+		const instanceCount = module.instanceCount ?? 1;
+		const forkSuffix = instanceCount > 1 ? ` (fork ${forkOrdinal} of ${instanceCount})` : "";
+		lines.push(`${module.reference.className}${forkSuffix}`);
+		if (module.imports.length > 0) lines.push(`${indent}imports: ${module.imports.map((token) => token.className).join(", ")}`);
+		if (module.exports.length > 0) lines.push(`${indent}exports: ${module.exports.map((token) => token.className).join(", ")}`);
+		if (module.providers.length > 0) {
+			lines.push(`${indent}providers:`);
+			for (const provider of module.providers) {
+				lines.push(`${indent.repeat(2)}${ModuleGraphReport.tokenLabel(provider.token)} [${provider.kind}]`);
+				for (const dependency of provider.dependencies) {
+					const origin = dependency.isLazy ? `${dependency.origin}, lazy` : dependency.origin;
+					const name = dependency.reference?.displayName ?? dependency.tokenName;
+					lines.push(`${indent.repeat(3)}→ ${name} (${origin})`);
+				}
+			}
+		}
+	}
+	/**
+	* A token's display label: its class name, or — for a class shipped under a compiler-synthesized
+	* machine-channel alias — its declared name with the alias kept visible, so the line still
+	* cross-references the generated wiring's import.
+	*/
+	static tokenLabel(token) {
+		return token.displayName === void 0 ? token.className : `${token.displayName} (shipped as ${token.className})`;
+	}
+};
+//#endregion
+//#region src/graph-command.ts
+/**
+* `heximon graph` — print the resolved module dependency graph (modules → providers → each provider's
+* resolved dependencies). This is a COMPILE-TIME artifact — like `heximon routes`, it needs no boot: it runs
+* the same from-disk `ProjectCompiler` compile `heximon check` runs and renders `CompileOutput`'s
+* module-graph projection. `--boundaries` also lists the cross-package boundary nodes the app composes.
+*
+* In a PUBLISHED MODULE PACKAGE the compile runs in library mode
+* ({@link ProjectCompileSession.compileLibrary}). Its nodes are the package's PUBLISHED ROOTS, each already
+* folded over the local sub-modules it owns — a package's individual source modules are not separately
+* composable, so they are not separately rendered.
+*/
+const graphCommand = defineCommand({
+	meta: {
+		name: "graph",
+		description: "Compile the project and print the resolved module dependency graph (modules → providers → dependencies)."
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		env: {
+			type: "string",
+			description: "The heximon.config.ts `$env` name to resolve (matches `vp dev`). Default development.",
+			default: "development"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit the graph as JSON on stdout instead of a tree.",
+			default: false
+		},
+		boundaries: {
+			type: "boolean",
+			description: "Also list the cross-package boundary nodes the app composes.",
+			default: false
+		},
+		out: {
+			type: "string",
+			description: "Write the JSON payload to this file instead of stdout, creating missing parent directories — the CI-artifact target."
+		},
+		src: {
+			type: "string",
+			description: "Source directories to scan, comma-separated. Defaults to `src/`, or `server/` for a Nitro/Nuxt host."
+		},
+		library: CompileModeResolver.flags.library,
+		app: CompileModeResolver.flags.app
+	},
+	async run({ args }) {
+		const rootDir = resolve(process.cwd(), args.cwd);
+		const asJson = args.json;
+		const withBoundaries = args.boundaries;
+		const jsonOutput = JsonOutputTarget.resolve(args.out, asJson);
+		const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+		const resolved = CompileModeResolver.resolve("graph", rootDir, args, sourceDirectories);
+		if (resolved === void 0) return;
+		if (!asJson) intro(`heximon graph — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
+		let output;
+		try {
+			const session = await ProjectCompileSession.open({
+				rootDir,
+				environment: args.env,
+				...sourceDirectories === void 0 ? {} : { sourceDirectories }
+			});
+			output = resolved.mode === CompileMode.Library ? session.compileLibrary() : session.compile();
+		} catch (error) {
+			GraphCommand.reportFailure(error, asJson, jsonOutput);
+			process.exitCode = 1;
+			return;
+		}
+		if (!GraphCommand.report(output, {
+			asJson,
+			withBoundaries,
+			jsonOutput,
+			libraryMode: resolved.mode === CompileMode.Library
+		})) process.exitCode = 1;
+	}
+});
+/** Output helpers for {@link graphCommand}: the module tree / JSON body and the boundary projection. */
+var GraphCommand = class GraphCommand {
+	/**
+	* Print the resolved graph — the JSON payload to its target, and a module-nested tree unless `--json`.
+	*
+	* @returns Whether the run succeeded; `false` for a failed compile or a failed `--out` write.
+	*/
+	static report(output, options) {
+		const view = output.moduleGraph ?? { modules: [] };
+		const boundaries = options.withBoundaries ? GraphCommand.boundarySummaries(output) : [];
+		const errors = output.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error).length;
+		const written = options.jsonOutput.emit({
+			...ModuleGraphReport.toJson(view, boundaries, errors === 0),
+			errors
+		});
+		if (options.asJson) return written && errors === 0;
+		if (written && options.jsonOutput.isFile()) log.success(`Graph JSON written to ${options.jsonOutput.filePath}.`);
+		log.message(ModuleGraphReport.renderTree(view, boundaries));
+		if (options.libraryMode === true) log.info("These nodes are this package's PUBLISHED ROOTS, each folded over the local sub-modules it owns. A package's own sub-modules are not separately composable, so they carry no node of their own.");
+		const moduleCount = view.modules.length;
+		const summary = `${moduleCount} module${moduleCount === 1 ? "" : "s"}`;
+		if (errors > 0) outro(`${summary} — ${errors} compile error${errors === 1 ? "" : "s"}; the graph may be incomplete.`);
+		else outro(`${summary}.`);
+		return written && errors === 0;
+	}
+	/**
+	* Report a config-load / compile failure: `{ ok: false, error }` to the JSON target, and a clack error +
+	* outro unless `--json`. The failure payload goes to `--out` too, so re-running replaces the previous
+	* artifact rather than leaving a stale success.
+	*/
+	static reportFailure(error, asJson, jsonOutput) {
+		const message = error instanceof Error ? error.message : String(error);
+		jsonOutput.emit({
+			ok: false,
+			error: message
+		});
+		if (asJson) return;
+		log.error(`Could not read the app's module graph:\n${message}`);
+		outro("No graph to show.");
+	}
+	/** Project the compile's cross-package boundary nodes into display summaries. */
+	static boundarySummaries(output) {
+		return output.boundaryNodes.map((boundary) => ({
+			specifier: boundary.specifier,
+			factory: boundary.factoryExport,
+			requires: boundary.requires.map((require) => require.token.className),
+			exports: boundary.exports.map((exported) => exported.token.className)
+		}));
+	}
+};
+//#endregion
+//#region src/migrations-command.ts
+/**
+* The plumbing every `heximon migrations` subcommand shares: the `.env` + detection prologue, the config
+* selection, one captured `drizzle-kit` invocation, and the throw-to-cancel guard.
+*/
+var MigrationsRunner = class MigrationsRunner {
+	/** The flags every `heximon migrations` subcommand accepts. */
+	static baseArgs = {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		env: {
+			type: "string",
+			description: "Env mode selecting the .env overlay (.env.<mode>); default development.",
+			default: "development"
+		},
+		"env-file": {
+			type: "string",
+			description: "Load an explicit dotenv file over the cascade (e.g. .env.production for a prod migrate)."
+		},
+		config: {
+			type: "string",
+			description: "Target one drizzle-kit config file, bypassing auto-detection."
+		}
+	};
+	/** The `select` sentinel for "run every detected database". */
+	static allDatabasesValue = "__all__";
+	/**
+	* Resolve the project root, load the `.env` cascade into `process.env` (so the spawned `drizzle-kit`
+	* inherits `DATABASE_URL`), and detect the app's drizzle-kit config file(s). An explicit `--env-file`
+	* overlays the cascade.
+	*/
+	static async prepare(args) {
+		const rootDir = resolve(process.cwd(), args.cwd);
+		const overlay = args["env-file"] === void 0 ? void 0 : await EnvFileReader.read(resolve(rootDir, args["env-file"]));
+		DotenvCascade.loadInto(rootDir, args.env, overlay);
+		return {
+			rootDir,
+			detection: await DatabaseConfigDetector.detect(rootDir)
+		};
+	}
+	/**
+	* Choose which detected config(s) to act on: an explicit `--config` wins; a single detected config is used
+	* silently; multiple prompt an interactive `select`, or — in a non-TTY run — fan out to ALL of them, which
+	* is named out loud because that is several databases the operator never chose. Reports the failure itself
+	* (no config / cancelled) and returns `undefined` so the caller just returns.
+	*/
+	static async selectConfigs(rootDir, detection, args, interactive) {
+		if (args.config !== void 0) {
+			const path = resolve(rootDir, args.config);
+			return [await DatabaseConfigDetector.classifyFile(rootDir, path) ?? MigrationsRunner.syntheticConfig(path)];
+		}
+		const { configs } = detection;
+		if (configs.length === 0) {
+			MigrationsRunner.reportNoConfig(detection);
+			return;
+		}
+		if (configs.length === 1) return configs;
+		if (!interactive) {
+			log.warn(`${configs.length} databases detected and no TTY to choose between them — acting on ALL of them: ${configs.map((config) => config.name).join(", ")}. Pass --config <path> to target one.`);
+			return configs;
+		}
+		const choice = await select({
+			message: "Which database?",
+			options: [{
+				value: MigrationsRunner.allDatabasesValue,
+				label: "All databases"
+			}, ...configs.map((config) => ({
+				value: config.path,
+				label: config.name
+			}))]
+		});
+		if (isCancel(choice)) {
+			cancel("Cancelled — nothing run.");
+			process.exitCode = 1;
+			return;
+		}
+		if (choice === MigrationsRunner.allDatabasesValue) return configs;
+		return configs.filter((config) => config.path === choice);
+	}
+	/**
+	* Run one captured `drizzle-kit` invocation behind a spinner, relaying its output.
+	*
+	* @returns `true` on exit code 0, else `false` (the output is logged either way).
+	*/
+	static async runStep(interactive, label, invoke) {
+		const progress = CliSpinner.begin(interactive, `${label}…`);
+		let result;
+		try {
+			result = await invoke();
+		} catch (error) {
+			progress?.stop(`${label} — failed to start.`);
+			throw error;
+		}
+		const output = [result.stdout.trim(), result.stderr.trim()].filter((part) => part.length > 0);
+		if (result.exitCode === 0) {
+			progress?.stop(`${label} — done.`);
+			if (output.length > 0) log.message(output.join("\n"));
+			return true;
+		}
+		progress?.stop(`${label} — failed (exit ${result.exitCode}).`);
+		if (output.length > 0) log.error(output.join("\n"));
+		return false;
+	}
+	/**
+	* Wrap a subcommand body so a thrown error (e.g. an unreadable `--env-file`) becomes a clean cancel +
+	* non-zero exit rather than an unhandled stack trace.
+	*/
+	static async guard(body) {
+		try {
+			await body();
+		} catch (error) {
+			process.exitCode = 1;
+			cancel(error instanceof Error ? error.message : String(error));
+		}
+	}
+	/**
+	* A stand-in for an explicit `--config` that could not be classified (unloadable / not a drizzle config):
+	* the command still drives `drizzle-kit` on it and surfaces drizzle-kit's own error, trusting the flag.
+	*/
+	static syntheticConfig(path) {
+		return {
+			path,
+			name: basename(path),
+			dialect: "unknown",
+			driver: void 0,
+			out: void 0,
+			applyMode: "drizzle-kit"
+		};
+	}
+	/**
+	* Report that no drizzle-kit config was detected — the actionable halt, listing any candidate that failed
+	* to load (the likeliest cause of a "missing" config).
+	*/
+	static reportNoConfig(detection) {
+		process.exitCode = 1;
+		cancel("No drizzle-kit config found — expected a `*.config.ts` that `export default`s a Drizzle config (e.g. src/database/database.config.ts), or pass --config <path>.");
+		for (const failure of detection.loadErrors) log.warn(`Could not load ${failure.path}: ${failure.message}`);
+	}
+};
+const generateCommand = defineCommand({
+	meta: {
+		name: "generate",
+		description: "Author a migration from the schema diff (drizzle-kit generate)."
+	},
+	args: {
+		...MigrationsRunner.baseArgs,
+		name: {
+			type: "string",
+			description: "Name the migration (drizzle-kit --name)."
+		}
+	},
+	run: ({ args }) => MigrationsRunner.guard(async () => {
+		const interactive = CliEnvironment.isInteractive();
+		intro("heximon migrations generate");
+		const { rootDir, detection } = await MigrationsRunner.prepare(args);
+		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+		if (selected === void 0) return;
+		const runner = new DrizzleKitRunner();
+		let allSucceeded = true;
+		for (const config of selected) allSucceeded = await MigrationsRunner.runStep(interactive, `Generating migration for ${config.name}`, () => runner.generate(config.path, { rootDir }, args.name)) && allSucceeded;
+		if (!allSucceeded) {
+			process.exitCode = 1;
+			cancel("Some migrations failed to generate — see above.");
+			return;
+		}
+		outro("Migration(s) generated — review the SQL, then `heximon migrations migrate`.");
+	})
+});
+const migrateCommand = defineCommand({
+	meta: {
+		name: "migrate",
+		description: "Apply pending migrations (drizzle-kit migrate)."
+	},
+	args: MigrationsRunner.baseArgs,
+	run: ({ args }) => MigrationsRunner.guard(async () => {
+		const interactive = CliEnvironment.isInteractive();
+		intro("heximon migrations migrate");
+		const { rootDir, detection } = await MigrationsRunner.prepare(args);
+		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+		if (selected === void 0) return;
+		const runner = new DrizzleKitRunner();
+		let allSucceeded = true;
+		for (const config of selected) {
+			if (config.applyMode === "wrangler-d1") {
+				log.warn(`${config.name}: a Cloudflare D1 database — apply it with \`wrangler d1 migrations apply <database> --remote\`, not drizzle-kit.`);
+				continue;
+			}
+			if (config.applyMode === "skip") {
+				log.info(`${config.name}: Durable Object SQLite — migrations bundle in-DO at init; no CLI apply step.`);
+				continue;
+			}
+			allSucceeded = await MigrationsRunner.runStep(interactive, `Applying migrations for ${config.name}`, () => runner.migrate(config.path, { rootDir })) && allSucceeded;
+		}
+		if (!allSucceeded) {
+			process.exitCode = 1;
+			cancel("Some migrations failed to apply — see above.");
+			return;
+		}
+		outro("Migrations applied.");
+	})
+});
+const statusCommand = defineCommand({
+	meta: {
+		name: "status",
+		description: "List the on-disk migrations per database."
+	},
+	args: MigrationsRunner.baseArgs,
+	run: ({ args }) => MigrationsRunner.guard(async () => {
+		const interactive = CliEnvironment.isInteractive();
+		intro("heximon migrations status");
+		const { rootDir, detection } = await MigrationsRunner.prepare(args);
+		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+		if (selected === void 0) return;
+		for (const config of selected) {
+			const outFolder = config.out ?? DatabaseConfigDetector.defaultOutDirectory;
+			const files = await MigrationInspector.collectSqlFiles(resolve(rootDir, outFolder));
+			if (files.length === 0) {
+				log.info(`${config.name}: no migrations in ${outFolder} — run \`heximon migrations generate\`.`);
+				continue;
+			}
+			log.message(`${config.name} · ${files.length} migration(s) in ${outFolder}:\n` + files.map((file) => `  ${file.relativePath}`).join("\n"));
+		}
+		log.info("Applied vs. pending state needs a live database query — not shown in this view.");
+		outro("Status listed.");
+	})
+});
+const pushCommand = defineCommand({
+	meta: {
+		name: "push",
+		description: "Push the schema straight to the database — destructive; dev only (drizzle-kit push)."
+	},
+	args: {
+		...MigrationsRunner.baseArgs,
+		yes: {
+			type: "boolean",
+			description: "Confirm the destructive push non-interactively."
+		}
+	},
+	run: ({ args }) => MigrationsRunner.guard(async () => {
+		const interactive = CliEnvironment.isInteractive();
+		intro("heximon migrations push");
+		const { rootDir, detection } = await MigrationsRunner.prepare(args);
+		const selected = await MigrationsRunner.selectConfigs(rootDir, detection, args, interactive);
+		if (selected === void 0) return;
+		let force = args.yes === true;
+		if (!force) {
+			if (!interactive) {
+				process.exitCode = 1;
+				cancel("`push` is destructive (it can drop columns/tables). Re-run with --yes to confirm in a non-interactive shell.");
+				return;
+			}
+			const confirmed = await confirm({
+				message: `Push schema directly to ${selected.map((config) => config.name).join(", ")}? This can DROP columns/tables.`,
+				initialValue: false
+			});
+			if (isCancel(confirmed) || confirmed !== true) {
+				cancel("Cancelled — nothing pushed.");
+				process.exitCode = 1;
+				return;
+			}
+			force = true;
+		}
+		const runner = new DrizzleKitRunner();
+		let allSucceeded = true;
+		for (const config of selected) allSucceeded = await MigrationsRunner.runStep(interactive, `Pushing schema for ${config.name}`, () => runner.push(config.path, { rootDir }, force)) && allSucceeded;
+		if (!allSucceeded) {
+			process.exitCode = 1;
+			cancel("Some schema pushes failed — see above.");
+			return;
+		}
+		outro("Schema pushed.");
+	})
+});
+/**
+* The `heximon migrations` command — drive the app's local `drizzle-kit` against its auto-detected Drizzle
+* config with `.env` loaded, so schema authoring / applying needs no hand-written `drizzle.config.ts` or
+* per-app script.
+*/
+const migrationsCommand = defineCommand({
+	meta: {
+		name: "migrations",
+		description: "Author + apply database migrations via the app's local drizzle-kit, against its auto-detected config."
+	},
+	subCommands: {
+		generate: generateCommand,
+		migrate: migrateCommand,
+		status: statusCommand,
+		push: pushCommand
+	}
+});
+//#endregion
+//#region src/provision-command.ts
+/**
+* `heximon provision` — the PRE-BUILD verb for resources whose id the build itself needs (a Cloudflare
+* Hyperdrive binding with an empty `id` fails the build outright, and provisioning is what mints that id).
+* It calls exactly one seam, `strategy.provisionInfrastructure(context)` — never the deploy-time
+* `strategy.provision(...)` that creates queues and pushes secrets.
+*/
+const provisionCommand = defineCommand({
+	meta: {
+		name: "provision",
+		description: "Create the foundational resources whose id the build needs (e.g. Cloudflare Hyperdrive), then report each id to record. Run once, before deploy."
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		env: {
+			type: "string",
+			description: "Deploy environment (production / staging / preview:<id>).",
+			default: "production"
+		},
+		"dry-run": {
+			type: "boolean",
+			description: "Report what would be created, but create nothing.",
+			default: false
+		},
+		"save-ids": {
+			type: "boolean",
+			description: "Record each created resource's id in the per-environment deploy ledger (.heximon/deploy-env.<env>.json) — the deploy injects it into the build, so a config reading the conventional env var needs no manual paste.",
+			default: false
+		},
+		platform: {
+			type: "string",
+			description: "Override the platform (e.g. cloudflare) when heximon.config.ts does not declare it."
+		},
+		profile: {
+			type: "string",
+			description: "Not supported here: provisioning talks to the Cloudflare REST API with CLOUDFLARE_API_TOKEN, which a wrangler auth profile does not carry. (heximon deploy does accept --profile.)"
+		}
+	},
+	async run({ args }) {
+		const rootDir = resolve(process.cwd(), args.cwd);
+		const environment = args.env;
+		const interactive = CliEnvironment.isInteractive();
+		intro(`heximon provision · ${environment}`);
+		if (args.profile !== void 0) {
+			cancel("--profile is not supported by `heximon provision` — provisioning talks to the Cloudflare REST API with CLOUDFLARE_API_TOKEN, which a wrangler auth profile does not carry. Set the token instead.");
+			process.exitCode = 1;
+			return;
+		}
+		try {
+			const target = await DeployTargetResolver.resolve(rootDir, environment, args.platform);
+			log.info(`Platform: ${target.platformName ?? "node (default)"} · target class: ${target.targetClass}`);
+			const specs = CredentialSelection.inPlay(target.strategy.requiredCredentials(), { provisioning: true });
+			const credentials = await CredentialResolver.resolve(specs, {
+				interactive,
+				prompter: interactive ? new ClackPrompter() : void 0
+			});
+			const progress = CliSpinner.begin(interactive, args["dry-run"] === true ? "Previewing the foundational resources…" : "Provisioning foundational resources…");
+			let outcome;
+			try {
+				outcome = await DeployRunner.provisionInfrastructure({
+					target,
+					rootDir,
+					environment,
+					credentials,
+					dryRun: args["dry-run"],
+					saveIds: args["save-ids"]
+				});
+			} catch (provisionError) {
+				progress?.stop("Provisioning failed — see the error below.");
+				throw provisionError;
+			}
+			progress?.stop("Provision steps complete.");
+			if (outcome.unsupported) {
+				cancel(`Platform ${outcome.platformName ?? "node (default)"} has no foundational resources to provision.`);
+				process.exitCode = 1;
+				return;
+			}
+			const result = outcome.result;
+			for (const message of result?.messages ?? []) log.message(message);
+			for (const provisioned of result?.provisioned ?? []) log.success(`Provisioned ${provisioned.resource} → id ${provisioned.id}.`);
+			if (outcome.savedIds !== void 0) log.success(`Recorded ${outcome.savedIds.names.join(", ")} in ${outcome.savedIds.path} — \`heximon deploy\` injects it into the build.`);
+			if (result !== void 0 && result.failed.length > 0) {
+				process.exitCode = 1;
+				cancel(`Provisioning failed for: ${result.failed.join(", ")} — see above.`);
+				return;
+			}
+			outro(outcome.savedIds !== void 0 ? "Provisioning complete — ids recorded in the deploy ledger; deploy when ready." : "Provisioning complete — record the ids above in your config, then deploy.");
+		} catch (error) {
+			if (DeployCommandFailure.report(error)) return;
+			throw error;
+		}
+	}
+});
+//#endregion
+//#region src/route-table-report.ts
+/**
+* Renders a {@link RouteCensusRow} list as an aligned, columnar route table for the terminal —
+* `METHOD  PATH  SOURCE  HANDLER`, one row per path the app answers, streams and sockets included. The
+* `HANDLER` column names the contract route a contract-mode row dispatches to (`UploadsApi.create`) and the
+* declaring class of a stream or socket row; it is blank for an inline route, which carries neither.
+*
+* Two more columns are appended only when some row carries the fact they report, so a table read off a
+* source that resolves neither stays exactly as wide as it always was: `SCOPES` for the authorization union,
+* and `MIDDLEWARE` for the connect/upgrade chain that guards a streaming path — the two are different
+* answers to "what stands between a caller and this path", so neither is rendered in the other's column.
+*/
+var RouteTableReport = class RouteTableReport {
+	static baseHeaders = [
+		"METHOD",
+		"PATH",
+		"SOURCE",
+		"HANDLER"
+	];
+	/** The `SCOPES` column header, appended only when some row carries scope information. */
+	static scopesHeader = "SCOPES";
+	/** The `MIDDLEWARE` column header, appended only when some row carries a connect/upgrade chain. */
+	static middlewareHeader = "MIDDLEWARE";
+	/** The `SCOPES` cell for a route that resolved to no scopes at all — an unguarded route. */
+	static noScopesCell = "-";
+	/** The `SCOPES` cell for a route whose scopes could not be resolved — NOT the same fact as none. */
+	static unresolvedScopesCell = "?";
+	/** Render `rows` (already sorted by the caller) as the aligned table text — never a trailing newline. */
+	static render(rows) {
+		const withScopes = rows.some((row) => row.scopes !== void 0 || row.scopesUnresolved !== void 0);
+		const withMiddleware = rows.some((row) => row.middlewares !== void 0);
+		const headers = [
+			...RouteTableReport.baseHeaders,
+			...withScopes ? [RouteTableReport.scopesHeader] : [],
+			...withMiddleware ? [RouteTableReport.middlewareHeader] : []
+		];
+		const cells = rows.map((row) => [
+			row.method,
+			row.path,
+			row.source,
+			RouteTableReport.handlerOf(row),
+			...withScopes ? [RouteTableReport.scopesOf(row)] : [],
+			...withMiddleware ? [(row.middlewares ?? []).join(", ")] : []
+		]);
+		const widths = headers.map((header, column) => Math.max(header.length, ...cells.map((row) => row[column].length)));
+		const line = (columns) => columns.map((value, column) => value.padEnd(widths[column])).join("  ").trimEnd();
+		return [line(headers), ...cells.map(line)].join("\n");
+	}
+	/**
+	* The `HANDLER` cell: `Contract.routeKey` for a contract route, the declaring class for a stream or socket
+	* row (whose one path IS the class), else empty for an inline route, which names neither.
+	*/
+	static handlerOf(row) {
+		if (row.handler === void 0) return row.middlewares === void 0 ? "" : row.controller ?? "";
+		return row.contract === void 0 ? row.handler : `${row.contract}.${row.handler}`;
+	}
+	/**
+	* The `SCOPES` cell: the scope names, `-` for an unguarded route, `?` when they could not be resolved, and
+	* EMPTY for a row that claims nothing on this axis at all — a streaming path, whose guard is the chain the
+	* `MIDDLEWARE` column names. Rendering `-` there would assert an unguarded path the census never claimed.
+	*/
+	static scopesOf(row) {
+		if (row.scopes !== void 0) return row.scopes.length === 0 ? RouteTableReport.noScopesCell : row.scopes.join(", ");
+		return row.scopesUnresolved === void 0 ? "" : RouteTableReport.unresolvedScopesCell;
+	}
+};
+//#endregion
+//#region src/routes-command.ts
+/**
+* Boots an app in-process to read its live HTTP route table — the `--boot` fallback for a route surface the
+* compiler cannot describe statically. Booting imports the app's TypeScript source through `.js` specifiers,
+* and Heximon's parameter-property classes need a TypeScript TRANSFORM (not just type-stripping), so the boot
+* runs under a one-time re-exec with Node's transform-types enabled plus a resolve hook that maps those `.js`
+* specifiers to their `.ts` sources.
+*/
+var RoutesBoot = class RoutesBoot {
+	/** Set on the re-exec'd child so it boots rather than re-exec'ing again. */
+	static transformMarker = "HEXIMON_ROUTES_TRANSFORM";
+	/** The `.js`/extensionless → `.ts` ESM resolve hook, inlined as a `data:` module so it ships in no file. */
+	static sourceResolverModule = RoutesBoot.buildSourceResolverModule();
+	/** Whether this process is the transform-enabled child that performs the boot. */
+	static isBootProcess() {
+		return process.env[RoutesBoot.transformMarker] === "1";
+	}
+	/**
+	* Re-run this exact CLI invocation under `node --experimental-transform-types`, inheriting stdio so the
+	* child's output and prompts reach the terminal directly.
+	*
+	* A child that never started, or that a signal killed, reports no exit code. Both become `1` — but they
+	* are NAMED on stderr first, because the child printed nothing of its own and a bare `exit 1` after a
+	* silent run reads as "the command found a problem" rather than "the command never ran".
+	*
+	* @returns The child process exit code (1 when it did not report one).
+	*/
+	static reexecUnderTransform() {
+		const result = spawnSync(process.execPath, [
+			"--experimental-transform-types",
+			"--disable-warning=ExperimentalWarning",
+			process.argv[1] ?? "",
+			...process.argv.slice(2)
+		], {
+			stdio: "inherit",
+			env: {
+				...process.env,
+				[RoutesBoot.transformMarker]: "1"
+			}
+		});
+		if (result.error !== void 0) process.stderr.write(`heximon routes --boot: could not start the transform-enabled child (${process.execPath}): ${result.error.message}\n`);
+		else if (result.signal !== null && result.signal !== void 0) process.stderr.write(`heximon routes --boot: the transform-enabled child was killed by ${result.signal}.\n`);
+		return result.status ?? 1;
+	}
+	/** Install the source resolve hook so the imminent boot can import the app's `.ts` source. */
+	static registerSourceResolver() {
+		register(RoutesBoot.sourceResolverModule);
+	}
+	/** Build the inline resolve-hook module — mirrors the compiler's own relative-import resolution. */
+	static buildSourceResolverModule() {
+		const source = [
+			"import { existsSync } from \"node:fs\";",
+			"import { fileURLToPath, pathToFileURL } from \"node:url\";",
+			"export async function resolve(specifier, context, nextResolve) {",
+			"  if ((specifier.startsWith(\"./\") || specifier.startsWith(\"../\")) && context.parentURL) {",
+			"    const base = fileURLToPath(new URL(specifier, context.parentURL));",
+			"    const withoutJs = base.endsWith(\".js\") ? base.slice(0, -3) : base;",
+			"    for (const candidate of [withoutJs + \".ts\", base + \".ts\", base + \"/index.ts\"]) {",
+			"      if (candidate.endsWith(\".ts\") && existsSync(candidate)) {",
+			"        return { url: pathToFileURL(candidate).href, shortCircuit: true };",
+			"      }",
+			"    }",
+			"  }",
+			"  return nextResolve(specifier, context);",
+			"}"
+		].join("\n");
+		return `data:text/javascript,${encodeURIComponent(source)}`;
+	}
+};
+/**
+* `heximon routes` — print the app's unified HTTP route table (inline-mode AND contract-mode routes
+* together), each row carrying the authorization scopes the app enforces on it.
+*
+* By default the table is a COMPILE-TIME artifact: the same from-disk compile `heximon check` runs emits a
+* route census, so the command needs no boot, no `.env`-backed infrastructure, and no running database. The
+* census is deterministic and path-free, so `--out` is a diffable CI artifact — two runs of the same source
+* produce byte-identical JSON, and a dropped authorization scope shows up as a changed `scopes` array.
+*
+* `--boot` selects the legacy in-process boot instead (compile + boot like the test harness, loading `.env`
+* first the way `vp dev` does). It is the fallback for a route the compiler names as unresolved — a
+* cross-package controller, or a contract whose route table is not statically readable.
+*
+* In a PUBLISHED MODULE PACKAGE the compile runs in library mode
+* ({@link ProjectCompileSession.compileLibrary}) and the table is the package's OWN — the paths its factory
+* bakes, over its own accumulated prefixes. The published root's default mount is a manifest fact, not a
+* baked path: a consuming host applies it, or replaces it at its import edge, so it is NOT folded in here.
+*/
+const routesCommand = defineCommand({
+	meta: {
+		name: "routes",
+		description: "Print the app's unified HTTP route table with its authorization scopes."
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		env: {
+			type: "string",
+			description: "The `.env.<mode>` overlay to load first; also the config `$env`. Default development.",
+			default: "development"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit the route table as JSON on stdout instead of a table.",
+			default: false
+		},
+		out: {
+			type: "string",
+			description: "Write the JSON payload to this file instead of stdout, creating missing parent directories — the CI-artifact target."
+		},
+		boot: {
+			type: "boolean",
+			description: "Boot the app in-process and read its live route table, instead of reading the compile-time census.",
+			default: false
+		},
+		src: {
+			type: "string",
+			description: "Source directories to scan, comma-separated. Defaults to `src/`, or `server/` for a Nitro/Nuxt host."
+		},
+		library: CompileModeResolver.flags.library,
+		app: CompileModeResolver.flags.app
+	},
+	async run({ args }) {
+		const asBoot = args.boot;
+		if (asBoot && !RoutesBoot.isBootProcess()) {
+			process.exitCode = RoutesBoot.reexecUnderTransform();
+			return;
+		}
+		const rootDir = resolve(process.cwd(), args.cwd);
+		const asJson = args.json;
+		const jsonOutput = JsonOutputTarget.resolve(args.out, asJson);
+		const resolved = CompileModeResolver.resolve("routes", rootDir, args, SourceDirectories.resolve(rootDir, args.src));
+		if (resolved === void 0) return;
+		if (!asJson) intro(`heximon routes — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
+		if (asBoot) {
+			await RoutesCommand.runBoot(rootDir, args, asJson, jsonOutput);
+			return;
+		}
+		await RoutesCommand.runCompile(rootDir, args, asJson, jsonOutput, resolved.mode);
+	}
+});
+/** Output helpers for {@link routesCommand}: the two read paths, the table / JSON body, and the failure summary. */
+var RoutesCommand = class RoutesCommand {
+	/**
+	* The compile-time read: run the same from-disk compile `heximon check` runs and report the route census
+	* the HTTP plugin emitted. No app boot, so an `OnBootstrap` hook never runs and no infrastructure is
+	* touched. A compile ERROR is reported as a failure — a graph that did not resolve describes no route
+	* surface, and half a census is worse than none for a security diff.
+	*
+	* In library mode the same census comes out of the package's own library emit, so a published module's
+	* route table is readable without composing it into an app. The `requires` a library leaves open for its
+	* host are not diagnostics there, so nothing floods the report.
+	*/
+	static async runCompile(rootDir, args, asJson, jsonOutput, mode = CompileMode.App) {
+		let census;
+		try {
+			const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+			DotenvCascade.loadInto(rootDir, args.env);
+			const session = await ProjectCompileSession.open({
+				rootDir,
+				environment: args.env,
+				...sourceDirectories === void 0 ? {} : { sourceDirectories }
+			});
+			const output = mode === CompileMode.Library ? session.compileLibrary() : session.compile();
+			const failure = output.diagnostics.find((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error);
+			if (failure !== void 0) {
+				RoutesCommand.reportFailure(new Error(failure.message), asJson, jsonOutput);
+				process.exitCode = 1;
+				return;
+			}
+			const file = output.files.find((generated) => generated.path === RouteCensus.fileName);
+			census = (file === void 0 ? void 0 : RouteCensus.parse(file.content)) ?? {
+				routes: [],
+				unresolved: []
+			};
+		} catch (error) {
+			RoutesCommand.reportFailure(error, asJson, jsonOutput);
+			process.exitCode = 1;
+			return;
+		}
+		RoutesCommand.report(census.routes, census.unresolved, asJson, jsonOutput, { libraryMode: mode === CompileMode.Library });
+	}
+	/**
+	* The boot fallback: compile and boot the app in-process (like the test harness), then read its live route
+	* table. A contract-mode row's scopes are read off its merged route descriptor, same as the compile-time
+	* census; only an inline first-party row — whose handler is an opaque `WrappedHandler` with no descriptor to
+	* read — is marked {@link RouteScopeGap.BootDerived} rather than reported as unguarded.
+	*
+	* `@heximon/testing` and `@heximon/http` are imported HERE rather than at module scope: they are the two
+	* heaviest imports in the package and only this opt-in path uses them, so a default `heximon routes` — and
+	* every other `heximon` verb, since citty builds the whole command tree on startup — no longer pays for
+	* them. Deferring the SUBCOMMAND instead does not work: `@bomb.sh/tab`'s citty adapter awaits every
+	* subcommand thunk while building the completion tree, so citty's lazy `Resolvable` form resolves the
+	* module anyway.
+	*/
+	static async runBoot(rootDir, args, asJson, jsonOutput) {
+		let app;
+		let inventory;
+		try {
+			RoutesBoot.registerSourceResolver();
+			const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+			DotenvCascade.loadInto(rootDir, args.env);
+			const config = await ConfigLoader.load(rootDir, args.env);
+			const [{ createTestApp: bootApp }, { RouteInventory }] = await Promise.all([import("@heximon/testing"), import("@heximon/http")]);
+			inventory = RouteInventory;
+			app = await bootApp({
+				root: rootDir,
+				printWarnings: false,
+				...sourceDirectories === void 0 ? {} : { sourceDirectories },
+				bindings: { InternalClient: { fetch: () => Promise.resolve(new Response(null, { status: 404 })) } },
+				...config?.plugins === void 0 ? {} : { plugins: config.plugins },
+				...config?.platform === void 0 ? {} : { platform: config.platform }
+			});
+		} catch (error) {
+			RoutesCommand.reportFailure(error, asJson, jsonOutput);
+			process.exitCode = 1;
+			return;
+		}
+		try {
+			const routes = inventory.describe(app).map(RoutesCommand.toCensusRow);
+			RoutesCommand.report(routes, [], asJson, jsonOutput);
+		} catch (error) {
+			RoutesCommand.reportFailure(error, asJson, jsonOutput);
+			process.exitCode = 1;
+		} finally {
+			try {
+				await app.context.drain({ timeoutMs: 5e3 });
+				await app[Symbol.asyncDispose]();
+			} catch (disposeError) {
+				process.exitCode = 1;
+				if (!asJson) log.warn(`The route table was read, but disposing the booted app failed — a client may still be open: ${disposeError instanceof Error ? disposeError.message : String(disposeError)}`);
+			}
+		}
+	}
+	/**
+	* Map one booted route to a census row. An entry whose {@link RouteInventoryEntry.scopes} is defined (every
+	* contract-mode row) carries it through as-is, `[]` included; an entry with none (an inline first-party row,
+	* which names no descriptor to read) keeps the {@link RouteScopeGap.BootDerived} stamp.
+	*/
+	static toCensusRow(entry) {
+		return {
+			method: entry.method,
+			path: entry.path,
+			source: entry.source,
+			...entry.contract === void 0 ? {} : { contract: entry.contract },
+			...entry.handler === void 0 ? {} : { handler: entry.handler },
+			...entry.scopes === void 0 ? { scopesUnresolved: RouteScopeGap.BootDerived } : { scopes: entry.scopes }
+		};
+	}
+	/**
+	* Print the resolved routes — the JSON payload to its target, and an aligned table unless `--json`.
+	*
+	* @param options - `libraryMode` adds the one fact a package's own table cannot show: the published root's
+	*   default mount is a manifest fact a consuming host applies or replaces, so it is not folded into these
+	*   paths.
+	*/
+	static report(routes, unresolved, asJson, jsonOutput, options = {}) {
+		const written = jsonOutput.emit({
+			ok: true,
+			routes,
+			unresolved
+		});
+		if (!written) process.exitCode = 1;
+		if (asJson) return;
+		if (written && jsonOutput.isFile()) log.success(`Route JSON written to ${jsonOutput.filePath}.`);
+		if (routes.length === 0 && unresolved.length === 0) {
+			outro(options.libraryMode === true ? "No HTTP routes — this package serves none, or its HTTP plugin is not active." : "No HTTP routes — this app serves none, or its HTTP plugin is not active.");
+			return;
+		}
+		if (routes.length > 0) log.message(RouteTableReport.render([...routes].sort(RouteCensus.byRoute)));
+		if (options.libraryMode === true) log.info("These are the paths this package BAKES. Its published root's own `http: { prefix }` is a manifest fact, not a baked path — a composing host applies it, or replaces it at its import edge — so it is not folded in here.");
+		if (unresolved.length === 0) {
+			outro(`${routes.length} route${routes.length === 1 ? "" : "s"}.`);
+			return;
+		}
+		log.warn(RoutesCommand.renderGaps(unresolved));
+		outro(`${routes.length} route${routes.length === 1 ? "" : "s"}; ${unresolved.length} unresolved` + (options.libraryMode === true ? "." : " — re-run with --boot to enumerate them."));
+	}
+	/**
+	* Report a compile / boot failure: `{ ok: false, error }` to the JSON target, and a clack error + outro
+	* unless `--json`. The failure payload goes to `--out` too, so re-running replaces the previous artifact
+	* rather than leaving a stale success; a failed write is treated exactly as on the success path.
+	*/
+	static reportFailure(error, asJson, jsonOutput) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (!jsonOutput.emit({
+			ok: false,
+			error: message
+		})) process.exitCode = 1;
+		if (asJson) return;
+		log.error(`Could not read the app's routes:\n${message}`);
+		outro("No route table to show.");
+	}
+	/**
+	* The unresolved-gap block: one line per controller (or package) whose routes the census could not name.
+	* A composed package whose manifest section IS readable contributes rows instead, so nothing here is a
+	* placeholder for a route the table already shows.
+	*/
+	static renderGaps(unresolved) {
+		return ["Routes the compile-time census could not resolve:", ...unresolved.map((gap) => {
+			const subject = gap.controller ?? gap.package ?? "(unknown)";
+			const detail = [
+				gap.contract === void 0 ? void 0 : `contract ${gap.contract}`,
+				gap.handler === void 0 ? void 0 : `route "${gap.handler}"`,
+				gap.package === void 0 || gap.controller === void 0 ? void 0 : `from ${gap.package}`
+			].filter((part) => part !== void 0);
+			return `${subject}${detail.length === 0 ? "" : ` (${detail.join(", ")})`} — ${gap.kind}`;
+		})].join("\n");
+	}
+};
+//#endregion
+//#region src/workflow-status-report.ts
+/** How one workflow's current step graph relates to the committed baseline gate. */
+const WorkflowBaselineState = {
+	/** The committed snapshot matches the current graph — the gate is armed and clean. */
+	InSync: "in-sync",
+	/**
+	* The committed sites are an exact prefix of the current ones — the append-only change the upgrade check
+	* accepts. In-flight runs replay through the recorded prefix unchanged.
+	*/
+	Appended: "appended",
+	/** The committed snapshot differs — `heximon check` gates the deploy until the change is re-acknowledged. */
+	Diverged: "diverged",
+	/** No committed snapshot for this workflow — the gate is unarmed until `heximon check --update` runs. */
+	Unarmed: "unarmed"
+};
+/**
+* Parses, classifies, and renders the durable-workflow upgrade-safety report — pure functions over the emitted
+* baseline, the committed baseline, and the (optional) Cloudflare live-fleet inventories.
+*/
+var WorkflowStatusReport = class WorkflowStatusReport {
+	/** The workflow plugin's section key inside the committed baseline. */
+	static sectionKey = "workflow";
+	/** Where the workflow plugin emits its current baseline section inside the `.heximon` output directory. */
+	static generatedBaselinePath = UpgradeBaselineFile.generatedPathFor(WorkflowStatusReport.sectionKey);
+	/** The committed baseline's file name at the app root (`heximon check --update` writes it). */
+	static committedBaselineFileName = UpgradeBaselineFile.fileName;
+	/** How many stale instance ids the terminal report lists per workflow before truncating. */
+	static maxRenderedStaleInstances = 10;
+	/**
+	* Parse the COMMITTED baseline file's text — the multi-section envelope at the app root — down to the
+	* workflow section. `undefined` when it is malformed or carries an envelope version this build cannot read.
+	*/
+	static parseBaselineText(text) {
+		return WorkflowStatusReport.parseJson(text, (value) => WorkflowStatusReport.parseSection(UpgradeBaselineFile.section(value, WorkflowStatusReport.sectionKey)));
+	}
+	/**
+	* Parse a freshly-EMITTED section artifact's text. The generated file is the bare section, with no envelope
+	* around it — a plugin emits only what it owns and `heximon check --update` composes the envelope.
+	*/
+	static parseGeneratedText(text) {
+		return WorkflowStatusReport.parseJson(text, (value) => WorkflowStatusReport.parseSection(value));
+	}
+	/** `JSON.parse` guarded, then handed to `parse` — malformed text reads as no baseline, never a throw. */
+	static parseJson(text, parse) {
+		let value;
+		try {
+			value = JSON.parse(text);
+		} catch {
+			return;
+		}
+		return parse(value);
+	}
+	/** Classify every current workflow against the committed baseline, keyed by `resourceName`. */
+	static classify(current, committed) {
+		const committedByName = /* @__PURE__ */ new Map();
+		for (const snapshot of committed?.workflows ?? []) committedByName.set(snapshot.resourceName, snapshot);
+		return current.map((workflow) => ({
+			resourceName: workflow.resourceName,
+			fingerprint: workflow.fingerprint,
+			stepCount: workflow.sites.length,
+			state: WorkflowStatusReport.stateFor(workflow, committedByName.get(workflow.resourceName))
+		}));
+	}
+	/** Render one workflow's status line — identity, fingerprint, step count, and its baseline state. */
+	static renderEntry(entry) {
+		const fingerprint = entry.fingerprint === "" ? "(not analyzable)" : entry.fingerprint;
+		const steps = `${entry.stepCount} durable step${entry.stepCount === 1 ? "" : "s"}`;
+		return `${entry.resourceName} — fingerprint ${fingerprint} · ${steps} — ${WorkflowStatusReport.stateDescription(entry.state)}`;
+	}
+	/** Render one workflow's live-fleet inventory block (multi-line, no trailing newline). */
+	static renderInventory(inventory) {
+		if (!inventory.comparable) return `live instances: ${inventory.liveInstanceCount} — the current graph is not analyzable, so staleness cannot be compared.`;
+		const lines = [`live instances: ${inventory.liveInstanceCount} · stale (predate the current graph): ${inventory.staleInstances.length}`];
+		const listed = inventory.staleInstances.slice(0, WorkflowStatusReport.maxRenderedStaleInstances);
+		for (const instance of listed) lines.push(`  ${instance.id} — ${instance.status}, created ${instance.createdOn}`);
+		const truncated = inventory.staleInstances.length - listed.length;
+		if (truncated > 0) lines.push(`  … and ${truncated} more stale instance${truncated === 1 ? "" : "s"}.`);
+		return lines.join("\n");
+	}
+	/** The outro summary line: total workflows plus any appended / diverged / unarmed / failure counts. */
+	static renderSummary(entries, enumerationFailed) {
+		const count = `${entries.length} workflow${entries.length === 1 ? "" : "s"}`;
+		const diverged = entries.filter((entry) => entry.state === WorkflowBaselineState.Diverged).length;
+		const unarmed = entries.filter((entry) => entry.state === WorkflowBaselineState.Unarmed).length;
+		const appended = entries.filter((entry) => entry.state === WorkflowBaselineState.Appended).length;
+		const parts = [];
+		if (diverged > 0) parts.push(`${diverged} diverged`);
+		if (appended > 0) parts.push(`${appended} append-only`);
+		if (unarmed > 0) parts.push(`${unarmed} unarmed`);
+		if (enumerationFailed) parts.push("live-instance enumeration incomplete");
+		return parts.length === 0 ? `${count} — baseline armed & in sync.` : `${count} — ${parts.join(", ")}.`;
+	}
+	/**
+	* The `--format json` body: the per-workflow entries with their inventories (`null` when skipped).
+	*
+	* @param options - The classified entries, their inventories, and any upgrade-verdict diagnostics the
+	*   compile raised. An upgrade verdict rides the report rather than replacing it — it is the outcome of a
+	*   complete analysis — but it still makes the run report `ok: false`.
+	*/
+	static toJson(options) {
+		const upgradeDiagnostics = options.upgradeDiagnostics ?? [];
+		return {
+			ok: options.enumerationErrors.size === 0 && upgradeDiagnostics.length === 0,
+			workflows: options.entries.map((entry) => {
+				const enumerationError = options.enumerationErrors.get(entry.resourceName);
+				return {
+					...entry,
+					inventory: options.inventories.get(entry.resourceName) ?? null,
+					...enumerationError === void 0 ? {} : { enumerationError }
+				};
+			}),
+			cloudflare: {
+				enumerated: options.cloudflareSkipped === void 0,
+				...options.cloudflareSkipped === void 0 ? {} : { skipped: options.cloudflareSkipped }
+			},
+			...upgradeDiagnostics.length === 0 ? {} : { diagnostics: upgradeDiagnostics }
+		};
+	}
+	/**
+	* The `--format json` body for a run that produced NO per-workflow report — a workflow-free app, a failed
+	* compile, or an unreadable committed baseline. Same shape as {@link toJson}, so one reader covers both.
+	*
+	* @param options - Why there is no report, and whether the run itself succeeded.
+	*/
+	static noReportJson(options) {
+		return {
+			ok: options.ok,
+			workflows: [],
+			cloudflare: {
+				enumerated: false,
+				skipped: options.reason
+			},
+			...options.error === void 0 ? {} : { error: options.error },
+			...options.diagnostics === void 0 ? {} : { diagnostics: options.diagnostics }
+		};
+	}
+	/**
+	* One workflow's state: unarmed without a committed snapshot, in-sync on exact graph equality, appended
+	* when the recorded sites are an exact prefix of the current ones, else diverged.
+	*/
+	static stateFor(current, committed) {
+		if (committed === void 0) return WorkflowBaselineState.Unarmed;
+		if (WorkflowStatusReport.snapshotEquals(current, committed)) return WorkflowBaselineState.InSync;
+		return WorkflowStatusReport.isAppendOnly(committed, current) ? WorkflowBaselineState.Appended : WorkflowBaselineState.Diverged;
+	}
+	/**
+	* Whether `current` only adds steps after every recorded site of `committed`. A recorded site with no
+	* `name` is a dynamic step this report cannot compare, so it never reads as an append.
+	*/
+	static isAppendOnly(committed, current) {
+		if (committed.sites.length >= current.sites.length) return false;
+		return committed.sites.every((site, index) => {
+			const other = current.sites[index];
+			return site.name !== void 0 && other !== void 0 && site.kind === other.kind && site.name === other.name;
+		});
+	}
+	/** Exact graph equality: same fingerprint AND the same ordered site list (kind + name per site). */
+	static snapshotEquals(left, right) {
+		if (left.fingerprint !== right.fingerprint || left.sites.length !== right.sites.length) return false;
+		return left.sites.every((site, index) => {
+			const other = right.sites[index];
+			return other !== void 0 && site.kind === other.kind && site.name === other.name;
+		});
+	}
+	/** The human text for one baseline state. */
+	static stateDescription(state) {
+		switch (state) {
+			case WorkflowBaselineState.InSync: return "armed & in sync";
+			case WorkflowBaselineState.Appended: return "step(s) APPENDED since the committed baseline (append-only — in-flight runs replay unaffected; run `heximon check --update` to record the new graph)";
+			case WorkflowBaselineState.Diverged: return "DIVERGED from the committed baseline (deploy gated — heximon check will fail)";
+			case WorkflowBaselineState.Unarmed: return "no committed baseline (gate unarmed — run `heximon check --update`)";
+		}
+	}
+	/**
+	* Structural validation of a parsed workflow SECTION — a wrong shape reads as no baseline.
+	*
+	* Public because a caller that already pulled the section out of the envelope needs to tell an ABSENT
+	* section (nothing acknowledged yet) from an unreadable one (an acknowledgement this build cannot read).
+	*/
+	static parseSection(section) {
+		if (typeof section !== "object" || section === null) return;
+		const record = section;
+		if (!Array.isArray(record["workflows"])) return;
+		const workflows = [];
+		for (const entry of record["workflows"]) {
+			const snapshot = WorkflowStatusReport.parseSnapshot(entry);
+			if (snapshot === void 0) return;
+			workflows.push(snapshot);
+		}
+		return { workflows };
+	}
+	static parseSnapshot(entry) {
+		if (typeof entry !== "object" || entry === null) return;
+		const record = entry;
+		const resourceName = record["resourceName"];
+		const fingerprint = record["fingerprint"];
+		if (typeof resourceName !== "string" || typeof fingerprint !== "string" || !Array.isArray(record["sites"])) return;
+		const sites = [];
+		for (const rawSite of record["sites"]) {
+			const site = WorkflowStatusReport.parseSite(rawSite);
+			if (site === void 0) return;
+			sites.push(site);
+		}
+		return {
+			resourceName,
+			fingerprint,
+			sites
+		};
+	}
+	static parseSite(rawSite) {
+		if (typeof rawSite !== "object" || rawSite === null) return;
+		const record = rawSite;
+		const kind = record["kind"];
+		if (typeof kind !== "string") return;
+		const name = record["name"];
+		return typeof name === "string" ? {
+			kind,
+			name
+		} : { kind };
+	}
+};
+//#endregion
+//#region src/workflows-command.ts
+/**
+* How the committed `heximon.upgrade.json` read resolved. Three-valued on purpose: folding "unreadable" into
+* "absent" would report every workflow as `unarmed` and exit 0, steering the operator at
+* `heximon check --update` — the one command that would overwrite the gate a diverged app depends on.
+*/
+const CommittedBaselineState = {
+	/** No committed file at the app root — every workflow's gate is legitimately unarmed. */
+	Absent: "absent",
+	/** The file was read and its workflow section parsed. */
+	Read: "read",
+	/** The file exists but could not be read or parsed — this build cannot say what was acknowledged. */
+	Unreadable: "unreadable"
+};
+/**
+* Loads the Cloudflare workflow inspector from the APP's own `@heximon/cloudflare` install.
+*
+* Resolved via `createRequire` at the app's package.json (the same pattern as `@heximon/deploy`'s
+* `PlatformDeployLoader`), so the CLI takes no dependency on the platform package.
+*/
+var CloudflareInspectorLoader = class {
+	/**
+	* @param rootDir - The app root whose `@heximon/cloudflare` install is resolved from.
+	* @param credentials - The REST credentials the instances client authenticates with.
+	* @returns The inspector, or `undefined` when the package is absent or exports neither class.
+	*/
+	static async load(rootDir, credentials) {
+		try {
+			const resolved = createRequire(join(rootDir, "package.json")).resolve("@heximon/cloudflare");
+			const loaded = await import(pathToFileURL(resolved).href);
+			const InstancesClient = loaded["CloudflareWorkflowInstancesClient"];
+			const Inspector = loaded["CloudflareWorkflowInspector"];
+			if (InstancesClient === void 0 || Inspector === void 0) return;
+			return new Inspector(new InstancesClient(credentials));
+		} catch {
+			return;
+		}
+	}
+};
+/**
+* `heximon workflows` — the durable-workflow upgrade-safety report. It runs the same from-disk compile as
+* `heximon check`, reads the freshly-emitted per-workflow step-graph baseline, and reports each workflow's
+* state against the committed `heximon.upgrade.json` gate. With Cloudflare credentials in the environment
+* it also enumerates the live fleet and names the stale instances a step-graph change would endanger.
+*/
+const workflowsCommand = defineCommand({
+	meta: {
+		name: "workflows",
+		description: "Compile the project and report each durable workflow's upgrade-safety state (baseline + live instances)."
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		format: {
+			type: "string",
+			description: "Output format: 'pretty' (default) or 'json'.",
+			default: "pretty"
+		},
+		env: {
+			type: "string",
+			description: "The heximon.config.ts `$env` name to resolve (matches `vp dev`).",
+			default: "development"
+		},
+		src: {
+			type: "string",
+			description: "Source directories to scan, comma-separated. Defaults to `src/`, or `server/` for a Nitro/Nuxt host."
+		}
+	},
+	async run({ args }) {
+		const rootDir = resolve(process.cwd(), args.cwd);
+		const asJson = args.format === "json";
+		const sourceDirectories = SourceDirectories.resolve(rootDir, args.src);
+		if (!asJson) intro(`heximon workflows — ${basename(rootDir)}`);
+		const output = (await ProjectCompileSession.open({
+			rootDir,
+			environment: args.env,
+			...sourceDirectories === void 0 ? {} : { sourceDirectories }
+		})).compile();
+		const errors = output.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error);
+		const upgradeErrors = errors.filter((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code));
+		const blockingErrors = errors.filter((diagnostic) => !UpgradeBaseline.isBreaking(diagnostic.code));
+		if (blockingErrors.length > 0) {
+			if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.noReportJson({
+				ok: false,
+				reason: "the compile failed — no workflow report to enumerate against.",
+				error: `Compile failed — ${blockingErrors.length} error${blockingErrors.length === 1 ? "" : "s"}.`,
+				diagnostics: blockingErrors
+			}))}\n`);
+			else {
+				CompileDiagnostics.renderToStderr(rootDir, blockingErrors);
+				outro(`Compile failed — ${blockingErrors.length} error${blockingErrors.length === 1 ? "" : "s"}; no workflow report.`);
+			}
+			process.exitCode = 1;
+			return;
+		}
+		const generated = output.files.find((file) => file.path === WorkflowStatusReport.generatedBaselinePath);
+		const current = generated === void 0 ? void 0 : WorkflowStatusReport.parseGeneratedText(generated.content);
+		if (current === void 0 || current.workflows.length === 0) {
+			if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.noReportJson({
+				ok: true,
+				reason: "this app declares no workflows — nothing to enumerate."
+			}))}\n`);
+			else outro("No workflows in this app.");
+			return;
+		}
+		const committed = WorkflowsCommand.readCommittedBaseline(rootDir);
+		if (committed.state === CommittedBaselineState.Unreadable) {
+			const message = `${WorkflowStatusReport.committedBaselineFileName} exists but could not be read (${committed.reason ?? "unknown reason"}), so no workflow's upgrade-safety state is known — this is NOT an unarmed gate. Restore the committed file (e.g. from git) before deploying; \`heximon check --update\` would overwrite it with the current surface.`;
+			if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.noReportJson({
+				ok: false,
+				reason: "the committed upgrade-safety baseline is unreadable — nothing to compare against.",
+				error: message
+			}))}\n`);
+			else {
+				log.error(message);
+				outro("Upgrade-safety baseline unreadable — no workflow report.");
+			}
+			process.exitCode = 1;
+			return;
+		}
+		const entries = WorkflowStatusReport.classify(current.workflows, committed.document);
+		const inventories = /* @__PURE__ */ new Map();
+		const enumerationErrors = /* @__PURE__ */ new Map();
+		let cloudflareSkipped;
+		const accountId = process.env["CLOUDFLARE_ACCOUNT_ID"];
+		const apiToken = process.env["CLOUDFLARE_API_TOKEN"];
+		if (accountId === void 0 || accountId === "" || apiToken === void 0 || apiToken === "") cloudflareSkipped = "CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN are not both set — Cloudflare live-instance enumeration skipped.";
+		else {
+			const inspector = await CloudflareInspectorLoader.load(rootDir, {
+				accountId,
+				apiToken
+			});
+			if (inspector === void 0) cloudflareSkipped = "@heximon/cloudflare is not installed in this app — Cloudflare live-instance enumeration skipped.";
+			else for (const entry of entries) try {
+				inventories.set(entry.resourceName, await inspector.inspect({
+					workflowName: entry.resourceName,
+					currentFingerprint: entry.fingerprint
+				}));
+			} catch (error) {
+				enumerationErrors.set(entry.resourceName, error instanceof Error ? error.message : String(error));
+			}
+		}
+		if (asJson) process.stdout.write(`${JSON.stringify(WorkflowStatusReport.toJson({
+			entries,
+			inventories,
+			enumerationErrors,
+			cloudflareSkipped,
+			...upgradeErrors.length === 0 ? {} : { upgradeDiagnostics: upgradeErrors }
+		}))}\n`);
+		else {
+			WorkflowsCommand.report(entries, inventories, enumerationErrors, cloudflareSkipped);
+			if (upgradeErrors.length > 0) CompileDiagnostics.renderToStderr(rootDir, upgradeErrors);
+		}
+		if (enumerationErrors.size > 0 || upgradeErrors.length > 0) process.exitCode = 1;
+	}
+});
+/** Output helpers for {@link workflowsCommand}: the committed-baseline read and the pretty report. */
+var WorkflowsCommand = class {
+	/**
+	* Read the committed `heximon.upgrade.json`, keeping "absent" and "unreadable" apart.
+	*
+	* An absent file, and a present file that simply carries no `workflow` section yet, both mean nothing has
+	* been acknowledged — the honest unarmed state. A file that exists but cannot be parsed, carries an
+	* envelope version this build does not read, or holds a `workflow` section of the wrong shape, is a gate
+	* whose contents this build cannot see; that must never read as "never baselined".
+	*/
+	static readCommittedBaseline(rootDir) {
+		const path = join(rootDir, WorkflowStatusReport.committedBaselineFileName);
+		let text;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch (error) {
+			if (error.code === "ENOENT") return { state: CommittedBaselineState.Absent };
+			return {
+				state: CommittedBaselineState.Unreadable,
+				reason: error instanceof Error ? error.message : String(error)
+			};
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			return {
+				state: CommittedBaselineState.Unreadable,
+				reason: `not valid JSON — ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+		if (!UpgradeBaselineFile.envelopeReadable(parsed)) return {
+			state: CommittedBaselineState.Unreadable,
+			reason: `its envelope is not version ${UpgradeBaselineFile.version} — written by a different heximon, or hand-edited`
+		};
+		if (!UpgradeBaselineFile.sectionPresent(parsed, WorkflowStatusReport.sectionKey)) return { state: CommittedBaselineState.Read };
+		const document = WorkflowStatusReport.parseSection(UpgradeBaselineFile.section(parsed, WorkflowStatusReport.sectionKey));
+		return document === void 0 ? {
+			state: CommittedBaselineState.Unreadable,
+			reason: `its \`${WorkflowStatusReport.sectionKey}\` section does not have the recorded shape`
+		} : {
+			state: CommittedBaselineState.Read,
+			document
+		};
+	}
+	/** Print the per-workflow report wrapped in clack framing: one status line + inventory block each. */
+	static report(entries, inventories, enumerationErrors, cloudflareSkipped) {
+		for (const entry of entries) {
+			const line = WorkflowStatusReport.renderEntry(entry);
+			if (entry.state === WorkflowBaselineState.Diverged) log.error(line);
+			else if (entry.state === WorkflowBaselineState.InSync) log.success(line);
+			else log.warn(line);
+			const inventory = inventories.get(entry.resourceName);
+			if (inventory !== void 0) log.message(WorkflowStatusReport.renderInventory(inventory));
+			const enumerationError = enumerationErrors.get(entry.resourceName);
+			if (enumerationError !== void 0) log.error(`Cloudflare enumeration failed for ${entry.resourceName}: ${enumerationError}`);
+		}
+		if (cloudflareSkipped !== void 0) log.info(cloudflareSkipped);
+		outro(WorkflowStatusReport.renderSummary(entries, enumerationErrors.size > 0));
+	}
+};
+//#endregion
+//#region src/bin.ts
+const main = defineCommand({
+	meta: {
+		name: "heximon",
+		description: "The Heximon CLI.",
+		version: CreateDefaults.cliVersion()
+	},
+	subCommands: {
+		create: createCommand,
+		deploy: deployCommand,
+		check: checkCommand,
+		routes: routesCommand,
+		graph: graphCommand,
+		doctor: doctorCommand,
+		provision: provisionCommand,
+		migrations: migrationsCommand,
+		workflows: workflowsCommand,
+		skills: skillsCommand
+	}
+});
+await tab(main);
+await runMain(main);
+//#endregion
+export {};