@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/config/readConfig.test.ts

@@ -0,0 +1,245 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { runTask } from "@canonical/task/node";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { evaluateProjectConfig } from "./evaluateProjectConfig.js";
+import { findProjectConfig } from "./findProjectConfig.js";
+import { readGlobalConfig } from "./globalConfig.js";
+import { configCacheDir, globalConfigPath } from "./paths.js";
+import { readConfig } from "./readConfig.js";
+import { writeConfigField } from "./writeConfigField.js";
+
+const originalConfigHome = process.env.XDG_CONFIG_HOME;
+const originalStateHome = process.env.XDG_STATE_HOME;
+
+/** Point XDG at fresh temp dirs so each test gets isolated global/cache layers. */
+function freshXdg(): void {
+  process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "pragma-cfg-"));
+  process.env.XDG_STATE_HOME = mkdtempSync(join(tmpdir(), "pragma-state-"));
+}
+
+/** Write the global config JSON. */
+function writeGlobal(json: string): void {
+  const path = globalConfigPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, json);
+}
+
+/** Create a temp project directory with the given `pragma.config.ts` body. */
+function projectWith(body: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-proj-"));
+  writeFileSync(join(dir, "pragma.config.ts"), body);
+  return dir;
+}
+
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = originalConfigHome;
+  process.env.XDG_STATE_HOME = originalStateHome;
+});
+
+describe("readConfig — layering + provenance", () => {
+  it("merges defaults < global < project per field", async () => {
+    freshXdg();
+    writeGlobal('{"channel":"experimental","detail":"summary"}');
+    const dir = projectWith(
+      'export default { tier: "core", detail: "detailed" };',
+    );
+
+    const { config, origins, project, global } = await readConfig(dir);
+
+    expect(config.tier).toBe("core");
+    expect(config.channel).toBe("experimental");
+    expect(config.detail).toBe("detailed");
+    expect(config.packages).toHaveLength(3); // from defaults
+
+    expect(origins).toMatchObject({
+      tier: "project",
+      channel: "global",
+      detail: "project", // project wins over global
+      packages: "default",
+    });
+    expect(project.exists).toBe(true);
+    expect(global.exists).toBe(true);
+  });
+
+  it("falls back to defaults when no layer sets a field", async () => {
+    freshXdg();
+    const dir = mkdtempSync(join(tmpdir(), "pragma-empty-"));
+
+    const { config, origins, project } = await readConfig(dir);
+
+    expect(config.channel).toBe("normal");
+    expect(origins.channel).toBe("default");
+    expect(project.exists).toBe(false);
+  });
+
+  it("replaces packages wholesale from the project layer", async () => {
+    freshXdg();
+    const dir = projectWith('export default { packages: ["@acme/only"] };');
+
+    const { config, origins } = await readConfig(dir);
+
+    expect(config.packages).toEqual(["@acme/only"]);
+    expect(origins.packages).toBe("project");
+  });
+
+  it("merges the completion policy into the effective config", async () => {
+    freshXdg();
+    const dir = projectWith(
+      "export default { completion: { minChars: 3, families: { skill: false } } };",
+    );
+
+    const { config } = await readConfig(dir);
+
+    expect(config.completion).toEqual({
+      minChars: 3,
+      families: { skill: false },
+    });
+  });
+});
+
+describe("global config — corrupt-file recovery", () => {
+  /** Backup siblings the recovery created next to the config file. */
+  function corruptBackups(): string[] {
+    return readdirSync(dirname(globalConfigPath())).filter((f) =>
+      f.includes(".corrupt-"),
+    );
+  }
+
+  it("readGlobalConfig backs up, resets, and degrades to defaults", () => {
+    freshXdg();
+    writeGlobal("{ this is: not valid json");
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+
+    const read = readGlobalConfig();
+    spy.mockRestore();
+
+    // Never bricks: degrades to defaults rather than throwing.
+    expect(read.values).toEqual({});
+    expect(read.exists).toBe(true);
+    expect(errs.join("")).toMatch(/not valid JSON/);
+    // Never silently discards: the corrupt content is preserved in a backup…
+    expect(corruptBackups()).toHaveLength(1);
+    // …and the live file self-heals to defaults.
+    expect(JSON.parse(readFileSync(globalConfigPath(), "utf-8"))).toEqual({});
+  });
+
+  it("writeConfigField backs up a corrupt config before overwriting", async () => {
+    freshXdg();
+    writeGlobal("{ broken");
+    const logs: string[] = [];
+
+    await runTask(writeConfigField("channel", "experimental"), {
+      onLog: (_level, message) => logs.push(message),
+    });
+
+    expect(corruptBackups()).toHaveLength(1);
+    expect(logs.join("")).toMatch(/backed it up/i);
+    // The new field is written over the reset defaults — no silent loss.
+    expect(JSON.parse(readFileSync(globalConfigPath(), "utf-8"))).toEqual({
+      channel: "experimental",
+    });
+  });
+});
+
+describe("findProjectConfig — walk-up", () => {
+  it("finds a config in an ancestor directory", () => {
+    const root = projectWith("export default {};");
+    const nested = join(root, "a", "b");
+    mkdirSync(nested, { recursive: true });
+    expect(findProjectConfig(nested)).toBe(join(root, "pragma.config.ts"));
+  });
+});
+
+describe("evaluateProjectConfig — mtime+VERSION cache", () => {
+  it("serves the cached value on a key hit (no re-evaluation)", async () => {
+    freshXdg();
+    const dir = projectWith('export default { channel: "normal" };');
+    const path = join(dir, "pragma.config.ts");
+
+    // Prime the cache with a cold evaluation.
+    expect(await evaluateProjectConfig(path)).toEqual({ channel: "normal" });
+
+    // Tamper the single cached entry: a genuine re-evaluation would still read
+    // "normal", so returning "experimental" proves the warm path served the
+    // cache without re-importing.
+    const [cached] = readdirSync(configCacheDir());
+    writeFileSync(
+      join(configCacheDir(), cached as string),
+      JSON.stringify({ channel: "experimental" }),
+    );
+
+    expect(await evaluateProjectConfig(path)).toEqual({
+      channel: "experimental",
+    });
+  });
+
+  it("invalidates the cache when the entry file's mtime changes", async () => {
+    freshXdg();
+    const dir = projectWith('export default { tier: "core" };');
+    const path = join(dir, "pragma.config.ts");
+
+    // Prime, then poison the primed entry so a stale-key read would be visible.
+    await evaluateProjectConfig(path);
+    const [primed] = readdirSync(configCacheDir());
+    writeFileSync(
+      join(configCacheDir(), primed as string),
+      JSON.stringify({ tier: "STALE" }),
+    );
+
+    // Bump the entry's mtime (content unchanged): the key changes, so the
+    // poisoned entry is bypassed and the real value is recomputed.
+    const later = new Date(Date.now() + 5000);
+    utimesSync(path, later, later);
+
+    expect(await evaluateProjectConfig(path)).toEqual({ tier: "core" });
+  });
+
+  it("evaluates and writes the cache on a miss", async () => {
+    freshXdg();
+    const dir = projectWith('export default { tier: "core" };');
+    const path = join(dir, "pragma.config.ts");
+
+    const config = await evaluateProjectConfig(path);
+    expect(config).toEqual({ tier: "core" });
+
+    // A second evaluation returns the same (now warm) value.
+    expect(await evaluateProjectConfig(path)).toEqual({ tier: "core" });
+  });
+
+  it("a config that throws while evaluating is a named CONFIG_ERROR, not INTERNAL_ERROR", async () => {
+    freshXdg();
+    // A malformed project config: references an undefined symbol → the module
+    // throws at evaluation. Left unwrapped this collapsed to INTERNAL_ERROR
+    // ("please report this issue") on EVERY command that reads config.
+    const dir = projectWith("export default { tier: definitelyNotDefined };");
+    const path = join(dir, "pragma.config.ts");
+
+    let caught: unknown;
+    try {
+      await evaluateProjectConfig(path);
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    // Names the offending file so the user knows WHAT to fix.
+    expect((caught as { message: string }).message).toContain(path);
+    expect(
+      (caught as { recovery?: { message: string } }).recovery?.message,
+    ).not.toContain("report this issue");
+  });
+});

package/src/kernel/config/readConfig.ts

@@ -0,0 +1,94 @@
+/**
+ * Resolve the layered configuration with per-field provenance.
+ *
+ * Layer order, least to most specific: the built-in {@link defaults}, the
+ * global XDG JSON, and the nearest evaluated `pragma.config.ts`. Merging is
+ * per field — a more specific layer wins wholesale (so `packages` *replaces*,
+ * preserving the "project pins exactly" semantics) — and each field records
+ * the layer that supplied it. Async because the project layer is evaluated
+ * (and content-hash cached).
+ */
+
+import defaults from "./defaults.js";
+import { evaluateProjectConfig } from "./evaluateProjectConfig.js";
+import { findProjectConfig } from "./findProjectConfig.js";
+import { readGlobalConfig } from "./globalConfig.js";
+import type {
+  Channel,
+  ConfigLayers,
+  ConfigOrigin,
+  PragmaConfig,
+  RawConfig,
+} from "./types.js";
+
+/**
+ * Read and merge the config layers for a working directory.
+ *
+ * @param cwd - Directory the project layer is resolved from.
+ * @returns The effective config, per-field origins, and layer metadata.
+ * @throws PragmaError with code `CONFIG_ERROR` when a layer is invalid.
+ * @note Impure — reads config files (and may evaluate `pragma.config.ts`).
+ */
+export async function readConfig(
+  cwd: string = process.cwd(),
+): Promise<ConfigLayers> {
+  const global = readGlobalConfig();
+  const projectPath = findProjectConfig(cwd);
+  const project: RawConfig = projectPath
+    ? await evaluateProjectConfig(projectPath)
+    : {};
+  const defaultValues = defaults as RawConfig;
+
+  const pick = <K extends keyof RawConfig>(
+    field: K,
+  ): { value: RawConfig[K] | undefined; origin: ConfigOrigin } => {
+    if (field in project && project[field] !== undefined) {
+      return { value: project[field], origin: "project" };
+    }
+    if (field in global.values && global.values[field] !== undefined) {
+      return { value: global.values[field], origin: "global" };
+    }
+    return { value: defaultValues[field], origin: "default" };
+  };
+
+  const tier = pick("tier");
+  const channel = pick("channel");
+  const detail = pick("detail");
+  const packages = pick("packages");
+  const stories = pick("stories");
+  const prefixes = pick("prefixes");
+  const prompts = pick("prompts");
+  // `completion` is read at `setup completions` emit time (not on any fast
+  // path) and carries no `config show` provenance, so it merges into the
+  // effective config but is deliberately absent from ConfigOrigins.
+  const completion = pick("completion");
+
+  const config: PragmaConfig = {
+    channel: (channel.value ?? defaults.channel) as Channel,
+    ...(tier.value !== undefined ? { tier: tier.value } : {}),
+    ...(detail.value !== undefined ? { detail: detail.value } : {}),
+    ...(packages.value !== undefined ? { packages: packages.value } : {}),
+    ...(stories.value !== undefined ? { stories: stories.value } : {}),
+    ...(prefixes.value !== undefined ? { prefixes: prefixes.value } : {}),
+    ...(prompts.value !== undefined ? { prompts: prompts.value } : {}),
+    ...(completion.value !== undefined ? { completion: completion.value } : {}),
+  };
+
+  return {
+    config,
+    origins: {
+      tier: tier.origin,
+      channel: channel.origin,
+      detail: detail.origin,
+      packages: packages.origin,
+      stories: stories.origin,
+      prefixes: prefixes.origin,
+      prompts: prompts.origin,
+    },
+    global: { path: global.path, exists: global.exists },
+    project: {
+      ...(projectPath ? { path: projectPath } : {}),
+      exists: projectPath !== undefined,
+    },
+  };
+}

package/src/kernel/config/schema.ts

@@ -0,0 +1,56 @@
+/**
+ * Zod validation for a config layer.
+ *
+ * One of the three sanctioned zod seams (validate.ts / mcp/registerVerb.ts /
+ * config/schema.ts) — never reached from the `--help` or `__complete` fast
+ * path, which are storeless and config-free. Validates the raw shape a global
+ * JSON file or an evaluated `pragma.config.ts` declares; unknown keys are
+ * stripped for forward compatibility, and only present keys survive so layer
+ * merging keeps honest per-field provenance.
+ */
+
+import { z } from "zod";
+import { PragmaError } from "../error/PragmaError.js";
+import { CHANNELS, type RawConfig } from "./types.js";
+
+const packageEntrySchema = z.union([
+  z.string().min(1),
+  z.object({ name: z.string().min(1), source: z.string().optional() }),
+]);
+
+const completionSchema = z.object({
+  minChars: z.number().int().min(0).optional(),
+  caseSensitive: z.boolean().optional(),
+  families: z.record(z.string(), z.boolean()).optional(),
+});
+
+const rawConfigSchema = z.object({
+  tier: z.string().optional(),
+  channel: z.enum(CHANNELS).optional(),
+  detail: z.string().optional(),
+  packages: z.array(packageEntrySchema).optional(),
+  stories: z.array(z.unknown()).optional(),
+  prefixes: z.record(z.string(), z.string()).optional(),
+  prompts: z.record(z.string(), z.unknown()).optional(),
+  completion: completionSchema.optional(),
+});
+
+/**
+ * Validate a raw config value into a {@link RawConfig}.
+ *
+ * @param value - The parsed JSON or evaluated module default.
+ * @param source - The file path, used in error messages.
+ * @returns The validated layer values (only the keys actually present).
+ * @throws PragmaError with code `CONFIG_ERROR` on an invalid shape.
+ */
+export function parseRawConfig(value: unknown, source: string): RawConfig {
+  const result = rawConfigSchema.safeParse(value ?? {});
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const path = issue?.path.join(".") ?? "<root>";
+    throw PragmaError.configError(
+      `Invalid config in ${source} at ${path}: ${issue?.message ?? "unknown error"}.`,
+    );
+  }
+  return result.data as RawConfig;
+}

package/src/kernel/config/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Configuration data shapes.
+ *
+ * The v2 config is deliberately smaller than v1's: no `trace`, no `framework`.
+ * A {@link PragmaConfig} is resolved from three layers — built-in defaults, the
+ * global XDG JSON, and the nearest evaluated `pragma.config.ts` — each field
+ * carrying its {@link ConfigOrigin} so `config show` reports honest provenance.
+ */
+
+/** Allowed release channel values. */
+export const CHANNELS = ["normal", "experimental", "prerelease"] as const;
+
+/** A release channel name. */
+export type Channel = (typeof CHANNELS)[number];
+
+/** The object form of a package source declaration. */
+export interface PackageDeclaration {
+  readonly name: string;
+  readonly source?: string;
+}
+
+/** A `packages` entry: a bare npm name or a `{ name, source }` declaration. */
+export type PackageEntry = string | PackageDeclaration;
+
+/**
+ * Completion policy, read at `setup completions` emit time (never on the
+ * storeless `__complete` fast path). Derive-by-default, tune-by-exception:
+ * `minChars` gates the `__complete` exec in the generated scripts, and
+ * `families` opts a noun out of name completion (`{ <family>: false }`).
+ */
+export interface CompletionConfig {
+  /** Minimum typed chars before the shell execs `__complete` (default 2). */
+  readonly minChars?: number;
+  /** Match case-sensitively (default false — loose match, canonical emit). */
+  readonly caseSensitive?: boolean;
+  /** Per-family opt-out: a noun mapped to `false` drops its name completion. */
+  readonly families?: Readonly<Record<string, boolean>>;
+}
+
+/** The effective, resolved configuration. `channel` always has a value. */
+export interface PragmaConfig {
+  /** Active tier path, or absent when no tier is configured. */
+  readonly tier?: string;
+  /** Release channel controlling component visibility. */
+  readonly channel: Channel;
+  /** Default progressive-disclosure level. */
+  readonly detail?: string;
+  /** Semantic package sources; replaces (does not merge) across layers. */
+  readonly packages?: readonly PackageEntry[];
+  /** Declarative read stories compiled at boot (experimental; opaque here). */
+  readonly stories?: readonly unknown[];
+  /** Additional namespace prefixes merged over the built-in map. */
+  readonly prefixes?: Readonly<Record<string, string>>;
+  /** Named prompt overrides (global machine state). */
+  readonly prompts?: Readonly<Record<string, unknown>>;
+  /** Completion policy (read at `setup completions` emit time). */
+  readonly completion?: CompletionConfig;
+}
+
+/**
+ * The fields a single config layer (global JSON or project TS) may declare. A
+ * key is present only when that layer sets it — presence drives which layer
+ * wins during the merge.
+ */
+export interface RawConfig {
+  readonly tier?: string;
+  readonly channel?: Channel;
+  readonly detail?: string;
+  readonly packages?: readonly PackageEntry[];
+  readonly stories?: readonly unknown[];
+  readonly prefixes?: Readonly<Record<string, string>>;
+  readonly prompts?: Readonly<Record<string, unknown>>;
+  readonly completion?: CompletionConfig;
+}
+
+/** Which layer supplied an effective field value. */
+export type ConfigOrigin = "default" | "global" | "project";
+
+/** Per-field provenance for the effective merged config. */
+export interface ConfigOrigins {
+  readonly tier: ConfigOrigin;
+  readonly channel: ConfigOrigin;
+  readonly detail: ConfigOrigin;
+  readonly packages: ConfigOrigin;
+  readonly stories: ConfigOrigin;
+  readonly prefixes: ConfigOrigin;
+  readonly prompts: ConfigOrigin;
+}
+
+/** A resolved config layer's file location and existence. */
+export interface ConfigLayer {
+  readonly path: string;
+  readonly exists: boolean;
+}
+
+/** The layered config resolution result. */
+export interface ConfigLayers {
+  /** The effective merged configuration (defaults < global < project). */
+  readonly config: PragmaConfig;
+  /** Which layer supplied each effective field. */
+  readonly origins: ConfigOrigins;
+  /** The global XDG layer. */
+  readonly global: ConfigLayer;
+  /** The project layer (absent `path` when no project config was found). */
+  readonly project: { readonly path?: string; readonly exists: boolean };
+}

package/src/kernel/config/writeConfigField.ts

@@ -0,0 +1,82 @@
+/**
+ * Write a single field into the global config, as a Task.
+ *
+ * A mutation, so it lives on the effect seam: `writeConfigField` returns a
+ * `Task` the dispatcher interprets (node interpreter to apply, dry-run to
+ * preview). It merges the field into the existing global document — a value of
+ * `undefined` removes it — and writes the whole document back. Only the global
+ * layer is writable; project configs are authored by hand.
+ *
+ * The Task effect vocabulary has no rename effect, so the write is a single
+ * `WriteFile` (the interpreter creates the parent dir) rather than the
+ * temp-file-plus-rename the v1 sync writer used — the closest atomicity the
+ * effect model expresses. If the existing file is corrupt (unparseable), it is
+ * backed up to a timestamped sibling before the overwrite — consistent with the
+ * read path (globalConfig) so a torn write is never silently discarded.
+ */
+
+import { dirname } from "node:path";
+import {
+  $,
+  exists,
+  gen,
+  mkdir,
+  readFile,
+  type Task,
+  warn,
+  writeFile,
+} from "@canonical/task";
+import { corruptBackupPath } from "./globalConfig.js";
+import { globalConfigPath } from "./paths.js";
+import type { RawConfig } from "./types.js";
+
+/** The result of a global-config write. */
+export interface WriteConfigResult {
+  readonly path: string;
+  readonly field: string;
+}
+
+/**
+ * Build the Task that sets (or removes) one global config field.
+ *
+ * @param field - The config field to write.
+ * @param value - The new value, or `undefined` to remove the field.
+ * @returns A Task yielding the written path and field name.
+ */
+export function writeConfigField(
+  field: keyof RawConfig,
+  value: unknown,
+): Task<WriteConfigResult> {
+  return gen(function* () {
+    const path = globalConfigPath();
+
+    let current: Record<string, unknown> = {};
+    if (yield* $(exists(path))) {
+      const raw = yield* $(readFile(path));
+      try {
+        current = JSON.parse(raw) as Record<string, unknown>;
+      } catch {
+        // Corrupt/torn existing config: preserve it in a timestamped backup and
+        // warn (routed to stderr by the dispatcher's interpreter) before we
+        // overwrite with defaults + the new field — never a silent discard.
+        const backup = corruptBackupPath(path);
+        yield* $(writeFile(backup, raw));
+        yield* $(
+          warn(`${path} was not valid JSON; backed it up to ${backup}.`),
+        );
+        current = {};
+      }
+    }
+
+    const next = { ...current };
+    if (value === undefined) {
+      delete next[field];
+    } else {
+      next[field] = value;
+    }
+
+    yield* $(mkdir(dirname(path), true));
+    yield* $(writeFile(path, `${JSON.stringify(next, null, 2)}\n`));
+    return { path, field };
+  });
+}