@modootoday/pmcp 0.1.1 → 0.1.3

package/README.md

@@ -7,7 +7,7 @@ Find and use package skills without loading every document into your agent's con
 ## Install
 
 ```sh
-npm install --save-dev pmcp
+npm install --save-dev @modootoday/pmcp
 ```
 
 Register it with an MCP host:

package/dist/{chunk-DKZ2DN6U.js → chunk-3SOVLFDB.js}

@@ -1,6 +1,6 @@
 import {
   createSkillServer
-} from "./chunk-OPCK6D2H.js";
+} from "./chunk-NTQWFY45.js";
 
 // src/stdio.ts
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
@@ -30,4 +30,4 @@ export {
   serve,
   main
 };
-//# sourceMappingURL=chunk-DKZ2DN6U.js.map
+//# sourceMappingURL=chunk-3SOVLFDB.js.map

package/dist/{chunk-EXPHIDIV.js → chunk-BP45RDLT.js}

@@ -1,6 +1,6 @@
 import {
   normaliseIntent
-} from "./chunk-OPCK6D2H.js";
+} from "./chunk-NTQWFY45.js";
 
 // src/cache.ts
 async function openDatabase(path) {
@@ -131,4 +131,4 @@ export {
   DEFAULT_INTENT_CACHE_LIMIT,
   openIntentCache
 };
-//# sourceMappingURL=chunk-EXPHIDIV.js.map
+//# sourceMappingURL=chunk-BP45RDLT.js.map

package/dist/{chunk-OPCK6D2H.js → chunk-NTQWFY45.js}

@@ -338,7 +338,7 @@ function registerSkillTools(server, tools) {
   return server;
 }
 function createSkillServer(options) {
-  const server = new McpServer({ name: SERVER_NAME, version: "0.1.1" });
+  const server = new McpServer({ name: SERVER_NAME, version: "0.1.3" });
   return registerSkillTools(server, createSkillTools(options));
 }
 
@@ -360,4 +360,4 @@ export {
   registerSkillTools,
   createSkillServer
 };
-//# sourceMappingURL=chunk-OPCK6D2H.js.map
+//# sourceMappingURL=chunk-NTQWFY45.js.map

package/dist/cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   openDatabase
-} from "./chunk-EXPHIDIV.js";
+} from "./chunk-BP45RDLT.js";
 import {
   serve
-} from "./chunk-DKZ2DN6U.js";
+} from "./chunk-3SOVLFDB.js";
 import {
   readCatalog
-} from "./chunk-OPCK6D2H.js";
+} from "./chunk-NTQWFY45.js";
 
 // src/cli/command.ts
 var ArgumentError = class extends Error {
@@ -510,14 +510,14 @@ async function discover(issuer, fetcher2) {
   }
   return body;
 }
-async function startDevice(metadata, request, fetcher2, now = Date.now) {
+async function startDevice(metadata, request2, fetcher2, now = Date.now) {
   const res = await fetcher2(metadata.device_authorization_endpoint, {
     method: "POST",
     headers: FORM_HEADERS,
     body: form({
-      client_id: request.clientId,
-      resource: request.resource,
-      scope: request.scope
+      client_id: request2.clientId,
+      resource: request2.resource,
+      scope: request2.scope
     })
   });
   const body = await res.json();
@@ -544,14 +544,14 @@ async function startDevice(metadata, request, fetcher2, now = Date.now) {
     expiresAt: now() + (Number.isFinite(expires) ? expires : 600) * 1e3
   };
 }
-async function pollOnce(metadata, request, fetcher2, now = Date.now) {
+async function pollOnce(metadata, request2, fetcher2, now = Date.now) {
   const res = await fetcher2(metadata.token_endpoint, {
     method: "POST",
     headers: FORM_HEADERS,
     body: form({
       grant_type: DEVICE_GRANT,
-      device_code: request.deviceCode,
-      client_id: request.clientId
+      device_code: request2.deviceCode,
+      client_id: request2.clientId
     })
   });
   const body = await res.json();
@@ -565,7 +565,7 @@ async function pollOnce(metadata, request, fetcher2, now = Date.now) {
     return {
       kind: "granted",
       session: {
-        issuer: request.issuer,
+        issuer: request2.issuer,
         accessToken: token,
         ...typeof refresh === "string" ? { refreshToken: refresh } : {},
         ...Number.isFinite(expiresIn) ? { expiresAt: now() + expiresIn * 1e3 } : {},
@@ -786,6 +786,28 @@ var whoamiCommand = {
   }
 };
 
+// src/commands/standing.ts
+function sayStanding(context, line) {
+  if (!line) return;
+  if (line.status === "recalled" && line.recall) {
+    context.ui.warn(
+      "recalled",
+      `${line.recall.severity} advisory against the versions this line covers`
+    );
+    context.ui.line(`    ${line.recall.summary}`);
+    context.ui.line(`    ${line.recall.advisoryUrl}`);
+    context.ui.line(
+      line.recall.reverifyAt ? `    the fix is in ${line.recall.reverifyAt}; move there and this skill still applies` : "    no release in this line is unaffected; move to a newer major"
+    );
+    return;
+  }
+  if (line.status === "frozen") {
+    context.ui.line(
+      `    written for ${String(line.major)}.x, which is no longer revised; the date above is where it stopped`
+    );
+  }
+}
+
 // src/installed.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { dirname, join as join2, resolve } from "path";
@@ -1035,8 +1057,17 @@ function planInstall(options) {
     if (installed && semver.gt(installed.version, entry2.delivery.version))
       throw new Error("catalog would downgrade an installed skill package");
     return !installed || installed.version !== entry2.delivery.version;
-  }).map((entry2) => entry2.delivery).sort((a, b) => a.packageName.localeCompare(b.packageName));
-  const specs = changes.map((entry2) => `${entry2.packageName}@${entry2.version}`);
+  }).sort(
+    (a, b) => a.delivery.packageName.localeCompare(b.delivery.packageName)
+  );
+  const recalled = changes.filter((entry2) => entry2.line?.status === "recalled").map((entry2) => ({
+    packageName: entry2.delivery.packageName,
+    line: entry2.line
+  }));
+  const deliveries = changes.map((entry2) => entry2.delivery);
+  const specs = deliveries.map(
+    (entry2) => `${entry2.packageName}@${entry2.version}`
+  );
   let args;
   if (context.manager === "npm") {
     args = [
@@ -1058,7 +1089,8 @@ function planInstall(options) {
   return {
     catalogRevision: catalog.revision,
     context,
-    changes,
+    changes: deliveries,
+    recalled,
     command: {
       executable: context.manager,
       args,
@@ -1071,9 +1103,62 @@ function planInstall(options) {
 import { resolve as resolve3 } from "path";
 
 // src/remote/catalog.ts
-import { readFileSync as readFileSync4, statSync } from "fs";
+import { readFileSync as readFileSync5, statSync } from "fs";
 import semver2 from "semver";
 import { z } from "zod";
+
+// src/remote/catalog-cache.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, renameSync, writeFileSync } from "fs";
+import { join as join4 } from "path";
+var MAX_CACHE_BYTES = 8 * 1024 * 1024;
+function memoryCatalogCache() {
+  const held = /* @__PURE__ */ new Map();
+  return {
+    read: (origin) => held.get(origin) ?? null,
+    write: (origin, entry2) => {
+      held.set(origin, entry2);
+    }
+  };
+}
+function fileCatalogCache(dir) {
+  const path = join4(dir, "catalog-cache.json");
+  return {
+    read(origin) {
+      try {
+        const raw = readFileSync4(path, "utf8");
+        if (raw.length > MAX_CACHE_BYTES) return null;
+        const held = JSON.parse(raw);
+        if (typeof held !== "object" || held === null) return null;
+        const record = held;
+        if (record["origin"] !== origin) return null;
+        const etag = record["etag"];
+        const body = record["body"];
+        if (typeof etag !== "string" || typeof body !== "string") return null;
+        return { etag, body };
+      } catch {
+        return null;
+      }
+    },
+    write(origin, entry2) {
+      try {
+        if (entry2.body.length > MAX_CACHE_BYTES) return;
+        mkdirSync2(dir, { recursive: true });
+        const temporary = `${path}.${String(process.pid)}`;
+        writeFileSync(
+          temporary,
+          `${JSON.stringify({ origin, etag: entry2.etag, body: entry2.body })}
+`,
+          { mode: 384 }
+        );
+        renameSync(temporary, path);
+      } catch {
+        return;
+      }
+    }
+  };
+}
+
+// src/remote/catalog.ts
 var npmName = z.string().max(214).regex(/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u);
 var version = z.string().refine(
   (value) => semver2.valid(value) !== null && semver2.valid(value) === value.split("+")[0]
@@ -1110,6 +1195,20 @@ var entry = z.object({
     headings: z.array(z.string().min(1)),
     example: z.string().min(1)
   }).optional(),
+  // Where this line stands: which major of the target it is written for, and
+  // whether it is the current one, an older one nobody is revising, or one an
+  // advisory has reached. Optional for the same reason as the preview -- a
+  // client that demands it rejects a catalog published before it existed.
+  line: z.object({
+    major: z.number().int().nonnegative(),
+    status: z.enum(["active", "frozen", "recalled"]),
+    recall: z.object({
+      advisoryUrl: z.string().url(),
+      severity: z.enum(["high", "critical"]),
+      summary: z.string().min(1),
+      reverifyAt: version.optional()
+    }).optional()
+  }).optional(),
   targets: z.array(target).min(1)
 });
 var responseSchema = z.object({
@@ -1149,18 +1248,39 @@ function readCatalogFile(path) {
   const stat = statSync(path);
   if (!stat.isFile() || stat.size > MAX_CATALOG_BYTES)
     throw new Error("catalog file exceeds the supported size");
-  const bytes = readFileSync4(path);
+  const bytes = readFileSync5(path);
   if (bytes.byteLength > MAX_CATALOG_BYTES)
     throw new Error("catalog file exceeds the supported size");
   return parseCatalog(JSON.parse(bytes.toString("utf8")));
 }
-async function fetchCatalog(origin, fetcher2 = fetch) {
+async function fetchCatalog(origin, fetcher2 = fetch, cache = memoryCatalogCache()) {
+  const held = cache.read(origin);
+  if (held) {
+    try {
+      return await request(origin, fetcher2, held, cache);
+    } catch (error) {
+      if (!(error instanceof StaleCacheError)) throw error;
+    }
+  }
+  return await request(origin, fetcher2, null, cache);
+}
+var StaleCacheError = class extends Error {
+};
+async function request(origin, fetcher2, held, cache) {
   const response = await fetcher2(catalogEndpoint(origin), {
     method: "GET",
-    headers: { accept: "application/json" },
+    headers: held ? { accept: "application/json", "if-none-match": held.etag } : { accept: "application/json" },
     redirect: "error",
     signal: AbortSignal.timeout(15e3)
   });
+  if (response.status === 304) {
+    if (!held) throw new Error("catalog answered 304 to an unconditional read");
+    try {
+      return parseCatalog(JSON.parse(held.body));
+    } catch {
+      throw new StaleCacheError("the held catalog no longer parses");
+    }
+  }
   if (!response.ok)
     throw new Error(`catalog request failed (${response.status})`);
   if (!response.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
@@ -1189,7 +1309,12 @@ async function fetchCatalog(origin, fetcher2 = fetch) {
     bytes.set(chunk, offset);
     offset += chunk.byteLength;
   }
-  return parseCatalog(JSON.parse(new TextDecoder().decode(bytes)));
+  const text = new TextDecoder().decode(bytes);
+  const catalog = parseCatalog(JSON.parse(text));
+  const tag = response.headers.get("etag");
+  if (tag !== null && tag !== "")
+    cache.write(origin, { etag: tag, body: text });
+  return catalog;
 }
 
 // src/commands/remote-options.ts
@@ -1220,7 +1345,7 @@ async function remoteCatalog(context) {
       throw new Error("choose --catalog or --api, not both");
     return readCatalogFile(resolve3(context.cwd, file));
   }
-  return fetchCatalog(apiOrigin(context));
+  return fetchCatalog(apiOrigin(context), fetch, fileCatalogCache(globalDir()));
 }
 
 // src/commands/available.ts
@@ -1255,6 +1380,7 @@ var availableCommand = {
         if (headings.length > 0) {
           context.ui.line(`    ${headings.join(" \xB7 ")}`);
         }
+        sayStanding(context, match.entry.line);
       }
       context.ui.info(`${matches.length} matching skills`, catalog.revision);
       if (matches.length > 0) {
@@ -1298,6 +1424,9 @@ var previewCommand = {
             summary: entry2.summary,
             package: `${entry2.delivery.packageName}@${entry2.delivery.version}`,
             evidence: entry2.evidence,
+            // A script deciding on our behalf needs the recall as much as a
+            // person does, and more so: it will not read the prose.
+            line: entry2.line,
             targets: entry2.targets,
             preview: entry2.preview
           },
@@ -1320,6 +1449,7 @@ ${entry2.summary}
 
 `
     );
+    sayStanding(context, entry2.line);
     if (!entry2.preview) {
       context.ui.data(
         "This entry was published before previews were recorded, so there is no sample to show.\n"
@@ -1437,8 +1567,8 @@ function applyInstallPlan(plan, runner = packageManagerRunner) {
 
 // src/install/verify-content.ts
 import { createHash as createHash2 } from "crypto";
-import { readdirSync, readFileSync as readFileSync5, statSync as statSync2 } from "fs";
-import { join as join4, relative as relative2, resolve as resolve4, sep as sep2 } from "path";
+import { readdirSync, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
+import { join as join5, relative as relative2, resolve as resolve4, sep as sep2 } from "path";
 var SKILL = "SKILL.md";
 var SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", ".cache"]);
 function skillFiles(root) {
@@ -1452,7 +1582,7 @@ function skillFiles(root) {
     }
     for (const name of entries) {
       if (SKIP.has(name)) continue;
-      const path = join4(dir, name);
+      const path = join5(dir, name);
       let stats;
       try {
         stats = statSync2(path);
@@ -1463,7 +1593,7 @@ function skillFiles(root) {
       else if (name === SKILL)
         found.set(
           relative2(root, path).split(sep2).join("/"),
-          readFileSync5(path, "utf8")
+          readFileSync6(path, "utf8")
         );
     }
   };
@@ -1492,9 +1622,9 @@ function verifyInstalledContent(project, packageName2, expected) {
 }
 
 // src/remote/distribution.ts
-import { chmodSync as chmodSync2, mkdtempSync, rmSync as rmSync2, writeFileSync } from "fs";
+import { chmodSync as chmodSync2, mkdtempSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { tmpdir } from "os";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 function api(origin, path) {
   const base = new URL(catalogEndpoint(origin));
   base.pathname = path;
@@ -1520,23 +1650,43 @@ function credential(value) {
 }
 var REFUSALS = {
   401: "sign in again before installing skills",
-  402: "your subscription does not include skill downloads",
+  402: "a subscription is needed to install these skills",
   403: "sign in again to approve skill downloads"
 };
-async function refusal(response, fallback) {
+function helpUrl(body) {
+  const error = body["error"];
+  if (!error || typeof error !== "object") return void 0;
+  const help = error["help"];
+  if (!help || typeof help !== "object") return void 0;
+  const url = help["subscribeUrl"];
+  if (typeof url !== "string") return void 0;
+  const parsed = URL.parse(url);
+  if (!parsed || parsed.protocol !== "https:") return void 0;
+  return parsed.host === "pmcp.build" ? parsed.href : void 0;
+}
+async function refusal(response, fallback, subjects = []) {
   let requestId;
+  let where;
   try {
     const body = await response.json();
     const value = body && typeof body === "object" && !Array.isArray(body) ? body : {};
     if (typeof value["requestId"] === "string" && value["requestId"] !== "") {
       requestId = value["requestId"];
     }
+    where = helpUrl(value);
   } catch {
   }
   const said = REFUSALS[response.status] ?? `${fallback} (${response.status})`;
-  return new Error(requestId ? `${said} [request ${requestId}]` : said);
+  const named = subjects.length > 0 ? `${said}: ${subjects.join(", ")}` : said;
+  return new Error(
+    [
+      named,
+      where ? `subscribe at ${where}` : "",
+      requestId ? `[request ${requestId}]` : ""
+    ].filter((part) => part !== "").join("\n  ")
+  );
 }
-async function issueDistributionCredential(accessToken, origin = DEFAULT_API_ORIGIN, fetcher2 = fetch) {
+async function issueDistributionCredential(accessToken, origin = DEFAULT_API_ORIGIN, fetcher2 = fetch, subjects = []) {
   const response = await fetcher2(api(origin, "/v1/distribution/credentials"), {
     method: "POST",
     redirect: "error",
@@ -1547,7 +1697,11 @@ async function issueDistributionCredential(accessToken, origin = DEFAULT_API_ORI
     }
   });
   if (!response.ok)
-    throw await refusal(response, "distribution credential request failed");
+    throw await refusal(
+      response,
+      "distribution credential request failed",
+      subjects
+    );
   return credential(await response.json());
 }
 async function verifyRegistryIntegrity(entries, value, fetcher2 = fetch) {
@@ -1610,12 +1764,12 @@ async function revokeDistributionCredential(accessToken, id, origin = DEFAULT_AP
   }
 }
 function temporaryRegistryConfig(value) {
-  const directory = mkdtempSync(join5(tmpdir(), "pmcp-registry-"));
+  const directory = mkdtempSync(join6(tmpdir(), "pmcp-registry-"));
   chmodSync2(directory, 448);
-  const path = join5(directory, ".npmrc");
+  const path = join6(directory, ".npmrc");
   const registry = new URL(value.registry);
   const auth = `//${registry.host}${registry.pathname}:_authToken=${value.token}`;
-  writeFileSync(path, `${value.scope}:registry=${registry.href}
+  writeFileSync2(path, `${value.scope}:registry=${registry.href}
 ${auth}
 `, {
     mode: 384
@@ -1684,6 +1838,16 @@ async function manage(context, sync) {
       context.ui.line(
         `  ${plan.command.executable} ${plan.command.args.join(" ")}`
       );
+    for (const entry2 of plan.recalled) {
+      context.ui.warn(
+        "recalled",
+        `${entry2.packageName} is written for versions a ${entry2.line.recall?.severity ?? "high"} advisory covers`
+      );
+      if (entry2.line.recall) {
+        context.ui.line(`  ${entry2.line.recall.summary}`);
+        context.ui.line(`  ${entry2.line.recall.advisoryUrl}`);
+      }
+    }
   }
   if (!dryRun && plan.changes.length === 0) {
     const drifted = mismatched(
@@ -1737,7 +1901,9 @@ async function manage(context, sync) {
   const origin = apiOrigin(context);
   const credential2 = await issueDistributionCredential(
     session.accessToken,
-    origin
+    origin,
+    fetch,
+    plan.changes.map((entry2) => entry2.packageName)
   );
   const registry = temporaryRegistryConfig(credential2);
   let revoked = false;
@@ -1876,7 +2042,7 @@ function dispatch(argv, options = {}) {
   }
   return run(command, rest, { ui, env, cwd });
 }
-var VERSION = "0.1.1";
+var VERSION = "0.1.3";
 async function run(command, argv, context) {
   try {
     return await command.run({

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_INTENT_CACHE_LIMIT,
   openIntentCache
-} from "./chunk-EXPHIDIV.js";
+} from "./chunk-BP45RDLT.js";
 import {
   DEFAULT_FIND_LIMIT,
   MAX_SKILL_DEPTH,
@@ -19,7 +19,7 @@ import {
   readFrontmatter,
   registerSkillTools,
   withoutBody
-} from "./chunk-OPCK6D2H.js";
+} from "./chunk-NTQWFY45.js";
 export {
   DEFAULT_FIND_LIMIT,
   DEFAULT_INTENT_CACHE_LIMIT,

package/dist/stdio.js

@@ -3,8 +3,8 @@ import {
   main,
   resolveRoots,
   serve
-} from "./chunk-DKZ2DN6U.js";
-import "./chunk-OPCK6D2H.js";
+} from "./chunk-3SOVLFDB.js";
+import "./chunk-NTQWFY45.js";
 export {
   main,
   resolveRoots,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modootoday/pmcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "Elastic-2.0",
   "author": "modootoday",
   "description": "An MCP server that finds the skills your installed packages already ship. Reads SKILL.md out of node_modules by shape rather than by path, so it sees the skills, .agent, .claude, .gemini and .codex conventions alike, and keeps session startup flat as the number of installed skills grows.",
@@ -61,7 +61,8 @@
     "test": "vitest run",
     "clean": "rimraf dist",
     "catalog:refresh": "node scripts/refresh-catalog.mjs",
-    "site:build": "node scripts/build-catalog-pages.mjs",
+    "observations:refresh": "node scripts/refresh-observations.mjs",
+    "site:build": "node scripts/build-catalog-pages.mjs && node scripts/build-observation-pages.mjs && node scripts/build-sitemap.mjs",
     "site:deployed": "node scripts/check-deployed.mjs",
     "prepack": "npm run build && npm run typecheck && npm test",
     "format": "prettier --write .",

package/skills/package-skill-catalog/SKILL.md

@@ -23,7 +23,7 @@ need a server in front of them. This exists for the skills you did not write.
 ## Install and wire
 
 ```sh
-npm install --save-dev pmcp
+npm install --save-dev @modootoday/pmcp
 ```
 
 For a host that spawns MCP servers over stdio: