@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,100 +0,0 @@
-/**
- * MCP tool specs for the config domain — config_show, config_tier,
- * config_channel.
- *
- * config_show is compiled from the config read story in `../stories.ts`
- * so both surfaces share resolution and formatters; the mutating tier and
- * channel tools are spec'd by hand.
- */
-
-import { readConfig, writeConfig } from "#config";
-import { compileReadTool } from "../../shared/stories/index.js";
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { validateChannel, validateTier } from "../operations/index.js";
-import { configShowStory } from "../stories.js";
-
-const specs: readonly ToolSpec[] = [
-  compileReadTool(configShowStory),
-  {
-    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,
-      },
-      global: {
-        type: "boolean",
-        description: "Write to the global config instead of the project file",
-        optional: true,
-      },
-    },
-    readOnly: false,
-    async execute(rt, { path, reset, global: globalScope }) {
-      const scope = globalScope === true ? "global" : undefined;
-
-      if (reset) {
-        const written = writeConfig(rt.cwd, { tier: undefined }, scope);
-        return { data: { tier: null, action: "reset", path: written } };
-      }
-
-      if (path) {
-        await validateTier(rt.store, path as string);
-        const written = writeConfig(rt.cwd, { tier: path as string }, scope);
-        return { data: { tier: path, action: "set", path: written } };
-      }
-
-      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,
-      },
-      global: {
-        type: "boolean",
-        description: "Write to the global config instead of the project file",
-        optional: true,
-      },
-    },
-    readOnly: false,
-    async execute(rt, { value, reset, global: globalScope }) {
-      const scope = globalScope === true ? "global" : undefined;
-
-      if (reset) {
-        const written = writeConfig(rt.cwd, { channel: undefined }, scope);
-        return { data: { channel: "normal", action: "reset", path: written } };
-      }
-
-      if (value) {
-        const channel = validateChannel(value as string);
-        const written = writeConfig(rt.cwd, { channel }, scope);
-        return { data: { channel, action: "set", path: written } };
-      }
-
-      const config = readConfig(rt.cwd);
-      return { data: { channel: config.channel, action: "query" } };
-    },
-  },
-];
-
-export default specs;

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

@@ -1,6 +0,0 @@
-/** @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 validateFramework } from "./validateFramework.js";
-export { default as validateTier } from "./validateTier.js";

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

@@ -1,78 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { ConfigOrigins } from "#config";
-import resolveConfigShow from "./show.js";
-
-const PROJECT_ORIGINS: ConfigOrigins = {
-  tier: "project",
-  channel: "project",
-  packages: "default",
-  trace: "default",
-  framework: "default",
-};
-
-const PROVENANCE = {
-  globalConfigPath: "/home/u/.config/pragma/config.json",
-  globalConfigExists: false,
-  origins: PROJECT_ORIGINS,
-};
-
-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,
-        ...PROVENANCE,
-      },
-    );
-
-    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,
-        ...PROVENANCE,
-      },
-    );
-
-    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,
-        ...PROVENANCE,
-      },
-    );
-
-    expect(data.includedReleases).toEqual([
-      "stable",
-      "experimental",
-      "alpha",
-      "beta",
-    ]);
-  });
-});

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

@@ -1,48 +0,0 @@
-import type { ConfigOrigins, 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;
-    globalConfigPath: string;
-    globalConfigExists: boolean;
-    origins: ConfigOrigins;
-  },
-): 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,
-    globalConfigPath: opts.globalConfigPath,
-    globalConfigExists: opts.globalConfigExists,
-    origins: opts.origins,
-  };
-}

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

@@ -1,20 +0,0 @@
-import type { ConfigOrigins } from "#config";
-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;
-  /** Nearest project config file (or the would-be path at cwd). */
-  readonly configFilePath: string;
-  readonly configFileExists: boolean;
-  /** The global XDG config file. */
-  readonly globalConfigPath: string;
-  readonly globalConfigExists: boolean;
-  /** Which layer supplied each effective field. */
-  readonly origins: ConfigOrigins;
-}

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

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

@@ -1,24 +0,0 @@
-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/validateFramework.ts

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

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

@@ -1,65 +0,0 @@
-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("matches case- and whitespace-insensitively", async () => {
-    // The documented lowercase slash-path must match regardless of the label's
-    // casing in the ontology (e.g. real graph uses `Apps/LXD`).
-    const upper = await validateTier(store, "APPS/LXD");
-    expect(upper.path).toBe("apps/lxd");
-    const padded = await validateTier(store, "  Apps/Lxd  ");
-    expect(padded.path).toBe("apps/lxd");
-  });
-
-  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");
-    }
-  });
-});

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

@@ -1,43 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { PragmaError } from "#error";
-import { listTiers } from "../../shared/listTiers.js";
-import type { TierEntry } from "../../shared/types/index.js";
-
-/** Normalise a tier path for comparison: trim and lowercase. */
-function normalizeTierPath(path: string): string {
-  return path.trim().toLowerCase();
-}
-
-/**
- * Validate a tier path against the ke store ontology.
- *
- * @param store - The booted ke store.
- * @param tierPath - The tier path string to validate.
- * @returns The matching TierEntry.
- * @throws PragmaError.invalidInput if the tier path does not exist in the ontology.
- * @note Queries ke store
- */
-export default async function validateTier(
-  store: Store,
-  tierPath: string,
-): Promise<TierEntry> {
-  const tiers = await listTiers(store);
-  // Compare case/format-insensitively so the documented lowercase slash-path
-  // (`apps/lxd`) matches the ontology's title-case label (`Apps/LXD`).
-  const target = normalizeTierPath(tierPath);
-  const match = tiers.find((t) => normalizeTierPath(t.path) === target);
-
-  if (!match) {
-    const validPaths = tiers.map((t) => t.path);
-    throw PragmaError.invalidInput("tier", tierPath, {
-      validOptions: validPaths,
-      recovery: {
-        message: "Reset tier configuration.",
-        cli: "pragma config tier --reset",
-        mcp: { tool: "config_tier", params: { reset: true } },
-      },
-    });
-  }
-
-  return match;
-}

package/src/domains/config/stories.ts

@@ -1,42 +0,0 @@
-/**
- * Config read story — the single declaration of `config show` for both
- * surfaces.
- *
- * Both surfaces resolve from the filesystem, so the MCP tool now reports
- * the real config path and existence (it previously hardcoded
- * `pragma.config.json` / `true` regardless of the working directory).
- */
-
-import { readConfigLayers } from "#config";
-import { detectInstallSource } from "#package-manager";
-import type { ReadStory } from "../shared/stories/index.js";
-import { showFormatters } from "./formatters/index.js";
-import { resolveConfigShow } from "./operations/index.js";
-import type { ConfigShowData } from "./operations/types.js";
-
-/** The `config show` / `config_show` read story. */
-export const configShowStory: ReadStory<ConfigShowData, ConfigShowData> = {
-  noun: "config",
-  verb: "show",
-  description: "Display resolved configuration",
-  toolDescription:
-    "Show current pragma configuration (tier and channel settings).",
-  params: [],
-  examples: ["pragma config show"],
-  resolve: async (rt) => {
-    const layers = readConfigLayers(rt.cwd);
-    const install = detectInstallSource();
-    return resolveConfigShow(layers.config, {
-      packageManager: install.packageManager,
-      installSource: install.label,
-      configFilePath: layers.project.path,
-      configFileExists: layers.project.exists,
-      globalConfigPath: layers.global.path,
-      globalConfigExists: layers.global.exists,
-      origins: layers.origins,
-    });
-  },
-  toOutput: (data) => data,
-  formatters: showFormatters,
-  toEnvelope: (data) => ({ data }),
-};

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

@@ -1,6 +0,0 @@
-/** @module Config write tasks. */
-export { default as setChannelTask } from "./setChannel.js";
-export { default as setFrameworkTask } from "./setFramework.js";
-export { default as setTierTask } from "./setTier.js";
-export { default as setTraceTask } from "./setTrace.js";
-export { default as writeConfigFieldTask } from "./writeConfigField.js";

package/src/domains/config/tasks/setChannel.ts

@@ -1,21 +0,0 @@
-import type { Task } from "@canonical/task";
-import type { ConfigScope } from "../../../config/index.js";
-import type { Channel } from "../../../constants.js";
-import writeConfigField from "./writeConfigField.js";
-
-/**
- * Build a config-write task for setting or resetting the release channel.
- *
- * @param cwd - Working directory the target config layer is resolved from.
- * @param channel - Channel to persist, or `undefined` to reset.
- * @param scope - Optional explicit target layer (`"global"` | `"local"`).
- * @returns Task yielding the persisted field/value payload and target path.
- * @note - Impure — reads and writes the target config file.
- */
-export default function setChannel(
-  cwd: string,
-  channel: Channel | undefined,
-  scope?: ConfigScope,
-): Task<{ field: "channel"; value: Channel | undefined; path: string }> {
-  return writeConfigField(cwd, "channel", channel, scope);
-}

package/src/domains/config/tasks/setFramework.ts

@@ -1,21 +0,0 @@
-import type { Task } from "@canonical/task";
-import type { ConfigScope } from "../../../config/index.js";
-import type { Framework } from "../../../constants.js";
-import writeConfigField from "./writeConfigField.js";
-
-/**
- * Build a config-write task for setting or resetting the preferred framework.
- *
- * @param cwd - Working directory the target config layer is resolved from.
- * @param framework - Framework to persist, or `undefined` to reset.
- * @param scope - Optional explicit target layer (`"global"` | `"local"`).
- * @returns Task yielding the persisted field/value payload and target path.
- * @note - Impure — reads and writes the target config file.
- */
-export default function setFramework(
-  cwd: string,
-  framework: Framework | undefined,
-  scope?: ConfigScope,
-): Task<{ field: "framework"; value: Framework | undefined; path: string }> {
-  return writeConfigField(cwd, "framework", framework, scope);
-}

package/src/domains/config/tasks/setTier.ts

@@ -1,20 +0,0 @@
-import type { Task } from "@canonical/task";
-import type { ConfigScope } from "../../../config/index.js";
-import writeConfigField from "./writeConfigField.js";
-
-/**
- * Build a config-write task for setting or resetting the active tier.
- *
- * @param cwd - Working directory the target config layer is resolved from.
- * @param tier - Tier path to persist, or `undefined` to reset.
- * @param scope - Optional explicit target layer (`"global"` | `"local"`).
- * @returns Task yielding the persisted field/value payload and target path.
- * @note - Impure — reads and writes the target config file.
- */
-export default function setTier(
-  cwd: string,
-  tier: string | undefined,
-  scope?: ConfigScope,
-): Task<{ field: "tier"; value: string | undefined; path: string }> {
-  return writeConfigField(cwd, "tier", tier, scope);
-}

package/src/domains/config/tasks/setTrace.ts

@@ -1,20 +0,0 @@
-import type { Task } from "@canonical/task";
-import type { ConfigScope } from "../../../config/index.js";
-import writeConfigField from "./writeConfigField.js";
-
-/**
- * Build a config-write task for enabling or disabling query tracing.
- *
- * @param cwd - Working directory the target config layer is resolved from.
- * @param trace - `true` to enable, `false` to disable.
- * @param scope - Optional explicit target layer (`"global"` | `"local"`).
- * @returns Task yielding the persisted field/value payload and target path.
- * @note - Impure — reads and writes the target config file.
- */
-export default function setTrace(
-  cwd: string,
-  trace: boolean,
-  scope?: ConfigScope,
-): Task<{ field: "trace"; value: boolean | undefined; path: string }> {
-  return writeConfigField(cwd, "trace", trace, scope);
-}

package/src/domains/config/tasks/writeConfigField.ts

@@ -1,41 +0,0 @@
-import { $, gen, type Task, writeFile } from "@canonical/task";
-import {
-  type ConfigScope,
-  type ConfigUpdate,
-  mergeConfigFileUpdate,
-  resolveWriteConfigPath,
-} from "../../../config/index.js";
-
-/**
- * Build a config-write task for one field.
- *
- * Resolves the target layer with the global-first write rule (explicit
- * scope wins, else the nearest existing project file, else the global XDG
- * file), merges the update into that file's own contents — never copying
- * values from another layer — and writes through the tracked `writeFile`
- * effect so the change participates in dry-run and undo. `undefined`
- * removes the field from the target file.
- *
- * @param cwd - Working directory the project layer is resolved from.
- * @param field - Config field to set or remove.
- * @param value - New value, or `undefined` to remove the field.
- * @param scope - Optional explicit target layer.
- * @returns Task yielding the persisted field/value payload and the path written.
- * @note Impure — resolves and reads the target file, writes via effect.
- */
-export default function writeConfigField<F extends keyof ConfigUpdate>(
-  cwd: string,
-  field: F,
-  value: ConfigUpdate[F],
-  scope?: ConfigScope,
-): Task<{ field: F; value: ConfigUpdate[F]; path: string }> {
-  return gen(function* () {
-    const path = resolveWriteConfigPath(cwd, scope);
-    const update = { [field]: value } as ConfigUpdate;
-    const content = mergeConfigFileUpdate(path, update);
-
-    yield* $(writeFile(path, content));
-
-    return { field, value, path };
-  });
-}