mirror-mind 0.35.0 → 0.36.0

package/ts/src/extensions/catalogWrites.ts

@@ -56,6 +56,7 @@ import { readSubcommandListing } from "./dispatch.ts";
 import { ExtensionError, ExtensionValidationError } from "./errors.ts";
 import { type ExtensionManifest, loadExtensionManifest } from "./manifest.ts";
 import { runMigrations } from "./migrations.ts";
+import { extensionSettingsPath } from "./settings.ts";
 
 /** Port of `_COPY_IGNORE_PATTERNS`: never shipped inside an installed tree. */
 const COPY_IGNORE_EXACT = new Set([
@@ -400,6 +401,13 @@ export interface UninstallReport {
   bindingsRemoved: number;
   removed: Array<readonly [string, string[]]>;
   sourceRemoved: boolean;
+  /**
+   * The settings file (CR145) a full uninstall found and left in place, or
+   * null. Kept on purpose -- deleting configuration a person wrote is the
+   * worse surprise -- and named on purpose: a credential that outlives the
+   * extension it served must not be silent.
+   */
+  settingsKept: string | null;
 }
 
 /** Port of `uninstall_extension`. */
@@ -461,6 +469,8 @@ export function uninstallExtension(options: {
     }
     rmSync(installedDir, { recursive: true, force: true });
   }
+  const settingsPath = extensionSettingsPath(mirrorHome, extensionId);
+  const settingsKept = options.runtime === null && existsSync(settingsPath) ? settingsPath : null;
 
   return {
     extensionId,
@@ -468,6 +478,7 @@ export function uninstallExtension(options: {
     bindingsRemoved,
     removed,
     sourceRemoved: options.runtime === null,
+    settingsKept,
   };
 }
 
@@ -641,6 +652,7 @@ export function renderUninstallReport(report: UninstallReport): RenderedCommand
     `  installed: ${report.installedDir}`,
   ];
   if (report.sourceRemoved) lines.push("  source tree: removed");
+  if (report.settingsKept !== null) lines.push(`  settings left in place: ${report.settingsKept}`);
   if (report.bindingsRemoved) {
     lines.push(`  bindings: ${report.bindingsRemoved} row(s) removed`);
   }

package/ts/src/extensions/contextRuntime.ts

@@ -3,6 +3,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { parse } from "yaml";
 import type { Database } from "#db/database.ts";
+import {
+  type ExtensionSettings,
+  readExtensionSettings,
+  settingsUnderEnvironment,
+} from "./settings.ts";
 
 export const MIRROR_CONTEXT_PROTOCOL = "mirror-context-v1";
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -47,6 +52,13 @@ export type ExtensionContextDiagnosticKind =
    * going dark is visible as a migration state, not as an empty context.
    */
   | "no_provider_runtime"
+  /**
+   * The extension's settings file (CR145) exists and could not be read. Its
+   * own kind, not `provider_failed`: months later the Mirror Mode warning
+   * must name the cause, and "the provider crashed" and "a file you chmod'ed
+   * cannot be read" are different repairs.
+   */
+  | "settings_unreadable"
   | "provider_failed"
   | "provider_timeout"
   | "invalid_output";
@@ -181,11 +193,17 @@ export function collectExtensionContext(
       diagnostics.push({ kind: "no_provider_runtime" });
       continue;
     }
+    const settings = readExtensionSettings(options.mirrorHome, binding.extensionId);
+    if (settings.kind === "unreadable") {
+      diagnostics.push({ kind: "settings_unreadable" });
+      continue;
+    }
     const outcome = invokeProvider(
       capability.providerRuntime.command,
       extensionRoot,
       request,
       options,
+      settings,
     );
     if (outcome.diagnostic) {
       diagnostics.push({ kind: outcome.diagnostic });
@@ -221,6 +239,20 @@ export function readProvidersWithoutRuntime(extensionRoot: string): string[] {
   }
 }
 
+/**
+ * The capability ids the manifest declares, for `bind` to check against
+ * (CR149). Tolerant like its siblings: an unreadable manifest declares
+ * nothing, and `bind` has already run the validator, whose message is the
+ * one a person should read for that case.
+ */
+export function readDeclaredCapabilityIds(extensionRoot: string): string[] {
+  try {
+    return readContextManifest(extensionRoot).capabilities.map((capability) => capability.id);
+  } catch {
+    return [];
+  }
+}
+
 function readContextManifest(extensionRoot: string): ExtensionManifest {
   const manifestPath = resolve(extensionRoot, "skill.yaml");
   const raw = parse(readFileSync(manifestPath, "utf8")) as unknown;
@@ -286,12 +318,15 @@ function invokeProvider(
   cwd: string,
   request: ExtensionContextRequest,
   options: CollectExtensionContextOptions,
+  settings: ExtensionSettings,
 ): { text?: string | null; diagnostic?: ExtensionContextDiagnosticKind } {
   const result = spawnSync(command[0] as string, command.slice(1), {
     cwd,
     encoding: "utf8",
     input: `${JSON.stringify(request)}\n`,
-    env: options.environment ?? process.env,
+    // The settings file under the environment (CR145): the same rule the
+    // dispatcher applies, minus the `MIRROR_*` layer a provider gets on stdin.
+    env: settingsUnderEnvironment(options.environment ?? process.env, settings),
     timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     maxBuffer: options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
     windowsHide: true,

package/ts/src/extensions/dispatch.ts

@@ -44,6 +44,12 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { parse } from "yaml";
 import type { RenderedCommand } from "./catalog.ts";
 import { tablePrefixFor } from "./migrations.ts";
+import {
+  describeExtensionSettings,
+  type ExtensionSettings,
+  readExtensionSettings,
+  settingsUnderEnvironment,
+} from "./settings.ts";
 
 export const MIRROR_CLI_PROTOCOL = "mirror-cli-v1";
 
@@ -189,13 +195,18 @@ function commandStaysInside(extensionRoot: string, command: readonly string[]):
  * one thing the legacy bridge cannot offer. Argv is appended to the declared
  * command verbatim, so a declared command sees exactly what a legacy handler
  * sees.
+ *
+ * Three layers, lowest first: the extension's settings file (CR145), the
+ * environment the `mirror` process had, and the five names Mirror owns. The
+ * spread order IS the precedence rule.
  */
 function declaredEnvironment(
   dispatch: ExtensionDispatch,
   options: DispatchOptions,
+  settings: ExtensionSettings,
 ): NodeJS.ProcessEnv {
   return {
-    ...(options.environment ?? process.env),
+    ...settingsUnderEnvironment(options.environment ?? process.env, settings),
     MIRROR_HOME: dispatch.mirrorHome,
     MIRROR_DATABASE_PATH: options.databasePath,
     MIRROR_EXTENSION_ID: dispatch.extensionId,
@@ -292,19 +303,29 @@ export function readSubcommandListing(extensionRoot: string): SubcommandEntry[]
  * this TypeScript's surface from here on -- a recorded divergence, not a
  * parity failure. Sorted by name, as Python sorted its registry, so the bytes
  * stay stable across manifest reordering.
+ *
+ * The last line is the extension's settings file (CR145): its absolute path,
+ * in the spelling `extension not installed:` uses, and its state. It is
+ * unindented so it reads as a footer, not as a subcommand named `settings:`.
+ * Pure: the caller read the file; this function only says what it found.
  */
-export function renderSubcommandListing(extensionId: string, entries: SubcommandEntry[]): string {
+export function renderSubcommandListing(
+  extensionId: string,
+  entries: SubcommandEntry[],
+  settings: ExtensionSettings,
+): string {
   const lines = [`=== subcommands of extension/${extensionId} ===`];
   if (entries.length === 0) {
     lines.push("  (none declared)");
-    return `${lines.join("\n")}\n`;
-  }
-  const sorted = [...entries].sort((left, right) => (left.name < right.name ? -1 : 1));
-  for (const entry of sorted) {
-    const summary = entry.summary ? ` — ${entry.summary}` : "";
-    const flag = entry.hasRuntime ? "" : "  (no runtime declared)";
-    lines.push(`  ${entry.name}${summary}${flag}`);
+  } else {
+    const sorted = [...entries].sort((left, right) => (left.name < right.name ? -1 : 1));
+    for (const entry of sorted) {
+      const summary = entry.summary ? ` — ${entry.summary}` : "";
+      const flag = entry.hasRuntime ? "" : "  (no runtime declared)";
+      lines.push(`  ${entry.name}${summary}${flag}`);
+    }
   }
+  lines.push(describeExtensionSettings(settings));
   return `${lines.join("\n")}\n`;
 }
 
@@ -343,11 +364,23 @@ export function runExtensionSubcommand(
   }
   if (!existsSync(dispatch.extensionRoot)) return 1;
 
+  // Read after the id and installed checks, before the spawn: running without
+  // the settings the user wrote is the failure the file exists to prevent, so
+  // an unreadable file is a refusal, and a refusal starts nothing.
+  const settings = readExtensionSettings(dispatch.mirrorHome, dispatch.extensionId);
+  if (settings.kind === "unreadable") {
+    report(
+      `Mirror: extension/${dispatch.extensionId} has a settings file that cannot be read: ` +
+        `${settings.path} (${settings.reason}).`,
+    );
+    return 1;
+  }
+
   const [executable, ...head] = dispatch.command;
   const spawn = options.spawn ?? spawnSync;
   const result = spawn(executable as string, [...head, ...dispatch.argv], {
     cwd: dispatch.extensionRoot,
-    env: declaredEnvironment(dispatch, options),
+    env: declaredEnvironment(dispatch, options, settings),
     // All three streams are the user's: a declared command may read stdin,
     // which is precisely what the retired bridge could never allow.
     stdio: "inherit",

package/ts/src/extensions/extensionPlugin.ts

@@ -0,0 +1,325 @@
+// CV21.DS5.US2 — the per-home extensions plugin.
+//
+// A Mirror home's installed extensions reach Claude Code, Codex, Antigravity, and
+// Grok Build as one generated plugin per home, in the canonical plugin's format:
+//
+//   <home>/runtime/plugin/
+//     .agents/plugins/marketplace.json     the Codex marketplace, named for the home
+//     mirror-ext-<user>/
+//       .claude-plugin/plugin.json         name, version, description — no hooks, no server
+//       plugin.json                        the root marker Grok and agy read (DS10.US1)
+//       skills/<dir>/SKILL.md              each installed extension's `claude` skill
+//
+// DS5.TS1 measured the three shapes DS12.TS5 left open and chose this one: a plugin is
+// listed and found on all four runtimes, needs no manifest rewritten (it carries the
+// `claude` skill the manifests already declare), and installs beside another home's.
+// Its price is that Codex, agy, and Grok copy a plugin, so a changed extension is live
+// only after a reinstall — which is why the version matters: Codex keys its cache by
+// it and `runtime diagnose` compares it.
+//
+// The generator is a pure function from the home's `claude` catalog — the same reader
+// `expose-claude` projects from, so the plugin carries what `expose-claude` exposes —
+// to a sorted file map. The version is `0.1.<generation>`, advanced by one when the
+// tree differs from the one on disk and held when it does not: an identical
+// regeneration must not tell every runtime it is stale. The writer replaces the tree
+// atomically (write `plugin.next`, rename over `plugin`), so Claude Code, which reads
+// the directory in place through a link, never sees a half tree. The tree holds only
+// regular files the generator wrote.
+
+import {
+  type Dirent,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { pythonJsonDumpsIndentedOrdered } from "#util/pyGenerators.ts";
+import { discoverExtensions, extensionsRootForHome, runtimeSkillsRootForHome } from "./catalog.ts";
+import { filesystemSkillDirName } from "./catalogWrites.ts";
+
+export const EXTENSION_PLUGIN_SEGMENTS: readonly string[] = ["runtime", "plugin"];
+const MARKETPLACE_RELATIVE = ".agents/plugins/marketplace.json";
+const VERSION_PREFIX = "0.1.";
+
+/** The plugin's name, which is also its Codex marketplace's: one per home. */
+export function extensionPluginName(user: string): string {
+  return `mirror-ext-${user}`;
+}
+
+/** The marketplace root: what `codex plugin marketplace add` takes. */
+export function extensionPluginRoot(mirrorHome: string): string {
+  return join(mirrorHome, ...EXTENSION_PLUGIN_SEGMENTS);
+}
+
+/** The plugin directory: what Claude Code links, and agy and Grok install. */
+export function extensionPluginDirectory(mirrorHome: string): string {
+  return join(extensionPluginRoot(mirrorHome), extensionPluginName(basename(mirrorHome)));
+}
+
+/** Relative path → file content, sorted by path. */
+export type PluginFileMap = Readonly<Record<string, string>>;
+
+export interface PluginEntry {
+  /** The `claude` block's `command_name`, e.g. `ext:review-copy`. */
+  readonly commandName: string;
+  /** The installed skill file's bytes, copied verbatim: frontmatter is the author's. */
+  readonly content: string;
+}
+
+export interface PluginPlan {
+  readonly name: string;
+  readonly version: string;
+  readonly generation: number;
+  readonly skills: number;
+  /** True when the tree differs from `previous` (or there was none). */
+  readonly changed: boolean;
+  readonly files: PluginFileMap;
+}
+
+export interface PreviousPlugin {
+  readonly generation: number;
+  readonly files: PluginFileMap;
+}
+
+function render(user: string, entries: readonly PluginEntry[], generation: number): PluginFileMap {
+  const name = extensionPluginName(user);
+  const version = `${VERSION_PREFIX}${generation}`;
+  const sorted = [...entries].sort((a, b) =>
+    a.commandName < b.commandName ? -1 : a.commandName > b.commandName ? 1 : 0,
+  );
+  const skills = sorted.length;
+  const manifest = {
+    name,
+    version,
+    description: `Extensions of the Mirror home ${user}: ${skills} skill${skills === 1 ? "" : "s"}`,
+  };
+  const marketplace = {
+    name,
+    owner: { name: "Mirror Mind" },
+    plugins: [
+      {
+        name,
+        source: { source: "local", path: `./${name}` },
+        description: manifest.description,
+      },
+    ],
+  };
+  const files: Record<string, string> = {
+    [MARKETPLACE_RELATIVE]: `${pythonJsonDumpsIndentedOrdered(marketplace)}\n`,
+    [`${name}/.claude-plugin/plugin.json`]: `${pythonJsonDumpsIndentedOrdered(manifest)}\n`,
+    [`${name}/plugin.json`]: `${pythonJsonDumpsIndentedOrdered(manifest)}\n`,
+  };
+  for (const entry of sorted) {
+    files[`${name}/skills/${filesystemSkillDirName(entry.commandName)}/SKILL.md`] = entry.content;
+  }
+  return Object.fromEntries(Object.entries(files).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+function sameFiles(a: PluginFileMap, b: PluginFileMap): boolean {
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key) => key in b && a[key] === b[key]);
+}
+
+/**
+ * The plan: the tree at the previous generation, compared to the previous tree;
+ * when it differs, the tree at the next generation. The version appears in both
+ * manifests, so a changed tree is re-rendered after the bump.
+ */
+export function planExtensionPlugin(input: {
+  user: string;
+  entries: readonly PluginEntry[];
+  previous: PreviousPlugin | null;
+}): PluginPlan {
+  const name = extensionPluginName(input.user);
+  const skills = input.entries.length;
+  if (input.previous === null) {
+    const files = render(input.user, input.entries, 1);
+    return { name, version: `${VERSION_PREFIX}1`, generation: 1, skills, changed: true, files };
+  }
+  const held = render(input.user, input.entries, input.previous.generation);
+  if (sameFiles(held, input.previous.files)) {
+    return {
+      name,
+      version: `${VERSION_PREFIX}${input.previous.generation}`,
+      generation: input.previous.generation,
+      skills,
+      changed: false,
+      files: held,
+    };
+  }
+  const generation = input.previous.generation + 1;
+  return {
+    name,
+    version: `${VERSION_PREFIX}${generation}`,
+    generation,
+    skills,
+    changed: true,
+    files: render(input.user, input.entries, generation),
+  };
+}
+
+/** The tree on disk as a file map with its generation, or null when there is none. */
+export function readExtensionPlugin(mirrorHome: string): PreviousPlugin | null {
+  const root = extensionPluginRoot(mirrorHome);
+  const manifestPath = join(extensionPluginDirectory(mirrorHome), ".claude-plugin", "plugin.json");
+  if (!existsSync(manifestPath)) return null;
+  let generation: number;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const version =
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>).version
+        : undefined;
+    const match = typeof version === "string" ? /^0\.1\.(\d+)$/.exec(version) : null;
+    if (match === null) return null;
+    generation = Number(match[1]);
+  } catch {
+    return null;
+  }
+  const files: Record<string, string> = {};
+  for (const path of walk(root)) {
+    files[path.slice(root.length + 1)] = readFileSync(path, "utf8");
+  }
+  return {
+    generation,
+    files: Object.fromEntries(
+      Object.entries(files).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    ),
+  };
+}
+
+function walk(root: string): string[] {
+  const found: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) found.push(...walk(path));
+    else if (entry.isFile()) found.push(path);
+  }
+  return found.sort();
+}
+
+/**
+ * Replace the tree atomically: the map is written to `plugin.next`, then renamed over
+ * `plugin`. The path a runtime links or installed from is unchanged; a removed skill's
+ * directory is gone because the whole tree is new. Mode 0700, like the rest of the home.
+ */
+export function writeExtensionPlugin(mirrorHome: string, files: PluginFileMap): void {
+  const root = extensionPluginRoot(mirrorHome);
+  const next = `${root}.next`;
+  const old = `${root}.old`;
+  rmSync(next, { recursive: true, force: true });
+  mkdirSync(next, { recursive: true, mode: 0o700 });
+  for (const [relative, content] of Object.entries(files)) {
+    const path = join(next, relative);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, content, { encoding: "utf8", mode: 0o600 });
+  }
+  rmSync(old, { recursive: true, force: true });
+  if (existsSync(root)) renameSync(root, old);
+  renameSync(next, root);
+  rmSync(old, { recursive: true, force: true });
+}
+
+export interface ExtensionPluginReport {
+  readonly name: string;
+  readonly directory: string;
+  readonly marketplaceRoot: string;
+  readonly version: string;
+  readonly skills: number;
+  readonly changed: boolean;
+  /** Installed extensions that declare no `claude` block, and so are not carried. */
+  readonly notCarried: readonly string[];
+}
+
+/** The home's `claude` catalog entries that still have a skill file, as plugin entries. */
+export function claudeCatalogEntries(mirrorHome: string): PluginEntry[] | null {
+  const catalogPath = join(runtimeSkillsRootForHome(mirrorHome, "claude"), "extensions.json");
+  if (!existsSync(catalogPath)) return null;
+  let items: unknown[];
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(catalogPath, "utf8"));
+    const list =
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>).extensions
+        : undefined;
+    items = Array.isArray(list) ? list : [];
+  } catch {
+    items = [];
+  }
+  const entries: PluginEntry[] = [];
+  for (const item of items) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) continue;
+    const record = item as Record<string, unknown>;
+    const commandName = record.command_name;
+    const skillPath = record.installed_skill_path;
+    if (typeof commandName !== "string" || typeof skillPath !== "string") continue;
+    if (!existsSync(skillPath)) continue;
+    entries.push({ commandName, content: readFileSync(skillPath, "utf8") });
+  }
+  return entries;
+}
+
+/**
+ * Regenerate the home's plugin from its `claude` catalog. A home with no catalog has
+ * never installed an extension that declares `claude`, and gets no plugin.
+ */
+export function regenerateExtensionPlugin(mirrorHome: string): ExtensionPluginReport | null {
+  const entries = claudeCatalogEntries(mirrorHome);
+  if (entries === null) return null;
+  const carried = new Set(readCatalogIds(mirrorHome) ?? []);
+  const notCarried = discoverExtensions(extensionsRootForHome(mirrorHome))
+    .manifests.map((manifest) => manifest.id)
+    .filter((id) => !carried.has(id))
+    .sort();
+  const plan = planExtensionPlugin({
+    user: basename(mirrorHome),
+    entries,
+    previous: readExtensionPlugin(mirrorHome),
+  });
+  if (plan.changed || readExtensionPlugin(mirrorHome) === null)
+    writeExtensionPlugin(mirrorHome, plan.files);
+  return {
+    name: plan.name,
+    directory: extensionPluginDirectory(mirrorHome),
+    marketplaceRoot: extensionPluginRoot(mirrorHome),
+    version: plan.version,
+    skills: plan.skills,
+    changed: plan.changed,
+    notCarried,
+  };
+}
+
+/** The extension ids the home's `claude` catalog names, or null without a catalog. */
+function readCatalogIds(mirrorHome: string): string[] | null {
+  const catalogPath = join(runtimeSkillsRootForHome(mirrorHome, "claude"), "extensions.json");
+  if (!existsSync(catalogPath)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(catalogPath, "utf8"));
+    const list =
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>).extensions
+        : undefined;
+    if (!Array.isArray(list)) return [];
+    return list
+      .map((item) =>
+        typeof item === "object" && item !== null && !Array.isArray(item)
+          ? (item as Record<string, unknown>).id
+          : undefined,
+      )
+      .filter((id): id is string => typeof id === "string");
+  } catch {
+    return [];
+  }
+}

package/ts/src/extensions/manifest.ts

@@ -31,7 +31,13 @@ import { tablePrefixFor } from "./migrations.ts";
 
 const ALLOWED_KINDS = new Set(["prompt-skill", "command-skill"]);
 const RUNTIME_NAME_RE = /^[a-z][a-z0-9_-]*$/;
-const SKILL_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * What an extension id may look like. `install` is the authority on ids, so
+ * this is THE grammar; the settings reader (CR145) builds a path from an id
+ * only after it passes here. Two older copies of the rule still live in
+ * `contextRuntime.ts` and `dispatch.ts` -- CR147 reconciles them.
+ */
+export const SKILL_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const REQUIRED_FIELDS = ["id", "name", "category", "kind", "summary", "runtimes"] as const;
 const PATH_LIKE_SUFFIXES = new Set([".js", ".mjs", ".cjs", ".py"]);