@canonical/pragma-cli 0.18.0

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

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

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

@@ -0,0 +1,93 @@
+/**
+ * MCP tool specs for the ontology domain.
+ */
+
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { listOntologies, showOntology } from "../operations/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "ontology_list",
+    description:
+      "List all ontologies loaded in the knowledge graph with class and property counts.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { condensed }) {
+      const result = await listOntologies(rt.store);
+
+      if (condensed) {
+        const lines = ["## Ontologies", ""];
+        for (const o of result) {
+          lines.push(
+            `- **${o.prefix}:** (${o.namespace}) | classes: ${o.classCount} | properties: ${o.propertyCount}`,
+          );
+        }
+        const text = lines.join("\n");
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data: result, meta: { count: result.length } };
+    },
+  },
+  {
+    name: "ontology_show",
+    description:
+      "Show detailed schema for an ontology including classes and properties.",
+    params: {
+      prefix: {
+        type: "string",
+        description: "Ontology prefix (e.g. 'ds', 'cs')",
+        optional: false,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { prefix, condensed }) {
+      const result = await showOntology(rt.store, prefix as string);
+
+      if (condensed) {
+        const lines = [`## ${result.prefix}: (${result.namespace})`, ""];
+        if (result.classes.length > 0) {
+          lines.push("### Classes");
+          for (const c of result.classes) {
+            const sup = c.superclass ? ` extends ${c.superclass}` : "";
+            lines.push(`- **${c.label}**${sup}`);
+          }
+          lines.push("");
+        }
+        if (result.properties.length > 0) {
+          lines.push("### Properties");
+          for (const p of result.properties) {
+            const domain = p.domain ? ` domain: ${p.domain}` : "";
+            const range = p.range ? ` range: ${p.range}` : "";
+            lines.push(`- **${p.label}** (${p.type})${domain}${range}`);
+          }
+        }
+        const text = lines.join("\n");
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data: result };
+    },
+  },
+];
+
+export default specs;

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

@@ -0,0 +1,5 @@
+/** @module Barrel for ontology operations. */
+
+export { default as listOntologies } from "./listOntologies.js";
+export { default as showOntology } from "./showOntology.js";
+export { default as showOntologyRaw } from "./showOntologyRaw.js";

package/src/domains/ontology/operations/listOntologies.test.ts

@@ -0,0 +1,45 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import listOntologies from "./listOntologies.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("listOntologies", () => {
+  it("returns loaded namespaces with counts", async () => {
+    const result = await listOntologies(store);
+    expect(result.length).toBeGreaterThan(0);
+
+    const ds = result.find((o) => o.prefix === "ds");
+    expect(ds).toBeDefined();
+    expect(ds?.namespace).toBe(PREFIX_MAP.ds);
+    expect(ds?.classCount).toBeGreaterThan(0);
+    expect(ds?.propertyCount).toBeGreaterThan(0);
+    expect(ds?.anatomyCount).toBeGreaterThan(0);
+  });
+
+  it("includes cs namespace", async () => {
+    const result = await listOntologies(store);
+    const cs = result.find((o) => o.prefix === "cs");
+    expect(cs).toBeDefined();
+    expect(cs?.classCount).toBeGreaterThan(0);
+    expect(cs?.anatomyCount).toBe(0);
+  });
+
+  it("returns sorted by prefix", async () => {
+    const result = await listOntologies(store);
+    const prefixes = result.map((o) => o.prefix);
+    const sorted = [...prefixes].sort();
+    expect(prefixes).toEqual(sorted);
+  });
+});

package/src/domains/ontology/operations/listOntologies.ts

@@ -0,0 +1,101 @@
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type { OntologySummary } from "../../shared/types.js";
+import findNamespace from "../helpers/findNamespace.js";
+
+/** Check whether a URI belongs to the anatomy namespace. */
+function isAnatomyTerm(uri: string): boolean {
+  return uri.toLowerCase().includes("anatomy");
+}
+
+/**
+ * List all loaded ontology namespaces with their class, property, and anatomy counts.
+ *
+ * Discovers namespaces by querying for `owl:Class` and
+ * `owl:ObjectProperty`/`owl:DatatypeProperty` definitions, then maps
+ * namespace URIs back to prefixes via `store.prefixes`.
+ *
+ * @param store - The ke store to query.
+ * @returns An array of {@link OntologySummary} sorted alphabetically by prefix.
+ *
+ * @note Queries ke store
+ */
+export default async function listOntologies(
+  store: Store,
+): Promise<OntologySummary[]> {
+  const classResult = await store.query(
+    buildQuery(`
+      SELECT ?class
+      WHERE { ?class a ${P.owl}Class }
+    `),
+  );
+
+  const propResult = await store.query(
+    buildQuery(`
+      SELECT ?prop ?propType
+      WHERE {
+        ?prop a ?propType .
+        VALUES ?propType { ${P.owl}ObjectProperty ${P.owl}DatatypeProperty }
+      }
+    `),
+  );
+
+  const prefixEntries = Object.entries(store.prefixes);
+  const classCounts = new Map<string, Set<string>>();
+  const propCounts = new Map<string, Set<string>>();
+  const anatomyCounts = new Map<string, Set<string>>();
+
+  if (classResult.type === "select") {
+    for (const b of classResult.bindings) {
+      const uri = b.class ?? "";
+      const ns = findNamespace(uri, prefixEntries);
+      if (ns) {
+        const set = classCounts.get(ns.prefix) ?? new Set();
+        set.add(uri);
+        classCounts.set(ns.prefix, set);
+
+        if (isAnatomyTerm(uri)) {
+          const anatomySet = anatomyCounts.get(ns.prefix) ?? new Set();
+          anatomySet.add(uri);
+          anatomyCounts.set(ns.prefix, anatomySet);
+        }
+      }
+    }
+  }
+
+  if (propResult.type === "select") {
+    for (const b of propResult.bindings) {
+      const uri = b.prop ?? "";
+      const ns = findNamespace(uri, prefixEntries);
+      if (ns) {
+        const set = propCounts.get(ns.prefix) ?? new Set();
+        set.add(uri);
+        propCounts.set(ns.prefix, set);
+
+        if (isAnatomyTerm(uri)) {
+          const anatomySet = anatomyCounts.get(ns.prefix) ?? new Set();
+          anatomySet.add(uri);
+          anatomyCounts.set(ns.prefix, anatomySet);
+        }
+      }
+    }
+  }
+
+  const allPrefixes = new Set([
+    ...classCounts.keys(),
+    ...propCounts.keys(),
+    ...anatomyCounts.keys(),
+  ]);
+
+  return [...allPrefixes].sort().map((prefix) => {
+    const namespace = prefixEntries.find(([p]) => p === prefix)?.[1] ?? "";
+    return {
+      prefix,
+      namespace,
+      classCount: classCounts.get(prefix)?.size ?? 0,
+      propertyCount: propCounts.get(prefix)?.size ?? 0,
+      anatomyCount: anatomyCounts.get(prefix)?.size ?? 0,
+    };
+  });
+}

package/src/domains/ontology/operations/showOntology.test.ts

@@ -0,0 +1,65 @@
+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 { PREFIX_MAP } from "../../shared/prefixes.js";
+import showOntology from "./showOntology.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("showOntology", () => {
+  it("returns classes and properties for a prefix", async () => {
+    const result = await showOntology(store, "ds");
+    expect(result.prefix).toBe("ds");
+    expect(result.namespace).toBe(PREFIX_MAP.ds);
+    expect(result.classes.length).toBeGreaterThan(0);
+    expect(result.properties.length).toBeGreaterThan(0);
+  });
+
+  it("includes class labels and superclass relationships", async () => {
+    const result = await showOntology(store, "ds");
+    const component = result.classes.find((c) => c.label === "Component");
+    expect(component).toBeDefined();
+    expect(component?.superclass).toContain("UIBlock");
+  });
+
+  it("includes property domain and range", async () => {
+    const result = await showOntology(store, "ds");
+    const nameProp = result.properties.find((p) => p.uri.endsWith("name"));
+    expect(nameProp).toBeDefined();
+    expect(nameProp?.domain).toContain("UIBlock");
+    expect(nameProp?.type).toBe("datatype");
+  });
+
+  it("resolves full namespace URI", async () => {
+    const result = await showOntology(store, PREFIX_MAP.ds);
+    expect(result.prefix).toBe("ds");
+    expect(result.classes.length).toBeGreaterThan(0);
+  });
+
+  it("throws PragmaError.invalidInput for unknown prefix", async () => {
+    await expect(showOntology(store, "unknown")).rejects.toThrow(PragmaError);
+
+    try {
+      await showOntology(store, "unknown");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+
+  it("returns cs ontology with standard classes", async () => {
+    const result = await showOntology(store, "cs");
+    expect(result.prefix).toBe("cs");
+    const standard = result.classes.find((c) => c.uri.includes("CodeStandard"));
+    expect(standard).toBeDefined();
+  });
+});

package/src/domains/ontology/operations/showOntology.ts

@@ -0,0 +1,41 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import type { OntologyDetailed } from "../../shared/types.js";
+import queryClasses from "../helpers/queryClasses.js";
+import queryProperties from "../helpers/queryProperties.js";
+import resolvePrefix from "../helpers/resolvePrefix.js";
+
+/**
+ * Returns detailed schema for a namespace, including its classes and properties.
+ *
+ * Accepts a short prefix (e.g. `ds`) or a full namespace URI.
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param prefixOrUri - A short prefix or full namespace URI.
+ * @returns An {@link OntologyDetailed} with classes and properties.
+ * @throws PragmaError.invalidInput if the prefix or namespace is unknown.
+ * @throws PragmaError.notFound if the namespace has no classes or properties.
+ */
+export default async function showOntology(
+  store: Store,
+  prefixOrUri: string,
+): Promise<OntologyDetailed> {
+  const { prefix, namespace } = resolvePrefix(prefixOrUri, store.prefixes);
+
+  const classes = await queryClasses(store, namespace);
+  const properties = await queryProperties(store, namespace);
+
+  if (classes.length === 0 && properties.length === 0) {
+    throw PragmaError.notFound("ontology", prefixOrUri, {
+      recovery: {
+        message: "List loaded ontologies.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+
+  return { prefix, namespace, classes, properties };
+}

package/src/domains/ontology/operations/showOntologyRaw.test.ts

@@ -0,0 +1,39 @@
+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 { PREFIX_MAP } from "../../shared/prefixes.js";
+import showOntologyRaw from "./showOntologyRaw.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("showOntologyRaw", () => {
+  it("returns triples for a known namespace", async () => {
+    const triples = await showOntologyRaw(store, "ds");
+    expect(triples.length).toBeGreaterThan(0);
+
+    const hasDs = triples.some((t) => t.subject.startsWith(PREFIX_MAP.ds));
+    expect(hasDs).toBe(true);
+  });
+
+  it("throws PragmaError.invalidInput for unknown prefix", async () => {
+    await expect(showOntologyRaw(store, "unknown")).rejects.toThrow(
+      PragmaError,
+    );
+
+    try {
+      await showOntologyRaw(store, "unknown");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+});

package/src/domains/ontology/operations/showOntologyRaw.ts

@@ -0,0 +1,50 @@
+import type { Store, Triple } from "@canonical/ke";
+import { PragmaError } from "#error";
+import { buildQuery } from "../../shared/buildQuery.js";
+import resolvePrefix from "../helpers/resolvePrefix.js";
+
+/**
+ * Retrieves raw triples for a namespace via a SPARQL CONSTRUCT query.
+ *
+ * Returns all triples where the subject or predicate starts with the
+ * resolved namespace URI.
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param prefixOrUri - A short prefix or full namespace URI.
+ * @returns An array of raw {@link Triple} objects.
+ * @throws PragmaError.invalidInput if the prefix or namespace is unknown.
+ * @throws PragmaError.notFound if the namespace yields no triples.
+ */
+export default async function showOntologyRaw(
+  store: Store,
+  prefixOrUri: string,
+): Promise<Triple[]> {
+  const { namespace } = resolvePrefix(prefixOrUri, store.prefixes);
+
+  const result = await store.query(
+    buildQuery(`
+      CONSTRUCT { ?s ?p ?o }
+      WHERE {
+        ?s ?p ?o .
+        FILTER(
+          STRSTARTS(STR(?s), "${namespace}") ||
+          STRSTARTS(STR(?p), "${namespace}")
+        )
+      }
+    `),
+  );
+
+  if (result.type !== "construct" || result.triples.length === 0) {
+    throw PragmaError.notFound("ontology", prefixOrUri, {
+      recovery: {
+        message: "List loaded ontologies.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+
+  return result.triples;
+}

package/src/domains/setup/commands/all.ts

@@ -0,0 +1,58 @@
+import type { CommandDefinition, CommandResult } from "@canonical/cli-core";
+import runSetupTask from "../helpers/runSetupTask.js";
+import setupAll from "../operations/setupAll.js";
+
+/**
+ * `pragma setup all` command definition.
+ *
+ * Runs all setup steps (completions, lsp, mcp) as a single
+ * composed Task with confirmation gates.
+ *
+ * @note Impure
+ */
+const allCommand: CommandDefinition = {
+  path: ["setup", "all"],
+  description: "Run all setup steps (completions, lsp, mcp)",
+  parameters: [
+    {
+      name: "dryRun",
+      description: "Preview changes without writing",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "undo",
+      description: "Reverse a previous setup",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "yes",
+      description: "Skip all confirmation prompts",
+      type: "boolean",
+      default: false,
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma setup all",
+      "pragma setup all --yes",
+      "pragma setup all --dry-run",
+      "pragma setup all --undo",
+    ],
+  },
+  execute: async (
+    params: Record<string, unknown>,
+    ctx,
+  ): Promise<CommandResult> =>
+    runSetupTask(setupAll(ctx.cwd), {
+      dryRun: params.dryRun === true,
+      undo: params.undo === true,
+      yes: params.yes === true,
+      verbose: ctx.globalFlags.verbose,
+      llm: ctx.globalFlags.llm,
+      format: ctx.globalFlags.format,
+    }),
+};
+
+export default allCommand;

package/src/domains/setup/commands/completions.ts

@@ -0,0 +1,85 @@
+import type { CommandDefinition, CommandResult } from "@canonical/cli-core";
+import type { ShellId } from "../helpers/detectShell.js";
+import runSetupTask from "../helpers/runSetupTask.js";
+import setupCompletions from "../operations/setupCompletions.js";
+
+/**
+ * Map boolean shell flags to a ShellId.
+ *
+ * @param params - Command parameters containing optional shell flags.
+ * @returns The forced ShellId, or undefined to auto-detect.
+ */
+function resolveForceShell(
+  params: Record<string, unknown>,
+): ShellId | undefined {
+  if (params.zsh === true) return "zsh";
+  if (params.bash === true) return "bash";
+  if (params.fish === true) return "fish";
+  return undefined;
+}
+
+/**
+ * `pragma setup completions` command definition.
+ *
+ * Installs shell completion scripts for bash, zsh, or fish.
+ * Auto-detects the shell unless overridden with --zsh, --bash, or --fish.
+ *
+ * @note Impure
+ */
+const completionsCommand: CommandDefinition = {
+  path: ["setup", "completions"],
+  description: "Install shell completion scripts",
+  parameters: [
+    {
+      name: "dryRun",
+      description: "Preview changes without writing",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "undo",
+      description: "Reverse a previous setup",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "zsh",
+      description: "Force zsh completions",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "bash",
+      description: "Force bash completions",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "fish",
+      description: "Force fish completions",
+      type: "boolean",
+      default: false,
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma setup completions",
+      "pragma setup completions --zsh",
+      "pragma setup completions --dry-run",
+      "pragma setup completions --undo",
+    ],
+  },
+  execute: async (
+    params: Record<string, unknown>,
+    ctx,
+  ): Promise<CommandResult> =>
+    runSetupTask(setupCompletions(resolveForceShell(params)), {
+      dryRun: params.dryRun === true,
+      undo: params.undo === true,
+      verbose: ctx.globalFlags.verbose,
+      llm: ctx.globalFlags.llm,
+      format: ctx.globalFlags.format,
+    }),
+};
+
+export default completionsCommand;