@canonical/pragma-cli 0.31.0 → 0.32.0

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

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

@@ -1,260 +0,0 @@
-/**
- * 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);
-    const lower = partial.toLowerCase();
-    // Block names recur across tiers/packages; dedupe so completion offers each
-    // name once.
-    const unique = new Set(
-      all
-        .map((block) => block.name)
-        .filter((name) => name.toLowerCase().startsWith(lower)),
-    );
-    return [...unique];
-  },
-  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/block/types.ts

@@ -1,30 +0,0 @@
-/**
- * Block domain types.
- *
- * Reused across block commands, formatters, and aspect resolution.
- */
-
-import type { ListContract } from "../shared/contracts.js";
-import type { BlockDetailed, BlockSummary } from "../shared/types/index.js";
-
-/** Flags controlling which detail aspects are included in block output. */
-export interface AspectFlags {
-  readonly anatomy: boolean;
-  readonly modifiers: boolean;
-  readonly tokens: boolean;
-  readonly implementations: boolean;
-}
-
-export interface BlockListDigest extends BlockSummary {
-  readonly summary: string | null;
-  readonly implementationPaths: readonly {
-    framework: string;
-    path: string;
-  }[];
-}
-
-export type BlockListContract = ListContract<
-  BlockSummary,
-  BlockListDigest,
-  BlockDetailed
->;

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

@@ -1,128 +0,0 @@
-import { mkdirSync, mkdtempSync, 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 buildChannelCommand from "./channel.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 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 () => {
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    const result = await cmd.execute({ value: "experimental" }, ctx);
-
-    expect(result.tag).toBe("output");
-    const config = readConfig(dir);
-    expect(config.channel).toBe("experimental");
-  });
-
-  it("renders set output", async () => {
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    const result = await cmd.execute({ value: "prerelease" }, ctx);
-
-    expect(result.tag).toBe("output");
-    if (result.tag === "output") {
-      const text = result.render.plain(result.value);
-      expect(text).toContain('Set channel to "prerelease".');
-    }
-  });
-
-  it("rejects a value combined with --reset", async () => {
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    await expect(
-      cmd.execute({ value: "experimental", reset: true }, ctx),
-    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
-  });
-
-  it("rejects an explicit empty-string value", async () => {
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    await expect(cmd.execute({ value: "" }, ctx)).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-    });
-  });
-
-  it("resets channel via --reset flag", async () => {
-    writeFileSync(
-      join(dir, "pragma.config.json"),
-      '{"channel":"experimental"}',
-    );
-
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    const result = await cmd.execute({ reset: true }, ctx);
-
-    expect(result.tag).toBe("output");
-    const config = readConfig(dir);
-    expect(config.channel).toBe("normal");
-  });
-
-  it("renders reset output", async () => {
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    const result = await cmd.execute({ reset: true }, ctx);
-
-    expect(result.tag).toBe("output");
-    if (result.tag === "output") {
-      const text = result.render.plain(result.value);
-      expect(text).toContain("Reset channel to default.");
-    }
-  });
-
-  it("shows current channel when no args", async () => {
-    writeFileSync(join(dir, "pragma.config.json"), '{"channel":"prerelease"}');
-
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    const result = await cmd.execute({}, ctx);
-
-    expect(result.tag).toBe("output");
-    if (result.tag === "output") {
-      expect(result.value).toBe("prerelease");
-      const text = result.render.plain(result.value);
-      expect(text).toBe("Current channel: prerelease");
-    }
-  });
-
-  it("throws INVALID_INPUT for invalid channel", async () => {
-    const ctx = makeCtx(dir);
-    const cmd = buildChannelCommand(ctx);
-    await expect(cmd.execute({ value: "aggressive" }, ctx)).rejects.toThrow(
-      'Invalid channel "aggressive"',
-    );
-  });
-});

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

@@ -1,99 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { runTask } from "@canonical/task/node";
-import { readConfig } from "#config";
-import { PragmaError } from "#error";
-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.
- *
- * Supports three modes: set a channel value, reset to default, or
- * query the current channel when no arguments are provided.
- *
- * @param ctx - Pragma context providing cwd and formatter selection.
- * @returns The command definition for `pragma config channel`.
- * @note - Impure — validates channel and writes config to disk.
- */
-export default function buildChannelCommand(
-  ctx: PragmaContext,
-): CommandDefinition {
-  return {
-    path: ["config", "channel"],
-    description: "Set or reset the release channel",
-    parameters: [
-      {
-        name: "value",
-        description: "Channel (normal, experimental, prerelease)",
-        type: "string",
-        positional: true,
-      },
-      {
-        name: "reset",
-        description: "Reset channel to normal",
-        type: "boolean",
-        default: false,
-      },
-      ...SCOPE_PARAMETERS,
-    ],
-    meta: {
-      examples: [
-        "pragma config channel experimental",
-        "pragma config channel --reset",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const scope = resolveConfigScope(params);
-      const reset = params.reset === true;
-      const value = params.value as string | undefined;
-
-      // Contradictory input: a value AND --reset. Reject rather than silently
-      // letting one win.
-      if (reset && value !== undefined) {
-        throw PragmaError.invalidInput("channel", value, {
-          recovery: {
-            message: "Pass either a channel value or --reset, not both.",
-          },
-        });
-      }
-
-      if (reset) {
-        const result = await runTask(setChannelTask(ctx.cwd, undefined, scope));
-        const format = selectFormatter(ctx, channelFormatters.reset);
-        return createOutputResult(
-          { field: "channel", path: result.path },
-          { plain: format },
-        );
-      }
-
-      // No value at all → query the current channel. An explicit empty string
-      // is invalid input, not a query.
-      if (value === undefined) {
-        const config = readConfig(ctx.cwd);
-        const format = selectFormatter(ctx, channelFormatters.query);
-        return createOutputResult(config.channel, {
-          plain: format,
-        });
-      }
-
-      const channel = validateChannel(value);
-
-      const result = await runTask(setChannelTask(ctx.cwd, channel, scope));
-      const format = selectFormatter(ctx, channelFormatters.set);
-      return createOutputResult(
-        { field: "channel", value: channel, path: result.path },
-        { plain: format },
-      );
-    },
-  };
-}

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

@@ -1,46 +0,0 @@
-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;
-}