@canonical/pragma-cli 0.30.0 → 0.32.0

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,92 +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", async () => {
-    const ctx = makeCtx({
-      globalFlags: { llm: true, format: "text" 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("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 { 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, PREFIX_MAP)));
-
-    for (const g of result.groups) {
-      lines.push("");
-      lines.push(chalk.bold(compactUri(g.predicate, PREFIX_MAP)));
-      for (const o of g.objects) {
-        lines.push(`  ${compactUri(o, PREFIX_MAP)}`);
-      }
-    }
-
-    return lines.join("\n");
-  },
-
-  llm(result) {
-    const lines = [
-      `## ${compactUri(result.uri, PREFIX_MAP)} (${result.uri})`,
-      "",
-    ];
-    for (const g of result.groups) {
-      lines.push(`**${compactUri(g.predicate, PREFIX_MAP)}:**`);
-      for (const o of g.objects) {
-        lines.push(`  - ${compactUri(o, PREFIX_MAP)}`);
-      }
-    }
-    return lines.join("\n");
-  },
-
-  json(result) {
-    return JSON.stringify(result, null, 2);
-  },
-};
-
-export default formatters;

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

@@ -1,37 +0,0 @@
-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

@@ -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";

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

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

@@ -1,68 +0,0 @@
-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

@@ -1,32 +0,0 @@
-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

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