@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/completion/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Shapes of the completion engine — the model both tiers share, the parsed
+ * request the `__complete` resolver answers, and the dynamic-tier seam.
+ *
+ * The model is derived from the capability modules (the specs), NOT parsed
+ * from `surface.v2.json`: the emitted surface deliberately omits enum values,
+ * param kinds, and the `complete` field, and the grammar must not grow for a
+ * projection. Agreement with the covenant is transitive — the projection
+ * agreement test pins the model's noun/verb/flag sets to `emitSurface`, which
+ * conformance pins to the golden.
+ */
+
+import type { CompletionMatch, CompletionSourceRef } from "../spec/types.js";
+
+/** The shells the static completion tier can emit scripts for. */
+export type Shell = "bash" | "zsh" | "fish";
+
+/** A single completion candidate — always a bare word, never shell syntax. */
+export type Candidate = string;
+
+/**
+ * Where a value-position's candidates come from (`ParamSpec.complete`
+ * resolved against the param kind — see `model.ts` for the defaults table).
+ */
+export type CompletionSource =
+  /** A closed value set (enum params) — inlined by the static tier. */
+  | { readonly kind: "values"; readonly values: readonly string[] }
+  /**
+   * Names of a storeless source (index/skills/tiers/prompts/prefixes) — the
+   * dynamic tier reads them via the seam and ranks them with `match`/case. The
+   * static scripts exec `__complete` for every name source, one code path.
+   */
+  | {
+      readonly kind: "names";
+      readonly ref: CompletionSourceRef;
+      readonly match: CompletionMatch;
+      readonly caseSensitive: boolean;
+    }
+  /** File paths — the static scripts delegate to native shell completion. */
+  | { readonly kind: "files" }
+  /** Nothing to offer. */
+  | { readonly kind: "none" };
+
+/** One flag of a verb (or a global/mutation flag) as completion sees it. */
+export interface FlagEntry {
+  /** The full flag token (`--with-history`). */
+  readonly flag: string;
+  /** Whether the flag consumes a value (false for booleans). */
+  readonly takesValue: boolean;
+  /** Whether the flag may repeat (`string[]` params) — never de-offered. */
+  readonly repeatable: boolean;
+  /** Offered only before a noun is chosen (`--version`). */
+  readonly rootOnly?: boolean;
+  /** Where the flag's value candidates come from. */
+  readonly source: CompletionSource;
+}
+
+/** One positional slot of a verb. */
+export interface PositionalEntry {
+  /** The param name (for diagnostics and projection agreement). */
+  readonly name: string;
+  /** Whether the positional is required (`<name>` vs `[name]`). */
+  readonly required: boolean;
+  /** Whether the positional absorbs all further indices (`string[]`). */
+  readonly variadic: boolean;
+  /** Where the positional's candidates come from. */
+  readonly source: CompletionSource;
+}
+
+/** One verb (a sub-verb or a noun's self-verb) as completion sees it. */
+export interface VerbEntry {
+  /** The verb label (`show`; the noun itself for a self-verb). */
+  readonly label: string;
+  /** Whether the verb mutates — mutation flags are offered iff true. */
+  readonly mutates: boolean;
+  /** The verb's flags, in declared order. */
+  readonly flags: readonly FlagEntry[];
+  /** The verb's positionals, in declared order. */
+  readonly positionals: readonly PositionalEntry[];
+}
+
+/** One noun with its self-verb (if any) and sub-verbs. */
+export interface NounEntry {
+  /** The noun token. */
+  readonly noun: string;
+  /** The self-verb (`["info"]`), when the noun is invocable bare. */
+  readonly selfVerb?: VerbEntry;
+  /** Sub-verbs (`["config","show"]`), sorted by label. */
+  readonly verbs: readonly VerbEntry[];
+}
+
+/** The completion model: everything both tiers offer, spec-derived. */
+export interface CompletionModel {
+  /** Every visible noun (plus the bin-served `mcp`), sorted. */
+  readonly nouns: readonly NounEntry[];
+  /** Global flags offered in every flag position (`rootOnly` filtered). */
+  readonly globalFlags: readonly FlagEntry[];
+  /** Mutation flags injected for `mutates` verbs. */
+  readonly mutationFlags: readonly FlagEntry[];
+}
+
+/**
+ * What the current word is completing, classified by the argv state machine.
+ * Structural contexts carry what to offer; value contexts carry the source.
+ */
+export type CompletionContext =
+  /** Completing the first command token — offer nouns. */
+  | { readonly kind: "noun" }
+  /** Completing a sub-verb of `noun`. */
+  | { readonly kind: "verb"; readonly noun: string }
+  /** Completing a flag name — `flags` is already scoped and de-offered. */
+  | { readonly kind: "flag-name"; readonly flags: readonly string[] }
+  /** Completing a flag's value. */
+  | {
+      readonly kind: "flag-value";
+      readonly flag: string;
+      readonly source: CompletionSource;
+    }
+  /** Completing a positional. */
+  | {
+      readonly kind: "positional";
+      readonly name: string;
+      readonly source: CompletionSource;
+    }
+  /** Nothing to offer; `reason` feeds the debug channel. */
+  | { readonly kind: "nothing"; readonly reason: string };
+
+/** A parsed completion request: the classified context plus the partial word. */
+export interface CompletionRequest {
+  /** The classified context of the word being completed. */
+  readonly context: CompletionContext;
+  /** The partial text of the word being completed (may be empty). */
+  readonly partial: string;
+}
+
+/**
+ * The dynamic-tier seam: reads candidate names for a `{kind:"names"}` source.
+ * One source-dispatched reader serves every family — index, skills, tiers,
+ * prompts, prefixes — so the resolver ranks them uniformly. The default
+ * ({@link import("./entitySource.js").emptyNameSource}) yields nothing, so
+ * structural completion never pays a read; {@link
+ * import("./entitySource.js").indexCompletionEnv} wires the storeless sources.
+ */
+export interface CompletionEnv {
+  /**
+   * The candidate names for a source ref (full list, canonical casing), or none
+   * when unavailable. May be sync or async; failures must surface as an empty
+   * list, never throw — the resolver filters/ranks against the partial.
+   */
+  names(
+    ref: CompletionSourceRef,
+  ): Promise<readonly string[]> | readonly string[];
+}

package/src/kernel/config/__snapshots__/firstRun.test.ts.snap

@@ -0,0 +1,11 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`first run > greets on stderr and seeds the global config 1`] = `
+[
+  "Hello! Thanks for taking the time to try the pre-release pragma CLI.",
+  "Please file issues and feedback at https://github.com/canonical/pragma/issues.",
+  "Pragma stores its configuration in <CONFIG> (just created with defaults).",
+  "A \`pragma.config.ts\` in this directory or above it overrides it per project.",
+  "",
+]
+`;

package/src/kernel/config/defaults.ts

@@ -0,0 +1,28 @@
+/**
+ * Built-in configuration defaults (D6 — TS, not JSON).
+ *
+ * The lowest config layer. Authored as a typed module so an invalid edit fails
+ * at type-check rather than at runtime, and so the default `packages` sources
+ * live in one place. Sources verified against the v1 `config/defaults.json`.
+ */
+
+import type { PragmaConfig } from "./types.js";
+
+export default {
+  channel: "normal",
+  detail: "standard",
+  packages: [
+    {
+      name: "@canonical/design-system",
+      source: "git+https://github.com/canonical/design-system.git#main",
+    },
+    {
+      name: "@canonical/anatomy-dsl",
+      source: "git+https://github.com/canonical/anatomy-dsl.git#main",
+    },
+    {
+      name: "@canonical/code-standards",
+      source: "git+https://github.com/canonical/web-code-standards.git#main",
+    },
+  ],
+} satisfies PragmaConfig;

package/src/kernel/config/evaluateProjectConfig.ts

@@ -0,0 +1,119 @@
+/**
+ * Evaluate `pragma.config.ts` with an invalidating cache (D7).
+ *
+ * The project config is real TypeScript — evaluated via the runtime's native
+ * dynamic import of the file's `default` export. Because evaluation is the cost,
+ * the validated (JSON-serializable) result is cached under
+ * `$XDG_STATE_HOME/pragma/config-cache/<key>.json`. Warm path: derive key →
+ * cache hit → `JSON.parse` (sub-ms). Cold path: import → validate → write cache.
+ *
+ * The cache key is `sha256(path + entry-mtime + VERSION)`, NOT a hash of the
+ * entry file's bytes. This means:
+ *   - editing the entry file bumps its mtime → new key → re-evaluation, in every
+ *     process (the byte-hash scheme missed nothing here, but see the limitation);
+ *   - a pragma upgrade bumps VERSION → new key → re-evaluation (a new binary must
+ *     never serve a config the old one cached).
+ *
+ * LIMITATION (accepted, per the review fold): a *transitively*-imported file
+ * (e.g. `./pkgs.ts`) edited without touching the entry's mtime is not detected
+ * across processes. The fix that would catch it — `bun build --bundle` the config
+ * and key on the bundle hash — is unavailable: Bun's bundler cannot run inside
+ * the `bun build --compile` binary (no source filesystem at `/$bunfs/root`), and
+ * bundling on every load would also blow the warm-load budget. Touch the entry
+ * (or bump VERSION) to force a rebuild.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { VERSION } from "../../constants.js";
+import { PragmaError } from "../error/PragmaError.js";
+import { configCacheDir } from "./paths.js";
+import { parseRawConfig } from "./schema.js";
+import type { RawConfig } from "./types.js";
+
+/** The cache file path for a given key. */
+function cachePathFor(key: string): string {
+  return join(configCacheDir(), `${key}.json`);
+}
+
+/**
+ * The cache key for a project-config file: `sha256(path + mtime + VERSION)`.
+ * Cheap to compute (a `stat`, not a full read) and threaded onto the import URL
+ * below so a long-lived process re-evaluates when the key changes.
+ */
+function cacheKey(path: string): string {
+  const { mtimeMs } = statSync(path);
+  return createHash("sha256")
+    .update(`${path}\u0000${mtimeMs}\u0000${VERSION}`)
+    .digest("hex");
+}
+
+/** Best-effort atomic write of the validated config to the cache. */
+function writeCache(cachePath: string, config: RawConfig): void {
+  try {
+    mkdirSync(configCacheDir(), { recursive: true });
+    const tempPath = `${cachePath}.tmp`;
+    writeFileSync(tempPath, JSON.stringify(config));
+    renameSync(tempPath, cachePath);
+  } catch {
+    // A read-only or racing cache is non-fatal — evaluation still returns.
+  }
+}
+
+/**
+ * Evaluate a project config file, serving a warm cache hit when possible.
+ *
+ * @param path - Absolute path to `pragma.config.{ts,js}`.
+ * @returns The validated raw config the file declares.
+ * @throws PragmaError with code `CONFIG_ERROR` when the evaluated shape is bad.
+ * @note Impure — reads the file, may import it, and writes the cache.
+ */
+export async function evaluateProjectConfig(path: string): Promise<RawConfig> {
+  const key = cacheKey(path);
+  const cachePath = cachePathFor(key);
+
+  try {
+    return JSON.parse(readFileSync(cachePath, "utf-8")) as RawConfig;
+  } catch {
+    // Cache miss — evaluate below.
+  }
+
+  // Cache-bust the dynamic import with the key so a long-lived process (the
+  // `mcp` server, which re-reads config per tool call) picks up an edited entry
+  // instead of a previously imported module. Node honours the query; under Bun
+  // the module cache is path-keyed and ignores it, but a fresh process always
+  // re-reads, so cross-process correctness holds regardless.
+  const url = `${pathToFileURL(path).href}?v=${key}`;
+  // Evaluating real TypeScript can throw for reasons `parseRawConfig` never sees:
+  // a syntax error, a bad import, or a top-level throw in the config module. Left
+  // unwrapped, that raw throw collapses to INTERNAL_ERROR ("please report this
+  // issue") on EVERY command that reads config. Name it: a CONFIG_ERROR that
+  // identifies the offending file and the underlying reason.
+  let module: { default?: unknown };
+  try {
+    module = (await import(url)) as { default?: unknown };
+  } catch (error) {
+    if (error instanceof PragmaError) throw error;
+    const reason = error instanceof Error ? error.message : String(error);
+    throw PragmaError.configError(
+      `Could not load project config ${path}: ${reason}`,
+      {
+        recovery: {
+          message:
+            "Fix the error in your pragma.config.ts (it must evaluate to a default export), then try again.",
+        },
+      },
+    );
+  }
+  const config = parseRawConfig(module.default, path);
+  writeCache(cachePath, config);
+  return config;
+}

package/src/kernel/config/findProjectConfig.ts

@@ -0,0 +1,45 @@
+/**
+ * Locate the nearest project config by walking up from `cwd`.
+ *
+ * Looks for `pragma.config.ts` (or, as a compiled-binary fallback,
+ * `pragma.config.js`) at or above `cwd`. The walk is bounded: it stops after
+ * the first directory containing `.git` (the repo root), after the home
+ * directory, and at the filesystem root — a config outside the repo or home
+ * never leaks in. Ported from the v1 `findProjectConfigPath`.
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/** Candidate project-config filenames, in preference order. */
+const CANDIDATES = ["pragma.config.ts", "pragma.config.js"] as const;
+
+/**
+ * Find the nearest project config file at or above `cwd`.
+ *
+ * @param cwd - Directory to start the walk from.
+ * @returns The absolute path of the nearest config, or `undefined`.
+ * @note Impure — probes the filesystem while walking up.
+ */
+export function findProjectConfig(cwd: string): string | undefined {
+  const home = homedir();
+  let dir = resolve(cwd);
+
+  while (true) {
+    for (const name of CANDIDATES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+    if (existsSync(join(dir, ".git")) || dir === home) {
+      return undefined;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}

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

@@ -0,0 +1,60 @@
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ensureFirstRun, firstRunTask } from "./firstRun.js";
+import { globalConfigPath } from "./paths.js";
+
+const originalConfigHome = process.env.XDG_CONFIG_HOME;
+
+function freshConfigHome(): void {
+  process.env.XDG_CONFIG_HOME = mkdtempSync(join(tmpdir(), "pragma-first-"));
+}
+
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = originalConfigHome;
+});
+
+describe("first run", () => {
+  it("greets on stderr and seeds the global config", async () => {
+    freshConfigHome();
+    const path = globalConfigPath();
+    const lines: string[] = [];
+
+    await ensureFirstRun((line) => lines.push(line));
+
+    expect(existsSync(path)).toBe(true);
+    expect(readFileSync(path, "utf-8")).toBe("{}\n");
+    expect(lines[0]).toContain("Hello!");
+    expect(lines.some((line) => line.includes(path))).toBe(true);
+    // Snapshot the note with the volatile path masked.
+    expect(
+      lines.map((line) => line.replace(path, "<CONFIG>")),
+    ).toMatchSnapshot();
+  });
+
+  it("is idempotent — no greeting when the config already exists", async () => {
+    freshConfigHome();
+    await ensureFirstRun(() => {});
+
+    const second: string[] = [];
+    await ensureFirstRun((line) => second.push(line));
+    expect(second).toEqual([]);
+
+    const task = firstRunTask();
+    expect(task).toBeDefined();
+  });
+
+  it("tolerates a creation failure with a single warning", async () => {
+    freshConfigHome();
+    // Make the pragma config directory path a file so mkdir fails.
+    writeFileSync(join(process.env.XDG_CONFIG_HOME as string, "pragma"), "x");
+    const lines: string[] = [];
+
+    await expect(
+      ensureFirstRun((line) => lines.push(line)),
+    ).resolves.toBeUndefined();
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain("Warning: could not create");
+  });
+});

package/src/kernel/config/firstRun.ts

@@ -0,0 +1,91 @@
+/**
+ * First-run onboarding — welcome note + global config creation.
+ *
+ * On the first invocation (detected by the absence of the global config file),
+ * greet on STDERR and seed `$XDG_CONFIG_HOME/pragma/config.json` with `{}` so
+ * every field keeps its built-in default and `config show` reports honest
+ * provenance. Modeled as a {@link Task} so the effects stay declarative and
+ * testable. The banner goes to stderr — stdout belongs to command output
+ * (`--format json`, MCP stdio) and must never be corrupted. Ported from the v1
+ * first-run pipeline; runs before dispatch and tolerates every failure.
+ */
+
+import { dirname } from "node:path";
+import {
+  $,
+  exists,
+  gen,
+  info,
+  mkdir,
+  type Task,
+  writeFile,
+} from "@canonical/task";
+import { runTask } from "@canonical/task/node";
+import { globalConfigPath } from "./paths.js";
+
+/** Seed content: an empty object, so nothing is pinned the user did not choose. */
+const SEED_CONFIG = "{}\n";
+
+/** Build the welcome note; the resolved path is shown so it is copyable. */
+function welcomeLines(path: string): string[] {
+  return [
+    "Hello! Thanks for taking the time to try the pre-release pragma CLI.",
+    "Please file issues and feedback at https://github.com/canonical/pragma/issues.",
+    `Pragma stores its configuration in ${path} (just created with defaults).`,
+    "A `pragma.config.ts` in this directory or above it overrides it per project.",
+    "",
+  ];
+}
+
+/**
+ * The first-run task: create the global config, announcing it on first run.
+ *
+ * @returns Task yielding whether the config was created and its path.
+ * @note Impure — checks/creates the global config file, emits log effects.
+ */
+export function firstRunTask(): Task<{ created: boolean; path: string }> {
+  return gen(function* () {
+    const path = globalConfigPath();
+
+    if (yield* $(exists(path))) {
+      return { created: false, path };
+    }
+
+    // Create first, then greet: if creation fails the effects throw before any
+    // line is emitted, so onboarding degrades to the single stderr warning
+    // rather than a "just created" banner alongside a failure.
+    yield* $(mkdir(dirname(path), true));
+    yield* $(writeFile(path, SEED_CONFIG));
+
+    for (const line of welcomeLines(path)) {
+      yield* $(info(line));
+    }
+
+    return { created: true, path };
+  });
+}
+
+/**
+ * Run the first-run task, tolerating every failure.
+ *
+ * Onboarding must never break an invocation: a read-only home or a race with a
+ * concurrent first run degrades to a single stderr warning and the invocation
+ * proceeds (the config layers treat a missing global file as defaults anyway).
+ *
+ * @param write - Stderr sink, injectable for tests.
+ * @note Impure — filesystem effects + stderr.
+ */
+export async function ensureFirstRun(
+  write: (line: string) => void = (line) => process.stderr.write(`${line}\n`),
+): Promise<void> {
+  try {
+    await runTask(firstRunTask(), {
+      // Route log effects to stderr without the interpreter's [INFO] prefix —
+      // this is a greeting, not diagnostics.
+      onLog: (_level, message) => write(message),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    write(`Warning: could not create the global pragma config — ${reason}`);
+  }
+}

package/src/kernel/config/globalConfig.ts

@@ -0,0 +1,94 @@
+/**
+ * Read the global machine config: `$XDG_CONFIG_HOME/pragma/config.json`.
+ *
+ * The global layer holds cross-project machine state (channel, detail, tier,
+ * prompts). A missing or empty file contributes no values — the layer simply
+ * does not participate in the merge. A *malformed* file (a torn write) must
+ * never brick every command (the old loud `CONFIG_ERROR` throw) nor be silently
+ * discarded (writeConfigField's old reset-to-`{}`): it is backed up to a
+ * timestamped sibling, reset to defaults, and a warning is written to stderr.
+ * A structurally *invalid* shape (valid JSON, wrong types) is still a real,
+ * fixable user error and surfaces as `CONFIG_ERROR` via {@link parseRawConfig}.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { globalConfigPath } from "./paths.js";
+import { parseRawConfig } from "./schema.js";
+import type { RawConfig } from "./types.js";
+
+/** A read of the global config layer. */
+export interface GlobalConfigRead {
+  readonly values: RawConfig;
+  readonly exists: boolean;
+  readonly path: string;
+}
+
+/**
+ * The timestamped sibling path a corrupt config is backed up to before it is
+ * reset — shared by the read (this module) and write (writeConfigField) paths
+ * so both name the backup identically.
+ *
+ * @param path - The config file path being recovered.
+ * @returns `<path>.corrupt-<ISO timestamp>`.
+ */
+export function corruptBackupPath(path: string): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return `${path}.corrupt-${stamp}`;
+}
+
+/**
+ * Recover from a corrupt (unparseable) global config: back the file up, reset it
+ * to defaults, and warn on stderr. Best-effort — a read-only config dir degrades
+ * to defaults without a backup but still warns. Never throws.
+ *
+ * @param path - The corrupt config file path.
+ * @param raw - Its unparseable contents, preserved in the backup.
+ * @note Impure — writes the backup + reset file and to stderr.
+ */
+function recoverCorruptGlobalConfig(path: string, raw: string): void {
+  const backup = corruptBackupPath(path);
+  try {
+    writeFileSync(backup, raw);
+    writeFileSync(path, "{}\n");
+    process.stderr.write(
+      `Warning: ${path} is not valid JSON. Backed it up to ${backup} and reset it to defaults.\n`,
+    );
+  } catch {
+    process.stderr.write(
+      `Warning: ${path} is not valid JSON; using built-in defaults.\n`,
+    );
+  }
+}
+
+/**
+ * Read and validate the global config file.
+ *
+ * @returns The declared values, whether the file exists, and its path.
+ * @throws PragmaError with code `CONFIG_ERROR` when the JSON is valid but its
+ *   shape is not (malformed JSON is recovered, not thrown).
+ * @note Impure — reads the filesystem (and may recover a corrupt file).
+ */
+export function readGlobalConfig(): GlobalConfigRead {
+  const path = globalConfigPath();
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return { values: {}, exists: false, path };
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    return { values: {}, exists: true, path };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    recoverCorruptGlobalConfig(path, raw);
+    return { values: {}, exists: true, path };
+  }
+
+  return { values: parseRawConfig(parsed, path), exists: true, path };
+}

package/src/kernel/config/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Config kernel barrel — layered TS-evaluated configuration.
+ *
+ * `schema.ts` (zod) is intentionally not re-exported here: it is imported
+ * directly and lazily by the readers, keeping this barrel — and any storeless
+ * consumer — off the zod fast path.
+ */
+
+export { default as defaults } from "./defaults.js";
+export { evaluateProjectConfig } from "./evaluateProjectConfig.js";
+export { findProjectConfig } from "./findProjectConfig.js";
+export { ensureFirstRun, firstRunTask } from "./firstRun.js";
+export type { GlobalConfigRead } from "./globalConfig.js";
+export { readGlobalConfig } from "./globalConfig.js";
+export {
+  cacheDir,
+  configCacheDir,
+  configDir,
+  globalConfigPath,
+  stateDir,
+} from "./paths.js";
+export { readConfig } from "./readConfig.js";
+export type {
+  Channel,
+  ConfigLayer,
+  ConfigLayers,
+  ConfigOrigin,
+  ConfigOrigins,
+  PackageDeclaration,
+  PackageEntry,
+  PragmaConfig,
+  RawConfig,
+} from "./types.js";
+export type { WriteConfigResult } from "./writeConfigField.js";
+export { writeConfigField } from "./writeConfigField.js";

package/src/kernel/config/paths.ts

@@ -0,0 +1,39 @@
+/**
+ * XDG base-directory resolution for config, cache, and state.
+ *
+ * Config (the global JSON) lives under `$XDG_CONFIG_HOME/pragma`; the evaluated
+ * project-config cache lives under `$XDG_STATE_HOME/pragma/config-cache`. Tests
+ * point these env vars at per-run temp directories (see setupXdgIsolation) so
+ * they never touch the developer's real state.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** `$XDG_CONFIG_HOME/pragma` (default `~/.config/pragma`). */
+export function configDir(): string {
+  const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  return join(base, "pragma");
+}
+
+/** `$XDG_CACHE_HOME/pragma` (default `~/.cache/pragma`). */
+export function cacheDir(): string {
+  const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+  return join(base, "pragma");
+}
+
+/** `$XDG_STATE_HOME/pragma` (default `~/.local/state/pragma`). */
+export function stateDir(): string {
+  const base = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+  return join(base, "pragma");
+}
+
+/** The global config file: `$XDG_CONFIG_HOME/pragma/config.json`. */
+export function globalConfigPath(): string {
+  return join(configDir(), "config.json");
+}
+
+/** The evaluated-project-config cache dir: `$XDG_STATE_HOME/pragma/config-cache`. */
+export function configCacheDir(): string {
+  return join(stateDir(), "config-cache");
+}