@canonical/pragma-cli 0.34.0 → 0.36.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
@@ -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 `notice`,
+  // routed to stderr (exit 0) by the dispatcher so a pipe reads no prose.
+  notice: (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");
+  });
 });

package/src/capabilities/renderVocabularySync.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Render-vocabulary sync (PROTECTED) — the two halves of the "one vocabulary"
+ * guarantee that cannot be a shared module.
+ *
+ * 1. CROSS-BINARY GLYPHS. The pragma CLI and the summon-core Ink wizard
+ *    narrate the same run — a ✓ per completed effect, a ✗ when it fails — but
+ *    they cannot read one module: pragma's renderers are statically reachable
+ *    from the `--help`/`__complete` fast paths, and THREE protected guards
+ *    (`create.test.ts`'s static-graph walk, `lazy.test.ts`, the perf budgets)
+ *    forbid summon-core from that graph — loading it costs a measured
+ *    double-digit-MB RSS, and an eager summon-core subpath import has already
+ *    cost the fast paths ~46 ms once (BUDGETS.md). So the duplication is kept
+ *    and made STRUCTURAL: summon-core publishes its wizard glyphs off the
+ *    light `/format` seam, and this test pins them byte-equal to the
+ *    vocabulary's. A divergence is a red build, not a review hope.
+ *
+ * 2. THE RETIRED WORD STAYS RETIRED, in the model as well as the copy. The
+ *    render goldens pin that no output says "band"; this pins the same for
+ *    the CODE of the modules that own setup/doctor's model and rendering, so
+ *    the split cannot reopen the way it did — words moved, model unmoved.
+ *    Comments are stripped first: history may NAME the retired word (the
+ *    vocabulary docblock does, deliberately); code may not USE it.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { GLYPHS } from "../kernel/render/vocabulary.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+describe("cross-binary glyph vocabulary (PROTECTED)", () => {
+  it("summon-core's wizard marks byte-equal the vocabulary's", async () => {
+    // Dynamic import, test-only — production pragma code never reaches
+    // summon-core statically, and this test must not become the exception.
+    const { COMPLETED_GLYPH, FAILURE_GLYPH } = await import(
+      "@canonical/summon-core/format"
+    );
+    expect(COMPLETED_GLYPH).toBe(GLYPHS.success);
+    expect(FAILURE_GLYPH).toBe(GLYPHS.failure);
+  });
+});
+
+/** The directories whose model/rendering code the word-guard covers. */
+const GUARDED_DIRS = [
+  "doctor",
+  "setup",
+  "shared",
+  "sources",
+  "skill",
+  "../kernel/render",
+];
+
+/** Every non-test .ts file under a directory, recursively. */
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return sourceFiles(path);
+    if (!entry.name.endsWith(".ts") || entry.name.endsWith(".test.ts"))
+      return [];
+    return [path];
+  });
+}
+
+/** Strip block and line comments, leaving only code that compiles to bytes. */
+const stripComments = (source: string): string =>
+  source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|\s)\/\/[^\n]*/g, "$1");
+
+describe("the retired word stays retired in the type layer (PROTECTED)", () => {
+  it("no setup/doctor model or render code says `band`", () => {
+    const offenders: string[] = [];
+    for (const dir of GUARDED_DIRS) {
+      for (const file of sourceFiles(resolve(here, dir))) {
+        const code = stripComments(readFileSync(file, "utf-8"));
+        const hit = code.match(/\bbands?\b/i);
+        if (hit) offenders.push(`${relative(here, file)}: ${hit[0]}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});