@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/mcp/resources/readEntity.ts

@@ -0,0 +1,169 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import findNamespace from "../../domains/ontology/helpers/findNamespace.js";
+import { buildQuery } from "../../domains/shared/buildQuery.js";
+import compactUri from "../../domains/shared/compactUri.js";
+import classifyEntity from "./classifyEntity.js";
+import { RDF_TYPE, RDFS_DOMAIN, RDFS_SUBCLASS_OF } from "./constants.js";
+import {
+  resolveDescriptionPredicates,
+  resolveLabelPredicates,
+} from "./displayPredicates.js";
+import pickFirstValue from "./pickFirstValue.js";
+import pickPrimaryType from "./pickPrimaryType.js";
+import type {
+  GraphIndex,
+  PropertyGroup,
+  PropertyValue,
+  ResourceEntity,
+} from "./types.js";
+
+/** Query the compacted subjects of `?x <predicate> <object>`. */
+async function fetchReferencingSubjects(
+  store: Store,
+  predicate: string,
+  object: string,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<string[]> {
+  const result = await store.query(
+    buildQuery(`SELECT ?x WHERE { ?x <${predicate}> <${object}> } ORDER BY ?x`),
+  );
+  if (result.type !== "select") return [];
+  return result.termBindings
+    .filter((t) => t.x?.termType === "NamedNode")
+    .map((t) => compactUri(t.x?.value ?? "", prefixes));
+}
+
+/**
+ * Read a single entity into a box-aware payload.
+ *
+ * Object values are classified by RDF term type (via `termBindings`), so a
+ * URL-shaped literal stays a literal and a foreign IRI is recognised as a URI.
+ * A class read is enriched with its superclasses, direct subclasses, asserted
+ * instance count, and declared properties; an individual read carries a
+ * pointer to its primary class. Object URIs are labelled from the prebuilt
+ * index — no per-object query.
+ *
+ * @param store - The ke store to query.
+ * @param fullUri - The fully resolved subject URI.
+ * @param prefixes - The store's merged prefix map.
+ * @param index - The prebuilt graph index for label and count lookups.
+ * @returns The entity payload.
+ * @throws PragmaError.notFound when the subject has no triples.
+ *
+ * @note Queries ke store
+ */
+export default async function readEntity(
+  store: Store,
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+  index: GraphIndex,
+): Promise<ResourceEntity> {
+  const result = await store.query(
+    buildQuery(`SELECT ?p ?o WHERE { <${fullUri}> ?p ?o } ORDER BY ?p ?o`),
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) {
+    throw PragmaError.notFound("entity", compactUri(fullUri, prefixes), {
+      recovery: {
+        message:
+          "Check the URI is correct and run a SPARQL query to find valid URIs.",
+        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
+        mcp: { tool: "graph_query" },
+      },
+    });
+  }
+
+  const fullTypes: string[] = [];
+  const types: string[] = [];
+  const groupMap = new Map<string, PropertyValue[]>();
+  const valuesByPredicate = new Map<string, string[]>();
+
+  for (const term of result.termBindings) {
+    const predicate = term.p?.value ?? "";
+    const objectTerm = term.o;
+    if (objectTerm === undefined) continue;
+
+    const rawValues = valuesByPredicate.get(predicate) ?? [];
+    rawValues.push(objectTerm.value);
+    valuesByPredicate.set(predicate, rawValues);
+
+    if (predicate === RDF_TYPE) {
+      fullTypes.push(objectTerm.value);
+      types.push(compactUri(objectTerm.value, prefixes));
+      continue;
+    }
+
+    const compactPred = compactUri(predicate, prefixes);
+    const existing = groupMap.get(compactPred) ?? [];
+    if (objectTerm.termType === "NamedNode") {
+      existing.push({
+        type: "uri",
+        uri: objectTerm.value,
+        prefixed: compactUri(objectTerm.value, prefixes),
+        label: index.labelByUri.get(objectTerm.value) ?? null,
+      });
+    } else if (objectTerm.termType === "BlankNode") {
+      existing.push({ type: "bnode", id: objectTerm.value });
+    } else {
+      existing.push({ type: "literal", value: objectTerm.value });
+    }
+    groupMap.set(compactPred, existing);
+  }
+
+  const classification = classifyEntity(fullTypes) ?? {
+    box: "abox" as const,
+    category: "individual" as const,
+  };
+  const prefix = findNamespace(fullUri, Object.entries(prefixes))?.prefix;
+  const label = pickFirstValue(
+    valuesByPredicate,
+    resolveLabelPredicates(prefix),
+  );
+  const description = pickFirstValue(
+    valuesByPredicate,
+    resolveDescriptionPredicates(prefix),
+  );
+
+  const properties: PropertyGroup[] = [...groupMap.entries()].map(
+    ([predicate, values]) => ({ predicate, values }),
+  );
+
+  const base: ResourceEntity = {
+    uri: fullUri,
+    prefixed: compactUri(fullUri, prefixes),
+    box: classification.box,
+    category: classification.category,
+    types,
+    label,
+    description,
+    properties,
+  };
+
+  if (classification.category === "class") {
+    const [subClasses, declaredProperties] = await Promise.all([
+      fetchReferencingSubjects(store, RDFS_SUBCLASS_OF, fullUri, prefixes),
+      fetchReferencingSubjects(store, RDFS_DOMAIN, fullUri, prefixes),
+    ]);
+    return {
+      ...base,
+      superClasses: (valuesByPredicate.get(RDFS_SUBCLASS_OF) ?? []).map((u) =>
+        compactUri(u, prefixes),
+      ),
+      subClasses,
+      instanceCount: index.instanceCountByType.get(fullUri) ?? 0,
+      declaredProperties,
+    };
+  }
+
+  if (classification.category === "individual") {
+    const primaryTypeFull = pickPrimaryType(fullTypes);
+    return {
+      ...base,
+      instanceOf:
+        primaryTypeFull === null ? null : compactUri(primaryTypeFull, prefixes),
+    };
+  }
+
+  return base;
+}

package/src/mcp/resources/registerResources.ts

@@ -0,0 +1,126 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PragmaError } from "#error";
+import resolveUri from "../../domains/graph/helpers/resolveUri.js";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import buildGraphIndex from "./buildGraphIndex.js";
+import buildResourceList from "./buildResourceList.js";
+import { COMPLETION_LIMIT } from "./constants.js";
+import rankUriCompletions from "./rankUriCompletions.js";
+import readEntity from "./readEntity.js";
+import type { GraphIndex, ListingTruncation } from "./types.js";
+
+/** RFC 6570 template capturing the whole (prefixed or full) URI as `uri`. */
+const URI_TEMPLATE = "{+uri}";
+
+const TEMPLATE_DESCRIPTION =
+  "Knowledge-graph entities from the ke store. TBox schema (owl:Class / property " +
+  "definitions) is listed first and in full; ABox individuals follow, grouped by " +
+  "class and capped per class. Category and box are carried in each entry's name, " +
+  "annotations.priority, and _meta. Read any entry by its prefixed URI " +
+  "(e.g. ds:global.component.button); autocomplete matches URI or label substrings.";
+
+/**
+ * Report capped individuals to stderr so truncation is never silent.
+ *
+ * @note Impure — writes to stderr.
+ */
+function warnTruncation(truncation: ListingTruncation): void {
+  const parts = [...truncation.droppedByType.entries()]
+    .filter(([, dropped]) => dropped > 0)
+    .map(([type, dropped]) => `${type}: ${dropped}`);
+  process.stderr.write(
+    `pragma MCP resources: capped ${truncation.totalDropped} individual(s) ` +
+      `from the listing (${parts.join(", ")}); reach them via URI autocomplete ` +
+      "or the graph_query tool.\n",
+  );
+}
+
+/** Read the single `uri` template variable, tolerating array expansion. */
+function readUriVariable(value: string | string[] | undefined): string {
+  const uri = Array.isArray(value) ? value.at(0) : value;
+  if (uri === undefined) {
+    throw PragmaError.invalidInput("uri", String(value), {
+      recovery: { message: "Provide a prefixed or full entity URI." },
+    });
+  }
+  return uri;
+}
+
+/**
+ * Register the graph-driven MCP resource surface on the server.
+ *
+ * One `{+uri}` template backs listing, autocomplete, and reads. The graph
+ * index is built once per runtime (the store is immutable after boot) and
+ * reused across calls, so autocomplete stays cheap. Listing separates TBox
+ * schema from ABox individuals and caps the instance long tail; reads return
+ * a box-aware payload.
+ *
+ * @param server - The MCP server to register resources on.
+ * @param runtime - The pragma runtime providing the ke store and prefixes.
+ *
+ * @note Impure — registers handlers and queries the store lazily.
+ */
+export default function registerResources(
+  server: McpServer,
+  runtime: PragmaRuntime,
+): void {
+  const { store } = runtime;
+  const prefixes = store.prefixes;
+
+  let indexPromise: Promise<GraphIndex> | undefined;
+  const getIndex = (): Promise<GraphIndex> => {
+    indexPromise ??= buildGraphIndex(store, prefixes);
+    return indexPromise;
+  };
+
+  const template = new ResourceTemplate(URI_TEMPLATE, {
+    list: async () => {
+      const index = await getIndex();
+      const { resources, truncation } = buildResourceList(index);
+      if (truncation.totalDropped > 0) warnTruncation(truncation);
+      return { resources };
+    },
+    complete: {
+      uri: async (value) => {
+        const index = await getIndex();
+        const candidates = index.entities.map((entity) => ({
+          prefixed: entity.prefixed,
+          label: entity.label,
+        }));
+        return rankUriCompletions(candidates, value, COMPLETION_LIMIT);
+      },
+    },
+  });
+
+  server.registerResource(
+    "graph-entity",
+    template,
+    { description: TEMPLATE_DESCRIPTION, mimeType: "application/json" },
+    async (url, variables) => {
+      try {
+        const prefixedUri = readUriVariable(variables.uri);
+        const fullUri = resolveUri(prefixedUri, prefixes);
+        const index = await getIndex();
+        const entity = await readEntity(store, fullUri, prefixes, index);
+        return {
+          contents: [
+            {
+              uri: url.href,
+              mimeType: "application/json",
+              text: JSON.stringify(entity, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        const message =
+          error instanceof PragmaError
+            ? JSON.stringify({ code: error.code, message: error.message })
+            : String(error);
+        return {
+          contents: [{ uri: url.href, mimeType: "text/plain", text: message }],
+        };
+      }
+    },
+  );
+}

package/src/mcp/resources/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared types for the MCP resource surface.
+ *
+ * These shapes flow from the bulk graph index (`buildGraphIndex`) through
+ * listing (`buildResourceList`), autocomplete (`rankUriCompletions`), and
+ * entity reads (`readEntity`). They live together because each stage
+ * consumes the previous stage's output — the box/category vocabulary is the
+ * spine that keeps TBox schema and ABox individuals distinguishable end to end.
+ */
+
+/** Whether an entity is schema (TBox) or an individual (ABox). */
+export type EntityBox = "tbox" | "abox";
+
+/** Fine-grained entity kind within its box. */
+export type EntityCategory = "class" | "property" | "individual";
+
+/** A literal object value in an entity read. */
+export interface PropertyValueLiteral {
+  readonly type: "literal";
+  readonly value: string;
+}
+
+/** A URI object value in an entity read, resolved to a summary. */
+export interface PropertyValueUri {
+  readonly type: "uri";
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly label: string | null;
+}
+
+/** A blank-node object value in an entity read. */
+export interface PropertyValueBlank {
+  readonly type: "bnode";
+  readonly id: string;
+}
+
+/** One object value of a predicate in an entity read. */
+export type PropertyValue =
+  | PropertyValueLiteral
+  | PropertyValueUri
+  | PropertyValueBlank;
+
+/** All object values asserted for a single predicate. */
+export interface PropertyGroup {
+  readonly predicate: string;
+  readonly values: PropertyValue[];
+}
+
+/** One classified subject in the graph index. */
+export interface GraphEntity {
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly box: EntityBox;
+  readonly category: EntityCategory;
+  /** Compacted `rdf:type` values. */
+  readonly types: string[];
+  /** Compacted primary type used for grouping and naming (individuals). */
+  readonly primaryType: string | null;
+  /** Compacted primary type label, or the type's local name. */
+  readonly primaryTypeLabel: string | null;
+  readonly label: string | null;
+  readonly description: string | null;
+}
+
+/** The in-memory index of all named-node subjects, built via bulk queries. */
+export interface GraphIndex {
+  readonly entities: GraphEntity[];
+  /** Full URI → resolved label, for cheap type-label and object-label joins. */
+  readonly labelByUri: ReadonlyMap<string, string>;
+  /** Full URI → count of subjects declaring it as an `rdf:type`. */
+  readonly instanceCountByType: ReadonlyMap<string, number>;
+}
+
+/** MCP resource annotations we emit (schema-valid subset). */
+export interface ResourceAnnotations {
+  readonly audience: ("assistant" | "user")[];
+  readonly priority: number;
+}
+
+/** A single resource entry returned from the `list` callback. */
+export interface ListedResource {
+  readonly uri: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly mimeType: "application/json";
+  readonly annotations: ResourceAnnotations;
+  readonly _meta: Record<string, unknown>;
+}
+
+/** How many individuals a listing dropped, per capped class. */
+export interface ListingTruncation {
+  readonly totalDropped: number;
+  readonly droppedByType: ReadonlyMap<string, number>;
+}
+
+/** Result of building a resource listing from the graph index. */
+export interface ResourceListing {
+  readonly resources: ListedResource[];
+  readonly truncation: ListingTruncation;
+}
+
+/** A candidate for URI autocomplete: its compacted form and human label. */
+export interface UriCompletionCandidate {
+  readonly prefixed: string;
+  readonly label: string | null;
+}
+
+/** A read entity payload, shaped by its box. */
+export interface ResourceEntity {
+  readonly uri: string;
+  readonly prefixed: string;
+  readonly box: EntityBox;
+  readonly category: EntityCategory;
+  readonly types: string[];
+  readonly label: string | null;
+  readonly description: string | null;
+  readonly properties: PropertyGroup[];
+  /** Class read: compacted superclasses. */
+  readonly superClasses?: string[];
+  /** Class read: compacted direct subclasses. */
+  readonly subClasses?: string[];
+  /** Class read: number of asserted individuals. */
+  readonly instanceCount?: number;
+  /** Class read: compacted properties declaring this class as their domain. */
+  readonly declaredProperties?: string[];
+  /** Individual read: compacted primary class this individual belongs to. */
+  readonly instanceOf?: string | null;
+}

package/src/mcp/tools/index.ts

@@ -18,6 +18,7 @@ import { specs as orientationSpecs } from "../../domains/llm/mcp/index.js";
 import { specs as modifierSpecs } from "../../domains/modifier/mcp/index.js";
 import { specs as ontologySpecs } from "../../domains/ontology/mcp/index.js";
 import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import { compilePackToolSpecs } from "../../domains/shared/stories/pack/index.js";
 import type { ToolSpec } from "../../domains/shared/ToolSpec.js";
 import { specs as skillSpecs } from "../../domains/skill/mcp/index.js";
 import { specs as standardSpecs } from "../../domains/standard/mcp/index.js";
@@ -54,4 +55,12 @@ export default function registerAllTools(
   for (const spec of allSpecs) {
     registerFromSpec(server, runtime, spec);
   }
+
+  // Story packs project onto the same surface; built-in nouns are reserved.
+  const reservedNouns = new Set(
+    allSpecs.map((spec) => spec.name.split("_").at(0) ?? ""),
+  );
+  for (const spec of compilePackToolSpecs(runtime, reservedNouns)) {
+    registerFromSpec(server, runtime, spec);
+  }
 }

package/src/mcp/tools/registerTools.test.ts

@@ -9,7 +9,12 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestMcpClient } from "#testing";
+import {
+  createTestMcpClient,
+  RECIPE_PREFIXES,
+  RECIPE_STORY,
+  RECIPE_TTL,
+} from "#testing";
 import type { McpErrorPayload } from "../types.js";
 
 let client: Client;
@@ -52,9 +57,9 @@ function parseData(result: Record<string, unknown>): unknown {
 // =============================================================================
 
 describe("tool listing", () => {
-  it("registers 29 tools", async () => {
+  it("registers 30 tools", async () => {
     const { tools } = await client.listTools();
-    expect(tools).toHaveLength(29);
+    expect(tools).toHaveLength(30);
   });
 
   it("all tools have descriptions", async () => {
@@ -508,6 +513,8 @@ describe("config_show", () => {
 describe("config_tier", () => {
   it("sets, queries, and resets tier in workspace config", async () => {
     const dir = mkdtempSync(join(tmpdir(), "pragma-mcp-tier-"));
+    // Seed a project file so global-first writes stay in this workspace.
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
 
     try {
       const scoped = await createTestMcpClient({ cwd: dir });
@@ -517,7 +524,10 @@ describe("config_tier", () => {
           name: "config_tier",
           arguments: { path: "global" },
         });
-        expect(parseData(setResult)).toEqual({ tier: "global", action: "set" });
+        expect(parseData(setResult)).toMatchObject({
+          tier: "global",
+          action: "set",
+        });
 
         const queryResult = await scoped.client.callTool({
           name: "config_tier",
@@ -532,7 +542,10 @@ describe("config_tier", () => {
           name: "config_tier",
           arguments: { reset: true },
         });
-        expect(parseData(resetResult)).toEqual({ tier: null, action: "reset" });
+        expect(parseData(resetResult)).toMatchObject({
+          tier: null,
+          action: "reset",
+        });
 
         const queriedAfterReset = await scoped.client.callTool({
           name: "config_tier",
@@ -554,6 +567,8 @@ describe("config_tier", () => {
 describe("config_channel", () => {
   it("sets, queries, and resets channel in workspace config", async () => {
     const dir = mkdtempSync(join(tmpdir(), "pragma-mcp-channel-"));
+    // Seed a project file so global-first writes stay in this workspace.
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
 
     try {
       const scoped = await createTestMcpClient({ cwd: dir });
@@ -563,7 +578,7 @@ describe("config_channel", () => {
           name: "config_channel",
           arguments: { value: "experimental" },
         });
-        expect(parseData(setResult)).toEqual({
+        expect(parseData(setResult)).toMatchObject({
           channel: "experimental",
           action: "set",
         });
@@ -581,7 +596,7 @@ describe("config_channel", () => {
           name: "config_channel",
           arguments: { reset: true },
         });
-        expect(parseData(resetResult)).toEqual({
+        expect(parseData(resetResult)).toMatchObject({
           channel: "normal",
           action: "reset",
         });
@@ -964,6 +979,48 @@ describe("graph_inspect", () => {
 // Skill tools
 // =============================================================================
 
+describe("story-pack tools", () => {
+  it("registers <noun>_list and <noun>_lookup from a stories config", async () => {
+    const scoped = await createTestMcpClient({
+      ttl: RECIPE_TTL,
+      config: {
+        tier: undefined,
+        channel: "normal",
+        stories: [RECIPE_STORY],
+        prefixes: RECIPE_PREFIXES,
+      },
+    });
+
+    try {
+      const tools = (await scoped.client.listTools()).tools.map(
+        (tool) => tool.name,
+      );
+      expect(tools).toHaveLength(32);
+      expect(tools).toContain("recipe_list");
+      expect(tools).toContain("recipe_lookup");
+
+      const listResult = await scoped.client.callTool({
+        name: "recipe_list",
+        arguments: {},
+      });
+      const rows = parseData(listResult) as { name: string }[];
+      expect(rows.map((row) => row.name)).toEqual(["Gazpacho", "Pancakes"]);
+
+      const lookupResult = await scoped.client.callTool({
+        name: "recipe_lookup",
+        arguments: { names: ["pancakes"] },
+      });
+      const data = parseData(lookupResult) as {
+        results: { name: string; instructions: string }[];
+      };
+      expect(data.results.at(0)?.name).toBe("Pancakes");
+      expect(data.results.at(0)?.instructions).toBe("Mix, fry, flip.");
+    } finally {
+      await scoped.cleanup();
+    }
+  });
+});
+
 describe("skill_list", () => {
   it("returns skills data", async () => {
     const result = await client.callTool({
@@ -1048,7 +1105,7 @@ describe("capabilities", () => {
     expect(toolNames).toContain("block_list");
     expect(toolNames).toContain("capabilities");
     expect(data.tools.every((t) => t.use_when.length > 0)).toBe(true);
-    expect(data.counts.total).toBe(29);
+    expect(data.counts.total).toBe(30);
     expect(data.counts.read).toBeGreaterThan(0);
     expect(data.counts.write).toBe(5);
     expect(data.counts.orientation).toBe(2);

package/src/mcp/types.ts

@@ -25,6 +25,8 @@ export type ToolPayload =
       readonly meta?: {
         readonly count?: number;
         readonly filters?: Record<string, string>;
+        /** Queries that failed unexpectedly (surfaced only when > 0). */
+        readonly internalErrorCount?: number;
       };
     }
   | {
@@ -47,6 +49,8 @@ export interface ToolResponse<T = unknown> {
   readonly meta: {
     readonly count?: number;
     readonly filters?: Record<string, string>;
+    /** Queries that failed unexpectedly (surfaced only when > 0). */
+    readonly internalErrorCount?: number;
   };
 }
 

package/src/pipeline/collectCommands.ts

@@ -14,6 +14,7 @@ import { commands as modifierCommands } from "../domains/modifier/index.js";
 import { commands as ontologyCommands } from "../domains/ontology/index.js";
 import { commands as setupCommands } from "../domains/setup/index.js";
 import type { PragmaContext } from "../domains/shared/context.js";
+import { compilePackCommands } from "../domains/shared/stories/pack/index.js";
 import { commands as skillCommands } from "../domains/skill/index.js";
 import { commands as standardCommands } from "../domains/standard/index.js";
 import { commands as tierCommands } from "../domains/tier/index.js";
@@ -31,7 +32,7 @@ import { commands as tokenCommands } from "../domains/token/index.js";
 export default function collectCommands(
   ctx: PragmaContext,
 ): CommandDefinition[] {
-  return [
+  const builtIn: CommandDefinition[] = [
     ...configCommands(ctx),
     ...createCommands(),
     ...setupCommands(),
@@ -50,4 +51,10 @@ export default function collectCommands(
     buildLlmCommand(ctx),
     buildCapabilitiesCommand(),
   ];
+
+  // Story packs project onto the same surface; built-in nouns are reserved.
+  const reservedNouns = new Set(
+    builtIn.map((command) => command.path.at(0) ?? ""),
+  );
+  return [...builtIn, ...compilePackCommands(ctx, reservedNouns)];
 }