@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/capabilities/meta/mcp.verb.ts

@@ -1,19 +1,21 @@
 /**
- * The hidden `mcp` verb — the MCP server entry point.
+ * `mcp serve` — the MCP server entry point.
  *
- * The server is not an agent tool, so it is withheld from MCP with a reason and
- * `hidden` from the CLI surface/help. The bin special-cases `pragma mcp` to
- * serve over stdio (D9); this spec's lazy `run` is the same serve, reachable if
- * a future tier dispatches it.
+ * The server is not an agent tool, so it is withheld from MCP with a reason —
+ * but it IS a command, and it is spelled like one: a noun and a verb, the same
+ * shape as every other pair in the grammar, so it completes, appears in help,
+ * and answers `--help` without a special case. The bin still short-circuits
+ * the exact `pragma mcp serve` invocation before flag parsing and first-run,
+ * because the server's stdout carries JSON-RPC and nothing else may reach it;
+ * this spec's lazy `run` is that same serve, for any tier that dispatches it.
  */
 
-import type { VerbSpec } from "../../kernel/spec/types.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 
 /** The `mcp` verb spec. */
 export const mcpVerb: VerbSpec<Record<string, unknown>, void> = {
-  path: ["mcp"],
+  path: ["mcp", "serve"],
   summary: "Start the MCP server over stdio.",
-  hidden: true,
   params: [],
   output: {
     formatters: {

package/src/capabilities/ontology/index.ts

@@ -2,18 +2,22 @@
  * The `ontology` capability module — schema (TBox) inspection.
  */
 
-import type { CapabilityModule } from "../../kernel/spec/types.js";
-import {
-  ontologyListVerb,
-  ontologyLookupVerb,
-  ontologyShowVerb,
-} from "./verbs.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
+import { ontologyListVerb, ontologyLookupVerb } from "./verbs.js";
 
-/**
- * The `ontology` capability module (`list`, `lookup`, and the deprecated `show`
- * alias — AV-228 B1).
- */
+/** The `ontology` capability module (`list` and the `lookup` by-name read). */
 export const ontologyModule: CapabilityModule = {
   name: "ontology",
-  verbs: [ontologyListVerb, ontologyLookupVerb, ontologyShowVerb],
+  verbs: [ontologyListVerb, ontologyLookupVerb],
+  /**
+   * The ONE hand-declared listing in the distribution. Every other module is
+   * story-compiled and has its slice DERIVED from the types its lookup already
+   * names; this noun addresses the schema itself, which no `type` filter
+   * expresses — the whole TBox is the answer, so it is stated once, here.
+   *
+   * `0.5` puts the schema below the story collections (weight 1) it explains
+   * and above nothing else: an agent orienting itself wants the collections
+   * first, then the vocabulary they are described in.
+   */
+  mcpListable: { sources: [{ box: "tbox", as: "entities", weight: 0.5 }] },
 };

package/src/capabilities/ontology/ontology.test.ts

@@ -1,5 +1,5 @@
 /**
- * Ontology inspection (list + show) over the block fixture graph.
+ * Ontology inspection (list + lookup) over the block fixture graph.
  *
  * Asserts the TBox exception: namespaces are grouped with class/property counts,
  * a namespace's class hierarchy carries per-class instance counts from the pack
@@ -32,10 +32,6 @@ const listVerb = ontologyModule.verbs.find(
 const lookupVerb = ontologyModule.verbs.find(
   (v) => verbKey(v.path) === "ontology lookup",
 ) as VerbSpec;
-const showVerb = ontologyModule.verbs.find(
-  (v) => verbKey(v.path) === "ontology show",
-) as VerbSpec;
-
 let rt: PragmaRuntime;
 beforeAll(async () => {
   ({ rt } = await buildFixtureRuntime({
@@ -132,36 +128,11 @@ describe("ontology lookup (primary by-name read)", () => {
   });
 });
 
-describe("ontology show — deprecated alias of lookup (AV-228 B1)", () => {
-  it("is marked deprecated in its summary and steers callers to `ontology lookup`", () => {
-    expect(showVerb.summary.toLowerCase()).toContain("deprecated");
-    expect(showVerb.summary).toContain("ontology lookup");
-  });
-
-  it("shares the lookup handler — same payload for the same input", async () => {
-    const viaLookup = (await lookupVerb.run(
-      { prefix: "ds", properties: true },
-      rt,
-    )) as OntologyShowData;
-    const viaShow = (await showVerb.run(
-      { prefix: "ds", properties: true },
-      rt,
-    )) as OntologyShowData;
-    expect(viaShow).toEqual(viaLookup);
-  });
-
-  it("still rejects an unknown prefix (the alias is a full, callable verb)", async () => {
-    await expect(showVerb.run({ prefix: "nope" }, rt)).rejects.toThrow(
-      /prefix/i,
-    );
-  });
-});
-
-describe("ontology_show honours detail over MCP (B5)", () => {
-  // The CLI B5 cases above seed `globalFlags.detail` and call `showVerb.run`
+describe("ontology_lookup honours detail over MCP (B5)", () => {
+  // The CLI B5 cases above seed `globalFlags.detail` and call `lookupVerb.run`
   // directly. Over MCP there are NO global flags — the ONLY detail channel is
   // the per-tool `detail` param the projector injects from the VerbSpec
-  // disclosure. Under an AMBIENT config `detail: standard`, an `ontology_show`
+  // disclosure. Under an AMBIENT config `detail: standard`, a by-name read
   // with no declared disclosure would force the properties section with no
   // per-call escape (the AV-228 MCP-opt-out asymmetry `block`/`standard` lack);
   // declaring disclosure lights the param up, so an agent can ask for
@@ -184,15 +155,6 @@ describe("ontology_show honours detail over MCP (B5)", () => {
     await fixture.dispose();
   });
 
-  it("injects a detail param onto the ontology_show tool (symmetric with block/standard)", async () => {
-    const tools = await mcp.listTools();
-    const show = tools.find((t) => t.name === "ontology_show");
-    const schema = show?.inputSchema as {
-      properties?: Record<string, unknown>;
-    };
-    expect(schema.properties?.detail).toBeDefined();
-  });
-
   it("exposes the primary ontology_lookup tool with the same injected detail param (AV-228 B1)", async () => {
     const tools = await mcp.listTools();
     const lookup = tools.find((t) => t.name === "ontology_lookup");
@@ -217,25 +179,14 @@ describe("ontology_show honours detail over MCP (B5)", () => {
   it("honours the ambient detail=standard config when no per-call detail is set", async () => {
     // Proves the ambient level really is standard, so the summary case below is
     // a genuine per-call override rather than merely the spec default.
-    const result = await mcp.callTool("ontology_show", { prefix: "ds" });
+    const result = await mcp.callTool("ontology_lookup", { prefix: "ds" });
     expect(result.ok).toBe(true);
     const data = result.data as { properties: unknown[] };
     expect(data.properties.length).toBeGreaterThan(0);
   });
 
-  it("a per-call detail=summary returns classes-only despite the ambient standard", async () => {
-    const result = await mcp.callTool("ontology_show", {
-      prefix: "ds",
-      detail: "summary",
-    });
-    expect(result.ok).toBe(true);
-    const data = result.data as { classes: unknown[]; properties: unknown[] };
-    expect(data.classes.length).toBeGreaterThan(0);
-    expect(data.properties).toEqual([]);
-  });
-
   it("an explicit detail=detailed overrides upward to include properties", async () => {
-    const result = await mcp.callTool("ontology_show", {
+    const result = await mcp.callTool("ontology_lookup", {
       prefix: "ds",
       detail: "detailed",
     });

package/src/capabilities/ontology/queries.ts

@@ -7,7 +7,7 @@
  * result never depends on which vocabulary prefixes the store injected.
  */
 
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 
 const OWL = "http://www.w3.org/2002/07/owl#";
 const RDFS = "http://www.w3.org/2000/01/rdf-schema#";
@@ -40,7 +40,7 @@ export interface OntologyProperty {
   readonly type: "object" | "datatype";
 }
 
-/** The `ontology show` payload — the detailed view plus render options. */
+/** The `ontology lookup` payload — the detailed view plus render options. */
 export interface OntologyShowData {
   readonly prefix: string;
   readonly namespace: string;

package/src/capabilities/ontology/render.ts

@@ -1,10 +1,9 @@
 /**
- * Formatters for `ontology list` and `ontology show`.
+ * Formatters for `ontology list` and `ontology lookup`.
  */
 
-import { compactUri } from "../../kernel/render/compactUri.js";
-import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
-import type { Formatters } from "../../kernel/spec/types.js";
+import { compactUri, DEFAULT_PREFIX_MAP } from "../../kernel/render/index.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type {
   OntologyClass,
   OntologyProperty,

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
@@ -23,16 +22,15 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { cliRecovery } from "../../kernel/error/recovery.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,
@@ -95,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
@@ -109,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",
@@ -147,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).
@@ -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: `${BIN_NAME} ontology lookup ds` },
-      { cmd: `${BIN_NAME} ontology lookup ds --properties` },
-      { cmd: `${BIN_NAME} 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: `${BIN_NAME} ontology lookup ds`, note: "prefer `lookup`" },
-      { cmd: `${BIN_NAME} 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/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

@@ -13,12 +13,11 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { cliRecovery } from "../../kernel/error/recovery.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.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 { VOCABULARY } from "../../kernel/vocabulary.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
 import {
   promptListFormatters,
   promptLookupFormatters,

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");
+  });
 });