@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -0,0 +1,340 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`emitScripts — snapshots (fixture model) > renders the bash script 1`] = `
+"# pragma bash completion (static tier) — generated by \`pragma setup completions\`. Do not edit.
+# Structure (nouns, verbs, flags, enum values) is inlined and never execs;
+# entity arguments call \`pragma __complete\` (storeless, never-throw);
+# file arguments use native completion. Requires bash >= 4 (mapfile).
+_pragma_dynamic() {
+  [ \${#cur} -ge 2 ] || return 0
+  mapfile -t COMPREPLY < <("pragma" __complete -- "\${COMP_WORDS[@]:1:COMP_CWORD-1}" "$cur" 2>/dev/null)
+}
+_pragma_pos() {
+  local skip="$1" vflags=" $2 " i w
+  POS=0
+  for ((i = 1; i < COMP_CWORD; i++)); do
+    w="\${COMP_WORDS[i]}"
+    case "$w" in
+      -*) case "$vflags" in *" $w "*) ((i++)) ;; esac ;;
+      *) if [ "$skip" -gt 0 ]; then skip=$((skip - 1)); else POS=$((POS + 1)); fi ;;
+    esac
+  done
+}
+_pragma() {
+  local cur prev noun verb i w POS
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  # Normalize the COMP_WORDBREAKS '=' split so a --flag=value context routes
+  # as a flag value (mirrors parse.ts). The default breaks split
+  # \`--flag=val\` into \`--flag\` \`=\` \`val\`; a custom COMP_WORDBREAKS may keep
+  # \`--flag=val\` whole. Either way, recover $prev=flag and $cur=value.
+  if [[ "$cur" == "=" ]]; then
+    cur=""
+  elif [[ "$prev" == "=" ]]; then
+    prev="\${COMP_WORDS[COMP_CWORD-2]}"
+  elif [[ "$cur" == --*=* ]]; then
+    prev="\${cur%%=*}"
+    cur="\${cur#*=}"
+  fi
+  noun="" verb="" POS=0
+  for ((i = 1; i < COMP_CWORD; i++)); do
+    w="\${COMP_WORDS[i]}"
+    case "$w" in
+      --format|--detail) ((i++)) ;;
+      -*) ;;
+      *)
+        if [ -z "$noun" ]; then noun="$w"
+        elif [ -z "$verb" ]; then verb="$w"
+        fi
+        ;;
+    esac
+  done
+
+  # flag values (verb-scoped, then global)
+  case "$noun/$verb/$prev" in
+    block/get/--view) COMPREPLY=($(compgen -W "anatomy full summary" -- "$cur")); return ;;
+    block/get/--out) COMPREPLY=($(compgen -f -- "$cur")); return ;;
+    block/get/--note) return ;;
+    block/list/--tags) return ;;
+  esac
+  case "$prev" in
+    --format) COMPREPLY=($(compgen -W "plain json" -- "$cur")); return ;;
+    --detail) COMPREPLY=($(compgen -W "summary standard detailed" -- "$cur")); return ;;
+  esac
+
+  # flag names
+  if [[ "$cur" == -* ]]; then
+    case "$noun/$verb" in
+      block/get) COMPREPLY=($(compgen -W "--view --out --with-meta --note --llm --format --verbose --detail --help" -- "$cur")); return ;;
+      block/list) COMPREPLY=($(compgen -W "--tags --llm --format --verbose --detail --help" -- "$cur")); return ;;
+      block/remove) COMPREPLY=($(compgen -W "--dry-run --undo --yes --llm --format --verbose --detail --help" -- "$cur")); return ;;
+    esac
+    if [ -z "$noun" ]; then
+      COMPREPLY=($(compgen -W "--llm --format --verbose --detail --help --version" -- "$cur"))
+    else
+      COMPREPLY=($(compgen -W "--llm --format --verbose --detail --help" -- "$cur"))
+    fi
+    return
+  fi
+
+  # nouns
+  if [ -z "$noun" ]; then
+    COMPREPLY=($(compgen -W "block mcp standard status" -- "$cur"))
+    return
+  fi
+
+  # verbs
+  if [ -z "$verb" ]; then
+    case "$noun" in
+      block) COMPREPLY=($(compgen -W "diff get list remove" -- "$cur")); return ;;
+      standard) COMPREPLY=($(compgen -W "list" -- "$cur")); return ;;
+    esac
+  fi
+
+  # positionals
+  case "$noun/$verb" in
+    block/diff)
+      _pragma_pos 2 "--format --detail"
+      case "$POS" in
+        *) _pragma_dynamic ;;
+      esac
+      ;;
+    block/get)
+      _pragma_pos 2 "--view --out --note --format --detail"
+      case "$POS" in
+        0) _pragma_dynamic ;;
+      esac
+      ;;
+    block/list)
+      _pragma_pos 2 "--tags --format --detail"
+      case "$POS" in
+        0) COMPREPLY=($(compgen -W "community core" -- "$cur")) ;;
+      esac
+      ;;
+    standard/)
+      _pragma_pos 1 "--format --detail"
+      case "$POS" in
+        0) _pragma_dynamic ;;
+      esac
+      ;;
+    status/)
+      _pragma_pos 1 "--format --detail"
+      case "$POS" in
+        0) COMPREPLY=($(compgen -W "all dirty" -- "$cur")) ;;
+      esac
+      ;;
+  esac
+}
+complete -F _pragma pragma
+"
+`;
+
+exports[`emitScripts — snapshots (fixture model) > renders the fish script 1`] = `
+"# pragma fish completion (static tier) — generated by \`pragma setup completions\`. Do not edit.
+# Structure (nouns, verbs, flags, enum values) is inlined and never execs;
+# name arguments call \`pragma __complete\` (storeless, never-throw) once
+# 2 chars are typed; file arguments use native completion (-rF). Requires fish >= 3.
+function __pragma_words
+    set -l toks (commandline -opc)
+    set -l cur (commandline -ct)
+    printf '%s\\n' $toks[2..-1] $cur
+end
+function __pragma_minchars
+    test (string length -- (commandline -ct)) -ge $argv[1]
+end
+function __pragma_at
+    set -l cmd (commandline -opc)
+    set -l noun ''
+    set -l verb ''
+    set -l skip 0
+    for w in $cmd[2..-1]
+        if test $skip -eq 1
+            set skip 0
+            continue
+        end
+        switch $w
+            case --format --detail
+                set skip 1
+            case '-*'
+            case '*'
+                if test -z "$noun"
+                    set noun $w
+                else if test -z "$verb"
+                    set verb $w
+                end
+        end
+    end
+    test "$noun" = "$argv[1]"; and test "$verb" = "$argv[2]"
+end
+complete -c pragma -f
+
+# nouns
+complete -c pragma -n "__pragma_at ''" -a "block mcp standard status"
+
+# global flags
+complete -c pragma -l llm
+complete -c pragma -l format -x -a "plain json"
+complete -c pragma -l verbose
+complete -c pragma -l detail -x -a "summary standard detailed"
+complete -c pragma -l help
+complete -c pragma -n "__pragma_at ''" -l version
+
+# block verbs
+complete -c pragma -n "__pragma_at block" -a "diff get list remove"
+
+# standard verbs
+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)"
+
+# 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)"
+
+# block/list
+complete -c pragma -n "__pragma_at block list" -l tags -x
+complete -c pragma -n "__pragma_at block list" -a "community core"
+
+# block/remove
+complete -c pragma -n "__pragma_at block remove" -l dry-run
+complete -c pragma -n "__pragma_at block remove" -l undo
+complete -c pragma -n "__pragma_at block remove" -l yes
+
+# status/
+complete -c pragma -n "__pragma_at status" -a "all dirty"
+"
+`;
+
+exports[`emitScripts — snapshots (fixture model) > renders the zsh script 1`] = `
+"#compdef pragma
+# pragma zsh completion (static tier) — generated by \`pragma setup completions\`. Do not edit.
+# Structure (nouns, verbs, flags, enum values) is inlined and never execs;
+# entity arguments call \`pragma __complete\` (storeless, never-throw);
+# file arguments use _files. Requires zsh >= 5.
+_pragma_dynamic() {
+  (( \${#cur} >= 2 )) || return 0
+  local -a _matches
+  _matches=("\${(f)$(pragma __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)}")
+  (( \${#_matches[@]} == 1 )) && [[ -z "\${_matches[1]}" ]] && return 0
+  compadd -- "\${_matches[@]}"
+}
+_pragma_pos() {
+  local skip="$1" vflags=" $2 " w
+  local -i i
+  POS=0
+  for ((i = 2; i < CURRENT; i++)); do
+    w="\${words[i]}"
+    case "$w" in
+      -*) [[ "$vflags" == *" $w "* ]] && ((i++)) ;;
+      *) if (( skip > 0 )); then (( skip-- )); else (( POS++ )); fi ;;
+    esac
+  done
+}
+_pragma() {
+  local cur prev noun verb w
+  local -i i POS
+  cur="\${words[CURRENT]}"
+  prev="\${words[CURRENT-1]}"
+  # Split an inline --flag=value word so the value routes as a flag value
+  # (mirrors parse.ts). zsh keeps \`--flag=value\` as one word, so recover
+  # $prev=flag and $cur=value before the flag-value cases below.
+  if [[ "$cur" == --*=* ]]; then
+    prev="\${cur%%=*}"
+    cur="\${cur#*=}"
+  fi
+  noun="" verb="" POS=0
+  for ((i = 2; i < CURRENT; i++)); do
+    w="\${words[i]}"
+    case "$w" in
+      --format|--detail) ((i++)) ;;
+      -*) ;;
+      *)
+        if [[ -z "$noun" ]]; then noun="$w"
+        elif [[ -z "$verb" ]]; then verb="$w"
+        fi
+        ;;
+    esac
+  done
+
+  # flag values (verb-scoped, then global)
+  case "$noun/$verb/$prev" in
+    block/get/--view) compadd -- anatomy full summary; return 0 ;;
+    block/get/--out) _files; return 0 ;;
+    block/get/--note) return 0 ;;
+    block/list/--tags) return 0 ;;
+  esac
+  case "$prev" in
+    --format) compadd -- plain json; return 0 ;;
+    --detail) compadd -- summary standard detailed; return 0 ;;
+  esac
+
+  # flag names
+  if [[ "$cur" == -* ]]; then
+    case "$noun/$verb" in
+      block/get) compadd -- --view --out --with-meta --note --llm --format --verbose --detail --help; return 0 ;;
+      block/list) compadd -- --tags --llm --format --verbose --detail --help; return 0 ;;
+      block/remove) compadd -- --dry-run --undo --yes --llm --format --verbose --detail --help; return 0 ;;
+    esac
+    if [[ -z "$noun" ]]; then
+      compadd -- --llm --format --verbose --detail --help --version
+    else
+      compadd -- --llm --format --verbose --detail --help
+    fi
+    return 0
+  fi
+
+  # nouns
+  if [[ -z "$noun" ]]; then
+    compadd -- block mcp standard status
+    return 0
+  fi
+
+  # verbs
+  if [[ -z "$verb" ]]; then
+    case "$noun" in
+      block) compadd -- diff get list remove; return 0 ;;
+      standard) compadd -- list; return 0 ;;
+    esac
+  fi
+
+  # positionals
+  case "$noun/$verb" in
+    block/diff)
+      _pragma_pos 2 "--format --detail"
+      case "$POS" in
+        *) _pragma_dynamic ;;
+      esac
+      ;;
+    block/get)
+      _pragma_pos 2 "--view --out --note --format --detail"
+      case "$POS" in
+        0) _pragma_dynamic ;;
+      esac
+      ;;
+    block/list)
+      _pragma_pos 2 "--tags --format --detail"
+      case "$POS" in
+        0) compadd -- community core ;;
+      esac
+      ;;
+    standard/)
+      _pragma_pos 1 "--format --detail"
+      case "$POS" in
+        0) _pragma_dynamic ;;
+      esac
+      ;;
+    status/)
+      _pragma_pos 1 "--format --detail"
+      case "$POS" in
+        0) compadd -- all dirty ;;
+      esac
+      ;;
+  esac
+}
+_pragma "$@"
+"
+`;

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

@@ -0,0 +1,73 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { completionFixture } from "../../testing/fixtures/completionFixture.js";
+import { emitScripts } from "./emitScripts.js";
+
+/**
+ * M1 regression: the generated bash script must complete the `--flag=value`
+ * wordbreak form. With `=` in COMP_WORDBREAKS, bash splits `--format=` into
+ * `--format` `=` `` (or `` after `=`); without the normalization at the top of
+ * `_pragma`, the value slot falls through to the noun/positional arm and
+ * offers the WRONG candidates. These tests drive the REAL bash to prove the
+ * fix, so the static tier answers `--format=<TAB>` as a flag value with zero
+ * exec (the resolver is only reached for `{kind:"entity"}` contexts).
+ */
+
+/** Whether a usable bash is on PATH (the package pins os:["linux"], so it is). */
+const bashOk =
+  spawnSync("bash", ["-c", "printf ok"], { encoding: "utf-8" }).stdout === "ok";
+
+/** The bash completion script for the fixture grammar (has the global --format). */
+const script = emitScripts([completionFixture]).bash;
+
+/**
+ * Source the generated script in a real bash, place the cursor per COMP_WORDS
+ * / COMP_CWORD, invoke `_pragma`, and return COMPREPLY line-by-line.
+ */
+function driveBash(words: readonly string[], cword: number): string[] {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-bashdrive-"));
+  const file = join(dir, "completion.bash");
+  writeFileSync(file, script);
+  const wordsLiteral = words
+    .map((word) => `'${word.replace(/'/g, "'\\''")}'`)
+    .join(" ");
+  const driver = [
+    `source '${file}'`,
+    `COMP_WORDS=(${wordsLiteral})`,
+    `COMP_CWORD=${cword}`,
+    "_pragma",
+    `printf '%s\\n' "\${COMPREPLY[@]}"`,
+  ].join("\n");
+  const result = spawnSync("bash", ["--norc", "--noprofile", "-c", driver], {
+    encoding: "utf-8",
+  });
+  return result.stdout.split("\n").filter((line) => line.length > 0);
+}
+
+describe.skipIf(!bashOk)("generated bash — --flag=value wordbreak (M1)", () => {
+  it("routes --format=<TAB> to the format values (not nouns/positionals)", () => {
+    // Default COMP_WORDBREAKS split: `--format` `=` `` (empty current word).
+    const reply = driveBash(["pragma", "--format", "=", ""], 3);
+    expect(reply.sort()).toEqual(["json", "plain"]);
+  });
+
+  it("filters the value by the partial typed after =", () => {
+    const reply = driveBash(["pragma", "--format", "=", "j"], 3);
+    expect(reply).toEqual(["json"]);
+  });
+
+  it("routes a verb-scoped --format=<TAB> the same way", () => {
+    // After a noun/verb the value must still route as a flag value, never as
+    // block's positional (which would offer entity/enum candidates instead).
+    const reply = driveBash(["pragma", "block", "get", "--format", "=", ""], 5);
+    expect(reply.sort()).toEqual(["json", "plain"]);
+  });
+
+  it("still completes the space form --format <TAB> (unbroken)", () => {
+    const reply = driveBash(["pragma", "--format", ""], 2);
+    expect(reply.sort()).toEqual(["json", "plain"]);
+  });
+});

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

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import {
+  completionFixture,
+  fixtureNameEnv,
+} from "../../testing/fixtures/completionFixture.js";
+import type { CapabilityModule } from "../spec/types.js";
+import { runComplete } from "./complete.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+});
+
+describe("runComplete — the __complete pipeline", () => {
+  it("resolves against the live capabilities (storeless static matches)", async () => {
+    await expect(runComplete(["co"], capabilities)).resolves.toEqual([
+      "colophon",
+      "config",
+    ]);
+    // The live `config` sub-verbs, prefix-filtered and sorted by the resolver.
+    await expect(runComplete(["config", ""], capabilities)).resolves.toEqual([
+      "channel",
+      "detail",
+      "set",
+      "show",
+      "tier",
+    ]);
+    await expect(runComplete(["mc"], capabilities)).resolves.toEqual(["mcp"]);
+    await expect(runComplete(["--l"], capabilities)).resolves.toEqual([
+      "--llm",
+    ]);
+  });
+
+  it("hidden verbs never complete", async () => {
+    const matches = await runComplete(["__com"], capabilities);
+    expect(matches).toEqual([]);
+  });
+
+  it("strips a leading bin name", async () => {
+    await expect(runComplete(["pragma", "co"], capabilities)).resolves.toEqual([
+      "colophon",
+      "config",
+    ]);
+  });
+
+  it("resolves name contexts through the provided env", async () => {
+    await expect(
+      runComplete(["block", "get", "but"], [completionFixture], fixtureNameEnv),
+    ).resolves.toEqual(["button", "button-group"]);
+  });
+
+  it("defaults to the empty name source (zero name candidates)", async () => {
+    await expect(
+      runComplete(["block", "get", "but"], [completionFixture]),
+    ).resolves.toEqual([]);
+  });
+});
+
+describe("runComplete — never-throw guard (PROTECTED)", () => {
+  const poisoned = [
+    { name: "poisoned", verbs: [{ path: ['x"; rm -rf ~'] }] },
+  ] as unknown as CapabilityModule[];
+
+  it("returns zero candidates instead of throwing on a poisoned model", async () => {
+    await expect(runComplete([""], poisoned)).resolves.toEqual([]);
+  });
+
+  it("stays silent on stderr without the debug flag", async () => {
+    vi.stubEnv("PRAGMA_COMPLETE_DEBUG", "");
+    const write = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    await runComplete([""], poisoned);
+    await runComplete(["co"], capabilities);
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it("reports the error on the debug channel when enabled", async () => {
+    vi.stubEnv("PRAGMA_COMPLETE_DEBUG", "1");
+    const write = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    await runComplete([""], poisoned);
+    expect(write).toHaveBeenCalledWith(
+      expect.stringContaining("[complete] error:"),
+    );
+  });
+
+  it("logs context, candidate count, and timing under debug", async () => {
+    vi.stubEnv("PRAGMA_COMPLETE_DEBUG", "1");
+    const write = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    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/,
+    );
+  });
+});

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 [];
+  }
+}