@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import type { ConfigShowData } from "../operations/types.js";
+import formatters from "./show.js";
+
+const WITH_TIER: ConfigShowData = {
+  tier: "apps/lxd",
+  tierChain: ["global", "apps", "apps/lxd"],
+  channel: "experimental",
+  includedReleases: ["stable", "experimental"],
+  packageManager: "bun",
+  installSource: "bun (global)",
+  configFilePath: "/project/pragma.config.json",
+  configFileExists: true,
+};
+
+const WITHOUT_TIER: ConfigShowData = {
+  tier: undefined,
+  tierChain: [],
+  channel: "normal",
+  includedReleases: ["stable"],
+  packageManager: "npm",
+  installSource: "bun (local)",
+  configFilePath: "/project/pragma.config.json",
+  configFileExists: false,
+};
+
+const PRERELEASE: ConfigShowData = {
+  tier: "global",
+  tierChain: ["global"],
+  channel: "prerelease",
+  includedReleases: ["stable", "experimental", "alpha", "beta"],
+  packageManager: "pnpm",
+  installSource: "pnpm (global)",
+  configFilePath: "/project/pragma.config.json",
+  configFileExists: true,
+};
+
+describe("formatters.plain", () => {
+  it("renders full config with tier", () => {
+    const output = formatters.plain(WITH_TIER);
+    expect(output).toContain("tier: apps/lxd (global → apps → apps/lxd)");
+    expect(output).toContain("channel: experimental (stable + experimental)");
+    expect(output).toContain("installed via: bun (global)");
+    expect(output).toContain("config file: /project/pragma.config.json");
+  });
+
+  it("renders config without tier", () => {
+    const output = formatters.plain(WITHOUT_TIER);
+    expect(output).toContain("tier: (none — all tiers visible)");
+    expect(output).toContain("channel: normal (stable)");
+    expect(output).toContain("installed via: bun (local)");
+    expect(output).toContain("config file: (not found)");
+  });
+
+  it("renders prerelease channel with all release levels", () => {
+    const output = formatters.plain(PRERELEASE);
+    expect(output).toContain(
+      "channel: prerelease (stable + experimental + alpha + beta)",
+    );
+  });
+});
+
+describe("formatters.llm", () => {
+  it("renders markdown heading", () => {
+    const output = formatters.llm(WITH_TIER);
+    expect(output).toContain("## Configuration");
+  });
+
+  it("renders tier info as markdown", () => {
+    const output = formatters.llm(WITH_TIER);
+    expect(output).toContain("**Tier:** apps/lxd (global > apps > apps/lxd)");
+  });
+
+  it("renders channel info as markdown", () => {
+    const output = formatters.llm(WITH_TIER);
+    expect(output).toContain(
+      "**Channel:** experimental (stable, experimental)",
+    );
+  });
+
+  it("renders config file path in backticks", () => {
+    const output = formatters.llm(WITH_TIER);
+    expect(output).toContain("`/project/pragma.config.json`");
+  });
+
+  it("renders no tier message", () => {
+    const output = formatters.llm(WITHOUT_TIER);
+    expect(output).toContain("**Tier:** none (all tiers visible)");
+  });
+
+  it("renders missing config file", () => {
+    const output = formatters.llm(WITHOUT_TIER);
+    expect(output).toContain("**Config file:** not found");
+  });
+});
+
+describe("formatters.json", () => {
+  it("returns valid JSON", () => {
+    const text = formatters.json(WITH_TIER);
+    const parsed = JSON.parse(text);
+    expect(parsed.tier).toBe("apps/lxd");
+    expect(parsed.channel).toBe("experimental");
+    expect(parsed.tierChain).toEqual(["global", "apps", "apps/lxd"]);
+    expect(parsed.includedReleases).toEqual(["stable", "experimental"]);
+    expect(parsed.packageManager).toBe("bun");
+    expect(parsed.configFileExists).toBe(true);
+  });
+
+  it("returns JSON without tier when undefined", () => {
+    const text = formatters.json(WITHOUT_TIER);
+    const parsed = JSON.parse(text);
+    expect(parsed.tier).toBeUndefined();
+    expect(parsed.tierChain).toEqual([]);
+  });
+
+  it("preserves all fields", () => {
+    const text = formatters.json(PRERELEASE);
+    const parsed = JSON.parse(text);
+    expect(parsed.includedReleases).toEqual([
+      "stable",
+      "experimental",
+      "alpha",
+      "beta",
+    ]);
+  });
+});

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

@@ -0,0 +1,66 @@
+import type { Formatters } from "../../shared/formatters.js";
+import type { ConfigShowData } from "../operations/types.js";
+
+/**
+ * Formatters for `pragma config show` output.
+ *
+ * - **plain** renders tier chain, channel, package manager, and config path.
+ * - **llm** renders a markdown section with bullet points.
+ * - **json** serializes the raw ConfigShowData.
+ */
+const formatters: Formatters<ConfigShowData> = {
+  plain(data) {
+    const lines: string[] = [];
+
+    if (data.tier !== undefined) {
+      const chain = data.tierChain.join(" → ");
+      lines.push(`tier: ${data.tier} (${chain})`);
+    } else {
+      lines.push("tier: (none — all tiers visible)");
+    }
+
+    const releases = data.includedReleases.join(" + ");
+    lines.push(`channel: ${data.channel} (${releases})`);
+    lines.push(`installed via: ${data.installSource}`);
+
+    if (data.configFileExists) {
+      lines.push(`config file: ${data.configFilePath}`);
+    } else {
+      lines.push("config file: (not found)");
+    }
+
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const lines: string[] = [];
+
+    lines.push("## Configuration");
+    lines.push("");
+
+    if (data.tier !== undefined) {
+      const chain = data.tierChain.join(" > ");
+      lines.push(`- **Tier:** ${data.tier} (${chain})`);
+    } else {
+      lines.push("- **Tier:** none (all tiers visible)");
+    }
+
+    const releases = data.includedReleases.join(", ");
+    lines.push(`- **Channel:** ${data.channel} (${releases})`);
+    lines.push(`- **Installed via:** ${data.installSource}`);
+
+    if (data.configFileExists) {
+      lines.push(`- **Config file:** \`${data.configFilePath}\``);
+    } else {
+      lines.push("- **Config file:** not found");
+    }
+
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data, null, 2);
+  },
+};
+
+export default formatters;

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

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import formatters from "./tier.js";
+
+describe("tierFormatters.set", () => {
+  const data = { field: "tier", value: "apps/lxd" };
+
+  it("plain renders set message", () => {
+    expect(formatters.set.plain(data)).toBe('Set tier to "apps/lxd".');
+  });
+
+  it("llm renders set message", () => {
+    expect(formatters.set.llm(data)).toBe('Set tier to "apps/lxd".');
+  });
+
+  it("json returns valid JSON", () => {
+    const parsed = JSON.parse(formatters.set.json(data));
+    expect(parsed.field).toBe("tier");
+    expect(parsed.value).toBe("apps/lxd");
+  });
+});
+
+describe("tierFormatters.reset", () => {
+  it("plain renders reset message", () => {
+    expect(formatters.reset.plain("")).toBe("Reset tier to default.");
+  });
+
+  it("llm renders reset message", () => {
+    expect(formatters.reset.llm("")).toBe("Reset tier to default.");
+  });
+
+  it("json returns valid JSON", () => {
+    const parsed = JSON.parse(formatters.reset.json(""));
+    expect(parsed.field).toBe("tier");
+    expect(parsed.reset).toBe(true);
+  });
+});
+
+describe("tierFormatters.query", () => {
+  it("plain shows current tier when set", () => {
+    expect(formatters.query.plain("apps")).toBe("Current tier: apps");
+  });
+
+  it("plain shows no tier message when undefined", () => {
+    expect(formatters.query.plain(undefined)).toBe(
+      "No tier set (all tiers visible).",
+    );
+  });
+
+  it("llm shows current tier when set", () => {
+    expect(formatters.query.llm("apps")).toBe("Current tier: apps");
+  });
+
+  it("llm shows no tier message when undefined", () => {
+    expect(formatters.query.llm(undefined)).toBe(
+      "No tier set (all tiers visible).",
+    );
+  });
+
+  it("json returns value when set", () => {
+    const parsed = JSON.parse(formatters.query.json("apps"));
+    expect(parsed.field).toBe("tier");
+    expect(parsed.value).toBe("apps");
+  });
+
+  it("json returns null value when undefined", () => {
+    const parsed = JSON.parse(formatters.query.json(undefined));
+    expect(parsed.field).toBe("tier");
+    expect(parsed.value).toBeNull();
+  });
+});

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

@@ -0,0 +1,40 @@
+import type { Formatters } from "../../shared/formatters.js";
+
+/**
+ * Formatter sets for `pragma config tier` output, grouped by branch:
+ *
+ * - **set** formats the confirmation after setting a tier (plain/llm/json).
+ * - **reset** formats the confirmation after resetting to default (plain/llm/json).
+ * - **query** formats the current tier value (plain/llm/json).
+ */
+const tierFormatters = {
+  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 tier to default.",
+    llm: () => "Reset tier to default.",
+    json: () => JSON.stringify({ field: "tier", reset: true }),
+  } satisfies Formatters<string>,
+
+  query: {
+    plain: (tier: string | undefined) =>
+      tier !== undefined
+        ? `Current tier: ${tier}`
+        : "No tier set (all tiers visible).",
+    llm: (tier: string | undefined) =>
+      tier !== undefined
+        ? `Current tier: ${tier}`
+        : "No tier set (all tiers visible).",
+    json: (tier: string | undefined) =>
+      JSON.stringify({ field: "tier", value: tier ?? null }),
+  } satisfies Formatters<string | undefined>,
+};
+
+export default tierFormatters;

package/src/domains/config/index.ts

@@ -0,0 +1,23 @@
+/** @module Config domain -- tier, channel, and show commands for `pragma config`. */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import type { PragmaContext } from "../shared/context.js";
+import { channelCommand, showCommand, tierCommand } from "./commands/index.js";
+
+/**
+ * Return all config command definitions.
+ *
+ * @param ctx - Pragma context providing cwd, store, and formatter selection.
+ * @returns An array of CommandDefinitions for the config subcommands.
+ */
+export function commands(ctx: PragmaContext): CommandDefinition[] {
+  return [tierCommand(ctx), channelCommand(ctx), showCommand(ctx)];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";
+export type { ConfigShowData } from "./operations/index.js";
+export {
+  resolveConfigShow,
+  validateChannel,
+  validateTier,
+} from "./operations/index.js";

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

@@ -0,0 +1,2 @@
+/** @module Config domain MCP barrel — config_show, config_tier, config_channel. */
+export { default as specs } from "./specs.js";

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

@@ -0,0 +1,108 @@
+/**
+ * MCP tool specs for the config domain.
+ */
+
+import { readConfig, writeConfig } from "#config";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { validateChannel, validateTier } from "../operations/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "config_show",
+    description:
+      "Show current pragma configuration (tier and channel settings).",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, { condensed }) {
+      const data = {
+        tier: rt.config.tier ?? null,
+        channel: rt.config.channel,
+      };
+
+      if (condensed) {
+        const text = `Config: tier=${data.tier ?? "(none)"} channel=${data.channel}`;
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data };
+    },
+  },
+  {
+    name: "config_tier",
+    description:
+      "Set or reset the active tier. Pass a tier path to set, or reset=true to clear.",
+    params: {
+      path: {
+        type: "string",
+        description: "Tier path (e.g. 'global', 'apps/lxd')",
+        optional: true,
+      },
+      reset: {
+        type: "boolean",
+        description: "Reset tier to default",
+        optional: true,
+      },
+    },
+    readOnly: false,
+    async execute(rt, { path, reset }) {
+      if (reset) {
+        writeConfig(rt.cwd, { tier: undefined });
+        return { data: { tier: null, action: "reset" } };
+      }
+
+      if (path) {
+        await validateTier(rt.store, path as string);
+        writeConfig(rt.cwd, { tier: path as string });
+        return { data: { tier: path, action: "set" } };
+      }
+
+      const config = readConfig(rt.cwd);
+      return { data: { tier: config.tier ?? null, action: "query" } };
+    },
+  },
+  {
+    name: "config_channel",
+    description:
+      "Set or reset the release channel. Pass a value to set, or reset=true to clear.",
+    params: {
+      value: {
+        type: "string",
+        description: "Channel (normal, experimental, prerelease)",
+        optional: true,
+      },
+      reset: {
+        type: "boolean",
+        description: "Reset channel to normal",
+        optional: true,
+      },
+    },
+    readOnly: false,
+    async execute(rt, { value, reset }) {
+      if (reset) {
+        writeConfig(rt.cwd, { channel: undefined });
+        return { data: { channel: "normal", action: "reset" } };
+      }
+
+      if (value) {
+        const channel = validateChannel(value as string);
+        writeConfig(rt.cwd, { channel });
+        return { data: { channel, action: "set" } };
+      }
+
+      const config = readConfig(rt.cwd);
+      return { data: { channel: config.channel, action: "query" } };
+    },
+  },
+];
+
+export default specs;

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

@@ -0,0 +1,5 @@
+/** @module Config operations: show, validate tier, validate channel. */
+export { default as resolveConfigShow } from "./show.js";
+export type { ConfigShowData } from "./types.js";
+export { default as validateChannel } from "./validateChannel.js";
+export { default as validateTier } from "./validateTier.js";

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

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import resolveConfigShow from "./show.js";
+
+describe("resolveConfigShow", () => {
+  it("resolves tier chain and included releases", () => {
+    const data = resolveConfigShow(
+      { tier: "apps/lxd", channel: "experimental" },
+      {
+        packageManager: "bun",
+        installSource: "bun (global)",
+        configFilePath: "/tmp/pragma.config.json",
+        configFileExists: true,
+      },
+    );
+
+    expect(data.tier).toBe("apps/lxd");
+    expect(data.tierChain).toEqual(["global", "apps", "apps/lxd"]);
+    expect(data.channel).toBe("experimental");
+    expect(data.includedReleases).toEqual(["stable", "experimental"]);
+    expect(data.packageManager).toBe("bun");
+    expect(data.installSource).toBe("bun (global)");
+    expect(data.configFileExists).toBe(true);
+  });
+
+  it("returns empty tier chain when no tier is set", () => {
+    const data = resolveConfigShow(
+      { tier: undefined, channel: "normal" },
+      {
+        packageManager: "npm",
+        installSource: "bun (local)",
+        configFilePath: "/tmp/pragma.config.json",
+        configFileExists: false,
+      },
+    );
+
+    expect(data.tier).toBeUndefined();
+    expect(data.tierChain).toEqual([]);
+    expect(data.includedReleases).toEqual(["stable"]);
+    expect(data.configFileExists).toBe(false);
+  });
+
+  it("includes all release levels for prerelease channel", () => {
+    const data = resolveConfigShow(
+      { tier: undefined, channel: "prerelease" },
+      {
+        packageManager: "pnpm",
+        installSource: "pnpm (global)",
+        configFilePath: "/tmp/pragma.config.json",
+        configFileExists: true,
+      },
+    );
+
+    expect(data.includedReleases).toEqual([
+      "stable",
+      "experimental",
+      "alpha",
+      "beta",
+    ]);
+  });
+});

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

@@ -0,0 +1,42 @@
+import type { PragmaConfig } from "#config";
+import { CHANNEL_RELEASES } from "../../shared/filters/buildChannelFilter.js";
+import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
+import type { ConfigShowData } from "./types.js";
+
+/**
+ * Assemble the data needed for `pragma config show` output.
+ *
+ * Pure data assembly -- the tier chain is resolved from the path
+ * string, not from the ontology.
+ *
+ * @param config - The resolved pragma config.
+ * @param opts - Additional context: package manager, config file path, and existence flag.
+ * @returns The fully resolved ConfigShowData.
+ */
+export default function resolveConfigShow(
+  config: PragmaConfig,
+  opts: {
+    packageManager: string;
+    installSource: string;
+    configFilePath: string;
+    configFileExists: boolean;
+  },
+): ConfigShowData {
+  // Don't throw for stale config — show always displays what's configured.
+  // resolveTierChain is pure string manipulation, doesn't need ontology.
+  const tierChain =
+    config.tier !== undefined ? resolveTierChain(config.tier) : [];
+
+  const includedReleases = CHANNEL_RELEASES[config.channel];
+
+  return {
+    tier: config.tier,
+    tierChain,
+    channel: config.channel,
+    includedReleases,
+    packageManager: opts.packageManager,
+    installSource: opts.installSource,
+    configFilePath: opts.configFilePath,
+    configFileExists: opts.configFileExists,
+  };
+}

package/src/domains/config/operations/types.ts

@@ -0,0 +1,13 @@
+import type { Channel } from "#constants";
+
+/** Data returned by `pragma config show`, including resolved tier chain and channel releases. */
+export interface ConfigShowData {
+  readonly tier: string | undefined;
+  readonly tierChain: readonly string[];
+  readonly channel: Channel;
+  readonly includedReleases: readonly string[];
+  readonly packageManager: string;
+  readonly installSource: string;
+  readonly configFilePath: string;
+  readonly configFileExists: boolean;
+}

package/src/domains/config/operations/validateChannel.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import validateChannel from "./validateChannel.js";
+
+describe("validateChannel", () => {
+  it("returns the channel for valid values", () => {
+    expect(validateChannel("normal")).toBe("normal");
+    expect(validateChannel("experimental")).toBe("experimental");
+    expect(validateChannel("prerelease")).toBe("prerelease");
+  });
+
+  it("throws INVALID_INPUT for an invalid channel", () => {
+    expect(() => validateChannel("aggressive")).toThrow(
+      'Invalid channel "aggressive"',
+    );
+  });
+
+  it("includes valid channels in error validOptions", () => {
+    try {
+      validateChannel("nope");
+      expect.unreachable("should have thrown");
+    } catch (err: unknown) {
+      const pragmaErr = err as {
+        code: string;
+        validOptions: string[];
+        recovery?: { cli?: string };
+      };
+      expect(pragmaErr.code).toBe("INVALID_INPUT");
+      expect(pragmaErr.validOptions).toEqual([
+        "normal",
+        "experimental",
+        "prerelease",
+      ]);
+      expect(pragmaErr.recovery?.cli).toBe("pragma config channel --reset");
+    }
+  });
+});

package/src/domains/config/operations/validateChannel.ts

@@ -0,0 +1,24 @@
+import { type Channel, VALID_CHANNELS } from "#constants";
+import { PragmaError } from "#error";
+
+/**
+ * Validate that a string is one of the accepted channel values.
+ *
+ * @param value - The channel string to validate.
+ * @returns The validated Channel value.
+ * @throws PragmaError.invalidInput if the value is not a valid channel.
+ */
+export default function validateChannel(value: string): Channel {
+  if (VALID_CHANNELS.includes(value as Channel)) {
+    return value as Channel;
+  }
+
+  throw PragmaError.invalidInput("channel", value, {
+    validOptions: [...VALID_CHANNELS],
+    recovery: {
+      message: "Reset channel configuration.",
+      cli: "pragma config channel --reset",
+      mcp: { tool: "config_channel", params: { reset: true } },
+    },
+  });
+}

package/src/domains/config/operations/validateTier.test.ts

@@ -0,0 +1,56 @@
+import type { Store } from "@canonical/ke";
+import type { TestStoreResult } from "@canonical/ke/testing";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ONTOLOGY_TTL, DS_TIERS_TTL } from "#testing";
+import validateTier from "./validateTier.js";
+
+const TIERS_TTL = [DS_ONTOLOGY_TTL, DS_TIERS_TTL].join("\n");
+
+describe("validateTier", () => {
+  let store: Store;
+  let cleanup: TestStoreResult["cleanup"];
+
+  beforeAll(async () => {
+    const result = await createTestStore({ ttl: TIERS_TTL });
+    store = result.store;
+    cleanup = result.cleanup;
+  });
+
+  afterAll(async () => {
+    await cleanup();
+  });
+
+  it("returns the matching TierEntry for a valid tier", async () => {
+    const entry = await validateTier(store, "apps/lxd");
+    expect(entry.path).toBe("apps/lxd");
+  });
+
+  it("returns the global tier", async () => {
+    const entry = await validateTier(store, "global");
+    expect(entry.path).toBe("global");
+  });
+
+  it("throws INVALID_INPUT for a nonexistent tier", async () => {
+    await expect(validateTier(store, "apps/nonexistent")).rejects.toThrow(
+      'Invalid tier "apps/nonexistent"',
+    );
+  });
+
+  it("includes valid tier paths in error validOptions", async () => {
+    try {
+      await validateTier(store, "nope");
+      expect.unreachable("should have thrown");
+    } catch (err: unknown) {
+      const pragmaErr = err as {
+        code: string;
+        validOptions: string[];
+        recovery: { message: string; cli: string };
+      };
+      expect(pragmaErr.code).toBe("INVALID_INPUT");
+      expect(pragmaErr.validOptions).toContain("global");
+      expect(pragmaErr.validOptions).toContain("apps");
+      expect(pragmaErr.validOptions).toContain("apps/lxd");
+      expect(pragmaErr.recovery.cli).toBe("pragma config tier --reset");
+    }
+  });
+});