@canonical/pragma-cli 0.18.0

package/src/domains/graph/formatters/query.ts

@@ -0,0 +1,37 @@
+import type { QueryResult } from "@canonical/ke";
+import type { Formatters } from "../../shared/formatters.js";
+
+/**
+ * Formatters for `pragma graph query` output.
+ *
+ * - **plain**: tab-separated table for SELECT results, `ASK: true/false` for ASK
+ *   queries, JSON fallback for CONSTRUCT.
+ * - **llm**: indented JSON for all query types.
+ * - **json**: serialized {@link QueryResult} as indented JSON.
+ */
+const formatters: Formatters<QueryResult> = {
+  plain(result) {
+    if (result.type === "select") {
+      if (result.bindings.length === 0) return "No results.";
+      const cols = Object.keys(result.bindings[0] ?? {});
+      const rows = result.bindings.map((b) =>
+        cols.map((c) => b[c] ?? "").join("\t"),
+      );
+      return [cols.join("\t"), ...rows].join("\n");
+    }
+    if (result.type === "ask") {
+      return `ASK: ${String(result.result)}`;
+    }
+    return JSON.stringify(result, null, 2);
+  },
+
+  llm(result) {
+    return JSON.stringify(result, null, 2);
+  },
+
+  json(result) {
+    return JSON.stringify(result, null, 2);
+  },
+};
+
+export default formatters;

package/src/domains/graph/helpers/index.ts

@@ -0,0 +1,3 @@
+/** @module Barrel for graph helpers. */
+
+export { default as resolveUri } from "./resolveUri.js";

package/src/domains/graph/helpers/resolveUri.ts

@@ -0,0 +1,70 @@
+import { PragmaError } from "#error";
+
+/**
+ * Characters not allowed inside `<IRI>` in SPARQL.
+ * Mirrors `validateIri` from `@canonical/ke`.
+ */
+const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
+
+/**
+ * Resolves a potentially prefixed URI (e.g. `ds:UIBlock`) to a full URI.
+ *
+ * If the URI is already a full URI (starts with `http`), validates IRI safety
+ * and returns it as-is. Otherwise, expands the prefix using the provided
+ * prefix map.
+ *
+ * @param uri - A full or prefixed URI string.
+ * @param prefixes - Registered prefix-to-namespace mapping from the store.
+ * @returns The fully expanded URI string.
+ * @throws PragmaError.invalidInput if the URI format is invalid or the prefix is unknown.
+ */
+export default function resolveUri(
+  uri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (uri.startsWith("http://") || uri.startsWith("https://")) {
+    assertSafeIri(uri);
+    return uri;
+  }
+
+  const colonIdx = uri.indexOf(":");
+  if (colonIdx === -1) {
+    throw PragmaError.invalidInput("uri", uri, {
+      recovery: {
+        message:
+          'Use a prefixed URI (e.g., "ds:global.component.button") or a full URI (e.g., "https://ds.canonical.com/global.component.button").',
+      },
+    });
+  }
+
+  const prefix = uri.slice(0, colonIdx);
+  const localName = uri.slice(colonIdx + 1);
+  const namespace = prefixes[prefix];
+
+  if (namespace === undefined) {
+    throw PragmaError.invalidInput("prefix", prefix, {
+      validOptions: Object.keys(prefixes),
+      recovery: {
+        message: "List known ontology prefixes.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+
+  const resolved = `${namespace}${localName}`;
+  assertSafeIri(resolved);
+  return resolved;
+}
+
+/**
+ * Reject URIs containing characters that would break SPARQL `<IRI>` syntax
+ * or enable injection.
+ */
+function assertSafeIri(uri: string): void {
+  if (UNSAFE_IRI_PATTERN.test(uri)) {
+    throw PragmaError.invalidInput("uri", uri, {
+      recovery: { message: "URI contains characters not allowed in IRIs." },
+    });
+  }
+}

package/src/domains/graph/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @module Graph domain barrel.
+ *
+ * Provides raw SPARQL querying and URI inspection against the ke store.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import { inspectCommand, queryCommand } from "./commands/index.js";
+
+/**
+ * Returns all command definitions for the graph domain.
+ *
+ * @param ctx - Pragma runtime context.
+ * @returns An array of command definitions (`graph query`, `graph inspect`).
+ */
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [queryCommand(ctx), inspectCommand(ctx)];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export { executeQuery, inspectUri } from "./operations/index.js";

package/src/domains/graph/mcp/index.ts

@@ -0,0 +1,2 @@
+/** @module Graph domain MCP barrel — graph_query, graph_inspect. */
+export { default as specs } from "./specs.js";

package/src/domains/graph/mcp/specs.ts

@@ -0,0 +1,82 @@
+/**
+ * MCP tool specs for graph domain — graph_query, graph_inspect.
+ */
+
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { executeQuery, inspectUri } from "../operations/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "graph_query",
+    description:
+      "Execute a SPARQL query against the knowledge graph. Returns raw query results. Use ontology_list to discover available namespaces and prefixes.",
+    params: {
+      sparql: {
+        type: "string",
+        description: "SPARQL query string",
+        optional: false,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, params) {
+      const result = await executeQuery(rt.store, params.sparql as string);
+
+      if (params.condensed) {
+        const text = JSON.stringify(result, null, 2);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data: result };
+    },
+  },
+  {
+    name: "graph_inspect",
+    description:
+      "Inspect a URI in the knowledge graph. Returns all predicates and objects for the given subject.",
+    params: {
+      uri: {
+        type: "string",
+        description: "URI to inspect (full or prefixed, e.g. 'ds:Button')",
+        optional: false,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, params) {
+      const result = await inspectUri(rt.store, params.uri as string);
+
+      if (params.condensed) {
+        const lines = [`## ${result.uri}`, ""];
+        for (const g of result.groups) {
+          lines.push(`**${g.predicate}:**`);
+          for (const o of g.objects) {
+            lines.push(`  - ${o}`);
+          }
+        }
+        const text = lines.join("\n");
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data: result };
+    },
+  },
+];
+
+export default specs;

package/src/domains/graph/operations/executeQuery.test.ts

@@ -0,0 +1,68 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import { P } from "../../shared/prefixes.js";
+import executeQuery from "./executeQuery.js";
+
+let store: Store;
+let cleanup: () => void;
+
+beforeAll(async () => {
+  const result = await createTestStore({ ttl: DS_ALL_TTL });
+  store = result.store;
+  cleanup = result.cleanup;
+});
+
+afterAll(() => cleanup());
+
+describe("executeQuery", () => {
+  it("executes a SELECT query and returns bindings", async () => {
+    const result = await executeQuery(
+      store,
+      `SELECT ?name WHERE { ?c a ${P.ds}Component ; ${P.ds}name ?name } ORDER BY ?name`,
+    );
+    expect(result.type).toBe("select");
+    if (result.type === "select") {
+      const names = result.bindings.map((b) => b.name);
+      expect(names).toContain("Button");
+      expect(names).toContain("Card");
+    }
+  });
+
+  it("executes a CONSTRUCT query and returns triples", async () => {
+    const result = await executeQuery(
+      store,
+      `CONSTRUCT { ?c ${P.ds}name ?name } WHERE { ?c a ${P.ds}Component ; ${P.ds}name ?name }`,
+    );
+    expect(result.type).toBe("construct");
+    if (result.type === "construct") {
+      expect(result.triples.length).toBeGreaterThan(0);
+      const names = result.triples.map((t) => t.object);
+      expect(names).toContain("Button");
+    }
+  });
+
+  it("executes an ASK query and returns boolean", async () => {
+    const result = await executeQuery(
+      store,
+      `ASK { ?c a ${P.ds}Component ; ${P.ds}name ?name }`,
+    );
+    expect(result.type).toBe("ask");
+    if (result.type === "ask") {
+      expect(result.result).toBe(true);
+    }
+  });
+
+  it("throws PragmaError on invalid SPARQL", async () => {
+    await expect(executeQuery(store, "SELECT INVALID SPARQL")).rejects.toThrow(
+      PragmaError,
+    );
+
+    try {
+      await executeQuery(store, "SELECT INVALID SPARQL");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("STORE_ERROR");
+    }
+  });
+});

package/src/domains/graph/operations/executeQuery.ts

@@ -0,0 +1,32 @@
+import type { QueryResult, Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import { buildQuery } from "../../shared/buildQuery.js";
+
+/**
+ * Executes a raw SPARQL query against the ke store.
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param sparql - A raw SPARQL query string.
+ * @returns The query result (select bindings, ask boolean, or construct triples).
+ * @throws PragmaError with code `STORE_ERROR` on query failure.
+ */
+export default async function executeQuery(
+  store: Store,
+  sparql: string,
+): Promise<QueryResult> {
+  try {
+    return await store.query(buildQuery(sparql));
+  } catch (error) {
+    throw new PragmaError({
+      code: "STORE_ERROR",
+      message: `Failed to execute query. ${error instanceof Error ? error.message : String(error)}`,
+      recovery: {
+        message: "Check your SPARQL syntax and see loaded namespaces.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+}

package/src/domains/graph/operations/index.ts

@@ -0,0 +1,4 @@
+/** @module Barrel for graph operations. */
+
+export { default as executeQuery } from "./executeQuery.js";
+export { default as inspectUri } from "./inspectUri.js";

package/src/domains/graph/operations/inspectUri.test.ts

@@ -0,0 +1,101 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import { P, PREFIX_MAP } from "../../shared/prefixes.js";
+import inspectUri from "./inspectUri.js";
+
+let store: Store;
+let cleanup: () => void;
+
+beforeAll(async () => {
+  const result = await createTestStore({ ttl: DS_ALL_TTL });
+  store = result.store;
+  cleanup = result.cleanup;
+});
+
+afterAll(() => cleanup());
+
+describe("inspectUri", () => {
+  it("returns grouped triples for a known URI", async () => {
+    const result = await inspectUri(store, `${P.ds}global.component.button`);
+    expect(result.uri).toBe(`${PREFIX_MAP.ds}global.component.button`);
+    expect(result.groups.length).toBeGreaterThan(0);
+
+    const predicates = result.groups.map((g) => g.predicate);
+    expect(predicates).toContain(
+      "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
+    );
+  });
+
+  it("resolves prefixed URIs", async () => {
+    const result = await inspectUri(store, `${P.ds}global.component.button`);
+    expect(result.uri).toBe(`${PREFIX_MAP.ds}global.component.button`);
+  });
+
+  it("accepts full URIs", async () => {
+    const result = await inspectUri(
+      store,
+      `${PREFIX_MAP.ds}global.component.button`,
+    );
+    expect(result.uri).toBe(`${PREFIX_MAP.ds}global.component.button`);
+    expect(result.groups.length).toBeGreaterThan(0);
+  });
+
+  it("groups objects by predicate", async () => {
+    const result = await inspectUri(store, `${P.ds}global.component.button`);
+    const modifierGroup = result.groups.find((g) =>
+      g.predicate.includes("modifier"),
+    );
+    // Button has two modifiers (importance, density)
+    if (modifierGroup) {
+      expect(modifierGroup.objects.length).toBe(2);
+    }
+  });
+
+  it("throws PragmaError.notFound for unknown URI", async () => {
+    await expect(
+      inspectUri(store, `${P.ds}nonexistent_entity`),
+    ).rejects.toThrow(PragmaError);
+
+    try {
+      await inspectUri(store, `${P.ds}nonexistent_entity`);
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
+    }
+  });
+
+  it("throws PragmaError.invalidInput for unknown prefix", async () => {
+    await expect(inspectUri(store, "unknown:something")).rejects.toThrow(
+      PragmaError,
+    );
+
+    try {
+      await inspectUri(store, "unknown:something");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+
+  it("throws PragmaError.invalidInput for bare string without prefix", async () => {
+    await expect(inspectUri(store, "button")).rejects.toThrow(PragmaError);
+
+    try {
+      await inspectUri(store, "button");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+
+  it("throws PragmaError.invalidInput for URI with unsafe IRI characters", async () => {
+    await expect(
+      inspectUri(store, "https://example.com/<injected>"),
+    ).rejects.toThrow(PragmaError);
+
+    try {
+      await inspectUri(store, "https://example.com/<injected>");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+});

package/src/domains/graph/operations/inspectUri.ts

@@ -0,0 +1,61 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import { buildQuery } from "../../shared/buildQuery.js";
+import type { InspectResult, PredicateGroup } from "../../shared/types.js";
+import resolveUri from "../helpers/resolveUri.js";
+
+/**
+ * Inspects a URI by retrieving all triples where it is the subject,
+ * grouped by predicate.
+ *
+ * Resolves prefixed URIs (e.g. `ds:Button`) to full URIs before querying.
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param uri - A full or prefixed URI to inspect.
+ * @returns An {@link InspectResult} with the resolved URI and predicate groups.
+ * @throws PragmaError.notFound if the URI has no triples in the store.
+ */
+export default async function inspectUri(
+  store: Store,
+  uri: string,
+): Promise<InspectResult> {
+  const resolvedUri = resolveUri(uri, store.prefixes);
+
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?predicate ?object
+      WHERE {
+        <${resolvedUri}> ?predicate ?object .
+      }
+      ORDER BY ?predicate ?object
+    `),
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) {
+    throw PragmaError.notFound("entity", uri, {
+      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 groupMap = new Map<string, string[]>();
+  for (const b of result.bindings) {
+    const predicate = b.predicate ?? "";
+    const object = b.object ?? "";
+    const existing = groupMap.get(predicate) ?? [];
+    existing.push(object);
+    groupMap.set(predicate, existing);
+  }
+
+  const groups: PredicateGroup[] = [...groupMap.entries()].map(
+    ([predicate, objects]) => ({ predicate, objects }),
+  );
+
+  return { uri: resolvedUri, groups };
+}

package/src/domains/info/commands/index.ts

@@ -0,0 +1,4 @@
+/** @module Barrel for info/upgrade command definitions. */
+
+export { default as infoCommand } from "./info.js";
+export { default as upgradeCommand } from "./upgrade.js";

package/src/domains/info/commands/info.test.ts

@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  collectInfoMock,
+  renderInfoJsonMock,
+  renderInfoLlmMock,
+  renderInfoPlainMock,
+} = vi.hoisted(() => ({
+  collectInfoMock: vi.fn(),
+  renderInfoJsonMock: vi.fn(() => "json"),
+  renderInfoLlmMock: vi.fn(() => "llm"),
+  renderInfoPlainMock: vi.fn(() => "plain"),
+}));
+
+vi.mock("../operations/collectInfo.js", () => ({
+  default: collectInfoMock,
+}));
+
+vi.mock("../formatters/index.js", () => ({
+  renderInfoJson: renderInfoJsonMock,
+  renderInfoLlm: renderInfoLlmMock,
+  renderInfoPlain: renderInfoPlainMock,
+}));
+
+import infoCommand from "./info.js";
+
+describe("infoCommand", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    collectInfoMock.mockResolvedValue({ version: "1.0.0" });
+  });
+
+  it("has path ['info']", () => {
+    expect(infoCommand.path).toEqual(["info"]);
+  });
+
+  it("has a description", () => {
+    expect(infoCommand.description).toBeTruthy();
+  });
+
+  it("has no parameters", () => {
+    expect(infoCommand.parameters).toEqual([]);
+  });
+
+  it("has an execute function", () => {
+    expect(typeof infoCommand.execute).toBe("function");
+  });
+
+  it("uses the plain renderer by default", async () => {
+    const result = await infoCommand.execute(
+      {},
+      { cwd: "/workspace", globalFlags: { llm: false, format: "text" } },
+    );
+
+    expect(collectInfoMock).toHaveBeenCalledWith("/workspace");
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("plain");
+      expect(renderInfoPlainMock).toHaveBeenCalledWith({ version: "1.0.0" });
+    }
+  });
+
+  it("uses the llm renderer when llm output is requested", async () => {
+    const result = await infoCommand.execute(
+      {},
+      { cwd: "/workspace", globalFlags: { llm: true, format: "text" } },
+    );
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("llm");
+      expect(renderInfoLlmMock).toHaveBeenCalledWith({ version: "1.0.0" });
+    }
+  });
+
+  it("prefers the json renderer over llm mode", async () => {
+    const result = await infoCommand.execute(
+      {},
+      { cwd: "/workspace", globalFlags: { llm: true, format: "json" } },
+    );
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("json");
+      expect(renderInfoJsonMock).toHaveBeenCalledWith({ version: "1.0.0" });
+    }
+  });
+});

package/src/domains/info/commands/info.ts

@@ -0,0 +1,47 @@
+import type { CommandDefinition, CommandResult } from "@canonical/cli-core";
+import {
+  renderInfoJson,
+  renderInfoLlm,
+  renderInfoPlain,
+} from "../formatters/index.js";
+import collectInfo from "../operations/collectInfo.js";
+import type { InfoData } from "../types.js";
+
+/**
+ * Selects the appropriate info renderer based on global CLI flags.
+ *
+ * @param flags - Global flags indicating output format.
+ * @returns A render function mapping {@link InfoData} to a string.
+ */
+function selectInfoRenderer(flags: {
+  llm: boolean;
+  format: "text" | "json";
+}): (data: InfoData) => string {
+  if (flags.format === "json") return renderInfoJson;
+  if (flags.llm) return renderInfoLlm;
+  return renderInfoPlain;
+}
+
+/**
+ * The `pragma info` command definition.
+ *
+ * Displays version, config, update status, and store summary.
+ */
+const infoCommand: CommandDefinition = {
+  path: ["info"],
+  description: "Show version, config, update status, and store summary",
+  parameters: [],
+  execute: async (
+    _params: Record<string, unknown>,
+    ctx: {
+      cwd: string;
+      globalFlags: { llm: boolean; format: "text" | "json" };
+    },
+  ): Promise<CommandResult> => {
+    const data = await collectInfo(ctx.cwd);
+    const render = selectInfoRenderer(ctx.globalFlags);
+    return { tag: "output", value: data, render: { plain: render } };
+  },
+};
+
+export default infoCommand;