@happyvertical/smrt-cli 0.53.2 → 0.53.4

package/dist/cli-BRFsobey.js

@@ -0,0 +1,1275 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { accessSync, constants, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { acquireWriterLease, createProviderReadinessProbe, findInstalledPackage, prepareApplicationStateRoot, readActiveWriterLease, resolveApplicationId, resolveApplicationStateRoot, runtimeConfigurationFingerprint, withOperationLock } from "@happyvertical/smrt-app-runtime";
+import { spawn, spawnSync } from "node:child_process";
+import { platform } from "node:os";
+import { randomBytes } from "node:crypto";
+//#region src/app/errors.ts
+/**
+* Shared error helpers for the `smrt app` command group.
+*/
+/** Read a Node `code` from an unknown thrown value. */
+function errorCode(error) {
+	return error && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : void 0;
+}
+/** Error carrying a process exit code from a failed child command. */
+var AppCommandError = class extends Error {
+	exitCode;
+	constructor(message, exitCode = 1, options) {
+		super(message);
+		this.name = "AppCommandError";
+		this.exitCode = exitCode;
+		if (options && "cause" in options) Object.defineProperty(this, "cause", {
+			value: options.cause,
+			configurable: true
+		});
+	}
+};
+/** Minimum length before an environment value is treated as redactable. */
+var MIN_REDACTED_VALUE_LENGTH = 8;
+/** Environment names whose values must never reach operator output. */
+var SECRET_ENVIRONMENT_NAME = /(?:^|_)(?:DATABASE_URL|URL|DSN|TOKEN|SECRET|PASSWORD|PASSWD|KEY|CREDENTIALS?|AUTH)(?:_|$)/i;
+/**
+* Remove secret material from an operator-facing message.
+*
+* Errors raised by drivers, config loaders, and providers routinely echo a
+* connection string, credential, or bootstrap token. Redaction covers:
+* literal values of secret-named environment variables, URL userinfo,
+* `token=`/`password=`/`secret=` query values, and bearer tokens.
+*/
+function redactSecrets(message, environment = process.env) {
+	let redacted = message;
+	const values = Object.entries(environment).filter(([name, value]) => typeof value === "string" && value.length >= MIN_REDACTED_VALUE_LENGTH && SECRET_ENVIRONMENT_NAME.test(name)).map(([, value]) => value).sort((left, right) => right.length - left.length);
+	for (const value of values) redacted = redacted.replaceAll(value, "[redacted]");
+	return redacted.replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@:'"]*(?::[^\s/@'"]*)?@/gi, "$1[redacted]@").replace(/([?&;](?:token|password|secret|key|access_token)=)[^&\s"'<>]+/gi, "$1[redacted]").replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/g, "Bearer [redacted]");
+}
+//#endregion
+//#region src/app/identity.ts
+/**
+* Application identity, private state root, and operator-artifact path
+* custody for the `smrt app` command group.
+*
+* Identity, configuration fingerprint, and the private state root are
+* `@happyvertical/smrt-app-runtime`'s single implementation (re-exported
+* here), so the running web process and these commands can never derive
+* different identities or lock domains. Operator-artifact path custody is
+* CLI-only and stays here.
+*/
+function isInside(parent, child) {
+	const relative = child.slice(parent.length);
+	return child === parent || child.startsWith(parent) && (relative.startsWith("/") || relative.startsWith("\\"));
+}
+/**
+* Resolve an operator-selected artifact through its nearest existing ancestor
+* and reject paths that could place application data in or over the checkout.
+*/
+function assertExternalArtifactPath(options) {
+	const canonicalSource = realpathSync(resolve(options.sourceRoot));
+	const missingSegments = [];
+	let existingAncestor = resolve(options.path);
+	while (!existsSync(existingAncestor)) {
+		const parent = dirname(existingAncestor);
+		if (parent === existingAncestor) break;
+		missingSegments.unshift(basename(existingAncestor));
+		existingAncestor = parent;
+	}
+	const canonicalPath = resolve(realpathSync(existingAncestor), ...missingSegments);
+	if (isInside(canonicalSource, canonicalPath) || isInside(canonicalPath, canonicalSource)) throw new Error(`${options.label || "Artifact"} must remain outside the source tree.`);
+	return canonicalPath;
+}
+//#endregion
+//#region src/app/runtime.ts
+/**
+* Shared per-invocation context for the `smrt app` command group: source
+* root, application identity, I/O, child-process runners, and the
+* profile-aware runtime environment.
+*/
+/** Locate this package's root (`…/smrt-cli`) from the running module. */
+function cliPackageRoot() {
+	let directory = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 5; depth += 1) {
+		const candidate = join(directory, "package.json");
+		if (existsSync(candidate)) try {
+			if (JSON.parse(readFileSync(candidate, "utf8")).name === "@happyvertical/smrt-cli") return directory;
+		} catch {}
+		const parent = dirname(directory);
+		if (parent === directory) break;
+		directory = parent;
+	}
+	throw new Error("The smrt CLI package root could not be located.");
+}
+/** Absolute path of the `smrt` executable shipped with this package. */
+function cliExecutablePath() {
+	return join(cliPackageRoot(), "bin", "smrt.js");
+}
+/** Absolute path of the web launcher `start` spawns. */
+function webLauncherPath() {
+	return join(cliPackageRoot(), "bin", "smrt-web.mjs");
+}
+/** Load `<sourceRoot>/.env` without overriding the shell; a missing file is fine. */
+function loadSourceEnvironment(sourceRoot) {
+	try {
+		process.loadEnvFile(join(sourceRoot, ".env"));
+	} catch (error) {
+		if (errorCode(error) !== "ENOENT") throw error;
+	}
+}
+function runChild(sourceRoot, binary, args, options = {}) {
+	const result = spawnSync(binary, args, {
+		cwd: sourceRoot,
+		env: options.env || process.env,
+		encoding: "utf8",
+		shell: options.shell || false,
+		stdio: options.capture ? [
+			"ignore",
+			"pipe",
+			"pipe"
+		] : "inherit"
+	});
+	if (!options.allowFailure && (result.error || result.status !== 0)) throw new AppCommandError(`${options.label || binary} failed with exit code ${result.status ?? 1}.`, result.status ?? 1, { cause: result.error });
+	return result;
+}
+/** Default package-manager runner: honours a pnpm `npm_execpath`. */
+function createPackageManagerRunner(sourceRoot) {
+	return (args, options = {}) => {
+		const npmExecPath = process.env.npm_execpath;
+		const pnpmExecPath = npmExecPath && basename(npmExecPath).toLowerCase().startsWith("pnpm") ? npmExecPath : null;
+		return pnpmExecPath ? runChild(sourceRoot, process.execPath, [pnpmExecPath, ...args], options) : runChild(sourceRoot, platform() === "win32" ? "pnpm.cmd" : "pnpm", args, {
+			...options,
+			shell: platform() === "win32"
+		});
+	};
+}
+/** Default self-runner: this package's own `smrt` executable. */
+function createSmrtRunner(sourceRoot) {
+	return (args, options = {}) => runChild(sourceRoot, process.execPath, [cliExecutablePath(), ...args], options);
+}
+/** Default browser opener (`SMRT_OPEN_STUB` writes the URL to a file instead). */
+function createBrowserOpener(sourceRoot) {
+	return (url) => {
+		if (process.env.SMRT_OPEN_STUB) {
+			writeFileSync(resolve(process.env.SMRT_OPEN_STUB), `${url}\n`);
+			return;
+		}
+		const [binary, args] = platform() === "darwin" ? ["open", [url]] : platform() === "win32" ? ["cmd", [
+			"/c",
+			"start",
+			"",
+			url
+		]] : ["xdg-open", [url]];
+		runChild(sourceRoot, binary, args);
+	};
+}
+/** Default runtime resolver: reload `smrt.config` without the cache. */
+async function resolveConfiguredRuntime(sourceRoot) {
+	const { loadConfig, resolveConfiguredApplicationRuntime } = await import("@happyvertical/smrt-config");
+	await loadConfig({
+		cache: false,
+		searchFrom: sourceRoot
+	});
+	return resolveConfiguredApplicationRuntime();
+}
+/** Build the default dependency set for `sourceRoot`. */
+async function defaultDependencies(sourceRoot) {
+	return {
+		runtime: await import("@happyvertical/smrt-app-runtime"),
+		resolveRuntime: resolveConfiguredRuntime,
+		runPackageManager: createPackageManagerRunner(sourceRoot),
+		runSmrt: createSmrtRunner(sourceRoot),
+		openBrowser: createBrowserOpener(sourceRoot),
+		fetch: globalThis.fetch.bind(globalThis),
+		sleep: (milliseconds) => new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)),
+		signal: (pid, signal) => {
+			process.kill(pid, signal);
+		}
+	};
+}
+/** Resolve the application id from `<sourceRoot>/package.json` and `SMRT_APP_ID`. */
+function resolveContextApplicationId(sourceRoot) {
+	return resolveApplicationId({
+		sourceRoot,
+		packageName: JSON.parse(readFileSync(join(sourceRoot, "package.json"), "utf8")).name,
+		explicitId: process.env.SMRT_APP_ID
+	});
+}
+/** Create or verify the private state root for this invocation. */
+function preparedStateRoot(context) {
+	return prepareApplicationStateRoot({
+		appId: context.appId,
+		dataDirectory: process.env.SMRT_DATA_DIR,
+		sourceRoot: context.sourceRoot
+	});
+}
+/** Compute the environment a web/migration child of this app runs with. */
+function runtimeEnvironment(context, runtime) {
+	const env = {
+		...process.env,
+		SMRT_APP_ID: context.appId,
+		SMRT_RUNTIME_PROFILE: runtime.profile,
+		HOST: runtime.profile === "local" ? "127.0.0.1" : process.env.HOST || "0.0.0.0",
+		PORT: process.env.PORT || "5173"
+	};
+	if (runtime.profile === "local") {
+		const paths = context.deps.runtime.resolveLocalRuntimePaths({
+			appId: context.appId,
+			dataDirectory: process.env.SMRT_DATA_DIR,
+			sourceRoot: context.sourceRoot
+		});
+		env.DATABASE_TYPE = "sqlite";
+		env.DATABASE_URL = paths.database;
+		env.SMRT_ASSETS_DIR = paths.assets;
+		return {
+			env,
+			paths,
+			assetRoot: paths.assets
+		};
+	}
+	if (!process.env.DATABASE_URL) throw new Error(`${runtime.profile} requires DATABASE_URL; copy the matching env example and configure providers.`);
+	env.DATABASE_TYPE = "postgres";
+	let assetRoot = null;
+	if (runtime.providers.assets.provider === "local-files") {
+		if (!process.env.SMRT_ASSETS_DIR || !isAbsolute(process.env.SMRT_ASSETS_DIR)) throw new Error("Filesystem-backed deployed profiles require an absolute SMRT_ASSETS_DIR outside the source tree.");
+		assetRoot = assertExternalArtifactPath({
+			sourceRoot: context.sourceRoot,
+			path: process.env.SMRT_ASSETS_DIR,
+			label: "Asset storage root"
+		});
+		env.SMRT_ASSETS_DIR = assetRoot;
+	}
+	return {
+		env,
+		paths: null,
+		assetRoot
+	};
+}
+//#endregion
+//#region src/app/launchers.ts
+/**
+* Process wrappers: explicit schema preparation (`migrate`), deployed job
+* workers (`worker`), and the Vite launcher (`dev`, `build`, `vite`).
+*
+* Ported from the template's `scripts/smrt-prepare-migration.mjs`,
+* `scripts/smrt-worker.mjs`, `scripts/smrt-vite.mjs`, and
+* `scripts/smrt-mcp-apps.mjs`.
+*/
+/**
+* Prepare the schema explicitly: under the operation lock, refuse while a
+* local writer is live, establish local storage custody without creating
+* schema or bootstrap records, then run `smrt db:migrate`.
+*/
+async function prepareMigration(context) {
+	const runtime = await context.deps.resolveRuntime(context.sourceRoot);
+	const stateRoot = preparedStateRoot(context);
+	await withOperationLock(stateRoot, "db:migrate", async () => {
+		const env = {
+			...process.env,
+			SMRT_APP_ID: context.appId
+		};
+		if (runtime.profile === "local") {
+			if (readActiveWriterLease(stateRoot)) throw new Error("Stop the local application before preparing its schema.");
+			const paths = context.deps.runtime.resolveLocalRuntimePaths({
+				appId: context.appId,
+				dataDirectory: process.env.SMRT_DATA_DIR,
+				sourceRoot: context.sourceRoot
+			});
+			await context.deps.runtime.prepareLocalDatabaseStorage({
+				appId: context.appId,
+				dataDirectory: process.env.SMRT_DATA_DIR,
+				sourceRoot: context.sourceRoot
+			});
+			env.DATABASE_TYPE = "sqlite";
+			env.DATABASE_URL = paths.database;
+			env.SMRT_ASSETS_DIR = paths.assets;
+		}
+		const result = context.deps.runSmrt(["db:migrate"], {
+			env,
+			allowFailure: true
+		});
+		if (result.error || result.status !== 0) throw new AppCommandError("s-m-r-t database migration failed.", result.status ?? 1, { cause: result.error });
+	});
+	return 0;
+}
+var WORKER_USAGE = "Usage: smrt app worker [task|schedule]";
+/** Parse `smrt app worker [kind]`, refusing anything but `task`/`schedule`. */
+function parseWorkerKind(args) {
+	if (args.length > 1) throw new AppCommandError(WORKER_USAGE, 2);
+	const kind = args[0] ?? "task";
+	if (kind !== "task" && kind !== "schedule") throw new AppCommandError(WORKER_USAGE, 2);
+	return kind;
+}
+/**
+* Start a deployed job worker. Resolves once the runner is started; the
+* process stays alive until SIGINT/SIGTERM closes the runtime.
+*/
+async function runWorker(context, args) {
+	const kind = parseWorkerKind(args);
+	const configured = await context.deps.resolveRuntime(context.sourceRoot);
+	if (configured.profile === "local") throw new Error("Local jobs run inline or embedded; a separate worker requires self-hosted or cloud.");
+	if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL is required.");
+	const registration = join(context.sourceRoot, ".smrt", "runtime", "register.js");
+	if (!existsSync(registration)) throw new Error("Missing .smrt/runtime/register.js: run pnpm build before starting a worker.");
+	await import(pathToFileURL(registration).href);
+	const probe = (component) => createProviderReadinessProbe(component, {
+		profile: configured.profile,
+		provider: configured.providers[component].provider
+	}, { sourceRoot: context.sourceRoot });
+	const runtime = await context.deps.runtime.initializeDeployedApplicationRuntime({
+		profile: configured.profile,
+		providers: {
+			database: configured.providers.database,
+			authentication: configured.providers.authentication,
+			tenancy: configured.providers.tenancy,
+			assets: configured.providers.assets,
+			secrets: configured.providers.secrets,
+			jobs: configured.providers.jobs,
+			network: configured.providers.network
+		},
+		database: {
+			engine: "postgres",
+			connect: async () => {
+				const { getDatabase } = await import("@happyvertical/sql");
+				return await getDatabase({
+					type: "postgres",
+					url: process.env.DATABASE_URL
+				});
+			},
+			close: async (db) => {
+				await db.close?.();
+			}
+		},
+		authentication: {
+			provider: configured.providers.authentication.provider,
+			readiness: probe("authentication")
+		},
+		assets: {
+			provider: configured.providers.assets.provider,
+			readiness: probe("assets")
+		},
+		secrets: {
+			provider: configured.providers.secrets.provider,
+			readiness: probe("secrets")
+		}
+	});
+	await (kind === "schedule" ? await runtime.createScheduleWorker() : await runtime.createTaskWorker({ concurrency: Number.parseInt(process.env.SMRT_WORKER_CONCURRENCY || "4", 10) })).start();
+	context.io.stdout(`${JSON.stringify({
+		schemaVersion: 1,
+		status: "ready",
+		kind,
+		secretValuesIncluded: false
+	})}\n`);
+	let stopping = false;
+	const stop = async () => {
+		if (stopping) return;
+		stopping = true;
+		await runtime.close();
+	};
+	process.once("SIGINT", () => void stop());
+	process.once("SIGTERM", () => void stop());
+	return 0;
+}
+/** Failure of the Vite launcher; rendered as `s-m-r-t Vite launcher: …`. */
+var ViteLauncherError = class extends Error {};
+/** Resolve the application's installed Vite CLI entry, refusing unsafe paths. */
+function resolveViteEntry(sourceRoot) {
+	const installed = findInstalledPackage(sourceRoot, "vite");
+	if (!installed) throw new ViteLauncherError("Could not resolve the installed Vite package. Verify the generated app dependencies and Vite compatibility.");
+	const packagePath = join(realpathSync(installed), "package.json");
+	const packageRoot = dirname(packagePath);
+	let metadata;
+	try {
+		metadata = JSON.parse(readFileSync(packagePath, "utf8"));
+	} catch {
+		throw new ViteLauncherError("The installed Vite package metadata is invalid; reinstall dependencies.");
+	}
+	const declaredBin = typeof metadata.bin === "string" ? metadata.bin : metadata.bin?.vite;
+	if (typeof declaredBin !== "string" || declaredBin === "") throw new ViteLauncherError("The installed Vite package does not declare its CLI.");
+	const entry = resolve(packageRoot, declaredBin);
+	const relativeEntry = relative(packageRoot, entry);
+	if (relativeEntry === "" || relativeEntry.startsWith("..") || isAbsolute(relativeEntry)) throw new ViteLauncherError("The installed Vite package declares an unsafe CLI path.");
+	if (!existsSync(entry)) throw new ViteLauncherError("The installed Vite package CLI is missing; reinstall dependencies.");
+	return entry;
+}
+/**
+* Run the application's Vite CLI in this process with `args` verbatim. The
+* caller has already loaded `.env` without overriding the shell.
+*/
+async function launchVite(context, args) {
+	let entry;
+	try {
+		entry = resolveViteEntry(context.sourceRoot);
+	} catch (error) {
+		if (error instanceof ViteLauncherError) {
+			context.io.stderr(`s-m-r-t Vite launcher: ${error.message}\n`);
+			return 1;
+		}
+		throw error;
+	}
+	process.argv = [
+		process.execPath,
+		entry,
+		...args
+	];
+	await import(pathToFileURL(entry).href);
+	return 0;
+}
+/**
+* Validate opt-in portable MCP Apps metadata (`./mcp-apps`) when present.
+* Returns the exit code; findings go to stderr.
+*/
+async function validateMcpAppsIfPresent(context) {
+	const root = join(context.sourceRoot, "mcp-apps");
+	if (!existsSync(root)) return 0;
+	const { validateMcpAppsPackage } = await import("./mcp-apps-packaging-CixRnxz_.js");
+	const result = validateMcpAppsPackage(root);
+	for (const finding of result.findings) context.io.stderr(`${finding.code}: ${finding.message}\n`);
+	if (!result.valid) {
+		context.io.stderr(`Error: MCP Apps package validation failed with ${result.findings.length} finding(s)\n`);
+		return 1;
+	}
+	context.io.stdout("MCP Apps package at ./mcp-apps is valid.\n");
+	return 0;
+}
+//#endregion
+//#region src/app/process-record.ts
+/**
+* Managed web-process record (`<state>/app.pid`).
+*
+* Ported from the template's `scripts/smrt-process.mjs`. A recorded pid is
+* only trusted when the live process's command line proves it is the web
+* launcher with this record's instance nonce, so a recycled pid is never
+* signalled.
+*/
+/** File name of the web launcher; part of the process-identity proof. */
+var WEB_LAUNCHER_NAME = "smrt-web.mjs";
+function processCommand(pid) {
+	if (platform() === "win32") {
+		const result = spawnSync("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}').CommandLine`
+		], {
+			encoding: "utf8",
+			windowsHide: true
+		});
+		return result.status === 0 ? result.stdout.trim() : null;
+	}
+	const result = spawnSync("ps", [
+		"-p",
+		String(pid),
+		"-o",
+		"command="
+	], { encoding: "utf8" });
+	return result.status === 0 ? result.stdout.trim() : null;
+}
+/** Write the private (mode 0600) process record. */
+function writeProcessRecord(path, record) {
+	writeFileSync(path, `${JSON.stringify(record)}\n`, { mode: 384 });
+}
+/**
+* Send SIGTERM. Returns `false` when the process had already exited; any
+* other failure (e.g. EPERM) is rethrown.
+*/
+function sendTerminationSignal(pid, killProcess = process.kill) {
+	try {
+		killProcess(pid, "SIGTERM");
+		return true;
+	} catch (error) {
+		if (errorCode(error) === "ESRCH") return false;
+		throw error;
+	}
+}
+/** Split a process command line into argv-like tokens, dropping quotes. */
+function commandTokens(command) {
+	return command.trim().split(/\s+/).map((token) => token.replace(/^"|"$/g, "")).filter(Boolean);
+}
+/**
+* True when `command` is exactly the web launcher started with this record's
+* nonce: the final argument is `--smrt-instance=<instance>` and the argument
+* before it is a path whose basename is `smrt-web.mjs` (the CLI's
+* `bin/smrt-web.mjs`, or the template's `scripts/smrt-web.mjs`). Substring
+* matches such as `evil-smrt-web.mjs` or a nonce with a suffix are rejected.
+*/
+function matchesApplicationProcess(record, command) {
+	if (typeof command !== "string") return false;
+	const tokens = commandTokens(command);
+	if (tokens.length < 2) return false;
+	const script = tokens[tokens.length - 2];
+	return tokens[tokens.length - 1] === `--smrt-instance=${record.instance}` && script.split(/[\\/]/).pop() === "smrt-web.mjs";
+}
+function isLive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		const code = errorCode(error);
+		return code === "EPERM" || code === "EACCES";
+	}
+}
+/**
+* Re-check `record` against the live process table. Only `gone` and
+* `mismatched` justify dropping the record; `unverifiable` (the process
+* query failed or returned nothing) must keep it and must not signal.
+*/
+function checkOwnedProcess(record) {
+	if (!isLive(record.pid)) return "gone";
+	const command = processCommand(record.pid);
+	if (command === null || command === "") return isLive(record.pid) ? "unverifiable" : "gone";
+	return matchesApplicationProcess(record, command) ? "owned" : "mismatched";
+}
+/** True only when {@link checkOwnedProcess} proves the record still owned. */
+function verifyOwnedProcess(record) {
+	return checkOwnedProcess(record) === "owned";
+}
+/**
+* Return the recorded web process when it is live and provably ours;
+* otherwise remove the stale record and return `null`.
+*/
+function readOwnedProcess(path) {
+	let record;
+	try {
+		record = JSON.parse(readFileSync(path, "utf8"));
+		if (!Number.isSafeInteger(record.pid) || record.pid < 1 || typeof record.instance !== "string" || !/^[a-f0-9]{32}$/.test(record.instance)) throw new Error("Invalid process record.");
+	} catch {
+		rmSync(path, { force: true });
+		return null;
+	}
+	try {
+		process.kill(record.pid, 0);
+	} catch (error) {
+		const code = errorCode(error);
+		if (code !== "EPERM" && code !== "EACCES") {
+			rmSync(path, { force: true });
+			return null;
+		}
+	}
+	const command = processCommand(record.pid);
+	if (command === null || command === "") throw new Error(`Application process ${record.pid} is live but its identity cannot be verified.`);
+	if (!matchesApplicationProcess(record, command)) {
+		rmSync(path, { force: true });
+		return null;
+	}
+	return record;
+}
+//#endregion
+//#region src/app/operations.ts
+/**
+* Local/deployed application operations: install, setup, recover, start,
+* stop, doctor, open, backup, export, import.
+*
+* Ported from the template's `scripts/smrt-app.mjs`. Output JSON, exit
+* codes, state files, and environment variables are unchanged so the
+* template's `pnpm app:*` scripts can become `smrt app <operation>`.
+*/
+/** Operations implemented by this module. */
+var APP_OPERATIONS = [
+	"install",
+	"setup",
+	"recover",
+	"start",
+	"stop",
+	"doctor",
+	"open",
+	"backup",
+	"export",
+	"import"
+];
+function printJson(context, value, pretty = false) {
+	context.io.stdout(`${pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value)}\n`);
+}
+function ensurePrivateDirectory(path) {
+	mkdirSync(path, {
+		recursive: true,
+		mode: 448
+	});
+}
+function nearestExistingAncestor(path) {
+	let candidate = path;
+	while (!existsSync(candidate)) {
+		const parent = dirname(candidate);
+		if (parent === candidate) return candidate;
+		candidate = parent;
+	}
+	return candidate;
+}
+function pidPath(context) {
+	return join(preparedStateRoot(context), "app.pid");
+}
+function onboardingPath(context) {
+	return join(preparedStateRoot(context), "onboarding.json");
+}
+function onboardingLaunchPath(context) {
+	return join(preparedStateRoot(context), "onboarding-launch.html");
+}
+function removeOnboardingHandoff(context) {
+	rmSync(onboardingPath(context), { force: true });
+	rmSync(onboardingLaunchPath(context), { force: true });
+}
+function writePrivateAtomic(destination, contents) {
+	const temporary = `${destination}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+	try {
+		writeFileSync(temporary, contents, {
+			flag: "wx",
+			mode: 384
+		});
+		renameSync(temporary, destination);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+function saveOnboardingLaunch(context, url) {
+	const escapedUrl = url.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+	writePrivateAtomic(onboardingLaunchPath(context), `<!doctype html><meta http-equiv="refresh" content="0;url=${escapedUrl}">\n`);
+}
+function saveOnboardingUrl(context, url) {
+	ensurePrivateDirectory(preparedStateRoot(context));
+	saveOnboardingLaunch(context, url);
+	writePrivateAtomic(onboardingPath(context), `${JSON.stringify({
+		schemaVersion: 1,
+		url
+	})}\n`);
+}
+var InvalidOnboardingHandoff = class extends Error {};
+/** Read the retained loopback onboarding URL; tampered handoffs are removed. */
+function readOnboardingUrl(context) {
+	try {
+		const value = JSON.parse(readFileSync(onboardingPath(context), "utf8"));
+		if (value?.schemaVersion !== 1 || typeof value.url !== "string") throw new InvalidOnboardingHandoff("Invalid onboarding handoff.");
+		const url = new URL(value.url);
+		if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" && url.hostname !== "localhost" || url.pathname !== "/setup") throw new InvalidOnboardingHandoff("Invalid onboarding handoff.");
+		return url.toString();
+	} catch (error) {
+		if (errorCode(error) === "ENOENT" || error instanceof SyntaxError || error instanceof InvalidOnboardingHandoff || errorCode(error) === "ERR_INVALID_URL") {
+			removeOnboardingHandoff(context);
+			return null;
+		}
+		throw error;
+	}
+}
+/** Throw unless the configured profile is `local`. */
+async function assertLocalOperation(context, operation) {
+	const runtime = await context.deps.resolveRuntime(context.sourceRoot);
+	if (runtime.profile !== "local") throw new Error(`${operation} is local-profile only; run the production Node build or container for deployed profiles.`);
+	return runtime;
+}
+async function initializeLocal(context, runtime, env, options = {}) {
+	if (runtime.profile !== "local") return null;
+	return context.deps.runtime.initializeLocalApplicationRuntime({
+		appId: context.appId,
+		dataDirectory: process.env.SMRT_DATA_DIR,
+		sourceRoot: context.sourceRoot,
+		bindHost: env.HOST || "127.0.0.1",
+		providers: {
+			database: runtime.providers.database,
+			authentication: runtime.providers.authentication,
+			tenancy: runtime.providers.tenancy,
+			assets: runtime.providers.assets,
+			secrets: runtime.providers.secrets,
+			jobs: runtime.providers.jobs,
+			network: runtime.providers.network
+		},
+		prepareDatabase: options.prepareDatabase ? async () => {
+			context.deps.runSmrt(["db:migrate"], {
+				env,
+				label: "smrt db:migrate"
+			});
+		} : void 0,
+		backgroundJobs: process.env.SMRT_BACKGROUND_JOBS === "true"
+	});
+}
+async function setup(context, operationLock) {
+	const runtime = await context.deps.resolveRuntime(context.sourceRoot);
+	const operatorLease = runtime.profile === "local" ? acquireWriterLease(preparedStateRoot(context), { operationInstance: operationLock?.instance }) : null;
+	try {
+		const { env } = runtimeEnvironment(context, runtime);
+		context.deps.runPackageManager(["build"], {
+			env,
+			label: "pnpm build"
+		});
+		let initialized = null;
+		if (runtime.profile === "local") initialized = await initializeLocal(context, runtime, env, { prepareDatabase: true });
+		else context.deps.runSmrt(["db:migrate"], {
+			env,
+			label: "smrt db:migrate"
+		});
+		const port = env.PORT || "5173";
+		const onboardingUrl = initialized?.bootstrap ? `http://127.0.0.1:${port}/setup?token=${encodeURIComponent(initialized.bootstrap.token)}` : null;
+		const diagnostics = await initialized?.runtime.diagnostics();
+		if (onboardingUrl) saveOnboardingUrl(context, onboardingUrl);
+		if (diagnostics?.bootstrap.status === "claimed") removeOnboardingHandoff(context);
+		await initialized?.runtime.db.close?.();
+		const retainedOnboardingUrl = onboardingUrl || readOnboardingUrl(context);
+		const onboardingAvailable = runtime.profile === "local" && retainedOnboardingUrl !== null;
+		const report = {
+			schemaVersion: 1,
+			status: "ready",
+			profile: runtime.profile,
+			onboardingAvailable,
+			onboardingRecovery: onboardingAvailable ? "pnpm app:open" : null,
+			secretValuesIncluded: false
+		};
+		printJson(context, report, true);
+		return {
+			...report,
+			onboardingUrl: retainedOnboardingUrl
+		};
+	} finally {
+		operatorLease?.release();
+	}
+}
+async function recoverOnboarding(context, operationLock) {
+	const runtime = await context.deps.resolveRuntime(context.sourceRoot);
+	const { env } = runtimeEnvironment(context, runtime);
+	if (runtime.profile !== "local") throw new Error("Owner onboarding recovery is local-only.");
+	const operatorLease = acquireWriterLease(preparedStateRoot(context), { operationInstance: operationLock?.instance });
+	try {
+		const initialized = await initializeLocal(context, runtime, env);
+		if (!initialized) throw new Error("Local runtime initialization failed.");
+		const invitation = await initialized.runtime.rotateBootstrapInvitation();
+		saveOnboardingUrl(context, `http://127.0.0.1:${env.PORT || "5173"}/setup?token=${encodeURIComponent(invitation.token)}`);
+		await initialized.runtime.db.close?.();
+		printJson(context, {
+			schemaVersion: 1,
+			status: "ready",
+			onboardingAvailable: true,
+			recovery: "Run pnpm app:start, then pnpm app:open.",
+			secretValuesIncluded: false
+		});
+	} finally {
+		operatorLease.release();
+	}
+}
+function isAlive(pid) {
+	process.kill(pid, 0);
+	return true;
+}
+async function waitForReady(context, url, pid, instance, configuration) {
+	const healthUrl = new URL("/api/_runtime/health", url);
+	for (let attempt = 0; attempt < 40; attempt += 1) {
+		try {
+			const response = await context.deps.fetch(healthUrl, { redirect: "manual" });
+			if (response.status === 200) {
+				const health = await response.json();
+				if (health?.status === "ready" && health.application === context.appId && health.instance === instance && health.configuration === configuration) {
+					isAlive(pid);
+					return;
+				}
+			}
+			isAlive(pid);
+		} catch {
+			try {
+				isAlive(pid);
+			} catch {
+				throw new Error("The application process exited before becoming ready.");
+			}
+		}
+		await context.deps.sleep(250);
+	}
+	throw new Error(`The application did not become ready at ${url}.`);
+}
+async function start(context, operationLock) {
+	const runtime = await assertLocalOperation(context, "app:start");
+	const { env } = runtimeEnvironment(context, runtime);
+	const url = `http://127.0.0.1:${env.PORT || "5173"}/`;
+	env.ORIGIN ||= url;
+	const configuration = runtimeConfigurationFingerprint(runtime, env);
+	const existing = readOwnedProcess(pidPath(context));
+	if (existing) {
+		await waitForReady(context, url, existing.pid, existing.instance, configuration);
+		printJson(context, {
+			schemaVersion: 1,
+			status: "running",
+			pid: existing.pid
+		});
+		return existing.pid;
+	}
+	ensurePrivateDirectory(preparedStateRoot(context));
+	const instance = randomBytes(16).toString("hex");
+	const child = spawn(process.execPath, [webLauncherPath(), `--smrt-instance=${instance}`], {
+		cwd: context.sourceRoot,
+		env: {
+			...env,
+			HOST: runtime.profile === "local" ? "127.0.0.1" : env.HOST || "0.0.0.0",
+			PORT: env.PORT || "5173",
+			SMRT_PROCESS_INSTANCE: instance,
+			SMRT_OPERATION_INSTANCE: operationLock?.instance
+		},
+		detached: true,
+		stdio: "ignore"
+	});
+	child.unref();
+	const pid = child.pid;
+	if (pid === void 0) throw new Error("The application process could not be started.");
+	writeProcessRecord(pidPath(context), {
+		pid,
+		instance
+	});
+	try {
+		await waitForReady(context, url, pid, instance, configuration);
+	} catch (error) {
+		if (!await terminateFailedStart(context, child)) throw new Error(`${error instanceof Error ? error.message : "The application did not become ready."} Application process ${pid} did not exit after SIGTERM and SIGKILL and remains recorded; run pnpm app:stop.`);
+		rmSync(pidPath(context), { force: true });
+		throw error;
+	}
+	printJson(context, {
+		schemaVersion: 1,
+		status: "started",
+		pid
+	});
+	return pid;
+}
+/**
+* Terminate a launcher that failed to prove readiness: SIGTERM, wait, then
+* SIGKILL, wait. Resolves `true` only once the child has provably exited.
+* Uses the child handle we own, so a reaped pid is never signalled.
+*/
+async function terminateFailedStart(context, child) {
+	const exited = () => child.exitCode !== null || child.signalCode !== null;
+	for (const [signal, attempts] of [["SIGTERM", 50], ["SIGKILL", 20]]) {
+		if (exited()) return true;
+		try {
+			context.deps.signal(child.pid, signal);
+		} catch (error) {
+			if (errorCode(error) === "ESRCH") return true;
+			throw error;
+		}
+		for (let attempt = 0; attempt < attempts; attempt += 1) {
+			await context.deps.sleep(100);
+			if (exited()) return true;
+		}
+	}
+	return exited();
+}
+async function stop(context) {
+	const record = readOwnedProcess(pidPath(context));
+	const pid = record?.pid || null;
+	if (!record || !pid) {
+		rmSync(pidPath(context), { force: true });
+		printJson(context, {
+			schemaVersion: 1,
+			status: "stopped"
+		});
+		return;
+	}
+	const state = checkOwnedProcess(record);
+	if (state === "unverifiable") throw new Error(`Application process ${pid} is live but its identity could not be re-verified; app.pid was kept and no signal was sent. Retry pnpm app:stop.`);
+	if (state !== "owned" || !sendTerminationSignal(pid)) {
+		rmSync(pidPath(context), { force: true });
+		printJson(context, {
+			schemaVersion: 1,
+			status: "stopped",
+			pid
+		});
+		return;
+	}
+	for (let attempt = 0; attempt < 40; attempt += 1) {
+		await new Promise((resolvePromise) => setTimeout(resolvePromise, 100));
+		try {
+			process.kill(pid, 0);
+		} catch {
+			break;
+		}
+		if (attempt === 39) throw new Error(`Application process ${pid} did not stop cleanly.`);
+	}
+	rmSync(pidPath(context), { force: true });
+	printJson(context, {
+		schemaVersion: 1,
+		status: "stopped",
+		pid
+	});
+}
+async function open(context) {
+	const runtime = await context.deps.resolveRuntime(context.sourceRoot);
+	const url = `http://${runtime.profile === "local" ? "127.0.0.1" : process.env.HOST || "127.0.0.1"}:${process.env.PORT || "5173"}/`;
+	const onboardingUrl = runtime.profile === "local" ? readOnboardingUrl(context) : null;
+	if (onboardingUrl) saveOnboardingLaunch(context, onboardingUrl);
+	const destination = onboardingUrl ? pathToFileURL(onboardingLaunchPath(context)).toString() : url;
+	context.deps.openBrowser(destination);
+	printJson(context, {
+		schemaVersion: 1,
+		status: "opened",
+		url
+	});
+}
+async function doctor(context) {
+	const findings = [];
+	let runtime = null;
+	let paths = null;
+	let statePath = null;
+	let canInspectMigrations = false;
+	try {
+		runtime = await context.deps.resolveRuntime(context.sourceRoot);
+	} catch {
+		findings.push({
+			code: "invalid-runtime-profile",
+			severity: "error",
+			message: "The canonical runtime profile is invalid.",
+			recovery: "Select local, self-hosted, or cloud in smrt.config.ts."
+		});
+	}
+	if (Number(process.versions.node.split(".")[0]) < 26) findings.push({
+		code: "unsupported-node",
+		severity: "error",
+		message: "Node.js 26 or newer is required.",
+		recovery: "Install the Node.js version declared in package.json engines."
+	});
+	if (runtime) {
+		if (runtime.profile !== "local") for (const [component, provider] of [
+			["authentication", runtime.providers.authentication.provider],
+			["assets", runtime.providers.assets.provider],
+			["secrets", runtime.providers.secrets.provider]
+		]) try {
+			await createProviderReadinessProbe(component, {
+				profile: runtime.profile,
+				provider
+			}, { sourceRoot: context.sourceRoot })();
+		} catch {
+			findings.push({
+				code: "provider-not-configured",
+				component,
+				severity: "error",
+				message: `The ${component} provider is not ready.`,
+				recovery: `Configure and verify the installed ${component} provider readiness module.`
+			});
+		}
+		try {
+			({paths} = runtimeEnvironment(context, runtime));
+			statePath = resolveApplicationStateRoot({
+				appId: context.appId,
+				dataDirectory: process.env.SMRT_DATA_DIR,
+				sourceRoot: context.sourceRoot
+			});
+			accessSync(nearestExistingAncestor(statePath), constants.W_OK);
+			if (runtime.profile === "local") paths = await context.deps.runtime.validateLocalDatabaseStorage({
+				appId: context.appId,
+				dataDirectory: process.env.SMRT_DATA_DIR,
+				sourceRoot: context.sourceRoot
+			});
+			canInspectMigrations = true;
+			const host = process.env.HOST || (runtime.profile === "local" ? "127.0.0.1" : "0.0.0.0");
+			if (runtime.profile === "local" && host !== "127.0.0.1" && host !== "::1") findings.push({
+				code: "unsafe-local-bind",
+				severity: "error",
+				message: "Local owner bootstrap may only bind to a loopback address.",
+				recovery: "Unset HOST or set HOST=127.0.0.1."
+			});
+			if (paths?.root) accessSync(nearestExistingAncestor(paths.root), constants.W_OK);
+		} catch (error) {
+			findings.push({
+				code: "runtime-path-unavailable",
+				severity: "error",
+				message: "A required runtime path or provider configuration is unavailable.",
+				recovery: error instanceof Error ? error.message : "Configure a writable runtime data path."
+			});
+		}
+		if (canInspectMigrations) try {
+			const status = context.deps.runSmrt(["db:status", "--json"], {
+				env: runtimeEnvironment(context, runtime).env,
+				capture: true,
+				allowFailure: true,
+				label: "smrt db:status --json"
+			});
+			if (status.status !== 0) findings.push({
+				code: "migration-status-failed",
+				severity: "error",
+				message: "Database migration status could not be verified.",
+				recovery: "Run pnpm app:setup and inspect the private migration logs."
+			});
+			else {
+				const migrationStatus = JSON.parse(status.stdout || "{}");
+				if ((migrationStatus.drift?.length || 0) > 0 || (migrationStatus.migrations?.failed?.actionRequired || 0) > 0 || migrationStatus.schemaContract?.ok === false || migrationStatus.preconditions?.some((item) => item.status === "error")) findings.push({
+					code: "migration-required",
+					severity: "error",
+					message: "Database migrations are pending or failed.",
+					recovery: "Run pnpm app:setup, then rerun pnpm app:doctor."
+				});
+			}
+		} catch {
+			findings.push({
+				code: "migration-status-failed",
+				severity: "error",
+				message: "Database migration status could not be parsed.",
+				recovery: "Run pnpm app:setup and inspect the private migration logs."
+			});
+		}
+	}
+	const report = {
+		schemaVersion: 1,
+		status: findings.some((finding) => finding.severity === "error") ? "error" : "ready",
+		profile: runtime?.profile || null,
+		capabilities: runtime?.capabilities || null,
+		paths: paths || statePath ? {
+			root: paths?.root || null,
+			database: paths?.database || null,
+			assets: paths?.assets || null,
+			state: statePath
+		} : null,
+		findings,
+		secretValuesIncluded: false
+	};
+	printJson(context, report, true);
+	return report.status === "error" ? 1 : 0;
+}
+async function backup(context, args, operationLock) {
+	if ((await context.deps.resolveRuntime(context.sourceRoot)).profile !== "local") throw new Error("This scaffold delegates deployed backups to the selected operator or managed provider.");
+	const explicitDestination = args[0] ? assertExternalArtifactPath({
+		sourceRoot: context.sourceRoot,
+		path: resolve(args[0]),
+		label: "Backup destination"
+	}) : null;
+	const paths = await context.deps.runtime.validateLocalDatabaseStorage({
+		appId: context.appId,
+		dataDirectory: process.env.SMRT_DATA_DIR,
+		sourceRoot: context.sourceRoot
+	});
+	const operatorLease = acquireWriterLease(preparedStateRoot(context), { operationInstance: operationLock?.instance });
+	try {
+		const destination = assertExternalArtifactPath({
+			sourceRoot: context.sourceRoot,
+			path: explicitDestination || join(dirname(paths.root), "backups", `${context.appId}-${(/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-")}`),
+			label: "Backup destination"
+		});
+		ensurePrivateDirectory(dirname(destination));
+		try {
+			mkdirSync(destination, { mode: 448 });
+		} catch (error) {
+			if (errorCode(error) === "EEXIST") throw new Error(`Backup destination already exists: ${destination}`);
+			throw error;
+		}
+		try {
+			cpSync(paths.root, destination, {
+				recursive: true,
+				force: false,
+				errorOnExist: true
+			});
+		} catch (error) {
+			rmSync(destination, {
+				recursive: true,
+				force: true
+			});
+			throw error;
+		}
+		printJson(context, {
+			schemaVersion: 1,
+			status: "backed-up",
+			destination
+		});
+	} finally {
+		operatorLease.release();
+	}
+}
+/**
+* The application's own adapter at `scripts/smrt-portability.mjs` keeps
+* working as the documented extension point; otherwise the built-in adapter
+* is used.
+*/
+async function loadPortabilityAdapter(context) {
+	const override = join(context.sourceRoot, "scripts", "smrt-portability.mjs");
+	if (existsSync(override)) return await import(pathToFileURL(override).href);
+	return import("./portability-DmQWSSXA.js").then((n) => n.s);
+}
+async function portability(context, operation, args, operationLock) {
+	const adapter = await loadPortabilityAdapter(context);
+	const runtime = await context.deps.resolveRuntime(context.sourceRoot);
+	const environment = runtimeEnvironment(context, runtime);
+	const requestedPath = args[0] ? resolve(args[0]) : void 0;
+	const artifactPath = requestedPath ? assertExternalArtifactPath({
+		sourceRoot: context.sourceRoot,
+		path: requestedPath,
+		label: operation === "export" ? "Export destination" : "Import source"
+	}) : requestedPath;
+	if (runtime.profile === "local") environment.paths = await context.deps.runtime.validateLocalDatabaseStorage({
+		appId: context.appId,
+		dataDirectory: process.env.SMRT_DATA_DIR,
+		sourceRoot: context.sourceRoot
+	});
+	const portabilityContext = {
+		appId: context.appId,
+		sourceRoot: context.sourceRoot,
+		stateRoot: preparedStateRoot(context),
+		runtime,
+		env: environment.env,
+		paths: environment.paths,
+		assetRoot: environment.assetRoot
+	};
+	let operatorLease = null;
+	if (operation === "import") {
+		if (runtime.profile === "local") operatorLease = acquireWriterLease(preparedStateRoot(context), { operationInstance: operationLock?.instance });
+		if (runtime.profile !== "local" && process.env.SMRT_MAINTENANCE_MODE !== "true") throw new Error("Stop deployed web/workers and set SMRT_MAINTENANCE_MODE=true before importing.");
+	}
+	try {
+		const result = await adapter[operation === "export" ? "exportApplication" : "importApplication"]({
+			...portabilityContext,
+			path: artifactPath
+		});
+		printJson(context, {
+			schemaVersion: 1,
+			status: `${operation}ed`,
+			...result
+		}, true);
+	} finally {
+		operatorLease?.release();
+	}
+}
+/**
+* Run one application operation. Resolves to the process exit code; throws
+* on failure (the caller renders the error envelope).
+*/
+async function runApplicationOperation(context, operation, args) {
+	switch (operation) {
+		case "install":
+			await assertLocalOperation(context, "app:install");
+			await withOperationLock(preparedStateRoot(context), "install", async (lock) => {
+				const report = await setup(context, lock);
+				await start(context, lock);
+				const baseUrl = `http://127.0.0.1:${process.env.PORT || "5173"}/`;
+				if (report.onboardingUrl) saveOnboardingLaunch(context, report.onboardingUrl);
+				context.deps.openBrowser(report.onboardingUrl ? pathToFileURL(onboardingLaunchPath(context)).toString() : baseUrl);
+			});
+			return 0;
+		case "setup":
+			await withOperationLock(preparedStateRoot(context), operation, (lock) => setup(context, lock));
+			return 0;
+		case "recover":
+			await assertLocalOperation(context, "app:recover");
+			await withOperationLock(preparedStateRoot(context), operation, (lock) => recoverOnboarding(context, lock));
+			return 0;
+		case "start":
+			await assertLocalOperation(context, "app:start");
+			await withOperationLock(preparedStateRoot(context), operation, (lock) => start(context, lock));
+			return 0;
+		case "doctor": return doctor(context);
+		case "open":
+			await open(context);
+			return 0;
+		case "stop":
+			await assertLocalOperation(context, "app:stop");
+			await withOperationLock(preparedStateRoot(context), operation, () => stop(context));
+			return 0;
+		case "backup":
+			await withOperationLock(preparedStateRoot(context), operation, (lock) => backup(context, args, lock));
+			return 0;
+		case "export":
+		case "import":
+			await withOperationLock(preparedStateRoot(context), operation, (lock) => portability(context, operation, args, lock));
+			return 0;
+	}
+}
+//#endregion
+//#region src/app/cli.ts
+/**
+* `smrt app <operation>` dispatcher.
+*
+* Every operation writes machine-readable JSON to stdout and, on failure,
+* one secret-free JSON envelope to stderr with exit code 1 — the contract
+* the template's `scripts/smrt-app.mjs` established.
+*/
+var cli_exports = /* @__PURE__ */ __exportAll({
+	APP_COMMANDS: () => APP_COMMANDS,
+	APP_RECOVERY: () => APP_RECOVERY,
+	errorEnvelope: () => errorEnvelope,
+	renderAppHelp: () => renderAppHelp,
+	runAppCommand: () => runAppCommand
+});
+/** Recovery line carried by every error envelope. */
+var APP_RECOVERY = "Run pnpm app:doctor and follow its recovery instructions.";
+/** Every `smrt app` command with a one-line description (for help output). */
+var APP_COMMANDS = Object.freeze({
+	install: "Local: set up, start, and open owner onboarding in one step",
+	setup: "Build, apply migrations explicitly, and prepare owner onboarding",
+	recover: "Local: issue a fresh single-use owner onboarding invitation",
+	start: "Local: start the production build on loopback and prove readiness",
+	stop: "Local: stop the managed application process",
+	doctor: "Report runtime, storage, provider, and migration findings (default)",
+	open: "Open the application or pending owner onboarding in a browser",
+	"backup [destination]": "Local: copy the private data root to a new directory",
+	"export [path]": "Write a logical, asset-aware export bundle",
+	"import <path>": "Import a logical export bundle into an empty application",
+	migrate: "Prepare storage custody and run smrt db:migrate under the lock",
+	"worker [task|schedule]": "Deployed: run the task or schedule worker",
+	"dev [...vite args]": "Run the application's Vite dev server",
+	"build [...vite args]": "Validate ./mcp-apps when present, then run the Vite build",
+	"vite [...args]": "Run the application's installed Vite CLI with args"
+});
+/** Build the stderr envelope for `error`, redacting secret material. */
+function errorEnvelope(error) {
+	const runtimeCode = error instanceof Error && error.name === "LocalRuntimeError" && typeof error.code === "string" ? error.code : void 0;
+	return {
+		schemaVersion: 1,
+		status: "error",
+		code: "operation-failed",
+		...runtimeCode ? { runtimeCode } : {},
+		message: redactSecrets(error instanceof Error ? error.message : "Application operation failed."),
+		recovery: APP_RECOVERY,
+		secretValuesIncluded: false
+	};
+}
+/** Render `smrt app` usage. */
+function renderAppHelp() {
+	const width = Math.max(...Object.keys(APP_COMMANDS).map((key) => key.length));
+	return `Usage: smrt app <operation> [args]\n\nOperations:\n${Object.entries(APP_COMMANDS).map(([name, description]) => `  ${name.padEnd(width)}  ${description}`).join("\n")}\n`;
+}
+var ENV_FILE_OPERATIONS = /* @__PURE__ */ new Set([
+	...APP_OPERATIONS,
+	"migrate",
+	"dev",
+	"build",
+	"vite"
+]);
+/**
+* Run `smrt app <argv…>` and resolve to the process exit code.
+*
+* `argv` is everything after `app`. A leading `--` before operation
+* arguments is ignored, matching `pnpm app:import -- <path>`.
+*/
+async function runAppCommand(argv, options = {}) {
+	const io = {
+		stdout: options.io?.stdout ?? ((text) => void process.stdout.write(text)),
+		stderr: options.io?.stderr ?? ((text) => void process.stderr.write(text))
+	};
+	const operation = argv[0] || "doctor";
+	const rawArgs = argv.slice(1);
+	const args = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs;
+	if (operation === "help" || operation === "--help" || operation === "-h") {
+		io.stdout(renderAppHelp());
+		return 0;
+	}
+	try {
+		const sourceRoot = resolve(options.cwd ?? process.cwd());
+		if (ENV_FILE_OPERATIONS.has(operation)) loadSourceEnvironment(sourceRoot);
+		if (operation === "dev" || operation === "build" || operation === "vite") {
+			const context = {
+				sourceRoot,
+				appId: "",
+				io,
+				deps: {}
+			};
+			if (operation === "build") {
+				const status = await validateMcpAppsIfPresent(context);
+				if (status !== 0) return status;
+			}
+			return launchVite(context, operation === "vite" ? args : [operation, ...args]);
+		}
+		const deps = {
+			...await defaultDependencies(sourceRoot),
+			...options.dependencies
+		};
+		const context = {
+			sourceRoot,
+			appId: resolveContextApplicationId(sourceRoot),
+			io,
+			deps
+		};
+		if (operation === "migrate") return await prepareMigration(context);
+		if (operation === "worker") return await runWorker(context, args);
+		if (!APP_OPERATIONS.includes(operation)) throw new Error(`Unknown app operation: ${operation}`);
+		return await runApplicationOperation(context, operation, args);
+	} catch (error) {
+		io.stderr(`${JSON.stringify(errorEnvelope(error))}\n`);
+		return 1;
+	}
+}
+//#endregion
+export { AppCommandError as A, runtimeEnvironment as C, resolveApplicationId as D, prepareApplicationStateRoot as E, redactSecrets as M, resolveApplicationStateRoot as O, cliExecutablePath as S, assertExternalArtifactPath as T, launchVite as _, renderAppHelp as a, runWorker as b, runApplicationOperation as c, matchesApplicationProcess as d, readOwnedProcess as f, ViteLauncherError as g, writeProcessRecord as h, errorEnvelope as i, errorCode as j, runtimeConfigurationFingerprint as k, WEB_LAUNCHER_NAME as l, verifyOwnedProcess as m, APP_RECOVERY as n, runAppCommand as o, sendTerminationSignal as p, cli_exports as r, APP_OPERATIONS as s, APP_COMMANDS as t, checkOwnedProcess as u, prepareMigration as v, webLauncherPath as w, validateMcpAppsIfPresent as x, resolveViteEntry as y };