opencodekit 0.18.22 → 0.18.23

package/dist/index.js

@@ -20,7 +20,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.18.22";
+var version = "0.18.23";
 
 //#endregion
 //#region src/utils/license.ts

package/dist/template/.opencode/plugin/lib/db/schema.ts

@@ -6,8 +6,27 @@
  */
 
 import { Database } from "bun:sqlite";
+import { appendFileSync, existsSync, renameSync } from "node:fs";
 import path from "node:path";
 
+// ============================================================================
+// Recovery Logger
+// ============================================================================
+
+/**
+ * Log recovery messages to a file instead of stderr.
+ * Writing to stderr corrupts the TUI in OpenCode.
+ */
+function logRecovery(message: string): void {
+	try {
+		const logPath = path.join(process.cwd(), ".opencode/memory-recovery.log");
+		const timestamp = new Date().toISOString();
+		appendFileSync(logPath, `[${timestamp}] ${message}\n`);
+	} catch {
+		// If we can't even write a log file, silently continue
+	}
+}
+
 // ============================================================================
 // Schema v2
 // ============================================================================
@@ -238,7 +257,64 @@ export function getMemoryDB(): Database {
 	if (dbInstance) return dbInstance;
 
 	const dbPath = path.join(process.cwd(), ".opencode/memory.db");
-	dbInstance = new Database(dbPath, { create: true });
+
+	try {
+		dbInstance = new Database(dbPath, { create: true });
+	} catch (err) {
+		// Database file may be corrupted — attempt recovery
+		const recovered = attemptDBRecovery(dbPath, err);
+		if (!recovered) {
+			throw new Error(
+				`Failed to open memory database: ${err instanceof Error ? err.message : String(err)}. ` +
+					`Recovery also failed. Try manually deleting ${dbPath} to start fresh.`,
+			);
+		}
+		dbInstance = recovered;
+	}
+
+	// Verify database integrity
+	try {
+		const result = dbInstance.query("PRAGMA integrity_check").get() as {
+			integrity_check: string;
+		} | null;
+		if (result && result.integrity_check !== "ok") {
+			logRecovery(
+				`[memory-db] Integrity check failed: ${result.integrity_check}`,
+			);
+			// Close bad instance and attempt recovery
+			dbInstance.close();
+			dbInstance = null;
+			const recovered = attemptDBRecovery(dbPath, new Error("integrity check failed"));
+			if (!recovered) {
+				throw new Error(
+					`Memory database integrity check failed and recovery failed. ` +
+						`Try manually deleting ${dbPath} to start fresh.`,
+				);
+			}
+			dbInstance = recovered;
+		}
+	} catch (err) {
+		if (
+			err instanceof Error &&
+			err.message.includes("recovery failed")
+		) {
+			throw err;
+		}
+		// integrity_check itself failed — try recovery
+		logRecovery(
+			`[memory-db] Integrity check query failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		dbInstance?.close();
+		dbInstance = null;
+		const recovered = attemptDBRecovery(dbPath, err);
+		if (!recovered) {
+			throw new Error(
+				`Memory database is corrupted and recovery failed. ` +
+					`Try manually deleting ${dbPath} to start fresh.`,
+			);
+		}
+		dbInstance = recovered;
+	}
 
 	// Enable WAL mode for better concurrency
 	dbInstance.run("PRAGMA journal_mode = WAL");
@@ -250,6 +326,77 @@ export function getMemoryDB(): Database {
 	return dbInstance;
 }
 
+/**
+ * Attempt to recover from a corrupted database.
+ * Strategy: WAL checkpoint first, then backup corrupt file + create fresh.
+ */
+function attemptDBRecovery(
+	dbPath: string,
+	originalError: unknown,
+): Database | null {
+	logRecovery(
+		`[memory-db] Database recovery triggered: ${originalError instanceof Error ? originalError.message : String(originalError)}`,
+	);
+
+	// Step 1: Try WAL checkpoint recovery (if file exists and is openable)
+	try {
+		if (existsSync(dbPath)) {
+			let tempDB: Database | undefined;
+			try {
+				tempDB = new Database(dbPath);
+				tempDB.run("PRAGMA wal_checkpoint(TRUNCATE)");
+				tempDB.close();
+				tempDB = undefined;
+			} catch {
+				tempDB?.close();
+				throw new Error("WAL checkpoint failed");
+			}
+			// Try reopening after WAL checkpoint
+			const db = new Database(dbPath, { create: true });
+			const check = db.query("PRAGMA integrity_check").get() as {
+				integrity_check: string;
+			} | null;
+			if (check?.integrity_check === "ok") {
+				logRecovery("[memory-db] WAL checkpoint recovery succeeded.");
+				return db;
+			}
+			db.close();
+		}
+	} catch {
+		// WAL recovery failed, continue to backup + recreate
+	}
+
+	// Step 2: Backup corrupt file and create fresh database
+	try {
+		if (existsSync(dbPath)) {
+			const backupPath = `${dbPath}.corrupt.${Date.now()}`;
+			renameSync(dbPath, backupPath);
+			logRecovery(
+				`[memory-db] Corrupt database backed up to: ${backupPath}`,
+			);
+
+			// Also clean up WAL/SHM files
+			for (const suffix of ["-wal", "-shm"]) {
+				const walPath = dbPath + suffix;
+				if (existsSync(walPath)) {
+					renameSync(walPath, `${backupPath}${suffix}`);
+				}
+			}
+		}
+
+		const freshDB = new Database(dbPath, { create: true });
+		logRecovery(
+			"[memory-db] Fresh database created. Previous observations are in the backup file.",
+		);
+		return freshDB;
+	} catch (backupErr) {
+		logRecovery(
+			`[memory-db] Recovery failed: ${backupErr instanceof Error ? backupErr.message : String(backupErr)}`,
+		);
+		return null;
+	}
+}
+
 /**
  * Close the database connection (for cleanup).
  */

package/dist/template/.opencode/plugin/lib/memory-admin-tools.ts

@@ -54,133 +54,148 @@ export function createAdminTools(deps: AdminToolDeps) {
 				force: tool.schema.boolean().optional().describe("Force re-migration"),
 			},
 			execute: async (args, ctx) => {
-				const op = args.operation ?? "status";
-				const dryRun = args.dry_run ?? false;
-				const olderThanDays = args.older_than_days ?? 90;
+				try {
+					const op = args.operation ?? "status";
+					const dryRun = args.dry_run ?? false;
+					const olderThanDays = args.older_than_days ?? 90;
 
-				switch (op) {
-					case "status": {
-						const sizes = getDatabaseSizes();
-						const stats = getObservationStats();
-						const archivable = archiveOldObservations({
-							olderThanDays,
-							dryRun: true,
-						});
-						const captureStats = getCaptureStats();
-						const distillStats = getDistillationStats();
-						return [
-							"## Memory System Status\n",
-							`**Database**: ${(sizes.total / 1024).toFixed(1)} KB`,
-							`**FTS5**: ${checkFTS5Available() ? "Available (porter stemming)" : "Unavailable"}`,
-							`**Schema**: v2 (4-tier storage)\n`,
-							"### Observations",
-							...Object.entries(stats).map(([k, v]) => `  ${k}: ${v}`),
-							`  Archivable (>${olderThanDays}d): ${archivable}\n`,
-							"### Capture Pipeline",
-							`  Messages: ${captureStats.total} (undistilled: ${captureStats.undistilled})`,
-							`  Sessions: ${captureStats.sessions}\n`,
-							"### Distillations",
-							`  Total: ${distillStats.total} (${distillStats.sessions} sessions)`,
-							`  Avg compression: ${(distillStats.avgCompression * 100).toFixed(1)}%`,
-						].join("\n");
-					}
-					case "full": {
-						if (dryRun)
-							return `Dry run: would archive, purge, optimize, checkpoint, vacuum.`;
-						const r = runFullMaintenance({
-							olderThanDays,
-							includeSuperseded: true,
-						});
-						return `Done: archived ${r.archived}, purged ${r.purgedMessages} msgs, freed ${(r.freedBytes / 1024).toFixed(1)} KB.`;
-					}
-					case "archive": {
-						const c = archiveOldObservations({
-							olderThanDays,
-							includeSuperseded: true,
-							dryRun,
-						});
-						return dryRun
-							? `Would archive ${c} observations.`
-							: `Archived ${c} observations.`;
-					}
-					case "checkpoint": {
-						const r = checkpointWAL();
-						return r.checkpointed
-							? `WAL checkpointed (${r.walSize} pages).`
-							: "Checkpoint failed or busy.";
-					}
-					case "vacuum":
-						return vacuumDatabase() ? "Vacuumed." : "Vacuum failed.";
-					case "capture-stats":
-						return JSON.stringify(getCaptureStats(), null, 2);
-					case "distill-now": {
-						const sid = ctx?.sessionID;
-						if (!sid) return "Error: No session ID.";
-						const did = distillSession(sid);
-						return did
-							? `Distillation #${did} created.`
-							: "Not enough undistilled messages.";
-					}
-					case "curate-now": {
-						const r = curateFromDistillations();
-						return `Created ${r.created}, skipped ${r.skipped}. Patterns: ${JSON.stringify(r.patterns)}`;
-					}
-					case "migrate": {
-						const obsDir = path.join(
-							directory,
-							".opencode",
-							"memory",
-							"observations",
-						);
-						let mdFiles: string[] = [];
-						try {
-							mdFiles = (await readdir(obsDir)).filter((f) =>
-								f.endsWith(".md"),
-							);
-						} catch {
-							return "No observations directory found.";
+					switch (op) {
+						case "status": {
+							const sizes = getDatabaseSizes();
+							const stats = getObservationStats();
+							const archivable = archiveOldObservations({
+								olderThanDays,
+								dryRun: true,
+							});
+							const captureStats = getCaptureStats();
+							const distillStats = getDistillationStats();
+							return [
+								"## Memory System Status\n",
+								`**Database**: ${(sizes.total / 1024).toFixed(1)} KB`,
+								`**FTS5**: ${checkFTS5Available() ? "Available (porter stemming)" : "Unavailable"}`,
+								`**Schema**: v2 (4-tier storage)\n`,
+								"### Observations",
+								...Object.entries(stats).map(([k, v]) => `  ${k}: ${v}`),
+								`  Archivable (>${olderThanDays}d): ${archivable}\n`,
+								"### Capture Pipeline",
+								`  Messages: ${captureStats.total} (undistilled: ${captureStats.undistilled})`,
+								`  Sessions: ${captureStats.sessions}\n`,
+								"### Distillations",
+								`  Total: ${distillStats.total} (${distillStats.sessions} sessions)`,
+								`  Avg compression: ${(distillStats.avgCompression * 100).toFixed(1)}%`,
+							].join("\n");
+						}
+						case "full": {
+							if (dryRun)
+								return `Dry run: would archive, purge, optimize, checkpoint, vacuum.`;
+							const r = runFullMaintenance({
+								olderThanDays,
+								includeSuperseded: true,
+							});
+							return `Done: archived ${r.archived}, purged ${r.purgedMessages} msgs, freed ${(r.freedBytes / 1024).toFixed(1)} KB.`;
 						}
-						if (mdFiles.length === 0) return "No files to migrate.";
-						const existing = new Set(getMarkdownFilesInSqlite());
-						const toMigrate = args.force
-							? mdFiles
-							: mdFiles.filter((f) => !existing.has(f));
-						if (toMigrate.length === 0) return "All files already migrated.";
-						if (dryRun) return `Would migrate ${toMigrate.length} files.`;
-						let migrated = 0;
-						for (const file of toMigrate) {
+						case "archive": {
+							const c = archiveOldObservations({
+								olderThanDays,
+								includeSuperseded: true,
+								dryRun,
+							});
+							return dryRun
+								? `Would archive ${c} observations.`
+								: `Archived ${c} observations.`;
+						}
+						case "checkpoint": {
+							const r = checkpointWAL();
+							return r.checkpointed
+								? `WAL checkpointed (${r.walSize} pages).`
+								: "Checkpoint failed or busy.";
+						}
+						case "vacuum":
+							return vacuumDatabase() ? "Vacuumed." : "Vacuum failed.";
+						case "capture-stats":
+							return JSON.stringify(getCaptureStats(), null, 2);
+						case "distill-now": {
+							const sid = ctx?.sessionID;
+							if (!sid) return "Error: No session ID.";
+							const did = distillSession(sid);
+							return did
+								? `Distillation #${did} created.`
+								: "Not enough undistilled messages.";
+						}
+						case "curate-now": {
+							const r = curateFromDistillations();
+							return `Created ${r.created}, skipped ${r.skipped}. Patterns: ${JSON.stringify(r.patterns)}`;
+						}
+						case "migrate": {
+							const obsDir = path.join(
+								directory,
+								".opencode",
+								"memory",
+								"observations",
+							);
+							let mdFiles: string[] = [];
 							try {
-								const content = await readFile(
-									path.join(obsDir, file),
-									"utf-8",
+								mdFiles = (await readdir(obsDir)).filter((f) =>
+									f.endsWith(".md"),
 								);
-								const fmMatch = content.match(
-									/^---\n([\s\S]*?)\n---\n([\s\S]*)$/,
-								);
-								const body = fmMatch ? fmMatch[2].trim() : content.trim();
-								const fm = fmMatch ? fmMatch[1] : "";
-								storeObservation({
-									type: (fm.match(/type:\s*(\w+)/)?.[1] ??
-										"discovery") as ObservationType,
-									title:
-										fm.match(/title:\s*(.+)/)?.[1]?.trim() ??
-										file.replace(/\.md$/, ""),
-									narrative: body,
-									confidence: (fm.match(/confidence:\s*(\w+)/)?.[1] ??
-										"medium") as ConfidenceLevel,
-									markdown_file: file,
-									source: "imported",
-								});
-								migrated++;
 							} catch {
-								/* Skip failed files */
+								return "No observations directory found.";
+							}
+							if (mdFiles.length === 0) return "No files to migrate.";
+							const existing = new Set(getMarkdownFilesInSqlite());
+							const toMigrate = args.force
+								? mdFiles
+								: mdFiles.filter((f) => !existing.has(f));
+							if (toMigrate.length === 0) return "All files already migrated.";
+							if (dryRun) return `Would migrate ${toMigrate.length} files.`;
+							let migrated = 0;
+							for (const file of toMigrate) {
+								try {
+									const content = await readFile(
+										path.join(obsDir, file),
+										"utf-8",
+									);
+									const fmMatch = content.match(
+										/^---\n([\s\S]*?)\n---\n([\s\S]*)$/,
+									);
+									const body = fmMatch ? fmMatch[2].trim() : content.trim();
+									const fm = fmMatch ? fmMatch[1] : "";
+									storeObservation({
+										type: (fm.match(/type:\s*(\w+)/)?.[1] ??
+											"discovery") as ObservationType,
+										title:
+											fm.match(/title:\s*(.+)/)?.[1]?.trim() ??
+											file.replace(/\.md$/, ""),
+										narrative: body,
+										confidence: (fm.match(/confidence:\s*(\w+)/)?.[1] ??
+											"medium") as ConfidenceLevel,
+										markdown_file: file,
+										source: "imported",
+									});
+									migrated++;
+								} catch {
+									/* Skip failed files */
+								}
 							}
+							if (migrated > 0) rebuildFTS5();
+							return `Migrated ${migrated}/${toMigrate.length} files.`;
 						}
-						if (migrated > 0) rebuildFTS5();
-						return `Migrated ${migrated}/${toMigrate.length} files.`;
+						default:
+							return `Unknown operation: "${op}".`;
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					if (
+						message.includes("database disk image is malformed") ||
+						message.includes("SQLITE_CORRUPT") ||
+						message.includes("integrity check failed")
+					) {
+						return (
+							`Error: Memory database is corrupted. ` +
+							`Automatic repair failed. Delete .opencode/memory.db to start fresh. Details: ${message}`
+						);
 					}
-					default:
-						return `Unknown operation: "${op}".`;
+					return `Error: Admin operation failed: ${message}`;
 				}
 			},
 		}),

package/dist/template/.opencode/plugin/lib/memory-tools.ts

@@ -32,6 +32,35 @@ import {
 	VALID_TYPES,
 } from "./memory-helpers.js";
 
+/**
+ * Wrap a memory tool execute function with DB error handling.
+ * Returns a user-friendly error message instead of raw SQLite crashes.
+ */
+function withDBErrorHandling<T extends Record<string, unknown>>(
+	fn: (args: T) => Promise<string>,
+): (args: T) => Promise<string> {
+	return async (args: T) => {
+		try {
+			return await fn(args);
+		} catch (err) {
+			const message =
+				err instanceof Error ? err.message : String(err);
+			if (
+				message.includes("database disk image is malformed") ||
+				message.includes("SQLITE_CORRUPT") ||
+				message.includes("integrity check failed")
+			) {
+				return (
+					`Error: Memory database is corrupted. ` +
+					`Run \`memory-admin({ operation: "full" })\` to attempt repair, ` +
+					`or delete .opencode/memory.db to start fresh. Details: ${message}`
+				);
+			}
+			return `Error: Memory operation failed: ${message}`;
+		}
+	};
+}
+
 interface CoreToolDeps {
 	handoffDir: string;
 }
@@ -89,7 +118,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 					.optional()
 					.describe("manual, curator, imported"),
 			},
-			execute: async (args) => {
+			execute: withDBErrorHandling(async (args) => {
 				const obsType = args.type as ObservationType;
 				if (!VALID_TYPES.includes(obsType)) {
 					return `Error: Invalid type "${args.type}". Valid: ${VALID_TYPES.join(", ")}`;
@@ -144,7 +173,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 				});
 
 				return `${TYPE_ICONS[obsType] ?? "\uD83D\uDCCC"} Observation #${id} stored [${obsType}] "${args.title}" (confidence: ${confidence}, source: ${source})`;
-			},
+			}),
 		}),
 
 		"memory-search": tool({
@@ -160,7 +189,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 					.optional()
 					.describe("Max results (default: 10)"),
 			},
-			execute: async (args) => {
+			execute: withDBErrorHandling(async (args) => {
 				const query = args.query.trim();
 				if (!query) return "Error: Empty search query";
 				const limit = args.limit ?? 10;
@@ -237,7 +266,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 				}
 
 				return lines.length > 0 ? lines.join("\n") : "No results found.";
-			},
+			}),
 		}),
 
 		"memory-get": tool({
@@ -245,7 +274,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 			args: {
 				ids: tool.schema.string().describe("Comma-separated observation IDs"),
 			},
-			execute: async (args) => {
+			execute: withDBErrorHandling(async (args) => {
 				const idList = args.ids
 					.split(",")
 					.map((s) => Number.parseInt(s.trim(), 10))
@@ -257,7 +286,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 				return observations
 					.map((obs) => formatObservation(obs))
 					.join("\n\n---\n\n");
-			},
+			}),
 		}),
 
 		"memory-read": tool({
@@ -265,12 +294,12 @@ export function createCoreTools(deps: CoreToolDeps) {
 			args: {
 				file: tool.schema.string().optional().describe("Memory file path"),
 			},
-			execute: async (args) => {
+			execute: withDBErrorHandling(async (args) => {
 				const filePath = (args.file ?? "").replace(/\.md$/, "");
 				if (!filePath) return "Error: No file path provided";
 				const row = getMemoryFile(filePath);
 				return row ? row.content : `Memory file "${filePath}" not found.`;
-			},
+			}),
 		}),
 
 		"memory-update": tool({
@@ -283,7 +312,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 					.optional()
 					.describe("replace (default) or append"),
 			},
-			execute: async (args) => {
+			execute: withDBErrorHandling(async (args) => {
 				const filePath = args.file.replace(/\.md$/, "");
 				const mode = (args.mode ?? "replace") as "replace" | "append";
 				let finalContent = args.content;
@@ -292,7 +321,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 				}
 				upsertMemoryFile(filePath, finalContent, mode);
 				return `Memory file "${filePath}" updated (mode: ${mode}).`;
-			},
+			}),
 		}),
 
 		"memory-timeline": tool({
@@ -308,7 +337,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 					.optional()
 					.describe("Later observations (default: 5)"),
 			},
-			execute: async (args) => {
+			execute: withDBErrorHandling(async (args) => {
 				const { anchor, before, after } = getTimelineAroundObservation(
 					args.anchor_id,
 					args.depth_before ?? 5,
@@ -335,7 +364,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 						);
 				}
 				return lines.join("\n");
-			},
+			}),
 		}),
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.18.22",
+	"version": "0.18.23",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",