@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,9 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { compileReadCommand } from "../../shared/stories/index.js";
-import { modifierListStory } from "../stories.js";
-
-/** Wire the `pragma modifier list` CLI command from the modifier list story. */
-export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return compileReadCommand(ctx, modifierListStory);
-}

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

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

@@ -1,14 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { compileLookupCommand } from "../../shared/stories/index.js";
-import { modifierLookupStory } from "../stories.js";
-
-/**
- * Wire the `pragma modifier lookup <name...>` CLI command from the
- * modifier lookup story.
- */
-export default function buildLookupCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return compileLookupCommand(ctx, modifierLookupStory);
-}

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

@@ -1,53 +0,0 @@
-/**
- * Wires the `pragma modifier sample` CLI command.
- *
- * Returns 1–5 complete modifier family instances as exemplars so agents
- * can learn the data shape before writing queries.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import type { ModifierFamily, SampleOutput } from "../../shared/types/index.js";
-import { sampleFormatters } from "../formatters/index.js";
-import { sampleModifiers } from "../operations/index.js";
-
-const NEXT_STEPS = [
-  "Use modifier_lookup to inspect specific modifier families by name.",
-  "Use modifier_list to see all available modifier families.",
-];
-
-export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
-  return {
-    path: ["modifier", "sample"],
-    description:
-      "Return randomly selected complete modifier family instances as exemplars for shape discovery",
-    parameters: [
-      {
-        name: "count",
-        type: "string",
-        description: "Number of samples to return (1–5, default 2)",
-        required: false,
-      },
-    ],
-    meta: {
-      examples: ["pragma modifier sample", "pragma modifier sample --count 3"],
-    },
-    async execute(params) {
-      const count = Number(params.count ?? 2);
-      const result = await sampleModifiers(ctx.store, count);
-
-      const output: SampleOutput<ModifierFamily> = {
-        ...result,
-        nextSteps: NEXT_STEPS,
-      };
-
-      return createOutputResult(output, {
-        plain: selectFormatter(ctx, sampleFormatters),
-      });
-    },
-  };
-}

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

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

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

@@ -1,38 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import type { ModifierFamily } from "../../shared/types/index.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

@@ -1,22 +0,0 @@
-import type { Formatters } from "../../shared/formatters.js";
-import { renderListLlm } from "../../shared/renderers.js";
-import type { ModifierFamily } from "../../shared/types/index.js";
-import { modifierConfig } from "../modifierConfig.js";
-
-/** Three-mode formatter for `pragma modifier list` output. */
-const formatters: Formatters<ModifierFamily[]> = {
-  plain: (families) =>
-    families
-      .map((family) => `${family.name}: ${family.values.join(", ")}`)
-      .join("\n"),
-
-  llm: (families) =>
-    renderListLlm(families, {
-      heading: "Modifier Families",
-      columns: modifierConfig.listColumns,
-    }),
-
-  json: (families) => JSON.stringify(families, null, 2),
-};
-
-export default formatters;

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

@@ -1,33 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import type { ModifierFamily } from "../../shared/types/index.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

@@ -1,50 +0,0 @@
-import type { RenderLookupOptions } from "../../shared/contracts.js";
-import type { Formatters } from "../../shared/formatters.js";
-import { renderLookupLlm, renderLookupPlain } from "../../shared/renderers.js";
-import type {
-  ModifierDetailed,
-  ModifierFamily,
-} from "../../shared/types/index.js";
-import { modifierConfig } from "../modifierConfig.js";
-
-/** Three-mode formatter for `pragma modifier lookup` output. */
-const formatters: Formatters<ModifierFamily> = {
-  plain: (family) =>
-    renderLookupPlain(family, {
-      title: (entry) => entry.name,
-      fields: [{ label: "IRI", value: (entry) => entry.uri }],
-      sections: modifierConfig.lookupSections,
-      sectionOverrides: {
-        values: {
-          plain: (entry) =>
-            entry.values.length > 0
-              ? entry.values.map((value) => `  ${value}`).join("\n")
-              : null,
-        },
-      },
-    }),
-
-  llm: (family) =>
-    renderLookupLlm(family, {
-      title: (entry) => entry.name,
-      fields: [{ label: "IRI", value: (entry) => entry.uri }],
-      sections: modifierConfig.lookupSections,
-    }),
-
-  json: (family) => JSON.stringify(family, null, 2),
-};
-
-export default formatters;
-
-/**
- * Build lookup rendering options for the Ink TUI view.
- *
- * @returns Options compatible with the LookupView component.
- */
-export function createInkLookupOptions(): RenderLookupOptions<ModifierDetailed> {
-  return {
-    title: (entry) => entry.name,
-    fields: [{ label: "IRI", value: (entry) => entry.uri }],
-    sections: modifierConfig.lookupSections,
-  };
-}

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

@@ -1,15 +0,0 @@
-/**
- * Sample formatter for the modifier domain.
- *
- * Delegates to the shared factory, rendering each item via the
- * existing modifier lookup formatter.
- */
-
-import createSampleFormatters from "../../shared/sampleFormatters.js";
-import type { ModifierFamily } from "../../shared/types/index.js";
-import lookupFormatters from "./lookup.js";
-
-export default createSampleFormatters<ModifierFamily>(
-  "modifiers",
-  (family, mode) => lookupFormatters[mode](family),
-);

package/src/domains/modifier/index.ts

@@ -1,27 +0,0 @@
-/**
- * @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, sampleCommand } from "./commands/index.js";
-
-export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx), sampleCommand(ctx)];
-}
-
-export { specs as mcpSpecs } from "./mcp/index.js";
-export { modifierConfig } from "./modifierConfig.js";
-export {
-  listModifiers,
-  lookupModifier,
-  sampleModifiers,
-} from "./operations/index.js";
-export {
-  modifierEmptyError,
-  resolveModifierList,
-  resolveModifierLookup,
-} from "./orchestration/index.js";

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

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

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

@@ -1,65 +0,0 @@
-/**
- * MCP tool specs for the modifier domain — modifier_list, modifier_lookup,
- * modifier_sample.
- *
- * The list and lookup tools are compiled from the modifier read stories in
- * `../stories.ts`; only the sample tool is spec'd by hand. The adapter
- * layer converts these into registered MCP tools via `registerFromSpec()`.
- */
-
-import {
-  compileLookupTool,
-  compileReadTool,
-  condense,
-} from "../../shared/stories/index.js";
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { sampleFormatters as modifierSampleFmt } from "../formatters/index.js";
-import { sampleModifiers } from "../operations/index.js";
-import { modifierListStory, modifierLookupStory } from "../stories.js";
-
-const specs: readonly ToolSpec[] = [
-  compileReadTool(modifierListStory),
-  compileLookupTool(modifierLookupStory),
-  {
-    name: "modifier_sample",
-    description:
-      "Return 1–5 randomly selected complete modifier family instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
-    params: {
-      count: {
-        type: "string",
-        description: "Number of samples (1–5, default 2)",
-        optional: true,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { count, condensed }) {
-      const n = Number(count ?? 2);
-      const result = await sampleModifiers(rt.store, n);
-      const nextSteps = [
-        `These are ${result.samples.length} of ${result.totalCount} total modifier families.`,
-        "Use modifier_lookup to inspect specific modifier families by name.",
-        "Use modifier_list to see all available modifier families.",
-      ];
-
-      if (condensed) {
-        return condense(modifierSampleFmt.llm({ ...result, nextSteps }));
-      }
-
-      return {
-        data: {
-          samples: result.samples,
-          totalCount: result.totalCount,
-          nextSteps,
-        },
-        meta: { count: result.samples.length },
-      };
-    },
-  },
-] as const;
-
-export default specs;

package/src/domains/modifier/modifierConfig.ts

@@ -1,36 +0,0 @@
-import type { EntityDisplayConfig } from "../shared/contracts.js";
-import { P } from "../shared/prefixes.js";
-import type {
-  FilterConfig,
-  ModifierDetailed,
-  ModifierDigest,
-  ModifierSummary,
-} from "../shared/types/index.js";
-
-/** Display-contract configuration for modifier-family entities. */
-export const modifierConfig: EntityDisplayConfig<
-  ModifierSummary,
-  ModifierDigest,
-  ModifierDetailed
-> = {
-  domain: "modifier",
-  entityName: "modifier",
-  rdfTypes: [`${P.ds}ModifierFamily`],
-  listColumns: [
-    { key: "uri", label: "IRI" },
-    { key: "name", label: "Name" },
-    { key: "values", label: "Values", showWhenEmpty: false },
-  ],
-  digestColumns: [],
-  lookupSections: [{ key: "values", heading: "Values", kind: "list" }],
-  emptyRecovery: (_filters: FilterConfig) => ({
-    message: "List available modifier families.",
-    cli: "pragma modifier list",
-    mcp: { tool: "modifier_list" },
-  }),
-  notFoundRecovery: (_query: string) => ({
-    message: "List available modifier families.",
-    cli: "pragma modifier list",
-    mcp: { tool: "modifier_list" },
-  }),
-};

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

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

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

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

@@ -1,41 +0,0 @@
-/**
- * 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/index.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

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

@@ -1,67 +0,0 @@
-/**
- * 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 {
-  detectCrossDomain,
-  listDomainNames,
-  suggestNames,
-} from "../../shared/suggestions/index.js";
-import type { ModifierFamily } from "../../shared/types/index.js";
-
-export default async function lookupModifier(
-  store: Store,
-  name: string,
-): Promise<ModifierFamily> {
-  const escaped = escapeSparqlValue(name.toLowerCase());
-
-  const result = await store.query(
-    buildQuery(`
-      SELECT ?family (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
-      WHERE {
-        ?family a ${P.ds}ModifierFamily ;
-                ${P.ds}name ?familyName .
-        FILTER(LCASE(STR(?familyName)) = ${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) {
-    const candidates = await listDomainNames(store, "modifier");
-    const crossDomain = await detectCrossDomain(name, "modifier", store);
-    throw PragmaError.notFound("modifier", name, {
-      suggestions: suggestNames(name, candidates),
-      recovery: {
-        message: "List available modifiers.",
-        cli: "pragma modifier list",
-        mcp: { tool: "modifier_list" },
-      },
-      crossDomain: crossDomain ?? undefined,
-    });
-  }
-
-  // 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) : [],
-  };
-}