@canonical/pragma-cli 0.18.0

package/src/domains/modifier/orchestration/resolveModifierList.ts

@@ -0,0 +1,16 @@
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import { listModifiers } from "../operations/index.js";
+import type { ModifierListResolution } from "../types.js";
+import modifierEmptyError from "./modifierEmptyError.js";
+
+export default async function resolveModifierList(
+  rt: Pick<PragmaRuntime, "store">,
+): Promise<ModifierListResolution> {
+  const items = await listModifiers(rt.store);
+
+  if (items.length === 0) {
+    throw modifierEmptyError();
+  }
+
+  return { items };
+}

package/src/domains/modifier/orchestration/resolveModifierLookup.ts

@@ -0,0 +1,20 @@
+import type { LookupContract, LookupResult } from "../../shared/contracts.js";
+import lookupMany from "../../shared/lookupMany.js";
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type { ModifierFamily } from "../../shared/types.js";
+import { lookupModifier } from "../operations/index.js";
+
+export default async function resolveModifierLookup(
+  store: Pick<PragmaRuntime, "store">["store"],
+  queries: readonly string[],
+): Promise<LookupContract<ModifierFamily>> {
+  const result: LookupResult<ModifierFamily> = await lookupMany(
+    queries,
+    (query) => lookupModifier(store, query),
+  );
+
+  return {
+    params: { names: queries },
+    result,
+  };
+}

package/src/domains/modifier/types.ts

@@ -0,0 +1,5 @@
+import type { ModifierFamily } from "../shared/types.js";
+
+export interface ModifierListResolution {
+  readonly items: readonly ModifierFamily[];
+}

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

@@ -0,0 +1,4 @@
+/** @module Barrel for ontology command builders. */
+
+export { default as listCommand } from "./list.js";
+export { default as showCommand } from "./show.js";

package/src/domains/ontology/commands/list.test.ts

@@ -0,0 +1,82 @@
+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 type { PragmaRuntime } from "../../shared/runtime.js";
+import type { OntologySummary } from "../../shared/types.js";
+import buildListCommand from "./list.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("ontology list command", () => {
+  it("returns ontology summaries", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { value } = await executeOutput(cmd, {}, ctx);
+
+    const prefixes = (value as OntologySummary[]).map((item) => item.prefix);
+    expect(prefixes).toContain("ds");
+    expect(prefixes).toContain("cs");
+  });
+
+  it("renders plain output", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+
+    expect(text).toContain("ds");
+    expect(text).toContain("classes:");
+    expect(text).toContain("anatomy:");
+  });
+
+  it("renders llm output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+
+    expect(text).toContain("## Ontologies");
+    expect(text).toContain("**ds:**");
+    expect(text).toContain("anatomy:");
+  });
+
+  it("renders json output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+
+    const parsed = JSON.parse(text) as OntologySummary[];
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.some((item) => item.prefix === "ds")).toBe(true);
+  });
+});

package/src/domains/ontology/commands/list.ts

@@ -0,0 +1,46 @@
+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 { listFormatters } from "../formatters/index.js";
+import { listOntologies } from "../operations/index.js";
+
+/**
+ * Builds the `pragma ontology list` command definition.
+ *
+ * Lists all loaded ontology namespaces with class and property counts.
+ *
+ * @param ctx - Pragma runtime context providing the ke store and config.
+ * @returns A command definition for `ontology list`.
+ */
+export default function buildListCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["ontology", "list"],
+    description: "List loaded ontologies",
+    parameters: [],
+    meta: {
+      examples: ["pragma ontology list", "pragma ontology list --llm"],
+    },
+    execute: async (): Promise<CommandResult> => {
+      const ontologies = await listOntologies(ctx.store);
+
+      if (ontologies.length === 0) {
+        throw PragmaError.emptyResults("ontology", {
+          recovery: {
+            message: "Ensure design system packages are installed.",
+          },
+        });
+      }
+
+      return createOutputResult(ontologies, {
+        plain: selectFormatter(ctx, listFormatters),
+      });
+    },
+  };
+}

package/src/domains/ontology/commands/show.test.ts

@@ -0,0 +1,103 @@
+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 type { PragmaRuntime } from "../../shared/runtime.js";
+import type { OntologyDetailed } from "../../shared/types.js";
+import buildShowCommand from "./show.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("ontology show command", () => {
+  it("returns ontology details", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+    const { value } = await executeOutput(cmd, { prefix: "ds" }, ctx);
+
+    const result = value as OntologyDetailed;
+    expect(result.prefix).toBe("ds");
+    expect(result.classes.length).toBeGreaterThan(0);
+    expect(result.properties.length).toBeGreaterThan(0);
+  });
+
+  it("completes ontology prefixes", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+    const complete = cmd.parameters[0]?.complete;
+
+    expect(complete).toBeTypeOf("function");
+    const matches = await complete?.("d", ctx);
+    expect(matches).toContain("ds");
+  });
+
+  it("renders plain output", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+    const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
+
+    expect(text).toContain("Classes");
+    expect(text).toContain("Properties");
+  });
+
+  it("renders llm output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildShowCommand(ctx);
+    const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
+
+    expect(text).toContain("## ds:");
+    expect(text).toContain("### Classes");
+  });
+
+  it("renders json output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildShowCommand(ctx);
+    const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
+
+    const parsed = JSON.parse(text) as OntologyDetailed;
+    expect(parsed.prefix).toBe("ds");
+  });
+
+  it("throws structured error when prefix is missing", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+
+    await expect(cmd.execute({}, ctx)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      recovery: {
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  });
+});

package/src/domains/ontology/commands/show.ts

@@ -0,0 +1,66 @@
+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 { showFormatters } from "../formatters/index.js";
+import { listOntologies, showOntology } from "../operations/index.js";
+
+/**
+ * Builds the `pragma ontology show` command definition.
+ *
+ * Displays detailed schema (classes and properties) for a given ontology
+ * prefix. Provides tab-completion for the prefix parameter.
+ *
+ * @param ctx - Pragma runtime context providing the ke store and config.
+ * @returns A command definition for `ontology show`.
+ */
+export default function buildShowCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["ontology", "show"],
+    description: "Show ontology schema details",
+    parameters: [
+      {
+        name: "prefix",
+        description: "Ontology prefix (e.g. 'ds', 'cs')",
+        type: "string",
+        positional: true,
+        required: true,
+        complete: async (partial: string) => {
+          const all = await listOntologies(ctx.store);
+          return all
+            .map((o) => o.prefix)
+            .filter((p) => p.toLowerCase().startsWith(partial.toLowerCase()));
+        },
+      },
+    ],
+    meta: {
+      examples: ["pragma ontology show ds", "pragma ontology show cs --llm"],
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const prefix = params.prefix as string;
+      if (!prefix) {
+        throw PragmaError.invalidInput("prefix", "(empty)", {
+          recovery: {
+            message: "List loaded ontologies to find valid prefixes.",
+            cli: "pragma ontology list",
+            mcp: { tool: "ontology_list" },
+          },
+        });
+      }
+
+      const result = await showOntology(ctx.store, prefix);
+
+      return createOutputResult(result, {
+        plain: selectFormatter(ctx, showFormatters),
+      });
+    },
+  };
+}

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

@@ -0,0 +1,4 @@
+/** @module Barrel for ontology formatters. */
+
+export { default as listFormatters } from "./list.js";
+export { default as showFormatters } from "./show.js";

package/src/domains/ontology/formatters/list.ts

@@ -0,0 +1,37 @@
+import chalk from "chalk";
+import type { Formatters } from "../../shared/formatters.js";
+import type { OntologySummary } from "../../shared/types.js";
+
+/**
+ * Formatters for `pragma ontology list` output.
+ *
+ * - **plain**: one line per ontology with chalk-styled prefix, namespace, and counts.
+ * - **llm**: condensed Markdown bullet list under an `## Ontologies` heading.
+ * - **json**: serialized ontology summary array as indented JSON.
+ */
+const formatters: Formatters<readonly OntologySummary[]> = {
+  plain(ontologies) {
+    return ontologies
+      .map(
+        (o) =>
+          `${chalk.bold(o.prefix)} ${chalk.dim(`(${o.namespace})`)} classes: ${o.classCount} properties: ${o.propertyCount} anatomy: ${o.anatomyCount}`,
+      )
+      .join("\n");
+  },
+
+  llm(ontologies) {
+    const lines = ["## Ontologies", ""];
+    for (const o of ontologies) {
+      lines.push(
+        `- **${o.prefix}:** (${o.namespace}) | classes: ${o.classCount} | properties: ${o.propertyCount} | anatomy: ${o.anatomyCount}`,
+      );
+    }
+    return lines.join("\n");
+  },
+
+  json(ontologies) {
+    return JSON.stringify(ontologies, null, 2);
+  },
+};
+
+export default formatters;

package/src/domains/ontology/formatters/show.ts

@@ -0,0 +1,74 @@
+import chalk from "chalk";
+import { formatHeading, formatSection } from "#pipeline";
+import type { Formatters } from "../../shared/formatters.js";
+import type { OntologyDetailed } from "../../shared/types.js";
+
+/**
+ * Formatters for `pragma ontology show` output.
+ *
+ * - **plain**: chalk-styled heading with Classes and Properties sections.
+ * - **llm**: condensed Markdown with `### Classes` and `### Properties` sub-headings.
+ * - **json**: serialized {@link OntologyDetailed} as indented JSON.
+ */
+const formatters: Formatters<OntologyDetailed> = {
+  plain(data) {
+    const lines: string[] = [];
+
+    lines.push(formatHeading(`${data.prefix}: (${data.namespace})`));
+
+    if (data.classes.length > 0) {
+      const classLines = data.classes
+        .map((c) => {
+          const sup = c.superclass ? chalk.dim(` extends ${c.superclass}`) : "";
+          return `  ${chalk.bold(c.label)}${sup}`;
+        })
+        .join("\n");
+      lines.push("");
+      lines.push(formatSection("Classes", classLines));
+    }
+
+    if (data.properties.length > 0) {
+      const propLines = data.properties
+        .map((p) => {
+          const domain = p.domain ? chalk.dim(` domain: ${p.domain}`) : "";
+          const range = p.range ? chalk.dim(` range: ${p.range}`) : "";
+          return `  ${chalk.bold(p.label)} (${p.type})${domain}${range}`;
+        })
+        .join("\n");
+      lines.push("");
+      lines.push(formatSection("Properties", propLines));
+    }
+
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const lines = [`## ${data.prefix}: (${data.namespace})`, ""];
+
+    if (data.classes.length > 0) {
+      lines.push("### Classes");
+      for (const c of data.classes) {
+        const sup = c.superclass ? ` extends ${c.superclass}` : "";
+        lines.push(`- **${c.label}**${sup}`);
+      }
+      lines.push("");
+    }
+
+    if (data.properties.length > 0) {
+      lines.push("### Properties");
+      for (const p of data.properties) {
+        const domain = p.domain ? ` domain: ${p.domain}` : "";
+        const range = p.range ? ` range: ${p.range}` : "";
+        lines.push(`- **${p.label}** (${p.type})${domain}${range}`);
+      }
+    }
+
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data, null, 2);
+  },
+};
+
+export default formatters;

package/src/domains/ontology/helpers/findNamespace.ts

@@ -0,0 +1,23 @@
+/**
+ * Finds the namespace prefix for a given URI by matching against registered
+ * prefix entries. When multiple prefixes match, selects the longest
+ * (most specific) namespace.
+ *
+ * @param uri - The full URI to look up.
+ * @param prefixEntries - Array of `[prefix, namespace]` tuples from the store.
+ * @returns The matching `{ prefix, namespace }` or `undefined` if no prefix matches.
+ */
+export default function findNamespace(
+  uri: string,
+  prefixEntries: [string, string][],
+): { prefix: string; namespace: string } | undefined {
+  let best: { prefix: string; namespace: string } | undefined;
+  for (const [prefix, namespace] of prefixEntries) {
+    if (uri.startsWith(namespace)) {
+      if (!best || namespace.length > best.namespace.length) {
+        best = { prefix, namespace };
+      }
+    }
+  }
+  return best;
+}

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

@@ -0,0 +1,7 @@
+/** @module Barrel for ontology helpers. */
+
+export { default as extractLocalName } from "../../shared/extractLocalName.js";
+export { default as findNamespace } from "./findNamespace.js";
+export { default as queryClasses } from "./queryClasses.js";
+export { default as queryProperties } from "./queryProperties.js";
+export { default as resolvePrefix } from "./resolvePrefix.js";

package/src/domains/ontology/helpers/queryClasses.ts

@@ -0,0 +1,50 @@
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import extractLocalName from "../../shared/extractLocalName.js";
+import { P } from "../../shared/prefixes.js";
+import type { OntologyClass } from "../../shared/types.js";
+
+/**
+ * Queries all `owl:Class` definitions within a namespace.
+ *
+ * Deduplicates by class URI -- when a class has multiple `rdfs:subClassOf`
+ * values, only the first superclass encountered is kept.
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param namespace - The namespace URI to filter classes by.
+ * @returns An array of {@link OntologyClass} entries.
+ */
+export default async function queryClasses(
+  store: Store,
+  namespace: string,
+): Promise<OntologyClass[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?class ?label ?superclass
+      WHERE {
+        ?class a ${P.owl}Class .
+        FILTER(STRSTARTS(STR(?class), "${namespace}"))
+        OPTIONAL { ?class ${P.rdfs}label ?label }
+        OPTIONAL { ?class ${P.rdfs}subClassOf ?superclass }
+      }
+      ORDER BY ?class
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  const seen = new Map<string, OntologyClass>();
+  for (const b of result.bindings) {
+    const uri = b.class ?? "";
+    if (seen.has(uri)) continue;
+    seen.set(uri, {
+      uri,
+      label: b.label ?? extractLocalName(uri),
+      ...(b.superclass ? { superclass: b.superclass } : {}),
+    });
+  }
+
+  return [...seen.values()];
+}

package/src/domains/ontology/helpers/queryProperties.ts

@@ -0,0 +1,57 @@
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import extractLocalName from "../../shared/extractLocalName.js";
+import { P } from "../../shared/prefixes.js";
+import type { OntologyProperty } from "../../shared/types.js";
+
+/**
+ * Queries all `owl:ObjectProperty` and `owl:DatatypeProperty` definitions
+ * within a namespace.
+ *
+ * Deduplicates by property URI -- when a property has multiple `rdfs:domain`
+ * or `rdfs:range` values, only the first encountered is kept.
+ *
+ * @note Queries ke store
+ *
+ * @param store - The ke store to query.
+ * @param namespace - The namespace URI to filter properties by.
+ * @returns An array of {@link OntologyProperty} entries.
+ */
+export default async function queryProperties(
+  store: Store,
+  namespace: string,
+): Promise<OntologyProperty[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?prop ?label ?domain ?range ?propType
+      WHERE {
+        ?prop a ?propType .
+        VALUES ?propType { ${P.owl}ObjectProperty ${P.owl}DatatypeProperty }
+        FILTER(STRSTARTS(STR(?prop), "${namespace}"))
+        OPTIONAL { ?prop ${P.rdfs}label ?label }
+        OPTIONAL { ?prop ${P.rdfs}domain ?domain }
+        OPTIONAL { ?prop ${P.rdfs}range ?range }
+      }
+      ORDER BY ?prop
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  const seen = new Map<string, OntologyProperty>();
+  for (const b of result.bindings) {
+    const uri = b.prop ?? "";
+    if (seen.has(uri)) continue;
+    seen.set(uri, {
+      uri,
+      label: b.label ?? extractLocalName(uri),
+      ...(b.domain ? { domain: b.domain } : {}),
+      ...(b.range ? { range: b.range } : {}),
+      type: b.propType?.includes("ObjectProperty")
+        ? ("object" as const)
+        : ("datatype" as const),
+    });
+  }
+
+  return [...seen.values()];
+}

package/src/domains/ontology/helpers/resolvePrefix.ts

@@ -0,0 +1,45 @@
+import { PragmaError } from "#error";
+
+/**
+ * Resolves a prefix string or full namespace URI to both prefix and namespace.
+ *
+ * Accepts either a short prefix (e.g. `ds`) or a full namespace URI
+ * (e.g. `https://ds.canonical.com/`) and returns the matching pair.
+ *
+ * @param prefixOrUri - A short prefix or full namespace URI.
+ * @param prefixes - Registered prefix-to-namespace mapping from the store.
+ * @returns An object with `prefix` and `namespace` strings.
+ * @throws PragmaError.invalidInput if the prefix or namespace is unknown.
+ */
+export default function resolvePrefix(
+  prefixOrUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): { prefix: string; namespace: string } {
+  if (prefixOrUri.startsWith("http://") || prefixOrUri.startsWith("https://")) {
+    const entry = Object.entries(prefixes).find(([, ns]) => ns === prefixOrUri);
+    if (entry) return { prefix: entry[0], namespace: entry[1] };
+
+    throw PragmaError.invalidInput("namespace", prefixOrUri, {
+      validOptions: Object.values(prefixes),
+      recovery: {
+        message: "List loaded ontology namespaces.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+
+  const namespace = prefixes[prefixOrUri];
+  if (namespace === undefined) {
+    throw PragmaError.invalidInput("prefix", prefixOrUri, {
+      validOptions: Object.keys(prefixes),
+      recovery: {
+        message: "List loaded ontologies.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+
+  return { prefix: prefixOrUri, namespace };
+}

package/src/domains/ontology/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @module Ontology domain barrel.
+ *
+ * Provides ontology listing, detailed schema inspection, and raw triple retrieval.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import { listCommand, showCommand } from "./commands/index.js";
+
+/**
+ * Returns all command definitions for the ontology domain.
+ *
+ * @param ctx - Pragma runtime context.
+ * @returns An array of command definitions (`ontology list`, `ontology show`).
+ */
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [listCommand(ctx), showCommand(ctx)];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export {
+  listOntologies,
+  showOntology,
+  showOntologyRaw,
+} from "./operations/index.js";