@canonical/pragma-cli 0.34.0 → 0.36.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.ts

@@ -17,6 +17,7 @@
 
 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 — the distribution's `name`. */
@@ -64,12 +65,45 @@ 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];
 
 /** Default detail level when neither flag, config, nor spec pins one. */
 const DEFAULT_DETAIL_LEVEL: DetailLevel = "standard";
 
+/**
+ * The wordmark `--help` opens with FOR A HUMAN READER, as raw ASCII-art lines.
+ *
+ * Whether it prints is decided at the one emit site (`rootHelp.ts`) from the
+ * invocation's global flags: a captured run (`--format llm`/`json`, including
+ * the `llm` a non-interactive stdout infers) gets the bare header instead. This
+ * constant is the ART, not the policy.
+ *
+ * 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,
@@ -79,6 +113,7 @@ export {
   MCP_SERVER_NAME,
   OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
+  PROGRAM_LOGO,
   PROJECT_CONFIG_FILENAME,
   RECOVERY_CLI_PREFIX,
   VERSION,

package/src/identity.test.ts

@@ -112,15 +112,27 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     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,
-    ]);
+    const help = formatRootHelp(
+      BIN_NAME,
+      PROGRAM_DESCRIPTION,
+      [
+        dishList,
+        ...configModule.verbs,
+        ...upgradeModule.verbs,
+        ...colophonModule.verbs,
+      ],
+      "9.9.9",
+      "https://recipes.test/issues",
+      // A human at a terminal: the fork's own art (it declares none) would
+      // print here, so the assertions below see the widest page.
+      { llm: false, format: "plain", verbose: false },
+    );
 
     expect(help).not.toMatch(THIS_DISTRIBUTION);
-    expect(help).toMatch(/^recipes — Explore the recipe graph$/m);
+    // 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);
@@ -151,29 +163,28 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     expect(text.startsWith("recipes — Explore the recipe graph (")).toBe(true);
   });
 
-  it("greets a first-time user with the fork's issues URL and config file", async () => {
+  it("hints at a first-time user in the fork's own name", async () => {
     process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "identity-"));
-    const { ensureFirstRun } = await import("./kernel/config/firstRun.js");
+    const { setupHintLines } = await import("./kernel/config/firstRun.js");
     const { globalConfigPath } = await import("./kernel/config/paths.js");
 
-    const lines: string[] = [];
-    await ensureFirstRun((line) => lines.push(line));
-    const greeting = lines.join("\n");
+    const hint = setupHintLines().join("\n");
 
-    // Nothing is masked: the resolved config path is IN the greeting, so the
-    // XDG namespace has to follow the fork's name too or this assertion fails.
-    expect(greeting).not.toMatch(THIS_DISTRIBUTION);
-    expect(greeting).toContain(globalConfigPath());
+    // 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(greeting).toContain("https://example.invalid/recipes/issues");
-    expect(greeting).toContain("`recipes.config.ts`");
+    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. With no packs declared, the fork's whole
-    // colophon is its own story. `kind: "pragma"` is asserted AS the literal:
+    // 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-"));
@@ -206,15 +217,25 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     // `$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(
+    const { skillRoots, installedSkillsDir, bundledSkillsDir } = await import(
       "./capabilities/skill/discover.js"
     );
     expect(installedSkillsDir().endsWith(join("recipes", "skills"))).toBe(true);
-    expect(skillRoots("/work")).toEqual([
+    // The two roots that live on SHARED ground — the user's data home and the
+    // user's repository — are the ones a fork must namespace.
+    const namespaced = [
       join("/work", ".recipes", "skills"),
       installedSkillsDir(),
-    ]);
-    for (const root of skillRoots("/work")) {
+    ];
+    // The bundled snapshot is the third, and it is deliberately NOT namespaced
+    // by the bin name: it is the distribution's OWN package directory, which is
+    // already private to the install. A fork is a different package and ships
+    // its own `bundled-skills/`, so there is no shared ground to collide on —
+    // and it is exempt from the check below for exactly that reason, since the
+    // path this repository's package sits at necessarily says "pragma".
+    expect(bundledSkillsDir()).toBeDefined();
+    expect(skillRoots("/work")).toEqual([...namespaced, bundledSkillsDir()]);
+    for (const root of namespaced) {
       expect(root).not.toMatch(THIS_DISTRIBUTION);
     }
   });
@@ -246,11 +267,17 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     const { pragmaMcpEntry } = await import(
       "./capabilities/setup/operations/setupMcp.js"
     );
-    expect(pragmaMcpEntry("/work")).toEqual({
+    expect(pragmaMcpEntry("/work", "project")).toEqual({
       command: "recipes",
-      args: ["mcp"],
+      args: ["mcp", "serve"],
       cwd: "/work",
     });
+    // The global scope 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 () => {
@@ -263,9 +290,10 @@ describe("identity projection — a fork changes values, not code (PROTECTED)",
     // 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` and `pragma/instanceCount` `_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.
+    // `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");

package/src/kernel/completion/__snapshots__/emitScripts.test.ts.snap

@@ -65,21 +65,21 @@ _pragma() {
   # flag names
   if [[ "$cur" == -* ]]; then
     case "$noun/$verb" in
-      block/get) COMPREPLY=($(compgen -W "--view --out --with-meta --note --format --verbose --detail --help" -- "$cur")); return ;;
-      block/list) COMPREPLY=($(compgen -W "--tags --format --verbose --detail --help" -- "$cur")); return ;;
-      block/remove) COMPREPLY=($(compgen -W "--dry-run --undo --yes --format --verbose --detail --help" -- "$cur")); return ;;
+      block/get) COMPREPLY=($(compgen -W "--view --out --with-meta --note --format --verbose --detail --no-headers --quiet --help" -- "$cur")); return ;;
+      block/list) COMPREPLY=($(compgen -W "--tags --format --verbose --detail --no-headers --quiet --help" -- "$cur")); return ;;
+      block/remove) COMPREPLY=($(compgen -W "--dry-run --undo --yes --format --verbose --detail --no-headers --quiet --help" -- "$cur")); return ;;
     esac
     if [ -z "$noun" ]; then
-      COMPREPLY=($(compgen -W "--format --verbose --detail --help --version" -- "$cur"))
+      COMPREPLY=($(compgen -W "--format --verbose --detail --no-headers --quiet --help --version" -- "$cur"))
     else
-      COMPREPLY=($(compgen -W "--format --verbose --detail --help" -- "$cur"))
+      COMPREPLY=($(compgen -W "--format --verbose --detail --no-headers --quiet --help" -- "$cur"))
     fi
     return
   fi
 
   # nouns
   if [ -z "$noun" ]; then
-    COMPREPLY=($(compgen -W "block mcp standard status" -- "$cur"))
+    COMPREPLY=($(compgen -W "block standard status" -- "$cur"))
     return
   fi
 
@@ -172,12 +172,14 @@ end
 complete -c pragma -f
 
 # nouns
-complete -c pragma -n "__pragma_at ''" -a "block mcp standard status"
+complete -c pragma -n "__pragma_at ''" -a "block standard status"
 
 # global flags
 complete -c pragma -l format -x -a "plain llm json"
 complete -c pragma -l verbose
 complete -c pragma -l detail -x -a "summary standard detailed"
+complete -c pragma -l no-headers
+complete -c pragma -l quiet
 complete -c pragma -l help
 complete -c pragma -n "__pragma_at ''" -l version
 
@@ -277,21 +279,21 @@ _pragma() {
   # flag names
   if [[ "$cur" == -* ]]; then
     case "$noun/$verb" in
-      block/get) compadd -- --view --out --with-meta --note --format --verbose --detail --help; return 0 ;;
-      block/list) compadd -- --tags --format --verbose --detail --help; return 0 ;;
-      block/remove) compadd -- --dry-run --undo --yes --format --verbose --detail --help; return 0 ;;
+      block/get) compadd -- --view --out --with-meta --note --format --verbose --detail --no-headers --quiet --help; return 0 ;;
+      block/list) compadd -- --tags --format --verbose --detail --no-headers --quiet --help; return 0 ;;
+      block/remove) compadd -- --dry-run --undo --yes --format --verbose --detail --no-headers --quiet --help; return 0 ;;
     esac
     if [[ -z "$noun" ]]; then
-      compadd -- --format --verbose --detail --help --version
+      compadd -- --format --verbose --detail --no-headers --quiet --help --version
     else
-      compadd -- --format --verbose --detail --help
+      compadd -- --format --verbose --detail --no-headers --quiet --help
     fi
     return 0
   fi
 
   # nouns
   if [[ -z "$noun" ]]; then
-    compadd -- block mcp standard status
+    compadd -- block standard status
     return 0
   fi
 

package/src/kernel/completion/complete.test.ts

@@ -16,15 +16,24 @@ describe("runComplete — the __complete pipeline", () => {
   it("resolves against the live capabilities (storeless static matches)", async () => {
     await expect(runComplete(["co"], capabilities)).resolves.toEqual([
       "colophon",
+      "concept",
       "config",
     ]);
     // The live `config` sub-verbs, prefix-filtered and sorted by the resolver.
-    // AV-228 B3 retired the per-field tier/channel/detail verbs, leaving set + show.
+    // AV-228 B3 retired the per-field tier/channel/detail verbs; the family is
+    // now the four jobs — read all, read one, write one, clear one.
     await expect(runComplete(["config", ""], capabilities)).resolves.toEqual([
+      "get",
       "set",
       "show",
+      "unset",
     ]);
     await expect(runComplete(["mc"], capabilities)).resolves.toEqual(["mcp"]);
+    // The server entry completes from its own spec — it used to be injected
+    // into the model because the bin served it without one.
+    await expect(runComplete(["mcp", ""], capabilities)).resolves.toEqual([
+      "serve",
+    ]);
     await expect(runComplete(["--d"], capabilities)).resolves.toEqual([
       "--detail",
     ]);
@@ -38,6 +47,7 @@ describe("runComplete — the __complete pipeline", () => {
   it("strips a leading bin name", async () => {
     await expect(runComplete(["pragma", "co"], capabilities)).resolves.toEqual([
       "colophon",
+      "concept",
       "config",
     ]);
   });
@@ -93,7 +103,7 @@ describe("runComplete — never-throw guard (PROTECTED)", () => {
     await runComplete(["co"], capabilities);
     const lines = write.mock.calls.map((call) => String(call[0]));
     expect(lines.join("")).toMatch(
-      /\[complete\] context=noun partial="co" candidates=2 in \d+(\.\d+)?ms/,
+      /\[complete\] context=noun partial="co" candidates=3 in \d+(\.\d+)?ms/,
     );
   });
 });

package/src/kernel/completion/complete.ts

@@ -30,7 +30,7 @@
  * whole grammar is testable through this one function.
  */
 
-import type { CapabilityModule } from "../spec/types.js";
+import type { CapabilityModule } from "../spec/index.js";
 import { emptyNameSource } from "./entitySource.js";
 import { buildCompletionModel } from "./model.js";
 import { parseWords } from "./parse.js";

package/src/kernel/completion/emitScripts.ts

@@ -28,7 +28,7 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { CapabilityModule } from "../spec/types.js";
+import type { CapabilityModule } from "../spec/index.js";
 import { assertSafeToken, buildCompletionModel } from "./model.js";
 import { bashScript } from "./templates/bash.js";
 import { fishScript } from "./templates/fish.js";

package/src/kernel/completion/entitySource.test.ts

@@ -2,6 +2,10 @@ import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  bundledSkillsDir,
+  discoverSkillsFrom,
+} from "../../capabilities/skill/discover.js";
 import { readConfig } from "../config/readConfig.js";
 import { embeddedManifest } from "../runtime/graphpack/embedded.js";
 import { activePackPath, packDir } from "../runtime/paths.js";
@@ -121,10 +125,19 @@ describe("indexCompletionEnv — multi-source names(ref)", () => {
       join(skillDir, "SKILL.md"),
       "---\nname: docx\ndescription: Word docs.\n---\n",
     );
+    // The BUNDLED snapshot ships inside the package, so it is a discovery root
+    // on every machine — including this one. The project root's skill is what
+    // this cell is about; the expectation is derived from the shipped artifact
+    // rather than pinned to a list, so a release that changes which skills the
+    // packs provide does not rewrite this test.
+    const bundled = discoverSkillsFrom([bundledSkillsDir() as string]).map(
+      (skill) => skill.name,
+    );
+    const expected = [...new Set(["docx", ...bundled])].sort();
     const env = indexCompletionEnv(cwd);
-    expect(await env.names({ from: "skills" })).toEqual(["docx"]);
+    expect(await env.names({ from: "skills" })).toEqual(expected);
     // A second read returns the same list (one filesystem walk per env).
-    expect(await env.names({ from: "skills" })).toEqual(["docx"]);
+    expect(await env.names({ from: "skills" })).toEqual(expected);
   });
 
   it("a type nothing matches yields [] (prefixes still list the default map)", async () => {
@@ -313,7 +326,7 @@ describe("the storeless fast path implements the pointer half", () => {
     // and would pass with the config file deleted. The read half refusing is
     // what makes this directory a configured-but-unbuilt project rather than a
     // fresh install. (`doctor` says so too, in the same words: verified against
-    // the compiled binary, where `block list` raises STORE_UNAVAILABLE while
+    // a cold install, where `block list` raises STORE_UNAVAILABLE while
     // this same completion still answers.)
     //
     // If a later change gives the fast path a config-free way to see

package/src/kernel/completion/entitySource.ts

@@ -33,11 +33,13 @@
  * - The embedded fallback is read from `pack.index.generated` — its OWN
  *   generated module (only the index string) — so the storeless `__complete`
  *   path never EVALUATES the n-quads/schema/manifest strings that live in
- *   `pack.generated`. It does not avoid parsing them: `bun build --compile`
- *   emits one script, so the whole embed is parsed at process start on every
- *   invocation (~+25 ms here, measured on `--version` against a toy-embed
- *   binary; BUDGETS.md records it). What the split buys is that a completion
- *   never allocates the 1.87 MB.
+ *   `pack.generated`. Under the compiled binary it did not avoid PARSING them
+ *   either — one emitted script meant the whole embed was parsed at process
+ *   start on every invocation (~+25 ms, measured on `--version`; BUDGETS.md
+ *   records it), and the split bought only that a completion never allocated
+ *   the 1.87 MB. Shipping per-module output changed that: `pack.generated` is
+ *   a separate module the fast path never imports, so it is no longer parsed
+ *   at all there. The split now buys both.
  * - The active pack is resolved through `kernel/runtime/paths` — a LEAF module
  *   (node builtins only) that shares the pointer read with `resolveSources`.
  *   `resolveSources` itself is unreachable from here: it pulls the graphpack
@@ -62,7 +64,7 @@ import { discoverSkills } from "../../capabilities/skill/discover.js";
 // Inlined embedded index — its OWN generated module (only the index string), so
 // the storeless `__complete` path never pulls the n-quads/schema/manifest
 // strings that live in `pack.generated.ts`.
-import { DEFAULT_PREFIX_MAP } from "../render/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../render/index.js";
 import { indexJson as EMBEDDED_INDEX_JSON } from "../runtime/graphpack/embedded/pack.index.generated.js";
 import type { PackIndex, PackIndexEntity } from "../runtime/graphpack/types.js";
 import { packDir, readActivePack } from "../runtime/paths.js";
@@ -156,8 +158,19 @@ function loadActiveIndex(cwd: string): PackIndex | undefined {
     : readIndexFile(packDir(contentHash));
 }
 
-/** Whether an entity matches a prefixed type filter (primary type or any type). */
-function matchesType(entity: PackIndexEntity, type: string): boolean {
+/**
+ * Whether an entity matches a prefixed type filter (primary type or any type).
+ *
+ * Exported because the MCP resource listing addresses the index by the SAME
+ * vocabulary a completion source does (`McpListableRef` reuses
+ * `CompletionSourceRef`'s fields), and "which entities is this type?" must be
+ * ONE rule — two would let a type list entities its completion refuses.
+ *
+ * @param entity - The indexed entity to test.
+ * @param type - A prefixed type filter; empty matches every entity.
+ * @returns Whether the entity carries that type.
+ */
+export function matchesType(entity: PackIndexEntity, type: string): boolean {
   if (!type) return true;
   if (entity.type === type) return true;
   return Array.isArray(entity.types) && entity.types.includes(type);