@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/spec/emitSurface.ts

@@ -8,6 +8,7 @@
  * envelope, exit codes, budgets, ...). Hidden verbs are excluded.
  */
 
+import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
 import type { CapabilityModule, ParamSpec, VerbSpec } from "./types.js";
 
 /** kebab-case a camelCase param name for its flag form (`allTiers` -> `all-tiers`). */
@@ -74,18 +75,26 @@ export interface EmittedSurface {
  */
 export const FIXED_SURFACE = {
   bins: {
-    pragma: "pragma v2 CLI and MCP server host (stdio)",
+    [BIN_NAME]: `${BIN_NAME} CLI and MCP server host (stdio)`,
   },
   globalFlags: [
     {
       flag: "--format <plain|llm|json>",
       doc: "Select output format (llm = condensed Markdown for agents)",
     },
-    { flag: "--verbose", doc: "Diagnostic output on stderr" },
+    { flag: "--verbose", doc: "Diagnostic output on stderr (sources update)" },
     {
       flag: "--detail <level>",
       doc: "Progressive-disclosure level (summary, standard, detailed)",
     },
+    {
+      flag: "--no-headers",
+      doc: "Hide the table header row in plain output",
+    },
+    {
+      flag: "--quiet",
+      doc: "Suppress success and progress output (errors still print)",
+    },
   ],
   detailLevels: ["summary", "standard", "detailed"],
   envelope: {
@@ -122,14 +131,17 @@ export const FIXED_SURFACE = {
     paramSource: "ParamSpec.complete",
   },
   configFiles: {
-    project: "pragma.config.ts (evaluated, content-hash cached)",
-    global: "$XDG_CONFIG_HOME/pragma/config.json",
-    lock: "$XDG_STATE_HOME/pragma/config-cache/<sha256>.json",
+    project: `${PROJECT_CONFIG_FILENAME} (evaluated, content-hash cached)`,
+    global: `$XDG_CONFIG_HOME/${BIN_NAME}/config.json`,
+    // Named `configCache` because that is what it is: the evaluated project
+    // config's content-addressed cache. It was called `lock` for a project lock
+    // file that no longer exists.
+    configCache: `$XDG_STATE_HOME/${BIN_NAME}/config-cache/<sha256>.json`,
     defaults: "built-in defaults.ts",
   },
   budgets: {
     $comment:
-      "help/complete are the designed <50ms aspiration; the ENFORCED ceilings (budgets.test.ts) are 130ms help / 100ms complete — ~2× the measured median on the build hardware, recorded in BUDGETS.md. Designed-aspiration vs enforced-measured.",
+      "help/complete/warmStoreVerb are designed aspirations; the ENFORCED ceilings (budgets.test.ts) are 130ms help / 100ms complete / 500ms warmStoreVerb, each derived from measurement on the build hardware and recorded in BUDGETS.md. Designed-aspiration vs enforced-measured. warmStoreVerb joined this list when the embedded pack became the distribution's real graph rather than a sample, which puts the reference box's projected p95 over the designed 300ms; BUDGETS.md carries the arithmetic.",
     help: "<50ms",
     complete: "<50ms",
     projectConfigLoad: "<10ms",
@@ -147,8 +159,30 @@ function positionalToken(param: ParamSpec): string {
     : `[${param.name}${variadic}]`;
 }
 
-/** Project one verb into its surface entry, omitting default/falsy fields. */
-export function emitVerb(verb: VerbSpec): EmittedVerb {
+/**
+ * Project one verb into its surface entry, omitting default/falsy fields.
+ *
+ * `flagTokens` is a MOUNTED verb's registered spelling per param name — the
+ * same `ReferenceCliSyntax.flagTokens` seam the reference emitter consumes,
+ * supplied by the module's `cliProjection` and derived there from
+ * `buildOptionInfo` (the single flag-shape authority both binaries register
+ * from; a default-`true` confirm registers ONLY its `--no-<kebab>` form).
+ * Without it the token derives from the param name — the kernel convention,
+ * sound for kernel-registered verbs where B9 ADDS the `--no-` negation
+ * beside the positive form; false for a mounted noun, where kebab-casing
+ * wrote seven covenant tokens the CLI rejects (`--with-styles`, `--ssr`, …).
+ *
+ * `positionalTokens` is the same seam's registered POSITIONAL spelling per
+ * param name (`componentPath` → `[component-path]` — the token the usage
+ * line and the Args tables print), preferred for `args` exactly as
+ * `flagTokens` is for `flags`; a param absent there keeps the kernel
+ * `<name>`/`[name]` derivation.
+ */
+export function emitVerb(
+  verb: VerbSpec,
+  flagTokens?: Readonly<Record<string, string>>,
+  positionalTokens?: Readonly<Record<string, string>>,
+): EmittedVerb {
   const positionals = verb.params.filter((p) => p.positional);
   const flags = verb.params.filter((p) => !p.positional);
 
@@ -161,9 +195,14 @@ export function emitVerb(verb: VerbSpec): EmittedVerb {
     mcp?: string | false;
   } = { v: verbLabel(verb.path) };
 
-  if (positionals.length > 0) entry.args = positionals.map(positionalToken);
+  if (positionals.length > 0)
+    entry.args = positionals.map(
+      (p) => positionalTokens?.[p.name] ?? positionalToken(p),
+    );
   if (flags.length > 0)
-    entry.flags = flags.map((p) => `--${kebabCase(p.name)}`);
+    entry.flags = flags.map(
+      (p) => flagTokens?.[p.name] ?? `--${kebabCase(p.name)}`,
+    );
   if (verb.capability.mutates) entry.mutates = true;
   if (verb.capability.needsStore) entry.needsStore = true;
   entry.mcp = verb.capability.mcp.expose ? toolName(verb.path) : false;
@@ -191,7 +230,14 @@ export function emitSurface(
       const noun = verb.path[0];
       const bucket = nouns[noun] ?? { verbs: [] };
       nouns[noun] = bucket;
-      bucket.verbs.push(emitVerb(verb));
+      // A mounted verb's covenant flags AND args are its REGISTERED
+      // spellings, from the module's own syntax seam (see emitVerb) — the
+      // covenant must name tokens the CLI parses (`--no-with-styles`,
+      // `[component-path]`), not camelCase param names its help never prints.
+      const syntax = module.cliProjection?.referenceSyntax?.(verb.path);
+      bucket.verbs.push(
+        emitVerb(verb, syntax?.flagTokens, syntax?.positionalTokens),
+      );
       if (verb.capability.mcp.expose) tools.push(toolName(verb.path));
     }
     // Non-tool MCP surfaces (module hooks, NOT verbs): the resource template ids

package/src/kernel/spec/surfaceConformance.test.ts

@@ -84,11 +84,13 @@ describe("surface conformance (PROTECTED)", () => {
     );
   });
 
-  it("freezes exactly 38 designed MCP tools including info, config_show, config_set, colophon", () => {
-    expect(golden.mcpSurface.tools).toHaveLength(38);
+  it("freezes exactly 42 designed MCP tools including info, the config family, colophon", () => {
+    expect(golden.mcpSurface.tools).toHaveLength(42);
     expect(golden.mcpSurface.tools).toContain("info");
     expect(golden.mcpSurface.tools).toContain("config_show");
+    expect(golden.mcpSurface.tools).toContain("config_get");
     expect(golden.mcpSurface.tools).toContain("config_set");
+    expect(golden.mcpSurface.tools).toContain("config_unset");
     expect(golden.mcpSurface.tools).toContain("colophon");
   });
 });

package/src/kernel/spec/surfaceConformance.ts

@@ -36,6 +36,14 @@ export interface Covenant {
     readonly resources?: readonly string[];
     readonly prompts?: boolean;
     readonly instructions?: boolean;
+    /**
+     * The wire-identity RULE (L-PR6 covenant extension): `serverInfo` projects
+     * from the distribution, stated as placeholders rather than live values so
+     * the covenant does not churn per release. Documentation for conformance —
+     * `assertConforms` does not deep-check it; `surface.test.ts` pins the rule
+     * text and the live handshake, `identity.test.ts` pins it from a fork.
+     */
+    readonly serverInfo?: { readonly name: string; readonly version: string };
   };
   readonly [section: string]: unknown;
 }

package/src/kernel/spec/types.ts

@@ -11,7 +11,7 @@
  * other param is a kebab-cased flag.
  */
 
-import type { Task } from "@canonical/task";
+import type { Effect, Task } from "@canonical/task";
 import type { PragmaRuntime } from "../runtime/types.js";
 
 /** MCP tool annotations mirrored onto exposed verbs. */
@@ -42,19 +42,28 @@ export type Capability = {
  * `__complete` never boots the graph, so every source is disk-readable: the
  * precomputed pack index, the filesystem, or the prefix table.
  */
-export type CompletionFrom =
-  | "index"
-  | "skills"
-  | "tiers"
-  | "prompts"
-  | "prefixes";
-
-/** A reference to one name source (with an optional prefixed type filter). */
+export type CompletionFrom = "index" | "skills" | "prefixes";
+
+/**
+ * Which of an index entity's name-bearing fields a param completes against.
+ * The kernel knows no entity families — a family is a `type` filter plus the
+ * field that family is addressed by, both declared at the verb.
+ */
+export type CompletionField = "name" | "label" | "altNames";
+
+/** A reference to one name source: where from, and which field of it. */
 export interface CompletionSourceRef {
   /** Which storeless source to read candidate names from. */
   readonly from: CompletionFrom;
   /** Prefixed type filter — meaningful only for `from: "index"` (empty = any). */
   readonly type?: string;
+  /**
+   * Which field the candidates come from — `from: "index"` only, default
+   * `"name"`. Declare the field the verb's lookup MATCHES on: `label` and
+   * `altNames` are optional index enrichment, and an entity carrying neither
+   * contributes no candidate rather than a token the lookup would refuse.
+   */
+  readonly field?: CompletionField;
 }
 
 /** How a partial word is matched against candidate names. */
@@ -102,6 +111,14 @@ export type ParamSpec =
       default?: unknown;
       positional?: boolean;
       complete?: ParamComplete;
+      /**
+       * A repeatable flag ACCUMULATES: `--category css --category git` is
+       * the union, never last-wins (repetition is the sanctioned multi-value
+       * form, and silently dropping all but the last value is data loss).
+       * CLI-side only: the MCP arg schema keeps its scalar shape, and the
+       * run body accepts one value or many.
+       */
+      repeatable?: true;
     }
   | {
       kind: "enum";
@@ -112,6 +129,8 @@ export type ParamSpec =
       default?: string;
       positional?: boolean;
       complete?: ParamComplete;
+      /** See the string variant — repeated occurrences accumulate. */
+      repeatable?: true;
     }
   | {
       kind: "string[]";
@@ -122,11 +141,28 @@ export type ParamSpec =
       complete?: ParamComplete;
     };
 
-/** The three output modes every verb must render. */
+/**
+ * The three output modes every verb must render.
+ *
+ * `plain` takes an optional {@link RenderContext} — the dispatcher's
+ * presentation facts (`--no-headers`, whether stdout is a terminal). Only
+ * list-shaped formatters read it; `llm` (the byte-frozen agent contract) and
+ * `json` (the envelope) never see it.
+ *
+ * `emptyNotice` is the empty-state seam: when the data amounts to zero
+ * records, return the calm notice — the dispatcher routes it to STDERR with
+ * exit 0, keeping the stdout data stream free of human sentences a pipe
+ * would read as records. Return `undefined` (or omit the member) for data
+ * that has content; only the plain mode routes it.
+ */
 export interface Formatters<T> {
-  readonly plain: (d: T) => string;
+  readonly plain: (
+    d: T,
+    context?: import("../render/contracts.js").RenderContext,
+  ) => string;
   readonly llm: (d: T) => string;
   readonly json: (d: T) => string;
+  readonly emptyNotice?: (d: T) => string | undefined;
 }
 
 /** A usage example shown in verb help. */
@@ -153,7 +189,8 @@ export interface ErrorSpec {
  * `run` is the effect seam — a read returns `Promise<R>`; a mutation returns a
  * `Task<R>` the dispatcher interprets under the node / dry-run interpreters. A
  * mutation that needs async setup before its effects are known (e.g.
- * `sources update` resolves and builds before locking) actually returns a
+ * `sources update` resolves and builds before pointing the project at the pack)
+ * actually returns a
  * `Promise<Task<R>>`, which the dispatcher and MCP handler both `await` into a
  * `Task<R>` before interpreting. That third shape is presented through the
  * `Task<R>` arm by a cast at the one call site (`update.verb.ts`): adding a
@@ -166,7 +203,38 @@ export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
   readonly summary: string;
   readonly doc?: string;
   readonly params: readonly ParamSpec[];
-  readonly output: { schema?: unknown; formatters: Formatters<R> };
+  readonly output: {
+    schema?: unknown;
+    formatters: Formatters<R>;
+    /**
+     * OPTIONAL dry-run seam. A `--dry-run` normally renders the raw effect
+     * dump — one `describeEffect` bullet per effect, absolute paths repeated
+     * per line, interpreter internals included — which is debug material, not a
+     * preview a user was meant to read. A verb that has stashed structured plan
+     * data on the runtime (`PragmaRuntime.planData`) can render that instead.
+     *
+     * ABSENT BY DEFAULT, and absent is exactly today's render: a verb that does
+     * not declare this is untouched. The honest preview still runs underneath
+     * either way, so a dry run still fails exactly when the run would.
+     *
+     * The previewed `effects` and the run's verbosity arrive BESIDE the stashed
+     * data, because a plan is not always known before the Task runs: `setup`
+     * computes its target table up front and renders that, while `create` has
+     * nothing to stash — its plan IS the effects the generator produced, which
+     * only exist once the preview interpreter has walked the Task. One seam
+     * serves both by handing the renderer everything the branch knows.
+     *
+     * MAY be async: a renderer whose formatting rules live in another package
+     * loads them behind a dynamic `import()` rather than putting them on the
+     * capabilities barrel's static graph, which every `--help` and
+     * `__complete` spawn pays for. The kernel awaits whatever it returns.
+     */
+    formatPlan?: (
+      planData: unknown,
+      effects: readonly Effect[],
+      verbose: boolean,
+    ) => string | Promise<string>;
+  };
   readonly examples?: readonly Example[];
   readonly disclosure?: DisclosureSpec;
   readonly capability: Capability;
@@ -175,6 +243,52 @@ export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
   readonly hidden?: boolean;
 }
 
+/**
+ * One slice of the index a module contributes to the MCP resource listing.
+ *
+ * Deliberately the vocabulary of {@link CompletionSourceRef} — a listing and a
+ * completion address the same index by the same three facts (which type, which
+ * box, what to yield), and a second vocabulary for that would be a second
+ * writing of one decision. The only source a listing can read is the index, so
+ * `from` is implied and absent.
+ */
+export interface McpListableRef {
+  /** Prefixed type filter (e.g. `ds:Component`) — empty = any type. */
+  readonly type?: string;
+  /** Restrict to schema (`tbox`) or individuals (`abox`); empty = both. */
+  readonly box?: "tbox" | "abox";
+  /**
+   * What the slice yields: `"collection"` lists ONE entry — the class entry
+   * for {@link type}, carrying its instance count — while `"entities"` lists
+   * every matching entity. Default `"entities"`.
+   */
+  readonly as?: "collection" | "entities";
+  /**
+   * Relative importance, 0–1 (default 1). Feeds MCP `annotations.priority` on
+   * the listed resource AND breaks ties in URI-completion ranking, so the two
+   * judgements about what matters most are ONE declaration rather than two
+   * constants in the kernel.
+   */
+  readonly weight?: number;
+}
+
+/**
+ * A module's declared contribution to the MCP resource listing.
+ *
+ * The listing is the UNION of every module's slices. It exists because
+ * `resources/list` has no working pagination in the SDK (the high-level
+ * `McpServer` list handler ignores `request.params.cursor` and never returns
+ * `nextCursor`), so the listing is curated rather than paged: every byte it
+ * spends on connect is context the agent cannot spend on the task.
+ *
+ * DERIVED wherever the module is compiled from a read story — a story already
+ * declares the type set it addresses (`PackLookup.type`/`types`), so its
+ * listing is read off that declaration, never authored a second time.
+ */
+export interface McpListable {
+  readonly sources: readonly McpListableRef[];
+}
+
 /**
  * An MCP resource provider — the ONE non-tool projection a module may add.
  *
@@ -182,11 +296,16 @@ export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
  * autocomplete are storeless over the pack index; a read is store-backed and
  * shares the CLI's entity reader). Resources are NOT tools, so they never enter
  * the emitted tool surface; the projector calls this per module that declares it.
+ *
+ * `register` receives the WHOLE effective module set, not just its own module:
+ * the listing a provider installs is the union of every module's
+ * {@link McpListable}, which no single module can see.
  */
 export interface McpResourceProvider {
   readonly register: (
     server: import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
     rt: PragmaRuntime,
+    modules: readonly CapabilityModule[],
   ) => void;
   /**
    * A static declaration of the resource template ids this provider installs
@@ -214,6 +333,132 @@ export interface McpPromptProvider {
   ) => Promise<void> | void;
 }
 
+/** A flag a mounted subcommand offers to completion (full `--token`). */
+export interface CompletionChildFlag {
+  /** The full flag token (`--no-with-styles`). */
+  readonly flag: string;
+  /** Whether the flag consumes a value. */
+  readonly takesValue: boolean;
+  /** Closed value set for the flag's value, when one exists. */
+  readonly values?: readonly string[];
+}
+
+/** A positional slot a mounted subcommand offers to completion. */
+export interface CompletionChildPositional {
+  /** The slot name (diagnostics only). */
+  readonly name: string;
+  /** Whether the positional is required. */
+  readonly required: boolean;
+  /** Closed value set (e.g. tree segments), when one exists. */
+  readonly values?: readonly string[];
+  /** True when the slot completes file paths natively. */
+  readonly files?: boolean;
+}
+
+/**
+ * The completion surface of one MOUNTED command node: its flags, its
+ * positional slots, and any deeper segment children — static data (it must
+ * pass the completion safety allowlist), never live module state.
+ */
+export interface CompletionChildSpec {
+  /** The command token at this node. */
+  readonly label: string;
+  /** Flags offered at this node. */
+  readonly flags: readonly CompletionChildFlag[];
+  /** Positional slots at this node, in order. */
+  readonly positionals: readonly CompletionChildPositional[];
+  /** Deeper segment children (each with its own flags/positionals/children). */
+  readonly children?: readonly CompletionChildSpec[];
+}
+
+/**
+ * The REGISTERED CLI spelling of one mounted verb — the single syntax seam
+ * every kernel emitter and gate consumes: the reference emitter (usage line
+ * + Args/Flags tables), `emitSurface` (the covenant's mounted-noun flag and
+ * positional tokens, L-CIS-2), and the `docExamples` gate's valid-token
+ * vocabulary. A mounted tree may register a different surface than the
+ * binding-level params suggest (tree segments as subcommands, a
+ * default-true boolean registered only as its `--no-` form), and all three
+ * surfaces must print what the CLI actually accepts — the module supplies
+ * it, the kernel renders it.
+ */
+export interface ReferenceCliSyntax {
+  /**
+   * The usage line after the bin name (e.g.
+   * `create application react [app-path] [options]`) — real tree segments,
+   * the registered positional token.
+   */
+  readonly usage: string;
+  /**
+   * The registered flag token per binding-level param name (e.g.
+   * `withStyles` → `--no-with-styles`). A param absent here renders with the
+   * default `--<kebab-name>` derivation.
+   */
+  readonly flagTokens: Readonly<Record<string, string>>;
+  /**
+   * The registered positional token per binding-level param name (e.g.
+   * `componentPath` → `[component-path]`) — the SAME token the usage line
+   * carries, so the Arguments table never contradicts its own synopsis. A
+   * param absent here renders with the default `<name>`/`[name]` derivation.
+   */
+  readonly positionalTokens?: Readonly<Record<string, string>>;
+}
+
+/** What the program hands a module mounting its own subtree. */
+export interface CliMountHost {
+  /** Global flags for this invocation (closed over by mounted actions). */
+  readonly globalFlags: import("../runtime/types.js").GlobalFlags;
+  /** The binary name (for messages the mounted tree prints). */
+  readonly programName: string;
+}
+
+/**
+ * A module-level CLI projection hook (precedented by `mcpResources`/
+ * `mcpPrompts`/`colophon` — module metadata, NOT a `VerbSpec` field, zero
+ * covenant impact): the module MOUNTS its noun's subtree onto the Commander
+ * parent itself, instead of the generic per-verb attachment. The module's
+ * verbs remain the binding-level grammar (surface, MCP, reference,
+ * completion labels); the mount owns everything beneath the noun.
+ */
+export interface CliProjection {
+  /**
+   * Load the mount's registration machinery, when it is deferred. The
+   * projection hook rides the capabilities barrel, which `--help` and
+   * `__complete` import on every spawn — so a mount whose registration needs
+   * heavy modules (a Commander adapter, shared decision logic) keeps them
+   * behind this async step instead of a static import, and only the one
+   * caller that actually builds the command tree (the bin, before
+   * `buildProgram`) awaits it. {@link mount} stays synchronous and throws
+   * when invoked unprepared, so a future caller cannot silently skip the
+   * step.
+   */
+  readonly prepare?: () => Promise<void>;
+  /** Populate this module's noun parent with its subcommands. */
+  readonly mount: (
+    parent: import("commander").Command,
+    host: CliMountHost,
+  ) => void;
+  /**
+   * The completion surface of the mounted tree, keyed by verb label —
+   * static data the completion model attaches as segment children.
+   */
+  readonly completionChildren: () => Readonly<
+    Record<string, CompletionChildSpec>
+  >;
+  /** Markdown inserted under the noun's heading in the generated reference. */
+  readonly referenceIntro?: string;
+  /**
+   * The registered CLI syntax for one of the noun's binding verbs — the
+   * MOUNTED spelling the reference must print (usage line with tree
+   * segments, flag tokens the CLI actually registers) instead of deriving
+   * tokens from binding-level param names the mounted tree may not register.
+   * Return `undefined` to keep the default rendering for that verb.
+   */
+  readonly referenceSyntax?: (
+    verbPath: VerbSpec["path"],
+  ) => ReferenceCliSyntax | undefined;
+}
+
 /** A capability module: a named bundle of verbs with optional boot/resources/prompts hooks. */
 export interface CapabilityModule {
   readonly name: string;
@@ -225,9 +470,28 @@ export interface CapabilityModule {
    * it has zero covenant impact.
    */
   readonly colophon?: string;
+  /**
+   * This module was compiled — wholly or in part — from a declared read story,
+   * so a story in the user's own CONFIG for the same noun REPLACES it. Authored
+   * modules (config, ontology, doctor, …) carry no story and can never be
+   * replaced; neither can any shipped noun be replaced by a PACKAGE story (see
+   * `kernel/packs/collect.validateStories`). Set where a story is compiled
+   * (`capabilities/distribution.ts` and the three composite nouns), read once,
+   * by `kernel/packs/collect.assembleEffectiveModules`.
+   */
+  readonly story?: true;
   readonly boot?: (rt: PragmaRuntime) => void;
   /** An optional MCP resource surface (NOT a VerbSpec field — a module hook). */
   readonly mcpResources?: McpResourceProvider;
+  /**
+   * The slices of the index this module contributes to the MCP resource
+   * listing (NOT a VerbSpec field — a module hook, like `mcpResources`). A
+   * story-compiled module gets it DERIVED from its lookup's declared types;
+   * only an authored module declares it by hand.
+   */
+  readonly mcpListable?: McpListable;
   /** An optional MCP prompt surface (NOT a VerbSpec field — a module hook). */
   readonly mcpPrompts?: McpPromptProvider;
+  /** An optional CLI mount for the module's noun (NOT a VerbSpec field). */
+  readonly cliProjection?: CliProjection;
 }

package/src/kernel/spec/validate.ts

@@ -17,8 +17,9 @@ const fn = z.custom<(...args: unknown[]) => unknown>(
 );
 
 const completionSourceRefSchema = z.object({
-  from: z.enum(["index", "skills", "tiers", "prompts", "prefixes"]),
+  from: z.enum(["index", "skills", "prefixes"]),
   type: z.string().optional(),
+  field: z.enum(["name", "label", "altNames"]).optional(),
 });
 
 const paramCompleteSchema = z.union([