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

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.");
     }
   });
 

package/src/domains/config/commands/tier.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 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 +41,7 @@ export default function buildTierCommand(
         type: "boolean",
         default: false,
       },
+      ...SCOPE_PARAMETERS,
     ],
     meta: {
       examples: ["pragma config tier apps/lxd", "pragma config tier --reset"],
@@ -47,15 +49,17 @@ 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;
 
       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) {
@@ -69,10 +73,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

@@ -0,0 +1,165 @@
+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";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readConfig } from "#config";
+import type { PragmaContext } from "../../shared/context.js";
+import buildTraceCommand from "./trace.js";
+
+function makeCtx(cwd: string): PragmaContext {
+  return {
+    cwd,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store: {} as Store,
+    config: { tier: undefined, channel: "normal" },
+  };
+}
+
+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 () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    const result = await cmd.execute({ value: "on" }, ctx);
+
+    expect(result.tag).toBe("output");
+    expect(readConfig(dir).trace).toBe(true);
+  });
+
+  it("disables tracing", async () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"trace":true}');
+
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    const result = await cmd.execute({ value: "off" }, ctx);
+
+    expect(result.tag).toBe("output");
+    expect(readConfig(dir).trace).toBe(false);
+  });
+
+  it("renders enable output", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    const result = await cmd.execute({ value: "on" }, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toContain("Tracing enabled.");
+    }
+  });
+
+  it("shows current status when no argument", async () => {
+    writeFileSync(join(dir, "pragma.config.json"), '{"trace":true}');
+
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.value).toBe("on");
+    }
+  });
+
+  it("reports off when unset", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    const result = await cmd.execute({}, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.value).toBe("off");
+    }
+  });
+
+  it("throws INVALID_INPUT for an invalid value", async () => {
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    await expect(cmd.execute({ value: "yes" }, ctx)).rejects.toThrow(/trace/i);
+  });
+
+  // Regression guard for the data-loss bug: enabling/disabling trace must NOT
+  // drop other persisted config fields. `packages` is runtime-consumed, so
+  // silently discarding it on a trace toggle would break package resolution.
+  it("preserves the packages field when toggling trace", async () => {
+    writeFileSync(
+      join(dir, "pragma.config.json"),
+      JSON.stringify({
+        tier: "Apps/WPE",
+        channel: "experimental",
+        packages: [
+          "@canonical/design-system",
+          {
+            name: "@canonical/anatomy-dsl",
+            source: "git+https://github.com/canonical/anatomy-dsl.git#main",
+          },
+        ],
+      }),
+    );
+
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    await cmd.execute({ value: "on" }, ctx);
+
+    const config = readConfig(dir);
+    expect(config.trace).toBe(true);
+    // Every pre-existing field survives the write.
+    expect(config.tier).toBe("Apps/WPE");
+    expect(config.channel).toBe("experimental");
+    expect(config.packages).toEqual([
+      "@canonical/design-system",
+      {
+        name: "@canonical/anatomy-dsl",
+        source: "git+https://github.com/canonical/anatomy-dsl.git#main",
+      },
+    ]);
+
+    // And toggling off again still preserves them.
+    await cmd.execute({ value: "off" }, ctx);
+    const after = readConfig(dir);
+    expect(after.trace).toBe(false);
+    expect(after.packages).toHaveLength(2);
+  });
+
+  it("does not persist the default channel when toggling trace", async () => {
+    // A bare `trace on` on an empty config should not write channel:"normal"
+    // (the default), keeping the file minimal per the existing convention.
+    const ctx = makeCtx(dir);
+    const cmd = buildTraceCommand(ctx);
+    await cmd.execute({ value: "on" }, ctx);
+
+    const raw = JSON.parse(
+      readFileSync(join(dir, "pragma.config.json"), "utf-8"),
+    ) as Record<string, unknown>;
+    expect(raw.trace).toBe(true);
+    expect(raw).not.toHaveProperty("channel");
+    expect(raw).not.toHaveProperty("tier");
+  });
+});

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

@@ -0,0 +1,83 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+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.
+ *
+ * Supports three modes: enable (`on`), disable (`off`), or query
+ * when no argument is provided.
+ */
+export default function buildTraceCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["config", "trace"],
+    description: "Enable or disable query access tracing",
+    parameters: [
+      {
+        name: "value",
+        description: "on or off",
+        type: "string",
+        positional: true,
+      },
+      ...SCOPE_PARAMETERS,
+    ],
+    meta: {
+      examples: [
+        "pragma config trace on",
+        "pragma config trace off",
+        "pragma config trace",
+      ],
+      extendedHelp:
+        "Persists to pragma.config.json. The PRAGMA_TRACE=1 env var overrides this setting.",
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const scope = resolveConfigScope(params);
+      const value = params.value as string | undefined;
+
+      // Query mode — no argument
+      if (!value) {
+        const config = readConfig(ctx.cwd);
+        const enabled = config.trace === true;
+        const envOverride = process.env.PRAGMA_TRACE === "1";
+        const status = envOverride
+          ? "on (PRAGMA_TRACE=1 override)"
+          : enabled
+            ? "on"
+            : "off";
+        const format = selectFormatter(ctx, traceFormatters.query);
+        return createOutputResult(status, { plain: format });
+      }
+
+      // Validate
+      if (value !== "on" && value !== "off") {
+        throw PragmaError.invalidInput("trace", value, {
+          validOptions: ["on", "off"],
+        });
+      }
+
+      // Set mode
+      const enabled = value === "on";
+      const result = await runTask(setTraceTask(ctx.cwd, enabled, scope));
+
+      const format = selectFormatter(ctx, traceFormatters.set);
+      return createOutputResult(
+        { 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

@@ -0,0 +1,37 @@
+import type { Formatters } from "../../shared/formatters.js";
+
+/**
+ * Formatter sets for `pragma config framework` output, grouped by branch:
+ *
+ * - **set** formats the confirmation after setting a framework.
+ * - **reset** formats the confirmation after resetting to default.
+ * - **query** formats the current framework value (or "none").
+ */
+const frameworkFormatters = {
+  set: {
+    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: (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}`,
+    llm: (framework: string) => `Current framework: ${framework}`,
+    json: (framework: string) =>
+      JSON.stringify({ field: "framework", value: framework }),
+  } satisfies Formatters<string>,
+};
+
+export default frameworkFormatters;

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

@@ -1,4 +1,6 @@
 /** @module Formatter sets for config domain output. */
 export { default as channelFormatters } from "./channel.js";
+export { default as frameworkFormatters } from "./framework.js";
 export { default as showFormatters } from "./show.js";
 export { default as tierFormatters } from "./tier.js";
+export { default as traceFormatters } from "./trace.js";

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", () => {

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");
   },