@snaptrude/plugin-core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -17,6 +17,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "ts-morph": "^28.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.5.4"
   },
@@ -30,6 +31,9 @@
     "check-types": "tsc --noEmit",
     "build": "tsup --clean",
     "dev": "tsup --watch",
-    "clean-dist": "rm -rf dist"
+    "clean-dist": "rm -rf dist",
+    "generate:manifest": "node scripts/generate-manifest.mjs",
+    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
+    "generate:manifest:all": "node scripts/generate-manifest.mjs --all"
   }
 }

package/scripts/generate-manifest.mjs

@@ -0,0 +1,193 @@
+// 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)
+}
+
+/** 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]
+      leaves.push({
+        path: `${pathPrefix}${name}`,
+        namespace: pathPrefix.replace(/\.$/, ""),
+        summary: summaryOf(jsDoc),
+        examplePrompts: examplePromptsOf(jsDoc),
+        argsType: param?.getTypeNode()?.getText() ?? null,
+        resultType: unwrapReturn(method.getReturnTypeNode()?.getText()),
+      })
+    }
+
+    // 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]
+        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()),
+        })
+      }
+    }
+  }
+
+  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)` : ""}`,
+    )
+  }
+}

package/scripts/generate-manifest.test.mjs

@@ -0,0 +1,193 @@
+// Unit tests for the discovery-manifest generator (pure codegen logic).
+// Run: `node --test scripts/generate-manifest.test.mjs` (from packages/plugin-core)
+import { test } from "node:test"
+import assert from "node:assert/strict"
+import { buildManifest } from "./generate-manifest.mjs"
+
+const manifest = buildManifest()
+const byPath = new Map(manifest.map((m) => [m.path, m]))
+
+test("every entry has a dotted path and a namespace", () => {
+  for (const m of manifest) {
+    assert.match(m.path, /^[a-z][a-zA-Z0-9.]*$/, `bad path: ${m.path}`)
+    assert.equal(typeof m.namespace, "string")
+    assert.ok(
+      Array.isArray(m.examplePrompts),
+      `${m.path} examplePrompts not array`,
+    )
+  }
+})
+
+test("output is sorted and unique by path", () => {
+  const paths = manifest.map((m) => m.path)
+  assert.deepEqual(
+    paths,
+    [...paths].sort((a, b) => a.localeCompare(b)),
+    "not sorted",
+  )
+  assert.equal(new Set(paths).size, paths.length, "duplicate paths")
+})
+
+test("all 4 Phase-1 slice methods are present with intent + prompts", () => {
+  const slice = [
+    "program.departments.list",
+    "program.departments.get",
+    "program.metrics.get",
+    "presentation.views.list",
+  ]
+  for (const p of slice) {
+    const m = byPath.get(p)
+    assert.ok(m, `missing slice method: ${p}`)
+    assert.ok(m.summary.length > 0, `${p} has no intent summary`)
+    assert.ok(m.examplePrompts.length >= 3, `${p} has < 3 example prompts`)
+    assert.ok(
+      m.resultType && m.resultType !== "void",
+      `${p} has no result type`,
+    )
+  }
+})
+
+test("departments.get carries its args type; list takes no args", () => {
+  assert.equal(
+    byPath.get("program.departments.get").argsType,
+    "PluginProgramDepartmentsGetArgs",
+  )
+  assert.equal(byPath.get("program.departments.list").argsType, null)
+})
+
+test("return-type wrapper PluginApiReturn<...> is unwrapped", () => {
+  for (const m of manifest) {
+    assert.ok(
+      !/^PluginApiReturn</.test(m.resultType ?? ""),
+      `${m.path} not unwrapped`,
+    )
+  }
+})
+
+test("author-ahead (optional) members are kept OUT of the manifest", () => {
+  // Optional sub-namespaces (`aiInspiration?`) and optional leaf methods
+  // (`departments.delete?`, `cores.create?`) are authored ahead of the host and
+  // must not appear in the discovery manifest until promoted to required
+  // `abstract` members. (See the discipline note in generate-manifest.mjs.)
+  const authoredAhead = [
+    "presentation.aiInspiration.listModels",
+    "program.departments.delete",
+    "program.cores.create",
+  ]
+  for (const p of authoredAhead) {
+    assert.ok(
+      !byPath.has(p),
+      `optional author-ahead member leaked into manifest: ${p}`,
+    )
+  }
+})
+
+test("promoted methods are present in the manifest", () => {
+  // Methods whose react host bodies have landed and been verified, flipped from
+  // optional author-ahead to required `abstract`.
+  const promoted = [
+    "program.departments.create",
+    "program.departments.setTargetArea",
+    "program.site.get",
+    "program.site.getContext",
+    "presentation.import.image",
+    "presentation.import.pdf",
+    "presentation.sheets.list",
+    "presentation.sheets.place",
+    "presentation.diagrams.place",
+    // 2026-07-02 promotions — react hosts landed and verified:
+    "program.spreadsheet.render",
+    "program.adjacency.getMatrix",
+    "program.adjacency.compute",
+    "program.spreadsheet.getTakeoff",
+    "program.spreadsheet.runScript",
+    "presentation.views.get",
+    "presentation.views.getActive",
+    "presentation.views.capture",
+    "presentation.views.setActive",
+    "presentation.views.create",
+    "core.layers.setActive",
+    "core.layers.update",
+    "program.areas.update",
+  ]
+  for (const p of promoted) {
+    assert.ok(
+      byPath.has(p),
+      `expected promoted method missing from manifest: ${p}`,
+    )
+  }
+})
+
+test("v2 family reads (all 5 families) are present with intent + prompts", () => {
+  // All 22 reads of the five landed families. Every sub-api mount is now required
+  // `abstract` (the react hosts have landed), so each read is in the discovery
+  // manifest with a summary, >= 3 example prompts, and a result type.
+  const reads = [
+    "core.groups.list",
+    "core.groups.get",
+    "core.groups.getForComponent",
+    "core.groups.listMembers",
+    "core.groups.isLocked",
+    "core.groups.getBounds",
+    "core.buildings.list",
+    "core.buildings.get",
+    "core.buildings.listStoreys",
+    "core.buildings.getActive",
+    "core.layers.list",
+    "core.layers.get",
+    "core.layers.getActive",
+    "core.tags.listCategories",
+    "core.tags.getCategory",
+    "core.tags.list",
+    "core.tags.get",
+    "core.tags.getTagsForComponent",
+    "core.tags.listComponents",
+    "program.areas.get",
+    "program.areas.list",
+    "program.areas.listMembers",
+  ]
+  for (const p of reads) {
+    const m = byPath.get(p)
+    assert.ok(m, `missing v2 family read: ${p}`)
+    assert.ok(m.summary.length > 0, `${p} has no intent summary`)
+    assert.ok(m.examplePrompts.length >= 3, `${p} has < 3 example prompts`)
+    assert.ok(
+      m.resultType && m.resultType !== "void",
+      `${p} has no result type`,
+    )
+  }
+})
+
+test("v2 family writes are IN the discovery manifest (hosts landed, promoted)", () => {
+  // 2026-07-02: every v2 family write's react host body has landed, so the
+  // contract members were promoted from optional `foo?: (args) => ...`
+  // fn-properties to required `abstract` methods — they now appear in the
+  // discovery build.
+  const promotedWrites = [
+    "core.groups.create",
+    "core.groups.update",
+    "core.groups.delete",
+    "core.buildings.setActive",
+    "core.buildings.create",
+    "core.buildings.update",
+    "core.buildings.copy",
+    "core.buildings.delete",
+    "core.layers.setActive",
+    "core.layers.update",
+    "core.tags.createCategory",
+    "core.tags.updateCategory",
+    "core.tags.deleteCategory",
+    "core.tags.create",
+    "core.tags.update",
+    "core.tags.delete",
+    "core.tags.assign",
+    "core.tags.unassign",
+    "program.areas.update",
+  ]
+  for (const p of promotedWrites) {
+    assert.ok(
+      byPath.has(p),
+      `promoted v2 family write missing from manifest: ${p}`,
+    )
+  }
+})