@canonical/pragma-cli 0.29.0 → 0.30.0

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

@@ -8,19 +8,28 @@ import type { ConfigShowData } from "../operations/types.js";
  * - **llm** renders a markdown section with bullet points.
  * - **json** serializes the raw ConfigShowData.
  */
+/** Render a `[layer]` marker for values a config file supplied. */
+function originMarker(origin: "default" | "global" | "project"): string {
+  return origin === "default" ? "" : ` [${origin}]`;
+}
+
 const formatters: Formatters<ConfigShowData> = {
   plain(data) {
     const lines: string[] = [];
 
     if (data.tier !== undefined) {
       const chain = data.tierChain.join(" → ");
-      lines.push(`tier: ${data.tier} (${chain})`);
+      lines.push(
+        `tier: ${data.tier} (${chain})${originMarker(data.origins.tier)}`,
+      );
     } else {
       lines.push("tier: (none — all tiers visible)");
     }
 
     const releases = data.includedReleases.join(" + ");
-    lines.push(`channel: ${data.channel} (${releases})`);
+    lines.push(
+      `channel: ${data.channel} (${releases})${originMarker(data.origins.channel)}`,
+    );
     lines.push(`installed via: ${data.installSource}`);
 
     if (data.configFileExists) {
@@ -28,6 +37,11 @@ const formatters: Formatters<ConfigShowData> = {
     } else {
       lines.push("config file: (not found)");
     }
+    if (data.globalConfigExists) {
+      lines.push(`global config: ${data.globalConfigPath}`);
+    } else {
+      lines.push("global config: (not found)");
+    }
 
     return lines.join("\n");
   },
@@ -40,13 +54,17 @@ const formatters: Formatters<ConfigShowData> = {
 
     if (data.tier !== undefined) {
       const chain = data.tierChain.join(" > ");
-      lines.push(`- **Tier:** ${data.tier} (${chain})`);
+      lines.push(
+        `- **Tier:** ${data.tier} (${chain})${originMarker(data.origins.tier)}`,
+      );
     } else {
       lines.push("- **Tier:** none (all tiers visible)");
     }
 
     const releases = data.includedReleases.join(", ");
-    lines.push(`- **Channel:** ${data.channel} (${releases})`);
+    lines.push(
+      `- **Channel:** ${data.channel} (${releases})${originMarker(data.origins.channel)}`,
+    );
     lines.push(`- **Installed via:** ${data.installSource}`);
 
     if (data.configFileExists) {
@@ -54,6 +72,11 @@ const formatters: Formatters<ConfigShowData> = {
     } else {
       lines.push("- **Config file:** not found");
     }
+    if (data.globalConfigExists) {
+      lines.push(`- **Global config:** \`${data.globalConfigPath}\``);
+    } else {
+      lines.push("- **Global config:** not found");
+    }
 
     return lines.join("\n");
   },

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

@@ -8,13 +8,13 @@ import type { Formatters } from "../../shared/formatters.js";
  */
 const traceFormatters = {
   set: {
-    plain: (d: { field: string; value: boolean }) =>
-      d.value ? "Tracing enabled." : "Tracing disabled.",
-    llm: (d: { field: string; value: boolean }) =>
-      d.value ? "Tracing enabled." : "Tracing disabled.",
-    json: (d: { field: string; value: boolean }) =>
-      JSON.stringify({ field: d.field, value: d.value }),
-  } satisfies Formatters<{ field: string; value: boolean }>,
+    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,

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/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/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

@@ -3,3 +3,4 @@ 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,36 +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* () {
-    // Merge onto the full existing config so other fields (e.g. `packages`,
-    // `trace`) survive. `readConfig` normalises defaults (tier: undefined,
-    // channel: "normal"); strip those to keep the file minimal, then apply
-    // the channel change (`undefined` resets it).
-    const current = readConfig(cwd);
-    const { tier, channel: _current, ...rest } = current;
-    const next = {
-      ...rest,
-      ...(tier !== undefined ? { 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

@@ -1,40 +1,21 @@
-import { $, gen, type Task, writeFile } from "@canonical/task";
-import type { Framework } from "#constants";
-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 { 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 containing pragma.config.json.
+ * @param cwd - Working directory the target config layer is resolved from.
  * @param framework - Framework 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 setFramework(
   cwd: string,
   framework: Framework | undefined,
-): Task<{ field: "framework"; value: Framework | undefined }> {
-  return gen(function* () {
-    // Merge onto the full existing config so other fields (e.g. `packages`,
-    // `trace`) survive. `readConfig` normalises defaults (tier: undefined,
-    // channel: "normal"); strip those to keep the file minimal, then apply
-    // the framework change (`undefined` resets it).
-    const current = readConfig(cwd);
-    // Destructure out `framework` too, so a reset (framework === undefined)
-    // actually removes it rather than letting the old value survive in `rest`.
-    const { tier, channel, framework: _current, ...rest } = current;
-    const next = {
-      ...rest,
-      ...(tier !== undefined ? { tier } : {}),
-      ...(channel !== "normal" ? { channel } : {}),
-      ...(framework !== undefined ? { framework } : {}),
-    };
-
-    yield* $(
-      writeFile(resolveConfigPath(cwd), `${JSON.stringify(next, null, 2)}\n`),
-    );
-
-    return { field: "framework", value: framework };
-  });
+  scope?: ConfigScope,
+): Task<{ field: "framework"; value: Framework | undefined; path: string }> {
+  return writeConfigField(cwd, "framework", framework, scope);
 }

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

@@ -1,39 +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* () {
-    // Merge onto the full existing config so other fields (e.g. `packages`,
-    // `trace`) survive. `readConfig` normalises defaults (tier: undefined,
-    // channel: "normal"); strip those to keep the file minimal, then apply
-    // the tier change (`undefined` resets it).
-    const current = readConfig(cwd);
-    const { tier: _current, channel, ...rest } = current;
-    const next = {
-      ...rest,
-      ...(tier !== undefined ? { tier } : {}),
-      ...(channel !== "normal" ? { 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);
 }