mirror-mind 0.0.1 → 0.33.0

package/ts/src/extensions/errors.ts

@@ -0,0 +1,24 @@
+// Extension error hierarchy (CV22.DS7.TS3 plateau 3a). Port of
+// `src/memory/extensions/errors.py`.
+//
+// These messages are not internal: `runtime status` prints an extension's
+// validation or migration failure verbatim as its health note, so the text and
+// the `[extension/<id>]` prefix are a graded parity surface, not free-form
+// diagnostics. `extension_id` is optional because a malformed manifest is
+// discovered before the id is known.
+
+export class ExtensionError extends Error {
+  readonly extensionId: string | null;
+
+  constructor(message: string, extensionId: string | null = null) {
+    super(extensionId ? `[extension/${extensionId}] ${message}` : message);
+    this.extensionId = extensionId;
+    this.name = new.target.name;
+  }
+}
+
+/** Raised when an extension's manifest fails validation. */
+export class ExtensionValidationError extends ExtensionError {}
+
+/** Raised when a SQL migration file is malformed or fails to apply. */
+export class ExtensionMigrationError extends ExtensionError {}

package/ts/src/extensions/manifest.ts

@@ -0,0 +1,356 @@
+// Extension manifest validation (CV22.DS7.TS3 plateau 3a). Port of
+// `load_extension_manifest` and its helpers from `src/memory/cli/extensions.py`.
+//
+// Why this lands in TS3 rather than TS4, where the extension catalog lives:
+// `inspect_extension_health` -- which `runtime status` renders -- calls the
+// validator for two fields (`id`, `kind`) and prints `str(exc)` verbatim as
+// the health note when it raises. Knowing a manifest is valid IS running the
+// validator, so there is no smaller honest port. TS4 extends this module.
+//
+// TWO RECORDED DIVERGENCES, both from the YAML parser and neither from us
+// (Navigator decision, 2026-09-08):
+//
+//   D1. `_load_yaml` renders `invalid YAML in {path}: {exc}` where `{exc}` is
+//       PyYAML's own error text. The `yaml` package cannot reproduce it. The
+//       golden pins the stable prefix byte-for-byte and records both tails.
+//   D2. PyYAML is YAML 1.1; `yaml` is YAML 1.2. An unquoted `no`/`yes`/`on`/
+//       `off`, octal, or sexagesimal scalar resolves differently. The same
+//       family swallows one branch outright: Python's `runtime names must be
+//       strings` is unreachable here, because a JavaScript object key is
+//       always a string. A manifest keying a runtime by `1:` gets Python's
+//       type error and TypeScript's `invalid runtime name: 1`.
+//
+// Every Mirror-authored message below is byte-identical across cores.
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { parse } from "yaml";
+import { pyRepr, pyStr, pyTruthy } from "#util/pythonText.ts";
+import { ExtensionValidationError } from "./errors.ts";
+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]+)*$/;
+const REQUIRED_FIELDS = ["id", "name", "category", "kind", "summary", "runtimes"] as const;
+const PATH_LIKE_SUFFIXES = new Set([".js", ".mjs", ".cjs", ".py"]);
+
+/** One runtime's validated entry, in the shape the catalog renderers print. */
+export interface ExtensionRuntimeEntry {
+  commandName: string;
+  /** The declared relative path, as written in the manifest. */
+  skillFile: string | null;
+  /** The resolved absolute path, present only when `skillFile` is. */
+  skillPath: string | null;
+}
+
+/**
+ * The validated manifest.
+ *
+ * TS3 returned `{id, kind}` -- all `runtime status` reads -- and said TS4
+ * would widen it "when the catalog commands give the remaining fields
+ * somewhere to go". They do now: every field below is printed by `extensions
+ * list`, `ext list`, or `inspect extension`, and none is here for its own
+ * sake.
+ *
+ * `entrypoint` is an ORDERED pair list rather than an object because
+ * `inspect extension` prints it by iterating the mapping, and Python appends
+ * the resolved `module_path` to the dict it parsed -- so insertion order is
+ * observable output, not an implementation detail.
+ */
+export interface ExtensionManifest {
+  id: string;
+  kind: string;
+  name: string;
+  category: string;
+  summary: string;
+  /** Absolute path of the extension directory, as Python's `root`. */
+  root: string;
+  manifestPath: string;
+  runtimes: Record<string, ExtensionRuntimeEntry>;
+  entrypoint: ReadonlyArray<readonly [string, string]>;
+}
+
+function isMapping(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Port of `_load_yaml`. See D1 for the malformed-YAML branch. */
+function loadYaml(manifestPath: string): Record<string, unknown> {
+  let text: string;
+  try {
+    text = readFileSync(manifestPath, "utf8");
+  } catch {
+    throw new ExtensionValidationError(`missing manifest: ${manifestPath}`);
+  }
+  let data: unknown;
+  try {
+    data = parse(text);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new ExtensionValidationError(`invalid YAML in ${manifestPath}: ${detail}`);
+  }
+  if (!isMapping(data)) {
+    throw new ExtensionValidationError(`manifest must be a mapping: ${manifestPath}`);
+  }
+  return data;
+}
+
+/** Port of `_validate_runtime_name`. */
+function validateRuntimeName(name: string): void {
+  if (!RUNTIME_NAME_RE.test(name)) {
+    throw new ExtensionValidationError(`invalid runtime name: ${name}`);
+  }
+}
+
+/** Port of `_validate_command_name`: the per-runtime command namespaces. */
+function validateCommandName(runtime: string, commandName: string): void {
+  if (runtime === "claude" && !commandName.startsWith("ext:")) {
+    throw new ExtensionValidationError(`runtime '${runtime}' command_name must start with 'ext:'`);
+  }
+  if (runtime === "pi" && !commandName.startsWith("ext-")) {
+    throw new ExtensionValidationError(`runtime '${runtime}' command_name must start with 'ext-'`);
+  }
+}
+
+/** Python `Path(p).suffix.lower()`. */
+function suffixOf(argument: string): string {
+  const base = argument.split(/[\\/]/).pop() ?? "";
+  const dot = base.lastIndexOf(".");
+  return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+
+/** Python `candidate.is_relative_to(root)`. */
+function isRelativeTo(candidate: string, root: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/** Port of `_validate_context_providers`. */
+function validateContextProviders(
+  data: Record<string, unknown>,
+  extensionDir: string,
+  manifestPath: string,
+): void {
+  const providers = data.mirror_context_providers;
+  if (providers === null || providers === undefined) return;
+  if (!Array.isArray(providers)) {
+    throw new ExtensionValidationError(
+      `mirror_context_providers must be a list in ${manifestPath}`,
+    );
+  }
+  const seen = new Set<string>();
+  const root = resolve(extensionDir);
+  for (const provider of providers) {
+    if (!isMapping(provider)) {
+      throw new ExtensionValidationError(
+        `mirror_context_providers entries must be objects in ${manifestPath}`,
+      );
+    }
+    const capabilityId = provider.id;
+    if (typeof capabilityId !== "string" || !RUNTIME_NAME_RE.test(capabilityId)) {
+      throw new ExtensionValidationError(
+        `invalid mirror context capability id ${pyRepr(capabilityId)} in ${manifestPath}`,
+      );
+    }
+    if (seen.has(capabilityId)) {
+      throw new ExtensionValidationError(
+        `duplicate mirror context capability id ${pyRepr(capabilityId)} in ${manifestPath}`,
+      );
+    }
+    seen.add(capabilityId);
+    const runtime = provider.provider_runtime;
+    if (runtime === null || runtime === undefined) continue;
+    if (!isMapping(runtime) || runtime.protocol !== "mirror-context-v1") {
+      throw new ExtensionValidationError(
+        `provider_runtime for ${pyRepr(capabilityId)} must use mirror-context-v1 ` +
+          `in ${manifestPath}`,
+      );
+    }
+    const command = runtime.command;
+    if (
+      !Array.isArray(command) ||
+      command.length === 0 ||
+      command.some((part) => typeof part !== "string" || part.length === 0)
+    ) {
+      throw new ExtensionValidationError(
+        `provider_runtime.command for ${pyRepr(capabilityId)} must be a non-empty argv list ` +
+          `in ${manifestPath}`,
+      );
+    }
+    for (const [index, argument] of (command as string[]).entries()) {
+      const pathLike =
+        isAbsolute(argument) ||
+        argument.includes("/") ||
+        argument.includes("\\") ||
+        (index > 0 && PATH_LIKE_SUFFIXES.has(suffixOf(argument)));
+      if (!pathLike) continue;
+      const candidate = resolve(root, argument);
+      if (isAbsolute(argument) || !isRelativeTo(candidate, root)) {
+        throw new ExtensionValidationError(
+          `provider_runtime.command path escapes extension root in ${manifestPath}`,
+        );
+      }
+      if (!existsSync(candidate)) {
+        throw new ExtensionValidationError(`provider_runtime.command path not found: ${candidate}`);
+      }
+    }
+  }
+}
+
+/**
+ * Validate an entrypoint the extension DECLARED, as the oracle did, and return
+ * the module path it resolves to. The `.py` suffix is the declared contract of
+ * an entrypoint -- an extension may be Python -- not a demand on extensions
+ * that declare none.
+ */
+function declaredModulePath(
+  entrypoint: unknown,
+  extensionDir: string,
+  manifestPath: string,
+): string {
+  if (!isMapping(entrypoint) || !pyTruthy(entrypoint.module)) {
+    throw new ExtensionValidationError(
+      "a declared entrypoint requires entrypoint.module (a Python module " +
+        `name under the extension directory) in ${manifestPath}`,
+    );
+  }
+  const moduleName = entrypoint.module;
+  if (typeof moduleName !== "string" || moduleName.length === 0) {
+    throw new ExtensionValidationError(
+      `entrypoint.module must be a non-empty string in ${manifestPath}`,
+    );
+  }
+  const modulePath = join(extensionDir, `${moduleName}.py`);
+  if (!existsSync(modulePath)) {
+    throw new ExtensionValidationError(
+      `entrypoint.module '${moduleName}' not found at ${modulePath}`,
+    );
+  }
+  return modulePath;
+}
+
+/**
+ * Port of `load_extension_manifest`. Check order is load-bearing: the oracle
+ * reports the FIRST failure, so reordering would change the health note text
+ * for a manifest that breaks two rules at once.
+ */
+export function loadExtensionManifest(extensionDir: string): ExtensionManifest {
+  // `join`, not `resolve`: the oracle builds these display paths with
+  // `extension_dir / name`, which does not normalize `..`, and the path is
+  // interpolated into error messages the health note prints verbatim.
+  const manifestPath = join(extensionDir, "skill.yaml");
+  const data = loadYaml(manifestPath);
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!pyTruthy(data[field])) {
+      throw new ExtensionValidationError(`missing required field '${field}' in ${manifestPath}`);
+    }
+  }
+
+  const skillId = data.id;
+  if (typeof skillId !== "string" || !SKILL_ID_RE.test(skillId)) {
+    throw new ExtensionValidationError(`invalid skill id '${pyStr(skillId)}' in ${manifestPath}`);
+  }
+
+  if (data.category !== "extension") {
+    throw new ExtensionValidationError(
+      `unsupported category '${pyStr(data.category)}' in ${manifestPath}`,
+    );
+  }
+
+  const kind = data.kind;
+  if (typeof kind !== "string" || !ALLOWED_KINDS.has(kind)) {
+    throw new ExtensionValidationError(`unsupported kind '${pyStr(kind)}' in ${manifestPath}`);
+  }
+
+  const runtimes = data.runtimes;
+  if (!isMapping(runtimes) || Object.keys(runtimes).length === 0) {
+    throw new ExtensionValidationError(`runtimes must be a non-empty mapping in ${manifestPath}`);
+  }
+
+  // Python mutates the parsed `entrypoint` dict, appending `module_path` after
+  // the keys the author wrote; `inspect extension` prints that order.
+  const entrypointPairs: [string, string][] = isMapping(data.entrypoint)
+    ? Object.entries(data.entrypoint).map(([key, value]) => [key, pyStr(value)])
+    : [];
+  const entrypoint: ReadonlyArray<readonly [string, string]> = entrypointPairs;
+  const validatedRuntimes: Record<string, ExtensionRuntimeEntry> = {};
+
+  if (kind === "command-skill") {
+    // Optional since CV22.DS10.TS5 (D10). The core has imported no entrypoint
+    // since CV22.DS10.TS2 -- every capability declares its own runtime -- so
+    // the rule demanded a Python file from every command-skill and read
+    // nothing from it. An entrypoint an extension DOES declare is validated
+    // exactly as before, so every installed extension validates as it did.
+    if (data.entrypoint !== undefined && data.entrypoint !== null) {
+      entrypointPairs.push([
+        "module_path",
+        declaredModulePath(data.entrypoint, extensionDir, manifestPath),
+      ]);
+    }
+
+    const expectedPrefix = tablePrefixFor(skillId);
+    const declaredPrefix = data.table_prefix;
+    if (declaredPrefix !== null && declaredPrefix !== undefined) {
+      if (declaredPrefix !== expectedPrefix) {
+        throw new ExtensionValidationError(
+          `table_prefix '${pyStr(declaredPrefix)}' does not match the ` +
+            `required prefix '${expectedPrefix}' for id '${skillId}' ` +
+            `in ${manifestPath}`,
+        );
+      }
+    }
+  }
+
+  for (const [runtimeName, runtimeData] of Object.entries(runtimes)) {
+    validateRuntimeName(runtimeName);
+    if (!isMapping(runtimeData)) {
+      throw new ExtensionValidationError(
+        `runtime '${runtimeName}' must map to an object in ${manifestPath}`,
+      );
+    }
+    const commandName = runtimeData.command_name;
+    if (typeof commandName !== "string" || commandName.length === 0) {
+      throw new ExtensionValidationError(
+        `runtime '${runtimeName}' missing command_name in ${manifestPath}`,
+      );
+    }
+    validateCommandName(runtimeName, commandName);
+
+    const skillFile = runtimeData.skill_file;
+    if (kind === "prompt-skill" && (typeof skillFile !== "string" || skillFile.length === 0)) {
+      throw new ExtensionValidationError(
+        `prompt-skill runtime '${runtimeName}' missing skill_file in ${manifestPath}`,
+      );
+    }
+    let skillPath: string | null = null;
+    if (typeof skillFile === "string" && skillFile.length > 0) {
+      skillPath = join(extensionDir, skillFile);
+      if (!existsSync(skillPath)) {
+        throw new ExtensionValidationError(
+          `runtime '${runtimeName}' skill_file not found: ${skillPath}`,
+        );
+      }
+    }
+    validatedRuntimes[runtimeName] = {
+      commandName,
+      skillFile: typeof skillFile === "string" && skillFile.length > 0 ? skillFile : null,
+      skillPath,
+    };
+  }
+
+  validateContextProviders(data, extensionDir, manifestPath);
+
+  return {
+    id: skillId,
+    kind,
+    name: pyStr(data.name),
+    category: pyStr(data.category),
+    summary: pyStr(data.summary),
+    root: extensionDir,
+    manifestPath,
+    runtimes: validatedRuntimes,
+    entrypoint,
+  };
+}