@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.17",
+  "version": "0.9.18-edgesetbacks-20261021.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/scripts/check-dist-fresh.mjs

@@ -1,22 +1,22 @@
-// `npm test` imports ../dist; refuse to run against a build older than the source.
-// A check, not a rebuild: the host dev checkout symlinks this package, so a
-// rebuild here would blank `dist` under a running editor.
-import { readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-
-const newest = (dir) =>
-  readdirSync(dir, { withFileTypes: true }).reduce((max, entry) => {
-    const path = join(dir, entry.name);
-    return Math.max(max, entry.isDirectory() ? newest(path) : statSync(path).mtimeMs);
-  }, 0);
-
-let built = 0;
-try {
-  built = statSync("dist/index.js").mtimeMs;
-} catch {
-  // no dist at all
-}
-if (newest("src") > built) {
-  console.error("dist is older than src — run `pnpm build` (tsup --clean) first, then test.");
-  process.exit(1);
-}
+// `npm test` imports ../dist; refuse to run against a build older than the source.
+// A check, not a rebuild: the host dev checkout symlinks this package, so a
+// rebuild here would blank `dist` under a running editor.
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const newest = (dir) =>
+  readdirSync(dir, { withFileTypes: true }).reduce((max, entry) => {
+    const path = join(dir, entry.name);
+    return Math.max(max, entry.isDirectory() ? newest(path) : statSync(path).mtimeMs);
+  }, 0);
+
+let built = 0;
+try {
+  built = statSync("dist/index.js").mtimeMs;
+} catch {
+  // no dist at all
+}
+if (newest("src") > built) {
+  console.error("dist is older than src — run `pnpm build` (tsup --clean) first, then test.");
+  process.exit(1);
+}

package/scripts/generate-manifest.mjs

@@ -1,238 +1,243 @@
-// Discovery-manifest generator.
-//
-// The plugin API surface is a tree of abstract `Plugin*Api` classes; the wire
-// method map (`PluginApiMethodMap`) is TYPE-LEVEL ONLY and cannot be enumerated
-// at runtime. This script statically walks the abstract+Zod source with ts-morph
-// and emits a flat, machine-readable manifest of every leaf method:
-//
-//   { path, namespace, summary, examplePrompts[], argsType, resultType }
-//
-// The manifest is the substrate the discovery server (plugin-mcp-server) and the
-// retrieval-accuracy eval harness key on. Authors only ever write the abstract
-// class + Zod schemas + JSDoc + `@examplePrompt` lines — this regenerates the rest.
-//
-// Run: `pnpm --filter @snaptrude/plugin-core generate:manifest`
-//      add `--check` to assert the on-disk manifest is up-to-date (CI gate);
-//      exits non-zero without writing if regeneration would change it.
-import { Project } from "ts-morph"
-import { fileURLToPath } from "node:url"
-import { dirname, resolve } from "node:path"
-import { writeFileSync, readFileSync, existsSync } from "node:fs"
-
-const here = dirname(fileURLToPath(import.meta.url))
-const pkgRoot = resolve(here, "..")
-const apiGlob = resolve(pkgRoot, "src/api/**/*.ts")
-const outFile = resolve(pkgRoot, "api-manifest.json")
-
-const ROOT_CLASS = "PluginApi"
-const RETURN_WRAPPER = "PluginApiReturn"
-
-/** First paragraph of a JSDoc description, whitespace-collapsed. */
-function summaryOf(jsDoc) {
-  if (!jsDoc) return ""
-  const desc = (jsDoc.getDescription() ?? "").trim()
-  const firstPara = desc.split(/\n\s*\n/)[0] ?? ""
-  return firstPara.replace(/\s+/g, " ").trim()
-}
-
-/** All `@examplePrompt` comment strings on a method's JSDoc. */
-function examplePromptsOf(jsDoc) {
-  if (!jsDoc) return []
-  return jsDoc
-    .getTags()
-    .filter((t) => t.getTagName() === "examplePrompt")
-    .map((t) => (t.getCommentText() ?? "").trim())
-    .filter(Boolean)
-}
-
-/**
- * The single `@performance` note on a method's JSDoc, if any.
- *
- * A short throughput hint the discovery layer surfaces so a code generator picks
- * the bulk/array API over a per-item loop (each API call is one host round-trip).
- * Authored on the plural/array methods; absent on everything else (the field is
- * omitted from the manifest entry entirely when there is no tag, to keep the diff
- * — and the LLM's attention — on the methods where it matters).
- */
-function performanceOf(jsDoc) {
-  if (!jsDoc) return ""
-  const tag = jsDoc.getTags().find((t) => t.getTagName() === "performance")
-  return (tag?.getCommentText() ?? "").replace(/\s+/g, " ").trim()
-}
-
-/**
- * The `@deprecated` marker for a method, or "" when the method is not deprecated.
- *
- * When the tag text names a replacement API as a dotted path — conventionally in
- * backticks, e.g. `` `core.handles.release([profile])` `` — we surface just that
- * path (call/array suffix stripped) so the discovery layer can point callers
- * straight at the successor. Otherwise we fall back to the tag's prose, or `true`
- * when the tag carries no comment. Methods with no `@deprecated` tag return "" and
- * get NO key in the manifest (the spread of "" is dropped), keeping the diff lean.
- */
-function deprecatedOf(jsDoc) {
-  if (!jsDoc) return ""
-  const tag = jsDoc.getTags().find((t) => t.getTagName() === "deprecated")
-  if (!tag) return ""
-  const text = (tag.getCommentText() ?? "").replace(/\s+/g, " ").trim()
-  for (const span of text.match(/`[^`]+`/g) ?? []) {
-    const path = span.match(/[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+/)
-    if (path) return path[0]
-  }
-  return text || true
-}
-
-/** Strip the `PluginApiReturn<...>` wrapper to the inner result type text. */
-function unwrapReturn(text) {
-  if (!text) return "void"
-  const m = text.match(new RegExp(`^${RETURN_WRAPPER}<([\\s\\S]*)>$`))
-  return (m ? m[1] : text).trim()
-}
-
-/**
- * Statically walk the abstract `PluginApi` class tree and return one flat,
- * sorted manifest entry per leaf method. Pure (no side effects) so it is unit
- * testable; the CLI below adds the write + report.
- */
-export function buildManifest({ includeOptional = false } = {}) {
-  const project = new Project({ skipAddingFilesFromTsConfig: true })
-  project.addSourceFilesAtPaths(apiGlob)
-
-  // className -> ClassDeclaration, for every abstract Plugin*Api class.
-  const classes = new Map()
-  for (const sf of project.getSourceFiles()) {
-    for (const cls of sf.getClasses()) {
-      const name = cls.getName()
-      if (name && name.startsWith("Plugin") && name.endsWith("Api")) {
-        classes.set(name, cls)
-      }
-    }
-  }
-
-  const leaves = []
-
-  function walk(className, pathPrefix) {
-    const cls = classes.get(className)
-    if (!cls) return
-
-    // Leaf methods on this namespace.
-    for (const method of cls.getMethods()) {
-      const name = method.getName()
-      const jsDoc = method.getJsDocs().at(-1) ?? null
-      const param = method.getParameters()[0]
-      const performance = performanceOf(jsDoc)
-      const deprecated = deprecatedOf(jsDoc)
-      leaves.push({
-        path: `${pathPrefix}${name}`,
-        namespace: pathPrefix.replace(/\.$/, ""),
-        summary: summaryOf(jsDoc),
-        examplePrompts: examplePromptsOf(jsDoc),
-        argsType: param?.getTypeNode()?.getText() ?? null,
-        resultType: unwrapReturn(method.getReturnTypeNode()?.getText()),
-        ...(performance ? { performance } : {}),
-        ...(deprecated ? { deprecated } : {}),
-      })
-    }
-
-    // Sub-namespaces are abstract properties typed as another Plugin*Api class.
-    //
-    // Author-ahead discipline: a member declared optional (`?`) is authored
-    // BEFORE the host implements it — present in the type tree (so plugins and
-    // codegen see the shape) but kept OUT of the discovery manifest until it is
-    // promoted to a required `abstract` member in the wave the host lands it.
-    // The default (discovery) build skips optional members; the authored-surface
-    // build (`includeOptional`, used by the retrieval eval) includes them — both
-    // the optional sub-namespaces and the optional function-property leaves.
-    for (const prop of cls.getProperties()) {
-      const optional = prop.hasQuestionToken()
-      if (optional && !includeOptional) continue
-      const typeNode = prop.getTypeNode()
-      const childType = typeNode?.getText()
-      if (childType && classes.has(childType)) {
-        walk(childType, `${pathPrefix}${prop.getName()}.`)
-      } else if (
-        includeOptional &&
-        typeNode &&
-        typeNode.getKindName() === "FunctionType"
-      ) {
-        // An optional author-ahead leaf, written as a function-property.
-        const jsDoc = prop.getJsDocs().at(-1) ?? null
-        const param = typeNode.getParameters()[0]
-        const performance = performanceOf(jsDoc)
-        const deprecated = deprecatedOf(jsDoc)
-        leaves.push({
-          path: `${pathPrefix}${prop.getName()}`,
-          namespace: pathPrefix.replace(/\.$/, ""),
-          summary: summaryOf(jsDoc),
-          examplePrompts: examplePromptsOf(jsDoc),
-          argsType: param?.getTypeNode()?.getText() ?? null,
-          resultType: unwrapReturn(typeNode.getReturnTypeNode()?.getText()),
-          ...(performance ? { performance } : {}),
-          ...(deprecated ? { deprecated } : {}),
-        })
-      }
-    }
-  }
-
-  walk(ROOT_CLASS, "")
-  leaves.sort((a, b) => a.path.localeCompare(b.path))
-  return leaves
-}
-
-// --- CLI: write + report (skipped when imported, e.g. by tests) ------------
-if (
-  process.argv[1] &&
-  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
-) {
-  // `--all` builds the AUTHORED-surface manifest (includes optional author-ahead
-  // members) to a separate file, for the retrieval eval. Default builds the
-  // discovery manifest (required/host-landed members only).
-  const all = process.argv.includes("--all")
-  const check = process.argv.includes("--check")
-  const target = all ? resolve(pkgRoot, "api-manifest.full.json") : outFile
-  const leaves = buildManifest({ includeOptional: all })
-  const json = JSON.stringify(leaves, null, 2) + "\n"
-
-  if (check) {
-    // Determinism / staleness gate: regenerate and compare, never write.
-    const current = existsSync(target) ? readFileSync(target, "utf8") : ""
-    if (current !== json) {
-      console.error(
-        `${target} is STALE or non-deterministic — run \`generate:manifest${all ? " --all" : ""}\` and commit the result.`,
-      )
-      process.exit(1)
-    }
-    console.log(
-      `manifest up-to-date & deterministic (${leaves.length} methods)`,
-    )
-    process.exit(0)
-  }
-
-  writeFileSync(target, json)
-
-  const missingPrompts = leaves.filter((l) => l.examplePrompts.length === 0)
-  console.log(
-    `manifest${all ? " (authored surface)" : ""}: ${leaves.length} methods -> ${target}`,
-  )
-  console.log(
-    `coverage: ${leaves.length - missingPrompts.length}/${leaves.length} methods have @examplePrompt lines`,
-  )
-  if (missingPrompts.length) {
-    console.log(
-      `  (no @examplePrompt yet: ${missingPrompts.map((l) => l.path).join(", ")})`,
-    )
-  }
-  const slice = [
-    "program.departments.list",
-    "program.departments.get",
-    "program.metrics.get",
-    "presentation.views.list",
-  ]
-  console.log("slice methods present:")
-  for (const p of slice) {
-    const hit = leaves.find((l) => l.path === p)
-    console.log(
-      `  ${hit ? "OK " : "MISS"} ${p}${hit ? ` (${hit.examplePrompts.length} prompts)` : ""}`,
-    )
-  }
-}
+// Discovery-manifest generator.
+//
+// The plugin API surface is a tree of abstract `Plugin*Api` classes; the wire
+// method map (`PluginApiMethodMap`) is TYPE-LEVEL ONLY and cannot be enumerated
+// at runtime. This script statically walks the abstract+Zod source with ts-morph
+// and emits a flat, machine-readable manifest of every leaf method:
+//
+//   { path, namespace, summary, examplePrompts[], argsType, resultType }
+//
+// The manifest is the substrate the discovery server (plugin-mcp-server) and the
+// retrieval-accuracy eval harness key on. Authors only ever write the abstract
+// class + Zod schemas + JSDoc + `@examplePrompt` lines — this regenerates the rest.
+//
+// Run: `pnpm --filter @snaptrude/plugin-core generate:manifest`
+//      add `--check` to assert the on-disk manifest is up-to-date (CI gate);
+//      exits non-zero without writing if regeneration would change it.
+import { Project } from "ts-morph"
+import { fileURLToPath } from "node:url"
+import { dirname, resolve } from "node:path"
+import { writeFileSync, readFileSync, existsSync } from "node:fs"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const pkgRoot = resolve(here, "..")
+const apiGlob = resolve(pkgRoot, "src/api/**/*.ts")
+const outFile = resolve(pkgRoot, "api-manifest.json")
+
+const ROOT_CLASS = "PluginApi"
+const RETURN_WRAPPER = "PluginApiReturn"
+
+/** First paragraph of a JSDoc description, whitespace-collapsed. */
+function summaryOf(jsDoc) {
+  if (!jsDoc) return ""
+  const desc = (jsDoc.getDescription() ?? "").trim()
+  const firstPara = desc.split(/\n\s*\n/)[0] ?? ""
+  return firstPara.replace(/\s+/g, " ").trim()
+}
+
+/** All `@examplePrompt` comment strings on a method's JSDoc. */
+function examplePromptsOf(jsDoc) {
+  if (!jsDoc) return []
+  return jsDoc
+    .getTags()
+    .filter((t) => t.getTagName() === "examplePrompt")
+    .map((t) => (t.getCommentText() ?? "").trim())
+    .filter(Boolean)
+}
+
+/**
+ * The single `@performance` note on a method's JSDoc, if any.
+ *
+ * A short throughput hint the discovery layer surfaces so a code generator picks
+ * the bulk/array API over a per-item loop (each API call is one host round-trip).
+ * Authored on the plural/array methods; absent on everything else (the field is
+ * omitted from the manifest entry entirely when there is no tag, to keep the diff
+ * — and the LLM's attention — on the methods where it matters).
+ */
+function performanceOf(jsDoc) {
+  if (!jsDoc) return ""
+  const tag = jsDoc.getTags().find((t) => t.getTagName() === "performance")
+  return (tag?.getCommentText() ?? "").replace(/\s+/g, " ").trim()
+}
+
+/**
+ * The `@deprecated` marker for a method, or "" when the method is not deprecated.
+ *
+ * When the tag text names a replacement API as a dotted path — conventionally in
+ * backticks, e.g. `` `core.handles.release([profile])` `` — we surface just that
+ * path (call/array suffix stripped) so the discovery layer can point callers
+ * straight at the successor. Otherwise we fall back to the tag's prose, or `true`
+ * when the tag carries no comment. Methods with no `@deprecated` tag return "" and
+ * get NO key in the manifest (the spread of "" is dropped), keeping the diff lean.
+ */
+function deprecatedOf(jsDoc) {
+  if (!jsDoc) return ""
+  const tag = jsDoc.getTags().find((t) => t.getTagName() === "deprecated")
+  if (!tag) return ""
+  const text = (tag.getCommentText() ?? "").replace(/\s+/g, " ").trim()
+  for (const span of text.match(/`[^`]+`/g) ?? []) {
+    const path = span.match(/[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+/)
+    if (path) return path[0]
+  }
+  return text || true
+}
+
+/** Strip the `PluginApiReturn<...>` wrapper to the inner result type text. */
+function unwrapReturn(text) {
+  if (!text) return "void"
+  const m = text.match(new RegExp(`^${RETURN_WRAPPER}<([\\s\\S]*)>$`))
+  return (m ? m[1] : text).trim()
+}
+
+/**
+ * Statically walk the abstract `PluginApi` class tree and return one flat,
+ * sorted manifest entry per leaf method. Pure (no side effects) so it is unit
+ * testable; the CLI below adds the write + report.
+ */
+export function buildManifest({ includeOptional = false } = {}) {
+  const project = new Project({ skipAddingFilesFromTsConfig: true })
+  project.addSourceFilesAtPaths(apiGlob)
+
+  // className -> ClassDeclaration, for every abstract Plugin*Api class.
+  const classes = new Map()
+  for (const sf of project.getSourceFiles()) {
+    for (const cls of sf.getClasses()) {
+      const name = cls.getName()
+      if (name && name.startsWith("Plugin") && name.endsWith("Api")) {
+        classes.set(name, cls)
+      }
+    }
+  }
+
+  const leaves = []
+
+  function walk(className, pathPrefix) {
+    const cls = classes.get(className)
+    if (!cls) return
+
+    // Domain network namespaces inherit their transport methods. Include these
+    // leaves so discovery exposes the same API as the generic worker proxy.
+    const base = cls.getExtends()?.getExpression().getText()
+    if (base && classes.has(base)) walk(base, pathPrefix)
+
+    // Leaf methods on this namespace.
+    for (const method of cls.getMethods()) {
+      const name = method.getName()
+      const jsDoc = method.getJsDocs().at(-1) ?? null
+      const param = method.getParameters()[0]
+      const performance = performanceOf(jsDoc)
+      const deprecated = deprecatedOf(jsDoc)
+      leaves.push({
+        path: `${pathPrefix}${name}`,
+        namespace: pathPrefix.replace(/\.$/, ""),
+        summary: summaryOf(jsDoc),
+        examplePrompts: examplePromptsOf(jsDoc),
+        argsType: param?.getTypeNode()?.getText() ?? null,
+        resultType: unwrapReturn(method.getReturnTypeNode()?.getText()),
+        ...(performance ? { performance } : {}),
+        ...(deprecated ? { deprecated } : {}),
+      })
+    }
+
+    // Sub-namespaces are abstract properties typed as another Plugin*Api class.
+    //
+    // Author-ahead discipline: a member declared optional (`?`) is authored
+    // BEFORE the host implements it — present in the type tree (so plugins and
+    // codegen see the shape) but kept OUT of the discovery manifest until it is
+    // promoted to a required `abstract` member in the wave the host lands it.
+    // The default (discovery) build skips optional members; the authored-surface
+    // build (`includeOptional`, used by the retrieval eval) includes them — both
+    // the optional sub-namespaces and the optional function-property leaves.
+    for (const prop of cls.getProperties()) {
+      const optional = prop.hasQuestionToken()
+      if (optional && !includeOptional) continue
+      const typeNode = prop.getTypeNode()
+      const childType = typeNode?.getText()
+      if (childType && classes.has(childType)) {
+        walk(childType, `${pathPrefix}${prop.getName()}.`)
+      } else if (
+        includeOptional &&
+        typeNode &&
+        typeNode.getKindName() === "FunctionType"
+      ) {
+        // An optional author-ahead leaf, written as a function-property.
+        const jsDoc = prop.getJsDocs().at(-1) ?? null
+        const param = typeNode.getParameters()[0]
+        const performance = performanceOf(jsDoc)
+        const deprecated = deprecatedOf(jsDoc)
+        leaves.push({
+          path: `${pathPrefix}${prop.getName()}`,
+          namespace: pathPrefix.replace(/\.$/, ""),
+          summary: summaryOf(jsDoc),
+          examplePrompts: examplePromptsOf(jsDoc),
+          argsType: param?.getTypeNode()?.getText() ?? null,
+          resultType: unwrapReturn(typeNode.getReturnTypeNode()?.getText()),
+          ...(performance ? { performance } : {}),
+          ...(deprecated ? { deprecated } : {}),
+        })
+      }
+    }
+  }
+
+  walk(ROOT_CLASS, "")
+  leaves.sort((a, b) => a.path.localeCompare(b.path))
+  return leaves
+}
+
+// --- CLI: write + report (skipped when imported, e.g. by tests) ------------
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  // `--all` builds the AUTHORED-surface manifest (includes optional author-ahead
+  // members) to a separate file, for the retrieval eval. Default builds the
+  // discovery manifest (required/host-landed members only).
+  const all = process.argv.includes("--all")
+  const check = process.argv.includes("--check")
+  const target = all ? resolve(pkgRoot, "api-manifest.full.json") : outFile
+  const leaves = buildManifest({ includeOptional: all })
+  const json = JSON.stringify(leaves, null, 2) + "\n"
+
+  if (check) {
+    // Determinism / staleness gate: regenerate and compare, never write.
+    const current = existsSync(target) ? readFileSync(target, "utf8") : ""
+    if (current !== json) {
+      console.error(
+        `${target} is STALE or non-deterministic — run \`generate:manifest${all ? " --all" : ""}\` and commit the result.`,
+      )
+      process.exit(1)
+    }
+    console.log(
+      `manifest up-to-date & deterministic (${leaves.length} methods)`,
+    )
+    process.exit(0)
+  }
+
+  writeFileSync(target, json)
+
+  const missingPrompts = leaves.filter((l) => l.examplePrompts.length === 0)
+  console.log(
+    `manifest${all ? " (authored surface)" : ""}: ${leaves.length} methods -> ${target}`,
+  )
+  console.log(
+    `coverage: ${leaves.length - missingPrompts.length}/${leaves.length} methods have @examplePrompt lines`,
+  )
+  if (missingPrompts.length) {
+    console.log(
+      `  (no @examplePrompt yet: ${missingPrompts.map((l) => l.path).join(", ")})`,
+    )
+  }
+  const slice = [
+    "program.departments.list",
+    "program.departments.get",
+    "program.metrics.get",
+    "presentation.views.list",
+  ]
+  console.log("slice methods present:")
+  for (const p of slice) {
+    const hit = leaves.find((l) => l.path === p)
+    console.log(
+      `  ${hit ? "OK " : "MISS"} ${p}${hit ? ` (${hit.examplePrompts.length} prompts)` : ""}`,
+    )
+  }
+}