@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/completion/model.ts

@@ -25,8 +25,13 @@
  */
 
 import { DETAIL_LEVELS, OUTPUT_FORMATS } from "../../constants.js";
-import { kebabCase, verbLabel } from "../spec/emitSurface.js";
-import type { CapabilityModule, ParamSpec, VerbSpec } from "../spec/types.js";
+import { kebabCase, verbLabel } from "../spec/index.js";
+import type {
+  CapabilityModule,
+  CompletionChildSpec,
+  ParamSpec,
+  VerbSpec,
+} from "../spec/types.js";
 import type {
   CompletionModel,
   CompletionSource,
@@ -40,6 +45,17 @@ import type {
  * The allowlist every inlined completion token must match: an alphanumeric
  * head, then word/URI-ish characters. No whitespace, quotes, `$`, backticks,
  * semicolons, or globs — nothing a shell could expand or split.
+ *
+ * KNOWN GAP, deliberately not closed: it admits shell RESERVED WORDS — `esac`,
+ * `in`, `do`, `done`, `fi`. A noun so named emits a `case` arm bash and zsh both
+ * refuse to parse, so `_pragma` is never defined and the user gets NO completion
+ * at all rather than a wrong candidate (`fish -n` does not catch it either). The
+ * gap is owned by the syntax gates, not by this regex: `shellDrive.test.ts`
+ * runs `bash -n`/`zsh -n` over the emitted scripts, so the day a live noun is
+ * named `done` the build fails loudly and names the file. A denylist here would
+ * be new production code guarding a case nothing in the tree exhibits — and a
+ * partial one (reserved words differ across families and versions) reads as
+ * more protection than it gives.
  */
 export const SAFE_TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9@/:._+-]*$/;
 
@@ -74,6 +90,13 @@ const GLOBAL_FLAGS: readonly FlagEntry[] = [
     repeatable: false,
     source: { kind: "values", values: DETAIL_LEVELS },
   },
+  {
+    flag: "--no-headers",
+    takesValue: false,
+    repeatable: false,
+    source: none(),
+  },
+  { flag: "--quiet", takesValue: false, repeatable: false, source: none() },
   { flag: "--help", takesValue: false, repeatable: false, source: none() },
   {
     flag: "--version",
@@ -170,7 +193,12 @@ function toVerbEntry(verb: VerbSpec): VerbEntry {
       flags.push({
         flag: `--${name}`,
         takesValue: param.kind !== "boolean",
-        repeatable: param.kind === "string[]",
+        // Two grammars accumulate, so two shapes are repeatable: a `string[]`
+        // flag (`--tag a --tag b`) and any `string`/`enum` param the spec
+        // marks `repeatable` — the form compiled packs give every declared
+        // filter. Reading only the kind de-offered a filter after its first
+        // use, hiding the repetition the parser had just started honouring.
+        repeatable: param.kind === "string[]" || param.repeatable === true,
         source,
       });
     }
@@ -179,18 +207,73 @@ function toVerbEntry(verb: VerbSpec): VerbEntry {
   return { label, mutates: verb.capability.mutates, flags, positionals };
 }
 
-/** An empty self-verb entry (used for the injected `mcp` noun). */
-function bareSelfVerb(label: string): VerbEntry {
-  return { label, mutates: false, flags: [], positionals: [] };
+/**
+ * Convert one module-declared completion node (a mounted subtree's static
+ * data) into a verb entry, asserting every inlinable token's safety exactly
+ * as spec-derived entries are asserted. `mutates` is the owning verb's
+ * mutability, applied only to the LEAVES (see the namespace note below).
+ */
+function toMountedEntry(
+  spec: CompletionChildSpec,
+  mutates: boolean,
+  where: string,
+): VerbEntry {
+  assertSafeToken(spec.label, `${where} label`);
+  const flags: FlagEntry[] = spec.flags.map((flag) => {
+    const name = flag.flag.replace(/^--?/, "");
+    assertSafeToken(name, `${where} flag "${flag.flag}"`);
+    const source: CompletionSource = flag.values
+      ? { kind: "values", values: flag.values }
+      : none();
+    assertSafeSource(source, `${where} flag "${flag.flag}"`);
+    return {
+      flag: flag.flag,
+      takesValue: flag.takesValue,
+      repeatable: false,
+      source,
+    };
+  });
+  const positionals: PositionalEntry[] = spec.positionals.map((positional) => {
+    const source: CompletionSource = positional.values
+      ? { kind: "values", values: positional.values }
+      : positional.files
+        ? { kind: "files" }
+        : none();
+    assertSafeSource(source, `${where} positional "${positional.name}"`);
+    return {
+      name: positional.name,
+      required: positional.required,
+      variadic: false,
+      source,
+    };
+  });
+  const children =
+    spec.children && spec.children.length > 0
+      ? spec.children.map((child) =>
+          toMountedEntry(child, mutates, `${where}/${child.label}`),
+        )
+      : undefined;
+  return {
+    label: spec.label,
+    // A node with children is a NAMESPACE, not a runnable command:
+    // `registerGeneratorCommands` adds the host mutation trio to runnable
+    // LEAVES only, so a mutating namespace would offer `--dry-run`/`--undo`/
+    // `--yes` BEFORE the framework segment — an ordering the CLI rejects as
+    // an unknown option. The verb's mutability descends to the leaves.
+    mutates: children ? false : mutates,
+    flags,
+    positionals,
+    ...(children ? { children } : {}),
+  };
 }
 
 /**
  * Derive the completion model from the capability modules.
  *
  * Hidden verbs are excluded (matching `emitSurface` and `buildProgram`).
- * The bin-served `mcp` entry is injected so `pragma mc<Tab>` completes it,
- * matching the root help.
- * TODO(spec): drop the injection when `mcp` lands as a real (non-hidden) spec.
+ * Every noun in the model comes from a declared verb — `mcp` used to be
+ * injected here because the bin served it without a spec, and it now declares
+ * `mcp serve` like any other pair.
  *
  * @param modules - The capability modules.
  * @returns The completion model, nouns and verbs sorted.
@@ -214,12 +297,24 @@ export function buildCompletionModel(
   };
 
   for (const module of modules) {
+    // A module-owned mount REPLACES its verbs' completion surface: the flags
+    // the mounted tree actually registers (e.g. a default-on confirm's
+    // `--no-` form), the segment positionals, and the child walk — declared
+    // as static data by the module, converted and safety-asserted here.
+    const mountedChildren = module.cliProjection?.completionChildren();
     for (const verb of module.verbs) {
       if (verb.hidden) continue;
       const noun = verb.path[0];
       assertSafeToken(noun, `noun "${noun}"`);
       const bucket = bucketFor(noun);
-      const entry = toVerbEntry(verb);
+      const mountedSpec = mountedChildren?.[verbLabel(verb.path)];
+      const entry = mountedSpec
+        ? toMountedEntry(
+            mountedSpec,
+            verb.capability.mutates,
+            `mounted "${verb.path.join(" ")}"`,
+          )
+        : toVerbEntry(verb);
       if (verb.path[1] === undefined) {
         bucket.selfVerb = entry;
       } else {
@@ -228,10 +323,6 @@ export function buildCompletionModel(
     }
   }
 
-  if (!byNoun.has("mcp")) {
-    byNoun.set("mcp", { selfVerb: bareSelfVerb("mcp"), verbs: [] });
-  }
-
   const nouns: NounEntry[] = [...byNoun.entries()]
     .map(([noun, bucket]) => ({
       noun,

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

@@ -86,6 +86,8 @@ describe("parseWords — flag names (PROTECTED)", () => {
       "--format",
       "--verbose",
       "--detail",
+      "--no-headers",
+      "--quiet",
       "--help",
       "--version",
     ]);
@@ -107,6 +109,8 @@ describe("parseWords — flag names (PROTECTED)", () => {
       "--format",
       "--verbose",
       "--detail",
+      "--no-headers",
+      "--quiet",
       "--help",
     ]);
   });
@@ -326,11 +330,4 @@ describe("parseWords — self-verb nouns (PROTECTED)", () => {
       reason: "positionals exhausted",
     });
   });
-
-  it("the injected mcp noun completes but offers nothing after", () => {
-    expect(parse(["mcp", ""]).context).toEqual({
-      kind: "nothing",
-      reason: "positionals exhausted",
-    });
-  });
 });

package/src/kernel/completion/parse.ts

@@ -137,6 +137,21 @@ function scanCommandWord(
     return;
   }
 
+  // A verb with segment children (a mounted subtree): the word resolves
+  // against the children BEFORE positional counting — a match descends, so
+  // deeper flags/positionals are the child's own; a non-match is terminal.
+  const resolved = knownVerb(state);
+  if (resolved?.children && resolved.children.length > 0) {
+    const child = resolved.children.find((entry) => entry.label === word);
+    if (child) {
+      state.verb = child;
+      state.positionalsSeen = 0;
+      return;
+    }
+    state.verb = "unknown";
+    return;
+  }
+
   state.positionalsSeen += 1;
 }
 

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

@@ -42,7 +42,6 @@ describe("resolveRequest — structural contexts (PROTECTED)", () => {
     await expect(complete(["blo"])).resolves.toEqual(["block"]);
     await expect(complete([""])).resolves.toEqual([
       "block",
-      "mcp",
       "standard",
       "status",
     ]);

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

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createStore } from "@canonical/ke";
 import { describe, expect, it, vi } from "vitest";
@@ -207,6 +207,8 @@ function staticImportGraph(
 }
 
 const here = dirname(fileURLToPath(import.meta.url));
+/** The package root, so a failure names `src/…` instead of an absolute path. */
+const pkgRoot = resolve(here, "../../..");
 const has = (graph: Set<string>, fragment: string): boolean =>
   [...graph].some((file) => file.includes(fragment));
 
@@ -224,16 +226,25 @@ describe("storeless guarantee (PROTECTED)", () => {
       // Runtime boot (bootRuntime) — never on the completion path.
       expect(has(graph, "kernel/runtime/boot.ts")).toBe(false);
       // The config LAYER (reader, evaluator, paths, schema) — storeless means
-      // no read. PR2's pure-leaf `config/types.ts` (the ConfigLayers type,
-      // imported type-only via VerbSpec.run's PragmaRuntime and erased at
-      // runtime) is the lone tolerated seam — as spec/types.ts and
-      // runtime/types.ts already sit in this graph as type-only.
-      const configModules = [...graph].filter(
-        (file) =>
-          file.includes("kernel/config/") &&
-          !file.endsWith("kernel/config/types.ts"),
-      );
-      expect(configModules).toEqual([]);
+      // no read. Its tolerated seams are POSITIVE-LISTED, not filtered out by a
+      // path fragment: the distribution config sits at the package root, so a
+      // `kernel/config/`-shaped filter would not see it and this guard would
+      // keep passing after it stopped being true.
+      //  - `kernel/config/types.ts` — the ConfigLayers type, imported type-only
+      //    via VerbSpec.run's PragmaRuntime and erased at runtime, as
+      //    spec/types.ts and runtime/types.ts already are in this graph.
+      //  - `pragma.conf.ts` — the distribution config, statically imported by
+      //    `constants.ts` (identity), `render/prefixes.ts` (the domain
+      //    namespaces) and `kernel/vocabulary.ts` (the domain terms). Safe only
+      //    while it stays inert data; `capabilities/lazy.test.ts` pins that.
+      const configModules = [...graph]
+        .filter((file) => /config|\.conf\./.test(file))
+        .map((file) => relative(pkgRoot, file))
+        .sort();
+      expect(configModules).toEqual([
+        "pragma.conf.ts",
+        "src/kernel/config/types.ts",
+      ]);
       // zod stays off the fast path (validate.ts is the registration seam).
       expect(has(graph, "kernel/spec/validate.ts")).toBe(false);
       // No store/graph modules, present or future.
@@ -266,7 +277,7 @@ describe("storeless guarantee (PROTECTED)", () => {
               required: true,
               complete: {
                 kind: "names",
-                source: { from: "index", type: "ex:Component" },
+                source: { from: "index", type: "ds:Component" },
               },
             },
           ],
@@ -286,87 +297,130 @@ describe("storeless guarantee (PROTECTED)", () => {
         } as VerbSpec,
       ],
     };
-    // Fresh cwd → no lock → the reader falls back to the embedded pack index.
+    // Fresh cwd → no pointer → the reader falls back to the embedded index.
     const cwd = mkdtempSync(join(tmpdir(), "pragma-storespy-"));
     const matches = await runComplete(
-      ["block", "lookup", "ex:B"],
+      ["block", "lookup", "ds:global.component.but"],
       [lookupModule],
       indexCompletionEnv(cwd),
     );
     // It DID read the index (a real name came back)…
-    expect(matches).toEqual(["ex:Button"]);
+    expect(matches).toContain("ds:global.component.button");
     // …and it did so without ever constructing the store.
     expect(vi.mocked(createStore)).not.toHaveBeenCalled();
   });
 
-  it("the non-index name sources resolve without constructing the store", async () => {
-    // skills (filesystem), prompts/tiers (index filter), prefixes (index ∪
-    // default map) — every family completes storelessly against the live
-    // capabilities. A fresh cwd → no lock → the embedded fallback index.
+  it("every declared name source resolves without constructing the store", async () => {
+    // skills (filesystem), prefixes (index ∪ default map) and the index's own
+    // `label`/`altNames` fields — every family completes storelessly against
+    // the live capabilities. A fresh cwd → no pointer → the embedded index.
     const cwd = mkdtempSync(join(tmpdir(), "pragma-storeless-src-"));
     const env = indexCompletionEnv(cwd);
 
     // prefixes: `ds` is in the default display map, so it comes back for `d`.
     await expect(
-      runComplete(["ontology", "show", "d"], capabilities, env),
+      runComplete(["ontology", "lookup", "d"], capabilities, env),
     ).resolves.toContain("ds");
 
-    // skills / prompts / tiers: no data here, but the point is they never boot
-    // the store — an empty list is the correct storeless answer.
+    // index (derived, no field): the tier lookup is a declared pack lookup
+    // (L-OPEN-9), so its candidates are the index's entity NAMES for the
+    // declared type — prefixed IRIs, like every other declared lookup's
+    // (D9-A). `ds:apps` is a real `ds:Tier` subject in the embedded index,
+    // and the lookup resolves a prefixed-IRI candidate directly.
+    await expect(
+      runComplete(["tier", "lookup", "ap"], capabilities, env),
+    ).resolves.toContain("ds:apps");
+
+    // skills (no skills root here) and prompt labels (this graph carries no
+    // prompt entities) have nothing to offer, and the honest storeless answer
+    // is an empty list rather than a store boot.
     for (const words of [
       ["skill", "lookup", "do"],
       ["prompt", "lookup", "bu"],
-      ["tier", "lookup", "ap"],
     ]) {
-      await expect(
-        runComplete(words, capabilities, env),
-      ).resolves.toBeInstanceOf(Array);
+      await expect(runComplete(words, capabilities, env)).resolves.toEqual([]);
     }
 
     expect(vi.mocked(createStore)).not.toHaveBeenCalled();
   });
 
   it("the spawned __complete fast path answers without touching any state", () => {
-    // The perf globalSetup guarantees dist/pragma exists.
-    const binary = fileURLToPath(
-      new URL("../../../dist/pragma", import.meta.url),
+    // The perf globalSetup guarantees the emitted `dist/` exists.
+    // A FRESH INSTALL, reproduced: nothing is inherited from this process's
+    // environment, the cwd holds no config, and $HOME plus all three XDG roots
+    // are empty temps. Anything the entry answers here it answered from
+    // itself. (The suite before this inherited `...process.env`, so it could
+    // not tell a compiled-in answer from an ambient one.)
+    const entry = fileURLToPath(
+      new URL("../../../dist/src/bin.js", import.meta.url),
     );
+    const home = mkdtempSync(join(tmpdir(), "pragma-storeless-home-"));
     const xdgConfig = mkdtempSync(join(tmpdir(), "pragma-storeless-cfg-"));
     const xdgState = mkdtempSync(join(tmpdir(), "pragma-storeless-state-"));
     const xdgCache = mkdtempSync(join(tmpdir(), "pragma-storeless-cache-"));
+    const emptyCwd = mkdtempSync(join(tmpdir(), "pragma-storeless-cwd-"));
+    const env = {
+      HOME: home,
+      XDG_CONFIG_HOME: xdgConfig,
+      XDG_STATE_HOME: xdgState,
+      XDG_CACHE_HOME: xdgCache,
+    };
 
-    const result = spawnSync(binary, ["__complete", "--", "co"], {
-      encoding: "utf-8",
-      env: {
-        ...process.env,
-        XDG_CONFIG_HOME: xdgConfig,
-        XDG_STATE_HOME: xdgState,
-        XDG_CACHE_HOME: xdgCache,
+    const nouns = spawnSync(
+      process.execPath,
+      [entry, "__complete", "--", "co"],
+      {
+        encoding: "utf-8",
+        cwd: emptyCwd,
+        env,
       },
-    });
+    );
+    expect(nouns.status).toBe(0);
+    expect(nouns.stdout).toBe("colophon\nconcept\nconfig\n");
+    expect(nouns.stderr).toBe("");
+
+    // The headline guarantee of the embedded pack: a user who has installed
+    // the shipped entry and nothing else gets ENTITY candidates on the first TAB.
+    // Every other pin on the embedded index runs in-process, where an emit
+    // change that made `pack.index.generated.ts` unreachable FROM THE SHIPPED
+    // ENTRY would leave the whole suite green.
+    const entities = spawnSync(
+      process.execPath,
+      [entry, "__complete", "--", "block", "lookup", "ds:global.component.but"],
+      { encoding: "utf-8", cwd: emptyCwd, env },
+    );
+    expect(entities.status).toBe(0);
+    expect(entities.stderr).toBe("");
+    expect(entities.stdout.split("\n").at(0)).toBe(
+      "ds:global.component.button",
+    );
 
-    expect(result.status).toBe(0);
-    expect(result.stdout).toBe("colophon\nconfig\n");
-    expect(result.stderr).toBe("");
     // Storeless and config-free: no first-run marker, no config cache, no
-    // store artifacts — the fast path must leave the environment untouched.
+    // store artifacts — the fast path must leave the environment untouched,
+    // after BOTH kinds of context.
+    expect(readdirSync(home)).toEqual([]);
     expect(readdirSync(xdgConfig)).toEqual([]);
     expect(readdirSync(xdgState)).toEqual([]);
     expect(readdirSync(xdgCache)).toEqual([]);
+    expect(readdirSync(emptyCwd)).toEqual([]);
   });
 
   it("the spawned fast path emits zero bytes for zero candidates, exit 0", () => {
-    const binary = fileURLToPath(
-      new URL("../../../dist/pragma", import.meta.url),
+    const entry = fileURLToPath(
+      new URL("../../../dist/src/bin.js", import.meta.url),
     );
-    const result = spawnSync(binary, ["__complete", "--", "bogus", ""], {
-      encoding: "utf-8",
-      env: {
-        ...process.env,
-        XDG_CONFIG_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-cfg-")),
-        XDG_STATE_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-state-")),
+    const result = spawnSync(
+      process.execPath,
+      [entry, "__complete", "--", "bogus", ""],
+      {
+        encoding: "utf-8",
+        env: {
+          ...process.env,
+          XDG_CONFIG_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-cfg-")),
+          XDG_STATE_HOME: mkdtempSync(join(tmpdir(), "pragma-zb-state-")),
+        },
       },
-    });
+    );
     expect(result.status).toBe(0);
     expect(result.stdout).toBe("");
     expect(result.stderr).toBe("");