mirror-mind 0.0.1 → 0.32.1

package/ts/src/guards/packContents.ts

@@ -0,0 +1,306 @@
+// What the npm tarball may hold, checked rather than trusted. CV22.DS10.US3
+// plateau 1, the artifact half of DS10's Zero Python gate.
+//
+// `files` in the manifest is a whitelist, and npm adds a few things on its
+// own (README, LICENSE, the manifest). Nothing here repeats that list: this
+// guard asks whether the packed inventory is the RUNTIME SUBSET and nothing
+// else -- every runtime's integration files present, every entry point
+// present, no test, golden, smoke, eval, scratch, environment file, database,
+// Python, Windows product, or spike; and no install lifecycle script, so that
+// installing Mirror is a file copy. The retired-surface guard proves the
+// tree's code spawns no interpreter; this one proves the shipped files carry
+// none.
+//
+// Pure over an inventory, so it can be graded on synthetic lists; the script
+// feeds it `npm pack --dry-run --json`.
+
+import { INTERPRETER_INVOCATIONS } from "#guards/retiredSurfaces.ts";
+import { PACKAGE_NAME } from "#runtime/packageIdentity.ts";
+
+/** Directory prefixes (with trailing slash) and exact files the tarball may contain. */
+export const ALLOWED_PREFIXES: readonly string[] = [
+  "bin/",
+  "ts/src/",
+  "templates/",
+  "docs/releases/",
+  ".pi/extensions/",
+  ".pi/skills/",
+  ".claude/hooks/",
+  ".gemini/hooks/",
+  "plugins/mirror-mind/",
+  "scripts/codex-hooks/",
+];
+
+export const ALLOWED_FILES: readonly string[] = [
+  "package.json",
+  "README.md",
+  "LICENSE",
+  "AGENTS.md",
+  "ts/README.md",
+  "scripts/codex-mirror.sh",
+];
+
+/** Files that must be in every tarball: the entries and one of each runtime's wiring. */
+export const REQUIRED_FILES: readonly string[] = [
+  "package.json",
+  "README.md",
+  "LICENSE",
+  "AGENTS.md",
+  "bin/loader.js",
+  "bin/mirror.js",
+  "bin/mirror-hook.js",
+  "ts/src/frontDoor/cli.ts",
+  "ts/src/hooks/main.ts",
+  "ts/src/mcp/main.ts",
+  ".pi/extensions/mirror-logger.ts",
+  ".pi/skills/mm-mirror/SKILL.md",
+  ".claude/hooks/session-start.sh",
+  ".gemini/hooks/session-start.sh",
+  "plugins/mirror-mind/mcp/launch.sh",
+  "scripts/codex-hooks/session-start.sh",
+  "scripts/codex-mirror.sh",
+];
+
+/** Prefixes that must have at least one file: content the program reads at runtime. */
+export const REQUIRED_PREFIXES: readonly string[] = ["templates/identity/", "docs/releases/"];
+
+/**
+ * What must never ship, by path. Each is a class the first panel named or a
+ * file the Zero Python gate forbids. A path matching any of these fails even
+ * when it sits under an allowed prefix (a `.test.ts` inside `ts/src/`, say).
+ */
+export const FORBIDDEN_PATTERNS: readonly { pattern: RegExp; why: string }[] = [
+  {
+    pattern: /(^|\/)ts\/(test|smoke|evals|parity)\//,
+    why: "tests, smokes, evals, and parity tooling",
+  },
+  { pattern: /\.test\.ts$/, why: "a test file" },
+  { pattern: /(^|\/)goldens?\//, why: "a golden" },
+  { pattern: /^tmp\//, why: "scratch" },
+  { pattern: /(^|\/)\.env(\.|$)/, why: "an environment file" },
+  { pattern: /\.(db|sqlite|sqlite3)$/, why: "a database" },
+  { pattern: /\.(py|pyc)$/, why: "Python" },
+  { pattern: /(^|\/)(pyproject\.toml|uv\.lock|requirements[^/]*\.txt)$/, why: "Python packaging" },
+  { pattern: /^(frame|installer)\//, why: "the Windows product" },
+  { pattern: /^(spikes|examples)\//, why: "spikes and examples" },
+  { pattern: /(^|\/)node_modules\//, why: "dependencies belong to npm, not the tarball" },
+  { pattern: /(^|\/)\.git(\/|$)/, why: "git metadata" },
+  { pattern: /\.(tgz|zip|exe|dmg)$/, why: "a binary artifact" },
+];
+
+/** Lifecycle scripts npm would run on install. Installing Mirror is a file copy. */
+export const FORBIDDEN_SCRIPTS: readonly string[] = [
+  "preinstall",
+  "install",
+  "postinstall",
+  "prepare",
+];
+
+export interface PackManifest {
+  name?: unknown;
+  version?: unknown;
+  private?: unknown;
+  bin?: unknown;
+  files?: unknown;
+  scripts?: unknown;
+}
+
+export interface PackInventory {
+  /** Paths as `npm pack --dry-run --json` lists them, relative to the package root. */
+  readonly files: readonly string[];
+  readonly manifest: PackManifest;
+}
+
+/**
+ * The file list in `npm pack --dry-run --json`'s output, whichever shape npm
+ * printed it in: npm 11 prints an array of packed packages, npm 12 an object
+ * keyed by package name. The release workflow's first run (2026-10-10) met
+ * the second with a reader written for the first and graded an EMPTY
+ * inventory -- every required file "missing" -- which is at least loud; an
+ * inventory with no files is never a valid answer, so it throws rather than
+ * letting a future reader grade nothing as clean.
+ */
+export function parsePackDryRun(raw: string): string[] {
+  const parsed: unknown = JSON.parse(raw);
+  const entries: unknown[] = Array.isArray(parsed)
+    ? parsed
+    : parsed !== null && typeof parsed === "object"
+      ? Object.values(parsed)
+      : [];
+  const first = entries[0];
+  const files =
+    first !== null &&
+    typeof first === "object" &&
+    Array.isArray((first as { files?: unknown }).files)
+      ? ((first as { files: { path?: unknown }[] }).files ?? [])
+      : [];
+  const paths = files
+    .map((entry) => entry.path)
+    .filter((path): path is string => typeof path === "string");
+  if (paths.length === 0) {
+    throw new Error("npm pack --dry-run --json listed no files; the inventory cannot be graded");
+  }
+  return paths;
+}
+
+/**
+ * What no shipped file may say, wherever it sits. Paths are graded above; this
+ * grades content, because a file can be in the runtime subset and still carry
+ * something that must not reach another person's machine.
+ *
+ * The runtime subset is read by whoever installed Mirror -- their agent loads
+ * the skills and AGENTS.md -- so it addresses them, never the mirror's first
+ * owner. US3 F4 found two skills telling every user's agent to present its
+ * proposals to the author by first name. The author is credited where that is
+ * the point, the license and the README.
+ *
+ * The second rule is the artifact half of DS10's Zero Python gate (US3
+ * plateau 5). The retired-surface guard proves the TREE spawns no interpreter,
+ * and the path rules above prove the tarball carries no Python file; this
+ * proves no shipped file tells an agent or a person to run the deleted core.
+ * The forms are the retired-surface guard's own list, imported, so the two
+ * halves cannot drift. Two places may still carry them: `docs/releases/`, each
+ * version's record of what it said and what was removed, which `runtime
+ * release-notes` shows as written; and the guard whose patterns ARE the data.
+ *
+ * Each pattern is written so that this file, which ships too, never matches
+ * it. An `allowedIn` entry ending in `/` is a prefix.
+ */
+export const FORBIDDEN_CONTENT: readonly {
+  pattern: RegExp;
+  why: string;
+  allowedIn: readonly string[];
+}[] = [
+  {
+    pattern: /Vin[ií]cius/i,
+    why: "names the author; shipped instructions address whoever installed Mirror",
+    allowedIn: ["LICENSE", "README.md"],
+  },
+  {
+    pattern: new RegExp(INTERPRETER_INVOCATIONS.join("|")),
+    why: "tells someone to run the Python core, deleted by CV22.DS10.TS5; the artifact carries none",
+    allowedIn: ["docs/releases/", "ts/src/guards/retiredSurfaces.ts"],
+  },
+];
+
+function allowedToSay(rule: { allowedIn: readonly string[] }, path: string): boolean {
+  return rule.allowedIn.some((entry) =>
+    entry.endsWith("/") ? path.startsWith(entry) : path === entry,
+  );
+}
+
+/** One shipped file, as the content check reads it. */
+export interface PackedFile {
+  readonly path: string;
+  readonly content: string;
+}
+
+export interface PackProblem {
+  readonly code:
+    | "forbidden_path"
+    | "forbidden_content"
+    | "unlisted_path"
+    | "missing_file"
+    | "missing_prefix"
+    | "lifecycle_script"
+    | "manifest";
+  readonly message: string;
+}
+
+function allowed(path: string): boolean {
+  return ALLOWED_FILES.includes(path) || ALLOWED_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+
+/** Every way the inventory departs from the runtime subset, in a stable order. */
+export function checkPackContents(inventory: PackInventory): PackProblem[] {
+  const problems: PackProblem[] = [];
+  const files = [...inventory.files].sort();
+  const present = new Set(files);
+
+  for (const path of files) {
+    const forbidden = FORBIDDEN_PATTERNS.find(({ pattern }) => pattern.test(path));
+    if (forbidden) {
+      problems.push({ code: "forbidden_path", message: `${path}: ${forbidden.why}` });
+      continue;
+    }
+    if (!allowed(path)) {
+      problems.push({ code: "unlisted_path", message: `${path}: not in the runtime subset` });
+    }
+  }
+
+  for (const path of REQUIRED_FILES) {
+    if (!present.has(path)) problems.push({ code: "missing_file", message: `${path}: required` });
+  }
+  for (const prefix of REQUIRED_PREFIXES) {
+    if (!files.some((path) => path.startsWith(prefix))) {
+      problems.push({ code: "missing_prefix", message: `${prefix}: nothing under it` });
+    }
+  }
+
+  const { manifest } = inventory;
+  if (manifest.name !== PACKAGE_NAME) {
+    problems.push({
+      code: "manifest",
+      message: `name: ${JSON.stringify(manifest.name)} is not ${PACKAGE_NAME}`,
+    });
+  }
+  if (manifest.private === true) {
+    problems.push({ code: "manifest", message: "private: true; the package cannot be published" });
+  }
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) {
+    problems.push({ code: "manifest", message: "files: missing; the tarball is not whitelisted" });
+  }
+  const bin = manifest.bin;
+  if (
+    typeof bin !== "object" ||
+    bin === null ||
+    typeof (bin as { mirror?: unknown }).mirror !== "string"
+  ) {
+    problems.push({ code: "manifest", message: "bin.mirror: missing" });
+  } else {
+    const entry = (bin as { mirror: string }).mirror.replace(/^\.\//, "");
+    if (!present.has(entry)) {
+      problems.push({ code: "manifest", message: `bin.mirror: ${entry} is not in the tarball` });
+    }
+  }
+  const scripts = manifest.scripts;
+  if (typeof scripts === "object" && scripts !== null) {
+    for (const name of FORBIDDEN_SCRIPTS) {
+      if (name in scripts) {
+        problems.push({
+          code: "lifecycle_script",
+          message: `scripts.${name}: npm would run it on install; installing Mirror is a file copy`,
+        });
+      }
+    }
+  }
+
+  return problems;
+}
+
+/** Every forbidden line in the shipped files, as `path:line: why`, in a stable order. */
+export function checkPackedContent(files: readonly PackedFile[]): PackProblem[] {
+  const problems: PackProblem[] = [];
+  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    for (const rule of FORBIDDEN_CONTENT) {
+      if (allowedToSay(rule, file.path)) continue;
+      file.content.split("\n").forEach((line, index) => {
+        if (rule.pattern.test(line)) {
+          problems.push({
+            code: "forbidden_content",
+            message: `${file.path}:${index + 1}: ${rule.why}`,
+          });
+        }
+      });
+    }
+  }
+  return problems;
+}
+
+export function renderPackVerdict(problems: readonly PackProblem[], fileCount: number): string {
+  if (problems.length === 0) {
+    return `pack contents: clean -- ${fileCount} files, the runtime subset and nothing else; no install script; no forbidden content.\n`;
+  }
+  const lines = problems.map((problem) => `  ${problem.code}: ${problem.message}`);
+  return `pack contents: ${problems.length} problem(s)\n${lines.join("\n")}\n`;
+}

package/ts/src/guards/piSourcedSkills.ts

@@ -0,0 +1,70 @@
+// Skills with one body in every runtime (CR102).
+//
+// Most Mirror skills have two authored bodies. `.pi/skills/` serves Pi, and
+// through the `.agents/skills/` links Codex and Gemini CLI too. `.claude/skills/`
+// serves Claude Code, and `claudePlugin.ts` copies it into the plugin. CR071
+// kept the two apart on purpose: Usage sections, example language, and in
+// `mm-soul` and `mm-mirror` whole lines that are true for one runtime only.
+//
+// `mm-build` had no such line, and its two bodies drifted anyway. By 2026-09-27
+// the Claude Code copy was 108 lines against Pi's 1093, with no activation
+// boundary, no journey binding, and no Ariad. So a skill in this list has one
+// body: its Pi copy is the only one anyone edits, and `claudePlugin.ts`
+// generates both Claude Code copies from it with this module's transform.
+//
+// A skill joins the list only when its Pi body is true in every runtime, which
+// is a decision to record in `docs/project/decisions.md`, not a refactoring.
+
+export const PI_SKILLS_DIR = ".pi/skills";
+
+/** Skills whose Claude Code copies are generated from the Pi copy. */
+export const PI_SOURCED_SKILLS: readonly string[] = ["mm-build"];
+
+const MIRROR_PREFIX = "mm-";
+
+/** The Claude Code name of a Mirror skill: `mm-build` is `mm:build` (CR071). */
+export function claudeSkillName(skill: string): string {
+  if (!skill.startsWith(MIRROR_PREFIX)) {
+    throw new Error(
+      `${skill} is not a Mirror skill: its name does not start with ${MIRROR_PREFIX}`,
+    );
+  }
+  return `mm:${skill.slice(MIRROR_PREFIX.length)}`;
+}
+
+/**
+ * The Claude Code copy of a Pi-sourced skill: the Pi text with its frontmatter
+ * `name` line rewritten, and every other byte unchanged.
+ *
+ * Refuses, naming `sourcePath`, unless the frontmatter holds exactly one `name`
+ * line and it names this skill as every Mirror skill does. A transform that
+ * guessed would write a wrong name into a file nobody edits by hand.
+ */
+export function claudeVariant(skill: string, piText: string, sourcePath: string): string {
+  const lines = piText.split("\n");
+  const close = lines.indexOf("---", 1);
+  if (lines[0] !== "---" || close === -1) {
+    throw new Error(`${sourcePath}: has no frontmatter`);
+  }
+
+  const expected = `name: "${skill}"`;
+  const nameLines = lines
+    .slice(1, close)
+    .map((line, offset) => ({ line, index: offset + 1 }))
+    .filter(({ line }) => line.startsWith("name:"));
+  if (nameLines.length !== 1 || nameLines[0].line !== expected) {
+    throw new Error(
+      `${sourcePath}: expected exactly one frontmatter line \`${expected}\`, ` +
+        `found ${describeFound(nameLines.map(({ line }) => line))}`,
+    );
+  }
+
+  lines[nameLines[0].index] = `name: "${claudeSkillName(skill)}"`;
+  return lines.join("\n");
+}
+
+function describeFound(nameLines: readonly string[]): string {
+  if (nameLines.length === 0) return "none";
+  if (nameLines.length > 1) return String(nameLines.length);
+  return `\`${nameLines[0]}\``;
+}

package/ts/src/guards/retiredRouteShadows.ts

@@ -0,0 +1,57 @@
+// A retired shape must route, underneath its retired entry, like any name
+// nobody claims (CV22.DS10.TS5, inventory F2).
+//
+// TS4 added the `retired` route and matched it BEFORE dispatch, so the family
+// branches that used to answer the same shapes became unreachable -- and stayed
+// in the file, because a branch the front door can never reach is invisible to
+// every test that goes through the front door. Two of them survived into TS5:
+// the backfill flags and the twenty Workbench verbs, each still routed to
+// Python by name.
+//
+// The file-scanning guard cannot see this. Its `sqlite-refinement-workbench`
+// row exempts `routing.ts` whole, because the retired entries legitimately
+// name the verbs they refuse -- and a file-level exemption is blind to
+// everything else in that file (TS2's lesson). So this check asks the router
+// instead: route each retired shape with the retired match removed, route an
+// unclaimed sibling that differs only in its final token, and require the two
+// decisions to be the same. A family branch keyed on the retired token is the
+// only thing that can make them differ.
+
+import { RETIRED_SURFACES, type RetiredSurface, type RouteDecision } from "#frontDoor/routing.ts";
+
+/** A final token no family names, so the sibling reaches whatever answers the unclaimed. */
+const UNCLAIMED_TOKEN = "__retired_route_sibling__";
+
+export interface ShadowedRetiredRoute {
+  /** The retired shape, as its entry names it. */
+  readonly surface: string;
+  /** What the family branch underneath answers for it -- a route decision reason, never argv. */
+  readonly reason: string;
+}
+
+/**
+ * Every retired shape that some family branch still claims by name.
+ *
+ * `route` is the family router without the retired match -- `routeByFamily` in
+ * production, a fake in the guard's own test, so the check can be seen to fire.
+ * Reasons are compared with the sibling's placeholder restored to the retired
+ * token, because a generic answer such as `unknown runtime subcommand: <name>`
+ * legitimately echoes whichever name it was given.
+ */
+export function shadowedRetiredRoutes(
+  route: (argv: readonly string[]) => RouteDecision,
+  surfaces: readonly RetiredSurface[] = RETIRED_SURFACES,
+): ShadowedRetiredRoute[] {
+  const shadowed: ShadowedRetiredRoute[] = [];
+  for (const entry of surfaces) {
+    const argv = entry.surface.split(" ");
+    const token = argv[argv.length - 1] ?? "";
+    const underneath = route(argv);
+    const unclaimed = route([...argv.slice(0, -1), UNCLAIMED_TOKEN]);
+    const unclaimedReason = unclaimed.reason.split(UNCLAIMED_TOKEN).join(token);
+    if (underneath.engine !== unclaimed.engine || underneath.reason !== unclaimedReason) {
+      shadowed.push({ surface: entry.surface, reason: underneath.reason });
+    }
+  }
+  return shadowed;
+}