@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/pipeline/rootHelp.ts

@@ -0,0 +1,265 @@
+/**
+ * Curated root `--help` for `pragma`.
+ *
+ * cli-core's generic `formatHelp` derives a description per top-level noun from
+ * its commands, but noun groups that only have verbs (e.g. `block list`) have
+ * no command to carry one — so it emits placeholder text like "block commands".
+ * The root help is also the CLI's front door, so its content and grouping are
+ * worth hand-curating here rather than auto-generating.
+ *
+ * This renderer:
+ * - groups nouns into task-oriented sections with real one-line summaries,
+ * - derives each section's live nouns from the registered commands (so a noun
+ *   that disappears is dropped, and a new, uncatalogued one still shows up
+ *   under "Other" instead of vanishing),
+ * - expands `create` to show its scaffolding subtypes, including the component
+ *   frameworks pulled straight from the command's parameter choices.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import chalk from "chalk";
+
+interface NounSummary {
+  readonly noun: string;
+  readonly summary: string;
+}
+
+interface HelpGroup {
+  readonly title: string;
+  readonly nouns: readonly NounSummary[];
+}
+
+/**
+ * Task-oriented grouping with curated summaries. Order is intentional: the
+ * things people reach for most (exploring the system, generating code) come
+ * first; agent/integration tooling comes last.
+ */
+const HELP_GROUPS: readonly HelpGroup[] = [
+  {
+    title: "Explore the design system",
+    nouns: [
+      {
+        noun: "block",
+        summary: "Inspect components & patterns and their anatomy",
+      },
+      { noun: "token", summary: "Look up design tokens and their values" },
+      { noun: "modifier", summary: "Inspect modifiers and modifier families" },
+      { noun: "standard", summary: "Browse code standards and categories" },
+      {
+        noun: "ontology",
+        summary: "Explore the loaded ontologies (classes, properties)",
+      },
+      { noun: "tier", summary: "List the design-system tiers" },
+    ],
+  },
+  {
+    title: "Generate code",
+    nouns: [
+      { noun: "create", summary: "Scaffold components, packages, and apps" },
+    ],
+  },
+  {
+    title: "Query & serve the graph",
+    nouns: [
+      {
+        noun: "graph",
+        summary: "Run SPARQL queries or inspect a URI directly",
+      },
+      {
+        noun: "graphql",
+        summary: "Compile and serve a GraphQL API over the ontologies",
+      },
+    ],
+  },
+  {
+    title: "Set up & maintain",
+    nouns: [
+      { noun: "doctor", summary: "Check environment health" },
+      {
+        noun: "setup",
+        summary: "Configure MCP, skills, completions, and the LSP",
+      },
+      { noun: "config", summary: "Read and write pragma.config.json" },
+      { noun: "tokens", summary: "Generate a Terrazzo tokens config" },
+      {
+        noun: "info",
+        summary: "Show version, config, update status, and store summary",
+      },
+      {
+        noun: "upgrade",
+        summary: "Upgrade the pragma CLI to the latest version",
+      },
+    ],
+  },
+  {
+    title: "For AI agents",
+    nouns: [
+      {
+        noun: "capabilities",
+        summary: "Discover conventions, tools, and the discovery sequence",
+      },
+      {
+        noun: "llm",
+        summary: "LLM orientation: context, decision trees, command reference",
+      },
+      { noun: "mcp", summary: "Start the MCP server over stdio" },
+      {
+        noun: "skill",
+        summary: "Browse agent skills from design-system packages",
+      },
+    ],
+  },
+];
+
+/** All distinct top-level nouns present in the registered commands. */
+function nounsFrom(commands: readonly CommandDefinition[]): Set<string> {
+  const nouns = new Set<string>();
+  for (const cmd of commands) {
+    const noun = cmd.path[0];
+    if (noun) nouns.add(noun);
+  }
+  return nouns;
+}
+
+/** The verbs (second path segment) registered under a noun, in order. */
+function verbsOf(
+  noun: string,
+  commands: readonly CommandDefinition[],
+): CommandDefinition[] {
+  return commands.filter((c) => c.path[0] === noun && c.path.length > 1);
+}
+
+/**
+ * The framework values offered by `create component`, e.g. `react · svelte ·
+ * lit`, read from the command's `framework` parameter choices so the help
+ * can never drift from what the generator actually accepts.
+ */
+function componentFrameworks(
+  commands: readonly CommandDefinition[],
+): string | undefined {
+  const component = commands.find(
+    (c) => c.path[0] === "create" && c.path[1] === "component",
+  );
+  const choices = component?.parameters.find(
+    (p) => p.name === "framework",
+  )?.choices;
+  if (!choices || choices.length === 0) return undefined;
+  return choices.map((c) => c.label).join(" · ");
+}
+
+/** Render the `create` subtypes as indented sub-lines. */
+function createSubtypes(
+  commands: readonly CommandDefinition[],
+  subWidth: number,
+): string[] {
+  const lines: string[] = [];
+  const frameworks = componentFrameworks(commands);
+  for (const verb of verbsOf("create", commands)) {
+    const name = verb.path[1] as string;
+    const note =
+      name === "component" && frameworks
+        ? frameworks
+        : name === "package"
+          ? "a new package for the monorepo"
+          : verb.description;
+    lines.push(
+      `      ${chalk.dim("·")} ${chalk.cyan(name.padEnd(subWidth))}  ${chalk.dim(note)}`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * Build the curated root help string.
+ *
+ * @param programName - The CLI binary name (`pragma`).
+ * @param description - The program description shown in the header.
+ * @param commands - All registered command definitions.
+ * @returns The formatted, colorized help text.
+ */
+export default function formatRootHelp(
+  programName: string,
+  description: string,
+  commands: readonly CommandDefinition[],
+): string {
+  const present = nounsFrom(commands);
+  // `mcp` is attached to Commander directly (not via the command list), but is
+  // always available — surface it so the front door is complete.
+  present.add("mcp");
+  const catalogued = new Set(
+    HELP_GROUPS.flatMap((g) => g.nouns.map((n) => n.noun)),
+  );
+
+  // Any live noun we didn't curate is surfaced so nothing silently disappears.
+  const uncatalogued = [...present].filter((n) => !catalogued.has(n)).sort();
+  const groups: HelpGroup[] = [
+    ...HELP_GROUPS.map((g) => ({
+      ...g,
+      nouns: g.nouns.filter((n) => present.has(n.noun)),
+    })),
+    ...(uncatalogued.length > 0
+      ? [
+          {
+            title: "Other",
+            nouns: uncatalogued.map((noun) => ({
+              noun,
+              summary:
+                verbsOf(noun, commands)[0]?.description ?? `${noun} commands`,
+            })),
+          },
+        ]
+      : []),
+  ].filter((g) => g.nouns.length > 0);
+
+  // One shared column width so summaries line up across every group.
+  const nounWidth = Math.max(
+    ...groups.flatMap((g) => g.nouns.map((n) => n.noun.length)),
+    0,
+  );
+  const subWidth = Math.max(
+    ...verbsOf("create", commands).map((v) => (v.path[1] as string).length),
+    0,
+  );
+
+  const lines: string[] = [
+    `${chalk.bold(programName)} — ${description}`,
+    "",
+    `${chalk.dim("Usage:")} ${programName} ${chalk.cyan("<command>")} ${chalk.dim("[subcommand] [flags]")}`,
+    "",
+  ];
+
+  for (const group of groups) {
+    lines.push(chalk.bold(group.title));
+    for (const { noun, summary } of group.nouns) {
+      lines.push(
+        `  ${chalk.cyan(noun.padEnd(nounWidth))}  ${chalk.dim(summary)}`,
+      );
+      if (noun === "create") {
+        lines.push(...createSubtypes(commands, subWidth));
+      }
+    }
+    lines.push("");
+  }
+
+  lines.push(chalk.bold("Global flags"));
+  const flags: [string, string][] = [
+    ["--llm", "Condensed Markdown output for agents"],
+    ["--format json", "Machine-readable JSON output"],
+    ["--verbose", "Diagnostic output on stderr"],
+    ["--help", "Show help (works on any command)"],
+    ["--version", "Show the CLI version"],
+  ];
+  const flagWidth = Math.max(...flags.map(([f]) => f.length));
+  for (const [flag, desc] of flags) {
+    lines.push(`  ${chalk.cyan(flag.padEnd(flagWidth))}  ${chalk.dim(desc)}`);
+  }
+  lines.push("");
+
+  lines.push(
+    chalk.dim(
+      `Run \`${programName} <command> --help\` for details, or \`${programName} capabilities\` to get oriented.`,
+    ),
+  );
+
+  return lines.join("\n");
+}

package/src/pipeline/runCli.orchestration.test.ts

@@ -33,6 +33,7 @@ vi.mock("./mapExitCode.js", () => ({
 vi.mock("./parseGlobalFlags.js", () => ({
   default: parseGlobalFlagsMock,
   stripGlobalFlags: (argv: readonly string[]) => [...argv],
+  readRawFormat: () => undefined,
 }));
 
 vi.mock("./resolveCommandKind.js", () => ({
@@ -109,10 +110,14 @@ describe("runCli orchestration", () => {
     collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
     createProgramMock.mockReturnValue({ parseAsync });
 
+    // Completion queries are classified before the root-help shortcut, so
+    // resolveCommandKind runs first; a non-completion result still falls
+    // through to root help without booting the store.
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+
     const { default: runCli } = await import("./runCli.js");
     await runCli(["node", "pragma", "--verbose"]);
 
-    expect(resolveCommandKindMock).not.toHaveBeenCalled();
     expect(bootPragmaMock).not.toHaveBeenCalled();
     expect(parseAsync).toHaveBeenCalledWith(["node", "pragma", "--help"]);
   });
@@ -257,19 +262,30 @@ describe("runCli orchestration", () => {
     expect(dispose).toHaveBeenCalledTimes(1);
   });
 
-  it("treats version commander errors as success", async () => {
-    const parseAsync = vi.fn(async () => {
-      throw new CommanderError(0, "commander.version", "version");
-    });
+  it("prints the version directly and never reaches the program", async () => {
+    // --version is a global flag handled before command dispatch, so it neither
+    // boots the store nor builds a Commander program.
+    const stdout: string[] = [];
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((chunk) => {
+        stdout.push(String(chunk));
+        return true;
+      });
 
     resolveCommandKindMock.mockReturnValue({ kind: "store-skip" });
-    setupCommandsMock.mockReturnValue([{ path: ["setup", "skills"] }]);
-    createProgramMock.mockReturnValue({ parseAsync });
-
-    const { default: runCli } = await import("./runCli.js");
-    await runCli(["node", "pragma", "--version"]);
-
-    expect(process.exitCode).toBe(0);
+    createProgramMock.mockClear();
+
+    try {
+      const { default: runCli } = await import("./runCli.js");
+      await runCli(["node", "pragma", "--version"]);
+    } finally {
+      stdoutSpy.mockRestore();
+    }
+
+    expect(stdout.join("")).toContain(".");
+    expect(createProgramMock).not.toHaveBeenCalled();
+    expect(process.exitCode).toBeUndefined();
   });
 
   it("renders pragma errors from the program using mapped exit codes", async () => {

package/src/pipeline/runCli.test.ts

@@ -4,9 +4,17 @@ import createProgram from "./createProgram.js";
 import parseGlobalFlags from "./parseGlobalFlags.js";
 
 describe("parseGlobalFlags", () => {
-  it("parses defaults", () => {
-    const flags = parseGlobalFlags(["node", "pragma"]);
-    expect(flags).toEqual({ llm: false, format: "text", verbose: false });
+  it("parses defaults on an interactive terminal", () => {
+    const flags = parseGlobalFlags(["node", "pragma"], {
+      isTty: true,
+      noAutoLlm: false,
+    });
+    expect(flags).toEqual({
+      llm: false,
+      autoLlm: false,
+      format: "text",
+      verbose: false,
+    });
   });
 
   it("parses --llm", () => {
@@ -33,7 +41,12 @@ describe("parseGlobalFlags", () => {
       "json",
       "--verbose",
     ]);
-    expect(flags).toEqual({ llm: true, format: "json", verbose: true });
+    expect(flags).toEqual({
+      llm: true,
+      autoLlm: false,
+      format: "json",
+      verbose: true,
+    });
   });
 });
 

package/src/pipeline/runCli.ts

@@ -1,5 +1,7 @@
 import type { GlobalFlags } from "@canonical/cli-core";
 import { CommanderError } from "commander";
+import { PROGRAM_NAME, VERSION } from "../constants.js";
+import { commands as createCommands } from "../domains/create/index.js";
 import { commands as graphqlCommands } from "../domains/graphql/index.js";
 import { buildCapabilitiesCommand } from "../domains/llm/index.js";
 import { commands as refsCommands } from "../domains/refs/index.js";
@@ -12,8 +14,12 @@ import { commands as traceCommands } from "../domains/trace/index.js";
 import { PragmaError } from "../error/index.js";
 import collectCommands from "./collectCommands.js";
 import createProgram from "./createProgram.js";
+import ensureFirstRun from "./firstRun.js";
 import mapExitCode from "./mapExitCode.js";
-import parseGlobalFlags, { stripGlobalFlags } from "./parseGlobalFlags.js";
+import parseGlobalFlags, {
+  readRawFormat,
+  stripGlobalFlags,
+} from "./parseGlobalFlags.js";
 import {
   renderErrorJson,
   renderErrorLlm,
@@ -67,8 +73,23 @@ async function handleCompletionsServer(): Promise<void> {
   await startCompletionsServer();
 }
 
-async function handleDoctor(globalFlags: GlobalFlags): Promise<void> {
+async function handleDoctor(
+  argv: readonly string[],
+  globalFlags: GlobalFlags,
+): Promise<void> {
   const { doctorCommand } = await import("../domains/doctor/commands/index.js");
+
+  // `doctor` runs before Commander, so honour --help/-h here rather than
+  // executing the health check when the user only asked for usage.
+  const wantsHelp = argv
+    .slice(2)
+    .some((arg) => arg === "--help" || arg === "-h");
+  if (wantsHelp) {
+    const { formatVerbHelp } = await import("@canonical/cli-core");
+    process.stdout.write(`${formatVerbHelp(PROGRAM_NAME, doctorCommand)}\n`);
+    return;
+  }
+
   const ctx = { cwd: process.cwd(), globalFlags };
   const result = await doctorCommand.execute({}, ctx);
   if (result.tag === "output") {
@@ -91,7 +112,7 @@ async function handleRootHelp(globalFlags: GlobalFlags): Promise<void> {
   try {
     await program.parseAsync(["node", "pragma", "--help"]);
   } catch (err) {
-    handleProgramError(err, globalFlags);
+    await handleProgramError(err, globalFlags, ["node", "pragma", "--help"]);
   }
 }
 
@@ -151,6 +172,8 @@ async function bootAndRun(
     return;
   }
 
+  await emitSchemaArtifact(runtime, globalFlags);
+
   try {
     const ctx: PragmaContext = {
       ...runtime,
@@ -161,12 +184,48 @@ async function bootAndRun(
     const program = createProgram(commands, ctx);
     await program.parseAsync(stripGlobalFlags(argv));
   } catch (err) {
-    handleProgramError(err, globalFlags);
+    await handleProgramError(err, globalFlags, argv);
   } finally {
     runtime.dispose();
   }
 }
 
+/**
+ * Keep the `schema.graphql` artifact current on every booted run.
+ *
+ * The freshness probe is a source hash against the artifact's header, so
+ * the common case costs one hash + one small read; compilation runs only
+ * when the resolved TTL sources actually changed (or on first use).
+ * Never fatal — a failed compile warns and the command proceeds.
+ */
+async function emitSchemaArtifact(
+  runtime: PragmaRuntime,
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  try {
+    const { ensureSchemaArtifact } = await import(
+      "../domains/graphql/operations/index.js"
+    );
+    const result = await ensureSchemaArtifact(runtime);
+    if (result.status === "written") {
+      process.stderr.write(
+        `Updated GraphQL schema artifact (sources changed): ${result.path}\n`,
+      );
+    } else if (result.status === "failed" && globalFlags.verbose) {
+      process.stderr.write(
+        `Warning: GraphQL schema compilation failed; ${result.path} not updated. Run \`pragma graphql check\` for diagnostics.\n`,
+      );
+    }
+  } catch (err) {
+    if (globalFlags.verbose) {
+      const reason = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        `Warning: could not update GraphQL schema artifact: ${reason}\n`,
+      );
+    }
+  }
+}
+
 async function runStoreSkip(
   argv: readonly string[],
   globalFlags: GlobalFlags,
@@ -185,6 +244,7 @@ async function runStoreSkip(
     ...refsCommands(),
     ...traceCommands(),
     ...graphqlCommands(),
+    ...createCommands(),
     buildCapabilitiesCommand(),
   ];
   const program = createProgram(commands, stubCtx);
@@ -192,11 +252,53 @@ async function runStoreSkip(
   try {
     await program.parseAsync(stripGlobalFlags(argv));
   } catch (err) {
-    handleProgramError(err, globalFlags);
+    await handleProgramError(err, globalFlags, argv);
   }
 }
 
-function handleProgramError(err: unknown, globalFlags: GlobalFlags): void {
+/**
+ * First non-flag token in argv — the command noun, if any.
+ *
+ * Global flags are stripped first so a flag *value* (e.g. the `json` in
+ * `--format json`) is never mistaken for the noun; otherwise
+ * `pragma --format json standard frobnicate` would scan `json` and fail to
+ * suggest `standard`'s verbs.
+ */
+function findNoun(argv: readonly string[]): string | undefined {
+  return stripGlobalFlags(argv)
+    .slice(2)
+    .find((arg) => !arg.startsWith("-"));
+}
+
+/**
+ * When an unknown command/verb is entered under a known noun, print that noun's
+ * valid verbs so the user can recover — "defer to the category that exists".
+ *
+ * @note Impure — writes the noun's verb list to stderr.
+ */
+async function suggestNounVerbs(argv: readonly string[]): Promise<void> {
+  const noun = findNoun(argv);
+  if (!noun) return;
+  const stubCtx: PragmaContext = {
+    store: {} as PragmaRuntime["store"],
+    ...(await resolveHelpConfig()),
+    cwd: process.cwd(),
+    dispose: () => {},
+    globalFlags: { llm: false, autoLlm: false, format: "text", verbose: false },
+    promptSession: createInteractivePromptSession,
+  };
+  const commands = collectCommands(stubCtx);
+  const hasNoun = commands.some((cmd) => cmd.path.at(0) === noun);
+  if (!hasNoun) return;
+  const { formatNounHelp } = await import("@canonical/cli-core");
+  process.stderr.write(`\n${formatNounHelp(PROGRAM_NAME, noun, commands)}\n`);
+}
+
+async function handleProgramError(
+  err: unknown,
+  globalFlags: GlobalFlags,
+  argv: readonly string[],
+): Promise<void> {
   if (err instanceof CommanderError) {
     if (
       err.code === "commander.helpDisplayed" ||
@@ -205,6 +307,9 @@ function handleProgramError(err: unknown, globalFlags: GlobalFlags): void {
       process.exitCode = 0;
       return;
     }
+    if (err.code === "commander.unknownCommand") {
+      await suggestNounVerbs(argv);
+    }
     process.exitCode = err.exitCode;
     return;
   }
@@ -240,26 +345,64 @@ function handleProgramError(err: unknown, globalFlags: GlobalFlags): void {
  */
 export default async function runCli(argv: readonly string[]): Promise<void> {
   const globalFlags = parseGlobalFlags(argv);
-  const explicitHelpOrVersion = argv
+
+  const commandKind = resolveCommandKind(argv);
+
+  // Completion queries must be handled before the root-help shortcut:
+  // `pragma --completions` (empty first-Tab partial) has no non-flag command
+  // arg, so it would otherwise fall through to root help and dump the help
+  // banner into the shell's completion buffer.
+  if (commandKind.kind === "completions-client") {
+    return handleCompletionsClient(commandKind.partial);
+  }
+  if (commandKind.kind === "completions-server") {
+    return handleCompletionsServer();
+  }
+
+  // First-run onboarding: when the global config does not exist yet, greet on
+  // stderr and create it with defaults. After the completions early-exits so
+  // the note can never leak into a shell completion buffer; stderr-only so
+  // stdout (command output, --format json, MCP stdio) stays untouched; and
+  // failure-tolerant — onboarding must never break an invocation.
+  await ensureFirstRun();
+
+  // `--version`/`-V` is a global flag: print the version and exit regardless
+  // of where it appears (root or after a command/verb), so `block list -V`
+  // behaves like the root `pragma --version` instead of erroring.
+  if (argv.slice(2).some((arg) => arg === "--version" || arg === "-V")) {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  const explicitHelp = argv
     .slice(2)
-    .some(
-      (arg) =>
-        arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V",
-    );
+    .some((arg) => arg === "--help" || arg === "-h");
 
-  if (!hasCommandArg(argv) && !explicitHelpOrVersion) {
-    return handleRootHelp(globalFlags);
+  // Reject an unknown --format value early (completion queries and --version
+  // are handled above, so neither errors). Skip when the user asked for help —
+  // it should print regardless of a bad --format. Only text/json are supported.
+  const rawFormat = readRawFormat(argv);
+  if (
+    !explicitHelp &&
+    rawFormat !== undefined &&
+    rawFormat !== "text" &&
+    rawFormat !== "json"
+  ) {
+    const error = PragmaError.invalidInput("format", rawFormat, {
+      validOptions: ["text", "json"],
+    });
+    process.stderr.write(`${renderError(error, globalFlags)}\n`);
+    process.exitCode = mapExitCode(error.code);
+    return;
   }
 
-  const commandKind = resolveCommandKind(argv);
+  if (!hasCommandArg(argv) && !explicitHelp) {
+    return handleRootHelp(globalFlags);
+  }
 
   switch (commandKind.kind) {
-    case "completions-client":
-      return handleCompletionsClient(commandKind.partial);
-    case "completions-server":
-      return handleCompletionsServer();
     case "doctor":
-      return handleDoctor(globalFlags);
+      return handleDoctor(argv, globalFlags);
     case "store-skip":
       return runStoreSkip(argv, globalFlags);
     case "store-required":

package/src/testing/cli.ts

@@ -6,7 +6,9 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { resolve } from "node:path";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 
 /** Captured output from a CLI subprocess invocation. */
 interface CommandResult {
@@ -15,21 +17,47 @@ interface CommandResult {
   exitCode: number;
 }
 
+/**
+ * XDG home whose global config already exists, shared by all default
+ * invocations in this file's worker.
+ *
+ * Subprocesses would otherwise trigger the first-run greeting in whichever
+ * test happens to spawn first (the setup-file XDG is fresh per file), making
+ * stderr assertions ordering-dependent. Seeding the config keeps every
+ * default `runCommand` past first-run; tests that WANT the first-run path
+ * pass their own fresh XDG via `env`.
+ */
+let seededXdg: string | undefined;
+function seededXdgHome(): string {
+  if (!seededXdg) {
+    seededXdg = mkdtempSync(join(tmpdir(), "pragma-cli-xdg-"));
+    mkdirSync(join(seededXdg, "pragma"), { recursive: true });
+    writeFileSync(join(seededXdg, "pragma", "config.json"), "{}\n");
+  }
+  return seededXdg;
+}
+
 /**
  * Spawn the pragma CLI binary synchronously and capture its output.
  *
  * @param args - CLI arguments to pass after the binary path.
  * @param cwd - Optional working directory for the subprocess.
+ * @param env - Extra environment overrides (merged over the seeded default).
  * @returns Captured stdout, stderr, and exit code.
  *
  * @note Impure
  */
-function runCommand(args: string[], cwd?: string): CommandResult {
+function runCommand(
+  args: string[],
+  cwd?: string,
+  env?: Record<string, string>,
+): CommandResult {
   const binPath = resolve(import.meta.dirname, "../bin.ts");
   const result = spawnSync("bun", ["run", binPath, ...args], {
     cwd,
     encoding: "utf-8",
     timeout: 20_000,
+    env: { ...process.env, XDG_CONFIG_HOME: seededXdgHome(), ...env },
   });
 
   return {