@canonical/pragma-cli 0.32.0 → 0.33.0

package/src/kernel/project/mcp/mcpError.ts

@@ -0,0 +1,52 @@
+/**
+ * Project a {@link PragmaError} into an SDK `McpError` for the NATIVE MCP
+ * surfaces (the `prompts/*` provider, the `pragma:{+uri}` resource browser),
+ * which signal failure by throwing a JSON-RPC error rather than by returning the
+ * `{ ok, error }` tool envelope.
+ *
+ * A native read must not swallow a failure into plain-text "success" content: it
+ * carries the machine `code` AND the structured `recovery` into the JSON-RPC
+ * `data`, so an agent that hits a cold store over `prompts/list` or a resource
+ * read sees the SAME `STORE_UNAVAILABLE` + `sources_update` recovery the tool
+ * envelope carries — never a bare string with the recovery dropped.
+ *
+ * The SDK's `McpError`/`ErrorCode` are PASSED IN by the caller (which already
+ * dynamic-imported them in its `register`), so this module — reachable on the
+ * capabilities import graph — never statically pulls the SDK onto the
+ * `--help`/`__complete` fast path.
+ */
+
+import type { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import type { PragmaError } from "../../error/PragmaError.js";
+
+/** The SDK error primitives a provider dynamic-imports and hands to {@link mcpErrorFrom}. */
+export interface McpErrorPrimitives {
+  readonly McpError: typeof McpError;
+  readonly ErrorCode: typeof ErrorCode;
+}
+
+/**
+ * Build an `McpError` from a {@link PragmaError}, mapping the machine code to a
+ * JSON-RPC code and preserving `code`/`recovery`/`suggestions`/`validOptions` in
+ * `data`.
+ *
+ * @param error - The structured pragma error to project.
+ * @param primitives - The SDK `McpError`/`ErrorCode` the caller imported.
+ * @returns An `McpError` carrying the diagnostic + recovery in its `data`.
+ */
+export function mcpErrorFrom(
+  error: PragmaError,
+  { McpError: McpErrorCtor, ErrorCode: ErrorCodeEnum }: McpErrorPrimitives,
+): McpError {
+  // A bad/missing entity or rejected input is the caller's fault (InvalidParams);
+  // an unreachable store or internal fault is the server's (InternalError).
+  const jsonRpcCode =
+    error.code === "ENTITY_NOT_FOUND" || error.code === "INVALID_INPUT"
+      ? ErrorCodeEnum.InvalidParams
+      : ErrorCodeEnum.InternalError;
+  const data: Record<string, unknown> = { code: error.code };
+  if (error.recovery) data.recovery = error.recovery;
+  if (error.suggestions.length > 0) data.suggestions = error.suggestions;
+  if (error.validOptions) data.validOptions = error.validOptions;
+  return new McpErrorCtor(jsonRpcCode, error.message, data);
+}

package/src/kernel/project/mcp/prompts/prompts.test.ts

@@ -47,6 +47,14 @@ describe("instructions — handshake orientation (PROTECTED)", () => {
     );
   });
 
+  it("states the plan-first/confirm convention in the orientation (D2)", () => {
+    // The confirm gate must be surfaced at handshake, not discovered by an agent
+    // tripping it. Same single source as the `capabilities` tool's conventions.
+    const text = buildInstructions(capabilities);
+    expect(text.toLowerCase()).toContain("plan-first");
+    expect(text).toContain("confirm: true");
+  });
+
   it("orients a cold agent to check/build the store before any store read", () => {
     // Store-blind guard: the handshake must point a cold agent at the store
     // pre-check (sources_status → sources_update) BEFORE the sample/query steps,

package/src/kernel/project/mcp/prompts/provider.ts

@@ -10,9 +10,19 @@
  * arguments. The SDK request schemas are dynamic-imported inside `register`, so
  * this module — reachable on the capabilities import graph through the prompt
  * module — never pulls the SDK types onto the `--help`/`__complete` fast path.
+ *
+ * Both handlers open with a STORELESS cold-store pre-check ({@link
+ * checkStoreAvailable}) so the native surface converges with the store-backed
+ * `prompt_list` tool: a cold store surfaces the SAME `STORE_UNAVAILABLE` +
+ * `sources_update` recovery here as the tool's `needsStore` guard raises, rather
+ * than a silent `[]` (list) or a bogus "not found" (get) that masks the cold
+ * store. When the store is available (including the embedded fallback) both
+ * handlers behave exactly as before.
  */
 
+import { checkStoreAvailable } from "../../../runtime/storeReadiness.js";
 import type { McpPromptProvider } from "../../../spec/types.js";
+import { mcpErrorFrom } from "../mcpError.js";
 import { listPromptSummaries, readPrompt } from "./source.js";
 
 /** Substitute `{{arg}}` placeholders in a template body with provided values. */
@@ -41,17 +51,37 @@ export const promptProvider: McpPromptProvider = {
     // of whether the active graph ships prompt entities.
     server.server.registerCapabilities({ prompts: { listChanged: false } });
 
-    server.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-      prompts: listPromptSummaries(runtime).map((prompt) => ({
-        name: prompt.name,
-        ...(prompt.description ? { description: prompt.description } : {}),
-      })),
-    }));
+    // A STORELESS cold-store pre-check, shared with the store-backed `prompt_list`
+    // tool (whose `needsStore` guard throws) and the resource browser: a cold
+    // store must present the SAME STORE_UNAVAILABLE + `sources_update` recovery on
+    // native `prompts/*` as on the tool surface, not silently list from a stale
+    // index (or `[]`) here while the tool errors. Available (incl. the embedded
+    // fallback) → the native list stays storeless and the get stays store-backed.
+    const guardStore = async (): Promise<void> => {
+      const unavailable = checkStoreAvailable(
+        await runtime.loadConfig(),
+        runtime.cwd,
+      );
+      if (unavailable) throw mcpErrorFrom(unavailable, { McpError, ErrorCode });
+    };
+
+    server.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      await guardStore();
+      return {
+        prompts: listPromptSummaries(runtime).map((prompt) => ({
+          name: prompt.name,
+          ...(prompt.description ? { description: prompt.description } : {}),
+        })),
+      };
+    });
 
     server.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      await guardStore();
       const { name, arguments: args } = request.params;
       const entry = await readPrompt(runtime, name);
       if (!entry) {
+        // Reached only when the store IS available — a genuine miss, not a cold
+        // store (which `guardStore` already surfaced as STORE_UNAVAILABLE).
         throw new McpError(
           ErrorCode.InvalidParams,
           `Prompt "${name}" not found`,

package/src/kernel/render/formatters.ts

@@ -3,9 +3,10 @@
  *
  * The grammar's {@link Formatters} (plain / llm / json — no ink field) is the
  * per-verb output contract. {@link selectFormatter} picks one by the parsed
- * global flags with a fixed precedence: `--format json` wins, then `--llm`,
- * then the plain terminal default. The dispatcher uses the plain/llm branches
- * directly and wraps the json branch in the machine envelope (D3).
+ * global flags with a fixed precedence: `--format json` wins, then the llm mode
+ * (`--format llm` or auto-detected on a non-interactive stdout), then the plain
+ * terminal default. The dispatcher uses the plain/llm branches directly and
+ * wraps the json branch in the machine envelope (D3).
  */
 
 import type { GlobalFlags } from "../runtime/types.js";
@@ -14,7 +15,7 @@ import type { Formatters } from "../spec/types.js";
 /**
  * Pick the formatter for the active output mode.
  *
- * Precedence: `--format json` > `--llm` > plain.
+ * Precedence: `--format json` > llm (`--format llm` / auto-detected) > plain.
  *
  * @param flags - The parsed global flags for this invocation.
  * @param formatters - The verb's three-mode formatter set.

package/src/kernel/render/renderers.test.ts

@@ -14,6 +14,7 @@ import {
   renderLookupLlm,
   renderLookupPlain,
 } from "./renderers.js";
+import { type RenderStyle, styleFor } from "./style.js";
 
 interface Widget {
   readonly uri: string;
@@ -144,6 +145,39 @@ describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () =>
   });
 });
 
+describe("lookup beautify (TTY style seam)", () => {
+  const lookupOpts = {
+    title: (w: Widget) => w.name,
+    fields: fieldsFor("standard"),
+    sections: sectionsFor("standard"),
+  };
+
+  it("bolds the title, dims the rule, and cyans field labels on a TTY", () => {
+    const tagged: RenderStyle = {
+      enabled: true,
+      bold: (t) => `B(${t})`,
+      dim: (t) => `D(${t})`,
+      cyan: (t) => `C(${t})`,
+      green: (t) => t,
+      yellow: (t) => t,
+    };
+    const lines = renderLookupPlain(
+      widgets[0] as Widget,
+      lookupOpts,
+      tagged,
+    ).split("\n");
+    expect(lines.at(0)).toBe("B(Button)");
+    expect(lines.at(1)).toBe(`D(${"═".repeat(24)})`);
+    expect(lines).toContain("  C(Kind): component");
+  });
+
+  it("is byte-identical to the plain lookup when the styler is disabled", () => {
+    expect(
+      renderLookupPlain(widgets[0] as Widget, lookupOpts, styleFor(false)),
+    ).toBe(`Button\n${"═".repeat(24)}\n\n  Kind: component`);
+  });
+});
+
 describe("error render matrix (× plain/llm/json)", () => {
   it("renders each error across the three formats", () => {
     const notFound = PragmaError.notFound("block", "Buton", {

package/src/kernel/render/renderers.ts

@@ -15,6 +15,7 @@ import type {
   SectionDef,
 } from "./contracts.js";
 import { DEFAULT_PREFIX_MAP } from "./prefixes.js";
+import { defaultStyle, type RenderStyle, styleFor } from "./style.js";
 
 type RenderMode = "plain" | "llm";
 
@@ -104,27 +105,40 @@ export function renderListLlm<T>(
   return lines.join("\n");
 }
 
+/**
+ * Render an entity lookup as plain text.
+ *
+ * @param entity - The looked-up entity.
+ * @param options - The lookup layout (title, fields, sections).
+ * @param style - TTY styling; defaults to the process style. On a color-capable
+ *   terminal the title is bold, its `═` rule dim, and field labels cyan; off a
+ *   TTY the styler is inert, so the output is byte-identical to the plain form.
+ * @returns The formatted lookup block.
+ */
 export function renderLookupPlain<T>(
   entity: T,
   options: RenderLookupOptions<T>,
+  style: RenderStyle = defaultStyle(),
 ): string {
-  return renderLookup(entity, options, "plain");
+  return renderLookup(entity, options, "plain", style);
 }
 
 export function renderLookupLlm<T>(
   entity: T,
   options: RenderLookupOptions<T>,
 ): string {
-  return renderLookup(entity, options, "llm");
+  // The condensed form is a byte-frozen agent contract — never styled.
+  return renderLookup(entity, options, "llm", styleFor(false));
 }
 
 function renderLookup<T>(
   entity: T,
   options: RenderLookupOptions<T>,
   mode: RenderMode,
+  style: RenderStyle,
 ): string {
   const title = options.title(entity);
-  const fields = renderLookupFields(entity, options, mode);
+  const fields = renderLookupFields(entity, options, mode, style);
   const sections = renderLookupSections(entity, options, mode);
 
   if (mode === "llm") {
@@ -132,13 +146,17 @@ function renderLookup<T>(
   }
 
   const headingRule = "═".repeat(Math.max(title.length, 24));
-  return [title, headingRule, "", ...fields, ...sections].join("\n").trimEnd();
+  const head = style.enabled
+    ? [style.bold(title), style.dim(headingRule)]
+    : [title, headingRule];
+  return [...head, "", ...fields, ...sections].join("\n").trimEnd();
 }
 
 function renderLookupFields<T>(
   entity: T,
   options: RenderLookupOptions<T>,
   mode: RenderMode,
+  style: RenderStyle,
 ): string[] {
   const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
   return options.fields.flatMap((field) => {
@@ -148,9 +166,9 @@ function renderLookupFields<T>(
     }
 
     const formatted = formatInlineValue(value, prefixes);
-    return mode === "llm"
-      ? [`- ${field.label}: ${formatted}`]
-      : [`  ${field.label}: ${formatted}`];
+    if (mode === "llm") return [`- ${field.label}: ${formatted}`];
+    const label = style.enabled ? style.cyan(field.label) : field.label;
+    return [`  ${label}: ${formatted}`];
   });
 }
 

package/src/kernel/render/style.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { defaultStyle, styleFor } from "./style.js";
+
+describe("styleFor", () => {
+  it("passes every color through unchanged when disabled", () => {
+    const style = styleFor(false);
+    expect(style.enabled).toBe(false);
+    expect(style.bold("x")).toBe("x");
+    expect(style.dim("x")).toBe("x");
+    expect(style.cyan("x")).toBe("x");
+    expect(style.green("x")).toBe("x");
+    expect(style.yellow("x")).toBe("x");
+  });
+
+  it("reports enabled and drives chalk when enabled", () => {
+    const style = styleFor(true);
+    expect(style.enabled).toBe(true);
+    // A non-TTY test process leaves chalk at level 0, so the text survives
+    // verbatim; what the beautified renderers gate on is `enabled`.
+    expect(style.cyan("x")).toContain("x");
+  });
+});
+
+describe("defaultStyle", () => {
+  it("is disabled when stdout is not a TTY (keeps piped output byte-stable)", () => {
+    // The vitest runner's stdout is never a TTY, so the beautify seam is inert
+    // here — the guarantee that piped / agent output is unstyled and stable.
+    expect(process.stdout.isTTY).not.toBe(true);
+    expect(defaultStyle().enabled).toBe(false);
+  });
+});

package/src/kernel/render/style.ts

@@ -0,0 +1,74 @@
+/**
+ * Terminal-styling seam for the human (TTY) output path.
+ *
+ * The condensed/agent (`llm`) and JSON paths are byte-frozen contracts; only an
+ * interactive terminal earns color and alignment. A {@link RenderStyle} carries
+ * that decision as data so a pure renderer can consult it without reading the
+ * process itself: {@link defaultStyle} probes chalk's own TTY/env detection (the
+ * same signal the help system leans on), so piped / redirected / MCP output —
+ * where `enabled` is false — renders byte-for-byte as before, while an attended
+ * terminal renders with `enabled: true`. Passing an explicit style keeps the
+ * beautified renderers deterministically testable in both modes.
+ */
+
+import chalk from "chalk";
+
+/** The palette + gate a renderer consults to beautify the human path. */
+export interface RenderStyle {
+  /** Whether to align + colorize — true only on a color-capable TTY. */
+  readonly enabled: boolean;
+  /** Emphasize a heading or primary label. */
+  bold(text: string): string;
+  /** De-emphasize secondary text (rules, markers, paths, punctuation). */
+  dim(text: string): string;
+  /** Highlight a value or identifier. */
+  cyan(text: string): string;
+  /** Tint a healthy / up-to-date status. */
+  green(text: string): string;
+  /** Tint a status that wants attention. */
+  yellow(text: string): string;
+}
+
+/** The identity styler — every function returns its input unchanged. */
+const PLAIN_STYLE: RenderStyle = {
+  enabled: false,
+  bold: (text) => text,
+  dim: (text) => text,
+  cyan: (text) => text,
+  green: (text) => text,
+  yellow: (text) => text,
+};
+
+/**
+ * Build a {@link RenderStyle} for a known color decision.
+ *
+ * @param enabled - True to colorize + align via chalk; false for the identity
+ *   styler (byte-identical to the pre-beautify plain output).
+ * @returns A style whose functions color, or pass through, accordingly.
+ */
+export function styleFor(enabled: boolean): RenderStyle {
+  if (!enabled) return PLAIN_STYLE;
+  return {
+    enabled: true,
+    bold: (text) => chalk.bold(text),
+    dim: (text) => chalk.dim(text),
+    cyan: (text) => chalk.cyan(text),
+    green: (text) => chalk.green(text),
+    yellow: (text) => chalk.yellow(text),
+  };
+}
+
+/**
+ * The active style for this process's stdout.
+ *
+ * Gated on BOTH signals: stdout must be an attended TTY, so piped / redirected /
+ * MCP output stays byte-stable even where `supports-color` fires off a TTY (CI
+ * sets `GITHUB_ACTIONS`, which chalk honors); AND chalk must report a usable
+ * color level, so `NO_COLOR` on a real terminal still yields the plain form.
+ *
+ * @returns A colorizing style on a color-capable TTY, else the identity styler.
+ * @note Impure — reads `process.stdout.isTTY` and chalk's color level.
+ */
+export function defaultStyle(): RenderStyle {
+  return styleFor(process.stdout.isTTY === true && chalk.level > 0);
+}

package/src/kernel/runtime/graphpack/build.ts

@@ -121,6 +121,16 @@ export async function buildPack(
       const index = await buildIndex(store, store.prefixes, hash);
       writeFileSync(join(temp, INDEX_FILE), JSON.stringify(index));
 
+      const tripleCount = await countTriples(store);
+      // Distinct abox subjects — the same figure `entityTotal` reports (A10),
+      // so `sources status` reads it from the manifest without parsing the
+      // whole index.json. Keep this in sync with `entityTotal` in entitySource.
+      const entityCount = new Set(
+        index.entities
+          .filter((entity) => entity.box === "abox")
+          .map((entity) => entity.uri ?? entity.name),
+      ).size;
+
       const manifest: Manifest = {
         name: options.name,
         version: options.version,
@@ -128,6 +138,8 @@ export async function buildPack(
         contentHash: hash,
         prefixes: { ...store.prefixes },
         createdAt: new Date().toISOString(),
+        tripleCount,
+        entityCount,
       };
       // Written LAST — the completeness marker for the directory.
       writeFileSync(join(temp, MANIFEST_FILE), JSON.stringify(manifest));
@@ -146,3 +158,19 @@ export async function buildPack(
     if (existsSync(temp)) rmSync(temp, { recursive: true, force: true });
   }
 }
+
+/**
+ * Count a store's triples (a cheap aggregate over the union graph).
+ *
+ * @param store - The booted store.
+ * @returns The number of triples.
+ * @note Impure — runs a COUNT query against the store.
+ */
+async function countTriples(
+  store: Awaited<ReturnType<typeof createStore>>,
+): Promise<number> {
+  const result = (await store.query(
+    "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+  )) as import("@canonical/ke").SelectResult;
+  return Number(result.bindings.at(0)?.n ?? 0);
+}

package/src/kernel/runtime/graphpack/buildIndex.test.ts

@@ -0,0 +1,103 @@
+import { createStore } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  OWL_EXPORT_ABOX_SUBJECTS,
+  OWL_EXPORT_PREFIXES,
+  OWL_EXPORT_TTL,
+} from "../../../testing/fixtures/graph/owlExport.js";
+import { entityTotal } from "../../completion/entitySource.js";
+import { buildIndex } from "./buildIndex.js";
+import type { PackIndex } from "./types.js";
+
+type Store = import("@canonical/ke").Store;
+
+/**
+ * The counters/classifiers `buildIndex` builds are masked by the embedded
+ * single-typed toy graph; the multi-typed OWL-export fixture is where the
+ * backlog-A bugs bite. Each `it` fails on the pre-fix code and passes after.
+ */
+describe("buildIndex — real-data counters/classifiers (backlog A)", () => {
+  let store: Store;
+  let index: PackIndex;
+
+  beforeAll(async () => {
+    store = await createStore({
+      sources: [{ content: OWL_EXPORT_TTL, path: "owl-export.ttl" }],
+      prefixes: OWL_EXPORT_PREFIXES,
+    });
+    index = await buildIndex(store, OWL_EXPORT_PREFIXES, "test-hash");
+  });
+
+  afterAll(() => {
+    store.dispose();
+  });
+
+  const byName = (name: string): PackIndex["entities"][number][] =>
+    index.entities.filter((entity) => entity.name === name);
+
+  it("A1: entityTotal counts DISTINCT abox subjects, not the raw multiset", () => {
+    // Every individual once — despite Protégé's `owl:NamedIndividual` dual-typing.
+    expect(entityTotal(index)).toBe(OWL_EXPORT_ABOX_SUBJECTS.length);
+
+    // The raw multiset the old code summed is strictly larger: each individual
+    // double-counts under `owl:NamedIndividual`, plus the class/property
+    // meta-buckets pile on top.
+    const rawSum = Object.values(index.instanceCountByType).reduce(
+      (sum, n) => sum + n,
+      0,
+    );
+    expect(rawSum).toBeGreaterThan(entityTotal(index));
+
+    // The abox names match the oracle exactly.
+    const aboxNames = index.entities
+      .filter((entity) => entity.box === "abox")
+      .map((entity) => entity.name);
+    expect([...new Set(aboxNames)].sort()).toEqual([
+      ...OWL_EXPORT_ABOX_SUBJECTS,
+    ]);
+  });
+
+  it("A3: a multi-domain individual gets a deterministic (lexical) primary type", () => {
+    // ex:toggle is both ex:Interactive and ex:FormControl; the smaller wins,
+    // every build/engine — never whichever type the store returned first.
+    const toggle = byName("ex:toggle").at(0);
+    expect(toggle?.type).toBe("ex:FormControl");
+    expect(toggle?.box).toBe("abox");
+  });
+
+  it("A6: a blank-node rdf:type is ignored, never a garbage primary type", () => {
+    // ex:field is typed by an anonymous class too; the blank node must not win.
+    expect(byName("ex:field").at(0)?.type).toBe("ex:FormControl");
+    // No entity type, no listed type, and no instance-count bucket is a blank node.
+    for (const entity of index.entities) {
+      expect(entity.type.startsWith("_:")).toBe(false);
+      for (const type of entity.types ?? []) {
+        expect(type.startsWith("_:")).toBe(false);
+      }
+    }
+    for (const key of Object.keys(index.instanceCountByType)) {
+      expect(key.startsWith("_:")).toBe(false);
+    }
+  });
+
+  it("A7: a multilingual label resolves to @en, deterministically", () => {
+    // "Button"@en / "Bouton"@fr → Button; the @lang no longer flips the pick.
+    expect(byName("ds:button").at(0)?.label).toBe("Button");
+    expect(byName("ex:toggle").at(0)?.label).toBe("Toggle");
+    expect(byName("ds:datePicker").at(0)?.label).toBe("Date Picker");
+  });
+
+  it("A8: an OWL-punned subject emits BOTH its tbox and abox facet", () => {
+    // ex:Slider is a class (tbox) AND an ex:Category individual (abox) — both
+    // must survive, so its abox membership stays completable.
+    const facets = byName("ex:Slider");
+    expect(facets).toHaveLength(2);
+    expect(facets.map((facet) => facet.box).sort()).toEqual(["abox", "tbox"]);
+    expect(facets.find((facet) => facet.box === "tbox")?.type).toBe(
+      "owl:Class",
+    );
+    expect(facets.find((facet) => facet.box === "abox")?.type).toBe(
+      "ex:Category",
+    );
+  });
+});