@happyvertical/smrt-cli 0.40.21 → 0.40.23

package/README.md

@@ -55,6 +55,27 @@ reconciles live schema drift. Global `--force` remains available by itself for
 backward compatibility but intentionally overrides guards for the whole pending
 batch.
 
+### Audited PostgreSQL timestamp conversion
+
+`timestamp without time zone` values do not carry enough information for SMRT
+to infer their original instant. After auditing every historical writer,
+database default, trigger, and raw SQL path, an operator may confirm that the
+legacy values are UTC wall times and include the exact opt-in:
+
+```bash
+smrt db:migrate --postgres-timestamp-legacy-timezone UTC
+```
+
+The option has no default and rejects every value other than `UTC`. On
+PostgreSQL, it allows the manifest-owned timestamp columns to be converted to
+`timestamptz` with `USING column AT TIME ZONE 'UTC'`, preserving the proven UTC
+instants. It is not safe for a database with any local-time writer; use an
+application-owned, provenance-aware migration in that case. Rehearse against a
+restored clone and keep a verified backup because type upgrades have no
+automatic down migration. `smrt db:diff --postgres-timestamp-legacy-timezone
+UTC` and `smrt db:migrate --dry-run --postgres-timestamp-legacy-timezone UTC`
+both preview the same conversion without writing it.
+
 ### Code Generation
 
 | Command | Description |

package/dist/{commands-mHvAZYmi.js → commands-CR1RZCYu.js}

@@ -12,6 +12,7 @@ import { createLogger } from "@happyvertical/logger";
 import glob from "fast-glob";
 import { createHash } from "node:crypto";
 import { toSnakeCase } from "@happyvertical/smrt-core/utils";
+import { readAgentModuleDocs } from "@happyvertical/smrt-core/knowledge";
 import { MCPGenerator } from "@happyvertical/smrt-core/generators";
 import { generateDeclarationsFromCLI } from "@happyvertical/smrt-core/prebuild";
 import { execSync, spawn, spawnSync } from "node:child_process";
@@ -408,6 +409,20 @@ async function autoDiscoverAndLoad(projectRoot = process.cwd()) {
 	};
 }
 //#endregion
+//#region src/commands/postgres-timestamp-migration.ts
+/**
+* Fail-closed confirmation shared by PostgreSQL schema preview and migration.
+*
+* A `timestamp without time zone` value cannot establish its own original
+* instant. Callers must therefore make the same explicit UTC provenance
+* confirmation whether they are previewing or applying the conversion.
+*/
+function resolvePostgresTimestampMigration(legacyTimezone) {
+	if (legacyTimezone === void 0) return;
+	if (legacyTimezone !== "UTC") throw new Error("--postgres-timestamp-legacy-timezone must be exactly UTC; refusing to infer the offset of legacy PostgreSQL timestamps");
+	return { legacyTimezone: "UTC" };
+}
+//#endregion
 //#region src/commands/db-diff.ts
 /**
 * db:diff Command
@@ -463,11 +478,16 @@ var dbDiffCommand = {
 			type: "boolean",
 			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
+		},
+		"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."
 		}
 	},
 	handler: async (_args, options) => {
 		let db;
 		try {
+			const postgresTimestampMigration = resolvePostgresTimestampMigration(options["postgres-timestamp-legacy-timezone"]);
 			const unsupportedFileOptions = [
 				"generate",
 				"name",
@@ -516,7 +536,8 @@ var dbDiffCommand = {
 			const diff = await new SchemaComparer(db, {
 				includeDroppedTables: false,
 				includeDroppedColumns: false,
-				includeDroppedIndexes: Boolean(options["drop-indexes"])
+				includeDroppedIndexes: Boolean(options["drop-indexes"]),
+				postgresTimestampMigration
 			}).compare(schemaDefinitions);
 			if (options.json) {
 				console.log(JSON.stringify({
@@ -2373,8 +2394,11 @@ function createDocsCommand(config) {
 				console.log(`   ${totalPackages} packages documented`);
 				if (packages.length > 0) console.log(`   ${packages.length} SMRT packages`);
 				if (sdkPackages.length > 0) console.log(`   ${sdkPackages.length} SDK packages`);
-				const withAgentDocs = [...packages, ...sdkPackages].filter((p) => p.agentMd).length;
+				const allPackages = [...packages, ...sdkPackages];
+				const withAgentDocs = allPackages.filter((p) => p.agentMd).length;
 				if (withAgentDocs > 0) console.log(`   ${withAgentDocs} with AGENTS.md`);
+				const moduleDocCount = allPackages.reduce((total, p) => total + (p.moduleDocs?.length ?? 0), 0);
+				if (moduleDocCount > 0) console.log(`   ${moduleDocCount} linked module docs`);
 				if (rootDocs.length > 0) console.log(`   ${rootDocs.length} framework documents included`);
 				console.log("");
 			} catch (error) {
@@ -2474,7 +2498,8 @@ function loadPackageInfo(packagePath, dirName) {
 			readme: existsSync(readmePath) ? readFileSync(readmePath, "utf-8") : null,
 			agentMd: agentDoc.content,
 			claudeMd: agentDoc.content,
-			docSource: agentDoc.source
+			docSource: agentDoc.source,
+			moduleDocs: agentDoc.source === "AGENTS.md" ? readAgentModuleDocs(packagePath, agentDoc.content ?? void 0) : []
 		};
 	} catch {
 		console.warn(`   ⚠️  Could not read package.json for ${dirName}`);
@@ -2553,6 +2578,27 @@ function renderAgentMd(content) {
 	if (h1Match) content = content.slice(h1Match[0].length);
 	return content.trim();
 }
+/**
+* The package's AGENTS.md followed by every module doc it links (#2108).
+* The links stay in the rendered text so a reader can still map a section back
+* to its source path; the bodies follow so nothing is lost downstream.
+*/
+function renderPackageDoc(pkg, lines) {
+	const content = pkg.agentMd ?? pkg.claudeMd;
+	if (!content) {
+		lines.push("*No AGENTS.md found for this package.*");
+		lines.push("");
+		return;
+	}
+	lines.push(renderAgentMd(content));
+	lines.push("");
+	for (const doc of pkg.moduleDocs ?? []) {
+		lines.push(`#### ${doc.path}`);
+		lines.push("");
+		lines.push(renderAgentMd(doc.content));
+		lines.push("");
+	}
+}
 function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt docs:agents") {
 	const lines = [];
 	lines.push("# SMRT Framework Context");
@@ -2596,14 +2642,7 @@ function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt d
 		lines.push("");
 		lines.push(`## ${pkg.name}`);
 		lines.push("");
-		const content = pkg.agentMd ?? pkg.claudeMd;
-		if (content) {
-			lines.push(renderAgentMd(content));
-			lines.push("");
-		} else {
-			lines.push("*No AGENTS.md found for this package.*");
-			lines.push("");
-		}
+		renderPackageDoc(pkg, lines);
 	}
 	if (sdkPackages && sdkPackages.length > 0) {
 		lines.push("---");
@@ -2615,14 +2654,7 @@ function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt d
 			lines.push("");
 			lines.push(`### ${pkg.name}`);
 			lines.push("");
-			const content = pkg.agentMd ?? pkg.claudeMd;
-			if (content) {
-				lines.push(renderAgentMd(content));
-				lines.push("");
-			} else {
-				lines.push("*No AGENTS.md found for this package.*");
-				lines.push("");
-			}
+			renderPackageDoc(pkg, lines);
 		}
 	}
 	lines.push("---");
@@ -7074,6 +7106,10 @@ export default testManifest;
 				description: "Use PostgreSQL-safe operations (CONCURRENTLY for indexes, lock_timeout)",
 				default: false
 			},
+			"postgres-timestamp-legacy-timezone": {
+				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."
+			},
 			force: {
 				type: "boolean",
 				description: "Force re-apply even if already applied (skip checksum validation)",
@@ -7111,6 +7147,7 @@ export default testManifest;
 			let db;
 			try {
 				const forceSelection = resolveForceMigrationSelection(options.force, options["force-migration"]);
+				const postgresTimestampMigration = resolvePostgresTimestampMigration(options["postgres-timestamp-legacy-timezone"]);
 				const { getPackageConfig } = await import("@happyvertical/smrt-config");
 				const { DEFAULT_CLI_CONFIG } = await import("./config-BwrFRL8L.js");
 				const config = getPackageConfig("cli", DEFAULT_CLI_CONFIG);
@@ -7211,7 +7248,10 @@ export default testManifest;
 					console.warn("   Use --repair-data instead.\n");
 				}
 				console.log("🔍 Comparing schemas...\n");
-				const diff = await new SchemaComparer(db, { includeDroppedIndexes: Boolean(options["drop-indexes"]) }).compare(manifestSchemas);
+				const diff = await new SchemaComparer(db, {
+					includeDroppedIndexes: Boolean(options["drop-indexes"]),
+					postgresTimestampMigration
+				}).compare(manifestSchemas);
 				const getClassForTable = (tableName) => {
 					for (const className of initOrder) if (ObjectRegistry.getTableName(className) === tableName) return className;
 					return tableName;

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-cli",
-  "version": "0.40.21",
+  "version": "0.40.23",
   "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.40.21",
-    "@happyvertical/smrt-agents": "0.40.21",
-    "@happyvertical/smrt-config": "0.40.21",
-    "@happyvertical/smrt-playground": "0.40.21",
-    "@happyvertical/smrt-dev-mcp": "0.40.21",
-    "@happyvertical/smrt-types": "0.40.21"
+    "@happyvertical/smrt-agents": "0.40.23",
+    "@happyvertical/smrt-config": "0.40.23",
+    "@happyvertical/smrt-dev-mcp": "0.40.23",
+    "@happyvertical/smrt-core": "0.40.23",
+    "@happyvertical/smrt-playground": "0.40.23",
+    "@happyvertical/smrt-types": "0.40.23"
   },
   "devDependencies": {
     "@types/node": "24.13.2",