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

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

@@ -2,36 +2,52 @@ import { describe, expect, it } from "vitest";
 import formatters from "./tier.js";
 
 describe("tierFormatters.set", () => {
-  const data = { field: "tier", value: "apps/lxd" };
+  const data = {
+    field: "tier",
+    value: "apps/lxd",
+    path: "/repo/pragma.config.json",
+  };
 
-  it("plain renders set message", () => {
-    expect(formatters.set.plain(data)).toBe('Set tier to "apps/lxd".');
+  it("plain renders set message with the written path", () => {
+    expect(formatters.set.plain(data)).toBe(
+      'Set tier to "apps/lxd".\nWrote /repo/pragma.config.json',
+    );
   });
 
-  it("llm renders set message", () => {
-    expect(formatters.set.llm(data)).toBe('Set tier to "apps/lxd".');
+  it("llm renders set message with the written path", () => {
+    expect(formatters.set.llm(data)).toBe(
+      'Set tier to "apps/lxd".\nWrote /repo/pragma.config.json',
+    );
   });
 
   it("json returns valid JSON", () => {
     const parsed = JSON.parse(formatters.set.json(data));
     expect(parsed.field).toBe("tier");
     expect(parsed.value).toBe("apps/lxd");
+    expect(parsed.path).toBe("/repo/pragma.config.json");
   });
 });
 
 describe("tierFormatters.reset", () => {
-  it("plain renders reset message", () => {
-    expect(formatters.reset.plain("")).toBe("Reset tier to default.");
+  const data = { field: "tier", path: "/repo/pragma.config.json" };
+
+  it("plain renders reset message with the written path", () => {
+    expect(formatters.reset.plain(data)).toBe(
+      "Reset tier to default.\nWrote /repo/pragma.config.json",
+    );
   });
 
-  it("llm renders reset message", () => {
-    expect(formatters.reset.llm("")).toBe("Reset tier to default.");
+  it("llm renders reset message with the written path", () => {
+    expect(formatters.reset.llm(data)).toBe(
+      "Reset tier to default.\nWrote /repo/pragma.config.json",
+    );
   });
 
   it("json returns valid JSON", () => {
-    const parsed = JSON.parse(formatters.reset.json(""));
+    const parsed = JSON.parse(formatters.reset.json(data));
     expect(parsed.field).toBe("tier");
     expect(parsed.reset).toBe(true);
+    expect(parsed.path).toBe("/repo/pragma.config.json");
   });
 });
 

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

@@ -1,5 +1,12 @@
 import type { Formatters } from "../../shared/formatters.js";
 
+/** Payload for a persisted config write, including the file written. */
+interface TierWrite {
+  readonly field: string;
+  readonly value: string;
+  readonly path: string;
+}
+
 /**
  * Formatter sets for `pragma config tier` output, grouped by branch:
  *
@@ -9,19 +16,20 @@ import type { Formatters } from "../../shared/formatters.js";
  */
 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 }>,
+    plain: (d: TierWrite) => `Set ${d.field} to "${d.value}".\nWrote ${d.path}`,
+    llm: (d: TierWrite) => `Set ${d.field} to "${d.value}".\nWrote ${d.path}`,
+    json: (d: TierWrite) =>
+      JSON.stringify({ field: d.field, value: d.value, path: d.path }),
+  } satisfies Formatters<TierWrite>,
 
   reset: {
-    plain: () => "Reset tier to default.",
-    llm: () => "Reset tier to default.",
-    json: () => JSON.stringify({ field: "tier", reset: true }),
-  } satisfies Formatters<string>,
+    plain: (d: { field: string; path: string }) =>
+      `Reset tier to default.\nWrote ${d.path}`,
+    llm: (d: { field: string; path: string }) =>
+      `Reset tier to default.\nWrote ${d.path}`,
+    json: (d: { field: string; path: string }) =>
+      JSON.stringify({ field: "tier", reset: true, path: d.path }),
+  } satisfies Formatters<{ field: string; path: string }>,
 
   query: {
     plain: (tier: string | undefined) =>

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

@@ -0,0 +1,28 @@
+import type { Formatters } from "../../shared/formatters.js";
+
+/**
+ * Formatter sets for `pragma config trace` output, grouped by branch:
+ *
+ * - **set** formats the confirmation after enabling/disabling.
+ * - **query** formats the current trace status.
+ */
+const traceFormatters = {
+  set: {
+    plain: (d: { field: string; value: boolean; path: string }) =>
+      `${d.value ? "Tracing enabled." : "Tracing disabled."}\nWrote ${d.path}`,
+    llm: (d: { field: string; value: boolean; path: string }) =>
+      `${d.value ? "Tracing enabled." : "Tracing disabled."}\nWrote ${d.path}`,
+    json: (d: { field: string; value: boolean; path: string }) =>
+      JSON.stringify({ field: d.field, value: d.value, path: d.path }),
+  } satisfies Formatters<{ field: string; value: boolean; path: string }>,
+
+  query: {
+    plain: (status: string) => status,
+    llm: (status: string) => status,
+    // Emit the human-readable status under `status`, not `value`, so the JSON
+    // shape stays consistent with `set` (where `value` is the boolean state).
+    json: (status: string) => JSON.stringify({ field: "trace", status }),
+  } satisfies Formatters<string>,
+};
+
+export default traceFormatters;

package/src/domains/config/index.ts

@@ -2,7 +2,13 @@
 
 import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../shared/context.js";
-import { channelCommand, showCommand, tierCommand } from "./commands/index.js";
+import {
+  channelCommand,
+  frameworkCommand,
+  showCommand,
+  tierCommand,
+  traceCommand,
+} from "./commands/index.js";
 
 /**
  * Return all config command definitions.
@@ -11,7 +17,13 @@ import { channelCommand, showCommand, tierCommand } from "./commands/index.js";
  * @returns An array of CommandDefinitions for the config subcommands.
  */
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [tierCommand(ctx), channelCommand(ctx), showCommand(ctx)];
+  return [
+    tierCommand(ctx),
+    channelCommand(ctx),
+    traceCommand(ctx),
+    frameworkCommand(ctx),
+    showCommand(ctx),
+  ];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
@@ -19,5 +31,6 @@ export type { ConfigShowData } from "./operations/index.js";
 export {
   resolveConfigShow,
   validateChannel,
+  validateFramework,
   validateTier,
 } from "./operations/index.js";

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

@@ -1,54 +1,20 @@
 /**
- * MCP tool specs for the config domain.
+ * MCP tool specs for the config domain — config_show, config_tier,
+ * config_channel.
  *
- * config_show uses the shared resolveConfigShow() operation so that
- * MCP data matches what the CLI produces (tierChain, includedReleases, etc.).
+ * 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 { detectInstallSource } from "#package-manager";
+import { compileReadTool } from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { showFormatters } from "../formatters/index.js";
-import {
-  resolveConfigShow,
-  validateChannel,
-  validateTier,
-} from "../operations/index.js";
+import { validateChannel, validateTier } from "../operations/index.js";
+import { configShowStory } from "../stories.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 install = detectInstallSource();
-      const data = resolveConfigShow(rt.config, {
-        packageManager: install.packageManager,
-        installSource: install.label,
-        configFilePath: "pragma.config.json",
-        configFileExists: true,
-      });
-
-      if (condensed) {
-        const text = showFormatters.llm(data);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data };
-    },
-  },
+  compileReadTool(configShowStory),
   {
     name: "config_tier",
     description:
@@ -64,18 +30,25 @@ const specs: readonly ToolSpec[] = [
         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 }) {
+    async execute(rt, { path, reset, global: globalScope }) {
+      const scope = globalScope === true ? "global" : undefined;
+
       if (reset) {
-        writeConfig(rt.cwd, { tier: undefined });
-        return { data: { tier: null, action: "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);
-        writeConfig(rt.cwd, { tier: path as string });
-        return { data: { tier: path, action: "set" } };
+        const written = writeConfig(rt.cwd, { tier: path as string }, scope);
+        return { data: { tier: path, action: "set", path: written } };
       }
 
       const config = readConfig(rt.cwd);
@@ -97,18 +70,25 @@ const specs: readonly ToolSpec[] = [
         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 }) {
+    async execute(rt, { value, reset, global: globalScope }) {
+      const scope = globalScope === true ? "global" : undefined;
+
       if (reset) {
-        writeConfig(rt.cwd, { channel: undefined });
-        return { data: { channel: "normal", action: "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);
-        writeConfig(rt.cwd, { channel });
-        return { data: { channel, action: "set" } };
+        const written = writeConfig(rt.cwd, { channel }, scope);
+        return { data: { channel, action: "set", path: written } };
       }
 
       const config = readConfig(rt.cwd);

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

@@ -2,4 +2,5 @@
 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,6 +1,21 @@
 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(
@@ -10,6 +25,7 @@ describe("resolveConfigShow", () => {
         installSource: "bun (global)",
         configFilePath: "/tmp/pragma.config.json",
         configFileExists: true,
+        ...PROVENANCE,
       },
     );
 
@@ -30,6 +46,7 @@ describe("resolveConfigShow", () => {
         installSource: "bun (local)",
         configFilePath: "/tmp/pragma.config.json",
         configFileExists: false,
+        ...PROVENANCE,
       },
     );
 
@@ -47,6 +64,7 @@ describe("resolveConfigShow", () => {
         installSource: "pnpm (global)",
         configFilePath: "/tmp/pragma.config.json",
         configFileExists: true,
+        ...PROVENANCE,
       },
     );
 

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

@@ -1,4 +1,4 @@
-import type { PragmaConfig } from "#config";
+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";
@@ -20,6 +20,9 @@ export default function resolveConfigShow(
     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.
@@ -38,5 +41,8 @@ export default function resolveConfigShow(
     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,3 +1,4 @@
+import type { ConfigOrigins } from "#config";
 import type { Channel } from "#constants";
 
 /** Data returned by `pragma config show`, including resolved tier chain and channel releases. */
@@ -8,6 +9,12 @@ export interface ConfigShowData {
   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/validateFramework.ts

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

@@ -0,0 +1,42 @@
+/**
+ * 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,3 +1,6 @@
 /** @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,30 +1,21 @@
-import { $, gen, type Task, writeFile } from "@canonical/task";
-import { readConfig } from "../../../config/index.js";
-import resolveConfigPath from "../../../config/resolveConfigPath.js";
+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 containing pragma.config.json.
- * @param channel - Channel value to persist, or `undefined` to reset.
- * @returns Task yielding the persisted field/value payload.
- * @note - Impure — reads config and writes to the file system.
+ * @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: string | undefined,
-): Task<{ field: "channel"; value: string | undefined }> {
-  return gen(function* () {
-    const current = readConfig(cwd);
-    const next = {
-      ...(current.tier !== undefined ? { tier: current.tier } : {}),
-      ...(channel !== undefined ? { channel } : {}),
-    };
-
-    yield* $(
-      writeFile(resolveConfigPath(cwd), `${JSON.stringify(next, null, 2)}\n`),
-    );
-
-    return { field: "channel", value: channel };
-  });
+  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

@@ -0,0 +1,21 @@
+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,33 +1,20 @@
-import { $, gen, type Task, writeFile } from "@canonical/task";
-import { readConfig } from "../../../config/index.js";
-import resolveConfigPath from "../../../config/resolveConfigPath.js";
+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 containing pragma.config.json.
+ * @param cwd - Working directory the target config layer is resolved from.
  * @param tier - Tier path to persist, or `undefined` to reset.
- * @returns Task yielding the persisted field/value payload.
- * @note - Impure — reads config and writes to the file system.
+ * @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,
-): Task<{
-  field: "tier";
-  value: string | undefined;
-}> {
-  return gen(function* () {
-    const current = readConfig(cwd);
-    const next = {
-      ...(tier !== undefined ? { tier } : {}),
-      ...(current.channel !== undefined ? { channel: current.channel } : {}),
-    };
-
-    yield* $(
-      writeFile(resolveConfigPath(cwd), `${JSON.stringify(next, null, 2)}\n`),
-    );
-
-    return { field: "tier", value: tier };
-  });
+  scope?: ConfigScope,
+): Task<{ field: "tier"; value: string | undefined; path: string }> {
+  return writeConfigField(cwd, "tier", tier, scope);
 }

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

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

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