@canonical/pragma-cli 0.29.0 → 0.31.0

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

@@ -0,0 +1,46 @@
+import type { ParameterDefinition } from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import type { ConfigScope } from "../../../config/index.js";
+
+/**
+ * The `--global` / `--local` target-layer flags shared by every config
+ * write command. Without either flag the write follows the global-first
+ * rule: nearest existing project file, else the global XDG file.
+ */
+export const SCOPE_PARAMETERS: readonly ParameterDefinition[] = [
+  {
+    name: "global",
+    description:
+      "Write to the global config ($XDG_CONFIG_HOME/pragma/config.json, default ~/.config/pragma/config.json)",
+    type: "boolean",
+    default: false,
+  },
+  {
+    name: "local",
+    description: "Write to ./pragma.config.json in the current directory",
+    type: "boolean",
+    default: false,
+  },
+];
+
+/**
+ * Resolve the explicit write scope from parsed command parameters.
+ *
+ * @param params - Parsed command parameters.
+ * @returns The explicit scope, or `undefined` for the default rule.
+ * @throws PragmaError with code `INVALID_INPUT` when both flags are set.
+ */
+export function resolveConfigScope(
+  params: Record<string, unknown>,
+): ConfigScope | undefined {
+  const global = params.global === true;
+  const local = params.local === true;
+  if (global && local) {
+    throw PragmaError.invalidInput("scope", "--global --local", {
+      recovery: { message: "Pass at most one of --global or --local." },
+    });
+  }
+  if (global) return "global";
+  if (local) return "local";
+  return undefined;
+}

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

@@ -1,4 +1,10 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Store } from "@canonical/ke";
@@ -18,13 +24,24 @@ function makeCtx(cwd: string): PragmaContext {
 
 describe("config framework command", () => {
   let dir: string;
+  let xdgDir: string;
+  let originalXdg: string | undefined;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), "pragma-cmd-framework-"));
+    // Bound the config walk at the fixture root, seed an empty project
+    // file so writes stay local, and isolate the global XDG layer.
+    mkdirSync(join(dir, ".git"));
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-cmd-framework-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
   });
 
   afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
     rmSync(dir, { recursive: true, force: true });
+    rmSync(xdgDir, { recursive: true, force: true });
   });
 
   it("sets framework to react", async () => {
@@ -45,6 +62,20 @@ describe("config framework command", () => {
     expect(readConfig(dir).framework).toBe("lit");
   });
 
+  it("rejects a value combined with --reset", async () => {
+    const ctx = makeCtx(dir);
+    await expect(
+      buildFrameworkCommand(ctx).execute({ value: "react", reset: true }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+
+  it("rejects an explicit empty-string value", async () => {
+    const ctx = makeCtx(dir);
+    await expect(
+      buildFrameworkCommand(ctx).execute({ value: "" }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+
   it("rejects an invalid framework", async () => {
     const ctx = makeCtx(dir);
     await expect(

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

@@ -3,13 +3,15 @@ import {
   type CommandResult,
   createOutputResult,
 } from "@canonical/cli-core";
-import { runTask } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import { readConfig } from "#config";
+import { PragmaError } from "#error";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
 import { frameworkFormatters } from "../formatters/index.js";
 import { validateFramework } from "../operations/index.js";
 import { setFrameworkTask } from "../tasks/index.js";
+import { resolveConfigScope, SCOPE_PARAMETERS } from "./configScope.js";
 
 /**
  * Build the `pragma config framework` command definition.
@@ -41,6 +43,7 @@ export default function buildFrameworkCommand(
         type: "boolean",
         default: false,
       },
+      ...SCOPE_PARAMETERS,
     ],
     meta: {
       examples: [
@@ -53,18 +56,33 @@ export default function buildFrameworkCommand(
     execute: async (
       params: Record<string, unknown>,
     ): Promise<CommandResult> => {
+      const scope = resolveConfigScope(params);
       const reset = params.reset === true;
       const value = params.value as string | undefined;
 
+      // Contradictory input: a value AND --reset. Reject rather than silently
+      // letting one win.
+      if (reset && value !== undefined) {
+        throw PragmaError.invalidInput("framework", value, {
+          recovery: {
+            message: "Pass either a framework value or --reset, not both.",
+          },
+        });
+      }
+
       if (reset) {
-        await runTask(setFrameworkTask(ctx.cwd, undefined));
+        const result = await runTask(
+          setFrameworkTask(ctx.cwd, undefined, scope),
+        );
         const format = selectFormatter(ctx, frameworkFormatters.reset);
-        return createOutputResult("Reset framework to default.", {
-          plain: format,
-        });
+        return createOutputResult(
+          { field: "framework", path: result.path },
+          { plain: format },
+        );
       }
 
-      if (!value) {
+      // No value at all → query. An explicit empty string is invalid input.
+      if (value === undefined) {
         const config = readConfig(ctx.cwd);
         const format = selectFormatter(ctx, frameworkFormatters.query);
         return createOutputResult(config.framework ?? "none", {
@@ -74,10 +92,10 @@ export default function buildFrameworkCommand(
 
       const framework = validateFramework(value);
 
-      await runTask(setFrameworkTask(ctx.cwd, framework));
+      const result = await runTask(setFrameworkTask(ctx.cwd, framework, scope));
       const format = selectFormatter(ctx, frameworkFormatters.set);
       return createOutputResult(
-        { field: "framework", value: framework },
+        { field: "framework", value: framework, path: result.path },
         { plain: format },
       );
     },

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

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

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

@@ -1,4 +1,4 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Store } from "@canonical/ke";
@@ -18,13 +18,24 @@ function makeCtx(cwd: string): PragmaContext {
 
 describe("config tier command", () => {
   let dir: string;
+  let xdgDir: string;
+  let originalXdg: string | undefined;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), "pragma-cmd-tier-"));
+    // Bound the config walk at the fixture root, seed an empty project
+    // file so writes stay local, and isolate the global XDG layer.
+    mkdirSync(join(dir, ".git"));
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-cmd-tier-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
   });
 
   afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
     rmSync(dir, { recursive: true, force: true });
+    rmSync(xdgDir, { recursive: true, force: true });
   });
 
   it("resets tier via --reset flag", async () => {
@@ -51,7 +62,7 @@ describe("config tier command", () => {
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
       const text = result.render.plain(result.value);
-      expect(text).toBe("Reset tier to default.");
+      expect(text).toContain("Reset tier to default.");
     }
   });
 
@@ -81,4 +92,11 @@ describe("config tier command", () => {
       expect(text).toBe("No tier set (all tiers visible).");
     }
   });
+
+  it("rejects a tier path combined with --reset", async () => {
+    const ctx = makeCtx(dir);
+    await expect(
+      buildTierCommand(ctx).execute({ path: "apps/lxd", reset: true }, ctx),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
 });

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

@@ -3,13 +3,15 @@ import {
   type CommandResult,
   createOutputResult,
 } from "@canonical/cli-core";
-import { runTask } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import { readConfig } from "#config";
+import { PragmaError } from "#error";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
 import { tierFormatters } from "../formatters/index.js";
 import { validateTier } from "../operations/index.js";
 import { setTierTask } from "../tasks/index.js";
+import { resolveConfigScope, SCOPE_PARAMETERS } from "./configScope.js";
 
 /**
  * Build the `pragma config tier` command definition.
@@ -40,6 +42,7 @@ export default function buildTierCommand(
         type: "boolean",
         default: false,
       },
+      ...SCOPE_PARAMETERS,
     ],
     meta: {
       examples: ["pragma config tier apps/lxd", "pragma config tier --reset"],
@@ -47,18 +50,32 @@ export default function buildTierCommand(
     execute: async (
       params: Record<string, unknown>,
     ): Promise<CommandResult> => {
+      const scope = resolveConfigScope(params);
       const reset = params.reset === true;
       const tierPath = params.path as string | undefined;
 
+      // Contradictory input: a tier path AND --reset. Reject rather than
+      // silently letting one win.
+      if (reset && tierPath !== undefined) {
+        throw PragmaError.invalidInput("tier", tierPath, {
+          recovery: {
+            message: "Pass either a tier path or --reset, not both.",
+          },
+        });
+      }
+
       if (reset) {
-        await runTask(setTierTask(ctx.cwd, undefined));
+        const result = await runTask(setTierTask(ctx.cwd, undefined, scope));
         const format = selectFormatter(ctx, tierFormatters.reset);
-        return createOutputResult("Reset tier to default.", {
-          plain: format,
-        });
+        return createOutputResult(
+          { field: "tier", path: result.path },
+          { plain: format },
+        );
       }
 
-      if (!tierPath) {
+      // No path at all → query. An explicit empty string is invalid input and
+      // is rejected by validateTier below.
+      if (tierPath === undefined) {
         const config = readConfig(ctx.cwd);
         const format = selectFormatter(ctx, tierFormatters.query);
         return createOutputResult(config.tier, {
@@ -69,10 +86,10 @@ export default function buildTierCommand(
       // Validate tier against ontology
       await validateTier(ctx.store, tierPath);
 
-      await runTask(setTierTask(ctx.cwd, tierPath));
+      const result = await runTask(setTierTask(ctx.cwd, tierPath, scope));
       const format = selectFormatter(ctx, tierFormatters.set);
       return createOutputResult(
-        { field: "tier", value: tierPath },
+        { field: "tier", value: tierPath, path: result.path },
         { plain: format },
       );
     },

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

@@ -1,4 +1,10 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Store } from "@canonical/ke";
@@ -18,13 +24,24 @@ function makeCtx(cwd: string): PragmaContext {
 
 describe("config trace command", () => {
   let dir: string;
+  let xdgDir: string;
+  let originalXdg: string | undefined;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), "pragma-cmd-trace-"));
+    // Bound the config walk at the fixture root, seed an empty project
+    // file so writes stay local, and isolate the global XDG layer.
+    mkdirSync(join(dir, ".git"));
+    writeFileSync(join(dir, "pragma.config.json"), "{}");
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    xdgDir = mkdtempSync(join(tmpdir(), "pragma-cmd-trace-xdg-"));
+    process.env.XDG_CONFIG_HOME = xdgDir;
   });
 
   afterEach(() => {
+    process.env.XDG_CONFIG_HOME = originalXdg;
     rmSync(dir, { recursive: true, force: true });
+    rmSync(xdgDir, { recursive: true, force: true });
   });
 
   it("enables tracing", async () => {
@@ -54,7 +71,7 @@ describe("config trace command", () => {
 
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
-      expect(result.render.plain(result.value)).toBe("Tracing enabled.");
+      expect(result.render.plain(result.value)).toContain("Tracing enabled.");
     }
   });
 

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

@@ -3,13 +3,14 @@ import {
   type CommandResult,
   createOutputResult,
 } from "@canonical/cli-core";
-import { runTask } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import { readConfig } from "#config";
 import { PragmaError } from "#error";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
 import { traceFormatters } from "../formatters/index.js";
 import { setTraceTask } from "../tasks/index.js";
+import { resolveConfigScope, SCOPE_PARAMETERS } from "./configScope.js";
 
 /**
  * Build the `pragma config trace` command definition.
@@ -30,6 +31,7 @@ export default function buildTraceCommand(
         type: "string",
         positional: true,
       },
+      ...SCOPE_PARAMETERS,
     ],
     meta: {
       examples: [
@@ -43,6 +45,7 @@ export default function buildTraceCommand(
     execute: async (
       params: Record<string, unknown>,
     ): Promise<CommandResult> => {
+      const scope = resolveConfigScope(params);
       const value = params.value as string | undefined;
 
       // Query mode — no argument
@@ -68,11 +71,11 @@ export default function buildTraceCommand(
 
       // Set mode
       const enabled = value === "on";
-      await runTask(setTraceTask(ctx.cwd, enabled));
+      const result = await runTask(setTraceTask(ctx.cwd, enabled, scope));
 
       const format = selectFormatter(ctx, traceFormatters.set);
       return createOutputResult(
-        { field: "trace", value: enabled },
+        { field: "trace", value: enabled, path: result.path },
         { plain: format },
       );
     },

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

@@ -2,14 +2,22 @@ import { describe, expect, it } from "vitest";
 import formatters from "./channel.js";
 
 describe("channelFormatters.set", () => {
-  const data = { field: "channel", value: "experimental" };
+  const data = {
+    field: "channel",
+    value: "experimental",
+    path: "/repo/pragma.config.json",
+  };
 
   it("plain renders set message", () => {
-    expect(formatters.set.plain(data)).toBe('Set channel to "experimental".');
+    expect(formatters.set.plain(data)).toBe(
+      'Set channel to "experimental".\nWrote /repo/pragma.config.json',
+    );
   });
 
   it("llm renders set message", () => {
-    expect(formatters.set.llm(data)).toBe('Set channel to "experimental".');
+    expect(formatters.set.llm(data)).toBe(
+      'Set channel to "experimental".\nWrote /repo/pragma.config.json',
+    );
   });
 
   it("json returns valid JSON", () => {
@@ -21,15 +29,21 @@ describe("channelFormatters.set", () => {
 
 describe("channelFormatters.reset", () => {
   it("plain renders reset message", () => {
-    expect(formatters.reset.plain("")).toBe("Reset channel to default.");
+    expect(
+      formatters.reset.plain({ field: "channel", path: "/repo/p.json" }),
+    ).toBe("Reset channel to default.\nWrote /repo/p.json");
   });
 
   it("llm renders reset message", () => {
-    expect(formatters.reset.llm("")).toBe("Reset channel to default.");
+    expect(
+      formatters.reset.llm({ field: "channel", path: "/repo/p.json" }),
+    ).toBe("Reset channel to default.\nWrote /repo/p.json");
   });
 
   it("json returns valid JSON", () => {
-    const parsed = JSON.parse(formatters.reset.json(""));
+    const parsed = JSON.parse(
+      formatters.reset.json({ field: "channel", path: "/repo/p.json" }),
+    );
     expect(parsed.field).toBe("channel");
     expect(parsed.reset).toBe(true);
   });

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

@@ -9,19 +9,22 @@ import type { Formatters } from "../../shared/formatters.js";
  */
 const channelFormatters = {
   set: {
-    plain: (d: { field: string; value: string }) =>
-      `Set ${d.field} to "${d.value}".`,
-    llm: (d: { field: string; value: string }) =>
-      `Set ${d.field} to "${d.value}".`,
-    json: (d: { field: string; value: string }) =>
-      JSON.stringify({ field: d.field, value: d.value }),
-  } satisfies Formatters<{ field: string; value: string }>,
+    plain: (d: { field: string; value: string; path: string }) =>
+      `Set ${d.field} to "${d.value}".\nWrote ${d.path}`,
+    llm: (d: { field: string; value: string; path: string }) =>
+      `Set ${d.field} to "${d.value}".\nWrote ${d.path}`,
+    json: (d: { field: string; value: string; path: string }) =>
+      JSON.stringify({ field: d.field, value: d.value, path: d.path }),
+  } satisfies Formatters<{ field: string; value: string; path: string }>,
 
   reset: {
-    plain: () => "Reset channel to default.",
-    llm: () => "Reset channel to default.",
-    json: () => JSON.stringify({ field: "channel", reset: true }),
-  } satisfies Formatters<string>,
+    plain: (d: { field: string; path: string }) =>
+      `Reset channel to default.\nWrote ${d.path}`,
+    llm: (d: { field: string; path: string }) =>
+      `Reset channel to default.\nWrote ${d.path}`,
+    json: (d: { field: string; path: string }) =>
+      JSON.stringify({ field: "channel", reset: true, path: d.path }),
+  } satisfies Formatters<{ field: string; path: string }>,
 
   query: {
     plain: (channel: string) => `Current channel: ${channel}`,

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

@@ -9,19 +9,22 @@ import type { Formatters } from "../../shared/formatters.js";
  */
 const frameworkFormatters = {
   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: { field: string; value: string; path: string }) =>
+      `Set ${d.field} to "${d.value}".\nWrote ${d.path}`,
+    llm: (d: { field: string; value: string; path: string }) =>
+      `Set ${d.field} to "${d.value}".\nWrote ${d.path}`,
+    json: (d: { field: string; value: string; path: string }) =>
+      JSON.stringify({ field: d.field, value: d.value, path: d.path }),
+  } satisfies Formatters<{ field: string; value: string; path: string }>,
 
   reset: {
-    plain: () => "Reset framework to default.",
-    llm: () => "Reset framework to default.",
-    json: () => JSON.stringify({ field: "framework", reset: true }),
-  } satisfies Formatters<string>,
+    plain: (d: { field: string; path: string }) =>
+      `Reset framework to default.\nWrote ${d.path}`,
+    llm: (d: { field: string; path: string }) =>
+      `Reset framework to default.\nWrote ${d.path}`,
+    json: (d: { field: string; path: string }) =>
+      JSON.stringify({ field: "framework", reset: true, path: d.path }),
+  } satisfies Formatters<{ field: string; path: string }>,
 
   query: {
     plain: (framework: string) => `Current framework: ${framework}`,

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

@@ -11,6 +11,15 @@ const WITH_TIER: ConfigShowData = {
   installSource: "bun (global)",
   configFilePath: "/project/pragma.config.json",
   configFileExists: true,
+  globalConfigPath: "/home/u/.config/pragma/config.json",
+  globalConfigExists: false,
+  origins: {
+    tier: "project",
+    channel: "project",
+    packages: "default",
+    trace: "default",
+    framework: "default",
+  },
 };
 
 const WITHOUT_TIER: ConfigShowData = {
@@ -22,6 +31,15 @@ const WITHOUT_TIER: ConfigShowData = {
   installSource: "bun (local)",
   configFilePath: "/project/pragma.config.json",
   configFileExists: false,
+  globalConfigPath: "/home/u/.config/pragma/config.json",
+  globalConfigExists: false,
+  origins: {
+    tier: "project",
+    channel: "project",
+    packages: "default",
+    trace: "default",
+    framework: "default",
+  },
 };
 
 const PRERELEASE: ConfigShowData = {
@@ -33,6 +51,15 @@ const PRERELEASE: ConfigShowData = {
   installSource: "pnpm (global)",
   configFilePath: "/project/pragma.config.json",
   configFileExists: true,
+  globalConfigPath: "/home/u/.config/pragma/config.json",
+  globalConfigExists: false,
+  origins: {
+    tier: "project",
+    channel: "project",
+    packages: "default",
+    trace: "default",
+    framework: "default",
+  },
 };
 
 describe("formatters.plain", () => {