@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/config/fields.ts

@@ -0,0 +1,81 @@
+/**
+ * The config field table — one declarative row per writable field. Since AV-228
+ * B3 retired the per-field `config tier`/`channel`/`detail` verbs, this table no
+ * longer emits verbs of its own: it is the shared source of truth that drives
+ * `config set <key> <value>` (via `runSet` → `runField`), giving `set` its
+ * `<key>` enum, per-field reset sentinels, enum validation, and positional
+ * shaping for free.
+ */
+
+import { DETAIL_LEVELS } from "../../constants.js";
+import type { RawConfig } from "../../kernel/config/types.js";
+import { CHANNELS } from "../../kernel/config/types.js";
+
+/** One writable config field and how its single positional is shaped/validated. */
+export interface ConfigFieldSpec {
+  /** The `RawConfig` key written (also the `config set` `<key>` enum member). */
+  readonly field: keyof RawConfig & ("tier" | "channel" | "detail");
+  /** The positional param NAME — its usage token is `<positional>` (covenant). */
+  readonly positional: string;
+  /** A free string (`tier`) or a fixed enum (`channel` / `detail`). */
+  readonly kind: "string" | "enum";
+  /** The allowed values for an enum field. */
+  readonly values?: readonly string[];
+  /** One-line field summary. */
+  readonly summary: string;
+  /** Extended help doc. */
+  readonly doc: string;
+  /** Reserved values that REMOVE the field instead of setting it. */
+  readonly resetSentinel?: readonly string[];
+  /** Field help examples. */
+  readonly examples: readonly { cmd: string; note?: string }[];
+}
+
+/**
+ * The three writable fields. Only `tier` (a free string with a meaningful
+ * "no value") carries reset sentinels; `channel`/`detail` reset by setting
+ * their default (`normal`/`standard`). The migration path for the retired
+ * field-verbs is `config set <field> <value>` (e.g. `config set tier apps/lxd`,
+ * `config set tier none` to clear it).
+ */
+export const CONFIG_FIELDS: readonly ConfigFieldSpec[] = [
+  {
+    field: "tier",
+    positional: "path",
+    kind: "string",
+    resetSentinel: ["none", "default", "-"],
+    summary: "Set the active design-system tier.",
+    doc: "Writes the `tier` field to the global config. Pass `none`, `default`, or `-` to clear it. Written to the global layer only — project configs are authored by hand.",
+    examples: [
+      {
+        cmd: "pragma config set tier apps/lxd",
+        note: "scope reads to a tier",
+      },
+      { cmd: "pragma config set tier none", note: "clear the tier" },
+    ],
+  },
+  {
+    field: "channel",
+    positional: "name",
+    kind: "enum",
+    values: CHANNELS,
+    summary: "Set the release channel controlling component visibility.",
+    doc: "Writes the `channel` field to the global config. Reset by setting the default, `normal`.",
+    examples: [
+      { cmd: "pragma config set channel experimental" },
+      { cmd: "pragma config set channel normal", note: "back to the default" },
+    ],
+  },
+  {
+    field: "detail",
+    positional: "level",
+    kind: "enum",
+    values: DETAIL_LEVELS,
+    summary: "Set the default progressive-disclosure level.",
+    doc: "Writes the `detail` field to the global config. Reset by setting the default, `standard`.",
+    examples: [
+      { cmd: "pragma config set detail detailed" },
+      { cmd: "pragma config set detail standard", note: "back to the default" },
+    ],
+  },
+];

package/src/capabilities/config/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `config` capability barrel.
+ */
+
+export { configModule } from "./show.verb.js";
+export type { ConfigFieldResult, ConfigShowData } from "./types.js";

package/src/capabilities/config/runField.ts

@@ -0,0 +1,59 @@
+/**
+ * The `config <field>` write body (lazily imported, off the fast path).
+ *
+ * Resolves the single positional and composes the write as a Task over the
+ * kernel `writeConfigField` (global-layer only): a reset sentinel removes the
+ * field (`writeConfigField(field, undefined)`), otherwise the value is written.
+ * An enum field re-validates its value as a belt-and-braces backstop — the CLI
+ * `coerceParam` and the MCP zod schema already reject a non-member before `run`,
+ * but a direct call (a test, a future caller) must not slip an invalid value to
+ * disk.
+ */
+
+import { map, type Task } from "@canonical/task";
+import { writeConfigField } from "../../kernel/config/writeConfigField.js";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import type { ConfigFieldSpec } from "./fields.js";
+import type { ConfigFieldResult } from "./types.js";
+
+/**
+ * Build the Task that writes (or resets) one config field.
+ *
+ * @param spec - The field-table row for the target field.
+ * @param params - The coerced param bag (carries the single positional).
+ * @returns A Task yielding the write outcome.
+ * @throws PragmaError INVALID_INPUT for an out-of-set enum value (backstop).
+ */
+export function runField(
+  spec: ConfigFieldSpec,
+  params: Record<string, unknown>,
+): Task<ConfigFieldResult> {
+  const value = String(params[spec.positional] ?? "");
+
+  if (spec.resetSentinel?.includes(value)) {
+    return map(
+      writeConfigField(spec.field, undefined),
+      (result): ConfigFieldResult => ({
+        field: result.field,
+        path: result.path,
+        reset: true,
+      }),
+    );
+  }
+
+  if (spec.kind === "enum" && !(spec.values ?? []).includes(value)) {
+    throw PragmaError.invalidInput(spec.field, value, {
+      validOptions: [...(spec.values ?? [])],
+    });
+  }
+
+  return map(
+    writeConfigField(spec.field, value),
+    (result): ConfigFieldResult => ({
+      field: result.field,
+      value,
+      path: result.path,
+      reset: false,
+    }),
+  );
+}

package/src/capabilities/config/runSet.ts

@@ -0,0 +1,38 @@
+/**
+ * The `config set <key> <value>` write body (lazily imported, off the fast path).
+ *
+ * `config set` is the single-command form of the per-field setters: it resolves
+ * `<key>` to its {@link ConfigFieldSpec} and delegates to the SAME
+ * {@link runField} write path, so reset sentinels, enum re-validation, and the
+ * global-layer write all behave identically to `config <field>`. An unknown key
+ * is a backstop INVALID_INPUT — the CLI enum coerce and the MCP schema already
+ * reject a non-member first, but a direct call must not slip through.
+ */
+
+import type { Task } from "@canonical/task";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { CONFIG_FIELDS } from "./fields.js";
+import { runField } from "./runField.js";
+import type { ConfigFieldResult } from "./types.js";
+
+/**
+ * Build the Task that writes (or resets) the config field named by `<key>`.
+ *
+ * @param params - The coerced param bag: `key` (field name) and `value`.
+ * @returns A Task yielding the write outcome.
+ * @throws PragmaError INVALID_INPUT for an unknown key (backstop).
+ */
+export function runSet(
+  params: Record<string, unknown>,
+): Task<ConfigFieldResult> {
+  const key = String(params.key ?? "");
+  const spec = CONFIG_FIELDS.find((field) => field.field === key);
+  if (!spec) {
+    throw PragmaError.invalidInput("key", key, {
+      validOptions: CONFIG_FIELDS.map((field) => field.field),
+    });
+  }
+  // Re-key the value under the field's own positional (`path`/`name`/`level`) so
+  // runField reads it exactly as the per-field verb would.
+  return runField(spec, { [spec.positional]: String(params.value ?? "") });
+}

package/src/capabilities/config/set.test.ts

@@ -0,0 +1,207 @@
+/**
+ * `config set <key> <value>` — the one-command config setter (PR9, COVENANT).
+ *
+ * Pins the emitted covenant slice (`{ v:"set", args:["<key>","<value>"],
+ * mutates:true, mcp:"config_set" }`), proves it drives the shared per-field
+ * write path (set / reset-sentinel / enum-backstop), rejects an unknown key and
+ * an out-of-set enum value with INVALID_INPUT, and holds MCP plan-first/confirm
+ * parity. Since AV-228 B3 retired `config tier/channel/detail`, `config set` is
+ * the sole config setter — `config set <field> <value>` is the migration path.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { globalConfigPath } from "../../kernel/config/paths.js";
+import { CHANNELS } from "../../kernel/config/types.js";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import {
+  executeVerb,
+  extractParams,
+} from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags, PragmaRuntime } from "../../kernel/runtime/types.js";
+import { emitVerb } from "../../kernel/spec/emitSurface.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { configModule } from "./index.js";
+import { runSet } from "./runSet.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const REAL = { dryRun: false, undo: false, yes: false };
+const DRY = { dryRun: true, undo: false, yes: false };
+
+const setVerb = configModule.verbs.find((v) => v.path[1] === "set") as VerbSpec;
+
+let prevXdg: string | undefined;
+const roots: string[] = [];
+const tmp = (prefix: string): string => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+};
+
+beforeEach(() => {
+  prevXdg = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = tmp("pragma-cfgset-xdg-");
+});
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = prevXdg;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+function readGlobal(): Record<string, unknown> {
+  return JSON.parse(readFileSync(globalConfigPath(), "utf-8"));
+}
+
+describe("config set — covenant-exact emission (PROTECTED)", () => {
+  it("emits the two-positional slice with the config_set tool", () => {
+    expect(emitVerb(setVerb)).toEqual({
+      v: "set",
+      args: ["<key>", "<value>"],
+      mutates: true,
+      mcp: "config_set",
+    });
+  });
+});
+
+describe("config set — write & reset (shares the per-field path)", () => {
+  it("set tier writes the field to the GLOBAL config, never booting the store", async () => {
+    const rt: PragmaRuntime = bootRuntime(FLAGS, tmp("pragma-proj-"));
+    const outcome = await executeVerb(
+      setVerb,
+      { key: "tier", value: "apps/lxd" },
+      REAL,
+      rt,
+    );
+
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("Set tier = apps/lxd");
+    expect(readGlobal().tier).toBe("apps/lxd");
+    expect(rt.store.booted).toBe(false);
+  });
+
+  it("set channel/detail write their enum value", async () => {
+    const rt = bootRuntime(FLAGS, tmp("pragma-proj-"));
+    await executeVerb(
+      setVerb,
+      { key: "channel", value: "experimental" },
+      REAL,
+      rt,
+    );
+    await executeVerb(setVerb, { key: "detail", value: "detailed" }, REAL, rt);
+    const written = readGlobal();
+    expect(written.channel).toBe("experimental");
+    expect(written.detail).toBe("detailed");
+  });
+
+  it("a reset sentinel via set removes the tier field", async () => {
+    const cwd = tmp("pragma-proj-");
+    await executeVerb(
+      setVerb,
+      { key: "tier", value: "apps/lxd" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    const outcome = await executeVerb(
+      setVerb,
+      { key: "tier", value: "none" },
+      REAL,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.stdout).toContain("Reset tier");
+    expect("tier" in readGlobal()).toBe(false);
+  });
+});
+
+describe("config set — input rejection (INVALID_INPUT)", () => {
+  it("the CLI enum coerce rejects an unknown key with the valid field names", () => {
+    let caught: unknown;
+    try {
+      extractParams(setVerb.params, ["bogus", "x"], {});
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(PragmaError);
+    expect((caught as PragmaError).code).toBe("INVALID_INPUT");
+    expect((caught as PragmaError).validOptions).toEqual([
+      "tier",
+      "channel",
+      "detail",
+    ]);
+  });
+
+  it("runSet backstops an unknown key before it reaches a field", () => {
+    expect(() => runSet({ key: "bogus", value: "x" })).toThrow(PragmaError);
+    try {
+      runSet({ key: "bogus", value: "x" });
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+      expect((error as PragmaError).validOptions).toEqual([
+        "tier",
+        "channel",
+        "detail",
+      ]);
+    }
+  });
+
+  it("an out-of-set enum value is rejected by the shared runField backstop", () => {
+    expect(() => runSet({ key: "channel", value: "bogus" })).toThrow(
+      /Invalid channel/,
+    );
+    // Sanity: the same key with a real member does not throw.
+    expect(() =>
+      runSet({ key: "channel", value: CHANNELS[0] as string }),
+    ).not.toThrow();
+  });
+});
+
+describe("config set — dry-run plan", () => {
+  it("--dry-run shows the WriteFile plan and writes nothing", async () => {
+    const rt = bootRuntime(FLAGS, tmp("pragma-proj-"));
+    const outcome = await executeVerb(
+      setVerb,
+      { key: "tier", value: "apps/lxd" },
+      DRY,
+      rt,
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("Write file");
+    expect(existsSync(globalConfigPath())).toBe(false);
+  });
+});
+
+describe("config set — MCP plan-first / confirm parity", () => {
+  it("config_set returns a plan without confirm, writes with confirm:true", async () => {
+    const cwd = tmp("pragma-proj-");
+    const mcp = await projectMcp([configModule], cwd);
+
+    const plan = await mcp.callTool("config_set", {
+      key: "tier",
+      value: "apps/lxd",
+    });
+    expect(plan.ok).toBe(true);
+    expect(plan.meta).toMatchObject({ planOnly: true, confirmRequired: true });
+    const planLines = (plan.data as { plan: string[] }).plan;
+    expect(planLines.some((line) => line.includes("Write file"))).toBe(true);
+    expect(existsSync(globalConfigPath())).toBe(false);
+
+    const done = await mcp.callTool("config_set", {
+      key: "tier",
+      value: "apps/lxd",
+      confirm: true,
+    });
+    await mcp.cleanup();
+
+    expect(done.ok).toBe(true);
+    expect(done.data).toMatchObject({ field: "tier", value: "apps/lxd" });
+    expect(readGlobal().tier).toBe("apps/lxd");
+  });
+});

package/src/capabilities/config/set.verb.ts

@@ -0,0 +1,70 @@
+/**
+ * `config set <key> <value>` — the one-command config setter (ADDITIVE).
+ *
+ * The single form for writing config: `pragma config set tier apps/lxd`. Since
+ * AV-228 B3 retired the per-field `config tier`/`channel`/`detail` verbs, this
+ * is now the ONLY config setter. It drives the shared write path (`runField` via
+ * `runSet`), so it inherits reset sentinels, enum re-validation, and the
+ * global-layer-only write from the {@link CONFIG_FIELDS} table.
+ *
+ * Covenant shape: `<key>` is an ENUM over the field names (better completion +
+ * validation; the token still emits as `<key>`), `<value>` a free string, so
+ * the verb emits `{ v:"set", args:["<key>","<value>"], mutates:true,
+ * mcp:"config_set" }` — no flags, storeless, exposed to MCP.
+ */
+
+import type { Task } from "@canonical/task";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { configFieldFormatters } from "./field.render.js";
+import { CONFIG_FIELDS } from "./fields.js";
+import type { ConfigFieldResult } from "./types.js";
+
+/** The writable field names, in covenant order — the `<key>` enum. */
+const CONFIG_KEYS = CONFIG_FIELDS.map((field) => field.field);
+
+const setVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
+  path: ["config", "set"],
+  summary: "Set a config field by name.",
+  doc: "Write a global config field by name — the one-command form of the per-field setters. `key` is one of `tier`, `channel`, or `detail`; the field's own reset rules apply (e.g. `set tier none` clears it). Written to the global layer only — project configs are authored by hand.",
+  params: [
+    {
+      kind: "enum",
+      name: "key",
+      doc: "The config field to write.",
+      values: CONFIG_KEYS,
+      required: true,
+      positional: true,
+    },
+    {
+      kind: "string",
+      name: "value",
+      doc: "The value to write (or a field's reset sentinel, e.g. `none`).",
+      required: true,
+      positional: true,
+    },
+  ],
+  output: { formatters: configFieldFormatters },
+  examples: [
+    { cmd: "pragma config set tier apps/lxd", note: "scope reads to a tier" },
+    { cmd: "pragma config set channel experimental" },
+    { cmd: "pragma config set tier none", note: "clear the tier" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: true,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+  },
+  // Lazily import the write body (off the fast path); the `Task` arm is the same
+  // honest cast the per-field verbs use — see fields.ts.
+  run: (params) =>
+    import("./runSet.js").then((m) =>
+      m.runSet(params),
+    ) as unknown as Task<ConfigFieldResult>,
+};
+
+/** The `config set` verb. */
+export const configSetVerb = asVerb(setVerb);

package/src/capabilities/config/show.render.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { type RenderStyle, styleFor } from "../../kernel/render/style.js";
+import { renderConfigShowPlain } from "./show.render.js";
+import type { ConfigShowData } from "./types.js";
+
+const DATA: ConfigShowData = {
+  config: {
+    tier: "apps/lxd",
+    channel: "normal",
+    detail: "standard",
+    packages: ["@canonical/ds"],
+  },
+  origins: {
+    tier: "project",
+    channel: "default",
+    detail: "default",
+    packages: "global",
+    stories: "default",
+    prefixes: "default",
+    prompts: "default",
+  },
+  globalConfigPath: "/home/u/.config/pragma/config.json",
+  projectConfigPath: "/repo/pragma.config.ts",
+  projectExists: true,
+  globalExists: true,
+};
+
+/** A sentinel styler — enabled, each color wrapped in a visible tag. */
+const TAGGED: RenderStyle = {
+  enabled: true,
+  bold: (t) => `<b>${t}</b>`,
+  dim: (t) => `<d>${t}</d>`,
+  cyan: (t) => `<c>${t}</c>`,
+  green: (t) => `<g>${t}</g>`,
+  yellow: (t) => `<y>${t}</y>`,
+};
+
+describe("renderConfigShowPlain", () => {
+  it("is byte-identical to the plain form when the styler is disabled", () => {
+    expect(renderConfigShowPlain(DATA, styleFor(false))).toBe(
+      [
+        "tier: apps/lxd [project]",
+        "channel: normal",
+        "detail: standard",
+        "packages: @canonical/ds [global]",
+        "global config: /home/u/.config/pragma/config.json",
+        "project config: /repo/pragma.config.ts",
+      ].join("\n"),
+    );
+  });
+
+  it("aligns the key column and colorizes values on a TTY", () => {
+    const out = renderConfigShowPlain(DATA, TAGGED);
+    const keyWidth = "project config:".length;
+    // Dim, padded key; cyan value; dim `[layer]` marker.
+    expect(out).toContain(
+      `<d>${"tier:".padEnd(keyWidth)}</d> <c>apps/lxd</c><d> [project]</d>`,
+    );
+    // A default-origin value carries no marker.
+    expect(out).toContain(
+      `<d>${"channel:".padEnd(keyWidth)}</d> <c>normal</c>`,
+    );
+    expect(out).not.toContain("<d> [default]</d>");
+  });
+});

package/src/capabilities/config/show.render.ts

@@ -0,0 +1,107 @@
+/**
+ * Formatters for `pragma config show` — plain, llm, json (no ink).
+ *
+ * Each resolved field carries a `[global]`/`[project]` origin marker so the
+ * user sees which layer won; default values carry no marker. Ported from the
+ * v1 config-show formatters.
+ */
+
+import type { ConfigOrigin } from "../../kernel/config/types.js";
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { ConfigShowData } from "./types.js";
+
+/** A `[layer]` marker for values a config file supplied (blank for defaults). */
+function originMarker(origin: ConfigOrigin): string {
+  return origin === "default" ? "" : ` [${origin}]`;
+}
+
+/** Summarize the `packages` list as a comma-separated set of names. */
+function packageNames(data: ConfigShowData): string {
+  const packages = data.config.packages ?? [];
+  const names = packages.map((entry) =>
+    typeof entry === "string" ? entry : entry.name,
+  );
+  return names.length > 0 ? names.join(", ") : "(none)";
+}
+
+/** One resolved row: its label, value, and `[layer]` marker (blank for a default). */
+type ConfigRow = readonly [label: string, value: string, marker: string];
+
+/** The resolved rows, in display order, shared by the plain + beautified forms. */
+function configRows(data: ConfigShowData): readonly ConfigRow[] {
+  const { config, origins } = data;
+  return [
+    [
+      "tier",
+      config.tier ?? "(none — all tiers visible)",
+      originMarker(origins.tier),
+    ],
+    ["channel", config.channel, originMarker(origins.channel)],
+    ["detail", config.detail ?? "standard", originMarker(origins.detail)],
+    ["packages", packageNames(data), originMarker(origins.packages)],
+    [
+      "global config",
+      `${data.globalConfigPath}${data.globalExists ? "" : " (not found)"}`,
+      "",
+    ],
+    ["project config", data.projectConfigPath ?? "(not found)", ""],
+  ];
+}
+
+/**
+ * Render `config show` as plain text.
+ *
+ * @param data - The resolved config-show payload.
+ * @param style - TTY styling; defaults to the process style. On a color-capable
+ *   terminal the `key:` column is aligned + dim, values cyan, and `[layer]`
+ *   markers dim; off a TTY the styler is inert, so the output is byte-identical
+ *   to the pre-beautify `key: value[marker]` form.
+ * @returns The formatted config block.
+ */
+export function renderConfigShowPlain(
+  data: ConfigShowData,
+  style: RenderStyle = defaultStyle(),
+): string {
+  const rows = configRows(data);
+  if (!style.enabled) {
+    return rows
+      .map(([label, value, marker]) => `${label}: ${value}${marker}`)
+      .join("\n");
+  }
+  const keyWidth = Math.max(...rows.map(([label]) => `${label}:`.length));
+  return rows
+    .map(([label, value, marker]) => {
+      const key = style.dim(`${label}:`.padEnd(keyWidth));
+      const tail = marker ? style.dim(marker) : "";
+      return `${key} ${style.cyan(value)}${tail}`;
+    })
+    .join("\n");
+}
+
+export const configShowFormatters: Formatters<ConfigShowData> = {
+  plain(data) {
+    return renderConfigShowPlain(data);
+  },
+
+  llm(data) {
+    const { config, origins } = data;
+    const lines = [
+      "## Configuration",
+      "",
+      `- **Tier:** ${config.tier ?? "none (all tiers)"}${originMarker(origins.tier)}`,
+      `- **Channel:** ${config.channel}${originMarker(origins.channel)}`,
+      `- **Detail:** ${config.detail ?? "standard"}${originMarker(origins.detail)}`,
+      `- **Packages:** ${packageNames(data)}${originMarker(origins.packages)}`,
+      `- **Global config:** \`${data.globalConfigPath}\``,
+    ];
+    if (data.projectConfigPath) {
+      lines.push(`- **Project config:** \`${data.projectConfigPath}\``);
+    }
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/config/show.verb.ts

@@ -0,0 +1,45 @@
+/**
+ * The `config show` verb spec (noun `config`, verb `show`).
+ *
+ * Storeless read; `run` lazily imports the collector. Config *setters* are a
+ * later PR — this ships only the reader.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { configSetVerb } from "./set.verb.js";
+import { configShowFormatters } from "./show.render.js";
+import type { ConfigShowData } from "./types.js";
+
+const showVerb: VerbSpec<Record<string, unknown>, ConfigShowData> = {
+  path: ["config", "show"],
+  summary: "Show the resolved config and per-field provenance.",
+  doc: "Merges built-in defaults, the global XDG config, and the nearest pragma.config.ts, marking which layer supplied each value.",
+  params: [],
+  output: { formatters: configShowFormatters },
+  examples: [
+    { cmd: "pragma config show" },
+    { cmd: "pragma config show --format json" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./collectConfigShow.js").then((m) => m.collectConfigShow(runtime)),
+};
+
+/**
+ * The `config` capability module: the `show` reader (PR1) and the one-command
+ * `set <key> <value>` setter (PR9), emitted in covenant order. The per-field
+ * `tier`/`channel`/`detail` verbs were retired in favour of `config set`
+ * (AV-228 B3).
+ */
+export const configModule: CapabilityModule = {
+  name: "config",
+  verbs: [asVerb(showVerb), configSetVerb],
+};