@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/graph/commands/inspect.test.ts

@@ -1,94 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import createTestRuntime from "../../../testing/helpers/createTestRuntime.js";
-import type { PragmaContext } from "../../shared/context.js";
-import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { InspectResult } from "../../shared/types/index.js";
-import buildInspectCommand from "./inspect.js";
-
-let runtime: PragmaRuntime;
-
-beforeAll(async () => {
-  runtime = await createTestRuntime();
-});
-
-afterAll(() => {
-  runtime.dispose();
-});
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    ...runtime,
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    ...overrides,
-  };
-}
-
-async function executeOutput(
-  cmd: CommandDefinition,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<{ value: unknown; text: string }> {
-  const result = await cmd.execute(params, ctx);
-  expect(result.tag).toBe("output");
-  if (result.tag !== "output") throw new Error("Expected output result");
-  return { value: result.value, text: result.render.plain(result.value) };
-}
-
-describe("graph inspect command", () => {
-  const uri = `${DEFAULT_PREFIX_MAP.ds}global.component.button`;
-
-  it("returns inspect results", async () => {
-    const ctx = makeCtx();
-    const cmd = buildInspectCommand(ctx);
-    const { value } = await executeOutput(cmd, { uri }, ctx);
-
-    const result = value as InspectResult;
-    expect(result.uri).toBe(uri);
-    expect(result.groups.length).toBeGreaterThan(0);
-  });
-
-  it("renders plain output", async () => {
-    const ctx = makeCtx();
-    const cmd = buildInspectCommand(ctx);
-    const { text } = await executeOutput(cmd, { uri }, ctx);
-
-    expect(text).toContain("http://www.w3.org/1999/02/22-rdf-syntax-ns#type");
-  });
-
-  it("renders llm output", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: true, format: "text" as const, verbose: false },
-    });
-    const cmd = buildInspectCommand(ctx);
-    const { text } = await executeOutput(cmd, { uri }, ctx);
-
-    expect(text).toContain("##");
-    expect(text).toContain(uri);
-  });
-
-  it("renders json output", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: false, format: "json" as const, verbose: false },
-    });
-    const cmd = buildInspectCommand(ctx);
-    const { text } = await executeOutput(cmd, { uri }, ctx);
-
-    const parsed = JSON.parse(text) as InspectResult;
-    expect(parsed.uri).toBe(uri);
-  });
-
-  it("throws structured error when uri is missing", async () => {
-    const ctx = makeCtx();
-    const cmd = buildInspectCommand(ctx);
-
-    await expect(cmd.execute({}, ctx)).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-      recovery: {
-        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
-        mcp: { tool: "graph_query" },
-      },
-    });
-  });
-});

package/src/domains/graph/commands/inspect.ts

@@ -1,63 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { inspectFormatters } from "../formatters/index.js";
-import { inspectUri } from "../operations/index.js";
-
-/**
- * Builds the `pragma graph inspect` command definition.
- *
- * Accepts a URI (full or prefixed) and returns all triples where
- * the URI is the subject, grouped by predicate.
- *
- * @param ctx - Pragma runtime context providing the ke store and config.
- * @returns A command definition for `graph inspect`.
- */
-export default function buildInspectCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return {
-    path: ["graph", "inspect"],
-    description: "Inspect a URI in the knowledge graph",
-    parameters: [
-      {
-        name: "uri",
-        description: "URI to inspect (full or prefixed, e.g. 'ds:Button')",
-        type: "string",
-        positional: true,
-        required: true,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma graph inspect ds:Button",
-        "pragma graph inspect https://ds.canonical.com/Button --llm",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const uri = params.uri as string;
-      if (!uri) {
-        throw PragmaError.invalidInput("uri", "(empty)", {
-          recovery: {
-            message: "Provide a URI to inspect.",
-            cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
-            mcp: { tool: "graph_query" },
-          },
-        });
-      }
-
-      const result = await inspectUri(ctx.store, uri);
-
-      return createOutputResult(result, {
-        plain: selectFormatter(ctx, inspectFormatters),
-      });
-    },
-  };
-}

package/src/domains/graph/commands/query.test.ts

@@ -1,94 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { QueryResult } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import createTestRuntime from "../../../testing/helpers/createTestRuntime.js";
-import type { PragmaContext } from "../../shared/context.js";
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import buildQueryCommand from "./query.js";
-
-let runtime: PragmaRuntime;
-
-beforeAll(async () => {
-  runtime = await createTestRuntime();
-});
-
-afterAll(() => {
-  runtime.dispose();
-});
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    ...runtime,
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    ...overrides,
-  };
-}
-
-async function executeOutput(
-  cmd: CommandDefinition,
-  params: Record<string, unknown>,
-  ctx: PragmaContext,
-): Promise<{ value: unknown; text: string }> {
-  const result = await cmd.execute(params, ctx);
-  expect(result.tag).toBe("output");
-  if (result.tag !== "output") throw new Error("Expected output result");
-  return { value: result.value, text: result.render.plain(result.value) };
-}
-
-describe("graph query command", () => {
-  const sparql = "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }";
-
-  it("returns query results", async () => {
-    const ctx = makeCtx();
-    const cmd = buildQueryCommand(ctx);
-    const { value } = await executeOutput(cmd, { sparql }, ctx);
-
-    const result = value as QueryResult;
-    expect(result.type).toBe("select");
-    if (result.type === "select") {
-      expect(Number(result.bindings[0]?.n)).toBeGreaterThan(0);
-    }
-  });
-
-  it("renders plain output", async () => {
-    const ctx = makeCtx();
-    const cmd = buildQueryCommand(ctx);
-    const { text } = await executeOutput(cmd, { sparql }, ctx);
-
-    expect(text).toContain("n");
-  });
-
-  it("renders llm output as a Markdown table for SELECT", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: true, format: "text" as const, verbose: false },
-    });
-    const cmd = buildQueryCommand(ctx);
-    const { text } = await executeOutput(cmd, { sparql }, ctx);
-
-    // Condensed Markdown, not a raw JSON dump.
-    expect(text).toContain("| n |");
-    expect(text).toContain("| --- |");
-    expect(() => JSON.parse(text)).toThrow();
-  });
-
-  it("renders json output", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: false, format: "json" as const, verbose: false },
-    });
-    const cmd = buildQueryCommand(ctx);
-    const { text } = await executeOutput(cmd, { sparql }, ctx);
-
-    const parsed = JSON.parse(text) as QueryResult;
-    expect(parsed.type).toBe("select");
-  });
-
-  it("throws structured error when sparql is missing", async () => {
-    const ctx = makeCtx();
-    const cmd = buildQueryCommand(ctx);
-
-    await expect(cmd.execute({}, ctx)).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-      recovery: { message: "Provide a SPARQL query string." },
-    });
-  });
-});

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

@@ -1,60 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { queryFormatters } from "../formatters/index.js";
-import { executeQuery } from "../operations/index.js";
-
-/**
- * Builds the `pragma graph query` command definition.
- *
- * Accepts a raw SPARQL query string and executes it against the ke store.
- *
- * @param ctx - Pragma runtime context providing the ke store and config.
- * @returns A command definition for `graph query`.
- */
-export default function buildQueryCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return {
-    path: ["graph", "query"],
-    description: "Execute a SPARQL query",
-    parameters: [
-      {
-        name: "sparql",
-        description: "SPARQL query string",
-        type: "string",
-        positional: true,
-        required: true,
-      },
-    ],
-    meta: {
-      examples: [
-        'pragma graph query "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }"',
-        'pragma graph query "SELECT ?s WHERE { ?s a ds:Component }" --llm',
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const sparql = params.sparql as string;
-      if (!sparql) {
-        throw PragmaError.invalidInput("sparql", "(empty)", {
-          recovery: {
-            message: "Provide a SPARQL query string.",
-          },
-        });
-      }
-
-      const result = await executeQuery(ctx.store, sparql);
-
-      return createOutputResult(result, {
-        plain: selectFormatter(ctx, queryFormatters),
-      });
-    },
-  };
-}

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

@@ -1,4 +0,0 @@
-/** @module Barrel for graph formatters. */
-
-export { default as inspectFormatters } from "./inspect.js";
-export { default as queryFormatters } from "./query.js";

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

@@ -1,50 +0,0 @@
-import chalk from "chalk";
-import { formatHeading } from "#pipeline";
-import compactUri from "../../shared/compactUri.js";
-import type { Formatters } from "../../shared/formatters.js";
-import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
-import type { InspectResult } from "../../shared/types/index.js";
-
-/**
- * Formatters for `pragma graph inspect` output.
- *
- * - **plain**: terminal output with chalk-styled URI heading and bold predicates.
- * - **llm**: condensed Markdown with heading and bulleted object lists.
- * - **json**: serialized {@link InspectResult} as indented JSON.
- */
-const formatters: Formatters<InspectResult> = {
-  plain(result) {
-    const lines: string[] = [];
-    lines.push(formatHeading(compactUri(result.uri, DEFAULT_PREFIX_MAP)));
-
-    for (const g of result.groups) {
-      lines.push("");
-      lines.push(chalk.bold(compactUri(g.predicate, DEFAULT_PREFIX_MAP)));
-      for (const o of g.objects) {
-        lines.push(`  ${compactUri(o, DEFAULT_PREFIX_MAP)}`);
-      }
-    }
-
-    return lines.join("\n");
-  },
-
-  llm(result) {
-    const lines = [
-      `## ${compactUri(result.uri, DEFAULT_PREFIX_MAP)} (${result.uri})`,
-      "",
-    ];
-    for (const g of result.groups) {
-      lines.push(`**${compactUri(g.predicate, DEFAULT_PREFIX_MAP)}:**`);
-      for (const o of g.objects) {
-        lines.push(`  - ${compactUri(o, DEFAULT_PREFIX_MAP)}`);
-      }
-    }
-    return lines.join("\n");
-  },
-
-  json(result) {
-    return JSON.stringify(result, null, 2);
-  },
-};
-
-export default formatters;

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

@@ -1,87 +0,0 @@
-import type { QueryResult } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import formatters from "./query.js";
-
-const selectResult = {
-  type: "select",
-  bindings: [
-    { s: "a", n: "1" },
-    { s: "b", n: "2" },
-  ],
-} as unknown as QueryResult;
-
-const emptySelect = {
-  type: "select",
-  bindings: [],
-} as unknown as QueryResult;
-
-const askResult = { type: "ask", result: true } as unknown as QueryResult;
-
-const constructResult = {
-  type: "construct",
-  triples: [
-    { subject: "s1", predicate: "p1", object: "line one\nline two" },
-    { subject: "s2", predicate: "p2", object: "o2" },
-  ],
-} as unknown as QueryResult;
-
-const emptyConstruct = {
-  type: "construct",
-  triples: [],
-} as unknown as QueryResult;
-
-describe("graph query formatters — plain", () => {
-  it("renders SELECT as a tab table", () => {
-    const text = formatters.plain(selectResult);
-    expect(text.split("\n")).toEqual(["s\tn", "a\t1", "b\t2"]);
-  });
-
-  it("reports no results for an empty SELECT", () => {
-    expect(formatters.plain(emptySelect)).toBe("No results.");
-  });
-
-  it("renders ASK as a boolean", () => {
-    expect(formatters.plain(askResult)).toBe("ASK: true");
-  });
-
-  it("renders CONSTRUCT as one-line triples", () => {
-    const text = formatters.plain(constructResult);
-    expect(text).toContain("s1\tp1\tline one line two");
-    expect(text).toContain("s2\tp2\to2");
-  });
-
-  it("reports no triples for an empty CONSTRUCT", () => {
-    expect(formatters.plain(emptyConstruct)).toBe("No triples.");
-  });
-});
-
-describe("graph query formatters — llm", () => {
-  it("renders SELECT as a Markdown table", () => {
-    const text = formatters.llm(selectResult);
-    expect(text).toContain("| s | n |");
-    expect(text).toContain("| --- | --- |");
-    expect(text).toContain("| a | 1 |");
-  });
-
-  it("renders an empty SELECT as italic no-results", () => {
-    expect(formatters.llm(emptySelect)).toBe("_No results._");
-  });
-
-  it("renders ASK as bold", () => {
-    expect(formatters.llm(askResult)).toBe("**ASK** → true");
-  });
-
-  it("renders CONSTRUCT triples as a bullet list", () => {
-    const text = formatters.llm(constructResult);
-    expect(text).toContain("- s1\tp1\tline one line two");
-  });
-});
-
-describe("graph query formatters — json", () => {
-  it("serializes the raw result", () => {
-    expect(JSON.parse(formatters.json(askResult))).toMatchObject({
-      type: "ask",
-      result: true,
-    });
-  });
-});

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

@@ -1,74 +0,0 @@
-import type { QueryResult } from "@canonical/ke";
-import type { Formatters } from "../../shared/formatters.js";
-
-/**
- * Render CONSTRUCT triples as readable `subject  predicate  object` lines,
- * collapsing any newlines in literal objects so each triple stays on one line.
- */
-function formatTriples(
-  triples: ReadonlyArray<{
-    subject: string;
-    predicate: string;
-    object: string;
-  }>,
-): string {
-  if (triples.length === 0) return "No triples.";
-  return triples
-    .map((t) => {
-      const object = t.object.replace(/\s*\n\s*/g, " ").trim();
-      return `${t.subject}\t${t.predicate}\t${object}`;
-    })
-    .join("\n");
-}
-
-/**
- * Formatters for `pragma graph query` output.
- *
- * - **plain**: tab-separated table for SELECT, `ASK: true/false` for ASK, and
- *   readable triple lines for CONSTRUCT.
- * - **llm**: condensed Markdown (table for SELECT, one line for ASK, a triple
- *   list for CONSTRUCT) rather than a raw JSON dump.
- * - **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 formatTriples(result.triples);
-  },
-
-  llm(result) {
-    if (result.type === "select") {
-      if (result.bindings.length === 0) return "_No results._";
-      const cols = Object.keys(result.bindings[0] ?? {});
-      const header = `| ${cols.join(" | ")} |`;
-      const divider = `| ${cols.map(() => "---").join(" | ")} |`;
-      const rows = result.bindings.map(
-        (b) => `| ${cols.map((c) => b[c] ?? "").join(" | ")} |`,
-      );
-      return [header, divider, ...rows].join("\n");
-    }
-    if (result.type === "ask") {
-      return `**ASK** → ${String(result.result)}`;
-    }
-    return formatTriples(result.triples)
-      .split("\n")
-      .map((line) => (line.includes("\t") ? `- ${line}` : line))
-      .join("\n");
-  },
-
-  json(result) {
-    return JSON.stringify(result, null, 2);
-  },
-};
-
-export default formatters;

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

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

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

@@ -1,50 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import resolveUri from "./resolveUri.js";
-
-const prefixes = {
-  ds: "https://ds.canonical.com/",
-  cs: "http://pragma.canonical.com/codestandards#",
-} as const;
-
-describe("resolveUri", () => {
-  it("expands a registered prefix", () => {
-    expect(resolveUri("ds:UIBlock", prefixes)).toBe(
-      "https://ds.canonical.com/UIBlock",
-    );
-  });
-
-  it("passes through a full http(s) IRI", () => {
-    expect(resolveUri("https://ds.canonical.com/global", prefixes)).toBe(
-      "https://ds.canonical.com/global",
-    );
-  });
-
-  it("passes through a urn: IRI", () => {
-    expect(resolveUri("urn:isbn:0451450523", prefixes)).toBe(
-      "urn:isbn:0451450523",
-    );
-  });
-
-  it("passes through a foreign scheme:// IRI", () => {
-    expect(resolveUri("ftp://example.org/thing", prefixes)).toBe(
-      "ftp://example.org/thing",
-    );
-  });
-
-  it("throws for an unknown prefix", () => {
-    expect(() => resolveUri("unknown:something", prefixes)).toThrow(
-      PragmaError,
-    );
-  });
-
-  it("throws for a bare string without a prefix", () => {
-    expect(() => resolveUri("button", prefixes)).toThrow(PragmaError);
-  });
-
-  it("throws for an IRI with unsafe characters", () => {
-    expect(() =>
-      resolveUri("https://example.com/<injected>", prefixes),
-    ).toThrow(PragmaError);
-  });
-});

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

@@ -1,77 +0,0 @@
-import { PragmaError } from "#error";
-
-/**
- * Characters not allowed inside `<IRI>` in SPARQL.
- * Mirrors `validateIri` from `@canonical/ke`.
- */
-const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
-
-/**
- * Matches a general absolute IRI: any scheme with an authority (`scheme://…`,
- * covering http, https, ftp, ws, and foreign schemes) or a `urn:` opaque IRI.
- * Broader than an http(s)-only check so foreign ontologies resolve.
- */
-const ABSOLUTE_IRI_PATTERN = /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/|urn:)\S/i;
-
-/**
- * Resolves a potentially prefixed URI (e.g. `ds:UIBlock`) to a full URI.
- *
- * A registered prefix always wins: `ds:UIBlock` expands via the prefix map.
- * Otherwise a general absolute IRI (`scheme://…` or `urn:…`) is validated and
- * returned as-is, so foreign ontologies are not rejected as unknown prefixes.
- * Any other `token:rest` is treated as an unknown prefix.
- *
- * @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 {
-  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 namespace = prefixes[prefix];
-
-  if (namespace !== undefined) {
-    const resolved = `${namespace}${uri.slice(colonIdx + 1)}`;
-    assertSafeIri(resolved);
-    return resolved;
-  }
-
-  if (ABSOLUTE_IRI_PATTERN.test(uri)) {
-    assertSafeIri(uri);
-    return uri;
-  }
-
-  throw PragmaError.invalidInput("prefix", prefix, {
-    validOptions: Object.keys(prefixes),
-    recovery: {
-      message: "List known ontology prefixes.",
-      cli: "pragma ontology list",
-      mcp: { tool: "ontology_list" },
-    },
-  });
-}
-
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * @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

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