mirror-mind 0.0.1 → 0.32.1

package/ts/src/explorer/transition.ts

@@ -0,0 +1,72 @@
+// CV22.DS7.US7 plateau 1 — the △ EXPLORER MODE ACTIVE card, ported from
+// `render_explorer_mode_transition` (`src/memory/surfaces/mode_transition.py`).
+//
+// Same WIDTH as the story cards in `render.ts`, and the `_box`/`_line` bodies
+// are character-identical -- but `_wrap` is NOT. This module's oracle has no
+// `_chunk_word`: a word longer than the line overflows, and `_line` truncates
+// it to WIDTH. The story-card oracle chunks it across several lines instead.
+//
+// So the two helpers must stay separate. Factoring them into one shared
+// implementation silently changes whichever card did not win the merge, and
+// the only input that reveals it is a journey slug longer than 54 characters
+// -- which is exactly why the golden carries one.
+
+import { codePointLength, pySplitWhitespace, sliceCodePoints } from "#util/pythonText.ts";
+
+const WIDTH = 56;
+
+type Row = readonly [label: string, value: string];
+
+function line(text: string): string {
+  const content = sliceCodePoints(text, WIDTH);
+  return `│${content.padEnd(WIDTH + (content.length - codePointLength(content)))}│`;
+}
+
+/** `mode_transition._wrap`: greedy fill, long words NOT chunked. */
+function wrap(text: string): string[] {
+  const maxWidth = WIDTH - 2;
+  const words = pySplitWhitespace(text);
+  if (words.length === 0) return [""];
+
+  const lines: string[] = [];
+  let current = words[0] as string;
+  for (const word of words.slice(1)) {
+    if (codePointLength(current) + 1 + codePointLength(word) <= maxWidth) {
+      current += ` ${word}`;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  lines.push(current);
+  return lines;
+}
+
+function box(title: string, rows: readonly Row[]): string {
+  const lines = ["Mirror", `╭${"─".repeat(WIDTH)}╮`, line(`        ${title}`)];
+  for (const [label, value] of rows) {
+    lines.push(line(""));
+    lines.push(line(`  ${label}`));
+    for (const wrapped of wrap(value)) {
+      lines.push(line(`  ${wrapped}`));
+    }
+  }
+  lines.push(`╰${"─".repeat(WIDTH)}╯`);
+  return lines.join("\n");
+}
+
+/** Port of `render_explorer_mode_transition`. */
+export function renderExplorerModeTransition(journey: string): string {
+  return box("△  EXPLORER MODE ACTIVE", [
+    ["active journey", journey],
+    [
+      "availability",
+      "Explorer Mode is active and ready for durable exploration, story thickening, attractors, experiments, and Builder handoff.",
+    ],
+    [
+      "what this mode is",
+      "Exploration lens. Mirror preserves uncertainty, keeps signals, and thickens exploratory stories before construction.",
+    ],
+    ["boundary", "Explorer preserves uncertainty."],
+  ]);
+}

package/ts/src/extensions/bindings.ts

@@ -0,0 +1,170 @@
+// Extension capability bindings and `ext <id> migrate` (CV22.DS7.TS4 plateau 3).
+//
+// Port of `_cmd_bind`, `_cmd_unbind`, `_cmd_bindings`, `_cmd_migrate`, and
+// `_handle_binding` from `src/memory/cli/ext.py`. These are the family's first
+// WRITES, and two measured facts shape them:
+//
+//   * **A `--global` bind is not idempotent, and a persona bind is.**
+//     `_ext_bindings`'s primary key includes `target_id`, which is NULL for a
+//     global binding, and SQLite does not consider two NULLs equal in a
+//     (non-STRICT, rowid) primary key. So `INSERT OR IGNORE` ignores nothing:
+//     binding the same capability globally three times leaves THREE rows,
+//     where binding it to a persona three times leaves one. Measured on the
+//     real schema, reproduced here, and recorded as debt -- the docstring
+//     that says "No-op if already present (PK conflict)" is true only for the
+//     targeted kinds.
+//   * **`created_at` is Python's `isoformat()`**, with `+00:00` and
+//     microseconds -- NOT the `Z` form `_now()` uses elsewhere in Mirror. The
+//     write probe grades these bytes, so the clock seam yields that spelling.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { PROGRAM } from "#util/program.ts";
+import type { RenderedCommand } from "./catalog.ts";
+import { extensionNotInstalled, installedExtensionDir } from "./dispatch.ts";
+import { ExtensionError } from "./errors.ts";
+import { runMigrations } from "./migrations.ts";
+
+/** Python `datetime.now(timezone.utc).isoformat()`: `+00:00`, microseconds. */
+export function pythonUtcIsoformat(date: Date = new Date()): string {
+  return date.toISOString().replace(/\.(\d{3})Z$/, ".$1000+00:00");
+}
+
+export interface BindingDeps {
+  /** Injected so the corpus and the probe can freeze it. */
+  readonly nowIso: () => string;
+}
+
+export interface BindingTarget {
+  kind: "persona" | "journey" | "global";
+  id: string | null;
+}
+
+function out(stdout: string, exitCode = 0): RenderedCommand {
+  return { stdout, stderr: "", exitCode };
+}
+
+function label(target: BindingTarget): string {
+  return target.id ? `${target.kind}/${target.id}` : target.kind;
+}
+
+/** Port of `_cmd_bind`. */
+export function runBind(
+  db: WritableDatabase,
+  extensionId: string,
+  capabilityId: string,
+  target: BindingTarget,
+  deps: BindingDeps,
+): RenderedCommand {
+  db.prepare(
+    "INSERT OR IGNORE INTO _ext_bindings " +
+      "(extension_id, capability_id, target_kind, target_id, created_at) " +
+      "VALUES (?, ?, ?, ?, ?)",
+  ).run(extensionId, capabilityId, target.kind, target.id, deps.nowIso());
+  return out(`bound ${extensionId}/${capabilityId} -> ${label(target)}\n`);
+}
+
+/** Port of `_cmd_unbind`. `target_id IS ?` is what makes a global unbind work. */
+export function runUnbind(
+  db: WritableDatabase,
+  extensionId: string,
+  capabilityId: string,
+  target: BindingTarget,
+): RenderedCommand {
+  const result = db
+    .prepare(
+      "DELETE FROM _ext_bindings WHERE " +
+        "extension_id = ? AND capability_id = ? AND " +
+        "target_kind = ? AND (target_id IS ? OR target_id = ?)",
+    )
+    .run(extensionId, capabilityId, target.kind, target.id, target.id);
+  if (Number(result.changes) === 0) return out("no matching binding\n");
+  return out(`unbound ${extensionId}/${capabilityId} -> ${label(target)}\n`);
+}
+
+/** Port of `_cmd_bindings`. */
+export function runBindings(db: Database, extensionId: string): RenderedCommand {
+  const rows = db
+    .prepare(
+      "SELECT capability_id, target_kind, target_id, created_at " +
+        "FROM _ext_bindings WHERE extension_id = ? " +
+        "ORDER BY capability_id, target_kind, target_id",
+    )
+    .all(extensionId);
+  if (rows.length === 0) return out(`no bindings for extension/${extensionId}\n`);
+  const lines = [`=== bindings for extension/${extensionId} ===`];
+  for (const row of rows) {
+    const target = row.target_id ? String(row.target_id) : "(global)";
+    lines.push(`  ${String(row.capability_id)} -> ${String(row.target_kind)}/${target}`);
+  }
+  return out(`${lines.join("\n")}\n`);
+}
+
+/** Port of `_cmd_migrate`. An extension error is a printed line and exit 1. */
+export function runMigrate(
+  db: WritableDatabase,
+  mirrorHome: string,
+  extensionId: string,
+  deps: BindingDeps,
+): RenderedCommand {
+  // `installedExtensionDir`, not `join`: Python builds this path without
+  // normalizing it and then PRINTS it, so `ext ../../etc migrate` must answer
+  // with the traversal intact. Plateau 3 shipped `join` here and plateau 4's
+  // measurement caught it -- the bindings golden only ever passed a plain id.
+  const extensionDir = installedExtensionDir(mirrorHome, extensionId);
+  if (!existsSync(extensionDir)) return extensionNotInstalled(mirrorHome, extensionId);
+  try {
+    const applied = runMigrations(db, extensionId, join(extensionDir, "migrations"), deps);
+    return out(`applied ${applied} migration(s) for extension/${extensionId}\n`);
+  } catch (error) {
+    if (!(error instanceof ExtensionError)) throw error;
+    return out(`${error.message}\n`, 1);
+  }
+}
+
+/**
+ * Port of `_handle_binding`'s parser.
+ *
+ * The LAST target flag wins, because Python overwrites `target_kind`/
+ * `target_id` on every match rather than refusing a second one; an
+ * unrecognised token refuses immediately with the token quoted.
+ */
+export function parseBindingTail(
+  extensionId: string,
+  action: "bind" | "unbind",
+  tail: readonly string[],
+): (BindingTarget & { capabilityId: string }) | RenderedCommand {
+  if (tail.length === 0) {
+    return out(
+      `usage: ${PROGRAM} ext ${extensionId} ${action} <capability> ` +
+        "(--persona <id> | --journey <id> | --global)\n",
+      1,
+    );
+  }
+  const capabilityId = tail[0] as string;
+  let kind: BindingTarget["kind"] | null = null;
+  let id: string | null = null;
+  for (let index = 1; index < tail.length; index += 1) {
+    const token = tail[index] as string;
+    const value = tail[index + 1];
+    if (token === "--persona" && value !== undefined) {
+      kind = "persona";
+      id = value;
+      index += 1;
+    } else if (token === "--journey" && value !== undefined) {
+      kind = "journey";
+      id = value;
+      index += 1;
+    } else if (token === "--global") {
+      kind = "global";
+      id = null;
+    } else {
+      return out(`unrecognised argument '${token}'\n`, 1);
+    }
+  }
+  if (kind === null) {
+    return out("missing target: pass --persona <id>, --journey <id>, or --global\n", 1);
+  }
+  return { capabilityId, kind, id };
+}

package/ts/src/extensions/catalog.ts

@@ -0,0 +1,249 @@
+// Extension catalog READS (CV22.DS7.TS4 plateau 1).
+//
+// Port of the read half of `src/memory/cli/extensions.py` plus the catalog
+// branches of `cli/inspect.py` and `cli/ext.py`: discovery, the runtime
+// filter, the runtime catalog file, and the five renderers behind
+// `extensions list|validate`, `ext list`, `list extensions`, `inspect
+// extension`, and `inspect runtime-catalog`.
+//
+// MEASURED AT PLATEAU 1, and the reason the golden grades exit codes:
+// `extensions` and `ext` are hand-rolled parsers. Every refusal in this family
+// prints to **stdout** and exits **1** -- stderr is empty even for a bare
+// `inspect` or an unknown `list` target. Three measured facts a reading of the
+// code would not have given:
+//
+//   * `extensions validate` and `extensions sync` print the INVALID block and
+//     exit 1 BEFORE reaching their own "sync requires --runtime" message, so an
+//     invalid extension masks a usage error;
+//   * `ext --help` and a bare `ext` print the same bytes and differ only in
+//     exit code (0 against 1);
+//   * a MISSING or CORRUPT runtime catalog is rendered as an empty catalog at
+//     exit **0**, not as an error -- `_load_catalog` swallows both.
+//
+// The write half (`sync`, `install`, `uninstall`, `expose-claude`,
+// `clean-claude`) is plateau 4 and deliberately absent.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { sortByCodePoint } from "#util/pythonText.ts";
+import { ExtensionValidationError } from "./errors.ts";
+import { type ExtensionManifest, loadExtensionManifest } from "./manifest.ts";
+
+/** Port of `default_extensions_dir_for_home`. */
+export function extensionsRootForHome(mirrorHome: string): string {
+  return join(mirrorHome, "extensions");
+}
+
+/** Port of `default_runtime_skills_dir_for_home`. */
+export function runtimeSkillsRootForHome(mirrorHome: string, runtime: string): string {
+  return join(mirrorHome, "runtime", "skills", runtime);
+}
+
+export interface DiscoveryResult {
+  manifests: ExtensionManifest[];
+  /** `(extension_id, message)` pairs, in discovery order. */
+  errors: Array<readonly [string, string]>;
+}
+
+/**
+ * Port of `discover_extensions`.
+ *
+ * A missing root is empty, not an error. A child that is not a directory or
+ * carries no `skill.yaml` is skipped SILENTLY -- only a present-but-invalid
+ * manifest becomes an error row. Python iterates `sorted(root.iterdir())`;
+ * every child shares one parent, so that is name order by code point.
+ */
+export function discoverExtensions(extensionsRoot: string): DiscoveryResult {
+  if (!existsSync(extensionsRoot)) return { manifests: [], errors: [] };
+
+  const manifests: ExtensionManifest[] = [];
+  const errors: Array<readonly [string, string]> = [];
+  for (const name of sortByCodePoint(readdirSync(extensionsRoot))) {
+    const child = join(extensionsRoot, name);
+    if (!isDirectory(child)) continue;
+    if (!existsSync(join(child, "skill.yaml"))) continue;
+    try {
+      manifests.push(loadExtensionManifest(child));
+    } catch (error) {
+      if (!(error instanceof ExtensionValidationError)) throw error;
+      errors.push([name, error.message] as const);
+    }
+  }
+  return { manifests, errors };
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Port of `filter_manifests_for_runtime`. */
+export function filterManifestsForRuntime(
+  manifests: readonly ExtensionManifest[],
+  runtime: string | null,
+): ExtensionManifest[] {
+  if (runtime === null) return [...manifests];
+  return manifests.filter((manifest) => runtime in manifest.runtimes);
+}
+
+function invalidBlock(errors: ReadonlyArray<readonly [string, string]>): string {
+  if (errors.length === 0) return "";
+  const lines = ["", "=== INVALID EXTENSIONS ==="];
+  for (const [extensionId, message] of errors) lines.push(`  ${extensionId}: ${message}`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** Port of `print_extension_list`. */
+export function renderExtensionList(
+  manifests: readonly ExtensionManifest[],
+  errors: ReadonlyArray<readonly [string, string]>,
+  root: string,
+): string {
+  const lines = [`Extensions root: ${root}`, "=== EXTENSIONS ==="];
+  if (manifests.length === 0) lines.push("  (none)");
+  for (const manifest of manifests) {
+    lines.push(`  ${manifest.id} [${manifest.kind}]`);
+    lines.push(`    name: ${manifest.name}`);
+    const parts = sortByCodePoint(Object.keys(manifest.runtimes)).map(
+      (runtimeName) => `${runtimeName}=${manifest.runtimes[runtimeName]?.commandName ?? ""}`,
+    );
+    lines.push(`    runtimes: ${parts.join(", ")}`);
+  }
+  return `${lines.join("\n")}\n${invalidBlock(errors)}`;
+}
+
+/** Port of `ext._cmd_list`: command-skills only, id and summary. */
+export function renderCommandSkillList(
+  manifests: readonly ExtensionManifest[],
+  errors: ReadonlyArray<readonly [string, string]>,
+  root: string,
+): string {
+  const commandSkills = manifests.filter((manifest) => manifest.kind === "command-skill");
+  const lines = [`Extensions root: ${root}`, "=== COMMAND-SKILL EXTENSIONS ==="];
+  if (commandSkills.length === 0) lines.push("  (none)");
+  for (const manifest of commandSkills) lines.push(`  ${manifest.id}: ${manifest.summary}`);
+  return `${lines.join("\n")}\n${invalidBlock(errors)}`;
+}
+
+export interface RenderedCommand {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Port of `_inspect_extension`. The refusal is TWO stdout lines and exit 1,
+ * with the validator's own message as the reason -- so a broken manifest and
+ * an absent directory are reported the same way, differing only in the reason.
+ */
+export function renderInspectExtension(root: string, extensionId: string): RenderedCommand {
+  let manifest: ExtensionManifest;
+  try {
+    manifest = loadExtensionManifest(join(root, extensionId));
+  } catch (error) {
+    if (!(error instanceof ExtensionValidationError)) throw error;
+    return {
+      stdout: `extension/${extensionId} not found or invalid\nreason: ${error.message}\n`,
+      stderr: "",
+      exitCode: 1,
+    };
+  }
+
+  const lines = [
+    `=== extension/${extensionId} ===`,
+    `name: ${manifest.name}`,
+    `category: ${manifest.category}`,
+    `kind: ${manifest.kind}`,
+    `summary: ${manifest.summary}`,
+    `root: ${manifest.root}`,
+    `manifest_path: ${manifest.manifestPath}`,
+  ];
+  if (manifest.entrypoint.length > 0) {
+    lines.push("entrypoint:");
+    for (const [key, value] of manifest.entrypoint) lines.push(`  ${key}: ${value}`);
+  }
+  lines.push("runtimes:");
+  for (const runtimeName of sortByCodePoint(Object.keys(manifest.runtimes))) {
+    const runtime = manifest.runtimes[runtimeName];
+    if (runtime === undefined) continue;
+    lines.push(`  ${runtimeName}:`);
+    lines.push(`    command_name: ${runtime.commandName}`);
+    if (runtime.skillFile) lines.push(`    skill_file: ${runtime.skillFile}`);
+    if (runtime.skillPath) lines.push(`    skill_path: ${runtime.skillPath}`);
+  }
+  return { stdout: `${lines.join("\n")}\n`, stderr: "", exitCode: 0 };
+}
+
+export interface RuntimeCatalog {
+  schemaVersion: unknown;
+  runtime: unknown;
+  generatedAt: unknown;
+  extensions: unknown[];
+}
+
+/**
+ * Port of `_load_catalog`. Absent, unreadable, and malformed all answer with
+ * the same empty catalog -- the reason `inspect runtime-catalog` on a corrupt
+ * file exits 0. A bare LIST is the schema-0 legacy shape.
+ */
+export function loadCatalog(catalogPath: string): RuntimeCatalog {
+  const empty: RuntimeCatalog = {
+    schemaVersion: "1",
+    runtime: undefined,
+    generatedAt: undefined,
+    extensions: [],
+  };
+  if (!existsSync(catalogPath)) return empty;
+  let data: unknown;
+  try {
+    data = JSON.parse(readFileSync(catalogPath, "utf8"));
+  } catch {
+    return empty;
+  }
+  if (Array.isArray(data)) {
+    return { schemaVersion: "0", runtime: undefined, generatedAt: undefined, extensions: data };
+  }
+  if (typeof data !== "object" || data === null) return empty;
+  const record = data as Record<string, unknown>;
+  return {
+    schemaVersion: record.schema_version,
+    runtime: record.runtime,
+    generatedAt: record.generated_at,
+    extensions: Array.isArray(record.extensions) ? record.extensions : [],
+  };
+}
+
+function catalogField(value: unknown): string {
+  return value === undefined || value === null ? "(unknown)" : String(value);
+}
+
+/** Port of `_inspect_runtime_catalog`. Always exit 0, even with no catalog. */
+export function renderInspectRuntimeCatalog(runtimeRoot: string, runtime: string): string {
+  const catalogPath = join(runtimeRoot, "extensions.json");
+  const catalog = loadCatalog(catalogPath);
+  const lines = [
+    `=== runtime-catalog/${runtime} ===`,
+    `runtime_root: ${runtimeRoot}`,
+    `catalog_path: ${catalogPath}`,
+    `schema_version: ${catalogField(catalog.schemaVersion)}`,
+    `generated_at: ${catalogField(catalog.generatedAt)}`,
+    "extensions:",
+  ];
+  if (catalog.extensions.length === 0) {
+    lines.push("  (none)");
+    return `${lines.join("\n")}\n`;
+  }
+  for (const item of catalog.extensions) {
+    const entry = (typeof item === "object" && item !== null ? item : {}) as Record<
+      string,
+      unknown
+    >;
+    lines.push(`  ${catalogField(entry.id)} -> ${catalogField(entry.command_name)}`);
+    lines.push(`    kind: ${catalogField(entry.kind)}`);
+    lines.push(`    installed_skill_path: ${catalogField(entry.installed_skill_path)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}