mirror-mind 0.0.1 → 0.32.1

package/ts/src/runtime/backup.ts

@@ -0,0 +1,151 @@
+// `runtime backup` — create, VERIFY, and say how to recover (CV22.DS10.US2).
+//
+// Not the `backup` command DS7.TS1 ported. That one creates an archive and
+// stops; this one is the updater's safety stage, and the promise it makes is
+// "a backup exists and was verified before the tree moved". Three functions,
+// characterized from `src/memory/cli/runtime.py:1052-1113`, with exactly one
+// deliberate difference, documented on `verifyBackupArchive`.
+
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { NotAReadableZipError, readZipEntry, readZipEntryNames } from "#backup/zipReader.ts";
+import { quickCheckDatabaseFile } from "#db/database.ts";
+
+/** The member every Mirror backup must hold. */
+const ARCHIVE_MEMBER = "memory.db";
+/** The only members it may hold: the database and SQLite's own sidecars. */
+const ALLOWED_MEMBERS = new Set(["memory.db", "memory.db-wal", "memory.db-shm"]);
+
+export interface BackupVerification {
+  backupPath: string;
+  valid: boolean;
+  entries: string[];
+  note: string | null;
+}
+
+function refuse(backupPath: string, entries: string[], note: string): BackupVerification {
+  return { backupPath, valid: false, entries, note };
+}
+
+/** Python's `Path(entry).is_absolute() or ".." in Path(entry).parts`. */
+function isUnsafeEntry(name: string): boolean {
+  if (name.startsWith("/")) return true;
+  // Windows-shaped absolutes, which `PurePath` would not call absolute on
+  // POSIX but which no Mirror archive has any reason to carry.
+  if (/^[A-Za-z]:[\\/]/.test(name)) return true;
+  return name.split(/[\\/]/).includes("..");
+}
+
+/**
+ * Does this database open and pass SQLite's own consistency check?
+ *
+ * THE ONE DELIBERATE DEVIATION FROM THE ORACLE. Python verifies entry NAMES:
+ * an archive holding a `memory.db` of 4 KB of zeros is reported `valid`, which
+ * is measured and recorded in the story's plateau-0 baseline. The updater
+ * relies on this verdict immediately before it moves the tree, so a backup
+ * that has never been opened is a belief rather than a backup.
+ *
+ * Runs on an extracted copy in a temp dir removed afterwards: the archive is
+ * untrusted input and this never touches the live database. The check itself
+ * goes through `#db/database.ts`, the one module allowed to hold the driver --
+ * an external `sqlite3` binary is not guaranteed on a user's machine, and a
+ * second SQLite access path is not something a verifier should introduce.
+ */
+function integrityNote(data: Buffer): string | null {
+  const dir = mkdtempSync(join(tmpdir(), "mirror-verify-"));
+  const path = join(dir, ARCHIVE_MEMBER);
+  try {
+    writeFileSync(path, data, { mode: 0o600 });
+    const { ok, verdict } = quickCheckDatabaseFile(path);
+    return ok ? null : `${ARCHIVE_MEMBER} failed integrity check: ${verdict}`;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Port of `verify_backup_archive`, in the oracle's order of refusal. */
+export function verifyBackupArchive(backupPath: string): BackupVerification {
+  if (!existsSync(backupPath)) return refuse(backupPath, [], "backup file not found");
+
+  let entries: string[];
+  let buffer: Buffer;
+  try {
+    buffer = readFileSync(backupPath);
+    entries = readZipEntryNames(buffer);
+  } catch (error) {
+    if (error instanceof NotAReadableZipError) {
+      return refuse(backupPath, [], "backup file is not a readable zip");
+    }
+    throw error;
+  }
+
+  // Before anything is read OUT of the archive: an entry that would escape the
+  // Mirror home is refused, with the names still reported so the operator can
+  // see what it held.
+  for (const entry of entries) {
+    if (isUnsafeEntry(entry)) return refuse(backupPath, entries, `unsafe archive entry: ${entry}`);
+  }
+  if (!entries.includes(ARCHIVE_MEMBER)) {
+    return refuse(backupPath, entries, `${ARCHIVE_MEMBER} missing from backup`);
+  }
+  const unexpected = entries.filter((entry) => !ALLOWED_MEMBERS.has(entry));
+  if (unexpected.length > 0) {
+    return refuse(backupPath, entries, `unexpected archive entries: ${unexpected.join(", ")}`);
+  }
+
+  let member: Buffer | null;
+  try {
+    member = readZipEntry(buffer, ARCHIVE_MEMBER);
+  } catch (error) {
+    if (error instanceof NotAReadableZipError) {
+      return refuse(backupPath, entries, `${ARCHIVE_MEMBER} failed to open: ${error.message}`);
+    }
+    throw error;
+  }
+  if (member === null) {
+    return refuse(backupPath, entries, `${ARCHIVE_MEMBER} missing from backup`);
+  }
+  const note = integrityNote(member);
+  if (note !== null) return refuse(backupPath, entries, note);
+
+  return { backupPath, valid: true, entries, note: null };
+}
+
+/** Port of `render_backup_verification`. */
+export function renderBackupVerification(verification: BackupVerification): string {
+  const lines = ["Mirror runtime backup verification", ""];
+  lines.push(`Backup: ${verification.backupPath}`);
+  if (verification.entries.length > 0) lines.push(`Entries: ${verification.entries.join(", ")}`);
+  if (verification.note) lines.push(`Verification note: ${verification.note}`);
+  lines.push(`Verification result: ${verification.valid ? "valid" : "invalid"}`);
+  return `${lines.join("\n")}\n`;
+}
+
+export interface BackupCreatedInput {
+  backupPath: string;
+  mirrorHome: string;
+  verification: BackupVerification;
+}
+
+/** Port of `render_runtime_backup_created`, recovery route included. */
+export function renderRuntimeBackupCreated(input: BackupCreatedInput): string {
+  const lines = ["Mirror runtime backup", ""];
+  lines.push(`Mirror home: ${input.mirrorHome}`);
+  lines.push(`Backup: ${input.backupPath}`);
+  lines.push(`Verification result: ${input.verification.valid ? "valid" : "invalid"}`);
+  if (input.verification.entries.length > 0) {
+    lines.push(`Entries: ${input.verification.entries.join(", ")}`);
+  }
+  if (input.verification.note) lines.push(`Verification note: ${input.verification.note}`);
+  lines.push("");
+  lines.push("Manual recovery route:");
+  lines.push("  1. Stop active runtime sessions that could write to the database.");
+  lines.push("  2. Move current memory.db, memory.db-wal, and memory.db-shm aside.");
+  lines.push("  3. Extract memory.db and sidecars from this backup into the Mirror home.");
+  lines.push("  4. Run runtime status against the Mirror home.");
+  lines.push("  5. Do not retry update execution until status is ready.");
+  lines.push("");
+  lines.push("Recovery is manual in this version; no files were restored.");
+  return `${lines.join("\n")}\n`;
+}

package/ts/src/runtime/channel.ts

@@ -0,0 +1,146 @@
+// `runtime channel [stable|main]` — where an install keeps the channel it
+// follows, read and written in one place. (CV22.DS10.US3 plateau 4, D9; pays
+// US2's D-027, which left the package channel file with no writer.)
+//
+// The channel is scoped the way the INSTALL is scoped. A clone keeps its
+// `.mirror-update-channel` marker at the checkout root, per checkout and
+// gitignored, so switching it leaves the tree clean for the update gate. A
+// package is one `npm install -g` per OS user while a Mirror home is not:
+// reading the channel from `<mirror-home>/…` would let two homes over one
+// global install re-tag each other on alternating updates, so it lives beside
+// the user's own config file instead, `${XDG_CONFIG_HOME:-~/.config}/mirror/`.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { type ConfigEnv, configFilePath } from "#runtime/config.ts";
+import { inspectUpdateChannel, type MarkerValue } from "#runtime/git.ts";
+import { describeInstallKind, type InstallKind } from "#runtime/installKind.ts";
+import { DEFAULT_CHANNEL, KNOWN_CHANNELS } from "#runtime/updatePipeline.ts";
+
+const CLONE_MARKER = ".mirror-update-channel";
+
+/** The file this install's channel lives in, or null when it has nowhere to. */
+export function channelPathFor(
+  install: InstallKind,
+  env: ConfigEnv = process.env,
+  home: string = homedir(),
+): string | null {
+  if (install.kind === "clone") return join(install.repository, CLONE_MARKER);
+  if (install.kind === "package") return join(dirname(configFilePath(env, home)), "update-channel");
+  return null;
+}
+
+/** `stable`, `main`, or null for anything else, after trimming and lowercasing. */
+export function normalizeChannel(raw: string): string | null {
+  const value = raw.trim().toLowerCase();
+  return KNOWN_CHANNELS.has(value) ? value : null;
+}
+
+function readPackageChannel(path: string): MarkerValue {
+  if (!existsSync(path)) return { value: DEFAULT_CHANNEL, source: null, note: null };
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { value: DEFAULT_CHANNEL, source: path, note: `unreadable: ${message}` };
+  }
+  const value = normalizeChannel(raw);
+  if (value !== null) return { value, source: path, note: null };
+  return {
+    value: DEFAULT_CHANNEL,
+    source: path,
+    note: `unknown channel '${raw.trim().toLowerCase()}', defaulting to ${DEFAULT_CHANNEL}`,
+  };
+}
+
+/**
+ * The channel this install follows: the override when one was given, else
+ * the install's own file, else the default. One answer for `update`,
+ * `--check`, `status`, `version`, and `channel`.
+ */
+export function channelFor(
+  install: InstallKind,
+  env: ConfigEnv = process.env,
+  home: string = homedir(),
+  override: string | null = null,
+): MarkerValue {
+  if (install.kind === "clone") return inspectUpdateChannel(install.repository, override);
+  if (override) {
+    const value = normalizeChannel(override);
+    if (value !== null) return { value, source: null, note: "command override" };
+    return {
+      value: DEFAULT_CHANNEL,
+      source: null,
+      note: `unknown channel '${override.trim().toLowerCase()}', defaulting to ${DEFAULT_CHANNEL}`,
+    };
+  }
+  if (install.kind === "package") {
+    return readPackageChannel(join(dirname(configFilePath(env, home)), "update-channel"));
+  }
+  return { value: DEFAULT_CHANNEL, source: null, note: "install kind unknown" };
+}
+
+export type ChannelWrite =
+  | { ok: true; path: string; value: string; previous: string }
+  | { ok: false; reason: string; exitCode: 1 | 2 };
+
+/**
+ * Persist the channel for this install. The value is checked against the
+ * vocabulary before anything is created; an unknown install is refused
+ * rather than guessed. For a package the config directory may not exist yet
+ * (`init` has not run), and it is created `0700`, as `init` creates it: the
+ * env file that later lands there holds the API key.
+ */
+export function setChannel(
+  install: InstallKind,
+  raw: string,
+  env: ConfigEnv = process.env,
+  home: string = homedir(),
+): ChannelWrite {
+  const value = normalizeChannel(raw);
+  if (value === null) {
+    return {
+      ok: false,
+      reason: `unknown channel ${JSON.stringify(raw)}: choose stable or main`,
+      exitCode: 2,
+    };
+  }
+  const path = channelPathFor(install, env, home);
+  if (path === null) {
+    return {
+      ok: false,
+      reason: `install kind unknown (${describeInstallKind(install)}): the channel has no home`,
+      exitCode: 1,
+    };
+  }
+  const previous = channelFor(install, env, home).value;
+  if (install.kind === "package") {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+  }
+  writeFileSync(path, `${value}\n`, "utf8");
+  return { ok: true, path, value, previous };
+}
+
+export interface ChannelView {
+  install: InstallKind;
+  channel: MarkerValue;
+  /** Present after a write: what the channel was before it. */
+  written: { previous: string } | null;
+}
+
+export function renderChannel(view: ChannelView): string {
+  const lines = ["Mirror runtime update channel", ""];
+  lines.push(`Install: ${describeInstallKind(view.install)}`);
+  const was =
+    view.written !== null && view.written.previous !== view.channel.value
+      ? ` (was ${view.written.previous})`
+      : "";
+  lines.push(`Update channel: ${view.channel.value}${was}`);
+  if (view.channel.note) lines.push(`Update channel note: ${view.channel.note}`);
+  lines.push(`Source: ${view.channel.source ?? "default"}`);
+  return `${lines.join("\n")}\n`;
+}

package/ts/src/runtime/config.ts

@@ -0,0 +1,168 @@
+// Where Mirror Mind's configuration comes from, and the warning filter every
+// entry point needs. CV22.DS10.US3 plateau 1, decision D3.
+//
+// Until this story every invocation carried `--env-file=.env` and
+// `NODE_OPTIONS=--no-warnings`: 135 skill lines, the Pi extension, the twelve
+// hook wrappers, and the MCP launcher each repeated both. Only a checkout can
+// satisfy the first (an installed package ships no `.env`), and a `bin` shim
+// sets neither. So the program does both itself, once, here, and the three
+// entries (`frontDoor/cli.ts`, `hooks/main.ts`, `mcp/main.ts`) call this
+// module before they touch the database.
+//
+// Two files, one order, nothing overridden:
+//
+//   1. the real environment -- whatever the shell or the runtime set;
+//   2. `<tree root>/.env` -- the clone's, located from the ENTRY FILE rather
+//      than from the cwd, so a skill run from /tmp reads the same file the
+//      checkout's own commands do. The tarball excludes `.env*`, so for an
+//      installed package this step finds nothing and says so;
+//   3. `${XDG_CONFIG_HOME:-~/.config}/mirror/env` -- the OS user's, in the
+//      directory CV22.DS10.US2 already chose for the package update channel.
+//
+// `process.loadEnvFile` has `--env-file` semantics: it fills what is unset and
+// never overrides, which is what makes the order above a precedence rather
+// than a last-writer-wins. A second mirror on the same machine runs with
+// `MIRROR_USER=<other>` in the shell, exactly as before.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseEnv } from "node:util";
+import { findPackageIdentity } from "./packageIdentity.ts";
+
+export type ConfigSource =
+  | { kind: "environment" }
+  | { kind: "tree_env"; path: string }
+  | { kind: "user_config"; path: string };
+
+export interface ConfigurationReport {
+  /** Every source that contributed, in precedence order. */
+  readonly sources: readonly ConfigSource[];
+}
+
+/** The env-var slice this module reads. `process.env` satisfies it. */
+export interface ConfigEnv {
+  XDG_CONFIG_HOME?: string | undefined;
+  [key: string]: string | undefined;
+}
+
+export interface ConfigIo {
+  env?: ConfigEnv;
+  home?: string;
+}
+
+/** `${XDG_CONFIG_HOME:-~/.config}/mirror/env`, the OS user's Mirror configuration. */
+export function configFilePath(env: ConfigEnv = process.env, home: string = homedir()): string {
+  const xdg = env.XDG_CONFIG_HOME;
+  const configHome = xdg && xdg.length > 0 ? xdg : join(home, ".config");
+  return join(configHome, "mirror", "env");
+}
+
+export interface LoadConfigurationOptions extends ConfigIo {
+  /**
+   * The running entry file (`import.meta.filename` of `cli.ts`, `hooks/main.ts`,
+   * or `mcp/main.ts`). The tree's `.env` is located by walking up from here.
+   */
+  entryPath: string;
+  /** Present only so a test can prove the cwd is NOT consulted. */
+  cwd?: string;
+  /** Injection for tests; defaults to `process.loadEnvFile` semantics. */
+  loadEnvFile?: (path: string, env: ConfigEnv) => void;
+}
+
+/**
+ * Fill `env` from the two files, in order, without overriding anything already
+ * set. Returns which sources contributed so `runtime status` and `diagnose`
+ * can print them.
+ */
+export function loadConfiguration(options: LoadConfigurationOptions): ConfigurationReport {
+  const env = options.env ?? process.env;
+  const home = options.home ?? homedir();
+  const load = options.loadEnvFile ?? loadEnvFileWithoutOverride;
+  const sources: ConfigSource[] = [{ kind: "environment" }];
+
+  const tree = findPackageIdentity(dirname(options.entryPath));
+  if (tree !== null) {
+    const treeEnv = join(tree.root, ".env");
+    if (existsSync(treeEnv)) {
+      load(treeEnv, env);
+      sources.push({ kind: "tree_env", path: treeEnv });
+    }
+  }
+
+  const userConfig = configFilePath(env, home);
+  if (existsSync(userConfig)) {
+    load(userConfig, env);
+    sources.push({ kind: "user_config", path: userConfig });
+  }
+
+  return { sources };
+}
+
+/**
+ * `process.loadEnvFile` fills `process.env` and nothing else. When the target
+ * is `process.env` that is exactly the call; for any other object (a test's),
+ * the file is parsed with Node's own parser and applied with the same
+ * no-override rule, so the two paths cannot disagree about precedence.
+ */
+function loadEnvFileWithoutOverride(path: string, env: ConfigEnv): void {
+  if (env === process.env) {
+    process.loadEnvFile(path);
+    return;
+  }
+  for (const [key, value] of Object.entries(parseEnv(readFileSync(path, "utf8")))) {
+    if (!(key in env)) env[key] = value;
+  }
+}
+
+/**
+ * Write one `KEY=value` line into the user's config file, creating the file
+ * `0600` inside a `0700` directory, replacing the key's line if it is already
+ * there and appending otherwise. Everything else in the file is preserved
+ * byte for byte: this is where `OPENROUTER_API_KEY` lives, added by hand, and
+ * `init` must never rewrite it.
+ */
+export function writeConfigValue(key: string, value: string, io: ConfigIo = {}): string {
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) {
+    throw new Error(`config key must be an environment variable name, got ${JSON.stringify(key)}`);
+  }
+  if (/[\r\n]/.test(value)) {
+    throw new Error("config value must not contain a newline");
+  }
+  const path = configFilePath(io.env ?? process.env, io.home ?? homedir());
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+
+  const line = `${key}=${value}`;
+  let body = "";
+  if (existsSync(path)) {
+    const lines = readFileSync(path, "utf8").split("\n");
+    if (lines.at(-1) === "") lines.pop();
+    const index = lines.findIndex((l) => l.replace(/^\s*(export\s+)?/, "").startsWith(`${key}=`));
+    if (index >= 0) lines[index] = line;
+    else lines.push(line);
+    body = `${lines.join("\n")}\n`;
+  } else {
+    body = `${line}\n`;
+  }
+  writeFileSync(path, body, { encoding: "utf8", mode: 0o600 });
+  chmodSync(path, 0o600);
+  return path;
+}
+
+/**
+ * Keep `node:sqlite`'s ExperimentalWarning off stderr, in-process.
+ *
+ * Every skill used to pass `NODE_OPTIONS=--no-warnings`; a `bin` shim, an MCP
+ * client, and a hook wrapper set no such thing, and for the MCP server stderr
+ * is the client's log. Other warnings still print, one line each, because a
+ * deprecation or a memory-leak warning is information.
+ */
+export function silenceExperimentalWarnings(): void {
+  process.removeAllListeners("warning");
+  process.on("warning", (warning) => {
+    if (warning.name === "ExperimentalWarning") return;
+    process.stderr.write(`${warning.name}: ${warning.message}\n`);
+  });
+}