@canonical/pragma-cli 0.33.0 → 0.35.0

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
 
@@ -142,6 +142,9 @@ end
 function __pragma_minchars
     test (string length -- (commandline -ct)) -ge $argv[1]
 end
+function __pragma_notflag
+    not string match -q -- '-*' (commandline -ct)
+end
 function __pragma_at
     set -l cmd (commandline -opc)
     set -l noun ''
@@ -169,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
 
@@ -185,14 +190,14 @@ complete -c pragma -n "__pragma_at block" -a "diff get list remove"
 complete -c pragma -n "__pragma_at standard" -a "list"
 
 # block/diff
-complete -c pragma -n "__pragma_at block diff; and __pragma_minchars 2" -a "(pragma __complete -- (__pragma_words) 2>/dev/null)"
+complete -c pragma -n "__pragma_at block diff; and __pragma_notflag; and __pragma_minchars 2" -a "(pragma __complete -- (__pragma_words) 2>/dev/null)"
 
 # block/get
 complete -c pragma -n "__pragma_at block get" -l view -x -a "anatomy full summary"
 complete -c pragma -n "__pragma_at block get" -l out -rF
 complete -c pragma -n "__pragma_at block get" -l with-meta
 complete -c pragma -n "__pragma_at block get" -l note -x
-complete -c pragma -n "__pragma_at block get; and __pragma_minchars 2" -a "(pragma __complete -- (__pragma_words) 2>/dev/null)"
+complete -c pragma -n "__pragma_at block get; and __pragma_notflag; and __pragma_minchars 2" -a "(pragma __complete -- (__pragma_words) 2>/dev/null)"
 
 # block/list
 complete -c pragma -n "__pragma_at block list" -l tags -x
@@ -274,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.test.ts

@@ -108,7 +108,7 @@ describe("emitScripts — minChars gate + family opt-out", () => {
   });
 });
 
-describe("emitScripts — binName parameterization (PR8 seam)", () => {
+describe("emitScripts — binName parameterization", () => {
   it("defaults to pragma", () => {
     expect(scripts.bash).toContain("complete -F _pragma pragma");
     expect(scripts.zsh.startsWith("#compdef pragma")).toBe(true);

package/src/kernel/completion/emitScripts.ts

@@ -5,12 +5,14 @@
  * derivation the `__complete` resolver uses — the tiers cannot disagree) and
  * renders one script per supported shell. The static tier answers STRUCTURE
  * with zero exec: nouns, verbs, flag names, enum values, mutation + global
- * flags, native file completion. Only `{kind:"entity"}` value contexts shell
+ * flags, native file completion. Only `{kind:"names"}` value contexts shell
  * out to `<bin> __complete`.
  *
  * PR6 boundary (`setup completions`): this module exports pure CONTENT only
  * — shell detection, install paths, mkdir/write effects, and hints all
- * belong to setup. `binName` is parameterized so the PR8 bin swap is free;
+ * belong to setup. `binName` is parameterized so a fork's rename reaches the
+ * script body (`completionScriptPath` derives the file NAME from the same
+ * constant, and the two must agree or the shell never loads the file);
  * `minChars` and `disabledFamilies` are read from `completion` config by setup.
  *
  * `minChars` (default {@link DEFAULT_MIN_CHARS}) is baked into the scripts to
@@ -26,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

@@ -1,45 +1,68 @@
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { readConfig } from "../config/readConfig.js";
+import { embeddedManifest } from "../runtime/graphpack/embedded.js";
+import { activePackPath, packDir } from "../runtime/paths.js";
+import { resolveSources } from "../runtime/resolveSources.js";
 import type { CapabilityModule, VerbSpec } from "../spec/types.js";
 import { runComplete } from "./complete.js";
-import { createIndexEntityReader, indexCompletionEnv } from "./entitySource.js";
+import {
+  createIndexEntityReader,
+  indexCompletionEnv,
+  readPackIndex,
+} from "./entitySource.js";
 
-/** A fresh cwd with no lock → the reader falls back to the embedded pack. */
+/** A fresh cwd with no pointer → the reader falls back to the embedded pack. */
 const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-entity-"));
 
-/** A project whose lock points at a crafted index.json in a temp pack cache. */
+/** The 64-hex content hash the crafted pack is filed under. */
+const CRAFTED_HASH = "1".repeat(64);
+
+/** A project pointed at a crafted index.json in a temp pack cache. */
 function projectWithIndex(index: unknown): string {
   const cwd = mkdtempSync(join(tmpdir(), "pragma-idx-cwd-"));
   const cache = mkdtempSync(join(tmpdir(), "pragma-idx-cache-"));
   vi.stubEnv("XDG_CACHE_HOME", cache);
-  writeFileSync(
-    join(cwd, "pragma.lock.json"),
-    JSON.stringify({ contentHash: "testhash" }),
-  );
-  const packDir = join(cache, "pragma", "packs", "testhash");
+  const pointer = activePackPath(cwd);
+  mkdirSync(dirname(pointer), { recursive: true });
+  writeFileSync(pointer, CRAFTED_HASH);
+  const packDir = join(cache, "pragma", "packs", CRAFTED_HASH);
   mkdirSync(packDir, { recursive: true });
   writeFileSync(join(packDir, "index.json"), JSON.stringify(index));
   return cwd;
 }
 
-/** A crafted index exercising the index / prompts / tiers / prefixes sources. */
+/**
+ * A crafted index exercising the index / prefixes sources. Deliberately in a
+ * NEUTRAL namespace: the reader knows no entity families any more, so a test
+ * proving it reads `label` or `altNames` must not need this distribution's
+ * vocabulary to say so. Since L-OPEN-9 no live verb declares the `altNames`
+ * field (the tier lookup completes entity names like every declared lookup),
+ * so this crafted index is where the field's read contract is held.
+ *
+ * Real-vocabulary coverage lives in two places, and neither is here: the
+ * PROTECTED contract describe below reads the shipped index for plain entity
+ * NAMES, and `safety.test.ts`'s "every declared name source resolves without
+ * constructing the store" drives the live grammar over the shipped index for
+ * entity names (`tier lookup ap` → `ds:apps`) and for `prefixes`.
+ */
 const CRAFTED_INDEX = {
   version: 2,
-  contentHash: "testhash",
-  prefixes: { ex: "https://example.com/", ds: "https://ds.canonical.com/" },
+  contentHash: CRAFTED_HASH,
+  prefixes: { ex: "https://example.com/" },
   instanceCountByType: {},
   entities: [
     { name: "ex:Button", type: "ex:Component" },
-    { name: "ds:prompt.build", type: "ds:Prompt", label: "build-a-block" },
+    { name: "ex:prompt.build", type: "ex:Prompt", label: "build-a-block" },
     {
-      name: "ds:tier.lxd",
-      type: "ds:Tier",
+      name: "ex:tier.lxd",
+      type: "ex:Tier",
       label: "LXD",
       altNames: ["apps/lxd"],
     },
-    { name: "ds:tier.core", type: "ds:Tier", label: "core" },
+    { name: "ex:tier.core", type: "ex:Tier", label: "core" },
   ],
 };
 
@@ -55,15 +78,27 @@ describe("indexCompletionEnv — multi-source names(ref)", () => {
     ]);
   });
 
-  it("prompts: ds:Prompt entities emit label || name", async () => {
+  it("index + field label: emits the label, and nothing for an entity without one", async () => {
     const env = indexCompletionEnv(projectWithIndex(CRAFTED_INDEX));
-    expect(await env.names({ from: "prompts" })).toEqual(["build-a-block"]);
+    expect(
+      await env.names({ from: "index", type: "ex:Prompt", field: "label" }),
+    ).toEqual(["build-a-block"]);
+    // `ex:Button` carries no label. The lookup that declared this field matches
+    // on the label, so standing the name in would offer a token that lookup
+    // cannot resolve.
+    expect(
+      await env.names({ from: "index", type: "ex:Component", field: "label" }),
+    ).toEqual([]);
   });
 
-  it("tiers: emit ds:name (altNames) when present, else label ?? name", async () => {
+  it("index + field altNames: emits only the alt names, never a label in their place", async () => {
     const env = indexCompletionEnv(projectWithIndex(CRAFTED_INDEX));
-    // apps/lxd from altNames (the ds:name); core from the label fallback.
-    expect(await env.names({ from: "tiers" })).toEqual(["apps/lxd", "core"]);
+    // `ex:tier.lxd` carries `apps/lxd`; `ex:tier.core` carries none, so its
+    // label `core` is NOT offered — a bespoke tier lookup filters on the
+    // declared alt-name property and would refuse it.
+    expect(
+      await env.names({ from: "index", type: "ex:Tier", field: "altNames" }),
+    ).toEqual(["apps/lxd"]);
   });
 
   it("prefixes: the index's prefixes ∪ the default display map", async () => {
@@ -92,18 +127,23 @@ describe("indexCompletionEnv — multi-source names(ref)", () => {
     expect(await env.names({ from: "skills" })).toEqual(["docx"]);
   });
 
-  it("missing sources degrade to [] (prefixes still lists the default map)", async () => {
+  it("a type nothing matches yields [] (prefixes still list the default map)", async () => {
     const env = indexCompletionEnv(
       projectWithIndex({
         version: 2,
-        contentHash: "testhash",
+        contentHash: CRAFTED_HASH,
         prefixes: {},
         instanceCountByType: {},
         entities: [{ name: "ex:Button", type: "ex:Component" }],
       }),
     );
-    expect(await env.names({ from: "prompts" })).toEqual([]);
-    expect(await env.names({ from: "tiers" })).toEqual([]);
+    expect(
+      await env.names({ from: "index", type: "ex:Prompt", field: "label" }),
+    ).toEqual([]);
+    expect(
+      await env.names({ from: "index", type: "ex:Tier", field: "altNames" }),
+    ).toEqual([]);
+    // The display map is compiled in, so it answers with no index at all.
     expect(await env.names({ from: "prefixes" })).toContain("ds");
   });
 });
@@ -112,16 +152,18 @@ describe("entity source contract (PROTECTED)", () => {
   it("reads the embedded index storelessly, filtering by type + partial", () => {
     const read = createIndexEntityReader(freshCwd());
 
-    // Abox individuals of ex:Component, sorted.
-    expect(read("ex:Component", "")).toEqual([
-      "ex:Button",
-      "ex:Card",
-      "ex:Dialog",
-    ]);
+    // An abox individual of ds:Component. Membership, not the full 100+ list:
+    // the roster moves whenever the design system does, but a design system
+    // without a button is a change a human should look at.
+    expect(read("ds:Component", "")).toContain("ds:global.component.button");
     // Tbox class.
-    expect(read("owl:Class", "")).toEqual(["ex:Component"]);
-    // Partial-prefix filter.
-    expect(read("ex:Component", "ex:B")).toEqual(["ex:Button"]);
+    expect(read("owl:Class", "")).toContain("ds:Component");
+    // Partial-prefix filter: every candidate starts with what was typed.
+    const partial = read("ds:Component", "ds:global.component.but");
+    expect(partial).toContain("ds:global.component.button");
+    for (const name of partial) {
+      expect(name.startsWith("ds:global.component.but")).toBe(true);
+    }
     // Unknown type → no matches (never throws).
     expect(read("ds:Nope", "")).toEqual([]);
   });
@@ -129,16 +171,16 @@ describe("entity source contract (PROTECTED)", () => {
   it("relies only on the frozen { name, type } minimum", () => {
     const read = createIndexEntityReader(freshCwd());
     // Every result is a bare name token (string), usable with no other field.
-    for (const name of read("ex:Component", "")) {
+    for (const name of read("ds:Component", "")) {
       expect(typeof name).toBe("string");
-      expect(name.startsWith("ex:")).toBe(true);
+      expect(name.startsWith("ds:")).toBe(true);
     }
   });
 
   it("is fast (well under the 50ms storeless budget)", () => {
     const read = createIndexEntityReader(freshCwd());
     const start = performance.now();
-    read("ex:Component", "");
+    read("ds:Component", "");
     expect(performance.now() - start).toBeLessThan(50);
   });
 });
@@ -159,7 +201,7 @@ describe("__complete entity tier wiring", () => {
             required: true,
             complete: {
               kind: "names",
-              source: { from: "index", type: "ex:Component" },
+              source: { from: "index", type: "ds:Component" },
             },
           },
         ],
@@ -185,14 +227,116 @@ describe("__complete entity tier wiring", () => {
     // index-backed reader over cwd, adapted to the resolver's EntityNameReader.
     await expect(
       runComplete(
-        ["block", "lookup", "ex:B"],
+        ["block", "lookup", "ds:global.component.but"],
         [lookupModule],
         indexCompletionEnv(freshCwd()),
       ),
-    ).resolves.toEqual(["ex:Button"]);
+    ).resolves.toContain("ds:global.component.button");
     // Without the env, the entity tier yields nothing (grammar-only).
     await expect(
-      runComplete(["block", "lookup", "ex:B"], [lookupModule]),
+      runComplete(
+        ["block", "lookup", "ds:global.component.but"],
+        [lookupModule],
+      ),
     ).resolves.toEqual([]);
   });
 });
+
+describe("readPackIndex answers the boot decision, never around it", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  // `info`, `doctor`, the MCP resource browser and native `prompts/list` all
+  // read through this. It takes the decision rather than re-deriving one, so it
+  // covers all three arms — including the one a re-derivation gets wrong.
+  it("reads the pack the decision names", () => {
+    projectWithIndex(CRAFTED_INDEX); // plants the pack under a stubbed cache
+    const index = readPackIndex({
+      kind: "pack",
+      dir: packDir(CRAFTED_HASH),
+      contentHash: CRAFTED_HASH,
+    });
+    expect(index?.contentHash).toBe(CRAFTED_HASH);
+    expect(index?.entities.map((entity) => entity.name)).toContain("ex:Button");
+  });
+
+  it("reads the embedded snapshot on the embedded arm", () => {
+    const index = readPackIndex({ kind: "embedded" });
+    expect(index?.contentHash).toBe(embeddedManifest().contentHash);
+  });
+
+  it("reads NOTHING when the store is unavailable", () => {
+    // The row that matters: a project that declared its own packs and never
+    // built them must not be listed the distribution's graph while every read
+    // of it fails STORE_UNAVAILABLE.
+    expect(readPackIndex({ kind: "unavailable", reason: "not built" })).toBe(
+      undefined,
+    );
+  });
+});
+
+describe("the storeless fast path implements the pointer half", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  // `__complete` cannot see `origins.packs` (the config evaluator is banned on
+  // this graph), so it cannot distinguish a fresh install from a configured-but-
+  // unbuilt project. It CAN see the pointer, and must not prefer the snapshot
+  // over a pointer whose pack the cache lost — that is the decision table's
+  // second row, where the two readers used to disagree.
+  it("offers no candidates when the pointed-at pack is gone", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-idx-cwd-"));
+    const cache = mkdtempSync(join(tmpdir(), "pragma-idx-cache-"));
+    vi.stubEnv("XDG_CACHE_HOME", cache);
+    const pointer = activePackPath(cwd);
+    mkdirSync(dirname(pointer), { recursive: true });
+    writeFileSync(pointer, CRAFTED_HASH); // …but no pack directory for it.
+
+    expect(createIndexEntityReader(cwd)("ds:Component", "")).toEqual([]);
+    expect(
+      await indexCompletionEnv(cwd).names({ from: "index", type: "" }),
+    ).toEqual([]);
+  });
+
+  it("still offers the snapshot's names in a configured-but-unbuilt project (the documented price)", async () => {
+    // The bounded exception `entitySource.ts` documents, pinned as it IS and
+    // not as it should be. The fast path is deliberately denied the config
+    // layer, so a `pragma.config.ts` declaring packs is invisible to it: with
+    // no pointer it cannot tell this project from a fresh install, and it
+    // answers from the embedded snapshot.
+    //
+    // Both halves are asserted against the SAME cwd, because the ASYMMETRY is
+    // the whole claim — asserting only that the snapshot answers would restate
+    // the fresh-install case the PROTECTED contract describe already covers,
+    // 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
+    // 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
+    // `origins.packs`, THIS is the test that must move, deliberately.
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-unbuilt-cwd-"));
+    vi.stubEnv(
+      "XDG_CACHE_HOME",
+      mkdtempSync(join(tmpdir(), "pragma-unbuilt-")),
+    );
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      'export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n',
+    );
+
+    const decision = resolveSources(await readConfig(cwd), cwd);
+    expect(decision).toEqual({
+      kind: "unavailable",
+      reason: "packs are configured but the store has not been built",
+    });
+    expect(readPackIndex(decision)).toBeUndefined();
+
+    expect(createIndexEntityReader(cwd)("ds:Component", "")).toContain(
+      "ds:global.component.button",
+    );
+  });
+});