mirror-mind 0.35.0 → 0.36.1

package/ts/src/extensions/bindings.ts

@@ -22,8 +22,10 @@ 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 { readDeclaredCapabilityIds } from "./contextRuntime.ts";
 import { extensionNotInstalled, installedExtensionDir } from "./dispatch.ts";
-import { ExtensionError } from "./errors.ts";
+import { ExtensionError, ExtensionValidationError } from "./errors.ts";
+import { loadExtensionManifest, SKILL_ID_RE } from "./manifest.ts";
 import { runMigrations } from "./migrations.ts";
 
 /** Python `datetime.now(timezone.utc).isoformat()`: `+00:00`, microseconds. */
@@ -49,14 +51,50 @@ function label(target: BindingTarget): string {
   return target.id ? `${target.kind}/${target.id}` : target.kind;
 }
 
-/** Port of `_cmd_bind`. */
+/**
+ * `_cmd_bind` checked nothing it bound: a missing extension, an undeclared
+ * capability, and a persona that does not exist all answered `bound`, and the
+ * person learned of the typo when the context they expected never appeared.
+ * CR149 diverges on purpose: four checks, outside in, before the one insert,
+ * each refusing with one line on stdout at exit 1 -- the shape of the
+ * family's other refusals -- and writing no row.
+ *
+ * The id check comes first and is not cosmetic. `installedExtensionDir` does
+ * not normalize (Python's bytes), so `../x` would pass the existence check
+ * when `<home>/x/skill.yaml` exists, and the context runtime later builds a
+ * path from whatever this row holds.
+ */
 export function runBind(
   db: WritableDatabase,
+  mirrorHome: string,
   extensionId: string,
   capabilityId: string,
   target: BindingTarget,
   deps: BindingDeps,
 ): RenderedCommand {
+  if (!SKILL_ID_RE.test(extensionId)) {
+    return out(`'${extensionId}' is not a valid extension id\n`, 1);
+  }
+  const extensionDir = installedExtensionDir(mirrorHome, extensionId);
+  if (!existsSync(extensionDir)) return extensionNotInstalled(mirrorHome, extensionId);
+  // The validator first, as `install` runs it: its message is already the
+  // user-facing one. Then the context runtime's reader for the ids.
+  try {
+    loadExtensionManifest(extensionDir);
+  } catch (error) {
+    if (!(error instanceof ExtensionValidationError)) throw error;
+    return out(`${error.message}\n`, 1);
+  }
+  const declared = readDeclaredCapabilityIds(extensionDir);
+  if (!declared.includes(capabilityId)) {
+    const list = declared.length === 0 ? "declares none" : `declared: ${declared.join(", ")}`;
+    return out(`extension/${extensionId} declares no capability '${capabilityId}' (${list})\n`, 1);
+  }
+  if (target.kind !== "global" && !targetExists(db, target.kind, target.id ?? "")) {
+    // The fix in the line, as `missing target: pass --persona <id>, ...` does.
+    const shows = target.kind === "persona" ? `${PROGRAM} list personas` : `${PROGRAM} journeys`;
+    return out(`no ${target.kind} '${target.id ?? ""}' (${shows} shows this home's)\n`, 1);
+  }
   db.prepare(
     "INSERT OR IGNORE INTO _ext_bindings " +
       "(extension_id, capability_id, target_kind, target_id, created_at) " +
@@ -65,6 +103,19 @@ export function runBind(
   return out(`bound ${extensionId}/${capabilityId} -> ${label(target)}\n`);
 }
 
+/**
+ * The rows a load is later matched against (`selectExtensionBindings`), and
+ * nothing else: `layer = 'journey'`, not `journey_path`; exact key, so
+ * `Engineer` is not `engineer`. What `bind` accepts is what a load can find.
+ */
+function targetExists(db: Database, layer: "persona" | "journey", key: string): boolean {
+  return (
+    db
+      .prepare("SELECT 1 AS found FROM identity WHERE layer = ? AND key = ? LIMIT 1")
+      .get(layer, key) !== undefined
+  );
+}
+
 /** Port of `_cmd_unbind`. `target_id IS ?` is what makes a global unbind work. */
 export function runUnbind(
   db: WritableDatabase,

package/ts/src/extensions/catalogCommands.ts

@@ -17,8 +17,12 @@
 
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import type { WritableDatabase } from "#db/database.ts";
+import {
+  extensionPluginStates,
+  renderExtensionPluginBlock,
+} from "#runtime/extensionPluginWiring.ts";
 import { PROGRAM } from "#util/program.ts";
 import {
   type BindingDeps,
@@ -59,6 +63,8 @@ import {
   renderSubcommandListing,
 } from "./dispatch.ts";
 import { ExtensionValidationError } from "./errors.ts";
+import { regenerateExtensionPlugin } from "./extensionPlugin.ts";
+import { readExtensionSettings } from "./settings.ts";
 
 export class UnsupportedCatalogCommandError extends Error {}
 
@@ -98,6 +104,15 @@ const EXTENSIONS_VERBS = new Set([
 export interface CatalogContext {
   /** The resolved Mirror home; `--mirror-home` has already been applied. */
   readonly mirrorHome: string;
+  /**
+   * The environment the extensions-plugin readers take their homes and PATH
+   * from (CV21.DS5.US2): HOME, CODEX_HOME, GROK_HOME, PATH. A test passes a
+   * stand-in; the route passes the process's. Absent, the readers see no
+   * runtime and the plugin block is its first line alone.
+   */
+  readonly env?: NodeJS.ProcessEnv;
+  /** Whether a PATH candidate is executable; absent, nothing is. */
+  readonly isExecutable?: (path: string) => boolean;
 }
 
 /** The writable half, for the four `ext` verbs that touch the database. */
@@ -201,6 +216,30 @@ function writeContext(context: CatalogContext, command: string): ExtWriteContext
  * the recorded divergence shape -- the same exit code, one line on stderr --
  * and, like Python, writes nothing to stdout.
  */
+/**
+ * CV21.DS5.US2: after a write that changed the home's `claude` catalog, the
+ * home's extensions plugin is regenerated and the lines a person needs are
+ * appended to the report — the runtimes on the PATH that still need a step, or
+ * one line saying the plugin is wired everywhere. New lines at the end, never
+ * changed ones, so a caller parsing the report sees what it saw before.
+ */
+function withExtensionPluginBlock(
+  context: CatalogContext,
+  rendered: RenderedCommand,
+  removed: readonly string[] = [],
+): RenderedCommand {
+  if (rendered.exitCode !== 0) return rendered;
+  const plugin = regenerateExtensionPlugin(context.mirrorHome);
+  if (plugin === null) return rendered;
+  const states = extensionPluginStates(
+    plugin,
+    context.env ?? {},
+    context.isExecutable ?? (() => false),
+  );
+  const block = renderExtensionPluginBlock(plugin, states, removed);
+  return { ...rendered, stdout: `${rendered.stdout}${block.join("\n")}\n` };
+}
+
 function failLoudly(run: () => RenderedCommand): RenderedCommand {
   try {
     return run();
@@ -229,15 +268,18 @@ export function runExtensionsCommand(
     if (options.extensionsRoot === null) return usage("install requires --extensions-root PATH");
     const write = writeContext(context, "install");
     return failLoudly(() =>
-      renderInstallReport(
-        installExtension({
-          extensionId: options.positional[1] as string,
-          sourceRoot: options.extensionsRoot as string,
-          mirrorHome: write.mirrorHome,
-          runtime: options.runtime,
-          db: write.db,
-          deps: write.deps,
-        }),
+      withExtensionPluginBlock(
+        context,
+        renderInstallReport(
+          installExtension({
+            extensionId: options.positional[1] as string,
+            sourceRoot: options.extensionsRoot as string,
+            mirrorHome: write.mirrorHome,
+            runtime: options.runtime,
+            db: write.db,
+            deps: write.deps,
+          }),
+        ),
       ),
     );
   }
@@ -252,15 +294,19 @@ export function runExtensionsCommand(
     // `install` lets the same class escape as a traceback. Same command, two
     // refusal shapes, measured rather than unified.
     try {
-      return renderUninstallReport(
-        uninstallExtension({
-          extensionId: options.positional[1] as string,
-          mirrorHome: write.mirrorHome,
-          runtime: options.runtime,
-          db: write.db,
-          deps: write.deps,
-        }),
-      );
+      const report = uninstallExtension({
+        extensionId: options.positional[1] as string,
+        mirrorHome: write.mirrorHome,
+        runtime: options.runtime,
+        db: write.db,
+        deps: write.deps,
+      });
+      // What the copying runtimes "still have" after the removal: the claude
+      // command names this uninstall took out of the catalog.
+      const removed = report.removed
+        .filter(([runtimeName]) => runtimeName === "claude")
+        .flatMap(([, paths]) => paths.map((path) => basename(path)));
+      return withExtensionPluginBlock(context, renderUninstallReport(report), removed);
     } catch (error) {
       if (!(error instanceof ExtensionValidationError)) throw error;
       return out(`${error.message}\n`, 1);
@@ -337,7 +383,9 @@ export function runExtensionsCommand(
     `${stdout}Synced ${synced.length} extension(s) to ${options.targetRoot}`,
     ...synced.map((item) => `  ${item.command_name} -> ${item.installed_skill_path}`),
   ];
-  return out(`${lines.join("\n")}\n`);
+  // A verb that regenerates the plugin without installing (plan amendment 6):
+  // from the home's own claude catalog, when the home has one.
+  return withExtensionPluginBlock(context, out(`${lines.join("\n")}\n`));
 }
 
 /**
@@ -404,7 +452,7 @@ export function runExtCommand(
   if ("stdout" in parsed) return parsed;
   const target = { kind: parsed.kind, id: parsed.id };
   return verb === "bind"
-    ? runBind(context.db, extensionId, parsed.capabilityId, target, context.deps)
+    ? runBind(context.db, home, extensionId, parsed.capabilityId, target, context.deps)
     : runUnbind(context.db, extensionId, parsed.capabilityId, target);
 }
 
@@ -444,13 +492,24 @@ function dispatchOrNotInstalled(
   if (!existsSync(extensionRoot)) return extensionNotInstalled(mirrorHome, extensionId);
 
   const entries = readSubcommandListing(extensionRoot);
-  if (HELP_FLAGS.has(subcommand)) return out(renderSubcommandListing(extensionId, entries));
+  // The listing says what the settings file holds (CR145) on both paths that
+  // render it -- a help spelling and an unknown subcommand -- by decision, not
+  // by accident: it is the same listing wherever it appears.
+  if (HELP_FLAGS.has(subcommand)) {
+    return out(
+      renderSubcommandListing(extensionId, entries, readExtensionSettings(mirrorHome, extensionId)),
+    );
+  }
 
   const documented = entries.find((entry) => entry.name === subcommand);
   if (documented === undefined) {
     return out(
       `unknown subcommand '${subcommand}' for extension/${extensionId}\n` +
-        renderSubcommandListing(extensionId, entries),
+        renderSubcommandListing(
+          extensionId,
+          entries,
+          readExtensionSettings(mirrorHome, extensionId),
+        ),
       1,
     );
   }

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",