@happyvertical/smrt-cli 0.43.10 → 0.44.0

package/AGENTS.md

@@ -82,6 +82,58 @@ after that commit. This is the mode for large index rollouts.
 - Without the flag, a batch containing explicit `CONCURRENTLY` DDL is rejected
   before the transaction opens — PostgreSQL cannot run it there.
 
+## `doctor`'s agent-surface section (#2591)
+
+`smrt doctor` reports the application's complete agent-addressable surface —
+generated model tools, declared view intents, registered playbooks — **from
+build artifacts alone**. No route is mounted, no server starts, and no
+application module is imported. That is the whole point: before this, the only
+way to answer "what can an agent do in this app" was to mount every route and
+enumerate, which is not an answer a build, a review, or a CI gate can use.
+
+`readAgentSurfaceReport(cwd)` reads the first of `.smrt/smrt-knowledge.json`
+then `dist/smrt-knowledge.json`. Model tools come from the artifact's `mcp`
+surfaces (REST/CLI entries are not agent-addressable tools and are excluded);
+intents and playbooks come from its `agentSurface`.
+
+**Known under-report, tracked as #2619:** the artifact's `mcp` surfaces come
+from `configuredSurfaces()` in core, which returns nothing when an object omits
+`mcp` config — while `MCPGenerator` treats an omitted config as full CRUD and
+also emits eligible public custom-method tools. Doctor therefore lists fewer
+model tools than the runtime exposes for such an object. The error is
+conservative (it never advertises a tool that does not exist), and the fix
+belongs to the shared surface projection rather than this report.
+`renderAgentSurfaceReport(report)` returns the printed lines; both are exported
+so the shape is testable without running the command.
+
+Sample output:
+
+```text
+🤖 Agent Surface
+
+  Source: .smrt/smrt-knowledge.json
+  Generated model tools: 2
+    - orders_create (Order.create)
+    - orders_list (Order.list)
+  Declared view intents: 1
+    - orders.next_page (read · browser · src/lib/orders.intents.ts)
+  Registered playbooks: 1
+    - commerce.checkout (2 step(s) · browser · src/lib/checkout.playbooks.ts)
+  ✅ 4 agent-addressable operation(s) reported
+```
+
+A declaration the scanner recognized but could not read is listed under
+`⚠️  Not statically emittable` with the message naming `useWebMcpTool`, and
+raises a doctor **warning**, not an issue — a computed tool set is a legitimate
+choice, but it must never vanish unremarked.
+
+Reading an artifact validates its shape, not just its JSON: `{}` parses cleanly
+and would otherwise render as a healthy zero-operation surface while suppressing
+the fallback to a good `dist/` artifact, and `{ "surfaces": {} }` would throw
+mid-report and abort the whole doctor run. A malformed candidate is stepped over
+so the next one is still tried; with no readable artifact at all the section says
+to run a build.
+
 ## Live-schema parity (#2368)
 
 `doctor --db` and `db:status --parity` share `src/commands/db-parity.ts`, which

package/dist/{commands-BoyqL_79.js → commands-DBnnqrFy.js}

@@ -581,7 +581,7 @@ function getUnresolvedGeneratedMigrationNames(changes) {
 	for (const change of changes) {
 		if (change.type !== "add_column" && change.type !== "drop_column" && change.type !== "alter_column" && change.type !== "add_foreign_key" && change.type !== "drop_foreign_key" && change.type !== "add_index" && change.type !== "drop_index" && change.type !== "type_upgrade") continue;
 		if (change.type === "type_upgrade" && classifyTypeUpgradeSql(change.sql) === "noop") continue;
-		if (change.type === "alter_column" && isAdvisoryOnlyChangeLike(change)) continue;
+		if ((change.type === "alter_column" || change.type === "type_upgrade") && isAdvisoryOnlyChangeLike(change)) continue;
 		for (const migrationName of getSyntheticMigrationNamesForChange(change)) names.add(migrationName);
 	}
 	return names;
@@ -765,6 +765,18 @@ function partitionSchemaChanges(changes, getClassForTable) {
 			case "type_upgrade": {
 				const mm = change.mismatch;
 				const col = change.column;
+				if (isAdvisoryOnlyChangeLike(change) && change.advisory) {
+					if (!change.name) continue;
+					advisories.push({
+						type: "type_upgrade",
+						tableName: change.table,
+						className,
+						name: change.name,
+						actual: mm?.actual,
+						advisory: change.advisory
+					});
+					break;
+				}
 				if (!change.name || !mm || !col) continue;
 				const action = {
 					type: "type_upgrade",
@@ -777,6 +789,7 @@ function partitionSchemaChanges(changes, getClassForTable) {
 						defaultValue: col.defaultValue,
 						unique: col.unique
 					},
+					...change.phase ? { phase: change.phase } : {},
 					mismatch: {
 						column: change.name,
 						expected: mm.expected,
@@ -840,6 +853,7 @@ function describeAdvisory(item) {
 	switch (item.type) {
 		case "orphan_column": return `${item.tableName}.${item.name}: orphan column${item.actual ? ` (${item.actual})` : ""}`;
 		case "orphan_index": return `${item.tableName}.${item.name}: unique constraint not in manifest${item.actual ? ` (${item.actual})` : ""}`;
+		case "type_upgrade": return `${item.tableName}.${item.name}: type upgrade blocked${item.actual ? ` (live: ${item.actual})` : ""}`;
 		default: return `${item.tableName}.${item.name}: ${item.alteration ?? "alter_column"}${item.actual ? ` (live: ${item.actual})` : ""}`;
 	}
 }
@@ -7628,6 +7642,99 @@ function getErrorContext(error) {
 	}
 }
 /**
+* Artifacts the surface is read from, in preference order.
+*
+* A dev/build working copy first, then a library build's output. Both are
+* BUILD artifacts — the whole point of the report is that "what can an agent do
+* in this app" is answerable without mounting a route or starting a server
+* (#2591). Nothing here loads application code.
+*/
+var AGENT_SURFACE_ARTIFACTS = [".smrt/smrt-knowledge.json", "dist/smrt-knowledge.json"];
+/**
+* Whether a parsed artifact has the shape this report reads.
+*
+* Deliberately checks the exact fields the report touches — the schema marker,
+* `surfaces`, and, when present, each `agentSurface` list — rather than trusting
+* the type assertion. Everything here comes off disk and may predate the
+* current schema or have been written by something else entirely.
+*/
+function isReadableKnowledgeArtifact(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value;
+	if (record.schemaVersion !== 1) return false;
+	if (!Array.isArray(record.surfaces)) return false;
+	const surface = record.agentSurface;
+	if (surface === void 0) return true;
+	if (!surface || typeof surface !== "object" || Array.isArray(surface)) return false;
+	const agentSurface = surface;
+	return Array.isArray(agentSurface.intents) && Array.isArray(agentSurface.playbooks) && Array.isArray(agentSurface.diagnostics);
+}
+/**
+* Read the complete agent-addressable surface from build artifacts alone.
+*
+* Model tools come from the artifact's emitted `mcp` surfaces, which is where
+* core has always recorded them; intents and playbooks come from the emitted
+* agent surface. They are reported together because an agent does not
+* experience them as three mechanisms — it experiences one list of things it
+* can do.
+*
+* @param cwd - Project root to read artifacts from.
+* @returns The report, or `undefined` when no artifact exists yet.
+*/
+async function readAgentSurfaceReport(cwd) {
+	const { existsSync, readFileSync } = await import("node:fs");
+	const { resolve } = await import("node:path");
+	for (const candidate of AGENT_SURFACE_ARTIFACTS) {
+		const artifactPath = resolve(cwd, candidate);
+		if (!existsSync(artifactPath)) continue;
+		try {
+			const parsed = JSON.parse(readFileSync(artifactPath, "utf-8"));
+			if (!isReadableKnowledgeArtifact(parsed)) continue;
+			const artifact = parsed;
+			const surface = artifact.agentSurface;
+			return {
+				source: candidate,
+				modelTools: (artifact.surfaces ?? []).filter((entry) => entry.kind === "mcp").map((entry) => ({
+					kind: "model tool",
+					name: String(entry.name),
+					detail: `${entry.objectName ?? "?"}.${entry.operation}`
+				})).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+				intents: (surface?.intents ?? []).map((intent) => ({
+					kind: "view intent",
+					name: String(intent.id),
+					detail: `${intent.capability.effect} · ${intent.planes.join("+")} · ${intent.sourceFile}`
+				})),
+				playbooks: (surface?.playbooks ?? []).map((playbook) => ({
+					kind: "playbook",
+					name: String(playbook.key),
+					detail: `${playbook.steps.length} step(s) · ${playbook.planes.join("+")} · ${playbook.sourceFile}`
+				})),
+				notStatic: (surface?.diagnostics ?? []).map((diagnostic) => ({
+					sourceFile: diagnostic.line ? `${diagnostic.sourceFile}:${diagnostic.line}` : String(diagnostic.sourceFile),
+					message: String(diagnostic.message)
+				}))
+			};
+		} catch {}
+	}
+}
+/** Render the surface report as the lines `smrt doctor` prints. */
+function renderAgentSurfaceReport(report) {
+	if (!report) return ["  ⚠️  No knowledge artifact found — run a build to emit the agent surface"];
+	const lines = [`  Source: ${report.source}`];
+	const section = (label, entries) => {
+		lines.push(`  ${label}: ${entries.length}`);
+		for (const entry of entries) lines.push(`    - ${entry.name} (${entry.detail})`);
+	};
+	section("Generated model tools", report.modelTools);
+	section("Declared view intents", report.intents);
+	section("Registered playbooks", report.playbooks);
+	if (report.notStatic.length > 0) {
+		lines.push(`  ⚠️  Not statically emittable: ${report.notStatic.length}`);
+		for (const entry of report.notStatic) lines.push(`    - ${entry.sourceFile}: ${entry.message}`);
+	}
+	return lines;
+}
+/**
 * Utility commands for CLI
 */
 var utilityCommands = {
@@ -8397,6 +8504,8 @@ export default testManifest;
 				migrations.push(...partitionedChanges.migrations);
 				manualInterventions.push(...partitionedChanges.manualInterventions);
 				const advisories = partitionedChanges.advisories;
+				const preForeignKeyMigrations = migrations.filter((migration) => migration.phase === "pre_foreign_key");
+				const remainingMigrations = migrations.filter((migration) => migration.phase !== "pre_foreign_key");
 				assertForceMigrationTargetsExist(forceSelection.forceMigrations, [
 					...diff.added_tables.map((schema) => `create_table_${schema.tableName}`),
 					...migrations.flatMap((migration) => {
@@ -8487,6 +8596,10 @@ export default testManifest;
 							console.log();
 						}
 						console.log("  SQL Statements:\n");
+						for (const m of preForeignKeyMigrations) {
+							const sqlStatements = m.sqlStatements ?? (m.sql ? [m.sql] : []);
+							for (const sql of sqlStatements) console.log(`    ${sql};`);
+						}
 						for (const schema of tablePlan.schemas) {
 							const ddl = plannedTableDDL.get(schema.tableName);
 							if (!ddl) continue;
@@ -8500,7 +8613,7 @@ export default testManifest;
 							const terminator = migration.sql.trimEnd().endsWith(";") ? "" : ";";
 							console.log(`    ${migration.sql}${terminator}`);
 						}
-						for (const m of migrations) {
+						for (const m of remainingMigrations) {
 							const sqlStatements = m.sqlStatements ?? (m.sql ? [m.sql] : []);
 							for (const sql of sqlStatements) console.log(`    ${sql};`);
 						}
@@ -8521,41 +8634,9 @@ export default testManifest;
 				if (applySchemaMigrations && schemaChangeCount > 0) {
 					const migrationDefs = [];
 					const migrationLogs = /* @__PURE__ */ new Map();
-					for (const schema of tablePlan.schemas) {
-						const ddl = plannedTableDDL.get(schema.tableName);
-						if (!ddl) throw new Error(`Cannot create table ${schema.tableName}: planned DDL is unavailable.`);
-						const createTableSql = ddl.createTable || schema.ddl;
-						if (!createTableSql?.trim()) throw new Error(`Cannot create table ${schema.tableName}: schema definition has no generated DDL.`);
-						const migrationName = `create_table_${schema.tableName}`;
-						const fields = Object.keys(schema.columns).length;
-						migrationDefs.push({
-							id: migrationName,
-							description: `Create table ${schema.tableName}`,
-							version: "1.0.0",
-							up: [
-								createTableSql,
-								...ddl.indexes,
-								...ddl.triggers
-							],
-							down: [`DROP TABLE IF EXISTS "${schema.tableName}"`]
-						});
-						migrationLogs.set(migrationName, { successMessage: `Created table ${schema.tableName} (${fields} columns)` });
-					}
-					for (const migration of deferredForeignKeyMigrations) {
+					const pushMigrationDef = (migration) => {
 						const migrationName = getSyntheticMigrationNameForAction(migration);
-						if (!migrationName) continue;
-						migrationDefs.push({
-							id: migrationName,
-							description: `Add deferred foreign-key constraint ${migration.className} on ${migration.tableName}`,
-							version: "1.0.0",
-							up: migration.sql ? [migration.sql] : [],
-							down: []
-						});
-						migrationLogs.set(migrationName, { successMessage: `Added deferred foreign-key constraint ${migration.className} on ${migration.tableName}` });
-					}
-					for (const migration of migrations) {
-						const migrationName = getSyntheticMigrationNameForAction(migration);
-						if (!migrationName) continue;
+						if (!migrationName) return;
 						let migrationSql;
 						let actionDesc;
 						if (migration.type === "add_column" && migration.column) {
@@ -8582,7 +8663,7 @@ export default testManifest;
 						} else if (migration.type === "drop_foreign_key") {
 							migrationSql = migration.sql || "";
 							actionDesc = `Dropped foreign-key constraint on ${migration.tableName}`;
-						} else continue;
+						} else return;
 						const migrationSqlStatements = migration.sqlStatements ?? (migrationSql ? [migrationSql] : []);
 						migrationDefs.push({
 							id: migrationName,
@@ -8595,7 +8676,41 @@ export default testManifest;
 							successMessage: actionDesc,
 							skippedMessage: `${migrationName} already applied`
 						});
+					};
+					for (const migration of preForeignKeyMigrations) pushMigrationDef(migration);
+					for (const schema of tablePlan.schemas) {
+						const ddl = plannedTableDDL.get(schema.tableName);
+						if (!ddl) throw new Error(`Cannot create table ${schema.tableName}: planned DDL is unavailable.`);
+						const createTableSql = ddl.createTable || schema.ddl;
+						if (!createTableSql?.trim()) throw new Error(`Cannot create table ${schema.tableName}: schema definition has no generated DDL.`);
+						const migrationName = `create_table_${schema.tableName}`;
+						const fields = Object.keys(schema.columns).length;
+						migrationDefs.push({
+							id: migrationName,
+							description: `Create table ${schema.tableName}`,
+							version: "1.0.0",
+							up: [
+								createTableSql,
+								...ddl.indexes,
+								...ddl.triggers
+							],
+							down: [`DROP TABLE IF EXISTS "${schema.tableName}"`]
+						});
+						migrationLogs.set(migrationName, { successMessage: `Created table ${schema.tableName} (${fields} columns)` });
 					}
+					for (const migration of deferredForeignKeyMigrations) {
+						const migrationName = getSyntheticMigrationNameForAction(migration);
+						if (!migrationName) continue;
+						migrationDefs.push({
+							id: migrationName,
+							description: `Add deferred foreign-key constraint ${migration.className} on ${migration.tableName}`,
+							version: "1.0.0",
+							up: migration.sql ? [migration.sql] : [],
+							down: []
+						});
+						migrationLogs.set(migrationName, { successMessage: `Added deferred foreign-key constraint ${migration.className} on ${migration.tableName}` });
+					}
+					for (const migration of remainingMigrations) pushMigrationDef(migration);
 					const deferredIndexMigrations = concurrentIndexMode && engine === "postgres" ? buildConcurrentIndexPlan(migrationDefs, true).size : 0;
 					const batchHasIndexDDL = migrations.some((migration) => migration.type === "add_index" || migration.type === "drop_index");
 					console.log(deferredIndexMigrations > 0 ? `🔨 Applying ${schemaChangeCount} schema change(s) (non-index DDL atomically, ${deferredIndexMigrations} index migration(s) CONCURRENTLY)...\n` : `🔨 Applying ${schemaChangeCount} schema change(s) atomically...\n`);
@@ -8939,6 +9054,14 @@ export default testManifest;
 				check("Project manifest readable", false, void 0, "Could not read .smrt/manifest.json to validate external registrations");
 			}
 			console.log();
+			console.log("🤖 Agent Surface\n");
+			const agentSurfaceReport = await readAgentSurfaceReport(cwd);
+			for (const line of renderAgentSurfaceReport(agentSurfaceReport)) console.log(line);
+			if (agentSurfaceReport) {
+				check(`${agentSurfaceReport.modelTools.length + agentSurfaceReport.intents.length + agentSurfaceReport.playbooks.length} agent-addressable operation(s) reported`, true);
+				if (agentSurfaceReport.notStatic.length > 0) check("Agent-surface declarations are all static", false, void 0, `${agentSurfaceReport.notStatic.length} declaration(s) could not be read statically and were excluded — use useWebMcpTool for a computed tool set`);
+			} else check("Agent surface reported", false, void 0, "No knowledge artifact — run a build first");
+			console.log();
 			console.log("🏃 Runtime\n");
 			const runtimeErrors = runtimeCheck.findings.filter((finding) => finding.severity === "error");
 			const runtimeWarnings = runtimeCheck.findings.filter((finding) => finding.severity === "warning");

package/dist/index.js

@@ -49,63 +49,63 @@ var _playgroundCommands = null;
 var _workbenchCommands = null;
 async function getGnodeCommands() {
 	if (!_gnodeCommands) {
-		const { gnodeCommands } = await import("./commands-BoyqL_79.js");
+		const { gnodeCommands } = await import("./commands-DBnnqrFy.js");
 		_gnodeCommands = gnodeCommands;
 	}
 	return _gnodeCommands;
 }
 async function getGitCommands() {
 	if (!_gitCommands) {
-		const { gitCommands } = await import("./commands-BoyqL_79.js");
+		const { gitCommands } = await import("./commands-DBnnqrFy.js");
 		_gitCommands = gitCommands;
 	}
 	return _gitCommands;
 }
 async function getGenerateCommands() {
 	if (!_generateCommands) {
-		const { generateCommands } = await import("./commands-BoyqL_79.js");
+		const { generateCommands } = await import("./commands-DBnnqrFy.js");
 		_generateCommands = generateCommands;
 	}
 	return _generateCommands;
 }
 async function getInitCommands() {
 	if (!_initCommands) {
-		const { initCommands } = await import("./commands-BoyqL_79.js");
+		const { initCommands } = await import("./commands-DBnnqrFy.js");
 		_initCommands = initCommands;
 	}
 	return _initCommands;
 }
 async function getUtilityCommands() {
 	if (!_utilityCommands) {
-		const { utilityCommands } = await import("./commands-BoyqL_79.js");
+		const { utilityCommands } = await import("./commands-DBnnqrFy.js");
 		_utilityCommands = utilityCommands;
 	}
 	return _utilityCommands;
 }
 async function getDispatchCommands() {
 	if (!_dispatchCommands) {
-		const { dispatchCommands } = await import("./commands-BoyqL_79.js");
+		const { dispatchCommands } = await import("./commands-DBnnqrFy.js");
 		_dispatchCommands = dispatchCommands;
 	}
 	return _dispatchCommands;
 }
 async function getDocsCommands() {
 	if (!_docsCommands) {
-		const { docsCommands } = await import("./commands-BoyqL_79.js");
+		const { docsCommands } = await import("./commands-DBnnqrFy.js");
 		_docsCommands = docsCommands;
 	}
 	return _docsCommands;
 }
 async function getPlaygroundCommands() {
 	if (!_playgroundCommands) {
-		const { playgroundCommands } = await import("./commands-BoyqL_79.js");
+		const { playgroundCommands } = await import("./commands-DBnnqrFy.js");
 		_playgroundCommands = playgroundCommands;
 	}
 	return _playgroundCommands;
 }
 async function getWorkbenchCommands() {
 	if (!_workbenchCommands) {
-		const { workbenchCommands } = await import("./commands-BoyqL_79.js");
+		const { workbenchCommands } = await import("./commands-DBnnqrFy.js");
 		_workbenchCommands = workbenchCommands;
 	}
 	return _workbenchCommands;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-cli",
-  "version": "0.43.10",
+  "version": "0.44.0",
   "description": "Developer CLI for SMRT framework - introspection, testing, and project management",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,12 +32,12 @@
     "acorn": "^8.17.0",
     "fast-glob": "3.3.3",
     "tar": "^7.5.19",
-    "@happyvertical/smrt-core": "0.43.10",
-    "@happyvertical/smrt-dev-mcp": "0.43.10",
-    "@happyvertical/smrt-playground": "0.43.10",
-    "@happyvertical/smrt-config": "0.43.10",
-    "@happyvertical/smrt-types": "0.43.10",
-    "@happyvertical/smrt-agents": "0.43.10"
+    "@happyvertical/smrt-agents": "0.44.0",
+    "@happyvertical/smrt-core": "0.44.0",
+    "@happyvertical/smrt-dev-mcp": "0.44.0",
+    "@happyvertical/smrt-config": "0.44.0",
+    "@happyvertical/smrt-types": "0.44.0",
+    "@happyvertical/smrt-playground": "0.44.0"
   },
   "devDependencies": {
     "@types/node": "24.13.2",