@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/constants.ts

@@ -1,35 +1,65 @@
 /**
- * Package-level constants for the pragma v2 kernel.
+ * Package-level constants — the distribution's identity, projected.
  *
- * Program metadata (bin name, MCP server name, description, version) plus the
- * stable cross-cutting enums (output formats, detail levels). The CLI binary
- * and the MCP server share the single `pragma` identity, so existing agent
- * wiring keeps resolving the server unchanged.
+ * The bin name, MCP server name, description and issues URL are NOT authored
+ * here: they are read from the distribution config (`pragma.conf.ts`), so a fork
+ * changes values, not code. The import is static because the surfaces that need
+ * identity — `--help`, `__complete`, first-run onboarding, the MCP handshake —
+ * all run before or without the config layer. That is safe precisely because
+ * `pragma.conf.ts` is inert data: a plain object literal whose only import is a
+ * type. It reaches no zod schema, no fs, no evaluator. `capabilities/lazy.test.ts`
+ * pins that boundary, and `src/identity.test.ts` proves the projection.
+ *
+ * Also holds the stable cross-cutting enums: output formats here, and the
+ * detail levels re-exported from `kernel/config/types.ts`, where the config
+ * validator closes the `detail` field over them.
  */
 
 import pkg from "../package.json" with { type: "json" };
+import identity from "../pragma.conf.js";
+import { DETAIL_LEVELS, type DetailLevel } from "./kernel/config/types.js";
 
-/** CLI binary name for the v2 kernel (installed as `pragma`). */
-const BIN_NAME = "pragma";
+/** CLI binary name — the distribution's `name`. */
+const BIN_NAME = identity.name;
 
 /**
- * MCP server identity — `pragma`, matching the CLI bin, so agents already
- * pointed at the pragma server resolve it unchanged.
+ * MCP server identity — the same name as the CLI bin, so agents already pointed
+ * at the server resolve it unchanged. Also the `serverInfo.name` the server
+ * introduces itself with on the wire (paired with {@link VERSION} by
+ * `buildServer`), so a peer reads the distribution's declared name, never a
+ * hardcoded one.
  */
-const MCP_SERVER_NAME = "pragma";
+const MCP_SERVER_NAME = identity.name;
 
 /** One-line program description for help and server metadata. */
-const PROGRAM_DESCRIPTION = "CLI and MCP server for Canonical's design system.";
+const PROGRAM_DESCRIPTION = identity.help;
+
+/** Where the distribution asks users to file issues and feedback. */
+const ISSUES_URL = identity.issuesUrl;
 
 /** Semver version string read from package.json. */
 const VERSION: string = pkg.version;
 
 /**
- * Literal prefix for every `recovery.cli` hint (`pragma `): recovery strings
- * quote the stable, documented command name — matching the bin (D5). The
- * recovery invariant test enforces this.
+ * The project config filename the walker looks for and every surface that
+ * quotes it — diagnostics, the onboarding note, the generated reference, the
+ * surface covenant — names. It lives HERE rather than beside the walker so the
+ * quoting surfaces do not have to import `kernel/config/**`: the storeless
+ * `--help`/`__complete` graph is asserted to reach no config module, and
+ * `completion/safety.test.ts` fails the moment one arrives.
  */
-const RECOVERY_CLI_PREFIX = "pragma ";
+const PROJECT_CONFIG_FILENAME = `${identity.name}.config.ts`;
+
+/**
+ * The distribution's name plus a space: the prefix a `recovery.cli` hint carries
+ * so it quotes a command the installed binary answers to (D5). Kernel hints are
+ * authored through `cliRecovery`, which prepends it; `packs/schema.ts` REJECTS
+ * it in a user-authored pack's `emptyRecovery.cli`, because the CONSUMING
+ * distribution's renderer supplies its own. Use {@link BIN_NAME} for prose —
+ * this constant's trailing space belongs to the recovery invariant, not to
+ * sentences.
+ */
+const RECOVERY_CLI_PREFIX = `${identity.name} `;
 
 /** The output formats the renderer selects between (`llm` = condensed Markdown). */
 const OUTPUT_FORMATS = ["plain", "llm", "json"] as const;
@@ -37,12 +67,6 @@ const OUTPUT_FORMATS = ["plain", "llm", "json"] as const;
 /** A selected output format. `--format text` is normalised to `plain`. */
 type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 
-/** Progressive-disclosure levels, least to most detail. */
-const DETAIL_LEVELS = ["summary", "standard", "detailed"] as const;
-
-/** A progressive-disclosure level. */
-type DetailLevel = (typeof DETAIL_LEVELS)[number];
-
 /** Default detail level when neither flag, config, nor spec pins one. */
 const DEFAULT_DETAIL_LEVEL: DetailLevel = "standard";
 
@@ -51,9 +75,11 @@ export {
   BIN_NAME,
   DEFAULT_DETAIL_LEVEL,
   DETAIL_LEVELS,
+  ISSUES_URL,
   MCP_SERVER_NAME,
   OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
+  PROJECT_CONFIG_FILENAME,
   RECOVERY_CLI_PREFIX,
   VERSION,
 };

package/src/identity.test.ts

@@ -0,0 +1,333 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import chalk from "chalk";
+import { afterAll, afterEach, describe, expect, it, vi } from "vitest";
+import type { VerbSpec } from "./kernel/spec/types.js";
+
+// A fork's distribution config. Everything the kernel says about itself must
+// follow from THIS object — that is the whole claim under test.
+vi.mock("../pragma.conf.js", () => ({
+  default: {
+    name: "recipes",
+    help: "Explore the recipe graph",
+    colophon: {
+      markdown: "Made by the kitchen, one dish at a time.",
+      summary: "Kitchen-made.",
+    },
+    issuesUrl: "https://example.invalid/recipes/issues",
+    packs: [],
+    prefixes: { rcp: "https://example.invalid/recipes/" },
+    channel: "normal",
+    detail: "standard",
+  },
+  // The fork's domain vocabulary, declared beside its identity. Every read of
+  // a domain term must follow from THIS object, which the last case below
+  // asserts by capturing the SPARQL the readers actually emit.
+  vocabulary: {
+    altName: "rcp:name",
+    prompt: {
+      type: "rcp:Prompt",
+      body: "rcp:promptBody",
+      argument: "rcp:promptArgument",
+      argName: "rcp:argName",
+      argRequired: "rcp:argRequired",
+    },
+  },
+}));
+
+/** Anything that would betray THIS distribution leaking through the kernel. */
+const THIS_DISTRIBUTION = /pragma|canonical|design[- ]system/i;
+
+/**
+ * THIS distribution's name alone. The generated reference legitimately carries
+ * bundled-pack CONTENT a fork owns and edits — `@canonical/…` package names in
+ * `create` examples, `ds:`/`cs:` entity values — so the reference probe below
+ * is scoped to the one token that must never survive a rename.
+ */
+const THIS_NAME = /\bpragma\b/i;
+
+// chalk paints ANSI when GITHUB_ACTIONS is set even off a TTY, which would
+// break the plain-text structure assertions below.
+const prevChalkLevel = chalk.level;
+chalk.level = 0;
+afterAll(() => {
+  chalk.level = prevChalkLevel;
+});
+
+const originalConfigHome = process.env.XDG_CONFIG_HOME;
+const originalDataHome = process.env.XDG_DATA_HOME;
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = originalConfigHome;
+  process.env.XDG_DATA_HOME = originalDataHome;
+});
+
+/** A pack-contributed noun the kernel has never heard of. */
+const dishList: VerbSpec = {
+  path: ["dish", "list"],
+  summary: "List every dish in the graph.",
+  params: [],
+  output: {
+    formatters: {
+      plain: (d) => String(d),
+      llm: (d) => String(d),
+      json: (d) => JSON.stringify(d),
+    },
+  },
+  capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+describe("identity projection — a fork changes values, not code (PROTECTED)", () => {
+  it("names the bin, the MCP server, and the recovery prefix from the distribution", async () => {
+    const c = await import("./constants.js");
+    expect(c.BIN_NAME).toBe("recipes");
+    expect(c.MCP_SERVER_NAME).toBe("recipes");
+    expect(c.RECOVERY_CLI_PREFIX).toBe("recipes ");
+    expect(c.PROGRAM_DESCRIPTION).toBe("Explore the recipe graph");
+    expect(c.ISSUES_URL).toBe("https://example.invalid/recipes/issues");
+  });
+
+  it("installs its completion script under the fork's name, in all three shells", async () => {
+    // The basename is load-bearing, not cosmetic — `shell.ts` records what each
+    // shell measurably does with it (fish and bash-completion autoload BY the
+    // command's name; zsh binds by the `#compdef` tag but autoloads a function
+    // named after the file). A mismatch installs a file the shell never loads
+    // while `setup completions` prints success, `doctor` passes, and TAB does
+    // nothing. It can only be pinned from a fork: with the distribution named
+    // `pragma` a hardcoded literal and `BIN_NAME` agree by construction, so a
+    // test in `setup.test.ts` cannot fail. Here they cannot agree by accident.
+    const { completionScriptPath } = await import(
+      "./capabilities/setup/shell.js"
+    );
+    expect(basename(completionScriptPath("zsh"))).toBe("_recipes");
+    expect(basename(completionScriptPath("bash"))).toBe("recipes");
+    expect(basename(completionScriptPath("fish"))).toBe("recipes.fish");
+  });
+
+  it("renders a front door that names only the fork", async () => {
+    const { BIN_NAME, PROGRAM_DESCRIPTION } = await import("./constants.js");
+    const { formatRootHelp } = await import("./kernel/project/cli/rootHelp.js");
+    const { configModule } = await import("./capabilities/config/index.js");
+    const { upgradeModule } = await import("./capabilities/upgrade/index.js");
+    const { colophonModule } = await import("./capabilities/colophon/index.js");
+
+    const help = formatRootHelp(BIN_NAME, PROGRAM_DESCRIPTION, [
+      dishList,
+      ...configModule.verbs,
+      ...upgradeModule.verbs,
+      ...colophonModule.verbs,
+    ]);
+
+    expect(help).not.toMatch(THIS_DISTRIBUTION);
+    expect(help).toMatch(/^recipes — Explore the recipe graph$/m);
+    // The pack noun leads the page untitled, and the blurb is not repeated as
+    // a heading three lines under the header that already carries it.
+    expect(help).toMatch(/^Usage: recipes .*\n\n {2}dish\b/m);
+    expect(help.match(/Explore the recipe graph/g)).toHaveLength(1);
+    expect(help).toContain("Read and write recipes configuration");
+  });
+
+  it("orients an MCP agent with the fork's identity", async () => {
+    const { buildInstructions } = await import(
+      "./kernel/project/mcp/instructions.js"
+    );
+    const { emitSurface } = await import("./kernel/spec/emitSurface.js");
+    const { capabilities } = await import("./capabilities/index.js");
+
+    // The `pragma:` resource scheme is covenant-frozen PROTOCOL identity
+    // (surface.v2.json), not copy. The orientation DERIVES it from the emitted
+    // surface, so mask exactly what the surface declares — a leak the kernel
+    // authored itself would survive this substitution and fail below.
+    const { resources } = emitSurface(capabilities).mcpSurface;
+    expect(resources.length).toBeGreaterThan(0);
+    const text = resources.reduce(
+      (orientation, template) => orientation.replace(template, "<resource>"),
+      buildInstructions(capabilities),
+    );
+
+    expect(text).not.toMatch(THIS_DISTRIBUTION);
+    // No punctuation is appended to the fork's `help` phrase.
+    expect(text.startsWith("recipes — Explore the recipe graph (")).toBe(true);
+  });
+
+  it("greets a first-time user with the fork's issues URL and config file", async () => {
+    process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "identity-"));
+    const { ensureFirstRun } = await import("./kernel/config/firstRun.js");
+    const { globalConfigPath } = await import("./kernel/config/paths.js");
+
+    const lines: string[] = [];
+    await ensureFirstRun((line) => lines.push(line));
+    const greeting = lines.join("\n");
+
+    // Nothing is masked: the resolved config path is IN the greeting, so the
+    // XDG namespace has to follow the fork's name too or this assertion fails.
+    expect(greeting).not.toMatch(THIS_DISTRIBUTION);
+    expect(greeting).toContain(globalConfigPath());
+    expect(globalConfigPath()).toContain("/recipes/");
+    expect(greeting).toContain("https://example.invalid/recipes/issues");
+    expect(greeting).toContain("`recipes.config.ts`");
+  });
+
+  it("narrates the colophon the fork declares, titled with the fork's name", async () => {
+    // The toolchain colophon is DECLARED content (`pragma.conf.ts#colophon`),
+    // not authored code: the collector must render the fork's declaration
+    // under the fork's own name. With no packs declared, the fork's whole
+    // colophon is its own story. `kind: "pragma"` is asserted AS the literal:
+    // it is the frozen JSON discriminant every distribution serves (wire
+    // compatibility, like the resource scheme), deliberately NOT derived.
+    process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "identity-"));
+    const { collectColophon } = await import(
+      "./capabilities/colophon/collectColophon.js"
+    );
+    const { bootRuntime } = await import("./kernel/runtime/boot.js");
+
+    const runtime = bootRuntime(
+      { llm: false, autoLlm: false, format: "plain", verbose: false },
+      mkdtempSync(join(tmpdir(), "identity-colophon-")),
+    );
+    const { sections } = await collectColophon(runtime);
+
+    expect(sections).toHaveLength(1);
+    const own = sections[0];
+    expect(own?.kind).toBe("pragma");
+    expect(own?.title).toBe("recipes");
+    expect(own?.markdown).toBe("Made by the kitchen, one dish at a time.");
+    expect(own?.summary).toBe("Kitchen-made.");
+    expect(own?.source).toBe("built-in");
+    for (const text of [own?.title, own?.markdown, own?.summary]) {
+      expect(text).not.toMatch(THIS_DISTRIBUTION);
+    }
+  });
+
+  it("owns its own on-disk skills namespace", async () => {
+    // Config, state and cache were namespaced by the bin name; the SKILLS roots
+    // were not. Two distributions installed side by side therefore shared one
+    // `$XDG_DATA_HOME/pragma/skills` and one `<cwd>/.pragma/skills`, so a fork
+    // read the other's skills and could not install its own without collision.
+    process.env.XDG_DATA_HOME = join(tmpdir(), "identity-data");
+    const { skillRoots, installedSkillsDir } = await import(
+      "./capabilities/skill/discover.js"
+    );
+    expect(installedSkillsDir().endsWith(join("recipes", "skills"))).toBe(true);
+    expect(skillRoots("/work")).toEqual([
+      join("/work", ".recipes", "skills"),
+      installedSkillsDir(),
+    ]);
+    for (const root of skillRoots("/work")) {
+      expect(root).not.toMatch(THIS_DISTRIBUTION);
+    }
+  });
+
+  it("introduces its MCP server on the wire under the fork's name", async () => {
+    // The wire half of the identity rule the covenant records
+    // (mcpSurface.serverInfo): serverInfo PROJECTS — name from the declared
+    // distribution, version from the package. Asserted through a real
+    // initialize handshake (in-memory transport), not on the constant, so a
+    // hardcoded serverInfo in buildServer would fail here even while
+    // MCP_SERVER_NAME projects correctly.
+    const { projectMcp } = await import("./testing/helpers/projectMcp.js");
+    const { VERSION } = await import("./constants.js");
+
+    const mcp = await projectMcp([]);
+    const wire = mcp.serverInfo();
+    await mcp.cleanup();
+
+    expect(wire).toEqual({ name: "recipes", version: VERSION });
+    expect(wire?.name).not.toMatch(THIS_DISTRIBUTION);
+  });
+
+  it("registers an MCP server entry the fork's own binary answers to", async () => {
+    // The entry `setup mcp` writes is what a harness later EXECUTES. It was
+    // hardcoded while the key it is stored under derived from the same
+    // identity, so a fork registered a `recipes` server that ran `pragma` —
+    // and `doctor`'s `MCP configured` check, which re-derived the key by hand,
+    // could never see its own registration.
+    const { pragmaMcpEntry } = await import(
+      "./capabilities/setup/operations/setupMcp.js"
+    );
+    expect(pragmaMcpEntry("/work")).toEqual({
+      command: "recipes",
+      args: ["mcp"],
+      cwd: "/work",
+    });
+  });
+
+  it("generates a reference that never names this distribution", async () => {
+    // `docs/reference/` is the surface this package PUBLISHES as machine-derived
+    // truth, so it is the surface a fork's rename must reach in full. Every
+    // command a page quotes, every page title and every prose mention is
+    // composed from `BIN_NAME`. The failure names `page: line`, so it is a
+    // worklist and not just a count.
+    //
+    // ONE exemption, the same one the MCP orientation case above makes and for
+    // the same reason: the `pragma:` resource scheme is covenant-frozen PROTOCOL
+    // identity (`surface.v2.json`), inherited by a fork along with the
+    // `pragma/box` and `pragma/instanceCount` `_meta` keys it travels with, and
+    // `tools.md` reports it truthfully. Masked from the emitted surface, not by
+    // a literal, so a leak the kernel authored itself still fails here.
+    const { emitReference } = await import("./kernel/spec/emitReference.js");
+    const { emitSurface } = await import("./kernel/spec/emitSurface.js");
+    const { capabilities } = await import("./capabilities/index.js");
+
+    const { resources } = emitSurface(capabilities).mcpSurface;
+    expect(resources.length).toBeGreaterThan(0);
+    const unmask = (line: string): string =>
+      resources.reduce((text, template) => text.replace(template, ""), line);
+
+    const offenders: string[] = [];
+    for (const [page, content] of emitReference(capabilities)) {
+      for (const line of content.split("\n")) {
+        if (THIS_NAME.test(unmask(line))) offenders.push(`${page}: ${line}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it("reads the graph with the fork's declared terms, not this distribution's", async () => {
+    // The couplings this tranche removed were all hardcoded terms, and a
+    // hardcoded term still passes every other test in this suite: the fixtures
+    // on both sides would simply agree. So capture what the readers EMIT.
+    const { DEFAULT_PREFIX_MAP } = await import("./kernel/render/prefixes.js");
+    const { VOCABULARY } = await import("./kernel/vocabulary.js");
+    const { readPrompts } = await import(
+      "./kernel/project/mcp/prompts/source.js"
+    );
+
+    // The display/expansion map: the fork's namespaces, none of ours, and the
+    // W3C half the kernel owns unchanged.
+    expect(DEFAULT_PREFIX_MAP.rcp).toBe("https://example.invalid/recipes/");
+    expect(DEFAULT_PREFIX_MAP.ds).toBeUndefined();
+    expect(DEFAULT_PREFIX_MAP.rdfs).toBe(
+      "http://www.w3.org/2000/01/rdf-schema#",
+    );
+
+    // The tier noun is no longer code AT ALL (L-OPEN-9): both its verbs are a
+    // story the distribution declares, so a fork writes its own terms into the
+    // declaration directly and there is nothing left in the kernel for a
+    // hardcoded tier term to hide in. `distribution.test.ts` holds this
+    // distribution's declaration coherent with the vocabulary. What the KERNEL
+    // still reads domain terms with is the vocabulary projection (the index
+    // builder interpolates `VOCABULARY.altName`) and the prompts reader —
+    // captured below.
+    expect(VOCABULARY.altName).toBe("rcp:name");
+
+    // The generated prompt read, captured off a stub facade.
+    const queries: string[] = [];
+    const recorder = {
+      query: {
+        sparql: (query: string) => {
+          queries.push(query);
+          return Promise.resolve({ type: "select", bindings: [] });
+        },
+      },
+    } as never;
+
+    await expect(readPrompts(recorder)).resolves.toEqual([]);
+
+    const emitted = queries.join("\n");
+    expect(emitted).toContain("rcp:Prompt");
+    expect(emitted).toContain("rcp:promptBody");
+    expect(emitted).not.toMatch(THIS_DISTRIBUTION);
+  });
+});

package/src/index.ts

@@ -22,8 +22,8 @@ export type {
   Formatters,
   McpAnnotations,
   OutputFormat,
-  PackageDeclaration,
-  PackageEntry,
+  PackDeclaration,
+  PackSource,
   ParamComplete,
   ParamSpec,
   PragmaConfig,

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

@@ -142,6 +142,9 @@ end
 function __pragma_minchars
     test (string length -- (commandline -ct)) -ge $argv[1]
 end
+function __pragma_notflag
+    not string match -q -- '-*' (commandline -ct)
+end
 function __pragma_at
     set -l cmd (commandline -opc)
     set -l noun ''
@@ -185,14 +188,14 @@ complete -c pragma -n "__pragma_at block" -a "diff get list remove"
 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)"
+complete -c pragma -n "__pragma_at block diff; and __pragma_notflag; 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)"
+complete -c pragma -n "__pragma_at block get; and __pragma_notflag; 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

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

@@ -108,7 +108,7 @@ describe("emitScripts — minChars gate + family opt-out", () => {
   });
 });
 
-describe("emitScripts — binName parameterization (PR8 seam)", () => {
+describe("emitScripts — binName parameterization", () => {
   it("defaults to pragma", () => {
     expect(scripts.bash).toContain("complete -F _pragma pragma");
     expect(scripts.zsh.startsWith("#compdef pragma")).toBe(true);

package/src/kernel/completion/emitScripts.ts

@@ -5,12 +5,14 @@
  * derivation the `__complete` resolver uses — the tiers cannot disagree) and
  * renders one script per supported shell. The static tier answers STRUCTURE
  * with zero exec: nouns, verbs, flag names, enum values, mutation + global
- * flags, native file completion. Only `{kind:"entity"}` value contexts shell
+ * flags, native file completion. Only `{kind:"names"}` value contexts shell
  * out to `<bin> __complete`.
  *
  * PR6 boundary (`setup completions`): this module exports pure CONTENT only
  * — shell detection, install paths, mkdir/write effects, and hints all
- * belong to setup. `binName` is parameterized so the PR8 bin swap is free;
+ * belong to setup. `binName` is parameterized so a fork's rename reaches the
+ * script body (`completionScriptPath` derives the file NAME from the same
+ * constant, and the two must agree or the shell never loads the file);
  * `minChars` and `disabledFamilies` are read from `completion` config by setup.
  *
  * `minChars` (default {@link DEFAULT_MIN_CHARS}) is baked into the scripts to