@canonical/pragma-cli 0.18.0

package/src/domains/doctor/operations/checks.test.ts

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("#config", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("#config")>()),
+  configExists: vi.fn(),
+}));
+vi.mock("../../shared/bootStore.js", () => ({
+  bootStore: vi.fn(),
+}));
+vi.mock("../../info/operations/collectStoreSummary.js", () => ({
+  collectStoreSummary: vi.fn(),
+}));
+vi.mock("@canonical/harnesses", () => ({
+  detectHarnesses: vi.fn(),
+  readMcpConfig: vi.fn(),
+}));
+vi.mock("@canonical/task", () => ({
+  runTask: vi.fn((task: unknown) => task),
+}));
+
+import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
+import { configExists } from "#config";
+import { collectStoreSummary } from "../../info/operations/index.js";
+import { bootStore } from "../../shared/bootStore.js";
+import {
+  checkConfigFile,
+  checkKeStore,
+  checkMcpConfigured,
+  checkNodeVersion,
+  checkPragmaVersion,
+  checkShellCompletions,
+  checkSkillsSymlinked,
+} from "./checks/index.js";
+
+const ctx = { cwd: "/test/project" };
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("checkNodeVersion", () => {
+  it("passes for current Node version", async () => {
+    const result = await checkNodeVersion();
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain(process.versions.node);
+  });
+});
+
+describe("checkPragmaVersion", () => {
+  it("always passes and includes version", async () => {
+    const result = await checkPragmaVersion();
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain("v");
+  });
+});
+
+describe("checkConfigFile", () => {
+  it("passes when config exists", async () => {
+    vi.mocked(configExists).mockReturnValue(true);
+    const result = await checkConfigFile(ctx);
+    expect(result.status).toBe("pass");
+  });
+
+  it("fails with remedy when config missing", async () => {
+    vi.mocked(configExists).mockReturnValue(false);
+    const result = await checkConfigFile(ctx);
+    expect(result.status).toBe("fail");
+    expect(result.remedy).toBeDefined();
+  });
+});
+
+describe("checkKeStore", () => {
+  it("passes when store boots and reports triple count", async () => {
+    const mockStore = {
+      query: vi.fn(),
+      dispose: vi.fn(),
+    };
+    vi.mocked(bootStore).mockResolvedValue(mockStore as never);
+    vi.mocked(collectStoreSummary).mockResolvedValue({
+      tripleCount: 12847,
+      graphNames: [],
+    });
+
+    const result = await checkKeStore(ctx);
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain("12,847");
+    expect(mockStore.dispose).toHaveBeenCalled();
+  });
+
+  it("fails when store boot throws", async () => {
+    vi.mocked(bootStore).mockRejectedValue(new Error("no data"));
+    const result = await checkKeStore(ctx);
+    expect(result.status).toBe("fail");
+    expect(result.remedy).toBeDefined();
+  });
+});
+
+describe("checkShellCompletions", () => {
+  it("returns pass or fail without throwing", async () => {
+    const result = await checkShellCompletions();
+    expect(["pass", "fail"]).toContain(result.status);
+  });
+});
+
+describe("checkMcpConfigured", () => {
+  it("fails when no harnesses detected", async () => {
+    vi.mocked(detectHarnesses).mockReturnValue(Promise.resolve([]) as never);
+    const result = await checkMcpConfigured(ctx);
+    expect(result.status).toBe("fail");
+  });
+
+  it("passes when pragma is configured in a harness", async () => {
+    const harness = {
+      id: "claude-code",
+      name: "Claude Code",
+      configPath: () => "/test/.mcp.json",
+      skillsPath: () => "/test/.claude/skills",
+      detect: [],
+      version: "*",
+      configFormat: "json" as const,
+      mcpKey: "mcpServers",
+    };
+    vi.mocked(detectHarnesses).mockReturnValue(
+      Promise.resolve([
+        {
+          harness,
+          confidence: "high" as const,
+          configExists: true,
+          configPath: "/test/.mcp.json",
+        },
+      ]) as never,
+    );
+    vi.mocked(readMcpConfig).mockReturnValue(
+      Promise.resolve({
+        pragma: { command: "pragma", args: ["mcp"] },
+      }) as never,
+    );
+
+    const result = await checkMcpConfigured(ctx);
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain("Claude Code");
+  });
+});
+
+describe("checkSkillsSymlinked", () => {
+  it("skips when no harnesses detected", async () => {
+    vi.mocked(detectHarnesses).mockReturnValue(Promise.resolve([]) as never);
+    const result = await checkSkillsSymlinked(ctx);
+    expect(result.status).toBe("skip");
+  });
+});

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

@@ -0,0 +1,3 @@
+/** @module Doctor operations: check orchestration and types. */
+export { default as runChecks } from "./runChecks.js";
+export type { CheckContext, CheckResult, DoctorData } from "./types.js";

package/src/domains/doctor/operations/runChecks.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("./checks/index.js", () => ({
+  checkNodeVersion: vi.fn(),
+  checkPragmaVersion: vi.fn(),
+  checkConfigFile: vi.fn(),
+  checkKeStore: vi.fn(),
+  checkShellCompletions: vi.fn(),
+  checkMcpConfigured: vi.fn(),
+  checkSkillsSymlinked: vi.fn(),
+}));
+
+import {
+  checkConfigFile,
+  checkKeStore,
+  checkMcpConfigured,
+  checkNodeVersion,
+  checkPragmaVersion,
+  checkShellCompletions,
+  checkSkillsSymlinked,
+} from "./checks/index.js";
+import runChecks from "./runChecks.js";
+
+const pass = (name: string) => ({
+  name,
+  status: "pass" as const,
+  detail: "ok",
+});
+const fail = (name: string) => ({
+  name,
+  status: "fail" as const,
+  detail: "bad",
+  remedy: "fix it",
+});
+const skip = (name: string) => ({
+  name,
+  status: "skip" as const,
+  detail: "skipped",
+});
+
+describe("runChecks", () => {
+  it("returns correct counts when all pass", async () => {
+    vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
+    vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
+    vi.mocked(checkConfigFile).mockResolvedValue(pass("config"));
+    vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
+    vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
+    vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
+
+    const data = await runChecks({ cwd: "/test" });
+    expect(data.passed).toBe(7);
+    expect(data.failed).toBe(0);
+    expect(data.skipped).toBe(0);
+    expect(data.checks).toHaveLength(7);
+  });
+
+  it("counts failures and skips correctly", async () => {
+    vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
+    vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
+    vi.mocked(checkConfigFile).mockResolvedValue(fail("config"));
+    vi.mocked(checkKeStore).mockResolvedValue(fail("store"));
+    vi.mocked(checkShellCompletions).mockResolvedValue(fail("completions"));
+    vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkSkillsSymlinked).mockResolvedValue(skip("skills"));
+
+    const data = await runChecks({ cwd: "/test" });
+    expect(data.passed).toBe(3);
+    expect(data.failed).toBe(3);
+    expect(data.skipped).toBe(1);
+  });
+
+  it("preserves check order", async () => {
+    vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
+    vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
+    vi.mocked(checkConfigFile).mockResolvedValue(pass("config"));
+    vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
+    vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
+    vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
+
+    const data = await runChecks({ cwd: "/test" });
+    expect(data.checks[0].name).toBe("Node");
+    expect(data.checks[1].name).toBe("pragma");
+    expect(data.checks[2].name).toBe("config");
+    expect(data.checks[3].name).toBe("store");
+    expect(data.checks[6].name).toBe("skills");
+  });
+});

package/src/domains/doctor/operations/runChecks.ts

@@ -0,0 +1,38 @@
+import {
+  checkConfigFile,
+  checkKeStore,
+  checkMcpConfigured,
+  checkNodeVersion,
+  checkPragmaVersion,
+  checkShellCompletions,
+  checkSkillsSymlinked,
+} from "./checks/index.js";
+import type { CheckContext, CheckResult, DoctorData } from "./types.js";
+
+/**
+ * Orchestrate all environment health checks sequentially and return
+ * a DoctorData summary with pass/fail/skip counts.
+ *
+ * @param ctx - Check context containing the working directory.
+ * @returns Aggregated check results.
+ * @note Impure
+ */
+export default async function runChecks(
+  ctx: CheckContext,
+): Promise<DoctorData> {
+  const checks: CheckResult[] = [];
+
+  checks.push(await checkNodeVersion());
+  checks.push(await checkPragmaVersion());
+  checks.push(await checkConfigFile(ctx));
+  checks.push(await checkKeStore(ctx));
+  checks.push(await checkShellCompletions());
+  checks.push(await checkMcpConfigured(ctx));
+  checks.push(await checkSkillsSymlinked(ctx));
+
+  const passed = checks.filter((c) => c.status === "pass").length;
+  const failed = checks.filter((c) => c.status === "fail").length;
+  const skipped = checks.filter((c) => c.status === "skip").length;
+
+  return { checks, passed, failed, skipped };
+}

package/src/domains/doctor/operations/types.ts

@@ -0,0 +1,20 @@
+/** Result of a single doctor check. */
+export interface CheckResult {
+  readonly name: string;
+  readonly status: "pass" | "fail" | "skip";
+  readonly detail: string;
+  readonly remedy?: string;
+}
+
+/** Context passed to each doctor check, providing the working directory. */
+export interface CheckContext {
+  readonly cwd: string;
+}
+
+/** Aggregated results from all doctor checks. */
+export interface DoctorData {
+  readonly checks: readonly CheckResult[];
+  readonly passed: number;
+  readonly failed: number;
+  readonly skipped: number;
+}

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

@@ -0,0 +1,4 @@
+/** @module Barrel for graph command builders. */
+
+export { default as inspectCommand } from "./inspect.js";
+export { default as queryCommand } from "./query.js";

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

@@ -0,0 +1,94 @@
+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 { PREFIX_MAP } from "../../shared/prefixes.js";
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type { InspectResult } from "../../shared/types.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 = `${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

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

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

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

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

@@ -0,0 +1,45 @@
+import chalk from "chalk";
+import { formatHeading } from "#pipeline";
+import type { Formatters } from "../../shared/formatters.js";
+import type { InspectResult } from "../../shared/types.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(result.uri));
+
+    for (const g of result.groups) {
+      lines.push("");
+      lines.push(chalk.bold(g.predicate));
+      for (const o of g.objects) {
+        lines.push(`  ${o}`);
+      }
+    }
+
+    return lines.join("\n");
+  },
+
+  llm(result) {
+    const lines = [`## ${result.uri}`, ""];
+    for (const g of result.groups) {
+      lines.push(`**${g.predicate}:**`);
+      for (const o of g.objects) {
+        lines.push(`  - ${o}`);
+      }
+    }
+    return lines.join("\n");
+  },
+
+  json(result) {
+    return JSON.stringify(result, null, 2);
+  },
+};
+
+export default formatters;