@happyvertical/smrt-cli 0.40.70 → 0.41.0

package/AGENTS.md

@@ -17,6 +17,8 @@ smrt db:migrate-uuid         # Convert schema-declared UUID text columns after d
 smrt db:diff                 # Show schema differences without generating migration files
 smrt db:rollback             # Roll back migrations by executing their recorded DOWN
 smrt db:rollback --mark-only # Record-only flip; schema deliberately untouched
+smrt db:prune                # Prune framework system tables to their retention windows
+smrt db:prune --dry-run      # Same predicates, counted rather than deleted
 smrt docs:agents             # Generate .agents/smrt-framework.md
 smrt docs:claude             # Deprecated alias writing .claude/smrt-framework.md
 smrt dev:knowledge-*         # Deterministic agent knowledge index/check/diff
@@ -139,6 +141,26 @@ the exact statement `db:migrate` records for `diff.added_tables`.
 Reverting a non-`create_table` change is a forward operation: update the
 `@smrt` object definitions and run `db:migrate` again.
 
+## `db:prune` is the retention cron entry point (#2375)
+
+Runs `runRetentionSweep()` from `@happyvertical/smrt-core` over every
+framework-owned system table plus every task other installed packages
+registered (`_smrt_jobs`/`_smrt_job_events` from `smrt-jobs`, expired
+sessions/magic-link tokens/CLI-auth requests from `smrt-users`).
+
+- Defaults are the framework's documented retention windows; `retention` in
+  `smrt.config` overrides them persistently, and `--changes-days`,
+  `--usage-days`, `--dispatch-days` override them for one run.
+- `--skip` takes **task** names, not table names — the same names the report
+  and `--json` print, so a package-contributed task is skipped the same way a
+  built-in one is.
+- `--dry-run` counts with the identical predicates instead of deleting; the
+  report says `would prune`.
+- The exit code is non-zero when **any** task failed, so a partial sweep never
+  looks clean to cron. Individual task failures never abort the others.
+- Deployments running a jobs `TaskRunner` already get the same sweep every six
+  hours; this command is for those that do not, and for one-off operator runs.
+
 ## Architecture
 
 - **Lazy command loading**: commands loaded on-demand via dynamic import (~100ms overhead on first use)

package/dist/{commands-Df9OZ6tG.js → commands-DjgCD-0o.js}

@@ -5,7 +5,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFile
 import * as path from "node:path";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { ObjectRegistry, SchemaComparer, checkLiveSchemaParity, createQualifiedName, generateDDLForEngine, getClassName, isQualifiedName, migratePostgresSystemTimestamps, parseQualifiedName, planPostgresSystemTimestampMigrations } from "@happyvertical/smrt-core";
+import { ObjectRegistry, SchemaComparer, checkLiveSchemaParity, createQualifiedName, ensureDeferredSystemTableCompatibility, generateDDLForEngine, getClassName, isQualifiedName, migratePostgresSystemTimestamps, parseQualifiedName, planPostgresSystemTimestampMigrations } from "@happyvertical/smrt-core";
 import { loadExternalManifestSync } from "@happyvertical/smrt-core/manifest";
 import { access, cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createLogger } from "@happyvertical/logger";
@@ -1400,6 +1400,191 @@ function formatDateTime(date) {
 	return date.toISOString().replace("T", " ").substring(0, 19);
 }
 //#endregion
+//#region src/commands/db-prune.ts
+/**
+* Packages that contribute retention tasks by registering them on import.
+*
+* `db:prune` runs in the CLI's own process, so a task only reaches the sweep
+* if this process actually loaded the package that registers it. These are
+* imported optionally — a project that does not depend on jobs or users simply
+* has no jobs or users tasks, which is the correct outcome, not an error.
+*/
+var RETENTION_TASK_PACKAGES = ["@happyvertical/smrt-jobs", "@happyvertical/smrt-users"];
+/**
+* Load every installed package that contributes retention tasks.
+*
+* A rejected import is always treated as "not installed" — this function
+* cannot reliably tell a genuine module-resolution miss apart from a package
+* that resolved but threw during its own top-level evaluation (error shapes
+* differ across bundlers and runtimes, and `importPackage` is caller-supplied
+* for exactly that flexibility). It still logs the message on `stderr`
+* rather than swallowing it outright, so an operator can tell "this project
+* doesn't depend on jobs/users" apart from "smrt-jobs is installed but broke
+* on import" without the sweep itself needing to fail over an optional
+* dependency.
+*
+* @returns The specifiers that loaded, in declaration order.
+*/
+async function loadRetentionTaskPackages(importPackage) {
+	const loaded = [];
+	for (const specifier of RETENTION_TASK_PACKAGES) try {
+		await importPackage(specifier);
+		loaded.push(specifier);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`⚠️  Could not load ${specifier} (${message}). Treating its retention tasks as not contributed — if the package is installed, this may be a real import failure rather than a missing dependency.`);
+	}
+	return loaded;
+}
+/**
+* Merge command-line overrides onto the configured retention policy.
+*
+* `--skip` names tasks, not tables, so it covers both the built-in tables and
+* anything a package registered — the same names `db:prune --json` reports.
+*/
+function buildPrunePolicy(configured, options) {
+	const policy = { ...configured ?? {} };
+	policy.dryRun = options["dry-run"] || (configured?.dryRun ?? false);
+	if (options["changes-days"] !== void 0) policy.changes = {
+		...policy.changes === false ? {} : policy.changes ?? {},
+		maxAgeDays: options["changes-days"]
+	};
+	if (options["usage-days"] !== void 0) policy.aiUsage = {
+		...policy.aiUsage === false ? {} : policy.aiUsage ?? {},
+		maxAgeDays: options["usage-days"]
+	};
+	if (options["dispatch-days"] !== void 0) policy.dispatch = {
+		...policy.dispatch === false ? {} : policy.dispatch ?? {},
+		completedOlderThanDays: options["dispatch-days"]
+	};
+	const skipped = (options.skip ?? "").split(",").map((name) => name.trim()).filter((name) => name.length > 0);
+	for (const name of skipped) switch (name) {
+		case "changes":
+			policy.changes = false;
+			break;
+		case "ai-usage":
+			policy.aiUsage = false;
+			break;
+		case "contexts":
+			policy.contexts = false;
+			break;
+		case "dispatch":
+			policy.dispatch = false;
+			break;
+		default: policy.tasks = {
+			...policy.tasks ?? {},
+			[name]: false
+		};
+	}
+	return policy;
+}
+/** Render a completed sweep as an operator-readable table. */
+function formatSweepResult(result) {
+	const lines = [];
+	const verb = result.dryRun ? "would prune" : "pruned";
+	for (const task of result.tasks) {
+		const status = task.error ? `error: ${task.error}` : task.skipped ? task.skipped : `${verb} ${task.pruned}`;
+		const detail = task.details ? ` (${Object.entries(task.details).map(([key, value]) => `${key}=${value}`).join(", ")})` : "";
+		lines.push(`  ${task.task.padEnd(24)}${status}${detail}`);
+	}
+	lines.push("");
+	lines.push(`  ${"total".padEnd(24)}${verb} ${result.pruned} row(s) in ${result.durationMs}ms`);
+	return lines.join("\n");
+}
+/**
+* Names passed to `--skip` that no task in the completed sweep answered to.
+*
+* A typo and a package that was never installed look identical on the command
+* line, so the command says which names it did not recognize rather than
+* silently doing less than the operator asked for.
+*/
+function unmatchedSkipNames(skip, result) {
+	const known = new Set(result.tasks.map((task) => task.task));
+	return (skip ?? "").split(",").map((name) => name.trim()).filter((name) => name.length > 0 && !known.has(name));
+}
+var dbPruneCommand = {
+	name: "db:prune",
+	description: "Prune framework-owned system tables to their retention windows",
+	args: [],
+	options: {
+		"dry-run": {
+			type: "boolean",
+			description: "Report what would be deleted without deleting it",
+			default: false
+		},
+		json: {
+			type: "boolean",
+			description: "Output as JSON (for CI/cron integration)",
+			default: false,
+			short: "j"
+		},
+		"changes-days": {
+			type: "number",
+			description: "Retention window for _smrt_changes, in days"
+		},
+		"usage-days": {
+			type: "number",
+			description: "Retention window for _smrt_ai_usage, in days"
+		},
+		"dispatch-days": {
+			type: "number",
+			description: "Retention window for completed _smrt_dispatch rows, in days"
+		},
+		skip: {
+			type: "string",
+			description: "Comma-separated task names to skip (changes, ai-usage, contexts, dispatch, …)"
+		}
+	},
+	handler: async (_args, options) => {
+		let db;
+		try {
+			const { getPackageConfig } = await import("@happyvertical/smrt-config");
+			const { DEFAULT_CLI_CONFIG } = await import("./config-BwrFRL8L.js");
+			const config = getPackageConfig("cli", DEFAULT_CLI_CONFIG);
+			if (!config.database?.url) {
+				const message = "Database not configured. Set database.url in smrt.config.ts.";
+				if (options.json) console.log(JSON.stringify({ error: message }));
+				else console.error(`\n❌ ${message}\n`);
+				process.exitCode = 1;
+				return;
+			}
+			const dbUrl = config.database.url;
+			const dbType = config.database.type || "sqlite";
+			const { getDatabase } = await import("@happyvertical/sql");
+			db = await getDatabase({
+				type: dbType,
+				url: dbUrl
+			});
+			const { config: smrtConfig, importOptionalDependency, runRetentionSweep } = await import("@happyvertical/smrt-core");
+			const loaded = await loadRetentionTaskPackages((specifier) => importOptionalDependency(specifier, "Install it in the project to include its retention tasks."));
+			const policy = buildPrunePolicy(smrtConfig.toJSON().retention, options);
+			const result = await runRetentionSweep(db, policy);
+			const unmatched = unmatchedSkipNames(options.skip, result);
+			if (options.json) console.log(JSON.stringify({
+				...result,
+				contributors: loaded,
+				unmatched
+			}, null, 2));
+			else {
+				console.log(`\n🧹 Retention sweep${result.dryRun ? " (dry run)" : ""}\n`);
+				console.log(`Database: ${formatDatabaseDisplayUrl(dbType, dbUrl)}\n`);
+				console.log(formatSweepResult(result));
+				console.log();
+				if (unmatched.length > 0) console.warn(`⚠️  --skip named no known task: ${unmatched.join(", ")}. Check the spelling, or the package that registers it may not be installed.
+`);
+			}
+			if (result.failed) process.exitCode = 1;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			if (options.json) console.log(JSON.stringify({ error: message }));
+			else console.error(`\n❌ Retention sweep failed: ${message}\n`);
+			process.exitCode = 1;
+		} finally {
+			await closeDatabaseConnection(db);
+		}
+	}
+};
+//#endregion
 //#region src/commands/db-rollback.ts
 /**
 * Name prefix of the only migration class `db:migrate` records a DOWN script
@@ -7084,6 +7269,28 @@ function resolveDDLPreviewEngine(dbType) {
 		default: return "sqlite";
 	}
 }
+/**
+* Run the framework's deferred system-table compatibility pass after
+* `db:migrate` has created the tables it reshapes (issue #2376).
+*
+* `_smrt_jobs` and `_smrt_job_events` are dual-owned — created here from the
+* jobs manifest, then given their compatibility columns and indexes by
+* `@happyvertical/smrt-core`. On a fresh install the framework bootstrap runs
+* before those tables exist, so without this call the pass would first become
+* reachable at the next process start.
+*
+* Best-effort: the pass is idempotent and re-runs on the next boot, so a
+* failure here must not fail an otherwise-successful migration.
+*/
+async function settleDeferredCompatibilityAfterMigrate(db, dbType, { verbose }) {
+	try {
+		const { settled } = await ensureDeferredSystemTableCompatibility(db, dbType);
+		if (verbose) console.log(settled ? "Deferred system-table compatibility settled (_smrt_jobs, _smrt_job_events)\n" : "Deferred system-table compatibility pending (jobs tables not present)\n");
+	} catch (error) {
+		console.warn(`⚠️  Deferred system-table compatibility did not complete: ${error instanceof Error ? error.message : String(error)}`);
+		console.warn("   It will be retried the next time the framework starts.\n");
+	}
+}
 function formatStiConflictIdentity(conflict) {
 	const entries = Object.entries(conflict.conflictIdentity);
 	return `${entries.length > 0 ? entries.map(([column, value]) => `${column}=${JSON.stringify(value)}`).join(", ") : "no non-_meta_type conflict columns"}${conflict.legacyId || conflict.qualifiedId ? ` (legacy id: ${conflict.legacyId ?? "unknown"}, qualified id: ${conflict.qualifiedId ?? "unknown"})` : ""}`;
@@ -7175,7 +7382,7 @@ function resolveDeclaredViteMajor(packageJson) {
 function assessDecoratorSupport(input) {
 	const { viteMajor, viteConfigContent, tsconfigContent } = input;
 	const hasOxcDecorator = viteConfigContent !== null && OXC_DECORATOR_BLOCK_RE.test(viteConfigContent);
-	const hasTsconfigDecorators = tsconfigContent !== null && tsconfigContent.includes("experimentalDecorators");
+	const hasTsconfigDecorators = tsconfigContent?.includes("experimentalDecorators");
 	const isVite8Plus = viteMajor !== null && viteMajor >= 8;
 	if (hasOxcDecorator) return {
 		status: "ok",
@@ -8229,11 +8436,14 @@ export default testManifest;
 					stiErrorCount,
 					dryRun: isDryRun
 				})) process.exitCode = 1;
-				if (!isDryRun) assertSchemaContract(await evaluateSchemaContract({
-					discovered,
-					schemaContract: config.schemaContract,
-					db
-				}));
+				if (!isDryRun) {
+					await settleDeferredCompatibilityAfterMigrate(db, dbType, { verbose: Boolean(options.verbose) });
+					assertSchemaContract(await evaluateSchemaContract({
+						discovered,
+						schemaContract: config.schemaContract,
+						db
+					}));
+				}
 				console.log("💡 Next steps:");
 				console.log("  - Run: smrt db:status (view migration status)");
 				console.log("  - Run: smrt db:history (view migration history)");
@@ -8504,6 +8714,7 @@ export default testManifest;
 	"db:rollback": dbRollbackCommand,
 	"db:generate": dbGenerateCommand,
 	"db:migrate-uuid": dbMigrateUuidCommand,
+	"db:prune": dbPruneCommand,
 	"config:export": configExportCommand,
 	export: exportCommand
 };

package/dist/index.js

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

package/package.json

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