@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/spec/emitSurface.ts

@@ -0,0 +1,225 @@
+/**
+ * Surface emitter: project capability modules into the machine-readable
+ * surface document that the covenant (`surface/surface.v2.json`) freezes.
+ *
+ * The emitter is pure and zod-free so it sits on the `--help`/`__complete`
+ * fast path. It reads only the grammar — never a run body — and merges in the
+ * fixed kernel sections that describe the invariant contract (bins, flags,
+ * envelope, exit codes, budgets, ...). Hidden verbs are excluded.
+ */
+
+import type { CapabilityModule, ParamSpec, VerbSpec } from "./types.js";
+
+/** kebab-case a camelCase param name for its flag form (`allTiers` -> `all-tiers`). */
+export function kebabCase(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/** The MCP tool name for a verb path (`["config","show"]` -> `config_show`). */
+export function toolName(path: readonly [string, string?]): string {
+  const [noun, verb] = path;
+  return verb ? `${noun}_${verb}` : noun;
+}
+
+/** The verb label within its noun (last path segment; the noun itself when self-verb). */
+export function verbLabel(path: readonly [string, string?]): string {
+  return path[1] ?? path[0];
+}
+
+/** One verb as it appears in the surface document. Optional fields omitted when falsy/default. */
+export interface EmittedVerb {
+  readonly v: string;
+  readonly args?: readonly string[];
+  readonly flags?: readonly string[];
+  readonly mutates?: true;
+  readonly needsStore?: true;
+  readonly mcp?: string | false;
+  readonly note?: string;
+}
+
+/**
+ * The MCP surface the covenant freezes: the tool set PLUS the non-tool surfaces
+ * (PR7 covenant extension). `resources` are the resource template ids providers
+ * declare; `prompts` marks whether any module offers the native `prompts/*`
+ * surface; `instructions` marks that the server carries handshake instructions
+ * (always true — buildServer sets it unconditionally). Prompt NAMES are graph
+ * DATA, not grammar, so they are guarded by the prompt tests, not frozen here.
+ */
+export interface McpSurface {
+  readonly tools: string[];
+  readonly resources: string[];
+  readonly prompts: boolean;
+  readonly instructions: boolean;
+}
+
+/** The full surface document: live nouns/tools plus the fixed kernel sections. */
+export interface EmittedSurface {
+  readonly nouns: Record<string, { verbs: EmittedVerb[] }>;
+  readonly mcpSurface: McpSurface;
+  readonly bins: typeof FIXED_SURFACE.bins;
+  readonly globalFlags: typeof FIXED_SURFACE.globalFlags;
+  readonly detailLevels: typeof FIXED_SURFACE.detailLevels;
+  readonly envelope: typeof FIXED_SURFACE.envelope;
+  readonly exitCodes: typeof FIXED_SURFACE.exitCodes;
+  readonly mutationContract: typeof FIXED_SURFACE.mutationContract;
+  readonly completion: typeof FIXED_SURFACE.completion;
+  readonly configFiles: typeof FIXED_SURFACE.configFiles;
+  readonly budgets: typeof FIXED_SURFACE.budgets;
+}
+
+/**
+ * The invariant kernel contract, merged into every emitted surface and frozen
+ * verbatim in the covenant. This is the single authoring point — the golden
+ * embeds a copy and conformance deep-equals the two, so drift is caught.
+ */
+export const FIXED_SURFACE = {
+  bins: {
+    pragma: "pragma v2 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: "--detail <level>",
+      doc: "Progressive-disclosure level (summary, standard, detailed)",
+    },
+  ],
+  detailLevels: ["summary", "standard", "detailed"],
+  envelope: {
+    success: { ok: true, data: "<payload>", meta: "<object>" },
+    error: {
+      ok: false,
+      error: {
+        code: "<ErrorCode>",
+        message: "<string>",
+        suggestions: "string[]?",
+        recovery: "Recovery?",
+        validOptions: "string[]?",
+        filters: "object?",
+      },
+    },
+  },
+  exitCodes: {
+    "0": "success",
+    "1": "runtime (entity-not-found, empty, config, internal)",
+    "2": "usage (invalid/ambiguous input, unknown verb)",
+    "3": "store unavailable",
+  },
+  mutationContract: {
+    cli: { dryRun: "--dry-run", undo: "--undo", confirm: "--yes" },
+    mcp: {
+      planFirst: true,
+      confirmParam: "confirm",
+      planMeta: { planOnly: true, confirmRequired: true },
+    },
+  },
+  completion: {
+    static: "shell script tier emitted by `setup completions`",
+    dynamic: "hidden `__complete` resolver, storeless",
+    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",
+    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: "<50ms",
+    complete: "<50ms",
+    projectConfigLoad: "<10ms",
+    warmStoreVerb: "<300ms",
+    mcpP95Warm: "<100ms",
+    condensedSDL: "<=8000 tokens",
+  },
+} as const;
+
+/** Format a positional param as its usage token (`<name>` required, `[name]` optional). */
+function positionalToken(param: ParamSpec): string {
+  const variadic = param.kind === "string[]" ? "..." : "";
+  return param.required
+    ? `<${param.name}${variadic}>`
+    : `[${param.name}${variadic}]`;
+}
+
+/** Project one verb into its surface entry, omitting default/falsy fields. */
+export function emitVerb(verb: VerbSpec): EmittedVerb {
+  const positionals = verb.params.filter((p) => p.positional);
+  const flags = verb.params.filter((p) => !p.positional);
+
+  const entry: {
+    v: string;
+    args?: string[];
+    flags?: string[];
+    mutates?: true;
+    needsStore?: true;
+    mcp?: string | false;
+  } = { v: verbLabel(verb.path) };
+
+  if (positionals.length > 0) entry.args = positionals.map(positionalToken);
+  if (flags.length > 0)
+    entry.flags = flags.map((p) => `--${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;
+
+  return entry;
+}
+
+/**
+ * Emit the full surface document for a set of capability modules.
+ *
+ * @param modules - The capability modules to project (hidden verbs excluded).
+ * @returns The surface document: live nouns + sorted tools + fixed sections.
+ */
+export function emitSurface(
+  modules: readonly CapabilityModule[],
+): EmittedSurface {
+  const nouns: Record<string, { verbs: EmittedVerb[] }> = {};
+  const tools: string[] = [];
+  const resources: string[] = [];
+  let prompts = false;
+
+  for (const module of modules) {
+    for (const verb of module.verbs) {
+      if (verb.hidden) continue;
+      const noun = verb.path[0];
+      const bucket = nouns[noun] ?? { verbs: [] };
+      nouns[noun] = bucket;
+      bucket.verbs.push(emitVerb(verb));
+      if (verb.capability.mcp.expose) tools.push(toolName(verb.path));
+    }
+    // Non-tool MCP surfaces (module hooks, NOT verbs): the resource template ids
+    // the provider declares, and whether a native prompt surface is offered.
+    if (module.mcpResources?.surface) {
+      resources.push(...module.mcpResources.surface.templates);
+    }
+    if (module.mcpPrompts) prompts = true;
+  }
+
+  return {
+    nouns,
+    mcpSurface: {
+      tools: tools.sort(),
+      resources: resources.sort(),
+      prompts,
+      // The server always carries handshake instructions (buildServer sets them
+      // unconditionally), so this is an invariant true — a stable presence marker.
+      instructions: true,
+    },
+    bins: FIXED_SURFACE.bins,
+    globalFlags: FIXED_SURFACE.globalFlags,
+    detailLevels: FIXED_SURFACE.detailLevels,
+    envelope: FIXED_SURFACE.envelope,
+    exitCodes: FIXED_SURFACE.exitCodes,
+    mutationContract: FIXED_SURFACE.mutationContract,
+    completion: FIXED_SURFACE.completion,
+    configFiles: FIXED_SURFACE.configFiles,
+    budgets: FIXED_SURFACE.budgets,
+  };
+}

package/src/kernel/spec/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Spec kernel barrel — the grammar and its zod-free projections.
+ *
+ * `validate.ts` (zod) is intentionally NOT re-exported here: it is imported
+ * directly, and lazily, by the registration seams so this barrel — and the
+ * `--help`/`__complete` path that reaches it — stays free of zod.
+ */
+
+export type { ReferenceDocs } from "./emitReference.js";
+export { emitReference } from "./emitReference.js";
+export type {
+  EmittedSurface,
+  EmittedVerb,
+} from "./emitSurface.js";
+export {
+  emitSurface,
+  emitVerb,
+  FIXED_SURFACE,
+  kebabCase,
+  toolName,
+  verbLabel,
+} from "./emitSurface.js";
+export type { Covenant } from "./surfaceConformance.js";
+export { assertConforms, deepEqual } from "./surfaceConformance.js";
+export type {
+  Capability,
+  CapabilityModule,
+  DisclosureSpec,
+  Example,
+  Formatters,
+  McpAnnotations,
+  McpResourceProvider,
+  ParamComplete,
+  ParamSpec,
+  VerbSpec,
+} from "./types.js";

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

@@ -0,0 +1,94 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { fixtureModule } from "../../testing/fixtures/fixtureCapability.js";
+import { emitSurface } from "./emitSurface.js";
+import {
+  assertConforms,
+  type Covenant,
+  deepEqual,
+} from "./surfaceConformance.js";
+
+/** The committed covenant, read from disk exactly as a consumer would. */
+const golden = JSON.parse(
+  readFileSync(
+    fileURLToPath(new URL("../../../surface/surface.v2.json", import.meta.url)),
+    "utf-8",
+  ),
+) as Covenant;
+
+describe("deepEqual", () => {
+  it("compares JSON-shaped values structurally", () => {
+    expect(deepEqual({ a: 1, b: [2, 3] }, { b: [2, 3], a: 1 })).toBe(true);
+    expect(deepEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false);
+    expect(deepEqual([1, 2], [2, 1])).toBe(false);
+    expect(deepEqual("x", "x")).toBe(true);
+  });
+});
+
+describe("surface conformance (PROTECTED)", () => {
+  it("the committed golden's fixed sections match the live emitter", () => {
+    // Emitting no modules conforms iff the golden's fixed sections agree with
+    // FIXED_SURFACE — the golden and the kernel constant cannot drift apart.
+    expect(() => assertConforms(emitSurface([]), golden)).not.toThrow();
+  });
+
+  it("accepts a surface whose emitted entries are all in the covenant", () => {
+    const covenant: Covenant = {
+      ...golden,
+      nouns: {
+        ...golden.nouns,
+        widget: {
+          verbs: [
+            { v: "list", mcp: "widget_list" },
+            {
+              v: "make",
+              args: ["<name>"],
+              flags: ["--with-history"],
+              mutates: true,
+              needsStore: true,
+              mcp: "widget_make",
+            },
+          ],
+        },
+      },
+      mcpSurface: {
+        tools: [...golden.mcpSurface.tools, "widget_list", "widget_make"],
+      },
+    };
+    expect(() =>
+      assertConforms(emitSurface([fixtureModule]), covenant),
+    ).not.toThrow();
+  });
+
+  it("rejects an emitted verb that drifts from the covenant", () => {
+    const covenant: Covenant = {
+      ...golden,
+      nouns: {
+        ...golden.nouns,
+        widget: { verbs: [{ v: "list", mcp: "widget_list_WRONG" }] },
+      },
+      mcpSurface: {
+        tools: [...golden.mcpSurface.tools, "widget_list", "widget_make"],
+      },
+    };
+    expect(() =>
+      assertConforms(emitSurface([fixtureModule]), covenant),
+    ).toThrow(/does not match the covenant/);
+  });
+
+  it("rejects an emitted tool the covenant does not bless", () => {
+    // Same golden, but the fixture's tools are absent from mcpSurface.tools.
+    expect(() => assertConforms(emitSurface([fixtureModule]), golden)).toThrow(
+      /is not in the covenant/,
+    );
+  });
+
+  it("freezes exactly 38 designed MCP tools including info, config_show, config_set, colophon", () => {
+    expect(golden.mcpSurface.tools).toHaveLength(38);
+    expect(golden.mcpSurface.tools).toContain("info");
+    expect(golden.mcpSurface.tools).toContain("config_show");
+    expect(golden.mcpSurface.tools).toContain("config_set");
+    expect(golden.mcpSurface.tools).toContain("colophon");
+  });
+});

package/src/kernel/spec/surfaceConformance.ts

@@ -0,0 +1,135 @@
+/**
+ * Frozen-covenant conformance (D1).
+ *
+ * `surface/surface.v2.json` is the designed, frozen surface. Each PR emits
+ * only the entries it has actually built and asserts that its emitted surface
+ * *conforms* to the covenant: every emitted noun+verb exists in the covenant
+ * and deep-equals it, every emitted tool is one the covenant blesses, and the
+ * fixed kernel sections match verbatim. The covenant may hold entries no PR
+ * emits yet (the future surface) — conformance is one-directional
+ * (emitted subset of covenant), so later PRs re-snapshot their slice in-diff
+ * without disturbing this one.
+ */
+
+import type { EmittedSurface, EmittedVerb } from "./emitSurface.js";
+
+/** The fixed kernel sections a covenant must match verbatim. */
+const FIXED_SECTIONS = [
+  "bins",
+  "globalFlags",
+  "detailLevels",
+  "envelope",
+  "exitCodes",
+  "mutationContract",
+  "completion",
+  "configFiles",
+  "budgets",
+] as const;
+
+/** The covenant document shape (the parsed golden), navigated defensively. */
+export interface Covenant {
+  readonly nouns: Record<string, { verbs: readonly EmittedVerb[] }>;
+  readonly mcpSurface: {
+    readonly tools: readonly string[];
+    /** Non-tool MCP surface (PR7 covenant extension) — optional so a synthetic
+     * covenant that pins only `tools` still conforms. */
+    readonly resources?: readonly string[];
+    readonly prompts?: boolean;
+    readonly instructions?: boolean;
+  };
+  readonly [section: string]: unknown;
+}
+
+/** Order-sensitive structural deep-equality for JSON-shaped values. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+      return false;
+    }
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (typeof a !== "object") return false;
+  const aObj = a as Record<string, unknown>;
+  const bObj = b as Record<string, unknown>;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((key) => key in bObj && deepEqual(aObj[key], bObj[key]));
+}
+
+/**
+ * Assert that an emitted surface conforms to the covenant.
+ *
+ * @param emitted - The surface produced by {@link emitSurface}.
+ * @param covenant - The parsed `surface.v2.json` golden.
+ * @throws Error with a specific path on the first non-conformance.
+ */
+export function assertConforms(
+  emitted: EmittedSurface,
+  covenant: Covenant,
+): void {
+  for (const [noun, { verbs }] of Object.entries(emitted.nouns)) {
+    const covNoun = covenant.nouns[noun];
+    if (!covNoun) {
+      throw new Error(`surface: emitted noun "${noun}" is not in the covenant`);
+    }
+    for (const verb of verbs) {
+      const covVerb = covNoun.verbs.find((entry) => entry.v === verb.v);
+      if (!covVerb) {
+        throw new Error(
+          `surface: emitted verb "${noun} ${verb.v}" is not in the covenant`,
+        );
+      }
+      if (!deepEqual(verb, covVerb)) {
+        throw new Error(
+          `surface: emitted verb "${noun} ${verb.v}" does not match the covenant\n` +
+            `  emitted:  ${JSON.stringify(verb)}\n` +
+            `  covenant: ${JSON.stringify(covVerb)}`,
+        );
+      }
+    }
+  }
+
+  const blessed = new Set(covenant.mcpSurface.tools);
+  for (const tool of emitted.mcpSurface.tools) {
+    if (!blessed.has(tool)) {
+      throw new Error(`surface: emitted tool "${tool}" is not in the covenant`);
+    }
+  }
+
+  // Non-tool MCP surface (PR7 covenant extension), checked with the same subset
+  // semantics as tools and ONLY when the covenant declares the section — so an
+  // emitted-empty surface still conforms and synthetic tool-only covenants pass.
+  const cov = covenant.mcpSurface;
+  if (cov.resources) {
+    const blessedResources = new Set(cov.resources);
+    for (const template of emitted.mcpSurface.resources) {
+      if (!blessedResources.has(template)) {
+        throw new Error(
+          `surface: emitted resource template "${template}" is not in the covenant`,
+        );
+      }
+    }
+  }
+  if (cov.prompts !== undefined && emitted.mcpSurface.prompts && !cov.prompts) {
+    throw new Error(
+      "surface: emitted a prompts surface the covenant does not bless",
+    );
+  }
+  if (
+    cov.instructions !== undefined &&
+    emitted.mcpSurface.instructions !== cov.instructions
+  ) {
+    throw new Error("surface: instructions marker does not match the covenant");
+  }
+
+  for (const section of FIXED_SECTIONS) {
+    if (!deepEqual(emitted[section], covenant[section])) {
+      throw new Error(
+        `surface: fixed section "${section}" does not match the covenant`,
+      );
+    }
+  }
+}