mirror-mind 0.0.1 → 0.32.1

package/ts/src/frontDoor/dbPath.ts

@@ -0,0 +1,131 @@
+// DB-path resolution for the TS front door — the port of the Python config
+// resolution (`src/memory/config.py`).
+//
+// Python semantics reproduced here (CR024/CR007):
+// - The environment selects the database NAME: `db_name_for_env` maps
+//   production→memory.db, development→memory_dev.db, test→memory_test.db,
+//   anything else→memory_<env>.db. A dev session must never touch memory.db.
+// - Env-var precedence matches Python: DB_PATH (full file path) wins over
+//   every derived directory; then MEMORY_PROD_DIR (production only), then
+//   MEMORY_DIR, then the mirror home from MIRROR_HOME/MIRROR_USER.
+// - MIRROR_HOME and MIRROR_USER conflict (home basename must equal the user,
+//   as in `resolve_mirror_home`) raises instead of silently preferring one.
+// - MIRROR_USER falls back to the legacy `~/.mirror/<user>` home when the
+//   modern `~/.mirror-minds/<user>` does not exist (one-line stderr warning,
+//   permanent support — see docs/project/decisions.md).
+// - Nothing configured fails loudly (CV9.E2.S6: unconfigured resolution must
+//   not write to the homes root), unlike the pre-CR024 silent fallback.
+//
+// Front-door-only extension: the CLI flags `--db-path` and `--mirror-home`
+// are explicit per-invocation intent and take precedence over all env vars.
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { expandHome } from "#util/paths.ts";
+import { optionValue } from "./args.ts";
+
+/** Raised when no database location can be resolved — maps to CLI exit 2. */
+export class MirrorHomeNotConfiguredError extends Error {}
+
+const DB_NAMES: Record<string, string> = {
+  production: "memory.db",
+  development: "memory_dev.db",
+  test: "memory_test.db",
+};
+
+const DEFAULT_USER_HOMES_DIR = ".mirror-minds";
+const LEGACY_USER_HOMES_DIR = ".mirror";
+
+/** Port of Python `db_name_for_env`: one (environment) → one database name. */
+export function dbNameForEnv(env: string): string {
+  return DB_NAMES[env] ?? `memory_${env}.db`;
+}
+
+/** The env-var slice the resolver reads. `process.env` satisfies it. */
+export interface DbPathEnv {
+  MEMORY_ENV?: string;
+  DB_PATH?: string;
+  MEMORY_PROD_DIR?: string;
+  MEMORY_DIR?: string;
+  MIRROR_HOME?: string;
+  MIRROR_USER?: string;
+}
+
+/** Injection points so tests can run without touching the real filesystem. */
+export interface DbPathIo {
+  home?: string;
+  exists?: (path: string) => boolean;
+  warn?: (message: string) => void;
+}
+
+/**
+ * Port of Python `resolve_mirror_home`: MIRROR_HOME wins; MIRROR_USER derives
+ * `<home>/.mirror-minds/<user>` (with the legacy `.mirror` fallback); both set
+ * and inconsistent raises; neither set raises.
+ */
+export function resolveMirrorHome(env: DbPathEnv, io: DbPathIo = {}): string {
+  const home = io.home ?? homedir();
+  const exists = io.exists ?? existsSync;
+  const warn = io.warn ?? ((message: string) => console.error(message));
+
+  const explicitHome = env.MIRROR_HOME ?? "";
+  const explicitUser = env.MIRROR_USER ?? "";
+  const resolvedHome = explicitHome ? expandHome(explicitHome) : null;
+  const derivedHome = explicitUser ? join(home, DEFAULT_USER_HOMES_DIR, explicitUser) : null;
+
+  if (resolvedHome && explicitUser && basename(resolvedHome) !== explicitUser) {
+    throw new MirrorHomeNotConfiguredError(
+      `MIRROR_HOME (${resolvedHome}) conflicts with MIRROR_USER (${explicitUser}).`,
+    );
+  }
+  if (resolvedHome) return resolvedHome;
+  if (derivedHome) {
+    if (!exists(derivedHome)) {
+      const legacyHome = join(home, LEGACY_USER_HOMES_DIR, explicitUser);
+      if (exists(legacyHome)) {
+        warn(
+          `warning: using legacy mirror home at ${legacyHome}. ` +
+            `To migrate: mv ${legacyHome} ${derivedHome}. ` +
+            "The legacy path remains supported indefinitely.",
+        );
+        return legacyHome;
+      }
+    }
+    return derivedHome;
+  }
+  throw new MirrorHomeNotConfiguredError(
+    "Mirror home is not configured. Set MIRROR_HOME or MIRROR_USER " +
+      "(or pass an explicit MEMORY_DIR/DB_PATH override).",
+  );
+}
+
+/**
+ * Resolve the database file for a front-door invocation.
+ *
+ * Precedence: `--db-path` flag → `--mirror-home` flag → `DB_PATH` env →
+ * `MEMORY_PROD_DIR` (production only) → `MEMORY_DIR` → mirror home
+ * (MIRROR_HOME/MIRROR_USER). Every directory branch joins the
+ * environment-specific database name; the two full-file-path branches
+ * (`--db-path`, `DB_PATH`) are used as-is, matching Python.
+ */
+export function resolveDbPath(
+  args: readonly string[],
+  env: DbPathEnv = process.env,
+  io: DbPathIo = {},
+): string {
+  const explicitDbPath = optionValue(args, "--db-path");
+  if (explicitDbPath) return expandHome(explicitDbPath);
+
+  const selectedEnv = env.MEMORY_ENV || "production";
+  const dbName = dbNameForEnv(selectedEnv);
+
+  const explicitHome = optionValue(args, "--mirror-home");
+  if (explicitHome) return join(expandHome(explicitHome), dbName);
+  if (env.DB_PATH) return expandHome(env.DB_PATH);
+  if (selectedEnv === "production" && env.MEMORY_PROD_DIR) {
+    return join(expandHome(env.MEMORY_PROD_DIR), dbName);
+  }
+  if (env.MEMORY_DIR) return join(expandHome(env.MEMORY_DIR), dbName);
+  return join(resolveMirrorHome(env, io), dbName);
+}

package/ts/src/frontDoor/dbSafetyToolsRoute.ts

@@ -0,0 +1,240 @@
+// Front-door routes for the DB safety tools (CV22.DS7.TS1): `backup` and
+// `repair-encoding`. Argument handling mirrors the two Python argparse
+// parsers closely enough that the exit codes and error lines match; the
+// behavior itself lives in `#backup/zipBackup.ts` and
+// `#repair/encodingRepair.ts`, graded by their goldens.
+//
+// `backup` never opens the database through the front door and never
+// bootstraps one; its snapshot uses a read-only connection of its own. Since
+// CR060, a backup that wrote no archive exits 1 whatever --silent says, with
+// one stderr line that leads with the consequence -- Python exited 0 under
+// --silent, which hid every failed session-end backup.
+// `repair-encoding` reads through a plain read-only handle for the dry run
+// (Python does not check the schema either — the scan is tolerant of old
+// databases by design) and goes through the caller-supplied live-write seam
+// for `--apply`, which adds the front door's own silent pre-write snapshot on
+// top of the dated zip Python takes.
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { BackupSnapshotError, createZipBackup } from "#backup/zipBackup.ts";
+import { Zip64RequiredError } from "#backup/zipWriter.ts";
+import { type Database, openDatabaseReadOnly, type WritableDatabase } from "#db/database.ts";
+import {
+  applyRepairs,
+  renderApplyReport,
+  renderScanReport,
+  scanDatabase,
+} from "#repair/encodingRepair.ts";
+import { expandHome } from "#util/paths.ts";
+import { MirrorHomeNotConfiguredError } from "./dbPath.ts";
+
+const BACKUP_USAGE =
+  "usage: backup [-h] [--silent] [--mirror-home MIRROR_HOME] [--backup-dir BACKUP_DIR]";
+const REPAIR_USAGE =
+  "usage: repair-encoding [-h] [--mirror-home MIRROR_HOME] [--apply] [--no-backup] [--limit LIMIT]";
+
+interface ParsedArgs {
+  flags: Set<string>;
+  values: Map<string, string>;
+  error: string | null;
+}
+
+/** argparse-shaped parsing: known flags, known valued options, nothing else. */
+function parseArgs(
+  args: readonly string[],
+  spec: { flags: readonly string[]; valued: readonly string[] },
+): ParsedArgs {
+  const flags = new Set<string>();
+  const values = new Map<string, string>();
+  const unrecognized: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] as string;
+    if (spec.flags.includes(arg)) {
+      flags.add(arg);
+    } else if (spec.valued.includes(arg)) {
+      const value = args[index + 1];
+      if (value === undefined)
+        return { flags, values, error: `argument ${arg}: expected one argument` };
+      values.set(arg, value);
+      index += 1;
+    } else {
+      unrecognized.push(arg);
+    }
+  }
+  return {
+    flags,
+    values,
+    error: unrecognized.length > 0 ? `unrecognized arguments: ${unrecognized.join(" ")}` : null,
+  };
+}
+
+function usageError(usage: string, program: string, message: string): number {
+  process.stderr.write(`${usage}\n${program}: error: ${message}\n`);
+  return 2;
+}
+
+export interface SafetyToolsIo {
+  /**
+   * Resolve the database path from argv (`--db-path`, `--mirror-home`, env);
+   * null when unconfigured and already reported. `backup` is handed a resolver
+   * that throws `MirrorHomeNotConfiguredError` instead, so that failure is
+   * reported once, in the backup's own words.
+   */
+  resolveDbPath: (args: readonly string[]) => string | null;
+  /** The live-write seam for a resolved path: pre-write snapshot, schema guard, always-close. */
+  withLiveWriteDb: (dbPath: string, write: (db: WritableDatabase) => number) => number;
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+  now?: () => Date;
+  env?: Readonly<Record<string, string | undefined>>;
+}
+
+/** What `backup` answered, for the caller and the front-door log. */
+export interface BackupOutcome {
+  exitCode: number;
+  /** `backup=<why>` when no archive was written: content-free, never a path or an argument. */
+  detail?: string;
+}
+
+type BackupFailure = "home_unresolved" | "database_missing" | "snapshot_failed" | "write_failed";
+
+/** An operating-system refusal (no space, no permission, a file in the way) rather than a bug. */
+function isSystemError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && typeof (error as NodeJS.ErrnoException).code === "string";
+}
+
+/** `backup [--silent] [--mirror-home PATH] [--backup-dir PATH] [--db-path PATH]`. */
+export function runBackupRoute(argv: readonly string[], io: SafetyToolsIo): BackupOutcome {
+  const args = argv.slice(1);
+  const parsed = parseArgs(args, {
+    flags: ["--silent"],
+    valued: ["--mirror-home", "--backup-dir", "--db-path"],
+  });
+  if (parsed.error) return { exitCode: usageError(BACKUP_USAGE, "backup", parsed.error) };
+  const silent = parsed.flags.has("--silent");
+  const err = io.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+  // CR060: --silent suppresses progress, never failure.
+  const fail = (why: BackupFailure, reason: string): BackupOutcome => {
+    err(`backup: no archive was written: ${reason}`);
+    return { exitCode: 1, detail: `backup=${why}` };
+  };
+
+  let dbPath: string | null;
+  try {
+    dbPath = io.resolveDbPath(args);
+  } catch (error) {
+    if (error instanceof MirrorHomeNotConfiguredError)
+      return fail("home_unresolved", error.message);
+    throw error;
+  }
+  // A resolver that returns null has reported the failure itself.
+  if (dbPath === null) return { exitCode: 1, detail: "backup=home_unresolved" };
+
+  const explicitHome = parsed.values.get("--mirror-home");
+  const explicitDir = parsed.values.get("--backup-dir");
+  let archive: string | null;
+  try {
+    archive = createZipBackup({
+      dbPath,
+      mirrorHome: explicitHome === undefined ? dirname(dbPath) : expandHome(explicitHome),
+      backupDir: explicitDir === undefined ? null : expandHome(explicitDir),
+      silent,
+      env: io.env ?? process.env,
+      ...(io.now ? { now: io.now } : {}),
+      ...(io.stdout ? { stdout: io.stdout } : {}),
+      ...(io.stderr ? { stderr: io.stderr } : {}),
+    });
+  } catch (error) {
+    // Expected failures are one line; anything else is a bug and keeps its stack.
+    if (error instanceof BackupSnapshotError) return fail("snapshot_failed", error.message);
+    if (isSystemError(error) || error instanceof Zip64RequiredError) {
+      return fail("write_failed", error.message);
+    }
+    throw error;
+  }
+  if (archive === null) {
+    // Without --silent, createZipBackup already said "Database not found" on stdout.
+    if (!silent) return { exitCode: 1, detail: "backup=database_missing" };
+    return fail("database_missing", `database not found: ${dbPath}`);
+  }
+  return { exitCode: 0 };
+}
+
+/** `repair-encoding [--mirror-home PATH] [--apply] [--no-backup] [--limit N] [--db-path PATH]`. */
+export function runRepairEncodingRoute(argv: readonly string[], io: SafetyToolsIo): number {
+  const args = argv.slice(1);
+  const parsed = parseArgs(args, {
+    flags: ["--apply", "--no-backup"],
+    valued: ["--mirror-home", "--limit", "--db-path"],
+  });
+  if (parsed.error) return usageError(REPAIR_USAGE, "repair-encoding", parsed.error);
+  const rawLimit = parsed.values.get("--limit");
+  // argparse `type=int`: Python's int() accepts surrounding whitespace and a sign.
+  if (rawLimit !== undefined && !/^\s*[+-]?\d+\s*$/.test(rawLimit)) {
+    return usageError(
+      REPAIR_USAGE,
+      "repair-encoding",
+      `argument --limit: invalid int value: '${rawLimit}'`,
+    );
+  }
+  const limit = rawLimit === undefined ? 20 : Number.parseInt(rawLimit, 10);
+  const apply = parsed.flags.has("--apply");
+  const noBackup = parsed.flags.has("--no-backup");
+  const out = io.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const err = io.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  const dbPath = io.resolveDbPath(args);
+  if (dbPath === null) return 1;
+  if (!existsSync(dbPath)) {
+    err(`Database not found: ${dbPath}`);
+    return 1;
+  }
+
+  const explicitHome = parsed.values.get("--mirror-home");
+  const report = (db: Database) => {
+    const hits = scanDatabase(db);
+    out(renderScanReport({ dbPath, hits, limit }).replace(/\n$/, ""));
+    return hits;
+  };
+
+  if (!apply) {
+    const db = openDatabaseReadOnly(dbPath);
+    try {
+      report(db);
+    } finally {
+      db.close();
+    }
+    out("Dry-run only. Re-run with --apply to modify the database.");
+    return 0;
+  }
+
+  return io.withLiveWriteDb(dbPath, (db) => {
+    const hits = report(db);
+    if (hits.length === 0) {
+      out("No changes needed.");
+      return 0;
+    }
+    if (!noBackup) {
+      // Python: backup(silent=False, db_path, db_backup_path=<home>/backups,
+      // mirror_home=<explicit or None>) -- the `Mirror home:` line appears
+      // only when --mirror-home was passed.
+      const created = createZipBackup({
+        dbPath,
+        mirrorHome: explicitHome === undefined ? null : expandHome(explicitHome),
+        backupDir: join(dirname(dbPath), "backups"),
+        silent: false,
+        env: io.env ?? process.env,
+        ...(io.now ? { now: io.now } : {}),
+        stdout: out,
+        stderr: err,
+      });
+      if (created === null) {
+        err("Backup failed; aborting repair.");
+        return 1;
+      }
+    }
+    out(renderApplyReport(applyRepairs(db, hits)).replace(/\n$/, ""));
+    return 0;
+  });
+}