@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/ontology/verbs.ts

@@ -8,10 +8,9 @@
  * `--class <name>` narrows to one class and the properties whose domain is that
  * class.
  *
- * `ontology show` is the DEPRECATED alias of `ontology lookup` (AV-228 B1): the
- * verb was renamed to `lookup` for consistency with block/standard/tier/etc.
- * (the ratified by-name read name), and `show` is kept callable — both share the
- * same params, disclosure, and handler, and both stay blessed in the covenant.
+ * `ontology lookup` is the ratified by-name read name (AV-228 B1 renamed it
+ * from `show` for consistency with block/standard/tier/etc.); the old alias
+ * is gone — one job, one spelling.
  *
  * Disclosure (B5): rather than reinvent its own scheme, the by-name read declares
  * the canonical disclosure ladder and honours the `--detail`/config `detail` the
@@ -22,15 +21,16 @@
  * any level), so the covenant is untouched.
  */
 
-import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { BIN_NAME } from "../../constants.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
 import { resolvePackDetail } from "../../kernel/packs/disclosure.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type {
   DisclosureSpec,
   ParamSpec,
   VerbSpec,
-} from "../../kernel/spec/types.js";
+} from "../../kernel/spec/index.js";
 import {
   listNamespaces,
   localName,
@@ -51,22 +51,22 @@ function resolvePrefix(
     if (entry) return { prefix: entry[0], namespace: entry[1] };
     throw PragmaError.invalidInput("namespace", input, {
       validOptions: Object.values(prefixes),
-      recovery: {
-        message: "List loaded ontology namespaces.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      recovery: cliRecovery(
+        "ontology list",
+        "List loaded ontology namespaces.",
+        {
+          tool: "ontology_list",
+        },
+      ),
     });
   }
   const namespace = prefixes[input];
   if (namespace === undefined) {
     throw PragmaError.invalidInput("prefix", input, {
       validOptions: Object.keys(prefixes),
-      recovery: {
-        message: "List loaded ontologies.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      recovery: cliRecovery("ontology list", "List loaded ontologies.", {
+        tool: "ontology_list",
+      }),
     });
   }
   return { prefix: input, namespace };
@@ -77,7 +77,7 @@ const listVerb: VerbSpec<Record<string, unknown>, OntologySummary[]> = {
   summary: "List loaded ontology namespaces with class and property counts.",
   params: [],
   output: { formatters: ontologyListFormatters },
-  examples: [{ cmd: "pragma ontology list" }],
+  examples: [{ cmd: `${BIN_NAME} ontology list` }],
   capability: {
     needsStore: true,
     mutates: false,
@@ -93,10 +93,9 @@ const listVerb: VerbSpec<Record<string, unknown>, OntologySummary[]> = {
 };
 
 /**
- * The canonical disclosure the by-name read folds onto (B5). Declared on both
- * the primary {@link ontologyLookupVerb} and its deprecated {@link
- * ontologyShowVerb} alias — so the MCP projector injects the `detail` enum tool
- * param and its per-call `withDetail` seeding light up (symmetric with
+ * The canonical disclosure the by-name read folds onto (B5). Declared on
+ * {@link ontologyLookupVerb} — so the MCP projector injects the `detail` enum
+ * tool param and its per-call `withDetail` seeding light up (symmetric with
  * `block`/`standard`, which an inline resolve left dark over MCP) — AND read by
  * `run` to resolve the effective level, so the advertised param and the fetched
  * level share ONE source. The levels are the full canonical ladder; the fold is
@@ -107,7 +106,7 @@ const BY_NAME_DISCLOSURE: DisclosureSpec = {
   default: "summary",
 };
 
-/** The params shared by `ontology lookup` and its deprecated `ontology show` alias. */
+/** The params of the `ontology lookup` by-name read. */
 const BY_NAME_PARAMS: ParamSpec[] = [
   {
     kind: "string",
@@ -145,7 +144,7 @@ const BY_NAME_CAPABILITY = {
 };
 
 /**
- * The by-name read handler shared by `ontology lookup` and `ontology show`.
+ * The `ontology lookup` by-name read handler.
  *
  * @param params - The coerced param bag (`prefix`, `properties`, `fullUris`, `class`).
  * @param rt - The runtime (store + disclosure precedence).
@@ -193,11 +192,9 @@ async function runByName(
 
   if (classes.length === 0 && properties.length === 0) {
     throw PragmaError.notFound("ontology", String(params.prefix), {
-      recovery: {
-        message: "List loaded ontologies.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
+      recovery: cliRecovery("ontology list", "List loaded ontologies.", {
+        tool: "ontology_list",
+      }),
     });
   }
 
@@ -211,59 +208,21 @@ async function runByName(
   };
 }
 
-/**
- * Build one by-name read verb (`lookup` primary or `show` deprecated alias) —
- * both share {@link BY_NAME_PARAMS}, {@link BY_NAME_DISCLOSURE}, the formatters,
- * and {@link runByName}; only the path label, summary, doc, and examples differ.
- */
-function byNameVerb(
-  verb: "lookup" | "show",
-  summary: string,
-  examples: VerbSpec["examples"],
-  doc?: string,
-): VerbSpec<Record<string, unknown>, OntologyShowData> {
-  return {
-    path: ["ontology", verb],
-    summary,
-    ...(doc !== undefined ? { doc } : {}),
-    params: BY_NAME_PARAMS,
-    output: { formatters: ontologyShowFormatters },
-    examples,
-    disclosure: BY_NAME_DISCLOSURE,
-    capability: BY_NAME_CAPABILITY,
-    run: runByName,
-  };
-}
-
-/** The `ontology` verbs (`list`, `lookup`, and the deprecated `show` alias). */
+/** The `ontology` verbs (`list` and the `lookup` by-name read). */
 export const ontologyListVerb = asVerb(listVerb);
 
-/** `ontology lookup <prefix>` — the primary by-name schema read. */
-export const ontologyLookupVerb = asVerb(
-  byNameVerb(
-    "lookup",
-    "Look up a namespace's classes (hierarchy + counts) and properties.",
-    [
-      { cmd: "pragma ontology lookup ds" },
-      { cmd: "pragma ontology lookup ds --properties" },
-      { cmd: "pragma ontology lookup ds --class Component" },
-    ],
-  ),
-);
-
-/**
- * `ontology show <prefix>` — DEPRECATED alias of {@link ontologyLookupVerb}
- * (AV-228 B1). Kept callable and blessed in the covenant; shares the same
- * handler, so it behaves identically. New callers should use `ontology lookup`.
- */
-export const ontologyShowVerb = asVerb(
-  byNameVerb(
-    "show",
-    "(deprecated: use `ontology lookup`) Show a namespace's classes (hierarchy + counts) and properties.",
-    [
-      { cmd: "pragma ontology lookup ds", note: "prefer `lookup`" },
-      { cmd: "pragma ontology show ds", note: "deprecated alias" },
-    ],
-    "Deprecated alias of `ontology lookup` — retained for compatibility. Prefer `ontology lookup <prefix>`.",
-  ),
-);
+/** `ontology lookup <prefix>` — the by-name schema read. */
+export const ontologyLookupVerb = asVerb({
+  path: ["ontology", "lookup"],
+  summary: "Look up a namespace's classes (hierarchy + counts) and properties.",
+  params: BY_NAME_PARAMS,
+  output: { formatters: ontologyShowFormatters },
+  examples: [
+    { cmd: `${BIN_NAME} ontology lookup ds` },
+    { cmd: `${BIN_NAME} ontology lookup ds --properties` },
+    { cmd: `${BIN_NAME} ontology lookup ds --class Component` },
+  ],
+  disclosure: BY_NAME_DISCLOSURE,
+  capability: BY_NAME_CAPABILITY,
+  run: runByName,
+} satisfies VerbSpec<Record<string, unknown>, OntologyShowData>);

package/src/capabilities/prompt/index.ts

@@ -6,8 +6,8 @@
  * default MCP server advertises prompts sourced from the active graph.
  */
 
-import { promptProvider } from "../../kernel/project/mcp/prompts/provider.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { promptProvider } from "../../kernel/project/mcp/prompts/index.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { promptListVerb, promptLookupVerb } from "./verbs.js";
 
 /** The `prompt` capability module (content tools + native prompt surface). */

package/src/capabilities/prompt/prompt.render.ts

@@ -3,7 +3,7 @@
  */
 
 import { defaultStyle } from "../../kernel/render/style.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type {
   PromptArgument,
   PromptListData,
@@ -19,8 +19,12 @@ function argTokens(args: readonly PromptArgument[]): string {
 }
 
 export const promptListFormatters: Formatters<PromptListData> = {
+  // Zero prompts: plain stdout stays empty — the notice is `emptyNotice`,
+  // routed to stderr (exit 0) by the dispatcher so a pipe reads no prose.
+  emptyNotice: (data) =>
+    data.prompts.length === 0 ? "No prompts in the store." : undefined,
   plain(data) {
-    if (data.prompts.length === 0) return "No prompts in the store.";
+    if (data.prompts.length === 0) return "";
     const lines = ["Prompts"];
     for (const prompt of data.prompts) {
       lines.push(`  ${prompt.name} — ${prompt.description ?? ""}`.trimEnd());

package/src/capabilities/prompt/prompt.test.ts

@@ -1,10 +1,10 @@
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { listPromptSummaries } from "../../kernel/project/mcp/prompts/source.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
-import { writeLock } from "../../kernel/runtime/lock.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
 import type { GlobalFlags } from "../../kernel/spec/types.js";
 import { CANONICAL_TTL } from "../../testing/fixtures/graph/canonical.js";
 import {
@@ -116,7 +116,9 @@ describe("prompt — native MCP prompts surface (PROTECTED)", () => {
 describe("prompt — storeless native listing (PROTECTED)", () => {
   it("listing the prompts does NOT boot the store", async () => {
     const runtime = bootRuntime(FLAGS, fixture.cwd);
-    const summaries = listPromptSummaries(runtime);
+    const summaries = listPromptSummaries(
+      resolveSources(await runtime.loadConfig(), runtime.cwd),
+    );
     expect(summaries.map((s) => s.name).sort()).toEqual(EXPECTED);
     expect(runtime.store.booted).toBe(false);
   });
@@ -127,15 +129,19 @@ describe("prompt — storeless native listing (PROTECTED)", () => {
  * (`needsStore`), so a cold store throws STORE_UNAVAILABLE through its pre-check;
  * native `prompts/list`/`prompts/get` must present the SAME diagnostic rather
  * than silently listing a stale index (D1) or reporting a bogus "not found"
- * (D4). A lock pointing at an evicted pack is the cold "configured but unbuilt"
- * store (the pack is absent from the XDG-isolated cache).
+ * (D4). A project that declares its own packs and has never built them is the
+ * cold "configured but unbuilt" store — the row of the boot decision table
+ * that must never be served the distribution's embedded graph.
  */
 describe("prompt — cold-store convergence, tool + native agree (D1/D4)", () => {
   let cold: McpHarness;
 
   beforeAll(async () => {
     const cwd = mkdtempSync(join(tmpdir(), "pragma-prompt-cold-"));
-    writeLock(cwd, { version: 1, contentHash: "b".repeat(64), packs: [] });
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      `export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n`,
+    );
     cold = await projectMcp(capabilities, cwd);
   });
   afterAll(async () => {

package/src/capabilities/prompt/types.ts

@@ -10,7 +10,7 @@
 import type {
   PromptArgument,
   PromptEntry,
-} from "../../kernel/project/mcp/prompts/source.js";
+} from "../../kernel/project/mcp/prompts/index.js";
 
 /** One prompt in a `prompt_list` result — summary only (no template body). */
 export interface PromptListing {

package/src/capabilities/prompt/verbs.ts

@@ -12,10 +12,12 @@
  * formatters).
  */
 
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { BIN_NAME } from "../../constants.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+import { VOCABULARY } from "../../kernel/index.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import {
   promptListFormatters,
   promptLookupFormatters,
@@ -34,10 +36,10 @@ const READ_CAPABILITY = {
 const listVerb: VerbSpec<Record<string, unknown>, PromptListData> = {
   path: ["prompt", "list"],
   summary: "List the workflow prompt templates the design system offers.",
-  doc: "Browse the ds:Prompt entities in the active graph — name, description, and argument names. The same prompts are offered natively over MCP prompts/list; use prompt_lookup for the full template body.",
+  doc: `Browse the prompt entities the active graph declares (${VOCABULARY.prompt.type} in this distribution) — name, description, and argument names. This distribution's graph carries none today. The same prompts are offered natively over MCP prompts/list; use prompt_lookup for the full template body.`,
   params: [],
   output: { formatters: promptListFormatters },
-  examples: [{ cmd: "pragma prompt list" }],
+  examples: [{ cmd: `${BIN_NAME} prompt list` }],
   capability: READ_CAPABILITY,
   run: (_params: Record<string, unknown>, rt: PragmaRuntime) =>
     import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
@@ -55,19 +57,31 @@ const listVerb: VerbSpec<Record<string, unknown>, PromptListData> = {
 const lookupVerb: VerbSpec<Record<string, unknown>, PromptLookupData> = {
   path: ["prompt", "lookup"],
   summary: "Show one workflow prompt template's body and arguments by name.",
-  doc: "Fetch a single ds:Prompt entity's full template body (with {{arg}} placeholders) and its declared arguments.",
+  doc: "Fetch a single prompt entity's full template body (with {{arg}} placeholders) and its declared arguments. A prompt is addressed by its label; prompt_list names the ones the active graph carries.",
   params: [
     {
       kind: "string",
       name: "name",
-      doc: "The prompt name (e.g. build-a-block).",
+      doc: "The prompt name, as `prompt list` reports it.",
       positional: true,
       required: true,
-      complete: { kind: "names", source: { from: "prompts" } },
+      // A prompt is addressed by its `rdfs:label`, which the index carries as
+      // `label`, and the index reader offers no substitute for a prompt that
+      // carries none. Not a total guarantee: `label` is the first of several
+      // label predicates the index accepts, so an entity labelled ONLY by
+      // `skos:prefLabel` would still complete without resolving. That gap is
+      // the index's label preference order, not this ref.
+      complete: {
+        kind: "names",
+        source: { from: "index", type: VOCABULARY.prompt.type, field: "label" },
+      },
     },
   ],
   output: { formatters: promptLookupFormatters },
-  examples: [{ cmd: "pragma prompt lookup build-a-block" }],
+  // No example command: this distribution's graph declares no prompt, so any
+  // name quoted here exits 1 with ENTITY_NOT_FOUND — and this is the GENERATED
+  // reference, published as machine-derived truth.
+  examples: [],
   capability: READ_CAPABILITY,
   run: (params: Record<string, unknown>, rt: PragmaRuntime) =>
     import("../../kernel/project/mcp/prompts/source.js").then(async (m) => {
@@ -77,11 +91,9 @@ const lookupVerb: VerbSpec<Record<string, unknown>, PromptLookupData> = {
         const available = await m.readPrompts(rt);
         throw PragmaError.notFound("prompt", name, {
           suggestions: available.map((prompt) => prompt.name),
-          recovery: {
-            message: "List available prompts.",
-            cli: "pragma prompt list",
-            mcp: { tool: "prompt_list" },
-          },
+          recovery: cliRecovery("prompt list", "List available prompts.", {
+            tool: "prompt_list",
+          }),
         });
       }
       return entry;

package/src/capabilities/reference.test.ts

@@ -29,4 +29,67 @@ describe("reference docs drift-guard — emitReference == committed (PROTECTED)"
       .sort();
     expect(committed).toEqual([...emitted.keys()].sort());
   });
+
+  it("the create chapter prints the REGISTERED grammar — segments and --no- forms, never rejected spellings", () => {
+    const commands = readCommitted("commands.md");
+    const start = commands.indexOf("\n## create\n");
+    expect(start).toBeGreaterThan(-1);
+    const end = commands.indexOf("\n## ", start + 1);
+    const chapter = commands.slice(start, end === -1 ? undefined : end);
+    // The single-leaf application binding's synopsis carries its required
+    // tree segment and the registered positional token — copying it must not
+    // exit 2 with the operand parsed as an unknown subcommand.
+    expect(chapter).toContain(
+      "pragma create application react [app-path] [options]",
+    );
+    expect(chapter).toContain(
+      "pragma create component <framework> [component-path] [options]",
+    );
+    // The Arguments tables print the SAME registered token their synopses
+    // carry — never the binding-level camelCase name (that spelling belongs
+    // to the MCP schemas in tools.md).
+    expect(chapter).toContain("| `[app-path]` |");
+    expect(chapter).toContain("| `[component-path]` |");
+    expect(chapter).not.toContain("`[appPath]`");
+    expect(chapter).not.toContain("`[componentPath]`");
+    // Default-true confirms document ONLY the spelling the mount registers…
+    for (const token of [
+      "| `--no-with-styles` |",
+      "| `--no-with-stories` |",
+      "| `--no-with-ssr-tests` |",
+      "| `--no-forms` |",
+      "| `--no-run-install` |",
+    ]) {
+      expect(chapter).toContain(token);
+    }
+    // …the rejected positive tokens appear in no flag cell — and the retired
+    // ssr/router pair (always-on facts, no longer prompts) in NO cell at all…
+    for (const token of [
+      "| `--with-styles` |",
+      "| `--with-stories` |",
+      "| `--with-ssr-tests` |",
+      "| `--ssr` |",
+      "| `--no-ssr` |",
+      "| `--router` |",
+      "| `--no-router` |",
+      "| `--forms` |",
+      "| `--run-install` |",
+    ]) {
+      expect(chapter).not.toContain(token);
+    }
+    // …and default-false confirms keep their registered positive form.
+    expect(chapter).toContain("| `--relay` |");
+    expect(chapter).toContain("| `--use-ts-stories` |");
+  });
+
+  it("the create chapter says the contract is executed, and names the guard", () => {
+    const commands = readCommitted("commands.md");
+    const start = commands.indexOf("\n## create\n");
+    expect(start).toBeGreaterThan(-1);
+    const chapter = commands.slice(start, commands.indexOf("\n### ", start));
+    // Pragma's docs point, never copy. The pointer names a TEST rather than a
+    // document, because the parity claim is only worth what executes it: a
+    // prose contract can go stale silently, a spawned matrix cannot.
+    expect(chapter).toContain("crossCli.subprocess.test.ts");
+  });
 });