@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/testing/fixtures/completionFixture.ts

@@ -0,0 +1,239 @@
+/**
+ * A synthetic capability module exercising every completion path (D8 —
+ * test-only, never listed in `src/capabilities/index.ts`): an entity
+ * positional, an enum positional, enum/files/boolean/none flags, a variadic
+ * `string[]` positional, a repeatable `string[]` flag, a mutating verb, a
+ * self-verb-only noun, a mixed self-verb + sub-verb noun, and a hidden verb.
+ *
+ * Snapshots and the protected parse/resolve tests pin against THIS module,
+ * not the live capabilities, so live noun renames never churn them.
+ */
+
+import { succeed } from "@canonical/task";
+import type { CompletionEnv } from "../../kernel/completion/types.js";
+import type {
+  CapabilityModule,
+  Formatters,
+  VerbSpec,
+} from "../../kernel/spec/types.js";
+
+const passthrough: Formatters<unknown> = {
+  plain: (d) => String(d),
+  llm: (d) => String(d),
+  json: (d) => JSON.stringify(d),
+};
+
+const read = {
+  needsStore: false,
+  mutates: false,
+  mcp: { expose: false, reason: "completion test fixture" },
+} as const;
+
+/** `block get <ref>` — entity positional; enum, files, boolean, none flags. */
+const blockGet: VerbSpec = {
+  path: ["block", "get"],
+  summary: "Get a block.",
+  params: [
+    {
+      kind: "string",
+      name: "ref",
+      doc: "The block to get.",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "index", type: "ds:Block" } },
+    },
+    {
+      kind: "enum",
+      name: "view",
+      doc: "Which projection to show.",
+      values: ["anatomy", "full", "summary"],
+    },
+    {
+      kind: "string",
+      name: "out",
+      doc: "Write the result to a file.",
+      complete: { kind: "files" },
+    },
+    { kind: "boolean", name: "withMeta", doc: "Include metadata." },
+    { kind: "string", name: "note", doc: "Free-text note (not completable)." },
+  ],
+  output: { formatters: passthrough },
+  capability: read,
+  run: async () => "ok",
+};
+
+/** `block list [tier]` — enum positional (declared) + repeatable tags flag. */
+const blockList: VerbSpec = {
+  path: ["block", "list"],
+  summary: "List blocks.",
+  params: [
+    {
+      kind: "enum",
+      name: "tier",
+      doc: "Restrict to a tier.",
+      values: ["community", "core"],
+      positional: true,
+      complete: { kind: "values" },
+    },
+    { kind: "string[]", name: "tags", doc: "Filter by tags." },
+  ],
+  output: { formatters: passthrough },
+  capability: read,
+  run: async () => "ok",
+};
+
+/** `block diff <refs...>` — variadic entity positional. */
+const blockDiff: VerbSpec = {
+  path: ["block", "diff"],
+  summary: "Diff blocks.",
+  params: [
+    {
+      kind: "string[]",
+      name: "refs",
+      doc: "The blocks to diff.",
+      positional: true,
+      required: true,
+      complete: { kind: "names", source: { from: "index", type: "ds:Block" } },
+    },
+  ],
+  output: { formatters: passthrough },
+  capability: read,
+  run: async () => "ok",
+};
+
+/** `block remove <ref>` — mutates (mutation flags), completion opted out. */
+const blockRemove: VerbSpec = {
+  path: ["block", "remove"],
+  summary: "Remove a block.",
+  params: [
+    {
+      kind: "string",
+      name: "ref",
+      doc: "The block to remove.",
+      positional: true,
+      required: true,
+      complete: { kind: "none" },
+    },
+  ],
+  output: { formatters: passthrough },
+  capability: {
+    needsStore: true,
+    mutates: true,
+    destructive: true,
+    mcp: { expose: false, reason: "completion test fixture" },
+  },
+  run: () => succeed({ removed: true }),
+};
+
+/** `block probe` — hidden; must never appear in completions. */
+const blockProbe: VerbSpec = {
+  path: ["block", "probe"],
+  summary: "Internal probe.",
+  hidden: true,
+  params: [],
+  output: { formatters: passthrough },
+  capability: read,
+  run: async () => "ok",
+};
+
+/** `standard [query]` — self-verb on a noun that ALSO has a sub-verb. */
+const standardSelf: VerbSpec = {
+  path: ["standard"],
+  summary: "Look up a standard.",
+  params: [
+    {
+      kind: "string",
+      name: "query",
+      doc: "The standard to look up.",
+      positional: true,
+      complete: {
+        kind: "names",
+        source: { from: "index", type: "ds:Standard" },
+      },
+    },
+  ],
+  output: { formatters: passthrough },
+  capability: read,
+  run: async () => "ok",
+};
+
+/** `standard list` — the sub-verb beside the self-verb. */
+const standardList: VerbSpec = {
+  path: ["standard", "list"],
+  summary: "List standards.",
+  params: [],
+  output: { formatters: passthrough },
+  capability: read,
+  run: async () => "ok",
+};
+
+/** `status [scope]` — a self-verb-only noun with an enum positional. */
+const statusSelf: VerbSpec = {
+  path: ["status"],
+  summary: "Show status.",
+  params: [
+    {
+      kind: "enum",
+      name: "scope",
+      doc: "Which scope to report.",
+      values: ["all", "dirty"],
+      positional: true,
+    },
+  ],
+  output: { formatters: passthrough },
+  capability: read,
+  run: async () => "ok",
+};
+
+/** The synthetic completion module (D8 — test-only). */
+export const completionFixture: CapabilityModule = {
+  name: "completion-fixture",
+  verbs: [
+    blockGet,
+    blockList,
+    blockDiff,
+    blockRemove,
+    blockProbe,
+    standardSelf,
+    standardList,
+    statusSelf,
+  ],
+};
+
+/**
+ * A compact per-type name table backing {@link fixtureNameEnv} — the hand-built
+ * stand-in the resolver's RANKING tests (resolve/complete) drive, NOT the
+ * on-disk `PackIndex` (a flat `entities[{name,type}]` array). The real index
+ * shape ⟷ reader agreement is proven live, against a freshly built index, by
+ * `kernel/runtime/graphpack/completionSeam.test.ts`.
+ */
+export const fixtureIndex = {
+  version: 1,
+  entities: {
+    "ds:Block": {
+      names: [
+        "button",
+        "button-group",
+        "card",
+        "chip",
+        "navigation",
+        "tooltip",
+      ],
+    },
+    "ds:Standard": { names: ["accessibility", "naming"] },
+  },
+} as const;
+
+/**
+ * A completion env serving {@link fixtureIndex} by the source ref's `type`
+ * (the `from:"index"` stand-in the ranking tests drive).
+ */
+export const fixtureNameEnv: CompletionEnv = {
+  names: (ref): readonly string[] =>
+    (
+      fixtureIndex.entities as Record<
+        string,
+        { names: readonly string[] } | undefined
+      >
+    )[ref.type ?? ""]?.names ?? [],
+};

package/src/testing/fixtures/fixtureCapability.ts

@@ -0,0 +1,331 @@
+/**
+ * A synthetic capability module used only by tests (D8 — never listed in
+ * `src/capabilities/index.ts`). It exercises every emit path: a read verb, a
+ * mutating verb with a positional + a camelCase flag, and a hidden verb the
+ * emitter must drop.
+ */
+
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { $, gen, succeed, writeFile } from "@canonical/task";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+
+/** A synthetic module: noun `widget`, three verbs (one hidden). */
+export const fixtureModule: CapabilityModule = {
+  name: "fixture",
+  verbs: [
+    {
+      path: ["widget", "list"],
+      summary: "List widgets.",
+      params: [],
+      output: {
+        formatters: {
+          plain: (d) => String(d),
+          llm: (d) => String(d),
+          json: (d) => JSON.stringify(d),
+        },
+      },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async () => ["alpha", "beta"],
+    },
+    {
+      path: ["widget", "make"],
+      summary: "Make a widget.",
+      params: [
+        {
+          kind: "string",
+          name: "name",
+          doc: "Widget name.",
+          positional: true,
+          required: true,
+        },
+        { kind: "boolean", name: "withHistory", doc: "Seed history." },
+      ],
+      output: {
+        formatters: {
+          plain: (d) => String(d),
+          llm: (d) => String(d),
+          json: (d) => JSON.stringify(d),
+        },
+      },
+      capability: {
+        needsStore: true,
+        mutates: true,
+        destructive: true,
+        mcp: {
+          expose: true,
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+          },
+        },
+      },
+      run: () => succeed({ made: true }),
+    },
+    {
+      path: ["widget", "internal"],
+      summary: "Internal probe.",
+      hidden: true,
+      params: [],
+      output: {
+        formatters: {
+          plain: (d) => String(d),
+          llm: (d) => String(d),
+          json: (d) => JSON.stringify(d),
+        },
+      },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: { expose: false, reason: "internal probe, not an agent tool" },
+      },
+      run: async () => "ok",
+    },
+  ],
+};
+
+/**
+ * The isolated tmp path the fixture `touch` verb writes to. Rooted under
+ * `$XDG_STATE_HOME` so the XDG isolation setup contains it per test run.
+ *
+ * @param name - The file name to create.
+ * @returns The absolute path under the isolated state directory.
+ */
+export function touchPath(name: string): string {
+  const base = process.env.XDG_STATE_HOME ?? tmpdir();
+  return join(base, "pragma-touch", name);
+}
+
+const passthroughFormatters = {
+  plain: (d: unknown) => String(d),
+  llm: (d: unknown) => String(d),
+  json: (d: unknown) => JSON.stringify(d),
+};
+
+/**
+ * A second synthetic module exercising the effect seam end-to-end: a read verb
+ * (`probe echo`) that returns its input, and a mutating Task verb (`probe
+ * touch`) that writes a file under the isolated tmp. Used by the CLI/MCP
+ * projector tests for envelope parity and MCP plan-first/confirm. Test-only
+ * (D8) — never listed in `capabilities/index.ts`.
+ */
+export const fixtureEffectsModule: CapabilityModule = {
+  name: "fixture-effects",
+  verbs: [
+    {
+      path: ["probe", "echo"],
+      summary: "Echo the message back.",
+      params: [
+        {
+          kind: "string",
+          name: "message",
+          doc: "The message to echo.",
+          positional: true,
+          required: true,
+        },
+      ],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async (p) => ({ echoed: (p as { message: string }).message }),
+    },
+    {
+      path: ["probe", "touch"],
+      summary: "Create a file under the isolated tmp.",
+      params: [
+        {
+          kind: "string",
+          name: "name",
+          doc: "File name to create.",
+          positional: true,
+          required: true,
+        },
+      ],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: true,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: false, openWorldHint: false },
+        },
+      },
+      run: (p) =>
+        gen(function* () {
+          const name = (p as { name: string }).name;
+          yield* $(writeFile(touchPath(name), "touched\n"));
+          return { touched: name };
+        }),
+    },
+  ],
+};
+
+/**
+ * A synthetic module that exercises every RENDER path of `emitReference` (D8 —
+ * never listed in `src/capabilities/index.ts`). Distinct from `fixtureModule`,
+ * which only exercises `emitSurface`: this one carries the doc-only shapes the
+ * reference generator reads and the machine surface ignores — a rich `doc`,
+ * examples with and without notes, a {@link DisclosureSpec}, every param kind
+ * as a flag (including a repeatable `string[]` flag), an OPTIONAL variadic
+ * positional, a destructive mutation AND a non-destructive one (the two
+ * `formatToolAnnotations` mutation branches), a visible MCP-withheld verb, a
+ * self-verb, a hidden verb the emitter must drop, and — so `renderNonToolSurface`
+ * renders both its optional bullets — an `mcpResources` template surface and an
+ * `mcpPrompts` native-prompt surface. The `register` hooks are no-ops: the
+ * reference emitter reads only `mcpResources.surface.templates` and the presence
+ * of `mcpPrompts`, never invoking either.
+ */
+export const fixtureReferenceModule: CapabilityModule = {
+  name: "fixture-reference",
+  verbs: [
+    {
+      path: ["gizmo", "scan"],
+      summary: "Scan the gizmos.",
+      doc: "Scan every gizmo under the active scope, optionally narrowing to named targets. Reads nothing off disk.",
+      params: [
+        {
+          kind: "string[]",
+          name: "targets",
+          doc: "Gizmo names to scan (all when omitted).",
+          positional: true,
+        },
+        {
+          kind: "enum",
+          name: "mode",
+          doc: "Scan mode.",
+          values: ["fast", "slow"],
+          default: "fast",
+        },
+        { kind: "number", name: "limit", doc: "Maximum gizmos to scan." },
+        { kind: "string", name: "label", doc: "Label to stamp on the report." },
+        { kind: "string[]", name: "include", doc: "Extra globs to include." },
+        { kind: "boolean", name: "deep", doc: "Recurse into sub-gizmos." },
+      ],
+      output: { formatters: passthroughFormatters },
+      examples: [
+        { cmd: "pragma gizmo scan", note: "scan everything" },
+        { cmd: "pragma gizmo scan alpha --mode slow" },
+      ],
+      disclosure: { levels: ["summary", "detailed"], default: "summary" },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async () => ({ scanned: true }),
+    },
+    {
+      path: ["gizmo", "wipe"],
+      summary: "Wipe a gizmo.",
+      params: [
+        {
+          kind: "string",
+          name: "path",
+          doc: "The gizmo path to wipe.",
+          positional: true,
+          required: true,
+        },
+      ],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: true,
+        mutates: true,
+        destructive: true,
+        mcp: {
+          expose: true,
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+          },
+        },
+      },
+      run: () => succeed({ wiped: true }),
+    },
+    {
+      path: ["gizmo", "tidy"],
+      summary: "Tidy the gizmo cache.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: true,
+        destructive: false,
+        mcp: {
+          expose: true,
+          annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: false,
+          },
+        },
+      },
+      run: () => succeed({ tidied: true }),
+    },
+    {
+      path: ["gizmo", "local"],
+      summary: "A visible gizmo verb withheld from MCP.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: { expose: false, reason: "CLI-only local helper" },
+      },
+      run: async () => ({ local: true }),
+    },
+    {
+      path: ["ping"],
+      summary: "Ping the gizmo host.",
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+          expose: true,
+          annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+      },
+      run: async () => ({ pong: true }),
+    },
+    {
+      path: ["gizmo", "hidden"],
+      summary: "Hidden gizmo probe.",
+      hidden: true,
+      params: [],
+      output: { formatters: passthroughFormatters },
+      capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: { expose: false, reason: "internal probe" },
+      },
+      run: async () => ({ ok: true }),
+    },
+  ],
+  // A non-tool MCP surface, so `renderNonToolSurface` emits its Resources bullet.
+  // `register` is a no-op — the emitter reads only `surface.templates`.
+  mcpResources: {
+    surface: { templates: ["gizmo:{+uri}"] },
+    register: () => {},
+  },
+  // A native prompt surface, so `renderNonToolSurface` emits its Prompts bullet.
+  mcpPrompts: { register: () => {} },
+};