@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/capabilities/colophon/types.ts

@@ -2,28 +2,37 @@
  * Data shapes for `pragma colophon`.
  *
  * A colophon (the printer's end-note on how a book is made) for the toolchain:
- * one section narrating how pragma itself is built, followed by one section per
- * active pack/domain that declares a `colophon`. Storeless and read-only.
+ * one section narrating how the distribution itself is built — declared in its
+ * config, not authored in code — followed by one section per active pack/domain
+ * that declares a `colophon`. Storeless and read-only.
  */
 
-/** One colophon section — pragma's own, or an active pack's domain story. */
+/** One colophon section — the distribution's own, or an active pack's story. */
 export interface ColophonSection {
-  /** Whether this is pragma's built-in section or an active pack's. */
+  /**
+   * Whether this is the distribution's declared section or an active pack's.
+   * `"pragma"` is a FROZEN JSON-visible discriminant (wire compatibility, like
+   * the `pragma:` resource scheme) — it does not track the distribution's
+   * name; a fork's own section still carries `kind: "pragma"`.
+   */
   readonly kind: "pragma" | "pack";
-  /** Section heading — `"pragma"`, or the pack's noun/name. */
+  /** Section heading — the distribution's name, or the pack's noun/name. */
   readonly title: string;
   /**
    * The authored Markdown BODY (no leading H1 — the renderer supplies the
    * heading from {@link title}, so a section is never double-titled).
    */
   readonly markdown: string;
-  /** Optional condensed body for `--format llm` (pragma supplies one). */
+  /** Optional condensed body for `--format llm` (the declaration's `summary`). */
   readonly summary?: string;
   /** Provenance: `"built-in"`, or `"pack:<name>"`. */
   readonly source?: string;
 }
 
-/** The full `colophon` payload: pragma's section first, then active packs'. */
+/**
+ * The full `colophon` payload: the distribution's declared section first (when
+ * its config declares one), then active packs'.
+ */
 export interface ColophonData {
   readonly sections: readonly ColophonSection[];
 }

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

@@ -0,0 +1,57 @@
+/**
+ * `config show` payload projection — declared story BODIES never ship.
+ *
+ * MCP returns the JSON formatter's output verbatim, so anything in this payload
+ * is tokens in every `config_show` tool call. The distribution declares five
+ * read stories on its packs, whose bodies are SPARQL; carried through, they take
+ * the payload from ~1.3 KB to ~11 KB — larger than `capabilities`, the discovery
+ * tool, for the least useful content in the surface.
+ */
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import { collectConfigShow } from "./collectConfigShow.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+
+describe("config show payload", () => {
+  it("names the declared packs but carries no story bodies", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-config-show-"));
+    const data = await collectConfigShow(bootRuntime(FLAGS, cwd));
+
+    // The pack declarations themselves are still fully reported…
+    expect(
+      data.config.packs?.map((pack) =>
+        typeof pack === "string" ? pack : pack.name,
+      ),
+    ).toEqual([
+      "@canonical/design-system",
+      "@canonical/anatomy-dsl",
+      "@canonical/code-standards",
+    ]);
+    for (const pack of data.config.packs ?? []) {
+      expect(
+        typeof pack === "string" ? undefined : pack.stories,
+      ).toBeUndefined();
+    }
+    expect(data.config.stories).toBeUndefined();
+
+    // …and provenance stays honest: the payload still says where they came from.
+    expect(data.origins.packs).toBe("default");
+    expect(data.origins.stories).toBe("default");
+
+    // The sharp end: no query text reaches the agent surface.
+    const payload = JSON.stringify(data);
+    expect(payload).not.toContain("SELECT ?");
+    expect(payload.length).toBeLessThan(3000);
+  });
+});

package/src/capabilities/config/collectConfigShow.ts

@@ -1,15 +1,52 @@
 /**
  * Collect the `config show` payload — the verb's run body (lazily imported).
  *
- * Storeless: read the layered config and pass it through with its provenance.
- * Dynamic-imported by the spec so building the tree never pulls the config
- * reader (or zod) onto the fast path.
+ * Storeless: read the layered config and pass it through with its provenance,
+ * minus the declared story BODIES (see {@link withoutStoryBodies}). Dynamic-
+ * imported by the spec so building the tree never pulls the config reader (or
+ * zod) onto the fast path.
  */
 
 import { readConfig } from "../../kernel/config/readConfig.js";
+import type {
+  PackDeclaration,
+  PragmaConfig,
+} from "../../kernel/config/types.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { ConfigShowData } from "./types.js";
 
+/** A pack declaration with any declared story bodies dropped. */
+function nameAndSourceOnly(pack: PackDeclaration): PackDeclaration {
+  if (typeof pack === "string") return pack;
+  return {
+    name: pack.name,
+    ...(pack.source === undefined ? {} : { source: pack.source }),
+  };
+}
+
+/**
+ * The effective config with declared story BODIES dropped — `packs` entries keep
+ * `{ name, source }`, and the top-level `stories` array is omitted.
+ *
+ * A PROJECTION of the payload, not a hiding of config: `origins` still reports
+ * where `packs` and `stories` came from, the plain and llm renders already print
+ * pack NAMES only, and `pragma capabilities` lists the verbs the stories
+ * produce. It exists because the bodies are SPARQL — the distribution's own five
+ * stories take `config show --format json` from 1.3 KB to 11 KB, and MCP returns
+ * the JSON formatter's output, so every `config_show` tool call would carry
+ * ~2.7k tokens of query text: the largest payload in the surface, for its least
+ * useful content.
+ */
+function withoutStoryBodies(config: PragmaConfig): PragmaConfig {
+  const { stories, ...rest } = config;
+  return {
+    ...rest,
+    ...(config.packs === undefined
+      ? {}
+      : { packs: config.packs.map(nameAndSourceOnly) }),
+  };
+}
+
 /**
  * Assemble the resolved config with provenance for the current runtime.
  *
@@ -22,7 +59,7 @@ export async function collectConfigShow(
 ): Promise<ConfigShowData> {
   const layers = await readConfig(runtime.cwd);
   return {
-    config: layers.config,
+    config: withoutStoryBodies(layers.config),
     origins: layers.origins,
     ...(layers.project.path ? { projectConfigPath: layers.project.path } : {}),
     globalConfigPath: layers.global.path,

package/src/capabilities/config/fields.ts

@@ -21,14 +21,8 @@ export interface ConfigFieldSpec {
   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 }[];
 }
 
 /**
@@ -44,38 +38,17 @@ export const CONFIG_FIELDS: readonly ConfigFieldSpec[] = [
     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/set.verb.ts

@@ -14,6 +14,7 @@
  */
 
 import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import { configFieldFormatters } from "./field.render.js";
@@ -46,9 +47,12 @@ const setVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
   ],
   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" },
+    {
+      cmd: `${BIN_NAME} config set tier apps/lxd`,
+      note: "scope reads to a tier",
+    },
+    { cmd: `${BIN_NAME} config set channel experimental` },
+    { cmd: `${BIN_NAME} config set tier none`, note: "clear the tier" },
   ],
   capability: {
     needsStore: false,

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

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 import { type RenderStyle, styleFor } from "../../kernel/render/style.js";
-import { renderConfigShowPlain } from "./show.render.js";
+import { emitReference } from "../../kernel/spec/emitReference.js";
+import { capabilities } from "../index.js";
+import { configShowFormatters, renderConfigShowPlain } from "./show.render.js";
 import type { ConfigShowData } from "./types.js";
 
 const DATA: ConfigShowData = {
@@ -8,16 +10,15 @@ const DATA: ConfigShowData = {
     tier: "apps/lxd",
     channel: "normal",
     detail: "standard",
-    packages: ["@canonical/ds"],
+    packs: ["@canonical/ds"],
   },
   origins: {
     tier: "project",
     channel: "default",
     detail: "default",
-    packages: "global",
+    packs: "global",
     stories: "default",
     prefixes: "default",
-    prompts: "default",
   },
   globalConfigPath: "/home/u/.config/pragma/config.json",
   projectConfigPath: "/repo/pragma.config.ts",
@@ -42,7 +43,7 @@ describe("renderConfigShowPlain", () => {
         "tier: apps/lxd [project]",
         "channel: normal",
         "detail: standard",
-        "packages: @canonical/ds [global]",
+        "packs: @canonical/ds [global]",
         "global config: /home/u/.config/pragma/config.json",
         "project config: /repo/pragma.config.ts",
       ].join("\n"),
@@ -62,4 +63,75 @@ describe("renderConfigShowPlain", () => {
     );
     expect(out).not.toContain("<d> [default]</d>");
   });
+
+  it("renders absent optional fields as (none)", () => {
+    const bare: ConfigShowData = {
+      config: { channel: "normal" },
+      origins: {
+        tier: "default",
+        channel: "default",
+        detail: "default",
+        packs: "default",
+        stories: "default",
+        prefixes: "default",
+      },
+      globalConfigPath: "/home/u/.config/pragma/config.json",
+      projectExists: false,
+      globalExists: false,
+    };
+
+    const out = renderConfigShowPlain(bare, styleFor(false));
+
+    expect(out).toContain("tier: (none)");
+    expect(out).toContain("packs: (none)");
+    expect(out).toContain("project config: (not found)");
+  });
+});
+
+describe("configShowFormatters.llm", () => {
+  it("renders the layered rows with origin markers", () => {
+    const out = configShowFormatters.llm(DATA);
+
+    expect(out).toContain("- **Tier:** apps/lxd [project]");
+    expect(out).toContain("- **Packs:** @canonical/ds [global]");
+  });
+
+  it("reports no identity row, in either form", () => {
+    // Identity is read statically from `pragma.conf.ts`; reporting a layer for
+    // it was reporting a provenance the kernel does not honour. Both renderers
+    // are asserted, because they list their rows independently.
+    for (const out of [
+      renderConfigShowPlain(DATA, styleFor(false)),
+      configShowFormatters.llm(DATA),
+    ]) {
+      for (const field of ["name", "help", "colophon", "issues"]) {
+        expect(out.toLowerCase()).not.toContain(`${field}:`);
+      }
+    }
+  });
+});
+
+describe("the generated configuration reference", () => {
+  it("names exactly the fields this renderer reports with a layer", () => {
+    // The page and the renderer are written independently — the page is kernel
+    // prose, the renderer a capability — and the page's account of the renderer
+    // was wrong in both directions: it claimed every field but `completion`
+    // carried a printed provenance, while `prefixes`, `stories` and the four
+    // distribution-only fields do not, and it claimed `completion` was not
+    // printed, while `--format json` carries it.
+    //
+    // DERIVED from the real formatter: the field rows are the ones before the
+    // two PATH rows, which are not fields at all. Adding a row here without
+    // saying so on the page, or naming a field there this renderer drops, fails.
+    const printed = renderConfigShowPlain(DATA, styleFor(false))
+      .split("\n")
+      .map((line) => line.slice(0, line.indexOf(":")));
+    const fields = printed.slice(0, printed.indexOf("global config"));
+    expect(fields.length).toBeGreaterThan(0);
+
+    const page = emitReference(capabilities).get("config.md") ?? "";
+    expect(page).toContain(
+      `${fields.map((field) => `\`${field}\``).join(", ")} — those and only those —`,
+    );
+  });
 });

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

@@ -16,10 +16,9 @@ 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) =>
+/** Summarize a list of named entries as a comma-separated set of names. */
+function entryNames(entries: readonly (string | { name: string })[]): string {
+  const names = entries.map((entry) =>
     typeof entry === "string" ? entry : entry.name,
   );
   return names.length > 0 ? names.join(", ") : "(none)";
@@ -32,14 +31,10 @@ type ConfigRow = readonly [label: string, value: string, marker: string];
 function configRows(data: ConfigShowData): readonly ConfigRow[] {
   const { config, origins } = data;
   return [
-    [
-      "tier",
-      config.tier ?? "(none — all tiers visible)",
-      originMarker(origins.tier),
-    ],
+    ["tier", config.tier ?? "(none)", originMarker(origins.tier)],
     ["channel", config.channel, originMarker(origins.channel)],
     ["detail", config.detail ?? "standard", originMarker(origins.detail)],
-    ["packages", packageNames(data), originMarker(origins.packages)],
+    ["packs", entryNames(config.packs ?? []), originMarker(origins.packs)],
     [
       "global config",
       `${data.globalConfigPath}${data.globalExists ? "" : " (not found)"}`,
@@ -89,10 +84,10 @@ export const configShowFormatters: Formatters<ConfigShowData> = {
     const lines = [
       "## Configuration",
       "",
-      `- **Tier:** ${config.tier ?? "none (all tiers)"}${originMarker(origins.tier)}`,
+      `- **Tier:** ${config.tier ?? "none"}${originMarker(origins.tier)}`,
       `- **Channel:** ${config.channel}${originMarker(origins.channel)}`,
       `- **Detail:** ${config.detail ?? "standard"}${originMarker(origins.detail)}`,
-      `- **Packages:** ${packageNames(data)}${originMarker(origins.packages)}`,
+      `- **Packs:** ${entryNames(config.packs ?? [])}${originMarker(origins.packs)}`,
       `- **Global config:** \`${data.globalConfigPath}\``,
     ];
     if (data.projectConfigPath) {

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

@@ -5,6 +5,7 @@
  * later PR — this ships only the reader.
  */
 
+import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
 import { configSetVerb } from "./set.verb.js";
@@ -14,12 +15,12 @@ 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.",
+  doc: `Merges built-in defaults, the global XDG config, and the nearest ${PROJECT_CONFIG_FILENAME}, marking which layer supplied each value.`,
   params: [],
   output: { formatters: configShowFormatters },
   examples: [
-    { cmd: "pragma config show" },
-    { cmd: "pragma config show --format json" },
+    { cmd: `${BIN_NAME} config show` },
+    { cmd: `${BIN_NAME} config show --format json` },
   ],
   capability: {
     needsStore: false,

package/src/capabilities/config/types.ts

@@ -6,6 +6,14 @@ import type { ConfigOrigins, PragmaConfig } from "../../kernel/config/types.js";
 
 /** The resolved configuration plus per-field provenance and layer locations. */
 export interface ConfigShowData {
+  /**
+   * The effective config, MINUS declared story bodies: `packs` entries carry
+   * `{ name, source }` only and the top-level `stories` array is omitted. The
+   * bodies are SPARQL, and MCP returns the JSON formatter's output verbatim, so
+   * carrying them would put ~2.7k tokens of query text in every `config_show`
+   * call. `origins` still reports where `packs`/`stories` came from, and
+   * `pragma capabilities` lists the verbs those stories produce.
+   */
   readonly config: PragmaConfig;
   readonly origins: ConfigOrigins;
   readonly projectConfigPath?: string;