@happyvertical/smrt-cli 0.53.3 → 0.53.5

package/dist/cli-OZsH5cdL.js

@@ -0,0 +1,1602 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { accessSync, chmodSync, closeSync, constants, cpSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { acquireWriterLease, createProviderReadinessProbe, findInstalledPackage, openLocalMcpTokenStore, 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
+		});
+	}
+};
+/**
+* A `smrt app start` whose web process never proved readiness. Carries the
+* already-redacted, bounded tail of that process's output and the private
+* log it came from, for the error envelope.
+*/
+var ApplicationStartError = class extends Error {
+	output;
+	logFile;
+	constructor(message, output, logFile) {
+		super(message);
+		this.name = "ApplicationStartError";
+		this.output = output;
+		this.logFile = logFile;
+	}
+};
+/** Replacement marker for every redacted value. */
+var REDACTED = "[redacted]";
+/** 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;
+/** URL userinfo (`scheme://user:pass@`); group 2 is the credential span. */
+var URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/@:'"]*(?::[^\s/@'"]*)?)@/dgi;
+/** Query/parameter credential (`?token=…`); group 2 is the value span. */
+var QUERY_CREDENTIAL = /([?&;](?:token|password|secret|key|access_token)=)([^&\s"'<>]+)/dgi;
+/** Bearer token; group 2 is the token span (8+ characters unless strict). */
+var BEARER = /\b(Bearer\s+)([A-Za-z0-9._~+/=-]{8,})/dg;
+var BEARER_ANY_LENGTH = /\b(Bearer\s+)([A-Za-z0-9._~+/=-]+)/dg;
+function structuralSpans(text, strict) {
+	const spans = [];
+	for (const pattern of [
+		URL_USERINFO,
+		QUERY_CREDENTIAL,
+		strict ? BEARER_ANY_LENGTH : BEARER
+	]) for (const match of text.matchAll(pattern)) {
+		const span = match.indices?.[2];
+		if (span && (span[1] > span[0] || pattern === URL_USERINFO)) spans.push([span[0], span[1]]);
+	}
+	return spans;
+}
+/** Every existing `[redacted]` marker in `text`: opaque to later passes. */
+function markerSpans(text) {
+	return literalSpans(text, [REDACTED], []);
+}
+function literalSpans(text, values, opaque) {
+	const spans = [];
+	for (const value of values) for (let index = text.indexOf(value); index !== -1; index = text.indexOf(value, index + 1)) {
+		const end = index + value.length;
+		if (opaque.some(([start, stop]) => index >= start && end <= stop)) continue;
+		spans.push([index, end]);
+	}
+	return spans;
+}
+/** Replace the union of `spans` (overlapping or touching spans merge). */
+function maskSpans(text, spans) {
+	if (spans.length === 0) return text;
+	spans.sort((left, right) => left[0] - right[0] || right[1] - left[1]);
+	let result = "";
+	let cursor = 0;
+	let [start, end] = spans[0];
+	const flush = () => {
+		result += text.slice(cursor, start) + REDACTED;
+		cursor = end;
+	};
+	for (const [nextStart, nextEnd] of spans.slice(1)) {
+		if (nextStart <= end) {
+			end = Math.max(end, nextEnd);
+			continue;
+		}
+		flush();
+		[start, end] = [nextStart, nextEnd];
+	}
+	flush();
+	return result + text.slice(cursor);
+}
+/**
+* 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.
+*
+* Every span is located on the raw text and the union is masked at once, so
+* a literal value can never split a structural match (an env value that is
+* a Bearer-token prefix, or a URL's scheme and host, used to leave the rest
+* of the token or the URL password visible). A final structural pass over
+* the masked text keeps everything the earlier sequential order masked.
+*/
+function redactSecrets(message, environment = process.env, options = {}) {
+	const strict = options.strict === true;
+	const minimumLength = strict ? 1 : MIN_REDACTED_VALUE_LENGTH;
+	const secretValues = Object.entries(environment).filter(([name, value]) => typeof value === "string" && value.length >= minimumLength && SECRET_ENVIRONMENT_NAME.test(name)).map(([, value]) => value);
+	const markers = markerSpans(message);
+	const masked = maskSpans(message, [
+		...markers,
+		...structuralSpans(message, strict),
+		...literalSpans(message, secretValues, markers)
+	]);
+	return maskSpans(masked, [...markerSpans(masked), ...structuralSpans(masked, strict)]);
+}
+/**
+* The last `maxBytes` of `text`: a leading partial line (and any split
+* multi-byte character) is dropped when the cut lands mid-text. Redact
+* before cutting; cutting never exposes anything redaction masked.
+*/
+function boundedTail(text, maxBytes) {
+	const bytes = Buffer.from(text, "utf8");
+	if (bytes.length <= maxBytes) return text;
+	const tail = bytes.subarray(bytes.length - maxBytes).toString("utf8");
+	let cut = tail.slice(tail.indexOf("\n") + 1);
+	while (Buffer.byteLength(cut) > maxBytes) cut = cut.slice(1);
+	return cut;
+}
+//#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.
+*
+* Profile selection is `resolveEffectiveApplicationRuntime()` from
+* smrt-config — the rule the web process applies in app-runtime's SvelteKit
+* entry — so the operator and the server it manages never disagree: no
+* `runtime` block (or no config file) is the `local` profile, and a present
+* value that is not a valid block (`null`, `false`, `0`, `''`, ...) fails
+* closed.
+*/
+async function resolveConfiguredRuntime(sourceRoot) {
+	const { loadConfig, resolveEffectiveApplicationRuntime } = await import("@happyvertical/smrt-config");
+	return resolveEffectiveApplicationRuntime(await loadConfig({
+		cache: false,
+		searchFrom: sourceRoot
+	}));
+}
+/** 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;
+}
+/** Loopback host every `smrt app` URL (onboarding, `open`, `start`) names. */
+var LOOPBACK_HOST = "127.0.0.1";
+/**
+* Arguments for `smrt app dev`: the caller's Vite arguments, plus
+* `--host 127.0.0.1` unless they name `--host`, and `--port $PORT` when
+* `PORT` is set and they name no `--port`. Vite's own default host is
+* `localhost`, which Node resolves to `[::1]` first, so the dev server would
+* not answer the `http://127.0.0.1:<PORT>` URL onboarding and `app:open` hand
+* out. An explicit `--host`/`--port` (or `smrt app vite dev …`) wins.
+*/
+function devServerArguments(args, env = process.env) {
+	const names = (flag) => args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+	const result = [...args];
+	if (!names("--host")) result.push("--host", LOOPBACK_HOST);
+	if (!names("--port") && env.PORT) result.push("--port", env.PORT);
+	return result;
+}
+/**
+* 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$1(context, value, pretty = false) {
+	context.io.stdout(`${pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value)}\n`);
+}
+/** Print the one-time URL to the operator's terminal only, never to logs. */
+function printOnboardingUrl(context, url) {
+	if (!url || !context.io.operatorTerminal) return;
+	context.io.operatorTerminal(`Open this one-time owner setup link on this device (it works once and expires):\n  ${url}\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$1(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();
+		const url = `http://127.0.0.1:${env.PORT || "5173"}/setup?token=${encodeURIComponent(invitation.token)}`;
+		saveOnboardingUrl(context, url);
+		await initialized.runtime.db.close?.();
+		printJson$1(context, {
+			schemaVersion: 1,
+			status: "ready",
+			onboardingAvailable: true,
+			recovery: "Run pnpm app:start, then pnpm app:open.",
+			secretValuesIncluded: false
+		});
+		printOnboardingUrl(context, url);
+	} 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$1(context, {
+			schemaVersion: 1,
+			status: "running",
+			pid: existing.pid
+		});
+		return existing.pid;
+	}
+	ensurePrivateDirectory(preparedStateRoot(context));
+	const instance = randomBytes(16).toString("hex");
+	const childEnv = {
+		...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
+	};
+	const logFile = startLogPath(context);
+	const logFd = openStartLog(logFile);
+	let child;
+	try {
+		child = spawn(process.execPath, [webLauncherPath(), `--smrt-instance=${instance}`], {
+			cwd: context.sourceRoot,
+			env: childEnv,
+			detached: true,
+			stdio: [
+				"ignore",
+				logFd,
+				logFd
+			]
+		});
+	} finally {
+		closeSync(logFd);
+	}
+	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 new ApplicationStartError(error instanceof Error ? error.message : "The application did not become ready.", redactedLogTail(logFile, childEnv), logFile);
+	}
+	printJson$1(context, {
+		schemaVersion: 1,
+		status: "started",
+		pid
+	});
+	return pid;
+}
+/** Upper bound on the web-process output a failed `start` reports. */
+var START_OUTPUT_TAIL_BYTES = 8 * 1024;
+/** Window read before redaction, so a cut never splits a reported secret. */
+var START_OUTPUT_WINDOW_BYTES = 64 * 1024;
+function startLogPath(context) {
+	return join(preparedStateRoot(context), "app.log");
+}
+/**
+* Create a fresh 0600 `app.log` for this start. The previous run's log is
+* removed first and the new one is created exclusively, so a planted link or
+* file is never written through.
+*/
+function openStartLog(path) {
+	rmSync(path, { force: true });
+	return openSync(path, "wx", 384);
+}
+/**
+* The last {@link START_OUTPUT_TAIL_BYTES} of `path`, strictly redacted
+* against the child's environment. A bounded window is redacted before it is cut, and a
+* window that starts mid-file drops its leading partial record (all of it
+* when the window holds no newline), so no fragment of a secret whose
+* prefix lies before the window can survive the cut.
+*/
+function redactedLogTail(path, env) {
+	let text;
+	try {
+		const fd = openSync(path, "r");
+		try {
+			const size = fstatSync(fd).size;
+			const length = Math.min(size, START_OUTPUT_WINDOW_BYTES);
+			const buffer = Buffer.alloc(length);
+			readSync(fd, buffer, 0, length, size - length);
+			text = buffer.toString("utf8");
+			if (length < size) {
+				const newline = text.indexOf("\n");
+				text = newline === -1 ? "" : text.slice(newline + 1);
+			}
+		} finally {
+			closeSync(fd);
+		}
+	} catch {
+		return "";
+	}
+	return boundedTail(redactSecrets(text, env, { strict: true }), START_OUTPUT_TAIL_BYTES);
+}
+/**
+* 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$1(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$1(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$1(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$1(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$1(context, report, true);
+	return report.status === "error" ? 1 : 0;
+}
+async function backup(context, args) {
+	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
+	});
+	await withOperationLock(preparedStateRoot(context), "backup", async (lock) => {
+		const operatorLease = acquireWriterLease(preparedStateRoot(context), { operationInstance: lock.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"
+			});
+			const storageRelative = relative(paths.root, destination);
+			if (storageRelative === "" || !isAbsolute(storageRelative) && storageRelative !== ".." && !storageRelative.startsWith(`..${sep}`)) throw new Error("Backup destination must remain outside local storage.");
+			ensurePrivateDirectory(dirname(destination));
+			try {
+				mkdirSync(destination, { mode: 448 });
+			} catch (error) {
+				if (error.code !== "EEXIST") throw error;
+				throw new Error(`Backup destination already exists: ${destination}`);
+			}
+			try {
+				for (const entry of readdirSync(paths.root)) cpSync(join(paths.root, entry), join(destination, entry), {
+					recursive: true,
+					force: false,
+					errorOnExist: true
+				});
+				chmodSync(destination, 448);
+			} catch (error) {
+				throw new Error(`Backup copy failed; destination preserved at ${destination}`, { cause: error });
+			}
+			printJson$1(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-CES1YC2m.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$1(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, async (lock) => {
+				printOnboardingUrl(context, (await setup(context, lock)).onboardingUrl);
+			});
+			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 backup(context, args);
+			return 0;
+		case "export":
+		case "import":
+			await withOperationLock(preparedStateRoot(context), operation, (lock) => portability(context, operation, args, lock));
+			return 0;
+	}
+}
+//#endregion
+//#region src/app/tokens.ts
+/**
+* `smrt app token` — owner-minted bearer tokens for local MCP clients.
+*
+* ```
+* smrt app token --scopes notes.read [--expires 30d] [--label "Claude Desktop"]
+* smrt app token list
+* smrt app token revoke <id>
+* ```
+*
+* Local profile only. The token is printed once, in the `issued` JSON
+* document on stdout, and is otherwise never written anywhere: the runtime
+* stores only its HMAC. `list` and `revoke` output carries no token values.
+*/
+/** Usage text for `smrt app token`. */
+var TOKEN_USAGE = "Usage: smrt app token [create] --scopes <scope[,scope...]> [--expires <n>s|m|h|d] [--label <text>] | token list | token revoke <id>";
+var UNIT_SECONDS = {
+	s: 1,
+	m: 60,
+	h: 3600,
+	d: 1440 * 60
+};
+/** Parse `30d`, `12h`, `90m`, `3600s` or bare seconds. */
+function parseTokenLifetime(value) {
+	const match = /^([1-9][0-9]{0,8})([smhd]?)$/u.exec(value.trim());
+	if (!match) throw new Error(`Invalid --expires value. ${TOKEN_USAGE}`);
+	return Number(match[1]) * UNIT_SECONDS[match[2] || "s"];
+}
+function parseCreateArgs(args) {
+	const scopes = [];
+	let expiresInSeconds;
+	let label;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		const equals = arg.indexOf("=");
+		const name = equals > 0 ? arg.slice(0, equals) : arg;
+		if (![
+			"--scopes",
+			"--scope",
+			"--expires",
+			"--label"
+		].includes(name)) throw new Error(`Unknown token option: ${name}. ${TOKEN_USAGE}`);
+		const value = equals > 0 ? arg.slice(equals + 1) : args[++index];
+		if (value === void 0 || equals < 0 && value.startsWith("--")) throw new Error(`Token option ${name} requires a value. ${TOKEN_USAGE}`);
+		if (name === "--scopes" || name === "--scope") scopes.push(...value.split(/[\s,]+/u).filter(Boolean));
+		else if (name === "--expires") {
+			if (expiresInSeconds !== void 0) throw new Error("Token option --expires was provided more than once.");
+			expiresInSeconds = parseTokenLifetime(value);
+		} else {
+			if (label !== void 0) throw new Error("Token option --label was provided more than once.");
+			label = value;
+		}
+	}
+	if (scopes.length === 0) throw new Error(`At least one scope is required. ${TOKEN_USAGE}`);
+	return {
+		scopes,
+		expiresInSeconds,
+		label
+	};
+}
+function printJson(context, value) {
+	context.io.stdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+/** Run `smrt app token <args…>` and resolve to the exit code. */
+async function runTokenOperation(context, args) {
+	const [first, ...rest] = args;
+	if (first === "help" || first === "--help" || first === "-h") {
+		context.io.stdout(`${TOKEN_USAGE}\n`);
+		return 0;
+	}
+	const subcommand = first === void 0 || first.startsWith("--") ? "create" : first;
+	const subArgs = subcommand === first ? rest : args;
+	if (![
+		"create",
+		"list",
+		"revoke"
+	].includes(subcommand)) throw new Error(`Unknown token operation: ${subcommand}. ${TOKEN_USAGE}`);
+	const create = subcommand === "create" ? parseCreateArgs(subArgs) : null;
+	if (subcommand === "list" && subArgs.length > 0) throw new Error(`token list takes no arguments. ${TOKEN_USAGE}`);
+	if (subcommand === "revoke" && subArgs.length !== 1) throw new Error(`token revoke takes exactly one token id. ${TOKEN_USAGE}`);
+	await assertLocalOperation(context, "app:token");
+	const open = context.deps.runtime.openLocalMcpTokenStore ?? openLocalMcpTokenStore;
+	const withStore = async (fn) => {
+		const store = await open({
+			appId: context.appId,
+			dataDirectory: process.env.SMRT_DATA_DIR,
+			sourceRoot: context.sourceRoot
+		});
+		try {
+			return await fn(store);
+		} finally {
+			await store.close();
+		}
+	};
+	if (subcommand === "list") {
+		printJson(context, {
+			schemaVersion: 1,
+			status: "ok",
+			tokens: await withStore((store) => store.list()),
+			secretValuesIncluded: false
+		});
+		return 0;
+	}
+	return withOperationLock(preparedStateRoot(context), `token-${subcommand}`, async () => {
+		if (create) {
+			const issued = await withStore((store) => store.issue(create));
+			printJson(context, {
+				schemaVersion: 1,
+				status: "issued",
+				id: issued.id,
+				token: issued.token,
+				scopes: issued.scopes,
+				label: issued.label,
+				createdAt: issued.createdAt,
+				expiresAt: issued.expiresAt,
+				notice: "This token is shown once and only its hash is stored. Put it in your MCP client configuration now; revoke it with smrt app token revoke <id>.",
+				secretValuesIncluded: true
+			});
+			return 0;
+		}
+		const id = subArgs[0];
+		printJson(context, {
+			schemaVersion: 1,
+			status: await withStore((store) => store.revoke(id)),
+			id,
+			secretValuesIncluded: false
+		});
+		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",
+	"token [list|revoke <id>] [--scopes ...]": "Local: issue, list, or revoke a scoped bearer token for a local MCP client",
+	"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."),
+		...error instanceof ApplicationStartError ? {
+			output: boundedTail(redactSecrets(error.output, process.env, { strict: true }), START_OUTPUT_TAIL_BYTES),
+			logFile: error.logFile
+		} : {},
+		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",
+	"token",
+	"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)),
+		operatorTerminal: options.io ? options.io.operatorTerminal : process.stderr.isTTY && process.stdout.isTTY ? (text) => void process.stderr.write(text) : void 0
+	};
+	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 === "dev" ? ["dev", ...devServerArguments(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 (operation === "token") return await runTokenOperation(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 { assertExternalArtifactPath as A, prepareMigration as C, cliExecutablePath as D, validateMcpAppsIfPresent as E, AppCommandError as F, ApplicationStartError as I, errorCode as L, resolveApplicationId as M, resolveApplicationStateRoot as N, runtimeEnvironment as O, runtimeConfigurationFingerprint as P, redactSecrets as R, launchVite as S, runWorker as T, sendTerminationSignal as _, renderAppHelp as a, ViteLauncherError as b, parseTokenLifetime as c, START_OUTPUT_TAIL_BYTES as d, runApplicationOperation as f, readOwnedProcess as g, matchesApplicationProcess as h, errorEnvelope as i, prepareApplicationStateRoot as j, webLauncherPath as k, runTokenOperation as l, checkOwnedProcess as m, APP_RECOVERY as n, runAppCommand as o, WEB_LAUNCHER_NAME as p, cli_exports as r, TOKEN_USAGE as s, APP_COMMANDS as t, APP_OPERATIONS as u, verifyOwnedProcess as v, resolveViteEntry as w, devServerArguments as x, writeProcessRecord as y };