mirror-mind 0.0.1 → 0.32.1

package/ts/src/runtime/installKind.ts

@@ -0,0 +1,220 @@
+// Where is this Mirror installed, and what can update it? (CV22.DS10.US2)
+//
+// The updater's first question, answered from where the front door ITSELF
+// lives rather than from configuration. A user who has to tell the updater how
+// they installed Mirror can tell it wrong, and the answer decides whether the
+// next step is `git merge --ff-only` or `npm install -g`.
+//
+// Three answers, and `unknown` is a real one: an install we cannot identify is
+// refused with its reason printed, never updated on a guess.
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+export type InstallKind =
+  | { kind: "clone"; repository: string }
+  | { kind: "package"; root: string; name: string; version: string }
+  | { kind: "unknown"; reason: string };
+
+export interface InstallKindProbe {
+  /** The front door's own resolved path. */
+  frontDoorPath: string;
+  /**
+   * `npm root -g`, resolved once by the caller, when the caller needs npm's
+   * word that `-g` addresses THIS install: the update lane does. Given as a
+   * string, a package must sit inside it. Omitted or `null` (npm not probed,
+   * or not available), a package is known by its layout alone -- see
+   * `packageByLayout` -- which is what the read-only routes ask, since they
+   * run where npm may not be on the PATH and must still say what this is.
+   */
+  npmRootGlobal?: string | null;
+  exists?: (path: string) => boolean;
+  readFile?: (path: string) => string;
+  /**
+   * Symlink resolution for the front door's path. `npm link` places a symlink
+   * named like the package under the global root, so a developer's checkout
+   * can be reached through a path that looks installed; what is updated must
+   * be the tree the file really lives in.
+   */
+  realpath?: (path: string) => string;
+}
+
+/** Is `child` inside `parent`, by path components rather than string prefix? */
+function isInside(parent: string, child: string): boolean {
+  const base = resolve(parent);
+  const target = resolve(child);
+  return target === base || target.startsWith(base.endsWith(sep) ? base : base + sep);
+}
+
+/**
+ * The git work tree holding this front door, identified by the repository
+ * marker this project actually has: a root that carries `package.json` and a
+ * `.git` entry (the manifest moved to the root in CV22.DS10.US3, D2). Walking up rather than asking git keeps detection free of a
+ * subprocess and of git's own notion of "inside a work tree", which is true in
+ * places this updater must not touch (a submodule, a nested checkout).
+ */
+function cloneRootFor(startDir: string, exists: (path: string) => boolean): string | null {
+  let current = resolve(startDir);
+  for (;;) {
+    if (exists(join(current, ".git")) && exists(join(current, "package.json"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+interface Manifest {
+  root: string;
+  name: string;
+  version: string;
+  bins: string[];
+}
+
+/** The nearest manifest above the front door that names and versions a package. */
+function nearestManifest(
+  frontDoorPath: string,
+  stopAt: string | null,
+  exists: (path: string) => boolean,
+  readFile: (path: string) => string,
+): Manifest | null {
+  let current = resolve(dirname(frontDoorPath));
+  const stop = stopAt === null ? null : resolve(stopAt);
+  for (;;) {
+    const manifest = join(current, "package.json");
+    if (exists(manifest)) {
+      try {
+        const parsed = JSON.parse(readFile(manifest)) as {
+          name?: unknown;
+          version?: unknown;
+          bin?: unknown;
+        };
+        if (typeof parsed.name === "string" && typeof parsed.version === "string") {
+          const bins =
+            typeof parsed.bin === "string"
+              ? [parsed.name]
+              : typeof parsed.bin === "object" && parsed.bin !== null
+                ? Object.keys(parsed.bin)
+                : [];
+          return { root: current, name: parsed.name, version: parsed.version, bins };
+        }
+      } catch {
+        // A manifest we cannot read is not a package we should reinstall.
+        return null;
+      }
+    }
+    if (current === stop) return null;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * The installed package holding this front door, by npm's own word: the
+ * manifest sits inside `npm root -g`.
+ *
+ * Being under SOME `node_modules/` is not enough, and the difference matters:
+ * a project-local dependency would detect as `package`, and `npm install -g`
+ * would then update a completely different tree from the one running. The
+ * global root is the evidence that `-g` addresses THIS install, which is why
+ * the update lane asks this way.
+ */
+function packageUnderNpmRoot(
+  frontDoorPath: string,
+  npmRootGlobal: string,
+  exists: (path: string) => boolean,
+  readFile: (path: string) => string,
+  realpath: (path: string) => string,
+): InstallKind | null {
+  // Both sides resolved: the front door already is, and npm answers with
+  // the prefix as configured, symlinks and all (/tmp on macOS is one).
+  const root = realpath(resolve(npmRootGlobal));
+  if (!isInside(root, frontDoorPath)) return null;
+  const manifest = nearestManifest(frontDoorPath, root, exists, readFile);
+  if (manifest === null) return null;
+  return { kind: "package", root: manifest.root, name: manifest.name, version: manifest.version };
+}
+
+/**
+ * The installed package holding this front door, by its layout, with no
+ * subprocess: the manifest sits at `<prefix>/lib/node_modules/<name>` -- the
+ * global layout npm uses on every platform this core supports -- AND one of
+ * the manifest's bins exists at `<prefix>/bin/<bin>` and resolves back into
+ * the package. The bin is what makes a global install global; a project that
+ * happens to live at `<x>/lib` has the first half and not the second.
+ * (CV22.DS10.US3 plateau 4: the read-only routes run where npm may be off
+ * the PATH and must still say what this is.)
+ */
+function packageByLayout(
+  frontDoorPath: string,
+  exists: (path: string) => boolean,
+  readFile: (path: string) => string,
+  realpath: (path: string) => string,
+): InstallKind | null {
+  const manifest = nearestManifest(frontDoorPath, null, exists, readFile);
+  if (manifest === null) return null;
+  const nodeModules = dirname(manifest.root);
+  const lib = dirname(nodeModules);
+  if (basename(nodeModules) !== "node_modules" || basename(lib) !== "lib") return null;
+  const prefix = dirname(lib);
+  const linked = manifest.bins.some((bin) => {
+    const link = join(prefix, "bin", bin);
+    return exists(link) && isInside(manifest.root, realpath(link));
+  });
+  if (!linked) return null;
+  return { kind: "package", root: manifest.root, name: manifest.name, version: manifest.version };
+}
+
+/** `realpathSync`, except that a path that does not exist is returned as given. */
+function safeRealpath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+export function detectInstallKind(probe: InstallKindProbe): InstallKind {
+  const exists = probe.exists ?? existsSync;
+  const readFile = probe.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+  const realpath = probe.realpath ?? safeRealpath;
+  const frontDoorPath = realpath(resolve(probe.frontDoorPath));
+
+  const asPackage = probe.npmRootGlobal
+    ? packageUnderNpmRoot(frontDoorPath, probe.npmRootGlobal, exists, readFile, realpath)
+    : packageByLayout(frontDoorPath, exists, readFile, realpath);
+  if (asPackage !== null) return asPackage;
+
+  const repository = cloneRootFor(dirname(frontDoorPath), exists);
+  if (repository !== null) return { kind: "clone", repository };
+
+  return {
+    kind: "unknown",
+    reason:
+      probe.npmRootGlobal === null
+        ? "not a git checkout, and npm is unavailable to identify a package install"
+        : probe.npmRootGlobal === undefined
+          ? "not a git checkout, and not laid out as a global npm install"
+          : "not a git checkout, and not under the global npm root",
+  };
+}
+
+/** One line for a render or a log entry. */
+export function describeInstallKind(install: InstallKind): string {
+  if (install.kind === "clone") return `clone (${install.repository})`;
+  if (install.kind === "package") return `package (${install.name}@${install.version})`;
+  return `unknown (${install.reason})`;
+}
+
+/**
+ * The install, for `runtime status` and `runtime version`: the kind, and for
+ * a package the root `npm install -g` replaces, which its one-line form does
+ * not carry (US2 D3, deferred to CV22.DS10.US3 plateau 4).
+ */
+export function renderInstallLines(install: InstallKind): string[] {
+  const lines = [`Install: ${describeInstallKind(install)}`];
+  if (install.kind === "package") lines.push(`Install root: ${install.root}`);
+  return lines;
+}

package/ts/src/runtime/migrate.ts

@@ -0,0 +1,154 @@
+// `runtime migrate` — apply pending migrations, and say what the ledger did.
+// (CV22.DS10.US2, decision D8)
+//
+// This verb does not exist on the oracle, and adding it corrects the oracle.
+// Python's updater calls `_apply_migrations` IN-PROCESS, which means it
+// migrates the database with the code it just fast-forwarded away from: the
+// interpreter has already imported the old modules, and a migration authored
+// in the new commit is not among them. The TypeScript updater spawns this verb
+// in a FRESH process after `apply`, so the code that migrates is the code that
+// was just installed.
+//
+// It is also useful on its own, which is why it is a named verb rather than a
+// private argv: when an update fails between `apply` and `migrate`, the
+// operator needs a way to finish the job without running the whole pipeline.
+//
+// The ledger is printed before and after because "migrations: pass" is a claim
+// and the `_migrations` rows are the evidence. A stage that infers a migration
+// from "some command opened the database" is what the Plan review rejected.
+
+import { existsSync } from "node:fs";
+import { openDatabaseReadOnly } from "#db/database.ts";
+import { ensureMigratedOnOpen, type MigrateVerdict } from "#db/migrateOnOpen.ts";
+
+export interface MigrateOutcome {
+  dbPath: string;
+  before: string[];
+  after: string[];
+  applied: string[];
+  migrated: boolean;
+  /**
+   * The verdict, and the whole point of CV22.DS10.US2's debt D-025.
+   *
+   * There used to be two: migrated, or not. "Not" covered both `nothing
+   * pending` and a DECLINED migration, and both rendered as
+   * `Migrate result: nothing pending` with exit 0 -- so the updater's migrate
+   * stage passed on a database with pending work nothing had applied, on the
+   * one command whose job is to leave the database correct after an update.
+   */
+  verdict: MigrateVerdict;
+  /** Why the engine declined, when it did. */
+  declinedReason: string | null;
+  backupPath: string | null;
+  error: string | null;
+}
+
+/** Exit code for a declined migration: not success, not a crash. */
+export const MIGRATE_DECLINED_EXIT = 1;
+
+/** The `_migrations` ledger, sorted. `null` when it cannot be read at all. */
+export function readLedger(dbPath: string): string[] | null {
+  if (!existsSync(dbPath)) return null;
+  let db: ReturnType<typeof openDatabaseReadOnly>;
+  try {
+    db = openDatabaseReadOnly(dbPath);
+  } catch {
+    return null;
+  }
+  try {
+    const rows = db.prepare("SELECT id FROM _migrations").all() as { id: string }[];
+    return rows.map((row) => row.id).sort();
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+export function runMigrate(dbPath: string): MigrateOutcome {
+  const before = readLedger(dbPath);
+  if (before === null) {
+    return {
+      dbPath,
+      before: [],
+      after: [],
+      applied: [],
+      migrated: false,
+      verdict: "declined",
+      declinedReason: null,
+      backupPath: null,
+      error: existsSync(dbPath)
+        ? "database has no readable migration ledger"
+        : `database not found: ${dbPath}`,
+    };
+  }
+
+  try {
+    const result = ensureMigratedOnOpen(dbPath);
+    const after = readLedger(dbPath) ?? before;
+    return {
+      dbPath,
+      before,
+      after,
+      applied: [...result.appliedIds],
+      migrated: result.migrated,
+      verdict: result.verdict,
+      declinedReason: result.declinedReason ?? null,
+      backupPath: result.backupPath ?? null,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      dbPath,
+      before,
+      after: readLedger(dbPath) ?? before,
+      applied: [],
+      migrated: false,
+      verdict: "declined",
+      declinedReason: null,
+      backupPath: null,
+      error: error instanceof Error ? error.message.split("\n")[0] : String(error),
+    };
+  }
+}
+
+export function renderMigrate(outcome: MigrateOutcome): string {
+  const lines: string[] = ["Mirror runtime migrate", ""];
+  lines.push(`Database: ${outcome.dbPath}`);
+  if (outcome.error !== null) {
+    lines.push(`Migration error: ${outcome.error}`);
+    lines.push("");
+    lines.push("Migrate result: failed");
+    return `${lines.join("\n")}\n`;
+  }
+
+  // A standalone `runtime migrate` runs OUTSIDE the updater's backup-and-verify
+  // chain: its only pre-state is migrate-on-open's own snapshot, which uses one
+  // fixed name and is overwritten on each write. Inside the pipeline a verified
+  // archive was taken three stages earlier; run directly, this line is the only
+  // warning a user gets (CV22.DS10.US2 handoff review, security-engineer).
+  lines.push(`Ledger before: ${outcome.before.length} migration(s)`);
+  lines.push(`Ledger after: ${outcome.after.length} migration(s)`);
+  if (outcome.applied.length > 0) lines.push(`Applied: ${outcome.applied.join(", ")}`);
+  if (outcome.backupPath) lines.push(`Pre-migration snapshot: ${outcome.backupPath}`);
+  if (outcome.verdict === "declined" && outcome.declinedReason) {
+    lines.push(`Declined: ${outcome.declinedReason}.`);
+  }
+  if (!outcome.migrated) {
+    lines.push("Take a verified archive first if you are running this outside an update:");
+    lines.push("  runtime backup");
+  }
+  lines.push("");
+  // Three verdicts, three lines. `declined` is NOT `nothing pending`: the first
+  // says the engine refused work it could not safely do, the second that there
+  // was none. Conflating them is what let an update report a passing migrate
+  // stage on a database that had not been migrated.
+  lines.push(
+    outcome.verdict === "applied"
+      ? `Migrate result: applied ${outcome.applied.length} migration(s)`
+      : outcome.verdict === "declined"
+        ? "Migrate result: declined"
+        : "Migrate result: nothing pending",
+  );
+  return `${lines.join("\n")}\n`;
+}

package/ts/src/runtime/packageIdentity.ts

@@ -0,0 +1,102 @@
+// What identifies a Mirror Mind tree, and where its version comes from.
+//
+// CV22.DS10.TS5 plateau 1, decision D1. Until this story both answers were
+// read out of `pyproject.toml`:
+//
+//   * `packageVersion` walked upward for its `version =` line -- THE version,
+//     read by the updater, the release doctor, the welcome card,
+//     `runtime version|status`, the MCP server's `initialize`, and the Claude
+//     plugin builder (US2 decision D2: one body, so npm changes one place);
+//   * `isMirrorMindCheckout` identified a checkout as the first directory
+//     holding both `pyproject.toml` and `src/memory/`.
+//
+// The second one is why this module exists rather than a one-line edit.
+// Deleting `src/memory/` would have silently disabled the production
+// clone-role guard -- the check that stops Builder from mutating a production
+// clone -- because the guard would simply stop recognizing the tree. No test
+// would have failed. The inventory found it by reading; `cloneRoleGuard.test.ts`
+// now pins it.
+//
+// So identity moves to the TypeScript package, and both answers come from one
+// walk. CV22.DS10.US3 (decisions D1, D2) renamed the package to `mirror-mind`
+// and moved the manifest to the repository root, so a checkout and an
+// installed package have the same paths and one layout serves both.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * The npm package name that identifies this codebase, and the name
+ * `npm install -g` takes (CV22.DS10.US3, D1).
+ *
+ * It is checked rather than assumed so a stray `package.json` -- `.pi/`, a
+ * user's own project -- is never mistaken for Mirror Mind.
+ */
+export const PACKAGE_NAME = "mirror-mind";
+
+/**
+ * Where the manifest and the front door sit relative to a tree root.
+ *
+ * One layout, because the repository IS the package (US3, D2): the manifest at
+ * the root and the front door at `ts/src/frontDoor/cli.ts`, in a checkout and
+ * under `npm root -g` alike. Until US3 a second candidate described a
+ * flattened install that was never published.
+ */
+const MANIFEST = "package.json";
+const FRONT_DOOR = join("ts", "src", "frontDoor", "cli.ts");
+
+export interface PackageIdentity {
+  /** The tree root: the directory the manifest was found relative to. */
+  readonly root: string;
+  /** The manifest's `name`, whatever it is. */
+  readonly name: string;
+  /** The manifest's `version`, or null when it has none. */
+  readonly version: string | null;
+  /** True when `name` is this codebase's. */
+  readonly isMirrorMind: boolean;
+}
+
+function readIdentity(root: string): PackageIdentity | null {
+  const manifestPath = join(root, MANIFEST);
+  // BOTH markers, as Python required both `pyproject.toml` and `src/memory/`:
+  // a manifest alone is a file anyone can have, and the front door is what
+  // makes the tree this program.
+  if (!existsSync(manifestPath) || !existsSync(join(root, FRONT_DOOR))) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+      name?: unknown;
+      version?: unknown;
+    };
+    const name = typeof parsed.name === "string" ? parsed.name : "";
+    return {
+      root,
+      name,
+      version: typeof parsed.version === "string" ? parsed.version : null,
+      isMirrorMind: name === PACKAGE_NAME,
+    };
+  } catch {
+    // An unreadable or malformed manifest answers "not Mirror Mind" rather
+    // than continuing upward -- Python's `return False` inside the `except`,
+    // not a `continue`. A broken manifest is a broken tree, not an absent one.
+    return { root, name: "", version: null, isMirrorMind: false };
+  }
+}
+
+/**
+ * Walk upward for the nearest tree that carries a manifest AND a front door.
+ *
+ * **The walk STOPS at the first such directory, whatever it answers.** It does
+ * not keep climbing toward a tree that would say yes. That is Python's
+ * behavior for the pyproject/`src/memory` pair, and it is what makes a nested
+ * project decide for itself instead of inheriting its parent's identity.
+ */
+export function findPackageIdentity(start: string): PackageIdentity | null {
+  let current = resolve(start);
+  for (;;) {
+    const identity = readIdentity(current);
+    if (identity) return identity;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}