@canonical/pragma-cli 0.18.0

package/src/domains/modifier/commands/lookup.test.ts

@@ -0,0 +1,91 @@
+import type { CommandOutputResult } from "@canonical/cli-core";
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import type { PragmaContext } from "../../shared/context.js";
+import lookupCommand from "./lookup.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());
+
+function makeCtx(
+  overrides?: Partial<PragmaContext["globalFlags"]>,
+): PragmaContext {
+  return {
+    cwd: "/tmp",
+    store,
+    config: { tier: undefined, channel: "normal" },
+    globalFlags: {
+      llm: false,
+      format: "text",
+      verbose: false,
+      ...overrides,
+    },
+  };
+}
+
+describe("modifier lookup command", () => {
+  it("returns a family with values", async () => {
+    const ctx = makeCtx();
+    const cmd = lookupCommand(ctx);
+    const result = await cmd.execute({ names: ["density"] }, ctx);
+    expect(result.tag).toBe("output");
+
+    const output = result as CommandOutputResult;
+    const text = output.render.plain(output.value);
+    expect(text).toContain("density");
+    expect(text).toContain("default");
+    expect(text).toContain("compact");
+  });
+
+  it("throws ENTITY_NOT_FOUND for unknown modifier", async () => {
+    const ctx = makeCtx();
+    const cmd = lookupCommand(ctx);
+    const result = await cmd.execute({ names: ["nonexistent"] }, ctx);
+    expect(result.tag).toBe("output");
+    if (result.tag !== "output") {
+      expect.fail("Expected output result");
+    }
+    expect(result.render.plain(result.value)).toContain("Errors:");
+  });
+
+  it("renders LLM format with --llm", async () => {
+    const ctx = makeCtx({ llm: true });
+    const cmd = lookupCommand(ctx);
+    const result = await cmd.execute({ names: ["importance"] }, ctx);
+    const output = result as CommandOutputResult;
+    const text = output.render.plain(output.value);
+    expect(text).toContain("## importance");
+    expect(text).toContain("- default");
+  });
+
+  it("renders JSON with --format json", async () => {
+    const ctx = makeCtx({ format: "json" });
+    const cmd = lookupCommand(ctx);
+    const result = await cmd.execute({ names: ["importance"] }, ctx);
+    const output = result as CommandOutputResult;
+    const text = output.render.plain(output.value);
+    const parsed = JSON.parse(text);
+    expect(parsed.name).toBe("importance");
+    expect(parsed.values).toContain("primary");
+  });
+
+  it("renders multiple families together", async () => {
+    const ctx = makeCtx();
+    const cmd = lookupCommand(ctx);
+    const result = await cmd.execute({ names: ["importance", "density"] }, ctx);
+    expect(result.tag).toBe("output");
+    const output = result as CommandOutputResult;
+    const text = output.render.plain(output.value);
+    expect(text).toContain("importance");
+    expect(text).toContain("density");
+  });
+});

package/src/domains/modifier/commands/lookup.ts

@@ -0,0 +1,105 @@
+/**
+ * Wires the `pragma modifier lookup <name...>` CLI command.
+ *
+ * Retrieves a single modifier family by name and renders its values.
+ */
+
+import {
+  type CommandDefinition,
+  createOutputResult,
+} from "@canonical/cli-core";
+import type { PragmaContext } from "../../shared/context.js";
+import type { LookupResult } from "../../shared/contracts.js";
+import { lookupFormatters } from "../formatters/index.js";
+import type { lookupModifier } from "../operations/index.js";
+import { resolveModifierLookup } from "../orchestration/index.js";
+
+interface ModifierLookupOutput {
+  readonly result: LookupResult<Awaited<ReturnType<typeof lookupModifier>>>;
+}
+
+export default function buildLookupCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["modifier", "lookup"],
+    description: "Look up a modifier family and its values",
+    parameters: [
+      {
+        name: "names",
+        description: "Modifier family names or IRIs",
+        type: "multiselect",
+        positional: true,
+        required: true,
+      },
+    ],
+    meta: {
+      examples: [
+        "pragma modifier lookup importance",
+        "pragma modifier lookup importance density",
+        "pragma modifier lookup importance --llm",
+      ],
+    },
+    async execute(params: Record<string, unknown>) {
+      const names = normalizeNames(params.names, params.name);
+      const contract = await resolveModifierLookup(ctx.store, names);
+
+      return createOutputResult<ModifierLookupOutput>(
+        { result: contract.result },
+        { plain: renderModifierLookupOutput(ctx) },
+      );
+    },
+  };
+}
+
+function normalizeNames(names: unknown, legacyName?: unknown): string[] {
+  if (Array.isArray(names)) {
+    return names.filter(
+      (name): name is string => typeof name === "string" && name.length > 0,
+    );
+  }
+  if (typeof legacyName === "string" && legacyName.length > 0) {
+    return [legacyName];
+  }
+  return [];
+}
+
+function renderModifierLookupOutput(
+  ctx: PragmaContext,
+): (data: ModifierLookupOutput) => string {
+  return ({ result }) => {
+    const formatOne =
+      ctx.globalFlags.format === "json"
+        ? lookupFormatters.json
+        : ctx.globalFlags.llm
+          ? lookupFormatters.llm
+          : lookupFormatters.plain;
+
+    if (ctx.globalFlags.format === "json") {
+      if (result.results.length === 1 && result.errors.length === 0) {
+        const only = result.results[0];
+        return only
+          ? lookupFormatters.json(only)
+          : JSON.stringify({ results: [], errors: result.errors }, null, 2);
+      }
+
+      return JSON.stringify(
+        { results: result.results, errors: result.errors },
+        null,
+        2,
+      );
+    }
+
+    const parts = result.results.map((family) => formatOne(family));
+    if (result.errors.length > 0) {
+      parts.push(
+        [
+          "Errors:",
+          ...result.errors.map((error) => `- ${error.query}: ${error.message}`),
+        ].join("\n"),
+      );
+    }
+
+    return parts.join("\n\n");
+  };
+}

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

@@ -0,0 +1,4 @@
+/** @module Re-exports modifier formatters (`lookupFormatters`, `listFormatters`). */
+
+export { default as listFormatters } from "./list.js";
+export { default as lookupFormatters } from "./lookup.js";

package/src/domains/modifier/formatters/list.test.ts

@@ -0,0 +1,38 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import type { ModifierFamily } from "../../shared/types.js";
+import formatters from "./list.js";
+
+const FAMILIES: ModifierFamily[] = [
+  {
+    uri: "http://example.com/f1" as URI,
+    name: "importance",
+    values: ["default", "primary", "secondary"],
+  },
+  {
+    uri: "http://example.com/f2" as URI,
+    name: "density",
+    values: ["default", "compact"],
+  },
+];
+
+describe("modifier list formatters", () => {
+  it("plain renders name with comma-separated values", () => {
+    const text = formatters.plain(FAMILIES);
+    expect(text).toContain("importance: default, primary, secondary");
+    expect(text).toContain("density: default, compact");
+  });
+
+  it("llm renders markdown heading and bold names", () => {
+    const text = formatters.llm(FAMILIES);
+    expect(text).toContain("## Modifier Families");
+    expect(text).toContain("**importance**");
+    expect(text).toContain("**density**");
+  });
+
+  it("json serializes the full array", () => {
+    const parsed = JSON.parse(formatters.json(FAMILIES));
+    expect(parsed).toHaveLength(2);
+    expect(parsed[0].name).toBe("importance");
+  });
+});

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

@@ -0,0 +1,35 @@
+/**
+ * Three-mode formatter for `pragma modifier list` output.
+ *
+ * - **plain** — one line per family showing name and comma-separated values.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON array for programmatic consumption.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { ModifierFamily } from "../../shared/types.js";
+
+const formatters: Formatters<ModifierFamily[]> = {
+  plain: (families) => {
+    const lines: string[] = [];
+    for (const f of families) {
+      lines.push(`${f.name}: ${f.values.join(", ")}`);
+    }
+    return lines.join("\n");
+  },
+
+  llm: (families) => {
+    const lines: string[] = [];
+    lines.push("## Modifier Families");
+    lines.push("");
+    for (const f of families) {
+      lines.push(`- **${f.name}**: ${f.values.join(", ")}`);
+    }
+    return lines.join("\n");
+  },
+
+  json: (families) => JSON.stringify(families, null, 2),
+};
+
+export default formatters;

package/src/domains/modifier/formatters/lookup.test.ts

@@ -0,0 +1,33 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import type { ModifierFamily } from "../../shared/types.js";
+import formatters from "./lookup.js";
+
+const FAMILY: ModifierFamily = {
+  uri: "http://example.com/f1" as URI,
+  name: "importance",
+  values: ["default", "primary", "secondary"],
+};
+
+describe("modifier lookup formatters", () => {
+  it("plain renders family name and indented values", () => {
+    const text = formatters.plain(FAMILY);
+    expect(text).toContain("importance");
+    expect(text).toContain("Values:");
+    expect(text).toContain("  default");
+    expect(text).toContain("  primary");
+  });
+
+  it("llm renders markdown heading and value list", () => {
+    const text = formatters.llm(FAMILY);
+    expect(text).toContain("## importance");
+    expect(text).toContain("- default");
+    expect(text).toContain("- primary");
+  });
+
+  it("json serializes the full family", () => {
+    const parsed = JSON.parse(formatters.json(FAMILY));
+    expect(parsed.name).toBe("importance");
+    expect(parsed.values).toEqual(["default", "primary", "secondary"]);
+  });
+});

package/src/domains/modifier/formatters/lookup.ts

@@ -0,0 +1,38 @@
+/**
+ * Three-mode formatter for `pragma modifier lookup` output.
+ *
+ * - **plain** — terminal text showing the family name and its values.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON for programmatic consumption.
+ */
+
+import type { Formatters } from "../../shared/formatters.js";
+import type { ModifierFamily } from "../../shared/types.js";
+
+const formatters: Formatters<ModifierFamily> = {
+  plain: (family) => {
+    const lines: string[] = [];
+    lines.push(family.name);
+    lines.push("");
+    lines.push("Values:");
+    for (const v of family.values) {
+      lines.push(`  ${v}`);
+    }
+    return lines.join("\n");
+  },
+
+  llm: (family) => {
+    const lines: string[] = [];
+    lines.push(`## ${family.name}`);
+    lines.push("");
+    for (const v of family.values) {
+      lines.push(`- ${v}`);
+    }
+    return lines.join("\n");
+  },
+
+  json: (family) => JSON.stringify(family, null, 2),
+};
+
+export default formatters;

package/src/domains/modifier/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @module Modifier domain — CLI commands and operations.
+ *
+ * Commands: `pragma modifier list`, `pragma modifier lookup <name>`.
+ * Operations: {@link lookupModifier}, {@link listModifiers}.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import { listCommand, lookupCommand } from "./commands/index.js";
+
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [listCommand(ctx), lookupCommand(ctx)];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export { listModifiers, lookupModifier } from "./operations/index.js";
+export {
+  modifierEmptyError,
+  resolveModifierList,
+  resolveModifierLookup,
+} from "./orchestration/index.js";

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

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

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

@@ -0,0 +1,97 @@
+/**
+ * MCP tool specs for the modifier domain.
+ *
+ * Declarative definitions — no MCP imports. The adapter layer
+ * converts these into registered MCP tools via `registerFromSpec()`.
+ */
+
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import {
+  listFormatters as modifierListFmt,
+  lookupFormatters as modifierLookupFmt,
+} from "../formatters/index.js";
+import {
+  resolveModifierList,
+  resolveModifierLookup,
+} from "../orchestration/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "modifier_list",
+    description: "List all modifier families with their values.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { condensed }) {
+      const resolution = await resolveModifierList(rt);
+
+      if (condensed) {
+        const text = modifierListFmt.llm([...resolution.items]);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return {
+        data: resolution.items,
+        meta: { count: resolution.items.length },
+      };
+    },
+  },
+
+  {
+    name: "modifier_lookup",
+    description: "Get one or more modifier families and their values.",
+    params: {
+      names: {
+        type: "string[]",
+        description: "Modifier family names or IRIs to look up",
+        optional: false,
+      },
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { names, condensed }) {
+      const contract = await resolveModifierLookup(rt.store, names as string[]);
+      const result = contract.result;
+
+      if (condensed) {
+        const textParts = result.results.map((family) =>
+          modifierLookupFmt.llm(family),
+        );
+
+        if (result.errors.length > 0) {
+          textParts.push(
+            [
+              "### Errors",
+              ...result.errors.map(
+                (error) => `- ${error.query}: ${error.message}`,
+              ),
+            ].join("\n"),
+          );
+        }
+
+        return {
+          condensed: true,
+          text: textParts.join("\n\n"),
+          tokens: `~${Math.ceil(textParts.join("\n\n").length / 4)}`,
+        };
+      }
+
+      return { data: result, meta: { count: result.results.length } };
+    },
+  },
+] as const;
+
+export default specs;

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

@@ -0,0 +1,4 @@
+/** @module Re-exports modifier operations (`lookupModifier`, `listModifiers`). */
+
+export { default as listModifiers } from "./list.js";
+export { default as lookupModifier } from "./lookup.js";

package/src/domains/modifier/operations/list.test.ts

@@ -0,0 +1,39 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import listModifiers from "./list.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("listModifiers", () => {
+  it("returns all modifier families", async () => {
+    const result = await listModifiers(store);
+    const names = result.map((m) => m.name);
+    expect(names).toContain("importance");
+    expect(names).toContain("density");
+  });
+
+  it("includes values for each family", async () => {
+    const result = await listModifiers(store);
+    const importance = result.find((m) => m.name === "importance");
+    expect(importance?.values).toContain("default");
+    expect(importance?.values).toContain("primary");
+    expect(importance?.values).toContain("secondary");
+  });
+
+  it("returns sorted by name", async () => {
+    const result = await listModifiers(store);
+    const names = result.map((m) => m.name);
+    const sorted = [...names].sort();
+    expect(names).toEqual(sorted);
+  });
+});

package/src/domains/modifier/operations/list.ts

@@ -0,0 +1,41 @@
+/**
+ * Lists all modifier families with their allowed values, ordered by name.
+ *
+ * @param store - ke store to query
+ * @returns array of modifier families, empty when none exist
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type { ModifierFamily } from "../../shared/types.js";
+
+export default async function listModifiers(
+  store: Store,
+): Promise<ModifierFamily[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?family ?name (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
+      WHERE {
+        ?family a ${P.ds}ModifierFamily ;
+                ${P.ds}name ?name .
+        OPTIONAL {
+          ?mod a ${P.ds}Modifier ;
+               ${P.ds}modifierFamily ?family ;
+               ${P.ds}name ?valueName .
+        }
+      }
+      GROUP BY ?family ?name
+      ORDER BY ?name
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  return result.bindings.map((b) => ({
+    uri: (b.family ?? "") as URI,
+    name: b.name ?? "",
+    values: b.values ? b.values.split("|").filter(Boolean) : [],
+  }));
+}

package/src/domains/modifier/operations/lookup.test.ts

@@ -0,0 +1,37 @@
+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 lookupModifier from "./lookup.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("lookupModifier", () => {
+  it("returns a single modifier family with values", async () => {
+    const result = await lookupModifier(store, "density");
+    expect(result.name).toBe("density");
+    expect(result.values).toContain("default");
+    expect(result.values).toContain("compact");
+  });
+
+  it("throws PragmaError.notFound for unknown modifier", async () => {
+    await expect(lookupModifier(store, "nonexistent")).rejects.toThrow(
+      PragmaError,
+    );
+
+    try {
+      await lookupModifier(store, "nonexistent");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
+    }
+  });
+});

package/src/domains/modifier/operations/lookup.ts

@@ -0,0 +1,57 @@
+/**
+ * Look up a single modifier family by name, including its allowed values.
+ *
+ * @param store - ke store to query
+ * @param name - modifier family name (e.g. "importance")
+ * @returns the modifier family with its value list
+ * @throws PragmaError.notFound if the modifier family does not exist
+ * @note Queries ke store
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { escapeSparqlValue } from "@canonical/ke";
+import { PragmaError } from "#error";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+import type { ModifierFamily } from "../../shared/types.js";
+
+export default async function lookupModifier(
+  store: Store,
+  name: string,
+): Promise<ModifierFamily> {
+  const escaped = escapeSparqlValue(name);
+
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?family (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
+      WHERE {
+        ?family a ${P.ds}ModifierFamily ;
+                ${P.ds}name ${escaped} .
+        OPTIONAL {
+          ?mod a ${P.ds}Modifier ;
+               ${P.ds}modifierFamily ?family ;
+               ${P.ds}name ?valueName .
+        }
+      }
+      GROUP BY ?family
+    `),
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) {
+    throw PragmaError.notFound("modifier", name, {
+      recovery: {
+        message: "List available modifiers.",
+        cli: "pragma modifier list",
+        mcp: { tool: "modifier_list" },
+      },
+    });
+  }
+
+  // Safe: length check above guarantees bindings[0] exists
+  const b = result.bindings[0] as (typeof result.bindings)[number];
+  return {
+    uri: (b.family ?? "") as URI,
+    name,
+    values: b.values ? b.values.split("|").filter(Boolean) : [],
+  };
+}

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

@@ -0,0 +1,3 @@
+export { default as modifierEmptyError } from "./modifierEmptyError.js";
+export { default as resolveModifierList } from "./resolveModifierList.js";
+export { default as resolveModifierLookup } from "./resolveModifierLookup.js";

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

@@ -0,0 +1,10 @@
+import { PragmaError } from "#error";
+
+export default function modifierEmptyError(): PragmaError {
+  return PragmaError.emptyResults("modifier", {
+    recovery: {
+      message:
+        "Ensure design system packages are installed: bun add -D @canonical/ds-global",
+    },
+  });
+}