@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,405 @@
+import { describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import { completionFixture } from "../../testing/fixtures/completionFixture.js";
+import { emitSurface } from "../spec/emitSurface.js";
+import type { CapabilityModule, ParamSpec, VerbSpec } from "../spec/types.js";
+import { assertSafeToken, buildCompletionModel, findNoun } from "./model.js";
+import type { CompletionModel, VerbEntry } from "./types.js";
+
+const model = buildCompletionModel([completionFixture]);
+
+/** A minimal module with one verb, for adversarial name tests. */
+function moduleWith(overrides: Partial<VerbSpec>): CapabilityModule {
+  const verb: VerbSpec = {
+    path: ["thing"],
+    summary: "Test verb.",
+    params: [],
+    output: {
+      formatters: {
+        plain: () => "",
+        llm: () => "",
+        json: () => "null",
+      },
+    },
+    capability: {
+      needsStore: false,
+      mutates: false,
+      mcp: { expose: false, reason: "test" },
+    },
+    run: async () => null,
+    ...overrides,
+  };
+  return { name: "adversarial", verbs: [verb] };
+}
+
+describe("buildCompletionModel — structure", () => {
+  it("collects nouns sorted, injecting the bin-served mcp", () => {
+    expect(model.nouns.map((n) => n.noun)).toEqual([
+      "block",
+      "mcp",
+      "standard",
+      "status",
+    ]);
+  });
+
+  it("excludes hidden verbs", () => {
+    const block = findNoun(model, "block");
+    expect(block?.verbs.map((v) => v.label)).toEqual([
+      "diff",
+      "get",
+      "list",
+      "remove",
+    ]);
+  });
+
+  it("separates self-verbs from sub-verbs", () => {
+    const standard = findNoun(model, "standard");
+    expect(standard?.selfVerb?.label).toBe("standard");
+    expect(standard?.verbs.map((v) => v.label)).toEqual(["list"]);
+
+    const status = findNoun(model, "status");
+    expect(status?.selfVerb?.label).toBe("status");
+    expect(status?.verbs).toEqual([]);
+  });
+
+  it("injects mcp as a bare self-verb noun with nothing to offer", () => {
+    const mcp = findNoun(model, "mcp");
+    expect(mcp?.selfVerb).toEqual({
+      label: "mcp",
+      mutates: false,
+      flags: [],
+      positionals: [],
+    });
+  });
+
+  it("does not inject mcp when a live mcp noun exists", () => {
+    const withMcp = buildCompletionModel([
+      moduleWith({ path: ["mcp", "serve"] }),
+    ]);
+    const mcp = findNoun(withMcp, "mcp");
+    expect(mcp?.selfVerb).toBeUndefined();
+    expect(mcp?.verbs.map((v) => v.label)).toEqual(["serve"]);
+  });
+});
+
+describe("buildCompletionModel — flags and sources", () => {
+  const get = findNoun(model, "block")?.verbs.find((v) => v.label === "get");
+
+  it("kebab-cases flag names and marks boolean flags valueless", () => {
+    const withMeta = get?.flags.find((f) => f.flag === "--with-meta");
+    expect(withMeta).toMatchObject({
+      takesValue: false,
+      repeatable: false,
+      source: { kind: "none" },
+    });
+  });
+
+  it("defaults an enum flag to its values source", () => {
+    const view = get?.flags.find((f) => f.flag === "--view");
+    expect(view).toMatchObject({
+      takesValue: true,
+      source: { kind: "values", values: ["anatomy", "full", "summary"] },
+    });
+  });
+
+  it("resolves declared files / none sources", () => {
+    expect(get?.flags.find((f) => f.flag === "--out")?.source).toEqual({
+      kind: "files",
+    });
+    expect(get?.flags.find((f) => f.flag === "--note")?.source).toEqual({
+      kind: "none",
+    });
+  });
+
+  it("marks string[] flags repeatable", () => {
+    const list = findNoun(model, "block")?.verbs.find(
+      (v) => v.label === "list",
+    );
+    expect(list?.flags.find((f) => f.flag === "--tags")).toMatchObject({
+      takesValue: true,
+      repeatable: true,
+    });
+  });
+
+  it("resolves name positionals with required/variadic markers", () => {
+    expect(get?.positionals).toEqual([
+      {
+        name: "ref",
+        required: true,
+        variadic: false,
+        source: {
+          kind: "names",
+          ref: { from: "index", type: "ds:Block" },
+          match: "substring",
+          caseSensitive: false,
+        },
+      },
+    ]);
+    const diff = findNoun(model, "block")?.verbs.find(
+      (v) => v.label === "diff",
+    );
+    expect(diff?.positionals[0]).toMatchObject({
+      variadic: true,
+      source: {
+        kind: "names",
+        ref: { from: "index", type: "ds:Block" },
+      },
+    });
+  });
+
+  it("resolves a declared values positional and a defaulted enum positional", () => {
+    const list = findNoun(model, "block")?.verbs.find(
+      (v) => v.label === "list",
+    );
+    expect(list?.positionals[0]?.source).toEqual({
+      kind: "values",
+      values: ["community", "core"],
+    });
+    const status = findNoun(model, "status")?.selfVerb;
+    expect(status?.positionals[0]?.source).toEqual({
+      kind: "values",
+      values: ["all", "dirty"],
+    });
+  });
+
+  it("treats a {values} declaration on a non-enum param as none", () => {
+    const bad = buildCompletionModel([
+      moduleWith({
+        params: [
+          {
+            kind: "string",
+            name: "q",
+            doc: "q",
+            positional: true,
+            complete: { kind: "values" },
+          },
+        ],
+      }),
+    ]);
+    expect(findNoun(bad, "thing")?.selfVerb?.positionals[0]?.source).toEqual({
+      kind: "none",
+    });
+  });
+
+  it("carries a names heuristic's match + caseSensitive, defaulting both", () => {
+    const built = buildCompletionModel([
+      moduleWith({
+        params: [
+          {
+            kind: "string",
+            name: "q",
+            doc: "q",
+            positional: true,
+            complete: {
+              kind: "names",
+              source: { from: "skills" },
+              match: "prefix",
+              caseSensitive: true,
+            },
+          },
+        ],
+      }),
+    ]);
+    expect(findNoun(built, "thing")?.selfVerb?.positionals[0]?.source).toEqual({
+      kind: "names",
+      ref: { from: "skills" },
+      match: "prefix",
+      caseSensitive: true,
+    });
+    // Defaults when unspecified: substring + case-insensitive.
+    const defaulted = buildCompletionModel([
+      moduleWith({
+        params: [
+          {
+            kind: "string",
+            name: "q",
+            doc: "q",
+            positional: true,
+            complete: { kind: "names", source: { from: "prefixes" } },
+          },
+        ],
+      }),
+    ]);
+    expect(
+      findNoun(defaulted, "thing")?.selfVerb?.positionals[0]?.source,
+    ).toMatchObject({ match: "substring", caseSensitive: false });
+  });
+
+  it("resolves an opted-out (enabled:false) names heuristic to none", () => {
+    const built = buildCompletionModel([
+      moduleWith({
+        params: [
+          {
+            kind: "string",
+            name: "q",
+            doc: "q",
+            positional: true,
+            complete: {
+              kind: "names",
+              source: { from: "tiers" },
+              enabled: false,
+            },
+          },
+        ],
+      }),
+    ]);
+    expect(findNoun(built, "thing")?.selfVerb?.positionals[0]?.source).toEqual({
+      kind: "none",
+    });
+  });
+
+  it("marks the mutating verb and carries the mutation flag set", () => {
+    const remove = findNoun(model, "block")?.verbs.find(
+      (v) => v.label === "remove",
+    );
+    expect(remove?.mutates).toBe(true);
+    expect(model.mutationFlags.map((f) => f.flag)).toEqual([
+      "--dry-run",
+      "--undo",
+      "--yes",
+    ]);
+  });
+
+  it("models global flags with their value sources and --version rootOnly", () => {
+    const flags = Object.fromEntries(model.globalFlags.map((f) => [f.flag, f]));
+    expect(flags["--format"]?.source).toEqual({
+      kind: "values",
+      values: ["plain", "llm", "json"],
+    });
+    expect(flags["--detail"]?.source).toEqual({
+      kind: "values",
+      values: ["summary", "standard", "detailed"],
+    });
+    expect(flags["--llm"]).toBeUndefined();
+    expect(flags["--version"]?.rootOnly).toBe(true);
+    expect(flags["--help"]?.rootOnly).toBeUndefined();
+  });
+});
+
+describe("buildCompletionModel — safety assertion", () => {
+  it("throws on a hostile noun", () => {
+    expect(() =>
+      buildCompletionModel([moduleWith({ path: ['x"; rm -rf ~'] })]),
+    ).toThrow(/unsafe token/);
+  });
+
+  it("throws on a hostile verb label", () => {
+    expect(() =>
+      buildCompletionModel([moduleWith({ path: ["thing", "a;b"] })]),
+    ).toThrow(/unsafe token/);
+  });
+
+  it("throws on a hostile enum value", () => {
+    expect(() =>
+      buildCompletionModel([
+        moduleWith({
+          params: [
+            {
+              kind: "enum",
+              name: "mode",
+              doc: "mode",
+              values: ["ok", "$(rm -rf ~)"],
+            },
+          ],
+        }),
+      ]),
+    ).toThrow(/unsafe token/);
+  });
+
+  it("throws on a flag name that kebab-cases to an unsafe token", () => {
+    expect(() =>
+      buildCompletionModel([
+        moduleWith({
+          params: [{ kind: "string", name: "bad name", doc: "bad" }],
+        }),
+      ]),
+    ).toThrow(/unsafe token/);
+  });
+
+  it("assertSafeToken accepts URI-ish names and rejects shell syntax", () => {
+    expect(() => assertSafeToken("ds:Block", "test")).not.toThrow();
+    expect(() => assertSafeToken("button-group", "test")).not.toThrow();
+    expect(() => assertSafeToken("a`b`", "test")).toThrow(/unsafe token/);
+    expect(() => assertSafeToken("-x", "test")).toThrow(/unsafe token/);
+    expect(() => assertSafeToken("", "test")).toThrow(/unsafe token/);
+  });
+});
+
+/** Rebuild a surface `args` token from a completion positional entry. */
+function positionalToken(entry: {
+  name: string;
+  required: boolean;
+  variadic: boolean;
+}): string {
+  const variadic = entry.variadic ? "..." : "";
+  return entry.required
+    ? `<${entry.name}${variadic}>`
+    : `[${entry.name}${variadic}]`;
+}
+
+/** Assert the model is structurally the same projection as emitSurface. */
+function expectAgreement(
+  modules: readonly CapabilityModule[],
+  completionModel: CompletionModel,
+): void {
+  const surface = emitSurface(modules);
+
+  const surfaceNouns = Object.keys(surface.nouns).sort();
+  const modelNouns = completionModel.nouns
+    .map((n) => n.noun)
+    .filter((noun) => noun !== "mcp" || surfaceNouns.includes("mcp"));
+  expect(modelNouns).toEqual(surfaceNouns);
+
+  for (const noun of surfaceNouns) {
+    const nounEntry = findNoun(completionModel, noun);
+    expect(nounEntry).toBeDefined();
+    if (!nounEntry) continue;
+
+    const surfaceVerbs = surface.nouns[noun]?.verbs ?? [];
+    const modelLabels = [
+      ...(nounEntry.selfVerb ? [nounEntry.selfVerb.label] : []),
+      ...nounEntry.verbs.map((v) => v.label),
+    ].sort();
+    expect(modelLabels).toEqual(surfaceVerbs.map((v) => v.v).sort());
+
+    for (const surfaceVerb of surfaceVerbs) {
+      const modelVerb: VerbEntry | undefined =
+        nounEntry.selfVerb?.label === surfaceVerb.v
+          ? nounEntry.selfVerb
+          : nounEntry.verbs.find((v) => v.label === surfaceVerb.v);
+      expect(modelVerb).toBeDefined();
+      if (!modelVerb) continue;
+
+      expect(modelVerb.flags.map((f) => f.flag)).toEqual(
+        surfaceVerb.flags ?? [],
+      );
+      expect(modelVerb.positionals.map(positionalToken)).toEqual(
+        surfaceVerb.args ?? [],
+      );
+      expect(modelVerb.mutates).toBe(surfaceVerb.mutates === true);
+    }
+  }
+}
+
+describe("projection agreement with emitSurface (PROTECTED)", () => {
+  it("the fixture model matches the fixture surface (hidden excluded)", () => {
+    expectAgreement([completionFixture], model);
+    const emitted = emitSurface([completionFixture]);
+    expect(JSON.stringify(emitted)).not.toContain("probe");
+  });
+
+  it("the live model matches the live surface", () => {
+    expectAgreement(capabilities, buildCompletionModel(capabilities));
+  });
+});
+
+/** Regression pin: ParamSpec.complete stays optional on every param kind. */
+it("accepts params without a complete field", () => {
+  const params: ParamSpec[] = [
+    { kind: "string", name: "a", doc: "a" },
+    { kind: "number", name: "b", doc: "b" },
+  ];
+  const built = buildCompletionModel([moduleWith({ params })]);
+  const flags = findNoun(built, "thing")?.selfVerb?.flags;
+  expect(flags?.map((f) => f.source.kind)).toEqual(["none", "none"]);
+});

package/src/kernel/completion/model.ts

@@ -0,0 +1,258 @@
+/**
+ * Build the completion model from the capability modules — the ONE derivation
+ * both tiers share: the static scripts inline it, the `__complete` resolver
+ * walks it, so the two can never disagree.
+ *
+ * `ParamSpec.complete` resolution (defaults when the field is absent):
+ *
+ * | declared         | param kind             | source                     |
+ * | ---------------- | ---------------------- | -------------------------- |
+ * | absent           | enum                   | values (the enum's values) |
+ * | absent           | boolean                | none (flag name only)      |
+ * | absent           | string/number/string[] | none                       |
+ * | `{values}`       | enum only              | values                     |
+ * | `{names,source}` | string/string[]        | names (dynamic tier)       |
+ * | `{names,off}`    | any                    | none (opt-out)             |
+ * | `{files}`        | string/string[]        | files (native shell)       |
+ * | `{none}`         | any                    | none                       |
+ *
+ * Injection safety, primary gate: every token the static tier would inline
+ * (nouns, verb labels, flag names, enum values) must match
+ * {@link SAFE_TOKEN_RE}; the build THROWS otherwise, so `setup completions`
+ * fails loudly and no hostile name ever reaches a shell script. The resolver
+ * wraps this in its never-throw guard, so `__complete` degrades to zero
+ * candidates instead.
+ */
+
+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 type {
+  CompletionModel,
+  CompletionSource,
+  FlagEntry,
+  NounEntry,
+  PositionalEntry,
+  VerbEntry,
+} from "./types.js";
+
+/**
+ * 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.
+ */
+export const SAFE_TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9@/:._+-]*$/;
+
+/**
+ * Assert a token is safe to inline in a shell script.
+ *
+ * @param token - The candidate token (a noun, verb label, flag name, value).
+ * @param where - Human-readable location for the error message.
+ * @throws Error when the token fails the {@link SAFE_TOKEN_RE} allowlist.
+ */
+export function assertSafeToken(token: string, where: string): void {
+  if (!SAFE_TOKEN_RE.test(token)) {
+    throw new Error(
+      `completion: unsafe token ${JSON.stringify(token)} in ${where} — ` +
+        `must match ${String(SAFE_TOKEN_RE)}`,
+    );
+  }
+}
+
+/** The global flags completion offers, mirroring the surface's globalFlags. */
+const GLOBAL_FLAGS: readonly FlagEntry[] = [
+  {
+    flag: "--format",
+    takesValue: true,
+    repeatable: false,
+    source: { kind: "values", values: OUTPUT_FORMATS },
+  },
+  { flag: "--verbose", takesValue: false, repeatable: false, source: none() },
+  {
+    flag: "--detail",
+    takesValue: true,
+    repeatable: false,
+    source: { kind: "values", values: DETAIL_LEVELS },
+  },
+  { flag: "--help", takesValue: false, repeatable: false, source: none() },
+  {
+    flag: "--version",
+    takesValue: false,
+    repeatable: false,
+    rootOnly: true,
+    source: none(),
+  },
+];
+
+/** The flags auto-injected for `mutates` verbs (mirrors `buildProgram`). */
+const MUTATION_FLAGS: readonly FlagEntry[] = [
+  { flag: "--dry-run", takesValue: false, repeatable: false, source: none() },
+  { flag: "--undo", takesValue: false, repeatable: false, source: none() },
+  { flag: "--yes", takesValue: false, repeatable: false, source: none() },
+];
+
+/** The `{kind:"none"}` source (shared instance). */
+function none(): CompletionSource {
+  return { kind: "none" };
+}
+
+/**
+ * Resolve a param's completion source from `ParamSpec.complete` + its kind
+ * (the table in the module docblock).
+ */
+function resolveSource(param: ParamSpec): CompletionSource {
+  const declared = param.complete;
+  if (declared === undefined) {
+    return param.kind === "enum"
+      ? { kind: "values", values: param.values }
+      : none();
+  }
+  switch (declared.kind) {
+    case "values":
+      // The zod refinement makes {values} on a non-enum unregistrable; the
+      // model mirrors the rule structurally rather than trusting call order.
+      return param.kind === "enum"
+        ? { kind: "values", values: param.values }
+        : none();
+    case "names":
+      // The per-family opt-out (`enabled:false`) collapses to no completion.
+      if (declared.enabled === false) return none();
+      return {
+        kind: "names",
+        ref: declared.source,
+        match: declared.match ?? "substring",
+        caseSensitive: declared.caseSensitive ?? false,
+      };
+    case "files":
+      return { kind: "files" };
+    case "none":
+      return none();
+  }
+}
+
+/** Assert the safety of every token a source could inline statically. */
+function assertSafeSource(source: CompletionSource, where: string): void {
+  if (source.kind === "values") {
+    for (const value of source.values) {
+      assertSafeToken(value, `${where} value`);
+    }
+  }
+  if (source.kind === "names" && source.ref.type && source.ref.type !== "") {
+    // The type key is never inlined into a script (only NAMES are, at runtime,
+    // through the same allowlist) — but keep any non-empty type well-formed
+    // anyway. An empty/absent type is the legitimate "any type" query (`graph
+    // inspect`), matched against every entity by the index reader.
+    assertSafeToken(source.ref.type, `${where} names type`);
+  }
+}
+
+/** Project one verb spec into its completion entry, asserting name safety. */
+function toVerbEntry(verb: VerbSpec): VerbEntry {
+  const label = verbLabel(verb.path);
+  assertSafeToken(label, `verb "${verb.path.join(" ")}"`);
+
+  const flags: FlagEntry[] = [];
+  const positionals: PositionalEntry[] = [];
+  for (const param of verb.params) {
+    const source = resolveSource(param);
+    if (param.positional) {
+      assertSafeSource(source, `positional "${param.name}"`);
+      positionals.push({
+        name: param.name,
+        required: param.required === true,
+        variadic: param.kind === "string[]",
+        source,
+      });
+    } else {
+      const name = kebabCase(param.name);
+      assertSafeToken(name, `flag "--${name}"`);
+      assertSafeSource(source, `flag "--${name}"`);
+      flags.push({
+        flag: `--${name}`,
+        takesValue: param.kind !== "boolean",
+        repeatable: param.kind === "string[]",
+        source,
+      });
+    }
+  }
+
+  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: [] };
+}
+
+/**
+ * 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.
+ *
+ * @param modules - The capability modules.
+ * @returns The completion model, nouns and verbs sorted.
+ * @throws Error when any inlined token fails the safety allowlist.
+ */
+export function buildCompletionModel(
+  modules: readonly CapabilityModule[],
+): CompletionModel {
+  const byNoun = new Map<
+    string,
+    { selfVerb?: VerbEntry; verbs: VerbEntry[] }
+  >();
+  const bucketFor = (
+    noun: string,
+  ): { selfVerb?: VerbEntry; verbs: VerbEntry[] } => {
+    const existing = byNoun.get(noun);
+    if (existing) return existing;
+    const created: { selfVerb?: VerbEntry; verbs: VerbEntry[] } = { verbs: [] };
+    byNoun.set(noun, created);
+    return created;
+  };
+
+  for (const module of modules) {
+    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);
+      if (verb.path[1] === undefined) {
+        bucket.selfVerb = entry;
+      } else {
+        bucket.verbs.push(entry);
+      }
+    }
+  }
+
+  if (!byNoun.has("mcp")) {
+    byNoun.set("mcp", { selfVerb: bareSelfVerb("mcp"), verbs: [] });
+  }
+
+  const nouns: NounEntry[] = [...byNoun.entries()]
+    .map(([noun, bucket]) => ({
+      noun,
+      ...(bucket.selfVerb ? { selfVerb: bucket.selfVerb } : {}),
+      verbs: [...bucket.verbs].sort((a, b) => a.label.localeCompare(b.label)),
+    }))
+    .sort((a, b) => a.noun.localeCompare(b.noun));
+
+  return { nouns, globalFlags: GLOBAL_FLAGS, mutationFlags: MUTATION_FLAGS };
+}
+
+/**
+ * Look up a noun's entry in the model.
+ *
+ * @param model - The completion model.
+ * @param noun - The noun token.
+ * @returns The entry, or `undefined` for an unknown noun.
+ */
+export function findNoun(
+  model: CompletionModel,
+  noun: string,
+): NounEntry | undefined {
+  return model.nouns.find((entry) => entry.noun === noun);
+}