@happyvertical/smrt-cli 0.52.0 → 0.53.1

package/dist/{commands-BvcMfEoO.js → commands-DISJzBlT.js}

@@ -2,7 +2,7 @@ import { t as resolveManifestEntryPackageName } from "./index.js";
 import { t as DEFAULT_CLI_CONFIG } from "./config-hqNo4lzH.js";
 import { createRequire } from "node:module";
 import * as fs from "node:fs";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -21,9 +21,10 @@ import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
 import https from "node:https";
 import { homedir, tmpdir } from "node:os";
 import { extract } from "tar";
+import Ajv2020 from "ajv/dist/2020.js";
 import { importWorkspaceModule } from "@happyvertical/smrt-core/utils/import-workspace-module";
 import { renderForeignKeyAddStatements } from "@happyvertical/smrt-core/schema";
-import { FRAMEWORK_BASE_TABLE_NAMES, buildIntegerWidthTableStatements, collectIntegerWidthTargets, collectNullEqualIndexTargets, dropFrameworkBaseTables, migrateNullEqualIndexes, nullEqualIndexStatements, parsePostgresTimeoutMs, planFrameworkBaseTableDrop, preflightIntegerWidthWidening, preflightNullEqualIndexes, widenIntegerColumnsToBigInt } from "@happyvertical/smrt-core/migrations";
+import { FRAMEWORK_BASE_TABLE_NAMES, backfillLegacyQualifiedNames, buildIntegerWidthTableStatements, collectIntegerWidthTargets, collectNullEqualIndexTargets, countLegacyQualifiedNameReferences, dropFrameworkBaseTables, migrateNullEqualIndexes, nullEqualIndexStatements, parsePostgresTimeoutMs, planFrameworkBaseTableDrop, preflightIntegerWidthWidening, preflightNullEqualIndexes, widenIntegerColumnsToBigInt } from "@happyvertical/smrt-core/migrations";
 import { buildArchitectureContext, buildKnowledgeIndex, buildReviewContext, checkKnowledgeFreshness, compactContextResult, diffKnowledgeIndex, renderFreshnessResult, renderKnowledgeIndexMarkdown } from "@happyvertical/smrt-dev-mcp/knowledge";
 import { RUNTIME_TOOLS } from "@happyvertical/smrt-dev-mcp/runtime";
 //#region src/commands/db-command-utils.ts
@@ -5683,6 +5684,19 @@ async function loadGitTemplate(gitUrl) {
 	}
 }
 /**
+* Get the template directory path (for copying overlay files)
+*
+* Prefers the subdir-resolved `__templateRoot` so that subdirectory templates
+* (`github:user/repo/subdir`) overlay from the subdir rather than the repo root.
+* Falls back to `__tempDir` for configs loaded before the field existed.
+*/
+function getGitTemplateDir(config) {
+	const gitConfig = config;
+	const templateRoot = gitConfig.__templateRoot ?? gitConfig.__tempDir;
+	if (!templateRoot) throw new Error("Template was not loaded from git repository");
+	return templateRoot;
+}
+/**
 * Cleanup temporary directory after template is used
 */
 async function cleanupGitTemplate(config) {
@@ -6231,8 +6245,310 @@ async function processPlaceholders(outputDir, config, options) {
 	console.log(`   Processed placeholders in ${replacedCount} files`);
 }
 //#endregion
+//#region src/commands/mcp-apps-packaging.ts
+/**
+* Portable MCP Apps plugin packaging helpers.
+*
+* These helpers intentionally validate distribution metadata only. Runtime
+* MCP extension metadata is owned by the v2 server adapter and is not an
+* install-plugin manifest.
+*/
+var requireSchema = createRequire(import.meta.url);
+var pluginSchema = requireSchema("@happyvertical/smrt-dev-mcp/schemas/agent-plugins-1.0.0/plugin.schema.json");
+var mcpSchema = requireSchema("@happyvertical/smrt-dev-mcp/schemas/agent-plugins-1.0.0/mcp.schema.json");
+var ajv = new Ajv2020({
+	strict: true,
+	allErrors: true
+});
+var validatePluginSchema = ajv.compile(pluginSchema);
+var validateMcpSchema = ajv.compile(mcpSchema);
+var PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+var MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+var CANONICAL_SCOPE_REGISTRY = "@happyvertical:registry=https://npm.happyvertical.com/";
+var SECRET_KEY = /(?:api[_-]?key|secret|token|password|authorization|credential)/i;
+var ENVIRONMENT_CREDENTIAL_FILE = /^\.env(?:\.|$)/;
+var PRIVATE_KEY_CARRIER = /^(?:id_(?:rsa|dsa|ecdsa|ed25519)|private(?:[._-]key)?|.*\.key)$/i;
+var PRIVATE_KEY_HEADER = /-----BEGIN(?: [A-Z0-9]+)* PRIVATE KEY-----/;
+function add(result, code, message) {
+	result.findings.push({
+		code,
+		message
+	});
+}
+function readJson$1(path, result) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		add(result, "json-malformed", `${relative(process.cwd(), path)} is not valid JSON`);
+		return;
+	}
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function safeRelativePath(value, field, root, result) {
+	if (typeof value !== "string" || !value.startsWith("./") || value.includes("\\") || value.split("/").includes("..")) {
+		add(result, "unsafe-path", `${field} must be a root-relative ./ path without parent segments`);
+		return;
+	}
+	const target = resolve(root, value);
+	if (!target.startsWith(`${root}${sep}`)) {
+		add(result, "unsafe-path", `${field} resolves outside the plugin root`);
+		return;
+	}
+	try {
+		const stat = lstatSync(target);
+		if (stat.isSymbolicLink() || !stat.isFile()) add(result, "invalid-resource", `${field} must name a regular file`);
+	} catch {
+		add(result, "missing-resource", `${field} does not exist`);
+	}
+}
+function scanTree(root, current, result) {
+	for (const entry of readdirSync(current, { withFileTypes: true })) {
+		const path = join(current, entry.name);
+		const display = relative(root, path);
+		const stat = lstatSync(path);
+		if (stat.isSymbolicLink()) add(result, "symlink", `${display} is a symbolic link; plugin packages must contain regular files`);
+		else if (stat.isDirectory()) scanTree(root, path, result);
+		else if (stat.isFile()) if (ENVIRONMENT_CREDENTIAL_FILE.test(entry.name) || PRIVATE_KEY_CARRIER.test(entry.name)) add(result, "secret-artifact", `${display} is a credential carrier and cannot be packaged`);
+		else try {
+			if (PRIVATE_KEY_HEADER.test(readFileSync(path, "utf8"))) add(result, "secret-artifact", `${display} contains a private key and cannot be packaged`);
+		} catch {
+			add(result, "artifact-unreadable", `${display} could not be inspected and cannot be packaged`);
+		}
+	}
+}
+function scanSecrets(value, source, result) {
+	if (Array.isArray(value)) {
+		value.forEach((item) => {
+			scanSecrets(item, source, result);
+		});
+		return;
+	}
+	if (!isObject(value)) return;
+	for (const [key, child] of Object.entries(value)) {
+		if (SECRET_KEY.test(key) && typeof child === "string" && child.trim()) add(result, "secret-artifact", `${source} contains a credential-shaped ${key} field`);
+		scanSecrets(child, source, result);
+	}
+}
+function validateServerUrl(value, name, result) {
+	if (typeof value !== "string") return add(result, "server-url", `mcpServers.${name}.url must be a string`);
+	try {
+		const url = new URL(value);
+		const isLoopback = url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "[::1]";
+		if (url.username || url.password) add(result, "server-url", `mcpServers.${name}.url must not contain credentials`);
+		if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) add(result, "server-url", `mcpServers.${name}.url must use HTTPS, except loopback development URLs`);
+	} catch {
+		add(result, "server-url", `mcpServers.${name}.url is not a URL`);
+	}
+}
+/** Validate portable plugin files and the optional OpenAI install extension. */
+function validateMcpAppsPackage(rootPath) {
+	const root = resolve(rootPath);
+	const result = {
+		findings: [],
+		valid: false
+	};
+	try {
+		scanTree(root, root, result);
+	} catch {
+		add(result, "plugin-root", "Plugin root must be a readable directory");
+		return result;
+	}
+	const pluginPath = join(root, "plugin.json");
+	const mcpPath = join(root, "mcp.json");
+	if (!lstatExists(pluginPath)) add(result, "plugin-missing", "plugin.json is required at the plugin root");
+	if (!lstatExists(mcpPath)) add(result, "mcp-missing", "mcp.json is required at the plugin root");
+	const plugin = lstatExists(pluginPath) ? readJson$1(pluginPath, result) : void 0;
+	const mcp = lstatExists(mcpPath) ? readJson$1(mcpPath, result) : void 0;
+	if (plugin !== void 0 && !isObject(plugin)) add(result, "plugin-object", "plugin.json must contain an object");
+	if (mcp !== void 0 && !isObject(mcp)) add(result, "mcp-object", "mcp.json must contain an object");
+	if (plugin !== void 0 && !validatePluginSchema(plugin)) add(result, "plugin-format", "plugin.json violates the pinned Agent Plugins 1.0.0 schema");
+	if (mcp !== void 0 && !validateMcpSchema(mcp)) add(result, "mcp-format", "mcp.json violates the pinned Agent Plugins 1.0.0 schema");
+	if (isObject(plugin)) {
+		scanSecrets(plugin, "plugin.json", result);
+		if (plugin.$schema !== PLUGIN_SCHEMA) add(result, "plugin-schema", `plugin.json.$schema must be ${PLUGIN_SCHEMA}`);
+		if (plugin.extensions !== void 0 && !isObject(plugin.extensions)) add(result, "extensions", "plugin.json.extensions must be an object");
+		const openai = (isObject(plugin.extensions) ? plugin.extensions : void 0)?.["com.openai"];
+		if (openai !== void 0 && !isObject(openai)) add(result, "openai-extension", "extensions.com.openai must be an object");
+		if (isObject(openai)) {
+			if (openai.apps !== void 0) safeRelativePath(openai.apps, "extensions.com.openai.apps", root, result);
+			const ui = openai.interface;
+			if (ui !== void 0 && !isObject(ui)) add(result, "openai-interface", "extensions.com.openai.interface must be an object");
+			if (isObject(ui)) {
+				for (const key of ["composerIcon", "logo"]) if (ui[key] !== void 0) safeRelativePath(ui[key], `extensions.com.openai.interface.${key}`, root, result);
+				if (ui.screenshots !== void 0) if (!Array.isArray(ui.screenshots) || ui.screenshots.some((path) => typeof path !== "string")) add(result, "openai-screenshots", "interface.screenshots must be an array of paths");
+				else ui.screenshots.forEach((path, index) => {
+					safeRelativePath(path, `extensions.com.openai.interface.screenshots[${index}]`, root, result);
+				});
+			}
+		}
+	}
+	if (isObject(mcp)) {
+		scanSecrets(mcp, "mcp.json", result);
+		if (mcp.$schema !== MCP_SCHEMA) add(result, "mcp-schema", `mcp.json.$schema must be ${MCP_SCHEMA}`);
+		if (!isObject(mcp.mcpServers) || Object.keys(mcp.mcpServers).length === 0) add(result, "mcp-servers", "mcp.json requires a non-empty mcpServers object");
+		else for (const [name, server] of Object.entries(mcp.mcpServers)) {
+			if (!name.trim() || !isObject(server)) {
+				add(result, "mcp-server", `mcpServers.${name || "<empty>"} must be an object with a name`);
+				continue;
+			}
+			if (server.type !== "streamable-http") add(result, "mcp-transport", `mcpServers.${name}.type must be streamable-http`);
+			validateServerUrl(server.url, name, result);
+		}
+	}
+	result.valid = result.findings.length === 0;
+	return result;
+}
+function lstatExists(path) {
+	try {
+		return lstatSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+/**
+* Add the public, credential-free SMRT package route to a generated app.
+* A pre-existing scope route is an explicit consumer decision and must not be
+* silently replaced.
+*/
+function configureMcpAppsConsumerRegistry(appRoot) {
+	const npmrcPath = join(resolve(appRoot), ".npmrc");
+	let existing = "";
+	try {
+		const stat = lstatSync(npmrcPath);
+		if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Generated application .npmrc must be a regular file");
+		existing = readFileSync(npmrcPath, "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	const scopeLines = existing.split(/\r?\n/).filter((line) => /^\s*@happyvertical:registry(?:\s|=|$)/.test(line));
+	if (scopeLines.length > 0) {
+		for (const line of scopeLines) {
+			const match = /^\s*@happyvertical:registry\s*=\s*(\S+?)(?:\s+[;#].*)?\s*$/.exec(line);
+			if (!match || match[1] !== "https://npm.happyvertical.com/") throw new Error("Generated application already declares a different or malformed @happyvertical registry; refusing to replace it");
+		}
+		return;
+	}
+	writeFileSync(npmrcPath, `${existing}${existing && !existing.endsWith("\n") ? "\n" : ""}${CANONICAL_SCOPE_REGISTRY}\n`);
+}
+/** Copy the opt-in app route/resources and merge only its declared dependencies. */
+function addMcpAppsRuntime(sourceRoot, appRoot) {
+	const resolvedSource = resolve(sourceRoot);
+	const source = join(lstatSync(resolvedSource).isFile() ? dirname(resolvedSource) : resolvedSource, "mcp-apps-template");
+	const dependencies = JSON.parse(readFileSync(join(source, "package.dependencies.json"), "utf8"));
+	cpSync(join(source, "src"), join(resolve(appRoot), "src"), {
+		recursive: true,
+		force: false,
+		errorOnExist: true
+	});
+	const packagePath = join(resolve(appRoot), "package.json");
+	const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+	packageJson.dependencies = {
+		...packageJson.dependencies,
+		...dependencies
+	};
+	writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+function assertMcpAppsPluginName(name) {
+	if (!validatePluginSchema({
+		$schema: PLUGIN_SCHEMA,
+		name
+	})) throw new Error("Plugin name must satisfy Agent Plugins 1.0.0 (1–64 lowercase letters, digits, dots or hyphens; no repeated separators).");
+}
+/** Create the minimal local portable package. It intentionally has no .app.json: registered IDs are host-owned. */
+function scaffoldMcpAppsPackage(rootPath, name, version = "0.1.0") {
+	assertMcpAppsPluginName(name);
+	const root = resolve(rootPath);
+	mkdirSync(root, { recursive: true });
+	const pluginPath = join(root, "plugin.json");
+	const mcpPath = join(root, "mcp.json");
+	if (lstatExists(pluginPath) || lstatExists(mcpPath)) throw new Error("Refusing to overwrite existing MCP Apps package files");
+	writeFileSync(pluginPath, `${JSON.stringify({
+		$schema: PLUGIN_SCHEMA,
+		name,
+		version,
+		description: "SMRT MCP Apps package",
+		extensions: { "com.openai": { interface: {
+			displayName: name,
+			shortDescription: "SMRT MCP Apps package"
+		} } }
+	}, null, 2)}\n`);
+	writeFileSync(mcpPath, `${JSON.stringify({
+		$schema: MCP_SCHEMA,
+		mcpServers: { smrt: {
+			type: "streamable-http",
+			url: "http://127.0.0.1:3000/api/mcp"
+		} }
+	}, null, 2)}\n`);
+}
+var mcpAppsCommands = {
+	"mcp-apps scaffold": {
+		name: "mcp-apps scaffold",
+		description: "Create opt-in portable MCP Apps plugin metadata for a local SMRT app",
+		options: {
+			"output-dir": {
+				type: "string",
+				description: "Plugin directory (defaults to ./mcp-apps)"
+			},
+			name: {
+				type: "string",
+				description: "Portable plugin name",
+				default: "smrt-app"
+			},
+			version: {
+				type: "string",
+				description: "Portable plugin version",
+				default: "0.1.0"
+			}
+		},
+		handler: async (_args, options) => {
+			const root = typeof options["output-dir"] === "string" ? options["output-dir"] : "./mcp-apps";
+			scaffoldMcpAppsPackage(root, typeof options.name === "string" ? options.name : "smrt-app", typeof options.version === "string" ? options.version : "0.1.0");
+			console.log(`Created portable MCP Apps metadata in ${root}.`);
+			console.log("Mount and authorize the native v2 /api/mcp endpoint before changing the loopback URL.");
+		}
+	},
+	"mcp-apps validate": {
+		name: "mcp-apps validate",
+		description: "Fail closed when portable MCP Apps package metadata is unsafe or incomplete",
+		options: { "output-dir": {
+			type: "string",
+			description: "Plugin directory (defaults to ./mcp-apps)"
+		} },
+		handler: async (_args, options) => {
+			const root = typeof options["output-dir"] === "string" ? options["output-dir"] : "./mcp-apps";
+			const result = validateMcpAppsPackage(root);
+			for (const finding of result.findings) console.error(`${finding.code}: ${finding.message}`);
+			if (!result.valid) throw new Error(`MCP Apps package validation failed with ${result.findings.length} finding(s)`);
+			console.log(`MCP Apps package at ${root} is valid.`);
+		}
+	}
+};
+//#endregion
 //#region src/commands/gnode.ts
 /**
+* Gnode CLI Commands
+*
+* Commands for creating and managing gnodes (federated local knowledge bases)
+*/
+var SCOPED_PACKAGE_NAME = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+function projectIdentity(name, outputDir) {
+	const packagePath = join(outputDir, "package.json");
+	if (existsSync(packagePath)) {
+		const existing = JSON.parse(readFileSync(packagePath, "utf8"));
+		if (typeof existing.name !== "string" || !SCOPED_PACKAGE_NAME.test(existing.name)) throw new Error("Generated applications require a scoped package identity (for example @smrt-app/my-app); rename the existing project before generating into it");
+		return existing.name;
+	}
+	if (SCOPED_PACKAGE_NAME.test(name)) return name;
+	const slug = name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+	if (!slug) throw new Error("MCP Apps project name must contain a package slug");
+	return `@smrt-app/${slug}`;
+}
+function mcpAppsPluginName(packageName) {
+	return packageName.split("/").at(-1) ?? packageName;
+}
+/**
 * Gnode commands for CLI
 */
 var gnodeCommands = {
@@ -6266,6 +6582,10 @@ var gnodeCommands = {
 				type: "string",
 				description: "IANA timezone (e.g., \"America/Edmonton\")",
 				default: "America/Edmonton"
+			},
+			"mcp-apps": {
+				type: "boolean",
+				description: "Add opt-in portable MCP Apps plugin metadata under mcp-apps/"
 			}
 		},
 		handler: async (args, options) => {
@@ -6273,26 +6593,38 @@ var gnodeCommands = {
 			if (!name) throw new Error("Project name is required: smrt gnode create <name>");
 			const outputDir = options.outputDir || `./${name}`;
 			const templateName = options.template || "sveltekit";
+			const mcpApps = options.mcpApps || options["mcp-apps"];
+			const projectName = projectIdentity(name, outputDir);
+			if (mcpApps) assertMcpAppsPluginName(mcpAppsPluginName(projectName));
 			const siteOptions = options.location || options.lat || options.lon ? {
 				location: options.location,
 				latitude: options.lat ? Number(options.lat) : void 0,
 				longitude: options.lon ? Number(options.lon) : void 0,
 				timezone: options.timezone
 			} : void 0;
+			let gitConfig;
 			try {
 				console.log(`🔍 Resolving template: ${templateName}...`);
 				const source = await resolveTemplate(templateName);
 				console.log(`✓ Found template: ${source.type}:${source.location}\n`);
 				const config = await loadTemplate(source);
+				if (source.type === "git") gitConfig = config;
 				await generate(source, config, {
-					name,
+					name: projectName,
 					template: templateName,
 					outputDir,
 					site: siteOptions
 				});
-				if (source.type === "git") await cleanupGitTemplate(config);
+				if (mcpApps || config.name === "sveltekit") configureMcpAppsConsumerRegistry(outputDir);
+				if (mcpApps) {
+					addMcpAppsRuntime(source.type === "git" ? getGitTemplateDir(config) : source.resolved, outputDir);
+					scaffoldMcpAppsPackage(`${outputDir}/mcp-apps`, mcpAppsPluginName(projectName));
+					console.log("✓ Added MCP Apps metadata and the canonical @happyvertical package registry. Configure the authorized v2 MCP endpoint before deployment.");
+				}
 			} catch (error) {
 				throw new Error(`Failed to create gnode: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
+			} finally {
+				if (gitConfig) await cleanupGitTemplate(gitConfig);
 			}
 		}
 	},
@@ -7077,7 +7409,7 @@ var dbMaterializeTenantHierarchyCommand = {
 			if (!config.database?.url || config.database.url === ":memory:") throw new Error("Database configuration required for db:materialize-tenant-hierarchy. Configure database.url in smrt.config.ts (or DATABASE_URL).");
 			const dbType = config.database.type || "sqlite";
 			const { getDatabase } = await import("@happyvertical/sql");
-			const { materializeTenantHierarchy, TenantHierarchyMaterializationError } = await import("./dist-vJJL0WMc.js");
+			const { materializeTenantHierarchy, TenantHierarchyMaterializationError } = await import("./dist-Ws7B05wT.js");
 			db = await getDatabase({
 				type: dbType,
 				url: config.database.url
@@ -7286,7 +7618,7 @@ var dbMigrateLedgerAccountsCommand = {
 			if (dbType !== "postgres") throw new Error("db:migrate-ledger-accounts currently supports PostgreSQL only; no changes were made. See the smrt-ledgers README for SQLite.");
 			await autoDiscoverAndLoad();
 			const { getDatabase } = await import("@happyvertical/sql");
-			const { migrateLedgerAccountsTable, planLedgerAccountsTableMove } = await import("./dist-Dm4q4uB4.js");
+			const { migrateLedgerAccountsTable, planLedgerAccountsTableMove } = await import("./dist-7S5I_gWk.js");
 			db = await getDatabase({
 				type: dbType,
 				url: config.database.url
@@ -8354,6 +8686,139 @@ async function columnIsUuid(db, table, column) {
 	return rows[0]?.data_type === "uuid";
 }
 //#endregion
+//#region src/commands/db-qualified-names.ts
+/**
+* Stored references to deprecated qualified names (#3338).
+*
+* `smrt doctor --db` reports how many rows still store a name a class
+* declared in `@smrt({ previousQualifiedNames })` — the signal that an alias
+* can (or cannot yet) be removed. `smrt db:migrate-qualified-names` is the
+* opt-in, idempotent cleanup; nothing rewrites stored names automatically.
+*/
+async function connect() {
+	const { getPackageConfig } = await import("@happyvertical/smrt-config");
+	const { DEFAULT_CLI_CONFIG } = await import("./config-hqNo4lzH.js").then((n) => n.n);
+	const config = getPackageConfig("cli", DEFAULT_CLI_CONFIG);
+	if (!config.database?.url || config.database.url === ":memory:") throw new Error("No persistent database is configured. Set `database.url` in smrt.config.ts (or DATABASE_URL).");
+	const dbType = config.database.type || "sqlite";
+	const { getDatabase } = await import("@happyvertical/sql");
+	return {
+		db: await getDatabase({
+			type: dbType,
+			url: config.database.url
+		}),
+		dbType,
+		url: config.database.url
+	};
+}
+/**
+* Count stored deprecated qualified names in the configured database.
+* Never throws for an operational problem.
+*/
+async function runLegacyQualifiedNameReport(options = {}) {
+	let db;
+	try {
+		if (options.discover ?? true) await autoDiscoverAndLoad();
+		const connection = await connect();
+		db = connection.db;
+		return {
+			report: await countLegacyQualifiedNameReferences(db, { engineHint: connection.dbType }),
+			error: null
+		};
+	} catch (error) {
+		return {
+			report: null,
+			error: redactConnectionStringsInText(error instanceof Error ? error.message : String(error))
+		};
+	} finally {
+		await closeDatabaseConnection(db);
+	}
+}
+/**
+* Render a legacy-name report as the lines `smrt doctor --db` and
+* `smrt db:migrate-qualified-names` print.
+*
+* A zero count is a removal signal only when it is global and complete: a
+* tenant-scoped count (`tenantId`) or one that skipped untenanted tables
+* never says the aliases are removable. Stored rows are also only half the
+* picture, so every report reminds the operator that source still naming an
+* old name must move first.
+*/
+function formatLegacyQualifiedNameReport(report, options = {}) {
+	if (report.aliases.length === 0) return ["   No class declares previousQualifiedNames."];
+	const scope = options.tenantId !== void 0 ? ` for tenant ${options.tenantId}` : "";
+	const lines = [`   Declared aliases: ${report.aliases.length}`, ...report.aliases.map(({ alias, current }) => `     - ${alias} → ${current}`)];
+	if (report.total > 0) {
+		lines.push(`   ⚠️  ${report.total} stored reference(s)${scope} still use a deprecated name:`);
+		for (const reference of report.references) lines.push(`     - ${reference.table}.${reference.column} = ${reference.alias}: ${reference.count} row(s)`);
+		lines.push("   They keep resolving. Rewrite them early with `smrt db:migrate-qualified-names` (opt-in); keep the aliases until this count is zero.");
+	} else if (options.tenantId !== void 0) lines.push(`   ✅ No counted row${scope} uses a deprecated name. This is a tenant-scoped count, not a removal signal: other tenants and untenanted tables were not counted. Run without --tenant (or \`smrt doctor --db\`) before deciding to remove an alias.`);
+	else if (report.untenantedTables.length > 0) lines.push("   ✅ No counted row uses a deprecated name, but some tables were skipped (below), so this is not a removal signal.");
+	else lines.push("   ✅ No stored row in this database uses a deprecated name. The aliases may be removed in a breaking release once every deployment reports zero and no source still names them.");
+	if (report.untenantedTables.length > 0) lines.push(`   Skipped (no tenant column, not counted): ${report.untenantedTables.join(", ")}`);
+	if (report.missingTables.length > 0) lines.push(`   (not migrated in this database: ${report.missingTables.join(", ")})`);
+	lines.push("   Before removing an alias, also update source still naming an old qualified name (@crossPackageRef / relationship targets, playbook step models) to the current name.");
+	return lines;
+}
+/** `smrt db:migrate-qualified-names` — the opt-in rewrite. */
+var dbMigrateQualifiedNamesCommand = {
+	name: "db:migrate-qualified-names",
+	description: "Rewrite stored deprecated qualified names (declared via @smrt({ previousQualifiedNames })) to current names. Opt-in and idempotent (#3338).",
+	aliases: ["migrate-qualified-names"],
+	args: [],
+	options: {
+		"dry-run": {
+			type: "boolean",
+			description: "Report the rows that would be rewritten without writing.",
+			default: false
+		},
+		tenant: {
+			type: "string",
+			description: "Rewrite only this tenant's rows (tables without a tenant column are skipped)."
+		},
+		force: {
+			type: "boolean",
+			description: "Run again even if this alias set was already recorded.",
+			default: false
+		}
+	},
+	handler: async (_args, options) => {
+		let db;
+		try {
+			await autoDiscoverAndLoad();
+			const connection = await connect();
+			db = connection.db;
+			console.log("\n🏷️  Deprecated qualified-name backfill\n");
+			console.log(`✓ Connected to ${formatDatabaseDisplayUrl(connection.dbType, connection.url)}\n`);
+			const result = await backfillLegacyQualifiedNames(db, {
+				engineHint: connection.dbType,
+				dryRun: options["dry-run"] === true,
+				force: options.force === true,
+				...options.tenant ? { tenantId: options.tenant } : {}
+			});
+			for (const line of formatLegacyQualifiedNameReport(result.before, { ...options.tenant ? { tenantId: options.tenant } : {} })) console.log(line);
+			console.log();
+			if (result.dryRun) {
+				console.log("DRY RUN: no changes made.\n");
+				return;
+			}
+			if (!result.ran) {
+				console.log(result.before.aliases.length === 0 ? "Nothing to do.\n" : `Already applied (${result.backfillName}); pass --force to run again.\n`);
+				return;
+			}
+			for (const reference of result.rewritten) console.log(`✓ ${reference.table}.${reference.column}: ${reference.count} row(s) ${reference.alias} → ${reference.current}`);
+			for (const reference of result.skippedDuplicates) console.log(`⚠️  ${reference.table}.${reference.column}: ${reference.count} row(s) kept as ${reference.alias} — a row with the same identity already uses ${reference.current}. Resolve the duplicates, then re-run.`);
+			if (result.skippedDuplicates.length > 0) process.exitCode = 1;
+			console.log(result.recorded ? `\n✓ Recorded ${result.backfillName}.\n` : "\nNot recorded: references remain.\n");
+		} catch (error) {
+			console.error(`\n❌ Qualified-name backfill failed: ${redactConnectionStringsInText(error instanceof Error ? error.message : String(error))}\n`);
+			process.exitCode = 1;
+		} finally {
+			await closeDatabaseConnection(db);
+		}
+	}
+};
+//#endregion
 //#region src/commands/dev-knowledge.ts
 /**
 * dev:knowledge-* commands
@@ -9547,6 +10012,7 @@ function renderAgentSurfaceReport(report) {
 * Utility commands for CLI
 */
 var utilityCommands = {
+	...mcpAppsCommands,
 	introspect: {
 		name: "introspect",
 		description: "Analyze project and discover SMRT objects",
@@ -10961,6 +11427,11 @@ export default testManifest;
 				check("SMRT objects discovered", false, void 0, "Could not discover manifests");
 			}
 			const runtimeCheck = await runRuntimeCheckSafely(cwd);
+			const mcpAppsPath = resolve(cwd, "mcp-apps");
+			if (existsSync(mcpAppsPath)) {
+				const mcpApps = validateMcpAppsPackage(mcpAppsPath);
+				check("Portable MCP Apps package", mcpApps.valid, mcpApps.findings.map((finding) => `${finding.code}: ${finding.message}`).join("; "));
+			}
 			const projectManifestPath = resolve(cwd, ".smrt", "manifest.json");
 			const registerPath = resolve(cwd, ".smrt", "register.js");
 			if (existsSync(projectManifestPath)) try {
@@ -11026,6 +11497,15 @@ export default testManifest;
 				for (const line of formatPermissionsOutcome(permissions)) console.log(line);
 				if (!permissions.skipped) check("PostgreSQL role permissions", !permissions.error && permissions.plan?.diagnostics.length === 0, permissions.error ?? "PostgreSQL role permissions differ from the configured contract");
 				console.log();
+				console.log("🏷️  Deprecated Qualified Names\n");
+				const legacyNames = await runLegacyQualifiedNameReport({ discover: false });
+				if (!legacyNames.report) check("Deprecated qualified-name references", false, legacyNames.error ?? "Could not count stored references");
+				else {
+					for (const line of formatLegacyQualifiedNameReport(legacyNames.report)) console.log(line);
+					if (legacyNames.report.total > 0) warnings.push(`deprecated qualified names: ${legacyNames.report.total} stored reference(s)`);
+					else passed.push("Deprecated qualified-name references");
+				}
+				console.log();
 			}
 			console.log("━".repeat(50));
 			console.log(`\n📊 Summary\n`);
@@ -11063,6 +11543,7 @@ export default testManifest;
 	"db:migrate-null-equal-indexes": dbMigrateNullEqualIndexesCommand,
 	"db:migrate-agent-schedule-slugs": dbMigrateAgentScheduleSlugsCommand,
 	"db:migrate-ledger-accounts": dbMigrateLedgerAccountsCommand,
+	"db:migrate-qualified-names": dbMigrateQualifiedNamesCommand,
 	"db:materialize-tenant-hierarchy": dbMaterializeTenantHierarchyCommand,
 	"db:drop-framework-base-tables": dbDropFrameworkBaseTablesCommand,
 	"db:orphans": dbOrphansCommand,