@modootoday/pmcp 0.5.1 → 0.7.0

package/dist/cli.js

@@ -1,16 +1,29 @@
 #!/usr/bin/env node
+import {
+  loadEmbedder,
+  openEntryVectors
+} from "./chunk-NI2OLZPA.js";
 import {
   ConfigError,
+  ProjectError,
+  TOOLS,
+  doctor,
   findConfig,
-  openDatabase,
-  readConfig
-} from "./chunk-XTLANVRL.js";
+  project,
+  readConfig,
+  readSpec,
+  renderFrontmatter,
+  spawnRunner,
+  splitFrontmatter
+} from "./chunk-GNJSZCRH.js";
+import "./chunk-ZLELYZHL.js";
 import {
   serve
-} from "./chunk-ICHBC5FM.js";
+} from "./chunk-POJOFL4L.js";
 import {
+  kindOf,
   readCatalog
-} from "./chunk-76UKXVUE.js";
+} from "./chunk-QHFORYIN.js";
 
 // src/cli/command.ts
 var ArgumentError = class extends Error {
@@ -189,109 +202,6 @@ var Ui = class {
   }
 };
 
-// src/embed.ts
-var DEFAULT_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
-var ENTRY_SCHEMA = `
-  CREATE TABLE IF NOT EXISTS entry_vector (
-    name TEXT NOT NULL,
-    model_id TEXT NOT NULL,
-    dims INTEGER NOT NULL,
-    description_hash TEXT NOT NULL,
-    vector BLOB NOT NULL,
-    PRIMARY KEY (name, model_id)
-  );
-`;
-var TRANSFORMERS = "@huggingface/transformers";
-async function loadEmbedder(modelId = DEFAULT_MODEL_ID) {
-  let module;
-  try {
-    module = await import(TRANSFORMERS);
-  } catch {
-    return null;
-  }
-  const factory = module.pipeline;
-  if (typeof factory !== "function") return null;
-  const encode = await factory("feature-extraction", modelId);
-  let dims = 0;
-  return {
-    modelId,
-    get dims() {
-      return dims;
-    },
-    async embed(text) {
-      const output = await encode(text, { pooling: "mean", normalize: true });
-      const vector = Float32Array.from(output.data);
-      dims = vector.length;
-      return vector;
-    }
-  };
-}
-function describeHash(description) {
-  let hash = 2166136261;
-  for (let i = 0; i < description.length; i++) {
-    hash ^= description.charCodeAt(i);
-    hash = Math.imul(hash, 16777619) >>> 0;
-  }
-  return hash.toString(16).padStart(8, "0");
-}
-async function openEntryVectors(path) {
-  const opened = await openDatabase(path);
-  if (opened === null) return null;
-  const db = opened.db;
-  db.exec(ENTRY_SCHEMA);
-  return {
-    read(modelId) {
-      const out = /* @__PURE__ */ new Map();
-      const rows = db.prepare(
-        "SELECT name, dims, vector FROM entry_vector WHERE model_id = ?"
-      ).all(modelId);
-      for (const row of rows) {
-        const bytes = row.vector;
-        const vector = new Float32Array(
-          bytes.buffer.slice(
-            bytes.byteOffset,
-            bytes.byteOffset + bytes.byteLength
-          )
-        );
-        if (vector.length === row.dims) out.set(row.name, vector);
-      }
-      return out;
-    },
-    stale(modelId, entries) {
-      const rows = db.prepare(
-        "SELECT name, description_hash FROM entry_vector WHERE model_id = ?"
-      ).all(modelId);
-      const stored = new Map(
-        rows.map((row) => [row.name, row.description_hash])
-      );
-      const out = [];
-      for (const [name, description] of entries) {
-        if (stored.get(name) !== describeHash(description)) out.push(name);
-      }
-      return out;
-    },
-    write(modelId, name, description, vector) {
-      db.prepare(
-        `INSERT INTO entry_vector (name, model_id, dims, description_hash, vector)
-         VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT(name, model_id) DO UPDATE SET
-           dims = excluded.dims,
-           description_hash = excluded.description_hash,
-           vector = excluded.vector`
-      ).run(
-        name,
-        modelId,
-        vector.length,
-        describeHash(description),
-        new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength)
-      );
-    },
-    close() {
-      db.close();
-    }
-  };
-}
-
 // src/commands/roots.ts
 var CATALOG_OPTIONS = [
   {
@@ -445,7 +355,7 @@ var indexCommand = {
         return 0;
       }
       for (const entry2 of todo) {
-        const vector = await embedder.embed(entry2.description);
+        const vector = embedder.embedPassage ? await embedder.embedPassage(entry2.description) : await embedder.embed(entry2.description);
         store.write(embedder.modelId, entry2.name, entry2.description, vector);
       }
       const indexed = store.read(embedder.modelId).size;
@@ -913,8 +823,8 @@ function absent(error) {
 function packageName(name) {
   return /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(name);
 }
-function locate(name, project) {
-  let directory = project;
+function locate(name, project2) {
+  let directory = project2;
   for (; ; ) {
     let source;
     try {
@@ -946,9 +856,9 @@ function locate(name, project) {
   }
 }
 function readInstalledDependencies(projectDirectory) {
-  const project = resolve(projectDirectory);
+  const project2 = resolve(projectDirectory);
   const manifest = JSON.parse(
-    readFileSync2(join2(project, "package.json"), "utf8")
+    readFileSync2(join2(project2, "package.json"), "utf8")
   );
   if (!object(manifest))
     throw new Error("project package.json must contain an object");
@@ -972,7 +882,7 @@ function readInstalledDependencies(projectDirectory) {
   const dependencies = [];
   const issues = [];
   for (const name of [...names].sort()) {
-    const result = locate(name, project);
+    const result = locate(name, project2);
     if ("reason" in result) issues.push(result);
     else dependencies.push(result);
   }
@@ -1034,12 +944,12 @@ function manifestAt(directory) {
   return value;
 }
 function installContext(directory) {
-  const project = resolve2(directory);
-  const manifest = manifestAt(project);
-  let root = project;
-  let ancestor = project;
+  const project2 = resolve2(directory);
+  const manifest = manifestAt(project2);
+  let root = project2;
+  let ancestor = project2;
   for (; ; ) {
-    if (ancestor !== project && existsSync(join3(ancestor, "package.json"))) {
+    if (ancestor !== project2 && existsSync(join3(ancestor, "package.json"))) {
       const candidate = manifestAt(ancestor);
       if (candidate.workspaces !== void 0) {
         root = ancestor;
@@ -1076,7 +986,7 @@ function installContext(directory) {
     throw new Error(
       "declare packageManager or install project dependencies first"
     );
-  if (root !== project && LOCKS.some((file) => existsSync(join3(project, file)))) {
+  if (root !== project2 && LOCKS.some((file) => existsSync(join3(project2, file)))) {
     throw new Error(
       "nested project has its own lockfile; resolve the workspace boundary first"
     );
@@ -1084,12 +994,12 @@ function installContext(directory) {
   const files = [
     .../* @__PURE__ */ new Set([
       join3(root, "package.json"),
-      join3(project, "package.json"),
+      join3(project2, "package.json"),
       ...LOCKS.map((file) => join3(root, file))
     ])
   ];
   return {
-    project,
+    project: project2,
     root,
     manager,
     manifest,
@@ -1584,10 +1494,10 @@ function createPackageManagerRunner(userConfig, baseEnv = process.env, verifiedI
     integrity(packageSpec, plan) {
       const alreadyVerified = verifiedIntegrity?.get(packageSpec);
       if (alreadyVerified) return alreadyVerified;
-      const { manager, project } = plan.context;
+      const { manager, project: project2 } = plan.context;
       const args = manager === "npm" ? ["view", packageSpec, "dist.integrity", "--json"] : ["info", packageSpec, "dist.integrity", "--json"];
       const result = spawnSync(manager, args, {
-        cwd: project,
+        cwd: project2,
         env: environment(userConfig, baseEnv),
         encoding: "utf8",
         shell: false,
@@ -1701,8 +1611,8 @@ function contentDigest(files) {
   }
   return `sha256:${hash.digest("hex")}`;
 }
-function verifyInstalledContent(project, packageName2, expected) {
-  const root = resolve4(project, "node_modules", ...packageName2.split("/"));
+function verifyInstalledContent(project2, packageName2, expected) {
+  const root = resolve4(project2, "node_modules", ...packageName2.split("/"));
   const files = skillFiles(root);
   const actual = contentDigest(files);
   return {
@@ -1888,9 +1798,9 @@ async function manage(context, sync) {
   if (!sync && !context.args.positional.length && !context.args.flags.has("all")) {
     throw new ArgumentError("select a skill package or pass --all");
   }
-  const project = projectFrom(context);
-  const install = installContext(project);
-  const inventory = readInstalledDependencies(project);
+  const project2 = projectFrom(context);
+  const install = installContext(project2);
+  const inventory = readInstalledDependencies(project2);
   const catalog = await remoteCatalog(context);
   const plan = planInstall({
     context: install,
@@ -1907,7 +1817,7 @@ async function manage(context, sync) {
     ])
   );
   const mismatched = (packages) => packages.map(
-    (name) => verifyInstalledContent(project, name, digests.get(name) ?? "")
+    (name) => verifyInstalledContent(project2, name, digests.get(name) ?? "")
   ).filter((check) => !check.matched);
   const reportMismatch = (checks) => {
     for (const check of checks) {
@@ -1919,12 +1829,12 @@ async function manage(context, sync) {
   };
   const report = {
     catalogRevision: plan.catalogRevision,
-    project,
+    project: project2,
     changes: plan.changes,
     command: plan.command
   };
   if (!context.args.flags.has("json")) {
-    context.ui.info("project", project);
+    context.ui.info("project", project2);
     for (const entry2 of plan.changes)
       context.ui.line(`  ${entry2.packageName}@${entry2.version}`);
     if (plan.changes.length)
@@ -2078,6 +1988,267 @@ var syncCommand = {
   run: (context) => manage(context, true)
 };
 
+// src/commands/project.ts
+import { homedir as homedir2 } from "os";
+
+// src/project/edit.ts
+import {
+  cpSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync7,
+  rmSync as rmSync3,
+  statSync as statSync3,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { basename, dirname as dirname3, join as join7 } from "path";
+var CROSS_TOOL = ["name", "description"];
+var tomlValue = (value) => JSON.stringify(value);
+function findEntry(entries, wanted) {
+  const exact = entries.filter((e) => e.name === wanted);
+  if (exact.length === 1 && exact[0]) return exact[0];
+  const bySlug = entries.filter(
+    (e) => e.slug === wanted || e.slug.endsWith(`/${wanted}`)
+  );
+  if (bySlug.length === 1 && bySlug[0]) return bySlug[0];
+  if (bySlug.length > 1) {
+    throw new ProjectError(
+      `${wanted} is ambiguous: ${bySlug.map((e) => e.name).join(", ")}`
+    );
+  }
+  throw new ProjectError(`no catalog skill or agent named ${wanted}`);
+}
+function addEntry(root, entry2) {
+  const kind = kindOf(entry2);
+  if (kind !== "skill" && kind !== "agent") {
+    throw new ProjectError(
+      `${entry2.name} is a ${kind}; only skills and agents are added to .agents/`
+    );
+  }
+  const { meta, body } = splitFrontmatter(readFileSync7(entry2.path, "utf8"));
+  const name = basename(entry2.slug);
+  if (!/^[a-z0-9][a-z0-9-]*$/u.test(name)) {
+    throw new ProjectError(
+      `${entry2.name}: ${name} is not a usable directory name`
+    );
+  }
+  if (kind === "skill") {
+    const dest2 = join7(root, ".agents/skills", name);
+    if (existsSync2(dest2))
+      throw new ProjectError(`.agents/skills/${name} already exists`);
+    const source = entry2.root ?? dirname3(entry2.path);
+    mkdirSync3(dirname3(dest2), { recursive: true });
+    if (statSync3(source).isDirectory()) {
+      cpSync(source, dest2, { recursive: true });
+    } else {
+      mkdirSync3(dest2);
+    }
+    const head = renderFrontmatter({
+      ...meta,
+      name,
+      description: meta["description"] ?? entry2.description
+    });
+    writeFileSync3(
+      join7(dest2, "SKILL.md"),
+      `${head}
+${body.replace(/^\n/u, "")}`
+    );
+    return { kind, name, path: `.agents/skills/${name}` };
+  }
+  const dest = join7(root, ".agents/agents", name);
+  if (existsSync2(dest))
+    throw new ProjectError(`.agents/agents/${name} already exists`);
+  const kept = {};
+  const moved = {};
+  for (const [key, value] of Object.entries({ ...meta, name })) {
+    if (CROSS_TOOL.includes(key)) kept[key] = value;
+    else moved[key] = value;
+  }
+  mkdirSync3(dest, { recursive: true });
+  writeFileSync3(
+    join7(dest, "agent.md"),
+    `${renderFrontmatter(kept)}
+${body.replace(/^\n/u, "")}`
+  );
+  if (Object.keys(moved).length > 0) {
+    const config = join7(root, "pmcp.toml");
+    const lines = [
+      `[agents.${name}.claude]`,
+      ...Object.entries(moved).map(([k, v]) => `${k} = ${tomlValue(v)}`)
+    ];
+    const before = existsSync2(config) ? readFileSync7(config, "utf8") : "";
+    const sep3 = before === "" || before.endsWith("\n\n") ? "" : "\n";
+    writeFileSync3(config, `${before}${sep3}${lines.join("\n")}
+`);
+  }
+  return { kind, name, path: `.agents/agents/${name}/agent.md` };
+}
+function withoutTables(toml, name) {
+  const own = new RegExp(
+    `^\\[(skills\\.${name}|agents\\.${name}(\\.[a-z]+)?)\\]\\s*$`,
+    "u"
+  );
+  const out = [];
+  let skipping = false;
+  for (const line of toml.split("\n")) {
+    if (/^\[/u.test(line)) skipping = own.test(line);
+    if (!skipping) out.push(line);
+  }
+  return out.join("\n").replace(/\n{3,}/gu, "\n\n");
+}
+function removeAsset(root, name) {
+  const removed = [];
+  for (const rel of [`.agents/skills/${name}`, `.agents/agents/${name}`]) {
+    if (!existsSync2(join7(root, rel))) continue;
+    rmSync3(join7(root, rel), { recursive: true, force: true });
+    removed.push(rel);
+  }
+  if (removed.length === 0)
+    throw new ProjectError(`no skill or agent named ${name} in .agents/`);
+  const config = join7(root, "pmcp.toml");
+  if (existsSync2(config)) {
+    const before = readFileSync7(config, "utf8");
+    const after = withoutTables(before, name);
+    if (after !== before) writeFileSync3(config, after);
+  }
+  return removed;
+}
+
+// src/commands/project.ts
+function specFrom(context) {
+  const config = configFrom(context);
+  if (config === null) {
+    throw new ArgumentError(
+      "no pmcp.toml at or above this directory; pass --config <file>"
+    );
+  }
+  try {
+    return readSpec(config);
+  } catch (error) {
+    throw new ArgumentError(
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+function reproject(context, spec) {
+  const result = project(spec, { check: false });
+  for (const problem of result.problems) context.ui.error(problem);
+  if (result.code !== 0) return 1;
+  context.ui.success(
+    `projected ${result.outputs} outputs`,
+    result.pruned > 0 ? `pruned ${result.pruned}` : void 0
+  );
+  return 0;
+}
+var projectCommand = {
+  name: "project",
+  describe: "Write each agent tool's native files from .agents/ and pmcp.toml",
+  usage: "pmcp project [--check] | pmcp project add <skill|agent> | pmcp project remove <name>",
+  options: [
+    ...CATALOG_OPTIONS,
+    {
+      name: "check",
+      describe: "Write nothing; exit 2 when an output drifted, went stale or is undeclared.",
+      boolean: true
+    }
+  ],
+  run(context) {
+    const [verb, name, ...extra] = context.args.positional;
+    if (extra.length > 0)
+      throw new ArgumentError(`unexpected ${extra.join(" ")}`);
+    try {
+      if (verb === void 0) {
+        const spec = specFrom(context);
+        if (!context.args.flags.has("check")) return reproject(context, spec);
+        const result = project(spec, { check: true });
+        for (const problem of result.problems) context.ui.error(problem);
+        if (result.code !== 0) {
+          context.ui.info(
+            "fix",
+            "pmcp project (edit .agents/ or pmcp.toml, never the outputs)"
+          );
+          return 2;
+        }
+        context.ui.success(`${result.outputs} outputs match`);
+        return 0;
+      }
+      if (context.args.flags.has("check"))
+        throw new ArgumentError("--check takes no subcommand");
+      if (name === void 0) throw new ArgumentError(`${verb} needs a name`);
+      if (verb === "add") {
+        const spec = specFrom(context);
+        const added = addEntry(
+          spec.root,
+          findEntry(catalogFrom(context), name)
+        );
+        context.ui.success(`added ${added.kind} ${added.name}`, added.path);
+        return reproject(context, specFrom(context));
+      }
+      if (verb === "remove") {
+        const spec = specFrom(context);
+        for (const path of removeAsset(spec.root, name))
+          context.ui.success("removed", path);
+        return reproject(context, specFrom(context));
+      }
+      throw new ArgumentError(`unknown subcommand ${verb}`);
+    } catch (error) {
+      if (error instanceof ProjectError) {
+        context.ui.error(error.message);
+        return 1;
+      }
+      throw error;
+    }
+  }
+};
+var MARKS = {
+  ok: "ok",
+  fail: "FAIL",
+  skip: "skip"
+};
+var doctorCommand = {
+  name: "doctor",
+  describe: "Ask each agent tool, through its own listing commands, whether it loads this project's assets",
+  usage: "pmcp doctor [--tool <name>] [--json]",
+  options: [
+    {
+      name: "config",
+      describe: "A pmcp.toml to read instead of the nearest one.",
+      placeholder: "<file>"
+    },
+    {
+      name: "tool",
+      describe: `Check only this tool (${TOOLS.join(", ")}). Repeatable.`,
+      repeat: true,
+      placeholder: "<name>"
+    },
+    { name: "json", describe: "Emit JSON rather than a table.", boolean: true }
+  ],
+  run(context) {
+    const only = many(context.args, "tool");
+    for (const tool of only) {
+      if (!TOOLS.includes(tool))
+        throw new ArgumentError(`unknown tool ${tool}`);
+    }
+    const findings = doctor(specFrom(context), {
+      run: spawnRunner,
+      home: context.env["HOME"] ?? homedir2(),
+      ...only.length > 0 ? { only: new Set(only) } : {}
+    });
+    if (context.args.flags.has("json")) {
+      context.ui.data(`${JSON.stringify({ findings }, null, 2)}
+`);
+    } else {
+      context.ui.table(
+        findings.map((f) => [
+          `${MARKS[f.status]}  ${f.tool}`,
+          f.detail ? `${f.check} (${f.detail})` : f.check
+        ])
+      );
+    }
+    return findings.some((f) => f.status === "fail") ? 1 : 0;
+  }
+};
+
 // src/commands/index.ts
 var COMMANDS = [
   serveCommand,
@@ -2089,7 +2260,9 @@ var COMMANDS = [
   availableCommand,
   previewCommand,
   installCommand,
-  syncCommand
+  syncCommand,
+  projectCommand,
+  doctorCommand
 ];
 var PLANNED = [];
 var GLOBAL = /* @__PURE__ */ new Set(["-q", "--quiet", "--no-color", "--color"]);
@@ -2135,7 +2308,7 @@ function dispatch(argv, options = {}) {
   }
   return run(command, rest, { ui, env, cwd });
 }
-var VERSION = "0.5.1";
+var VERSION = "0.7.0";
 async function run(command, argv, context) {
   try {
     return await command.run({

package/dist/http.d.ts

@@ -1,5 +1,40 @@
 import { S as SkillEntry } from './catalog-5v7jrGwP.js';
-import { S as SkillServerOptions } from './server-Dm71qZgM.js';
+import { E as Embedder, S as SkillServerOptions } from './server-wpYiAJ2n.js';
+
+/**
+ * The optional encoder and the store for the vectors it produces.
+ *
+ * Neither the model nor its runtime is a dependency: a caller who wants
+ * semantic ranking installs the peer and runs `pmcp index`, and everything
+ * here degrades to null rather than throwing when that has not happened.
+ */
+
+/**
+ * What `pmcp index` writes and what the server reads back. Multilingual, so a
+ * Korean intent finds an English description (measured 20261005: 8/8 Korean
+ * and 8/8 English intents in the top three over a 99-skill catalog).
+ */
+declare const DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
+interface LoadEmbedderOptions {
+    /** Where model files live; a host bakes them into its image here. */
+    readonly cacheDir?: string;
+    /** Refuse to download, so a missing model is an error rather than a fetch. */
+    readonly localOnly?: boolean;
+    /**
+     * Weight precision. q8 is a quarter of fp32's size (118 MB against 470 MB for
+     * the default model) and ranked the same in the 20261005 measurement.
+     */
+    readonly dtype?: "q8" | "fp32";
+    /** Injected for tests. The optional peer is imported otherwise. */
+    readonly module?: unknown;
+}
+/**
+ * Loads the encoder, or returns null when the peer is not installed.
+ *
+ * Absence is not failure anywhere in this package: the caller reports it and
+ * ranking stays lexical.
+ */
+declare function loadEmbedder(modelId?: string, options?: LoadEmbedderOptions): Promise<Embedder | null>;
 
 /**
  * The catalog over streamable HTTP, for a hosted skills server.
@@ -9,6 +44,15 @@ import { S as SkillServerOptions } from './server-Dm71qZgM.js';
  * tiers tiersFor() grants. The catalog is read once and filtered per request.
  */
 
+/** Semantic ranking for a hosted catalog: the encoder runs in the host process. */
+interface SkillHttpSemanticOptions extends Omit<LoadEmbedderOptions, "module"> {
+    /** Defaults to the multilingual model pmcp index uses. */
+    readonly modelId?: string;
+    /** Injected for tests, or by a host that already holds an encoder. */
+    readonly embedder?: Embedder;
+    /** Told when the encoder cannot load; ranking then stays lexical. */
+    readonly onError?: (error: unknown) => void;
+}
 interface SkillCaller {
     /** Stable id of the signed-in user, recorded by the host, never by pmcp. */
     readonly id: string;
@@ -21,6 +65,8 @@ interface SkillHttpOptions extends SkillServerOptions {
     readonly tiersFor?: (caller: SkillCaller) => readonly string[];
     /** Sent in WWW-Authenticate on a refused request, e.g. a resource metadata URL. */
     readonly challenge?: string;
+    /** Encode the catalog at start so find ranks by meaning across languages. */
+    readonly semantic?: SkillHttpSemanticOptions;
 }
 declare const DEFAULT_TIERS: readonly string[];
 declare function visibleTo(entries: readonly SkillEntry[], tiers: readonly string[]): SkillEntry[];
@@ -28,7 +74,9 @@ interface SkillHttpHandler {
     fetch(request: Request): Promise<Response>;
     /** Re-read the catalog, for a host that deploys new skill releases in place. */
     reload(): void;
+    /** Settles once the catalog is encoded, or at once when ranking is lexical. */
+    ready(): Promise<"semantic" | "lexical">;
 }
 declare function createSkillHttpHandler(options: SkillHttpOptions): SkillHttpHandler;
 
-export { DEFAULT_TIERS, type SkillCaller, type SkillHttpHandler, type SkillHttpOptions, createSkillHttpHandler, visibleTo };
+export { DEFAULT_MODEL_ID, DEFAULT_TIERS, Embedder, type SkillCaller, type SkillHttpHandler, type SkillHttpOptions, type SkillHttpSemanticOptions, createSkillHttpHandler, loadEmbedder, visibleTo };