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

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

@@ -0,0 +1,85 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { runTask } from "@canonical/task";
+import { readConfig } from "#config";
+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";
+
+/**
+ * Build the `pragma config framework` command definition.
+ *
+ * Sets the preferred UI framework (`react` | `svelte` | `lit`). The value is
+ * currently advisory only — no behaviour reads it yet; it is persisted for
+ * future framework-defaulting. Supports set, reset, and query (no argument).
+ *
+ * @param ctx - Pragma context providing cwd and formatter selection.
+ * @returns The command definition for `pragma config framework`.
+ * @note - Impure — validates framework and writes config to disk.
+ */
+export default function buildFrameworkCommand(
+  ctx: PragmaContext,
+): CommandDefinition {
+  return {
+    path: ["config", "framework"],
+    description: "Set or reset the preferred UI framework (advisory)",
+    parameters: [
+      {
+        name: "value",
+        description: "Framework (react, svelte, lit)",
+        type: "string",
+        positional: true,
+      },
+      {
+        name: "reset",
+        description: "Reset framework to default (none)",
+        type: "boolean",
+        default: false,
+      },
+    ],
+    meta: {
+      examples: [
+        "pragma config framework react",
+        "pragma config framework --reset",
+      ],
+      extendedHelp:
+        "Advisory only for now: the value is persisted but no command reads it yet. Reserved for future framework defaulting.",
+    },
+    execute: async (
+      params: Record<string, unknown>,
+    ): Promise<CommandResult> => {
+      const reset = params.reset === true;
+      const value = params.value as string | undefined;
+
+      if (reset) {
+        await runTask(setFrameworkTask(ctx.cwd, undefined));
+        const format = selectFormatter(ctx, frameworkFormatters.reset);
+        return createOutputResult("Reset framework to default.", {
+          plain: format,
+        });
+      }
+
+      if (!value) {
+        const config = readConfig(ctx.cwd);
+        const format = selectFormatter(ctx, frameworkFormatters.query);
+        return createOutputResult(config.framework ?? "none", {
+          plain: format,
+        });
+      }
+
+      const framework = validateFramework(value);
+
+      await runTask(setFrameworkTask(ctx.cwd, framework));
+      const format = selectFormatter(ctx, frameworkFormatters.set);
+      return createOutputResult(
+        { field: "framework", value: framework },
+        { plain: format },
+      );
+    },
+  };
+}

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

@@ -1,4 +1,6 @@
 /** @module Config command definitions for `pragma config`. */
 export { default as channelCommand } from "./channel.js";
+export { default as frameworkCommand } from "./framework.js";
 export { default as showCommand } from "./show.js";
 export { default as tierCommand } from "./tier.js";
+export { default as traceCommand } from "./trace.js";

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

@@ -0,0 +1,148 @@
+import { 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;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-cmd-trace-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { 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)).toBe("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,80 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { runTask } from "@canonical/task";
+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";
+
+/**
+ * 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,
+      },
+    ],
+    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 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";
+      await runTask(setTraceTask(ctx.cwd, enabled));
+
+      const format = selectFormatter(ctx, traceFormatters.set);
+      return createOutputResult(
+        { field: "trace", value: enabled },
+        { plain: format },
+      );
+    },
+  };
+}

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

@@ -0,0 +1,34 @@
+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 }) =>
+      `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 }>,
+
+  reset: {
+    plain: () => "Reset framework to default.",
+    llm: () => "Reset framework to default.",
+    json: () => JSON.stringify({ field: "framework", reset: true }),
+  } satisfies Formatters<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/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 }) =>
+      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 }>,
+
+  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/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/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/tasks/index.ts

@@ -1,3 +1,5 @@
 /** @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";

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

@@ -15,9 +15,15 @@ export default function setChannel(
   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 = {
-      ...(current.tier !== undefined ? { tier: current.tier } : {}),
+      ...rest,
+      ...(tier !== undefined ? { tier } : {}),
       ...(channel !== undefined ? { channel } : {}),
     };
 

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

@@ -0,0 +1,40 @@
+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";
+
+/**
+ * Build a config-write task for setting or resetting the preferred framework.
+ *
+ * @param cwd - Working directory containing pragma.config.json.
+ * @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.
+ */
+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 };
+  });
+}

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

@@ -18,10 +18,16 @@ export default function setTier(
   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 } : {}),
-      ...(current.channel !== undefined ? { channel: current.channel } : {}),
+      ...(channel !== "normal" ? { channel } : {}),
     };
 
     yield* $(

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

@@ -0,0 +1,38 @@
+import { $, gen, type Task, writeFile } from "@canonical/task";
+import { readConfig } from "../../../config/index.js";
+import resolveConfigPath from "../../../config/resolveConfigPath.js";
+
+/**
+ * Build a config-write task for enabling or disabling query tracing.
+ *
+ * @param cwd - Working directory containing pragma.config.json.
+ * @param trace - `true` to enable, `false` to disable.
+ * @returns Task yielding the persisted field/value payload.
+ */
+export default function setTrace(
+  cwd: string,
+  trace: boolean,
+): Task<{ field: "trace"; value: boolean }> {
+  return gen(function* () {
+    // Merge onto the full existing config so other fields (e.g. `packages`)
+    // survive — rebuilding from a fixed field list silently drops everything
+    // not listed, and `packages` is runtime-consumed, so dropping it is data
+    // loss. `readConfig` normalises defaults (tier: undefined, channel:
+    // "normal"); strip those so we keep the file minimal, matching the
+    // existing convention of not persisting unset defaults.
+    const current = readConfig(cwd);
+    const { tier, channel, ...rest } = current;
+    const next = {
+      ...rest,
+      ...(tier !== undefined ? { tier } : {}),
+      ...(channel !== "normal" ? { channel } : {}),
+      trace,
+    };
+
+    yield* $(
+      writeFile(resolveConfigPath(cwd), `${JSON.stringify(next, null, 2)}\n`),
+    );
+
+    return { field: "trace", value: trace };
+  });
+}

package/src/domains/doctor/operations/checks/checkKeStore.ts

@@ -14,10 +14,10 @@ export default async function checkKeStore(
   ctx: CheckContext,
 ): Promise<CheckResult> {
   const start = performance.now();
-  let store: Awaited<ReturnType<typeof bootStore>> | undefined;
+  let result: Awaited<ReturnType<typeof bootStore>> | undefined;
   try {
-    store = await bootStore({ cwd: ctx.cwd });
-    const summary = await collectStoreSummary(store);
+    result = await bootStore({ cwd: ctx.cwd });
+    const summary = await collectStoreSummary(result.store);
     const elapsed = Math.round(performance.now() - start);
     return {
       name: "ke store",
@@ -30,9 +30,9 @@ export default async function checkKeStore(
       status: "fail",
       detail: "failed to boot",
       remedy:
-        "Ensure design system packages are installed: bun add -D @canonical/ds-global @canonical/code-standards",
+        "Ensure design system packages are installed: bun add -D @canonical/design-system @canonical/anatomy-dsl @canonical/code-standards",
     };
   } finally {
-    store?.dispose();
+    result?.store.dispose();
   }
 }