@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -0,0 +1,194 @@
+/**
+ * The ONE source of truth for prompt entities — read TWO ways from ONE KG type
+ * (`ds:Prompt`), so the native MCP `prompts/*` surface and the covenant
+ * `prompt_list`/`prompt_lookup` content tools never diverge.
+ *
+ * A `ds:Prompt` is authored as:
+ *   ds:prompt.x a ds:Prompt ;
+ *     rdfs:label "x" ;                 # the prompt NAME (indexed → storeless list)
+ *     rdfs:comment "…" ;               # the description (indexed)
+ *     ds:promptBody "…" ;              # the template body (store-backed)
+ *     ds:promptArgument [ ds:argName "a" ; rdfs:comment "…" ; ds:argRequired true ] .
+ *
+ * Listing is STORELESS (over the pack index — `label`/`description` are indexed),
+ * so `prompts/list` and native discovery cost nothing until a `get`. A `get`
+ * (body + arguments) is STORE-BACKED through the SPARQL facade — identical
+ * laziness to the resource browser (list storeless, read store-backed). An empty
+ * or missing index yields zero prompts (never a store boot on the list path).
+ */
+
+import { readPackIndex } from "../../../completion/entitySource.js";
+import type { PragmaRuntime } from "../../../runtime/types.js";
+
+/** The KG type (prefixed) every prompt entity carries. */
+export const PROMPT_TYPE = "ds:Prompt";
+
+/** One declared argument of a prompt template. */
+export interface PromptArgument {
+  readonly name: string;
+  readonly description?: string;
+  readonly required?: boolean;
+}
+
+/** A prompt as it appears in a listing (name + description only — storeless). */
+export interface PromptSummary {
+  readonly name: string;
+  readonly description?: string;
+}
+
+/** A fully materialized prompt (body + arguments — store-backed). */
+export interface PromptEntry extends PromptSummary {
+  readonly body: string;
+  readonly arguments: readonly PromptArgument[];
+}
+
+/** Whether an index entity is a `ds:Prompt` (primary type or any type). */
+function isPromptEntity(entity: {
+  type: string;
+  types?: readonly string[];
+}): boolean {
+  return (
+    entity.type === PROMPT_TYPE ||
+    (Array.isArray(entity.types) && entity.types.includes(PROMPT_TYPE))
+  );
+}
+
+/**
+ * List prompt summaries STORELESSLY from the active pack index. Returns `[]`
+ * when no index is reachable or the index carries no prompts — never boots the
+ * store.
+ *
+ * @param rt - The per-invocation runtime (for `cwd`).
+ * @returns Prompt summaries (name from the entity label, sorted by name).
+ */
+export function listPromptSummaries(rt: PragmaRuntime): PromptSummary[] {
+  const index = readPackIndex(rt.cwd);
+  if (!index || !Array.isArray(index.entities)) return [];
+  const summaries: PromptSummary[] = [];
+  for (const entity of index.entities) {
+    if (!isPromptEntity(entity)) continue;
+    const name = entity.label || entity.name;
+    summaries.push({
+      name,
+      ...(entity.description ? { description: entity.description } : {}),
+    });
+  }
+  return summaries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Rows the prompt SELECT returns (one per argument; body repeats). The facade's
+ * SELECT bindings are keyed by variable name with PLAIN string values (an
+ * unbound OPTIONAL variable is simply absent) — the same shape `runSelect`
+ * consumes.
+ */
+interface PromptRow {
+  readonly name?: string;
+  readonly description?: string;
+  readonly body?: string;
+  readonly argName?: string;
+  readonly argDescription?: string;
+  readonly argRequired?: string;
+}
+
+/** The SPARQL that materializes prompts (all, or one when `label` is bound). */
+function promptQuery(labelFilter?: string): string {
+  const filter = labelFilter
+    ? `  FILTER(LCASE(STR(?name)) = LCASE(${JSON.stringify(labelFilter)}))`
+    : "";
+  return [
+    "SELECT ?name ?description ?body ?argName ?argDescription ?argRequired WHERE {",
+    "  ?prompt a ds:Prompt ;",
+    "          rdfs:label ?name .",
+    filter,
+    "  OPTIONAL { ?prompt rdfs:comment ?description }",
+    "  OPTIONAL { ?prompt ds:promptBody ?body }",
+    "  OPTIONAL {",
+    "    ?prompt ds:promptArgument ?arg .",
+    "    ?arg ds:argName ?argName .",
+    "    OPTIONAL { ?arg rdfs:comment ?argDescription }",
+    "    OPTIONAL { ?arg ds:argRequired ?argRequired }",
+    "  }",
+    "}",
+    "ORDER BY ?name ?argName",
+  ].join("\n");
+}
+
+/** Fold SELECT rows (one per argument) into distinct {@link PromptEntry}s. */
+function foldPromptRows(rows: readonly PromptRow[]): PromptEntry[] {
+  const byName = new Map<
+    string,
+    { description?: string; body: string; args: Map<string, PromptArgument> }
+  >();
+  for (const row of rows) {
+    const name = row.name;
+    if (!name) continue;
+    let entry = byName.get(name);
+    if (!entry) {
+      entry = { body: "", args: new Map() };
+      if (row.description) entry.description = row.description;
+      byName.set(name, entry);
+    }
+    if (row.body) entry.body = row.body;
+    const argName = row.argName;
+    if (argName && !entry.args.has(argName)) {
+      entry.args.set(argName, {
+        name: argName,
+        ...(row.argDescription ? { description: row.argDescription } : {}),
+        ...(row.argRequired !== undefined
+          ? { required: row.argRequired === "true" }
+          : {}),
+      });
+    }
+  }
+  return [...byName.entries()]
+    .map(([name, entry]) => ({
+      name,
+      ...(entry.description ? { description: entry.description } : {}),
+      body: entry.body,
+      arguments: [...entry.args.values()],
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Extract the SELECT binding rows from a facade query result. */
+function selectRows(result: unknown): PromptRow[] {
+  const typed = result as { type?: string; bindings?: unknown };
+  if (typed.type !== "select" || !Array.isArray(typed.bindings)) return [];
+  return typed.bindings as PromptRow[];
+}
+
+/**
+ * Read every prompt entity STORE-BACKED (body + arguments). Boots the store via
+ * the SPARQL facade; returns `[]` on any query failure (graceful degradation).
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The materialized prompt entries, sorted by name.
+ */
+export async function readPrompts(rt: PragmaRuntime): Promise<PromptEntry[]> {
+  try {
+    const result = await rt.query.sparql(promptQuery());
+    return foldPromptRows(selectRows(result));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read ONE prompt entity by name (case-insensitive), STORE-BACKED.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param name - The prompt name (its `rdfs:label`).
+ * @returns The materialized prompt, or `undefined` when not found.
+ */
+export async function readPrompt(
+  rt: PragmaRuntime,
+  name: string,
+): Promise<PromptEntry | undefined> {
+  try {
+    const result = await rt.query.sparql(promptQuery(name));
+    return foldPromptRows(selectRows(result))[0];
+  } catch {
+    return undefined;
+  }
+}

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

@@ -0,0 +1,238 @@
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { describe, expect, it, type Mock, vi } from "vitest";
+import { z } from "zod";
+import {
+  fixtureEffectsModule,
+  fixtureModule,
+  touchPath,
+} from "../../../testing/fixtures/fixtureCapability.js";
+import { projectMcp } from "../../../testing/helpers/projectMcp.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type {
+  GlobalFlags,
+  LazyStore,
+  PragmaRuntime,
+} from "../../runtime/types.js";
+import type {
+  CapabilityModule,
+  ParamSpec,
+  VerbSpec,
+} from "../../spec/types.js";
+import { buildZodSchema, registerVerb } from "./registerVerb.js";
+
+const passthroughFormatters = {
+  plain: (d: unknown) => String(d),
+  llm: (d: unknown) => String(d),
+  json: (d: unknown) => JSON.stringify(d),
+};
+
+describe("buildZodSchema (params → zod)", () => {
+  const params: ParamSpec[] = [
+    {
+      kind: "string",
+      name: "name",
+      doc: "n",
+      positional: true,
+      required: true,
+    },
+    { kind: "boolean", name: "withHistory", doc: "h" },
+    { kind: "enum", name: "mode", doc: "m", values: ["a", "b"] },
+    { kind: "number", name: "count", doc: "c" },
+    { kind: "string[]", name: "tags", doc: "t" },
+  ];
+  const schema = z.object(buildZodSchema(params));
+
+  it("maps each param kind and keys by param name", () => {
+    expect(Object.keys(buildZodSchema(params)).sort()).toEqual([
+      "count",
+      "mode",
+      "name",
+      "tags",
+      "withHistory",
+    ]);
+  });
+
+  it("makes non-required params optional but keeps required ones", () => {
+    expect(schema.safeParse({ name: "x" }).success).toBe(true);
+    expect(schema.safeParse({}).success).toBe(false);
+  });
+
+  it("validates enum, number, and array fields", () => {
+    expect(schema.safeParse({ name: "x", mode: "z" }).success).toBe(false);
+    expect(
+      schema.safeParse({
+        name: "x",
+        mode: "a",
+        count: 2,
+        tags: ["p"],
+        withHistory: true,
+      }).success,
+    ).toBe(true);
+  });
+
+  it("applies a declared default when the field is omitted (CLI parity)", () => {
+    const withDefault = z.object(
+      buildZodSchema([
+        { kind: "string", name: "mode", doc: "m", default: "fast" },
+      ]),
+    );
+    expect(withDefault.parse({})).toEqual({ mode: "fast" });
+    expect(withDefault.parse({ mode: "slow" })).toEqual({ mode: "slow" });
+  });
+});
+
+describe("tool error envelope parity", () => {
+  it("wraps a thrown non-PragmaError as the INTERNAL_ERROR envelope", async () => {
+    const boom: CapabilityModule = {
+      name: "boom",
+      verbs: [
+        {
+          path: ["boom", "go"],
+          summary: "Throws a plain Error.",
+          params: [],
+          output: { formatters: passthroughFormatters },
+          capability: {
+            needsStore: false,
+            mutates: false,
+            mcp: { expose: true },
+          },
+          run: async () => {
+            throw new Error("kaboom");
+          },
+        },
+      ],
+    };
+    const mcp = await projectMcp([boom]);
+    const envelope = await mcp.callTool("boom_go");
+    await mcp.cleanup();
+
+    expect(envelope.ok).toBe(false);
+    const error = envelope.error as { code: string; message: string };
+    expect(error.code).toBe("INTERNAL_ERROR");
+    expect(error.message).toContain("kaboom");
+  });
+});
+
+describe("tool registration", () => {
+  it("names tools by path and excludes non-exposed verbs", async () => {
+    const mcp = await projectMcp([fixtureModule]);
+    const names = (await mcp.listTools()).map((t) => t.name).sort();
+    await mcp.cleanup();
+    expect(names).toEqual(["widget_list", "widget_make"]);
+  });
+
+  it("derives annotations from the capability", async () => {
+    const mcp = await projectMcp([fixtureModule]);
+    const tools = await mcp.listTools();
+    await mcp.cleanup();
+    expect(
+      tools.find((t) => t.name === "widget_list")?.annotations,
+    ).toMatchObject({ readOnlyHint: true, openWorldHint: false });
+    expect(
+      tools.find((t) => t.name === "widget_make")?.annotations,
+    ).toMatchObject({
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: false,
+    });
+  });
+
+  it("records a reason for a verb withheld from MCP", () => {
+    const internal = fixtureModule.verbs.find((v) => v.path[1] === "internal");
+    expect(internal?.capability.mcp).toEqual({
+      expose: false,
+      reason: "internal probe, not an agent tool",
+    });
+  });
+});
+
+describe("real MCP mutation invalidates the shared server-lifetime store (C2 hook)", () => {
+  const MCP_FLAGS: GlobalFlags = {
+    llm: true,
+    autoLlm: false,
+    format: "json",
+    verbose: false,
+  };
+  const touchVerb = fixtureEffectsModule.verbs.find(
+    (v) => v.path[1] === "touch",
+  ) as VerbSpec;
+
+  /**
+   * A real `bootRuntime` (real cwd/config), but with its store swapped for one
+   * whose `invalidate` is observable. `probe touch` is `needsStore: false`, so
+   * `get()` is never called — only the mutate handler's post-run invalidation is.
+   */
+  function runtimeWithSpyStore(): { runtime: PragmaRuntime; invalidate: Mock } {
+    const base = bootRuntime(
+      MCP_FLAGS,
+      mkdtempSync(join(tmpdir(), "pragma-c2-hook-")),
+    );
+    const invalidate = vi.fn();
+    const store: LazyStore = {
+      get booted() {
+        return base.store.booted;
+      },
+      get: base.store.get.bind(base.store),
+      invalidate,
+    };
+    return { runtime: { ...base, store }, invalidate };
+  }
+
+  /** Register `touchVerb` and hand back the raw tool handler (no transport). */
+  function captureHandler(
+    runtime: PragmaRuntime,
+  ): (args: Record<string, unknown>) => Promise<CallToolResult> {
+    let handler:
+      | ((args: Record<string, unknown>) => Promise<CallToolResult>)
+      | undefined;
+    const server = {
+      registerTool: (
+        _name: string,
+        _config: unknown,
+        h: (args: Record<string, unknown>) => Promise<CallToolResult>,
+      ) => {
+        handler = h;
+      },
+    } as unknown as McpServer;
+    registerVerb(server, touchVerb, runtime);
+    if (!handler) throw new Error("registerVerb registered no handler");
+    return handler;
+  }
+
+  const envelopeOf = (result: CallToolResult): Record<string, unknown> =>
+    JSON.parse((result.content[0] as { text: string }).text);
+
+  it("invalidates the store after a real (confirm:true) mutation settles", async () => {
+    const { runtime, invalidate } = runtimeWithSpyStore();
+    const handler = captureHandler(runtime);
+    const name = `c2-confirm-${Date.now()}`;
+
+    const result = await handler({ name, confirm: true });
+
+    // The real run wrote the file AND dropped the shared server-lifetime caches
+    // afterwards, so the next read tool re-boots against the new on-disk state.
+    expect(existsSync(touchPath(name))).toBe(true);
+    expect(invalidate).toHaveBeenCalledTimes(1);
+    expect(envelopeOf(result).ok).toBe(true);
+  });
+
+  it("does NOT invalidate the store on a plan-only preview (no confirm)", async () => {
+    const { runtime, invalidate } = runtimeWithSpyStore();
+    const handler = captureHandler(runtime);
+    const name = `c2-preview-${Date.now()}`;
+
+    const result = await handler({ name });
+
+    // A preview touches no disk and leaves the caches intact — no invalidation.
+    expect(existsSync(touchPath(name))).toBe(false);
+    expect(invalidate).not.toHaveBeenCalled();
+    expect(envelopeOf(result).meta).toEqual({
+      planOnly: true,
+      confirmRequired: true,
+    });
+  });
+});