@canonical/pragma-cli 0.18.0

package/src/domains/block/orchestration/resolveBlockList.ts

@@ -0,0 +1,39 @@
+import type { ListParams } from "../../shared/contracts.js";
+import type { PragmaRuntime } from "../../shared/runtime.js";
+import type { Disclosure } from "../../shared/types.js";
+import { listBlocks } from "../operations/index.js";
+import type { BlockListContract } from "../types.js";
+import blockEmptyError from "./blockEmptyError.js";
+import buildBlockFilters from "./buildBlockFilters.js";
+import enrichBlocks from "./enrichBlocks.js";
+
+export default async function resolveBlockList(
+  rt: Pick<PragmaRuntime, "store" | "config">,
+  params: ListParams,
+): Promise<BlockListContract> {
+  const filters = buildBlockFilters(rt, params.allTiers);
+  const disclosure: Disclosure = params.detailed
+    ? { level: "detailed" }
+    : params.digest
+      ? { level: "digest" }
+      : { level: "summary" };
+  const summaries = await listBlocks(rt.store, filters);
+
+  if (summaries.length === 0) {
+    throw blockEmptyError(filters, params.allTiers);
+  }
+
+  const items =
+    disclosure.level === "summary"
+      ? summaries
+      : await enrichBlocks(summaries, rt.store, filters, disclosure);
+
+  return {
+    params,
+    result: {
+      items,
+      filters,
+      disclosure,
+    },
+  };
+}

package/src/domains/block/orchestration/resolveBlockLookup.ts

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

package/src/domains/block/types.ts

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

@@ -0,0 +1,101 @@
+import { 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;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-cmd-channel-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { 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).toBe('Set channel to "prerelease".');
+    }
+  });
+
+  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).toBe("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

@@ -0,0 +1,80 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { readConfig, writeConfig } 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";
+
+/**
+ * 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
+ */
+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,
+      },
+    ],
+    meta: {
+      examples: [
+        "pragma config channel experimental",
+        "pragma config channel --reset",
+      ],
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const reset = params.reset === true;
+      const value = params.value as string | undefined;
+
+      if (reset) {
+        writeConfig(ctx.cwd, { channel: undefined });
+        const format = selectFormatter(ctx, channelFormatters.reset);
+        return createOutputResult("Reset channel to default.", {
+          plain: format,
+        });
+      }
+
+      if (!value) {
+        const config = readConfig(ctx.cwd);
+        const format = selectFormatter(ctx, channelFormatters.query);
+        return createOutputResult(config.channel, {
+          plain: format,
+        });
+      }
+
+      const channel = validateChannel(value);
+
+      writeConfig(ctx.cwd, { channel });
+      const format = selectFormatter(ctx, channelFormatters.set);
+      return createOutputResult(
+        { field: "channel", value: channel },
+        { plain: format },
+      );
+    },
+  };
+}

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

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

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

@@ -0,0 +1,61 @@
+import { 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 type { PragmaContext } from "../../shared/context.js";
+import buildShowCommand from "./show.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 show command", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-cmd-show-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("renders show output with defaults", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildShowCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      const text = result.render.plain(result.value);
+      expect(text).toContain("tier: (none — all tiers visible)");
+      expect(text).toContain("channel: normal (stable)");
+      expect(text).toContain("config file: (not found)");
+    }
+  });
+
+  it("renders show output with configured values", async () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      '{"tier":"apps/lxd","channel":"experimental"}',
+    );
+
+    const ctx = makeCtx(dir);
+    const cmd = buildShowCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      const text = result.render.plain(result.value);
+      expect(text).toContain("tier: apps/lxd (global → apps → apps/lxd)");
+      expect(text).toContain("channel: experimental (stable + experimental)");
+      expect(text).toContain("config file:");
+    }
+  });
+});

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

@@ -0,0 +1,51 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { configExists, readConfig, resolveConfigPath } from "#config";
+import { detectInstallSource } from "#package-manager";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { showFormatters } from "../formatters/index.js";
+import { resolveConfigShow } from "../operations/index.js";
+
+/**
+ * Build the `pragma config show` command definition.
+ *
+ * Displays the resolved configuration including tier, channel,
+ * package manager, and config file location.
+ *
+ * @param ctx - Pragma context providing cwd and formatter selection.
+ * @returns The command definition for `pragma config show`.
+ * @note Impure
+ */
+export default function buildShowCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["config", "show"],
+    description: "Display resolved configuration",
+    parameters: [],
+    meta: {
+      examples: ["pragma config show"],
+    },
+    execute: async (): Promise<CommandResult> => {
+      const config = readConfig(ctx.cwd);
+      const install = detectInstallSource();
+      const cfgPath = resolveConfigPath(ctx.cwd);
+      const cfgExists = configExists(ctx.cwd);
+
+      const data = resolveConfigShow(config, {
+        packageManager: install.packageManager,
+        installSource: install.label,
+        configFilePath: cfgPath,
+        configFileExists: cfgExists,
+      });
+
+      return createOutputResult(data, {
+        plain: selectFormatter(ctx, showFormatters),
+      });
+    },
+  };
+}

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

@@ -0,0 +1,84 @@
+import { 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 buildTierCommand from "./tier.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 tier command", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-cmd-tier-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("resets tier via --reset flag", async () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      '{"tier":"apps/lxd","channel":"normal"}',
+    );
+
+    const ctx = makeCtx(dir);
+    const cmd = buildTierCommand(ctx);
+    const result = await cmd.execute({ reset: true }, ctx);
+
+    expect(result.tag).toBe("output");
+    const config = readConfig(dir);
+    expect(config.tier).toBeUndefined();
+    expect(config.channel).toBe("normal");
+  });
+
+  it("renders reset output", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildTierCommand(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).toBe("Reset tier to default.");
+    }
+  });
+
+  it("shows current tier when no args", async () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"tier":"apps"}');
+
+    const ctx = makeCtx(dir);
+    const cmd = buildTierCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.value).toBe("apps");
+      const text = result.render.plain(result.value);
+      expect(text).toBe("Current tier: apps");
+    }
+  });
+
+  it("shows no tier message when none set", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildTierCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      const text = result.render.plain(result.value);
+      expect(text).toBe("No tier set (all tiers visible).");
+    }
+  });
+});

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

@@ -0,0 +1,78 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { readConfig, writeConfig } from "#config";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { tierFormatters } from "../formatters/index.js";
+import { validateTier } from "../operations/index.js";
+
+/**
+ * Build the `pragma config tier` command definition.
+ *
+ * Supports three modes: set a tier path (validated against the ontology),
+ * reset to default, or query the current tier.
+ *
+ * @param ctx - Pragma context providing cwd, store, and formatter selection.
+ * @returns The command definition for `pragma config tier`.
+ * @note Impure
+ */
+export default function buildTierCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["config", "tier"],
+    description: "Set or reset the active tier",
+    parameters: [
+      {
+        name: "path",
+        description: "Tier path (e.g., global, apps, apps/lxd)",
+        type: "string",
+        positional: true,
+      },
+      {
+        name: "reset",
+        description: "Reset tier to default (all tiers visible)",
+        type: "boolean",
+        default: false,
+      },
+    ],
+    meta: {
+      examples: ["pragma config tier apps/lxd", "pragma config tier --reset"],
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const reset = params.reset === true;
+      const tierPath = params.path as string | undefined;
+
+      if (reset) {
+        writeConfig(ctx.cwd, { tier: undefined });
+        const format = selectFormatter(ctx, tierFormatters.reset);
+        return createOutputResult("Reset tier to default.", {
+          plain: format,
+        });
+      }
+
+      if (!tierPath) {
+        const config = readConfig(ctx.cwd);
+        const format = selectFormatter(ctx, tierFormatters.query);
+        return createOutputResult(config.tier, {
+          plain: format,
+        });
+      }
+
+      // Validate tier against ontology
+      await validateTier(ctx.store, tierPath);
+
+      writeConfig(ctx.cwd, { tier: tierPath });
+      const format = selectFormatter(ctx, tierFormatters.set);
+      return createOutputResult(
+        { field: "tier", value: tierPath },
+        { plain: format },
+      );
+    },
+  };
+}

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import formatters from "./channel.js";
+
+describe("channelFormatters.set", () => {
+  const data = { field: "channel", value: "experimental" };
+
+  it("plain renders set message", () => {
+    expect(formatters.set.plain(data)).toBe('Set channel to "experimental".');
+  });
+
+  it("llm renders set message", () => {
+    expect(formatters.set.llm(data)).toBe('Set channel to "experimental".');
+  });
+
+  it("json returns valid JSON", () => {
+    const parsed = JSON.parse(formatters.set.json(data));
+    expect(parsed.field).toBe("channel");
+    expect(parsed.value).toBe("experimental");
+  });
+});
+
+describe("channelFormatters.reset", () => {
+  it("plain renders reset message", () => {
+    expect(formatters.reset.plain("")).toBe("Reset channel to default.");
+  });
+
+  it("llm renders reset message", () => {
+    expect(formatters.reset.llm("")).toBe("Reset channel to default.");
+  });
+
+  it("json returns valid JSON", () => {
+    const parsed = JSON.parse(formatters.reset.json(""));
+    expect(parsed.field).toBe("channel");
+    expect(parsed.reset).toBe(true);
+  });
+});
+
+describe("channelFormatters.query", () => {
+  it("plain shows current channel", () => {
+    expect(formatters.query.plain("prerelease")).toBe(
+      "Current channel: prerelease",
+    );
+  });
+
+  it("llm shows current channel", () => {
+    expect(formatters.query.llm("prerelease")).toBe(
+      "Current channel: prerelease",
+    );
+  });
+
+  it("json returns valid JSON", () => {
+    const parsed = JSON.parse(formatters.query.json("prerelease"));
+    expect(parsed.field).toBe("channel");
+    expect(parsed.value).toBe("prerelease");
+  });
+});

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

@@ -0,0 +1,34 @@
+import type { Formatters } from "../../shared/formatters.js";
+
+/**
+ * Formatter sets for `pragma config channel` output, grouped by branch:
+ *
+ * - **set** formats the confirmation after setting a channel (plain/llm/json).
+ * - **reset** formats the confirmation after resetting to default (plain/llm/json).
+ * - **query** formats the current channel value (plain/llm/json).
+ */
+const channelFormatters = {
+  set: {
+    plain: (d: { field: string; value: string }) =>
+      `Set ${d.field} to "${d.value}".`,
+    llm: (d: { field: string; value: string }) =>
+      `Set ${d.field} to "${d.value}".`,
+    json: (d: { field: string; value: string }) =>
+      JSON.stringify({ field: d.field, value: d.value }),
+  } satisfies Formatters<{ field: string; value: string }>,
+
+  reset: {
+    plain: () => "Reset channel to default.",
+    llm: () => "Reset channel to default.",
+    json: () => JSON.stringify({ field: "channel", reset: true }),
+  } satisfies Formatters<string>,
+
+  query: {
+    plain: (channel: string) => `Current channel: ${channel}`,
+    llm: (channel: string) => `Current channel: ${channel}`,
+    json: (channel: string) =>
+      JSON.stringify({ field: "channel", value: channel }),
+  } satisfies Formatters<string>,
+};
+
+export default channelFormatters;

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

@@ -0,0 +1,4 @@
+/** @module Formatter sets for config domain output. */
+export { default as channelFormatters } from "./channel.js";
+export { default as showFormatters } from "./show.js";
+export { default as tierFormatters } from "./tier.js";