@happyvertical/smrt-cli 0.51.39 → 0.52.0

package/dist/commands/tenant-natural-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-natural-keys.d.ts","sourceRoot":"","sources":["../../src/commands/tenant-natural-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,yEAAyE;AACzE,KAAK,aAAa,GAAG;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG;IAAE,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,EAAE,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,eAAe,GAAG,sBAAsB,GAAG,uBAAuB,CAAC;KAC1E,CAAC;CACH;AAMD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,GAC9C,uBAAuB,EAAE,CAwG3B"}

package/dist/commands/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../../src/commands/utilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../../src/commands/utilities.ts"],"names":[],"mappings":"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"}

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

@@ -13,7 +13,7 @@ import { createLogger } from "@happyvertical/logger";
 import glob from "fast-glob";
 import { createHash } from "node:crypto";
 import { getPackageConfig } from "@happyvertical/smrt-config";
-import { toSnakeCase } from "@happyvertical/smrt-core/utils";
+import { toSnakeCase as toSnakeCase$1 } from "@happyvertical/smrt-core/utils";
 import { checkKnowledgeGraphFreshness, discoverScopedPackageDirectories, readAgentModuleDocs, readPackageAgentDoc, resolveAgentModuleDocPaths } from "@happyvertical/smrt-core/knowledge";
 import { MCPGenerator } from "@happyvertical/smrt-core/generators";
 import { generateDeclarationsFromCLI } from "@happyvertical/smrt-core/prebuild";
@@ -767,7 +767,8 @@ function partitionSchemaChanges(changes, getClassForTable) {
 					...change.foreignKey ? { foreignKey: change.foreignKey } : {},
 					...change.orphanBlocked !== void 0 ? { orphanBlocked: change.orphanBlocked } : {},
 					...change.orphanNullable !== void 0 ? { orphanNullable: change.orphanNullable } : {},
-					...change.engineUnsupported !== void 0 ? { engineUnsupported: change.engineUnsupported } : {}
+					...change.engineUnsupported !== void 0 ? { engineUnsupported: change.engineUnsupported } : {},
+					...change.note ? { note: change.note } : {}
 				};
 				if (isAdvisoryOnlyChangeLike(change)) manualInterventions.push(action);
 				else migrations.push(action);
@@ -833,7 +834,8 @@ function partitionSchemaChanges(changes, getClassForTable) {
 						actual: mm.actual
 					},
 					sql: change.sql,
-					...change.sqlStatements ? { sqlStatements: change.sqlStatements } : {}
+					...change.sqlStatements ? { sqlStatements: change.sqlStatements } : {},
+					...change.note ? { note: change.note } : {}
 				};
 				const executionKind = classifyTypeUpgradeSql(change.sql);
 				if (executionKind === "executable") migrations.push(action);
@@ -1230,6 +1232,11 @@ var dbDiffCommand = {
 			description: "Include orphan-index drops in the diff (indexes in DB but not in the manifest, excluding *_pkey/*_key implicit-from-constraint indexes). Off by default for safety.",
 			default: false
 		},
+		"drop-legacy-natural-key": {
+			type: "boolean",
+			description: "Include the drop of the legacy global (slug, context) unique index a tenant-led natural key superseded (see db:migrate --drop-legacy-natural-key).",
+			default: false
+		},
 		"drop-columns": {
 			type: "boolean",
 			description: "Include orphan-column drops in the diff (columns in DB but not in the manifest). Off by default; orphans are always reported.",
@@ -1243,6 +1250,11 @@ var dbDiffCommand = {
 		"postgres-timestamp-legacy-timezone": {
 			type: "string",
 			description: "Confirm that legacy PostgreSQL timestamp-without-time-zone values are UTC wall times before previewing their conversion to timestamptz. Exact value required: UTC; omitted by default."
+		},
+		"empty-text-as-null": {
+			type: "boolean",
+			description: "Preview storing empty or whitespace-only text as NULL when converging a nullable legacy text column to a typed column (timestamp, JSON, integer). Any other value that does not convert still blocks. Off by default; the diff names the empty-text count instead.",
+			default: false
 		}
 	},
 	handler: async (_args, options) => {
@@ -1298,8 +1310,10 @@ var dbDiffCommand = {
 				includeDroppedTables: false,
 				includeDroppedColumns: Boolean(options["drop-columns"]),
 				includeDroppedIndexes: Boolean(options["drop-indexes"]),
+				dropLegacyNaturalKey: Boolean(options["drop-legacy-natural-key"]),
 				relaxColumns: Boolean(options["relax-columns"]),
-				postgresTimestampMigration
+				postgresTimestampMigration,
+				emptyTextAsNull: Boolean(options["empty-text-as-null"])
 			}).compare(schemaDefinitions);
 			if (options.json) {
 				console.log(JSON.stringify({
@@ -1394,9 +1408,21 @@ var dbDiffCommand = {
 			}
 			if (typeUpgrades.length > 0) {
 				console.log(`  🔁 Type upgrades (${typeUpgrades.length}):`);
-				for (const change of typeUpgrades) console.log(`     ⤴ ${change.table}.${change.name}: ${change.mismatch?.actual} → ${change.mismatch?.expected}`);
+				for (const change of typeUpgrades) {
+					console.log(`     ⤴ ${change.table}.${change.name}: ${change.mismatch?.actual} → ${change.mismatch?.expected}`);
+					if (change.note) console.log(`       (${change.note})`);
+				}
 				console.log("     (auto-applied by smrt db:migrate)\n");
 			}
+			const foreignKeyChanges = diff.changes.filter((c) => c.type === "add_foreign_key" && (c.sql || c.sqlStatements?.length));
+			if (foreignKeyChanges.length > 0) {
+				console.log(`  🔗 Foreign keys (${foreignKeyChanges.length}):`);
+				for (const change of foreignKeyChanges) {
+					console.log(`     + ${change.name} on ${change.table}${change.note ? ` (${change.note})` : ""}`);
+					if (change.advisory?.severity === "warning") console.log(`       ⚠️  ${change.advisory.message}`);
+				}
+				console.log();
+			}
 			if (typeMismatches.length > 0) {
 				console.log(`  ⚠️  Type mismatches (${typeMismatches.length}):`);
 				for (const change of typeMismatches) console.log(`     ! ${change.table}.${change.name}: ${change.mismatch?.expected} vs ${change.mismatch?.actual}`);
@@ -1581,6 +1607,11 @@ var dbHistoryCommand = {
 			description: "Show full details including checksums",
 			default: false,
 			short: "v"
+		},
+		"empty-text-as-null": {
+			type: "boolean",
+			description: "Assess the same convergence `db:migrate --empty-text-as-null` would apply: a nullable legacy text column whose only obstacle is empty or whitespace-only text is pending, not blocked. Off by default.",
+			default: false
 		}
 	},
 	handler: async (_args, options) => {
@@ -1619,7 +1650,7 @@ var dbHistoryCommand = {
 			if (failedHistory.length > 0 && typeof db.getTableSchema === "function") try {
 				await autoDiscoverAndLoad();
 				const manifestSchemas = ObjectRegistry.getAllSchemasAsDefinitions();
-				const diff = await new SchemaComparer(db).compare(manifestSchemas);
+				const diff = await new SchemaComparer(db, { emptyTextAsNull: Boolean(options["empty-text-as-null"]) }).compare(manifestSchemas);
 				liveSchemaCompared = true;
 				failedAssessments = assessFailedMigrations(failedHistory, diff);
 			} catch {
@@ -2868,7 +2899,7 @@ async function evaluateSchemaContract(options) {
 			present = (await ObjectRegistry.getAllFields(entry.name)).has(fieldName);
 			if (present) {
 				table = inferTableName(entry);
-				column = toSnakeCase(fieldName);
+				column = toSnakeCase$1(fieldName);
 				if (table) {
 					inferredTables.add(table);
 					inferredColumns.add(`${table}.${column}`);
@@ -2928,6 +2959,99 @@ function assertSchemaContract(report) {
 	if (!report.ok) throw new SchemaContractError(report);
 }
 //#endregion
+//#region src/commands/tenant-natural-keys.ts
+/**
+* Tenant natural-key detector for `db:status`.
+*
+* A tenant-owned table (declared tenant scope, or an undeclared `tenantId`
+* field — `ObjectRegistry.getOwnershipTenantColumn()`) upserts on a
+* tenant-led key such as `(tenant_id, slug, context)`. A live database created
+* before that default can still carry the GLOBAL `(slug, context)` unique:
+* then a second tenant's same-slug save collides with a row it cannot see.
+* Before the save-time ownership guard, `ON CONFLICT … DO UPDATE` rewrote that
+* row's `id` and `tenant_id` (the Anytown Ludis takeover); now the save is
+* refused, and on engines that require an exact ON CONFLICT target the create
+* fails until `smrt db:migrate` swaps the index.
+*
+* Rollout is expand, then contract: `smrt db:migrate` builds the tenant-led
+* unique beside the global one (an `error` until it exists, so db:status exits
+* 1), and the global one stays — reported as a `warning` — until
+* `smrt db:migrate --drop-legacy-natural-key` once no old code is running.
+* Explicit `@smrt({ conflictColumns })` that omit the tenant column are the
+* author's declared contract and are not reported here (the tenancy
+* package's `auditTenantScopedRegistrations()` flags runtime-registered ones).
+*/
+function sameColumnSet(a, b) {
+	return a.length === b.length && a.every((column) => b.includes(column));
+}
+/**
+* Compare every tenant-owned table's upsert target with its live unique
+* indexes. Tables absent from `liveSchemas` (not created yet, or not
+* introspected) are skipped — the schema diff reports those.
+*/
+function checkTenantNaturalKeyUniques(liveSchemas) {
+	const findings = [];
+	const seenTables = /* @__PURE__ */ new Set();
+	for (const className of ObjectRegistry.getQualifiedClassNames()) {
+		if (isCollectionRegistration(className)) continue;
+		const tableName = ObjectRegistry.getTableName(className);
+		if (!tableName || seenTables.has(tableName)) continue;
+		const tenantColumn = ObjectRegistry.getOwnershipTenantColumn(className);
+		if (!tenantColumn) continue;
+		const conflictColumns = ObjectRegistry.getConflictColumns(className);
+		if (!conflictColumns.includes(tenantColumn)) continue;
+		const live = liveSchemas.get(tableName);
+		if (!live) continue;
+		seenTables.add(tableName);
+		const uniques = (live.indexes ?? []).filter((index) => index.unique === true && !index.where);
+		const naturalKey = conflictColumns.filter((column) => column !== tenantColumn);
+		const global = uniques.find((index) => sameColumnSet(index.columns ?? [], naturalKey));
+		const target = `(${conflictColumns.join(", ")})`;
+		if (uniques.some((index) => sameColumnSet(index.columns ?? [], conflictColumns))) {
+			if (global) findings.push({
+				name: `${tableName}.${global.name ?? "(unnamed unique)"}`,
+				status: "warning",
+				message: `Tenant-owned table "${tableName}" (${className}) still carries the legacy unique index on (${naturalKey.join(", ")}) beside the tenant-led ${target}. Until it is dropped, a second tenant cannot store a key another tenant already uses (the save fails with a unique violation; nothing is overwritten).`,
+				recommendation: "Once every running instance is on the release that upserts on the tenant-led key, run `smrt db:migrate --drop-legacy-natural-key` to drop it.",
+				details: {
+					className,
+					tableName,
+					conflictColumns,
+					liveIndex: global.name,
+					kind: "legacy_global_unique"
+				}
+			});
+			continue;
+		}
+		if (global) findings.push({
+			name: `${tableName}.${global.name ?? "(unnamed unique)"}`,
+			status: "error",
+			message: `Tenant-owned table "${tableName}" (${className}) has a unique index on (${naturalKey.join(", ")}) shared by every tenant, but the model upserts on ${target}. A second tenant cannot store a key another tenant already uses; saves that collide are refused (TENANT_ISOLATION_VIOLATION), and creates can fail outright until the index matches the upsert target.`,
+			recommendation: "Run `smrt db:migrate` BEFORE deploying the release that upserts on the tenant-led key: it builds the tenant-inclusive unique under its own name (a superset, so it cannot fail on existing rows) and keeps this one, so old code (ON CONFLICT on the global key) and new code (ON CONFLICT on the tenant-led key) both keep working. After the rollout, `smrt db:migrate --drop-legacy-natural-key` drops the legacy index.",
+			details: {
+				className,
+				tableName,
+				conflictColumns,
+				liveIndex: global.name,
+				kind: "global_unique"
+			}
+		});
+		else findings.push({
+			name: `${tableName}.${target}`,
+			status: "warning",
+			message: `Tenant-owned table "${tableName}" (${className}) has no unique index on ${target}, the key the model upserts on.`,
+			recommendation: "Run `smrt db:migrate` to create the tenant-inclusive unique index.",
+			details: {
+				className,
+				tableName,
+				conflictColumns,
+				kind: "missing_tenant_unique"
+			}
+		});
+	}
+	return findings;
+}
+//#endregion
 //#region src/commands/db-status.ts
 /**
 * db:status Command
@@ -3148,6 +3272,11 @@ var dbStatusCommand = {
 			description: "Also compare the live schema to the expected shape (incl. _smrt_* system tables and index policy)",
 			default: false,
 			short: "p"
+		},
+		"empty-text-as-null": {
+			type: "boolean",
+			description: "Assess the same convergence `db:migrate --empty-text-as-null` would apply: a nullable legacy text column whose only obstacle is empty or whitespace-only text is pending, not blocked. Off by default.",
+			default: false
 		}
 	},
 	handler: async (_args, options) => {
@@ -3246,16 +3375,16 @@ var dbStatusCommand = {
 			const manifestSchemas = ObjectRegistry.getAllSchemasAsDefinitions();
 			let comparer;
 			if (typeof db.getTableSchema === "function") {
-				comparer = new SchemaComparer(db);
+				comparer = new SchemaComparer(db, { emptyTextAsNull: Boolean(options["empty-text-as-null"]) });
 				diff = await comparer.compare(manifestSchemas);
 				status.drift = summarizeSchemaDiff(diff);
 				status.notes = summarizeSchemaNotes(diff);
-				status.preconditions = await checkTenantIdUuidPreconditions({
+				status.preconditions = [...await checkTenantIdUuidPreconditions({
 					db,
 					dbType,
 					dbUrl,
 					manifestSchemas
-				});
+				}), ...checkTenantNaturalKeyUniques(comparer.getLiveSchemaSnapshot())];
 				status.failedMigrations = summarizeFailedMigrations(failed, getUnresolvedGeneratedMigrationNames(diff.changes));
 				if (options.parity) try {
 					status.parity = await checkLiveSchemaParity({
@@ -4139,14 +4268,14 @@ var docsCommands = {
 * This replaces per-agent export commands (praeco export, caelus export, etc.)
 * with a single, schema-driven export that respects field-level export annotations.
 */
-function toSnakeCase$1(str) {
+function toSnakeCase$2(str) {
 	return str.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
 }
 function toColumnName(fieldName) {
 	const dotIndex = fieldName.indexOf(".");
 	const baseFieldName = dotIndex >= 0 ? fieldName.substring(0, dotIndex) : fieldName;
 	const jsonPath = dotIndex >= 0 ? fieldName.substring(dotIndex) : "";
-	return `${baseFieldName.startsWith("_") ? `_${toSnakeCase$1(baseFieldName.slice(1))}` : toSnakeCase$1(baseFieldName)}${jsonPath}`;
+	return `${baseFieldName.startsWith("_") ? `_${toSnakeCase$2(baseFieldName.slice(1))}` : toSnakeCase$2(baseFieldName)}${jsonPath}`;
 }
 function assertSafeIdentifier(identifier, label) {
 	if (!/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$/.test(identifier)) throw new Error(`Invalid ${label}: ${identifier}`);
@@ -6948,7 +7077,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-iMaSv6C_.js");
+			const { materializeTenantHierarchy, TenantHierarchyMaterializationError } = await import("./dist-vJJL0WMc.js");
 			db = await getDatabase({
 				type: dbType,
 				url: config.database.url
@@ -7157,7 +7286,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-C8sNOzr2.js");
+			const { migrateLedgerAccountsTable, planLedgerAccountsTableMove } = await import("./dist-Dm4q4uB4.js");
 			db = await getDatabase({
 				type: dbType,
 				url: config.database.url
@@ -9876,7 +10005,7 @@ export default testManifest;
 				}
 			}
 			try {
-				const { resolveDataPath, discoverJsonFiles, JsonDatabaseValidator, displayValidationResults } = await import("./json-validator-oEN7eUI3.js");
+				const { resolveDataPath, discoverJsonFiles, JsonDatabaseValidator, displayValidationResults } = await import("./json-validator-BiAdsE1O.js");
 				const dataPath = await resolveDataPath(options.data);
 				if (!dataPath) {
 					console.error("\n❌ Could not find data directory");
@@ -9998,6 +10127,11 @@ export default testManifest;
 				type: "string",
 				description: "Confirm that legacy PostgreSQL timestamp-without-time-zone values are UTC wall times before converting them to timestamptz. Exact value required: UTC; omitted by default."
 			},
+			"empty-text-as-null": {
+				type: "boolean",
+				description: "Store empty or whitespace-only text as NULL when converging a nullable legacy text column to a typed column (timestamp, JSON, integer). Any other value that does not convert still blocks, and NOT NULL columns are never changed. Off by default.",
+				default: false
+			},
 			force: {
 				type: "boolean",
 				description: "Force re-apply even if already applied (skip checksum validation)",
@@ -10023,6 +10157,11 @@ export default testManifest;
 				description: "Drop orphan indexes (in DB but not in manifest, excluding *_pkey/*_key implicit-from-constraint indexes). Off by default.",
 				default: false
 			},
+			"drop-legacy-natural-key": {
+				type: "boolean",
+				description: "Drop the legacy global (slug, context) unique index a tenant-led natural key superseded on a table that is tenant-owned by its tenantId field. Off by default: db:migrate builds the tenant-led index beside it so code still on the previous release keeps upserting. Pass this once every instance runs the release that upserts on the tenant-led key.",
+				default: false
+			},
 			"drop-columns": {
 				type: "boolean",
 				description: "DESTRUCTIVE: drop orphan columns (in DB but not in manifest). Off by default; orphans are always reported.",
@@ -10171,8 +10310,10 @@ export default testManifest;
 				const diff = await new SchemaComparer(db, {
 					includeDroppedIndexes: Boolean(options["drop-indexes"]),
 					includeDroppedColumns: Boolean(options["drop-columns"]),
+					dropLegacyNaturalKey: Boolean(options["drop-legacy-natural-key"]),
 					relaxColumns: Boolean(options["relax-columns"]),
-					postgresTimestampMigration
+					postgresTimestampMigration,
+					emptyTextAsNull: Boolean(options["empty-text-as-null"])
 				}).compare(manifestSchemas);
 				const engine = tracker.getEngine();
 				const tablePlan = planForeignKeyCreation(diff.added_tables, engine);
@@ -10255,6 +10396,12 @@ export default testManifest;
 					pendingOrphanDispositions.length = 0;
 					pendingOrphanDispositions.push(...stillPending);
 				}
+				const destructiveForeignKeys = migrations.filter((migration) => migration.type === "add_foreign_key" && migration.advisory?.severity === "warning" && Boolean(migration.sql || migration.sqlStatements?.length));
+				if (destructiveForeignKeys.length > 0) {
+					console.log(`\n⚠️  ${destructiveForeignKeys.length} foreign-key change(s) make deletes DESTRUCTIVE:`);
+					for (const migration of destructiveForeignKeys) console.log(`   ${migration.advisory?.message}`);
+					console.log();
+				}
 				const preForeignKeyMigrations = migrations.filter((migration) => migration.phase === "pre_foreign_key");
 				const remainingMigrations = migrations.filter((migration) => migration.phase !== "pre_foreign_key");
 				assertForceMigrationTargetsExist(forceSelection.forceMigrations, [
@@ -10407,7 +10554,7 @@ export default testManifest;
 							actionDesc = `Dropped column ${migration.tableName}.${migration.columnName}`;
 						} else if (migration.type === "type_upgrade" && migration.column) {
 							migrationSql = migration.sql || "";
-							actionDesc = `Upgraded column ${migration.tableName}.${migration.column.name} from ${migration.mismatch?.actual} to ${migration.mismatch?.expected}`;
+							actionDesc = `Upgraded column ${migration.tableName}.${migration.column.name} from ${migration.mismatch?.actual} to ${migration.mismatch?.expected}${migration.note ? ` (${migration.note})` : ""}`;
 						} else if (migration.type === "add_index" && migration.index) {
 							migrationSql = migration.sql || "";
 							actionDesc = `Created index ${migration.index.name} on ${migration.tableName}`;
@@ -10416,7 +10563,7 @@ export default testManifest;
 							actionDesc = `Dropped index ${migration.indexName} on ${migration.tableName}`;
 						} else if (migration.type === "add_foreign_key") {
 							migrationSql = migration.sql || "";
-							actionDesc = `Added foreign-key constraint on ${migration.tableName}`;
+							actionDesc = migration.note ? `Replaced foreign-key constraint on ${migration.tableName} (${migration.note})` : `Added foreign-key constraint on ${migration.tableName}`;
 						} else if (migration.type === "drop_foreign_key") {
 							migrationSql = migration.sql || "";
 							actionDesc = `Dropped foreign-key constraint on ${migration.tableName}`;