@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
+ */
+export type ComponentId = string;
+/**
+ * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
+ */
+export type PluginApiReturn<T> = Promise<T> | T;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@snaptrude/plugin-core",
+  "version": "0.0.0-bimsvg-20260928124803",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "ts-morph": "^28.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "build": "tsup --clean",
+    "dev": "tsup --watch",
+    "clean-dist": "rm -rf dist",
+    "test": "node --test test/*.test.mjs",
+    "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",
+    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
+  }
+}

package/scripts/generate-manifest.mjs

@@ -0,0 +1,238 @@
+// 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)` : ""}`,
+    )
+  }
+}

package/scripts/generate-manifest.test.mjs

@@ -0,0 +1,292 @@
+// 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, "string")
+  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",
+    // 2026-07-06 promotions — analysis namespace + program.site geo reads,
+    // react hosts landed:
+    "analysis.sunpath.enable",
+    "analysis.sunpath.disable",
+    "analysis.sunpath.isActive",
+    "analysis.shadows.enable",
+    "analysis.shadows.disable",
+    "analysis.shadows.isEnabled",
+    "analysis.shadows.setDateTime",
+    "analysis.shadows.getDateTime",
+    "analysis.sunlightHours.compute",
+    "analysis.sunlightHours.get",
+    "analysis.sunlightHours.cancel",
+    "analysis.sunlightHours.reset",
+    "analysis.illuminance.compute",
+    "analysis.illuminance.get",
+    "analysis.illuminance.cancel",
+    "analysis.illuminance.reset",
+    "program.site.getLocation",
+    "program.site.getNorthAngle",
+    // 2026-07-07 promotion — analysis.heatmaps, react host landed:
+    "analysis.heatmaps.renderSpaces",
+    "analysis.heatmaps.renderGrid",
+    "analysis.heatmaps.reset",
+    "analysis.heatmaps.isActive",
+    // 2026-07-09 promotion — program.layout became an async-job family (was
+    // author-ahead optional `arrange`/`pack`; now required + getState/cancel):
+    "program.layout.arrange",
+    "program.layout.pack",
+    "program.layout.getState",
+    "program.layout.cancel",
+  ]
+  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}`,
+    )
+  }
+})
+
+test("0.7.0 batch — new families & methods present with intent + prompts", () => {
+  // The 0.7.0 wave: core.proposals, the program.layout async-job family,
+  // door/window catalogs + placement, furniture categories, smart layout,
+  // align, per-face materials, staircase read/write, footprint-area lock,
+  // storey duplicate, SVG import, and view display settings. Every entry is a
+  // required `abstract` member (react hosts landed), so each must be in the
+  // discovery manifest with a summary, >= 3 example prompts, and a result type.
+  const batch = [
+    // core.proposals — design-option infrastructure
+    "core.proposals.list",
+    "core.proposals.get",
+    "core.proposals.getActive",
+    "core.proposals.listForComponent",
+    "core.proposals.isActive",
+    "core.proposals.create",
+    "core.proposals.rename",
+    "core.proposals.setActive",
+    "core.proposals.delete",
+    // program.layout — async space-solver job family
+    "program.layout.arrange",
+    "program.layout.pack",
+    "program.layout.getState",
+    "program.layout.cancel",
+    // door / window catalogs (shared DTOs) + placement creators
+    "design.doors.listCatalogGroups",
+    "design.doors.listCatalog",
+    "design.doors.getCatalogItem",
+    "design.doors.exists",
+    "design.windows.listCatalogGroups",
+    "design.windows.listCatalog",
+    "design.windows.getCatalogItem",
+    "design.windows.exists",
+    "design.create.door",
+    "design.create.window",
+    // furniture categories + smart layout
+    "design.furniture.listCategories",
+    "design.create.smartLayout",
+    // align
+    "design.transform.align",
+    // per-face materials
+    "design.materials.applyToFaces",
+    "design.materials.resetFaces",
+    "design.materials.getByFace",
+    "design.materials.listByFace",
+    // staircase read/write
+    "design.query.getStaircaseParams",
+    "design.update.staircase",
+    // footprint-area lock
+    "design.lockArea",
+    "design.unlockArea",
+    "design.isAreaLocked",
+    "design.listAreaLocked",
+    // storey duplicate
+    "entity.story.duplicate",
+    // present-canvas SVG import + view display settings
+    "presentation.import.svg",
+    "presentation.views.getSettings",
+    "presentation.views.updateSettings",
+  ]
+  for (const p of batch) {
+    const m = byPath.get(p)
+    assert.ok(m, `missing 0.7.0 batch 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`,
+    )
+  }
+})