@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/block/stories.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { blockListStory, blockLookupStory } from "./stories.js";
+
+describe("blockListStory", () => {
+  it("renders the ink list view", () => {
+    const view = blockListStory.renderInk?.([]);
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Blocks");
+  });
+});
+
+describe("blockLookupStory", () => {
+  it("renders the ink lookup view", () => {
+    const view = blockLookupStory.renderInk?.(
+      { results: [], errors: [] },
+      { surface: "cli", detailed: false, params: {} },
+    );
+    expect(typeof view).toBe("string");
+  });
+
+  it("implies detail from aspect flags on the CLI only", () => {
+    const resolveDetailed = blockLookupStory.resolveDetailed;
+    expect(resolveDetailed?.("cli", { anatomy: true })).toBe(true);
+    expect(resolveDetailed?.("cli", {})).toBe(false);
+    expect(resolveDetailed?.("mcp", {})).toBe(true);
+    expect(resolveDetailed?.("mcp", { detailed: false })).toBe(false);
+  });
+});

package/src/domains/block/stories.ts

@@ -0,0 +1,254 @@
+/**
+ * Block read stories — the single declaration of `block list` and
+ * `block lookup` for both surfaces.
+ *
+ * The story kernel compiles these into the CLI commands and MCP tools,
+ * so descriptions, parameters, resolution, and rendering live here once.
+ */
+
+import { PragmaError } from "#error";
+import { createListView, createLookupView } from "#tui";
+import type { ColumnDef } from "../shared/contracts.js";
+import {
+  type LookupStory,
+  type LookupStoryView,
+  type ReadStory,
+  requirePragmaContext,
+} from "../shared/stories/index.js";
+import type { BlockDetailed } from "../shared/types/index.js";
+import { blockConfig } from "./blockConfig.js";
+import {
+  createLookupOptions,
+  listFormatters,
+  lookupFormatters,
+} from "./formatters/index.js";
+import type { BlockLookupInput } from "./formatters/types.js";
+import { resolveAspects } from "./helpers/index.js";
+import { listBlocks } from "./operations/index.js";
+import {
+  buildBlockFilters,
+  resolveBlockList,
+  resolveBlockLookup,
+} from "./orchestration/index.js";
+import type { AspectFlags, BlockListContract } from "./types.js";
+
+type BlockListItems = BlockListContract["result"]["items"];
+
+const LIST_COLUMN_ORDER = ["name", "type", "tier", "modifiers", "uri"] as const;
+
+/** The `block list` / `block_list` read story. */
+export const blockListStory: ReadStory<BlockListContract, BlockListItems> = {
+  noun: "block",
+  verb: "list",
+  description: "List blocks in the design system",
+  toolDescription:
+    "List design system blocks visible under current tier and channel configuration.",
+  params: [
+    {
+      name: "allTiers",
+      type: "boolean",
+      description: "Show blocks from all tiers",
+      toolDescription: "Show blocks from all tiers, ignoring tier filter",
+      default: false,
+    },
+    {
+      name: "digest",
+      type: "boolean",
+      description: "Show enriched summary with implementations",
+      toolDescription: "Include implementations per block",
+      default: false,
+    },
+    {
+      name: "detailed",
+      type: "boolean",
+      description: "Show full details for each block",
+      toolDescription: "Include full details per block",
+      default: false,
+    },
+  ],
+  examples: [
+    "pragma block list",
+    "pragma block list --all-tiers",
+    "pragma block list --digest",
+    "pragma block list --detailed",
+    "pragma block list --llm",
+    "pragma block list --format json",
+  ],
+  resolve: (rt, params) =>
+    resolveBlockList(rt, {
+      allTiers: params.allTiers === true,
+      digest: params.digest === true,
+      detailed: params.detailed === true,
+    }),
+  toOutput: (contract) => contract.result.items,
+  formatters: listFormatters,
+  toEnvelope: (contract) => {
+    const { items, disclosure, filters } = contract.result;
+    if (disclosure.level === "summary") {
+      return { data: items, meta: { count: items.length, filters } };
+    }
+    return {
+      data: items,
+      meta: { count: items.length, disclosure: disclosure.level, filters },
+    };
+  },
+  renderInk: (items) =>
+    createListView({
+      heading: "Blocks",
+      domain: "block",
+      items,
+      columns: reorderColumns(blockConfig.listColumns, LIST_COLUMN_ORDER),
+    }),
+};
+
+/** The `block lookup` / `block_lookup` read story. */
+export const blockLookupStory: LookupStory<BlockDetailed, BlockLookupInput> = {
+  noun: "block",
+  description: "Look up block details",
+  toolDescription:
+    "Get detailed information about one or more design system blocks including anatomy, modifiers, tokens, and applicable standards.",
+  namesDescription: "Block names or IRIs",
+  namesToolDescription:
+    "Block names or IRIs to look up (e.g. ['Button', 'ds:global.component.card'])",
+  complete: async (partial, cmdCtx) => {
+    const ctx = requirePragmaContext(cmdCtx);
+    const all = await listBlocks(ctx.store, ctx.config);
+    return all
+      .map((block) => block.name)
+      .filter((name) => name.toLowerCase().startsWith(partial.toLowerCase()));
+  },
+  detailedParam: {
+    description:
+      "Show full details including anatomy, modifiers, tokens, and implementations",
+    toolDescription: "Return full details (default: true for MCP)",
+  },
+  params: [
+    {
+      name: "anatomy",
+      type: "boolean",
+      description: "Show anatomy tree",
+      default: false,
+      surfaces: "cli",
+    },
+    {
+      name: "modifiers",
+      type: "boolean",
+      description: "Show modifier values",
+      default: false,
+      surfaces: "cli",
+    },
+    {
+      name: "tokens",
+      type: "boolean",
+      description: "Show token references",
+      default: false,
+      surfaces: "cli",
+    },
+    {
+      name: "implementations",
+      type: "boolean",
+      description: "Show implementation paths",
+      default: false,
+      surfaces: "cli",
+    },
+  ],
+  parameterGroups: {
+    "Aspect filters": ["anatomy", "modifiers", "tokens", "implementations"],
+  },
+  examples: [
+    "pragma block lookup Button",
+    "pragma block lookup Button Card",
+    "pragma block lookup Button --detailed",
+    "pragma block lookup Button --anatomy --modifiers",
+    "pragma block lookup Button --detailed --llm",
+    "pragma block lookup ds:global.component.button",
+  ],
+  resolve: async (rt, names) => {
+    const contract = await resolveBlockLookup(
+      rt.store,
+      names,
+      buildBlockFilters(rt),
+    );
+    return contract.result;
+  },
+  resolveDetailed: (surface, params) => {
+    if (surface === "mcp") {
+      return ((params.detailed as boolean | undefined) ?? true) === true;
+    }
+    return params.detailed === true || isAspectSelected(params);
+  },
+  toFmtInput: (block, view) => ({
+    block,
+    detailed: view.detailed,
+    aspects: resolveViewAspects(view),
+  }),
+  formatters: lookupFormatters,
+  project: (block) => {
+    const {
+      uri,
+      name,
+      type,
+      tier,
+      modifiers,
+      implementations,
+      nodeCount,
+      tokenCount,
+      summary,
+    } = block;
+    return {
+      uri,
+      name,
+      type,
+      tier,
+      modifiers,
+      implementations,
+      nodeCount,
+      tokenCount,
+      summary,
+    };
+  },
+  emptyNamesError: () =>
+    PragmaError.invalidInput("names", "(empty)", {
+      recovery: {
+        message: "List available blocks.",
+        cli: "pragma block list",
+        mcp: { tool: "block_list" },
+      },
+    }),
+  renderInk: (result, view) =>
+    createLookupView({
+      results: result.results,
+      errors: result.errors,
+      domain: "block",
+      options: createLookupOptions(view.detailed, resolveViewAspects(view)),
+    }),
+};
+
+function isAspectSelected(params: Record<string, unknown>): boolean {
+  return (
+    params.anatomy === true ||
+    params.modifiers === true ||
+    params.tokens === true ||
+    params.implementations === true
+  );
+}
+
+function resolveViewAspects(view: LookupStoryView): AspectFlags {
+  return resolveAspects({
+    anatomy: view.params.anatomy === true,
+    modifiers: view.params.modifiers === true,
+    tokens: view.params.tokens === true,
+    implementations: view.params.implementations === true,
+  });
+}
+
+function reorderColumns<T>(
+  columns: readonly ColumnDef<T>[],
+  order: readonly string[],
+): readonly ColumnDef<T>[] {
+  const byKey = new Map(columns.map((col) => [col.key, col]));
+  return order.flatMap((key) => {
+    const col = byKey.get(key as keyof T & string);
+    return col ? [col] : [];
+  });
+}

package/src/domains/config/commands/channel.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Store } from "@canonical/ke";
@@ -18,13 +18,24 @@ function makeCtx(cwd: string): PragmaContext {
 
 describe("config channel command", () => {
   let dir: string;
+  let xdgDir: string;
+  let originalXdg: string | undefined;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), "pragma-cmd-channel-"));
+    // Bound the config walk at the fixture root, seed an empty project
+    // file so writes stay local, and isolate the global XDG layer.
+    mkdirSync(join(dir, ".git"));
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-cmd-channel-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
   });
 
   afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
     rmSync(dir, { recursive: true, force: true });
+    rmSync(xdgDir, { recursive: true, force: true });
   });
 
   it("sets channel to experimental", async () => {
@@ -45,7 +56,7 @@ describe("config channel command", () => {
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
       const text = result.render.plain(result.value);
-      expect(text).toBe('Set channel to "prerelease".');
+      expect(text).toContain('Set channel to "prerelease".');
     }
   });
 
@@ -72,7 +83,7 @@ describe("config channel command", () => {
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
       const text = result.render.plain(result.value);
-      expect(text).toBe("Reset channel to default.");
+      expect(text).toContain("Reset channel to default.");
     }
   });
 

package/src/domains/config/commands/channel.ts

@@ -3,13 +3,14 @@ import {
   type CommandResult,
   createOutputResult,
 } from "@canonical/cli-core";
-import { runTask } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import { readConfig } from "#config";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
 import { channelFormatters } from "../formatters/index.js";
 import { validateChannel } from "../operations/index.js";
 import { setChannelTask } from "../tasks/index.js";
+import { resolveConfigScope, SCOPE_PARAMETERS } from "./configScope.js";
 
 /**
  * Build the `pragma config channel` command definition.
@@ -40,6 +41,7 @@ export default function buildChannelCommand(
         type: "boolean",
         default: false,
       },
+      ...SCOPE_PARAMETERS,
     ],
     meta: {
       examples: [
@@ -50,15 +52,17 @@ export default function buildChannelCommand(
     execute: async (
       params: Record<string, unknown>,
     ): Promise<CommandResult> => {
+      const scope = resolveConfigScope(params);
       const reset = params.reset === true;
       const value = params.value as string | undefined;
 
       if (reset) {
-        await runTask(setChannelTask(ctx.cwd, undefined));
+        const result = await runTask(setChannelTask(ctx.cwd, undefined, scope));
         const format = selectFormatter(ctx, channelFormatters.reset);
-        return createOutputResult("Reset channel to default.", {
-          plain: format,
-        });
+        return createOutputResult(
+          { field: "channel", path: result.path },
+          { plain: format },
+        );
       }
 
       if (!value) {
@@ -71,10 +75,10 @@ export default function buildChannelCommand(
 
       const channel = validateChannel(value);
 
-      await runTask(setChannelTask(ctx.cwd, channel));
+      const result = await runTask(setChannelTask(ctx.cwd, channel, scope));
       const format = selectFormatter(ctx, channelFormatters.set);
       return createOutputResult(
-        { field: "channel", value: channel },
+        { field: "channel", value: channel, path: result.path },
         { plain: format },
       );
     },

package/src/domains/config/commands/configScope.ts

@@ -0,0 +1,46 @@
+import type { ParameterDefinition } from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import type { ConfigScope } from "../../../config/index.js";
+
+/**
+ * The `--global` / `--local` target-layer flags shared by every config
+ * write command. Without either flag the write follows the global-first
+ * rule: nearest existing project file, else the global XDG file.
+ */
+export const SCOPE_PARAMETERS: readonly ParameterDefinition[] = [
+  {
+    name: "global",
+    description:
+      "Write to the global config ($XDG_CONFIG_HOME/pragma/config.json, default ~/.config/pragma/config.json)",
+    type: "boolean",
+    default: false,
+  },
+  {
+    name: "local",
+    description: "Write to ./pragma.config.json in the current directory",
+    type: "boolean",
+    default: false,
+  },
+];
+
+/**
+ * Resolve the explicit write scope from parsed command parameters.
+ *
+ * @param params - Parsed command parameters.
+ * @returns The explicit scope, or `undefined` for the default rule.
+ * @throws PragmaError with code `INVALID_INPUT` when both flags are set.
+ */
+export function resolveConfigScope(
+  params: Record<string, unknown>,
+): ConfigScope | undefined {
+  const global = params.global === true;
+  const local = params.local === true;
+  if (global && local) {
+    throw PragmaError.invalidInput("scope", "--global --local", {
+      recovery: { message: "Pass at most one of --global or --local." },
+    });
+  }
+  if (global) return "global";
+  if (local) return "local";
+  return undefined;
+}

package/src/domains/config/commands/framework.test.ts

@@ -0,0 +1,105 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Store } from "@canonical/ke";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readConfig } from "#config";
+import type { PragmaContext } from "../../shared/context.js";
+import buildFrameworkCommand from "./framework.js";
+
+function makeCtx(cwd: string): PragmaContext {
+  return {
+    cwd,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store: {} as Store,
+    config: { tier: undefined, channel: "normal" },
+  };
+}
+
+describe("config framework command", () => {
+  let dir: string;
+  let xdgDir: string;
+  let originalXdg: string | undefined;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-cmd-framework-"));
+    // Bound the config walk at the fixture root, seed an empty project
+    // file so writes stay local, and isolate the global XDG layer.
+    mkdirSync(join(dir, ".git"));
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-cmd-framework-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
+  });
+
+  afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
+    rmSync(dir, { recursive: true, force: true });
+    rmSync(xdgDir, { recursive: true, force: true });
+  });
+
+  it("sets framework to react", async () => {
+    const ctx = makeCtx(dir);
+    const result = await buildFrameworkCommand(ctx).execute(
+      { value: "react" },
+      ctx,
+    );
+    expect(result.tag).toBe("output");
+    expect(readConfig(dir).framework).toBe("react");
+  });
+
+  it("accepts svelte and lit", async () => {
+    const ctx = makeCtx(dir);
+    await buildFrameworkCommand(ctx).execute({ value: "svelte" }, ctx);
+    expect(readConfig(dir).framework).toBe("svelte");
+    await buildFrameworkCommand(ctx).execute({ value: "lit" }, ctx);
+    expect(readConfig(dir).framework).toBe("lit");
+  });
+
+  it("rejects an invalid framework", async () => {
+    const ctx = makeCtx(dir);
+    await expect(
+      buildFrameworkCommand(ctx).execute({ value: "angular" }, ctx),
+    ).rejects.toThrow(/framework/i);
+  });
+
+  it("reports 'none' when unset", async () => {
+    const ctx = makeCtx(dir);
+    const result = await buildFrameworkCommand(ctx).execute({}, ctx);
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.value).toBe("none");
+    }
+  });
+
+  it("resets framework via --reset (removes the field)", async () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"framework":"react"}');
+    const ctx = makeCtx(dir);
+    await buildFrameworkCommand(ctx).execute({ reset: true }, ctx);
+    expect(readConfig(dir).framework).toBeUndefined();
+    // The field is removed, not left as a stale value.
+    const raw = JSON.parse(
+      readFileSync(join(dir, "pragma.config.json"), "utf-8"),
+    ) as Record<string, unknown>;
+    expect(raw).not.toHaveProperty("framework");
+  });
+
+  it("preserves other config fields when setting framework", async () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      JSON.stringify({ tier: "Apps/WPE", trace: true }),
+    );
+    const ctx = makeCtx(dir);
+    await buildFrameworkCommand(ctx).execute({ value: "lit" }, ctx);
+    const config = readConfig(dir);
+    expect(config.framework).toBe("lit");
+    expect(config.tier).toBe("Apps/WPE");
+    expect(config.trace).toBe(true);
+  });
+});

package/src/domains/config/commands/framework.ts

@@ -0,0 +1,91 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { runTask } from "@canonical/task/node";
+import { readConfig } from "#config";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { frameworkFormatters } from "../formatters/index.js";
+import { validateFramework } from "../operations/index.js";
+import { setFrameworkTask } from "../tasks/index.js";
+import { resolveConfigScope, SCOPE_PARAMETERS } from "./configScope.js";
+
+/**
+ * Build the `pragma config framework` command definition.
+ *
+ * Sets the preferred UI framework (`react` | `svelte` | `lit`). The value is
+ * currently advisory only — no behaviour reads it yet; it is persisted for
+ * future framework-defaulting. Supports set, reset, and query (no argument).
+ *
+ * @param ctx - Pragma context providing cwd and formatter selection.
+ * @returns The command definition for `pragma config framework`.
+ * @note - Impure — validates framework and writes config to disk.
+ */
+export default function buildFrameworkCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["config", "framework"],
+    description: "Set or reset the preferred UI framework (advisory)",
+    parameters: [
+      {
+        name: "value",
+        description: "Framework (react, svelte, lit)",
+        type: "string",
+        positional: true,
+      },
+      {
+        name: "reset",
+        description: "Reset framework to default (none)",
+        type: "boolean",
+        default: false,
+      },
+      ...SCOPE_PARAMETERS,
+    ],
+    meta: {
+      examples: [
+        "pragma config framework react",
+        "pragma config framework --reset",
+      ],
+      extendedHelp:
+        "Advisory only for now: the value is persisted but no command reads it yet. Reserved for future framework defaulting.",
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const scope = resolveConfigScope(params);
+      const reset = params.reset === true;
+      const value = params.value as string | undefined;
+
+      if (reset) {
+        const result = await runTask(
+          setFrameworkTask(ctx.cwd, undefined, scope),
+        );
+        const format = selectFormatter(ctx, frameworkFormatters.reset);
+        return createOutputResult(
+          { field: "framework", path: result.path },
+          { plain: format },
+        );
+      }
+
+      if (!value) {
+        const config = readConfig(ctx.cwd);
+        const format = selectFormatter(ctx, frameworkFormatters.query);
+        return createOutputResult(config.framework ?? "none", {
+          plain: format,
+        });
+      }
+
+      const framework = validateFramework(value);
+
+      const result = await runTask(setFrameworkTask(ctx.cwd, framework, scope));
+      const format = selectFormatter(ctx, frameworkFormatters.set);
+      return createOutputResult(
+        { field: "framework", value: framework, path: result.path },
+        { plain: format },
+      );
+    },
+  };
+}

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

@@ -1,4 +1,6 @@
 /** @module Config command definitions for `pragma config`. */
 export { default as channelCommand } from "./channel.js";
+export { default as frameworkCommand } from "./framework.js";
 export { default as showCommand } from "./show.js";
 export { default as tierCommand } from "./tier.js";
+export { default as traceCommand } from "./trace.js";