@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/completion/complete.ts

@@ -0,0 +1,77 @@
+/**
+ * `runComplete` — the `__complete` resolver entry point. THE PROTOCOL:
+ *
+ * Invocation: `pragma __complete -- <word1> … <current>`
+ * - The bin fast-paths `argv[0] === "__complete"` literally, BEFORE
+ *   global-flag parsing, Commander, config reads, or first-run — the resolver
+ *   is storeless and config-free by construction. The first `--` after
+ *   `__complete` is protocol framing and is stripped by the bin (tolerated
+ *   absent). A later bare `--` belongs to the user's command line and is
+ *   honoured as end-of-options by the state machine.
+ * - Words are the raw argv after the program name, up to and INCLUDING the
+ *   word being completed — the LAST word is the partial (possibly empty).
+ *   Words after the cursor are never sent. A leading word equal to the bin
+ *   name is stripped (some shells include it).
+ * - Output: matching candidates, newline-delimited, on stdout. Zero
+ *   candidates → zero bytes. Nothing else is ever written to stdout.
+ * - Exit code: ALWAYS 0. `runComplete` never throws — any internal error
+ *   degrades to zero candidates so TAB never breaks a shell.
+ * - stderr is silent unless `PRAGMA_COMPLETE_DEBUG=1`, which logs the
+ *   classified context, "nothing" reasons (unknown noun/verb, exhausted
+ *   positionals, reserved completion kinds), dropped unsafe candidates, and
+ *   timing.
+ * - Shell floors: bash ≥ 4 (mapfile), zsh ≥ 5, fish ≥ 3. bash splits words at
+ *   `=` (COMP_WORDBREAKS), so the state machine treats `=` tokens around a
+ *   value-taking flag as transparent.
+ *
+ * The static scripts (see `emitScripts`) answer structure without exec and
+ * invoke `__complete` only for `{kind:"names"}` value contexts; the resolver
+ * is nevertheless a complete standalone answer for EVERY context, so the
+ * whole grammar is testable through this one function.
+ */
+
+import type { CapabilityModule } from "../spec/types.js";
+import { emptyNameSource } from "./entitySource.js";
+import { buildCompletionModel } from "./model.js";
+import { parseWords } from "./parse.js";
+import { completionDebug, resolveRequest } from "./resolve.js";
+import type { CompletionEnv } from "./types.js";
+
+/** The default environment: no name sources (callers wire `indexCompletionEnv`). */
+const DEFAULT_ENV: CompletionEnv = { names: emptyNameSource };
+
+/**
+ * Resolve completions for the given words against the capability modules.
+ *
+ * Builds the model, parses the words, resolves the request — wrapped in a
+ * never-throw guard: on ANY internal error the answer is zero candidates and
+ * (under `PRAGMA_COMPLETE_DEBUG=1`) a stderr note, never an exception.
+ *
+ * @param words - The command words after the program name; the last is the
+ *   partial being completed (possibly empty).
+ * @param modules - The capability modules to derive the model from.
+ * @param env - The completion environment; defaults to the empty entity seam.
+ * @returns The matching candidates, in offer order.
+ */
+export async function runComplete(
+  words: readonly string[],
+  modules: readonly CapabilityModule[],
+  env: CompletionEnv = DEFAULT_ENV,
+): Promise<string[]> {
+  const started = performance.now();
+  try {
+    const model = buildCompletionModel(modules);
+    const request = parseWords(words, model);
+    const candidates = await resolveRequest(request, model, env);
+    completionDebug(
+      `context=${request.context.kind} partial=${JSON.stringify(request.partial)} ` +
+        `candidates=${candidates.length} in ${(performance.now() - started).toFixed(1)}ms`,
+    );
+    return candidates;
+  } catch (error) {
+    completionDebug(
+      `error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return [];
+  }
+}

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

@@ -0,0 +1,173 @@
+import { describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import { completionFixture } from "../../testing/fixtures/completionFixture.js";
+import type { CapabilityModule } from "../spec/types.js";
+import { emitScripts } from "./emitScripts.js";
+
+const scripts = emitScripts([completionFixture]);
+
+describe("emitScripts — snapshots (fixture model)", () => {
+  it("renders the bash script", () => {
+    expect(scripts.bash).toMatchSnapshot();
+  });
+
+  it("renders the zsh script", () => {
+    expect(scripts.zsh).toMatchSnapshot();
+  });
+
+  it("renders the fish script", () => {
+    expect(scripts.fish).toMatchSnapshot();
+  });
+});
+
+describe("emitScripts — static tier contract", () => {
+  it("inlines enum values in every shell (zero exec for structure)", () => {
+    for (const shell of ["bash", "zsh", "fish"] as const) {
+      expect(scripts[shell]).toContain("anatomy full summary");
+      expect(scripts[shell]).toContain("community core");
+    }
+  });
+
+  it("delegates only entity contexts to __complete", () => {
+    expect(scripts.bash).toContain(
+      'mapfile -t COMPREPLY < <("pragma" __complete --',
+    );
+    expect(scripts.zsh).toContain("${(f)$(pragma __complete --");
+    expect(scripts.fish).toContain(
+      '-a "(pragma __complete -- (__pragma_words) 2>/dev/null)"',
+    );
+  });
+
+  it("completes files natively, never through the resolver", () => {
+    expect(scripts.bash).toContain('compgen -f -- "$cur"');
+    expect(scripts.zsh).toContain("_files");
+    expect(scripts.fish).toContain("-l out -rF");
+  });
+
+  it("offers mutation flags for mutating verbs", () => {
+    expect(scripts.bash).toContain("--dry-run --undo --yes");
+    expect(scripts.zsh).toContain("--dry-run --undo --yes");
+    expect(scripts.fish).toContain("-l dry-run");
+  });
+
+  it("offers --version at the root only", () => {
+    const bashRoot = scripts.bash
+      .split("\n")
+      .filter((line) => line.includes("--version"));
+    expect(bashRoot.length).toBe(1);
+    expect(scripts.fish).toContain(`-n "__pragma_at ''" -l version`);
+  });
+
+  it("hidden verbs never reach a script", () => {
+    for (const shell of ["bash", "zsh", "fish"] as const) {
+      expect(scripts[shell]).not.toContain("probe");
+    }
+  });
+
+  it("documents the shell floors in the headers", () => {
+    expect(scripts.bash).toContain("bash >= 4");
+    expect(scripts.zsh).toContain("zsh >= 5");
+    expect(scripts.fish).toContain("fish >= 3");
+  });
+});
+
+describe("emitScripts — minChars gate + family opt-out", () => {
+  it("gates only the name exec, never the inlined enum arms", () => {
+    // The gate lives inside the shared _dynamic (bash/zsh) and each fish name
+    // rule; enum values stay inlined and complete on bare TAB. (Substrings drop
+    // the leading `$` to keep the parameter expansion out of a JS string.)
+    expect(scripts.bash).toContain("#cur} -ge 2 ] || return 0");
+    expect(scripts.zsh).toContain("#cur} >= 2 )) || return 0");
+    expect(scripts.fish).toContain("__pragma_minchars 2");
+    expect(scripts.bash).toContain('compgen -W "anatomy full summary"');
+    expect(scripts.zsh).toContain("compadd -- anatomy full summary");
+  });
+
+  it("bakes a custom minChars and drops the gate at 0", () => {
+    expect(emitScripts([completionFixture], { minChars: 3 }).bash).toContain(
+      "#cur} -ge 3 ] || return 0",
+    );
+    const off = emitScripts([completionFixture], { minChars: 0 });
+    expect(off.bash).not.toContain("-ge");
+    // (`#cur} >=` avoids the `zsh >= 5` shell-floor comment in the header.)
+    expect(off.zsh).not.toContain("#cur} >=");
+    expect(off.fish).not.toContain("__pragma_minchars");
+  });
+
+  it("disabledFamilies drops a noun's name completion (config opt-out)", () => {
+    const off = emitScripts([completionFixture], {
+      disabledFamilies: ["block"],
+    });
+    // block's only-positional name verb loses its exec entirely…
+    expect(scripts.bash).toContain("block/diff)");
+    expect(off.bash).not.toContain("block/diff)");
+    expect(off.fish).not.toContain("__pragma_at block diff");
+    // …while a non-disabled family (standard) still execs the resolver.
+    expect(off.bash).toContain("standard/)");
+    expect(off.bash).toContain("_pragma_dynamic");
+  });
+});
+
+describe("emitScripts — binName parameterization (PR8 seam)", () => {
+  it("defaults to pragma", () => {
+    expect(scripts.bash).toContain("complete -F _pragma pragma");
+    expect(scripts.zsh.startsWith("#compdef pragma")).toBe(true);
+  });
+
+  it("targets a custom bin everywhere", () => {
+    const renamed = emitScripts([completionFixture], { binName: "widget9" });
+    for (const shell of ["bash", "zsh", "fish"] as const) {
+      expect(renamed[shell]).not.toContain("pragma");
+      expect(renamed[shell]).toContain("widget9");
+    }
+    expect(renamed.bash).toContain("complete -F _widget9 widget9");
+    expect(renamed.fish).toContain("__widget9_at");
+  });
+
+  it("throws on a bin name outside the allowlist", () => {
+    expect(() =>
+      emitScripts([completionFixture], { binName: "bad name" }),
+    ).toThrow(/unsafe token/);
+    expect(() =>
+      emitScripts([completionFixture], { binName: "x$(y)" }),
+    ).toThrow(/unsafe token/);
+  });
+});
+
+describe("emitScripts — live capabilities", () => {
+  const live = emitScripts(capabilities);
+
+  it("emits the live nouns and verbs", () => {
+    for (const shell of ["bash", "zsh", "fish"] as const) {
+      expect(live[shell]).toContain("config");
+      expect(live[shell]).toContain("info");
+      expect(live[shell]).toContain("show");
+      expect(live[shell]).toContain("mcp");
+    }
+  });
+});
+
+describe("emitScripts — adversarial emit-time throw (PROTECTED)", () => {
+  it("refuses to emit any script for a hostile grammar", () => {
+    const hostile = {
+      name: "hostile",
+      verbs: [
+        {
+          path: ["block", 'x"; rm -rf ~'],
+          summary: "x",
+          params: [],
+          output: {
+            formatters: { plain: () => "", llm: () => "", json: () => "" },
+          },
+          capability: {
+            needsStore: false,
+            mutates: false,
+            mcp: { expose: false, reason: "t" },
+          },
+          run: async () => null,
+        },
+      ],
+    } as unknown as CapabilityModule;
+    expect(() => emitScripts([hostile])).toThrow(/unsafe token/);
+  });
+});

package/src/kernel/completion/emitScripts.ts

@@ -0,0 +1,122 @@
+/**
+ * Emit the static shell-completion scripts from the grammar.
+ *
+ * Builds the completion model from the capability modules (the same
+ * 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
+ * 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;
+ * `minChars` and `disabledFamilies` are read from `completion` config by setup.
+ *
+ * `minChars` (default {@link DEFAULT_MIN_CHARS}) is baked into the scripts to
+ * gate the `__complete` exec for NAME contexts only — structure and enum values
+ * stay inlined and complete on bare TAB with zero exec. `disabledFamilies`
+ * scrubs a noun's name sources to `none` (the config-level opt-out), so its
+ * name arms drop out of every script; the pack-grammar opt-out (`enabled:false`)
+ * lands earlier, in the model.
+ *
+ * @throws Emitting THROWS on any name outside the safety allowlist (the
+ *   model build asserts, and every template re-asserts what it inlines) —
+ *   `setup completions` fails loudly rather than installing a hostile token.
+ */
+
+import { BIN_NAME } from "../../constants.js";
+import type { CapabilityModule } from "../spec/types.js";
+import { assertSafeToken, buildCompletionModel } from "./model.js";
+import { bashScript } from "./templates/bash.js";
+import { fishScript } from "./templates/fish.js";
+import { zshScript } from "./templates/zsh.js";
+import type {
+  CompletionModel,
+  CompletionSource,
+  Shell,
+  VerbEntry,
+} from "./types.js";
+
+/** The default `minChars` gate baked into the generated scripts. */
+export const DEFAULT_MIN_CHARS = 2;
+
+/** Options for {@link emitScripts}. */
+export interface EmitScriptsOptions {
+  /** The binary to complete; defaults to {@link BIN_NAME} (`pragma`). */
+  readonly binName?: string;
+  /** Min chars before a name source execs `__complete` (default 2). */
+  readonly minChars?: number;
+  /** Noun families whose name completion is disabled (config opt-out). */
+  readonly disabledFamilies?: readonly string[];
+}
+
+/** Replace a name source with `none` (the family-level opt-out). */
+function scrubSource(source: CompletionSource): CompletionSource {
+  return source.kind === "names" ? { kind: "none" } : source;
+}
+
+/** Scrub every name source of a verb entry to `none`. */
+function scrubVerb(verb: VerbEntry): VerbEntry {
+  return {
+    ...verb,
+    flags: verb.flags.map((flag) => ({
+      ...flag,
+      source: scrubSource(flag.source),
+    })),
+    positionals: verb.positionals.map((positional) => ({
+      ...positional,
+      source: scrubSource(positional.source),
+    })),
+  };
+}
+
+/**
+ * Drop name completion for the disabled noun families (config opt-out): every
+ * name source under a disabled noun becomes `none`, so no template emits its
+ * exec. A pure structural transform on the model — the templates stay unaware.
+ */
+function applyDisabledFamilies(
+  model: CompletionModel,
+  disabled: ReadonlySet<string>,
+): CompletionModel {
+  if (disabled.size === 0) return model;
+  return {
+    ...model,
+    nouns: model.nouns.map((noun) =>
+      disabled.has(noun.noun)
+        ? {
+            ...noun,
+            ...(noun.selfVerb ? { selfVerb: scrubVerb(noun.selfVerb) } : {}),
+            verbs: noun.verbs.map(scrubVerb),
+          }
+        : noun,
+    ),
+  };
+}
+
+/**
+ * Emit the completion scripts for every supported shell.
+ *
+ * @param modules - The capability modules to derive completions from.
+ * @param options - Bin name, `minChars` gate, and disabled name families.
+ * @returns A map of shell to its completion script.
+ * @throws Error when any inlinable token fails the safety allowlist.
+ */
+export function emitScripts(
+  modules: readonly CapabilityModule[],
+  options: EmitScriptsOptions = {},
+): Record<Shell, string> {
+  const binName = options.binName ?? BIN_NAME;
+  assertSafeToken(binName, "bin name");
+  const minChars = options.minChars ?? DEFAULT_MIN_CHARS;
+  const model = applyDisabledFamilies(
+    buildCompletionModel(modules),
+    new Set(options.disabledFamilies ?? []),
+  );
+  return {
+    bash: bashScript(model, binName, minChars),
+    zsh: zshScript(model, binName, minChars),
+    fish: fishScript(model, binName, minChars),
+  };
+}

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

@@ -0,0 +1,198 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { CapabilityModule, VerbSpec } from "../spec/types.js";
+import { runComplete } from "./complete.js";
+import { createIndexEntityReader, indexCompletionEnv } from "./entitySource.js";
+
+/** A fresh cwd with no lock → 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. */
+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");
+  mkdirSync(packDir, { recursive: true });
+  writeFileSync(join(packDir, "index.json"), JSON.stringify(index));
+  return cwd;
+}
+
+/** A crafted index exercising the index / prompts / tiers / prefixes sources. */
+const CRAFTED_INDEX = {
+  version: 2,
+  contentHash: "testhash",
+  prefixes: { ex: "https://example.com/", ds: "https://ds.canonical.com/" },
+  instanceCountByType: {},
+  entities: [
+    { name: "ex:Button", type: "ex:Component" },
+    { name: "ds:prompt.build", type: "ds:Prompt", label: "build-a-block" },
+    {
+      name: "ds:tier.lxd",
+      type: "ds:Tier",
+      label: "LXD",
+      altNames: ["apps/lxd"],
+    },
+    { name: "ds:tier.core", type: "ds:Tier", label: "core" },
+  ],
+};
+
+describe("indexCompletionEnv — multi-source names(ref)", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("index: entity names of a prefixed type", async () => {
+    const env = indexCompletionEnv(projectWithIndex(CRAFTED_INDEX));
+    expect(await env.names({ from: "index", type: "ex:Component" })).toEqual([
+      "ex:Button",
+    ]);
+  });
+
+  it("prompts: ds:Prompt entities emit label || name", async () => {
+    const env = indexCompletionEnv(projectWithIndex(CRAFTED_INDEX));
+    expect(await env.names({ from: "prompts" })).toEqual(["build-a-block"]);
+  });
+
+  it("tiers: emit ds:name (altNames) when present, else label ?? name", 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"]);
+  });
+
+  it("prefixes: the index's prefixes ∪ the default display map", async () => {
+    const env = indexCompletionEnv(projectWithIndex(CRAFTED_INDEX));
+    const prefixes = await env.names({ from: "prefixes" });
+    expect(prefixes).toContain("ex"); // from the index
+    expect(prefixes).toContain("ds"); // default map
+    expect(prefixes).toContain("rdfs"); // default map
+  });
+
+  it("skills: names from the project skills root, walked once (memoized)", async () => {
+    const cwd = projectWithIndex(CRAFTED_INDEX);
+    vi.stubEnv(
+      "XDG_DATA_HOME",
+      mkdtempSync(join(tmpdir(), "pragma-idx-data-")),
+    );
+    const skillDir = join(cwd, ".pragma", "skills", "docx");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      "---\nname: docx\ndescription: Word docs.\n---\n",
+    );
+    const env = indexCompletionEnv(cwd);
+    expect(await env.names({ from: "skills" })).toEqual(["docx"]);
+    // A second read returns the same list (one filesystem walk per env).
+    expect(await env.names({ from: "skills" })).toEqual(["docx"]);
+  });
+
+  it("missing sources degrade to [] (prefixes still lists the default map)", async () => {
+    const env = indexCompletionEnv(
+      projectWithIndex({
+        version: 2,
+        contentHash: "testhash",
+        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: "prefixes" })).toContain("ds");
+  });
+});
+
+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",
+    ]);
+    // Tbox class.
+    expect(read("owl:Class", "")).toEqual(["ex:Component"]);
+    // Partial-prefix filter.
+    expect(read("ex:Component", "ex:B")).toEqual(["ex:Button"]);
+    // Unknown type → no matches (never throws).
+    expect(read("ds:Nope", "")).toEqual([]);
+  });
+
+  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", "")) {
+      expect(typeof name).toBe("string");
+      expect(name.startsWith("ex:")).toBe(true);
+    }
+  });
+
+  it("is fast (well under the 50ms storeless budget)", () => {
+    const read = createIndexEntityReader(freshCwd());
+    const start = performance.now();
+    read("ex:Component", "");
+    expect(performance.now() - start).toBeLessThan(50);
+  });
+});
+
+describe("__complete entity tier wiring", () => {
+  const lookupModule: CapabilityModule = {
+    name: "fixture-block",
+    verbs: [
+      {
+        path: ["block", "lookup"],
+        summary: "Look up a block.",
+        params: [
+          {
+            kind: "string",
+            name: "name",
+            doc: "The block name.",
+            positional: true,
+            required: true,
+            complete: {
+              kind: "names",
+              source: { from: "index", type: "ex:Component" },
+            },
+          },
+        ],
+        output: {
+          formatters: {
+            plain: String,
+            llm: String,
+            json: (d) => JSON.stringify(d),
+          },
+        },
+        capability: {
+          needsStore: true,
+          mutates: false,
+          mcp: { expose: false, reason: "test" },
+        },
+        run: async () => ({}),
+      } as VerbSpec,
+    ],
+  };
+
+  it("resolves a positional entity param through the wired env", async () => {
+    // The bin fast path and the __complete verb wire this exact env: the
+    // index-backed reader over cwd, adapted to the resolver's EntityNameReader.
+    await expect(
+      runComplete(
+        ["block", "lookup", "ex:B"],
+        [lookupModule],
+        indexCompletionEnv(freshCwd()),
+      ),
+    ).resolves.toEqual(["ex:Button"]);
+    // Without the env, the entity tier yields nothing (grammar-only).
+    await expect(
+      runComplete(["block", "lookup", "ex:B"], [lookupModule]),
+    ).resolves.toEqual([]);
+  });
+});