@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/version/version.verb.ts

@@ -0,0 +1,39 @@
+/**
+ * `pragma version` — the command form of `--version`.
+ *
+ * Users type it reflexively, so it exists and prints exactly the bytes the
+ * flag prints: the bare semver on stdout, storeless, no store or network
+ * touched. Withheld from MCP — the version already rides `info` and the
+ * server handshake's `serverInfo`.
+ */
+
+import { BIN_NAME, VERSION } from "../../constants.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
+
+const versionVerb: VerbSpec<Record<string, unknown>, string> = {
+  path: ["version"],
+  summary: "Print the CLI version.",
+  doc: "Prints the version `--version` prints — one value, two spellings of the same read.",
+  params: [],
+  output: {
+    formatters: {
+      plain: (version) => version,
+      llm: (version) => version,
+      json: (version) => JSON.stringify({ version }),
+    },
+  },
+  examples: [{ cmd: `${BIN_NAME} version` }],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: false,
+      reason: "the version rides `info` and the MCP handshake's serverInfo",
+    },
+  },
+  run: async () => VERSION,
+};
+
+/** The `version` verb. */
+export const versionVerbSpec = asVerb(versionVerb);

package/src/constants.test.ts

@@ -3,6 +3,7 @@ import {
   BIN_NAME,
   DEFAULT_DETAIL_LEVEL,
   DETAIL_LEVELS,
+  ISSUES_URL,
   MCP_SERVER_NAME,
   OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
@@ -11,23 +12,24 @@ import {
 } from "./constants.js";
 
 describe("constants", () => {
-  it("names the v2 bin and the MCP server pragma", () => {
+  it("projects the shipped distribution's identity", () => {
+    // Every value here is read from `pragma.conf.ts`, so this pins what THIS
+    // distribution ships. That the projection is real — a fork changing the
+    // config changes the CLI — is proven by `src/identity.test.ts`.
     expect(BIN_NAME).toBe("pragma");
     expect(MCP_SERVER_NAME).toBe("pragma");
+    expect(PROGRAM_DESCRIPTION).toBe("Explore the design system");
+    expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
+    expect(ISSUES_URL).toBe("https://github.com/canonical/pragma/issues");
   });
 
   it("reads a semver version from package.json", () => {
     expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
   });
 
-  it("keeps the recovery prefix on the stable command name (D5)", () => {
-    expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
-  });
-
   it("exposes the stable output formats and detail levels", () => {
     expect(OUTPUT_FORMATS).toEqual(["plain", "llm", "json"]);
     expect(DETAIL_LEVELS).toEqual(["summary", "standard", "detailed"]);
     expect(DETAIL_LEVELS).toContain(DEFAULT_DETAIL_LEVEL);
-    expect(PROGRAM_DESCRIPTION.length).toBeGreaterThan(0);
   });
 });

package/src/constants.ts

@@ -1,59 +1,115 @@
 /**
- * Package-level constants for the pragma v2 kernel.
+ * Package-level constants — the distribution's identity, projected.
  *
- * Program metadata (bin name, MCP server name, description, version) plus the
- * stable cross-cutting enums (output formats, detail levels). The CLI binary
- * and the MCP server share the single `pragma` identity, so existing agent
- * wiring keeps resolving the server unchanged.
+ * The bin name, MCP server name, description and issues URL are NOT authored
+ * here: they are read from the distribution config (`pragma.conf.ts`), so a fork
+ * changes values, not code. The import is static because the surfaces that need
+ * identity — `--help`, `__complete`, first-run onboarding, the MCP handshake —
+ * all run before or without the config layer. That is safe precisely because
+ * `pragma.conf.ts` is inert data: a plain object literal whose only import is a
+ * type. It reaches no zod schema, no fs, no evaluator. `capabilities/lazy.test.ts`
+ * pins that boundary, and `src/identity.test.ts` proves the projection.
+ *
+ * Also holds the stable cross-cutting enums: output formats here, and the
+ * detail levels re-exported from `kernel/config/types.ts`, where the config
+ * validator closes the `detail` field over them.
  */
 
 import pkg from "../package.json" with { type: "json" };
+import identity from "../pragma.conf.js";
+import type { RawConfig } from "./kernel/config/types.js";
+import { DETAIL_LEVELS, type DetailLevel } from "./kernel/config/types.js";
 
-/** CLI binary name for the v2 kernel (installed as `pragma`). */
-const BIN_NAME = "pragma";
+/** CLI binary name — the distribution's `name`. */
+const BIN_NAME = identity.name;
 
 /**
- * MCP server identity — `pragma`, matching the CLI bin, so agents already
- * pointed at the pragma server resolve it unchanged.
+ * MCP server identity — the same name as the CLI bin, so agents already pointed
+ * at the server resolve it unchanged. Also the `serverInfo.name` the server
+ * introduces itself with on the wire (paired with {@link VERSION} by
+ * `buildServer`), so a peer reads the distribution's declared name, never a
+ * hardcoded one.
  */
-const MCP_SERVER_NAME = "pragma";
+const MCP_SERVER_NAME = identity.name;
 
 /** One-line program description for help and server metadata. */
-const PROGRAM_DESCRIPTION = "CLI and MCP server for Canonical's design system.";
+const PROGRAM_DESCRIPTION = identity.help;
+
+/** Where the distribution asks users to file issues and feedback. */
+const ISSUES_URL = identity.issuesUrl;
 
 /** Semver version string read from package.json. */
 const VERSION: string = pkg.version;
 
 /**
- * Literal prefix for every `recovery.cli` hint (`pragma `): recovery strings
- * quote the stable, documented command name — matching the bin (D5). The
- * recovery invariant test enforces this.
+ * The project config filename the walker looks for and every surface that
+ * quotes it — diagnostics, the onboarding note, the generated reference, the
+ * surface covenant — names. It lives HERE rather than beside the walker so the
+ * quoting surfaces do not have to import `kernel/config/**`: the storeless
+ * `--help`/`__complete` graph is asserted to reach no config module, and
+ * `completion/safety.test.ts` fails the moment one arrives.
+ */
+const PROJECT_CONFIG_FILENAME = `${identity.name}.config.ts`;
+
+/**
+ * The distribution's name plus a space: the prefix a `recovery.cli` hint carries
+ * so it quotes a command the installed binary answers to (D5). Kernel hints are
+ * authored through `cliRecovery`, which prepends it; `packs/schema.ts` REJECTS
+ * it in a user-authored pack's `emptyRecovery.cli`, because the CONSUMING
+ * distribution's renderer supplies its own. Use {@link BIN_NAME} for prose —
+ * this constant's trailing space belongs to the recovery invariant, not to
+ * sentences.
  */
-const RECOVERY_CLI_PREFIX = "pragma ";
+const RECOVERY_CLI_PREFIX = `${identity.name} `;
 
 /** The output formats the renderer selects between (`llm` = condensed Markdown). */
 const OUTPUT_FORMATS = ["plain", "llm", "json"] as const;
 
-/** A selected output format. `--format text` is normalised to `plain`. */
+/**
+ * A selected output format. The set is CLOSED — no alias normalises into it,
+ * so a `--format` value outside {@link OUTPUT_FORMATS} is rejected at the
+ * entry point rather than quietly becoming `plain`.
+ */
 type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 
-/** Progressive-disclosure levels, least to most detail. */
-const DETAIL_LEVELS = ["summary", "standard", "detailed"] as const;
-
-/** A progressive-disclosure level. */
-type DetailLevel = (typeof DETAIL_LEVELS)[number];
-
 /** Default detail level when neither flag, config, nor spec pins one. */
 const DEFAULT_DETAIL_LEVEL: DetailLevel = "standard";
 
+/**
+ * The wordmark `--help` opens with, as raw ASCII-art lines.
+ *
+ * PROJECTED from the distribution config, exactly like {@link BIN_NAME} and
+ * {@link PROGRAM_DESCRIPTION} — a wordmark spells a name, so it is identity, and
+ * `kernel/copy.test.ts` forbids any kernel string from naming the distribution.
+ * Authoring the art here would have branded a fork's front door with someone
+ * else's logo; declaring it as data means a fork ships its own or none.
+ *
+ * Lines rather than one string because the art contains a backtick and
+ * backslashes: a template literal would need every one of them escaped, which is
+ * how a character gets lost the next time someone edits it.
+ */
+// Read through the DECLARED type, not the literal's inferred one. The
+// distribution config is `satisfies RawConfig`, which narrows to exactly the
+// keys that file writes — so `identity.logo` does not typecheck in a fork that
+// omits the field, which is precisely the fork this feature promises a bare
+// header. The assignment (not a cast) is what `satisfies` already guarantees,
+// and it makes every OPTIONAL field readable here. The other constants keep
+// reading `identity` directly, so their literal types are untouched.
+const declared: RawConfig = identity;
+
+const PROGRAM_LOGO: readonly string[] = declared.logo ?? [];
+
 export type { DetailLevel, OutputFormat };
 export {
   BIN_NAME,
   DEFAULT_DETAIL_LEVEL,
   DETAIL_LEVELS,
+  ISSUES_URL,
   MCP_SERVER_NAME,
   OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
+  PROGRAM_LOGO,
+  PROJECT_CONFIG_FILENAME,
   RECOVERY_CLI_PREFIX,
   VERSION,
 };

package/src/identity.test.ts

@@ -0,0 +1,348 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import chalk from "chalk";
+import { afterAll, afterEach, describe, expect, it, vi } from "vitest";
+import type { VerbSpec } from "./kernel/spec/types.js";
+
+// A fork's distribution config. Everything the kernel says about itself must
+// follow from THIS object — that is the whole claim under test.
+vi.mock("../pragma.conf.js", () => ({
+  default: {
+    name: "recipes",
+    help: "Explore the recipe graph",
+    colophon: {
+      markdown: "Made by the kitchen, one dish at a time.",
+      summary: "Kitchen-made.",
+    },
+    issuesUrl: "https://example.invalid/recipes/issues",
+    packs: [],
+    prefixes: { rcp: "https://example.invalid/recipes/" },
+    channel: "normal",
+    detail: "standard",
+  },
+  // The fork's domain vocabulary, declared beside its identity. Every read of
+  // a domain term must follow from THIS object, which the last case below
+  // asserts by capturing the SPARQL the readers actually emit.
+  vocabulary: {
+    altName: "rcp:name",
+    prompt: {
+      type: "rcp:Prompt",
+      body: "rcp:promptBody",
+      argument: "rcp:promptArgument",
+      argName: "rcp:argName",
+      argRequired: "rcp:argRequired",
+    },
+  },
+}));
+
+/** Anything that would betray THIS distribution leaking through the kernel. */
+const THIS_DISTRIBUTION = /pragma|canonical|design[- ]system/i;
+
+/**
+ * THIS distribution's name alone. The generated reference legitimately carries
+ * bundled-pack CONTENT a fork owns and edits — `@canonical/…` package names in
+ * `create` examples, `ds:`/`cs:` entity values — so the reference probe below
+ * is scoped to the one token that must never survive a rename.
+ */
+const THIS_NAME = /\bpragma\b/i;
+
+// chalk paints ANSI when GITHUB_ACTIONS is set even off a TTY, which would
+// break the plain-text structure assertions below.
+const prevChalkLevel = chalk.level;
+chalk.level = 0;
+afterAll(() => {
+  chalk.level = prevChalkLevel;
+});
+
+const originalConfigHome = process.env.XDG_CONFIG_HOME;
+const originalDataHome = process.env.XDG_DATA_HOME;
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = originalConfigHome;
+  process.env.XDG_DATA_HOME = originalDataHome;
+});
+
+/** A pack-contributed noun the kernel has never heard of. */
+const dishList: VerbSpec = {
+  path: ["dish", "list"],
+  summary: "List every dish in the graph.",
+  params: [],
+  output: {
+    formatters: {
+      plain: (d) => String(d),
+      llm: (d) => String(d),
+      json: (d) => JSON.stringify(d),
+    },
+  },
+  capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+describe("identity projection — a fork changes values, not code (PROTECTED)", () => {
+  it("names the bin, the MCP server, and the recovery prefix from the distribution", async () => {
+    const c = await import("./constants.js");
+    expect(c.BIN_NAME).toBe("recipes");
+    expect(c.MCP_SERVER_NAME).toBe("recipes");
+    expect(c.RECOVERY_CLI_PREFIX).toBe("recipes ");
+    expect(c.PROGRAM_DESCRIPTION).toBe("Explore the recipe graph");
+    expect(c.ISSUES_URL).toBe("https://example.invalid/recipes/issues");
+  });
+
+  it("installs its completion script under the fork's name, in all three shells", async () => {
+    // The basename is load-bearing, not cosmetic — `shell.ts` records what each
+    // shell measurably does with it (fish and bash-completion autoload BY the
+    // command's name; zsh binds by the `#compdef` tag but autoloads a function
+    // named after the file). A mismatch installs a file the shell never loads
+    // while `setup completions` prints success, `doctor` passes, and TAB does
+    // nothing. It can only be pinned from a fork: with the distribution named
+    // `pragma` a hardcoded literal and `BIN_NAME` agree by construction, so a
+    // test in `setup.test.ts` cannot fail. Here they cannot agree by accident.
+    const { completionScriptPath } = await import(
+      "./capabilities/setup/shell.js"
+    );
+    expect(basename(completionScriptPath("zsh"))).toBe("_recipes");
+    expect(basename(completionScriptPath("bash"))).toBe("recipes");
+    expect(basename(completionScriptPath("fish"))).toBe("recipes.fish");
+  });
+
+  it("renders a front door that names only the fork", async () => {
+    const { BIN_NAME, PROGRAM_DESCRIPTION } = await import("./constants.js");
+    const { formatRootHelp } = await import("./kernel/project/cli/rootHelp.js");
+    const { configModule } = await import("./capabilities/config/index.js");
+    const { upgradeModule } = await import("./capabilities/upgrade/index.js");
+    const { colophonModule } = await import("./capabilities/colophon/index.js");
+
+    const help = formatRootHelp(
+      BIN_NAME,
+      PROGRAM_DESCRIPTION,
+      [
+        dishList,
+        ...configModule.verbs,
+        ...upgradeModule.verbs,
+        ...colophonModule.verbs,
+      ],
+      "9.9.9",
+      "https://recipes.test/issues",
+    );
+
+    expect(help).not.toMatch(THIS_DISTRIBUTION);
+    // The fork's own name and its own version — the header stamps the build
+    // exactly as `--version` reports it, and neither half names this
+    // distribution.
+    expect(help).toMatch(/^recipes v9\.9\.9 — Explore the recipe graph$/m);
+    // The pack noun leads the page untitled, and the blurb is not repeated as
+    // a heading three lines under the header that already carries it.
+    expect(help).toMatch(/^Usage: recipes .*\n\n {2}dish\b/m);
+    expect(help.match(/Explore the recipe graph/g)).toHaveLength(1);
+    expect(help).toContain("Read and write recipes configuration");
+  });
+
+  it("orients an MCP agent with the fork's identity", async () => {
+    const { buildInstructions } = await import(
+      "./kernel/project/mcp/instructions.js"
+    );
+    const { emitSurface } = await import("./kernel/spec/emitSurface.js");
+    const { capabilities } = await import("./capabilities/index.js");
+
+    // The `pragma:` resource scheme is covenant-frozen PROTOCOL identity
+    // (surface.v2.json), not copy. The orientation DERIVES it from the emitted
+    // surface, so mask exactly what the surface declares — a leak the kernel
+    // authored itself would survive this substitution and fail below.
+    const { resources } = emitSurface(capabilities).mcpSurface;
+    expect(resources.length).toBeGreaterThan(0);
+    const text = resources.reduce(
+      (orientation, template) => orientation.replace(template, "<resource>"),
+      buildInstructions(capabilities),
+    );
+
+    expect(text).not.toMatch(THIS_DISTRIBUTION);
+    // No punctuation is appended to the fork's `help` phrase.
+    expect(text.startsWith("recipes — Explore the recipe graph (")).toBe(true);
+  });
+
+  it("hints at a first-time user in the fork's own name", async () => {
+    process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "identity-"));
+    const { setupHintLines } = await import("./kernel/config/firstRun.js");
+    const { globalConfigPath } = await import("./kernel/config/paths.js");
+
+    const hint = setupHintLines().join("\n");
+
+    // The hint names the fork's issues URL and its own setup command; the XDG
+    // namespace has to follow the fork's name too or the path assertion fails.
+    expect(hint).not.toMatch(THIS_DISTRIBUTION);
+    expect(globalConfigPath()).toContain("/recipes/");
+    expect(hint).toContain("https://example.invalid/recipes/issues");
+    expect(hint).toContain("recipes setup");
+  });
+
+  it("narrates the colophon the fork declares, titled with the fork's name", async () => {
+    // The toolchain colophon is DECLARED content (`pragma.conf.ts#colophon`),
+    // not authored code: the collector must render the fork's declaration
+    // under the fork's own name. This is also where the FALLBACK is pinned —
+    // the toolchain's own section prints when no pack tells a domain story,
+    // and a fork with no packs is the distribution that has none.
+    // `kind: "pragma"` is asserted AS the literal:
+    // it is the frozen JSON discriminant every distribution serves (wire
+    // compatibility, like the resource scheme), deliberately NOT derived.
+    process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "identity-"));
+    const { collectColophon } = await import(
+      "./capabilities/colophon/collectColophon.js"
+    );
+    const { bootRuntime } = await import("./kernel/runtime/boot.js");
+
+    const runtime = bootRuntime(
+      { llm: false, autoLlm: false, format: "plain", verbose: false },
+      mkdtempSync(join(tmpdir(), "identity-colophon-")),
+    );
+    const { sections } = await collectColophon(runtime);
+
+    expect(sections).toHaveLength(1);
+    const own = sections[0];
+    expect(own?.kind).toBe("pragma");
+    expect(own?.title).toBe("recipes");
+    expect(own?.markdown).toBe("Made by the kitchen, one dish at a time.");
+    expect(own?.summary).toBe("Kitchen-made.");
+    expect(own?.source).toBe("built-in");
+    for (const text of [own?.title, own?.markdown, own?.summary]) {
+      expect(text).not.toMatch(THIS_DISTRIBUTION);
+    }
+  });
+
+  it("owns its own on-disk skills namespace", async () => {
+    // Config, state and cache were namespaced by the bin name; the SKILLS roots
+    // were not. Two distributions installed side by side therefore shared one
+    // `$XDG_DATA_HOME/pragma/skills` and one `<cwd>/.pragma/skills`, so a fork
+    // read the other's skills and could not install its own without collision.
+    process.env.XDG_DATA_HOME = join(tmpdir(), "identity-data");
+    const { skillRoots, installedSkillsDir } = await import(
+      "./capabilities/skill/discover.js"
+    );
+    expect(installedSkillsDir().endsWith(join("recipes", "skills"))).toBe(true);
+    expect(skillRoots("/work")).toEqual([
+      join("/work", ".recipes", "skills"),
+      installedSkillsDir(),
+    ]);
+    for (const root of skillRoots("/work")) {
+      expect(root).not.toMatch(THIS_DISTRIBUTION);
+    }
+  });
+
+  it("introduces its MCP server on the wire under the fork's name", async () => {
+    // The wire half of the identity rule the covenant records
+    // (mcpSurface.serverInfo): serverInfo PROJECTS — name from the declared
+    // distribution, version from the package. Asserted through a real
+    // initialize handshake (in-memory transport), not on the constant, so a
+    // hardcoded serverInfo in buildServer would fail here even while
+    // MCP_SERVER_NAME projects correctly.
+    const { projectMcp } = await import("./testing/helpers/projectMcp.js");
+    const { VERSION } = await import("./constants.js");
+
+    const mcp = await projectMcp([]);
+    const wire = mcp.serverInfo();
+    await mcp.cleanup();
+
+    expect(wire).toEqual({ name: "recipes", version: VERSION });
+    expect(wire?.name).not.toMatch(THIS_DISTRIBUTION);
+  });
+
+  it("registers an MCP server entry the fork's own binary answers to", async () => {
+    // The entry `setup mcp` writes is what a harness later EXECUTES. It was
+    // hardcoded while the key it is stored under derived from the same
+    // identity, so a fork registered a `recipes` server that ran `pragma` —
+    // and `doctor`'s `MCP configured` check, which re-derived the key by hand,
+    // could never see its own registration.
+    const { pragmaMcpEntry } = await import(
+      "./capabilities/setup/operations/setupMcp.js"
+    );
+    expect(pragmaMcpEntry("/work", "project")).toEqual({
+      command: "recipes",
+      args: ["mcp", "serve"],
+      cwd: "/work",
+    });
+    // The global band omits `cwd` (a per-user server is not project-pinned)
+    // but still runs the fork's own binary.
+    expect(pragmaMcpEntry("/work", "global")).toEqual({
+      command: "recipes",
+      args: ["mcp", "serve"],
+    });
+  });
+
+  it("generates a reference that never names this distribution", async () => {
+    // `docs/reference/` is the surface this package PUBLISHES as machine-derived
+    // truth, so it is the surface a fork's rename must reach in full. Every
+    // command a page quotes, every page title and every prose mention is
+    // composed from `BIN_NAME`. The failure names `page: line`, so it is a
+    // worklist and not just a count.
+    //
+    // ONE exemption, the same one the MCP orientation case above makes and for
+    // the same reason: the `pragma:` resource scheme is covenant-frozen PROTOCOL
+    // identity (`surface.v2.json`), inherited by a fork along with the
+    // `pragma/box`, `pragma/instanceCount` and `pragma/type` `_meta` keys it
+    // travels with, and `tools.md` reports it truthfully. Masked from the
+    // emitted surface, not by a literal, so a leak the kernel authored itself
+    // still fails here.
+    const { emitReference } = await import("./kernel/spec/emitReference.js");
+    const { emitSurface } = await import("./kernel/spec/emitSurface.js");
+    const { capabilities } = await import("./capabilities/index.js");
+
+    const { resources } = emitSurface(capabilities).mcpSurface;
+    expect(resources.length).toBeGreaterThan(0);
+    const unmask = (line: string): string =>
+      resources.reduce((text, template) => text.replace(template, ""), line);
+
+    const offenders: string[] = [];
+    for (const [page, content] of emitReference(capabilities)) {
+      for (const line of content.split("\n")) {
+        if (THIS_NAME.test(unmask(line))) offenders.push(`${page}: ${line}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it("reads the graph with the fork's declared terms, not this distribution's", async () => {
+    // The couplings this tranche removed were all hardcoded terms, and a
+    // hardcoded term still passes every other test in this suite: the fixtures
+    // on both sides would simply agree. So capture what the readers EMIT.
+    const { DEFAULT_PREFIX_MAP } = await import("./kernel/render/prefixes.js");
+    const { VOCABULARY } = await import("./kernel/vocabulary.js");
+    const { readPrompts } = await import(
+      "./kernel/project/mcp/prompts/source.js"
+    );
+
+    // The display/expansion map: the fork's namespaces, none of ours, and the
+    // W3C half the kernel owns unchanged.
+    expect(DEFAULT_PREFIX_MAP.rcp).toBe("https://example.invalid/recipes/");
+    expect(DEFAULT_PREFIX_MAP.ds).toBeUndefined();
+    expect(DEFAULT_PREFIX_MAP.rdfs).toBe(
+      "http://www.w3.org/2000/01/rdf-schema#",
+    );
+
+    // The tier noun is no longer code AT ALL (L-OPEN-9): both its verbs are a
+    // story the distribution declares, so a fork writes its own terms into the
+    // declaration directly and there is nothing left in the kernel for a
+    // hardcoded tier term to hide in. `distribution.test.ts` holds this
+    // distribution's declaration coherent with the vocabulary. What the KERNEL
+    // still reads domain terms with is the vocabulary projection (the index
+    // builder interpolates `VOCABULARY.altName`) and the prompts reader —
+    // captured below.
+    expect(VOCABULARY.altName).toBe("rcp:name");
+
+    // The generated prompt read, captured off a stub facade.
+    const queries: string[] = [];
+    const recorder = {
+      query: {
+        sparql: (query: string) => {
+          queries.push(query);
+          return Promise.resolve({ type: "select", bindings: [] });
+        },
+      },
+    } as never;
+
+    await expect(readPrompts(recorder)).resolves.toEqual([]);
+
+    const emitted = queries.join("\n");
+    expect(emitted).toContain("rcp:Prompt");
+    expect(emitted).toContain("rcp:promptBody");
+    expect(emitted).not.toMatch(THIS_DISTRIBUTION);
+  });
+});

package/src/index.ts

@@ -22,8 +22,8 @@ export type {
   Formatters,
   McpAnnotations,
   OutputFormat,
-  PackageDeclaration,
-  PackageEntry,
+  PackDeclaration,
+  PackSource,
   ParamComplete,
   ParamSpec,
   PragmaConfig,