@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/completion/templates/fish.ts

@@ -8,7 +8,9 @@
  * via a command substitution — fish treats substitution results as literal
  * candidates (split on newlines, never evaluated). Each name rule ANDs a
  * `__<bin>_minchars` guard into its condition, so the exec waits for `minChars`
- * typed chars. No `eval`, no backticks.
+ * typed chars, and a name-source POSITIONAL also ANDs `__<bin>_notflag` — fish
+ * evaluates every matching rule rather than one exclusive branch, so without it
+ * a structural `--<TAB>` would spawn the delegate too. No `eval`, no backticks.
  *
  * Static-tier coarseness (the resolver is exact): positional value rules are
  * not index-gated, and a mixed self-verb + sub-verb noun only offers its
@@ -23,6 +25,11 @@ function fnBase(binName: string): string {
   return `__${binName.replace(/[^A-Za-z0-9_]/g, "_")}`;
 }
 
+/** AND a guard into a rule's condition (or start one with it). */
+function and(condition: string | undefined, guard: string): string {
+  return condition ? `${condition}; and ${guard}` : guard;
+}
+
 /** AND a `minChars` guard into a name rule's condition (or start one). */
 function withMinChars(
   fn: string,
@@ -30,8 +37,7 @@ function withMinChars(
   minChars: number,
 ): string | undefined {
   if (minChars <= 0) return condition;
-  const guard = `${fn}_minchars ${minChars}`;
-  return condition ? `${condition}; and ${guard}` : guard;
+  return and(condition, `${fn}_minchars ${minChars}`);
 }
 
 /** The rule fragment completing one flag of a view (or a global flag). */
@@ -93,9 +99,20 @@ function positionalRule(
     if (positional.source.kind === "names") names = true;
     if (positional.source.kind === "files") files = true;
   }
-  // A name source gates its exec on `minChars`; a values/files positional keeps
-  // the bare position condition so it still completes on bare TAB.
-  const cond = names ? withMinChars(fn, condition, minChars) : condition;
+  // A name source gates its exec on `minChars` AND on the current token not
+  // being a flag; a values/files positional keeps the bare position condition
+  // so it still completes on bare TAB.
+  //
+  // The `_notflag` half is what keeps a purely STRUCTURAL `--<TAB>` free of
+  // exec. fish evaluates every `complete` rule matching a position, so without
+  // it this positional rule fires alongside the flag-name rules the moment the
+  // token clears `minChars` — and `--` is two characters. That cost a process
+  // spawn per TAB on a flag name AND put the delegate's answer in the user's
+  // candidate list. bash and zsh route the same context through one exclusive
+  // `case` arm and exec nothing; this is how fish joins them.
+  const cond = names
+    ? withMinChars(fn, and(condition, `${fn}_notflag`), minChars)
+    : condition;
   const parts = [`complete -c ${binName} -n "${cond}"`];
   if (names) {
     parts.push(`-a "(${binName} __complete -- (${fn}_words) 2>/dev/null)"`);
@@ -147,6 +164,11 @@ export function fishScript(
           "end",
         ]
       : []),
+    // True when the token being completed is not a flag, so a name-source
+    // positional rule stays out of a structural `--<TAB>`.
+    `function ${fn}_notflag`,
+    "    not string match -q -- '-*' (commandline -ct)",
+    "end",
     `function ${fn}_at`,
     "    set -l cmd (commandline -opc)",
     "    set -l noun ''",

package/src/kernel/completion/templates/index.ts

@@ -0,0 +1,23 @@
+/**
+ * The static shell-completion templates — one emitter per shell, all fed by
+ * the same completion model.
+ *
+ * The three exports are the domain: each takes the model and returns the text
+ * of a script `setup completions` writes to disk. They are grouped because
+ * they are interchangeable answers to one question — which shell is this — and
+ * because they must stay in step: a fact the model carries has to be
+ * expressible in all three, so a change to one is a change to all three.
+ *
+ * What the barrel does NOT expose is the rendering layer underneath
+ * (`shared.ts`): the per-verb views, the token allowlist re-assertion, the
+ * name/flag list derivations. Those exist so the scripts cannot disagree about
+ * structure, and they are safe only in the emit context they were built for —
+ * every token they return has been re-checked against the safety allowlist on
+ * its way into script text. Offering them across the domain boundary would
+ * offer a way to compose that text without that check, which is the one thing
+ * this domain exists to make impossible.
+ */
+
+export { bashScript } from "./bash.js";
+export { fishScript } from "./fish.js";
+export { zshScript } from "./zsh.js";

package/src/kernel/completion/types.ts

@@ -26,7 +26,7 @@ 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
+   * Names of a storeless source (index/skills/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.
    */
@@ -77,6 +77,13 @@ export interface VerbEntry {
   readonly flags: readonly FlagEntry[];
   /** The verb's positionals, in declared order. */
   readonly positionals: readonly PositionalEntry[];
+  /**
+   * Segment pseudo-verbs beneath this verb (a module-mounted subtree, from
+   * `CapabilityModule.cliProjection.completionChildren`), each with its own
+   * flags/positionals/children. The parse walk descends into a matching
+   * child before flag/positional resolution.
+   */
+  readonly children?: readonly VerbEntry[];
 }
 
 /** One noun with its self-verb (if any) and sub-verbs. */
@@ -135,8 +142,8 @@ export interface CompletionRequest {
 
 /**
  * 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
+ * One source-dispatched reader serves every family — index, skills, 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.

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

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import defaults from "./defaults.js";
+
+describe("defaults — the validated distribution config (pragma.conf.ts)", () => {
+  it("ships the distribution identity", () => {
+    expect(defaults.name).toBe("pragma");
+    expect(defaults.help).toBe("Explore the design system");
+    expect(defaults.issuesUrl).toBe(
+      "https://github.com/canonical/pragma/issues",
+    );
+  });
+
+  it("declares the toolchain colophon as content (markdown body + summary)", () => {
+    // The narrative is a DECLARATION the `colophon` verb renders, not code:
+    // `collectColophon` reads exactly this object. Pin the shape and the two
+    // stable fragments — the story's own subject and the maker line the old
+    // one-line `colophon` string carried (folded in when the field went live).
+    //
+    // DOMAIN FIRST: this section is deliberately a one-liner that hands off to
+    // `docs/architecture.md`. `pragma colophon` renders it ABOVE the active
+    // pack's domain colophon, and a reader reaching for the colophon wants the
+    // design system, not the toolchain that serves it. The length pin is the
+    // ruling: architecture prose belongs in the docs, not in front of the
+    // domain every reader came for.
+    expect(defaults.colophon?.markdown).toContain("domain-based toolchain");
+    expect(defaults.colophon?.markdown).toContain(
+      "Made by the Canonical Webteam — https://canonical.com.",
+    );
+    expect(defaults.colophon?.summary).toContain("domain-based toolchain");
+    // Bodies, not documents: the renderer supplies the H1 from the name.
+    expect(defaults.colophon?.markdown.startsWith("#")).toBe(false);
+    expect(defaults.colophon?.summary?.startsWith("#")).toBe(false);
+    // The handoff, and the brevity that makes it honest (see the note above).
+    // It is a URL, not a repo path: `docs/` is outside the package's `files`
+    // allowlist and is not copied into `dist`, so a path would name a file no
+    // installed user has. A bare `docs/architecture.md` must fail here.
+    expect(defaults.colophon?.markdown).toContain(
+      "https://github.com/canonical/pragma/blob/main/packages/cli/pragma/docs/architecture.md",
+    );
+    expect(defaults.colophon?.summary).toContain(
+      "https://github.com/canonical/pragma/blob/main/packages/cli/pragma/docs/architecture.md",
+    );
+    expect(defaults.colophon?.markdown.length).toBeLessThan(400);
+    expect(defaults.colophon?.summary?.length).toBeLessThan(400);
+  });
+
+  it("ships the four canonical default packs (git+https sources)", () => {
+    expect(
+      defaults.packs?.map((pack) =>
+        typeof pack === "string"
+          ? pack
+          : { name: pack.name, source: pack.source },
+      ),
+    ).toEqual([
+      {
+        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",
+      },
+      {
+        name: "@canonical/ds-implementations",
+        source: "git+https://github.com/canonical/pragma.git#main",
+      },
+    ]);
+  });
+
+  it("carries the declared read stories through validation, on their packs", () => {
+    // The zod layer must not strip `stories` (unknown keys ARE stripped for
+    // forward compatibility). Content is owned by `capabilities/distribution.test.ts`;
+    // this pins only that the field survives `parseRawConfig` on the right pack.
+    const storyCounts = defaults.packs?.map((pack) =>
+      typeof pack === "string" ? 0 : (pack.stories?.length ?? 0),
+    );
+    expect(storyCounts).toEqual([5, 0, 1, 1]);
+  });
+
+  it("declares no removed field — the validator would refuse to load one", () => {
+    // `generators` was deleted (L-OPEN-1 ruling): validated, layered, and read
+    // by nothing. The distribution config goes through the same strict
+    // `parseRawConfig` as every layer, so a `generators:` reintroduced here
+    // would fail the eager validation at import — this pins the honest state.
+    expect(defaults).not.toHaveProperty("generators");
+  });
+
+  it("declares the domain namespaces the store is built with and the CLI resolves", () => {
+    // Two consumers, one declaration. (1) The config layer wins every prefix
+    // harvest, so this is what keeps `ds:` entity names stable when the design
+    // system declares `ds:` with two IRIs. (2) It is the domain half of
+    // `DEFAULT_PREFIX_MAP`, so it also decides which prefixed names a lookup
+    // can expand — `cs:` is here for that reader.
+    expect(defaults.prefixes).toEqual({
+      ds: "https://ds.canonical.com/",
+      cs: "http://pragma.canonical.com/codestandards#",
+    });
+  });
+
+  it("ships the normal channel and standard detail level", () => {
+    expect(defaults.channel).toBe("normal");
+    expect(defaults.detail).toBe("standard");
+  });
+});

package/src/kernel/config/defaults.ts

@@ -1,28 +1,18 @@
 /**
- * Built-in configuration defaults (D6 — TS, not JSON).
+ * Built-in configuration defaults — the validated distribution config.
  *
- * 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`.
+ * The lowest config layer is the distribution's own `pragma.conf.ts` (package
+ * root), STATICALLY imported so it travels with the emitted modules (no fs read
+ * — `evaluateProjectConfig` stats/imports from disk, which is right for a
+ * consumer's config and wrong for the distribution's own) and validated through
+ * the same `parseRawConfig` as every
+ * other layer. Statically imported by `readConfig` (itself dynamic-imported,
+ * off the `--help`/`__complete` fast path) and by its own test, so the eager
+ * validation and the zod import here add nothing to the storeless surfaces —
+ * the lazy.test.ts module-graph probe covers that boundary.
  */
 
-import type { PragmaConfig } from "./types.js";
+import rawConfig from "../../../pragma.conf.js";
+import { parseRawConfig } from "./schema.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;
+export default parseRawConfig(rawConfig, "pragma.conf.ts");

package/src/kernel/config/evaluateProjectConfig.ts

@@ -16,11 +16,19 @@
  *
  * 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.
+ * across processes. The fix that would catch it — bundling the config and keying
+ * on the bundle hash — would blow the warm-load budget on every load. Touch the
+ * entry (or bump VERSION) to force a rebuild.
+ *
+ * THE CONFIG IS THE CONSUMER'S OWN TYPESCRIPT, and this is the one place the
+ * distribution executes code it did not author. `pragma` ships on a `node`
+ * shebang, so that import is served by node's type STRIPPING — which erases
+ * annotations and refuses syntax that would need real emit (`enum`, `namespace`,
+ * parameter properties). Those are rejected with `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`,
+ * which {@link evaluateProjectConfig} names specifically rather than letting it
+ * arrive as an anonymous load failure. The `engines` floor (node >= 22.18) is what
+ * makes stripping default-on — and the range excludes 23.0-23.5, which satisfy
+ * a bare `>=22.18` but predate the 23.x line's own default-on release (23.6).
  */
 
 import { createHash } from "node:crypto";
@@ -33,8 +41,8 @@ import {
 } 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 { PROJECT_CONFIG_FILENAME, VERSION } from "../../constants.js";
+import { PragmaError } from "../error/index.js";
 import { configCacheDir } from "./paths.js";
 import { parseRawConfig } from "./schema.js";
 import type { RawConfig } from "./types.js";
@@ -94,7 +102,7 @@ export async function evaluateProjectConfig(path: string): Promise<RawConfig> {
   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
+  // unwrapped, that raw throw collapses to INTERNAL_ERROR ("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 };
@@ -103,12 +111,26 @@ export async function evaluateProjectConfig(path: string): Promise<RawConfig> {
   } catch (error) {
     if (error instanceof PragmaError) throw error;
     const reason = error instanceof Error ? error.message : String(error);
+    // Node strips types rather than compiling them, so a config using syntax that
+    // needs real emit fails here with a message naming neither the constraint nor
+    // the fix. Say both — this is a supported config that simply must be written
+    // in erasable TypeScript, and the author has no other way to learn that.
+    const { code } = (error ?? {}) as { code?: unknown };
+    if (code === "ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX") {
+      throw PragmaError.configError(
+        `Your ${PROJECT_CONFIG_FILENAME} uses TypeScript syntax that cannot be erased: ${reason}`,
+        {
+          recovery: {
+            message: `Rewrite it in erasable TypeScript — types, interfaces and \`satisfies\` are fine; \`enum\`, \`namespace\` and constructor parameter properties are not. A plain object literal with a \`default\` export always works.`,
+          },
+        },
+      );
+    }
     throw PragmaError.configError(
-      `Could not load project config ${path}: ${reason}`,
+      `Cannot 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.",
+          message: `Fix the error in your ${PROJECT_CONFIG_FILENAME} (it must evaluate to a default export), then try again.`,
         },
       },
     );

package/src/kernel/config/findProjectConfig.ts

@@ -1,8 +1,8 @@
 /**
  * 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
+ * Looks for `<bin>.config.ts` (or, as a compiled-binary fallback,
+ * `<bin>.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`.
@@ -11,9 +11,10 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
 
 /** Candidate project-config filenames, in preference order. */
-const CANDIDATES = ["pragma.config.ts", "pragma.config.js"] as const;
+const CANDIDATES = [PROJECT_CONFIG_FILENAME, `${BIN_NAME}.config.js`] as const;
 
 /**
  * Find the nearest project config file at or above `cwd`.

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

@@ -1,60 +1,66 @@
-import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+/**
+ * The setup hint — the read-only replacement for first-run seeding.
+ *
+ * Onboarding used to WRITE: a pipeline step ran before dispatch on every
+ * non-help invocation and created the global config, so `skill list` — a read —
+ * mutated the machine before the user had consented to anything. Seeding is now
+ * the `config` setup target, created inside a consented run. What is left is a
+ * stateless hint, and the property that matters most about it is the one these
+ * tests pin: reading it writes nothing.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { ensureFirstRun, firstRunTask } from "./firstRun.js";
+import { setupHintLines } 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-"));
+function freshConfigHome(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-first-"));
+  process.env.XDG_CONFIG_HOME = dir;
+  return dir;
 }
 
 afterEach(() => {
   process.env.XDG_CONFIG_HOME = originalConfigHome;
 });
 
-describe("first run", () => {
-  it("greets on stderr and seeds the global config", async () => {
+describe("the setup hint", () => {
+  it("names the pre-release and the command that configures the machine", () => {
     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();
+    const lines = setupHintLines();
+    expect(lines.some((line) => line.includes("pre-release"))).toBe(true);
+    expect(lines.some((line) => line.includes("pragma setup"))).toBe(true);
   });
 
-  it("is idempotent — no greeting when the config already exists", async () => {
-    freshConfigHome();
-    await ensureFirstRun(() => {});
+  it("writes NOTHING — presence of the config is the state, not a marker", () => {
+    // A marker file would itself be a pre-consent write, which is the exact
+    // defect being removed. The probe must leave the config home untouched.
+    const dir = freshConfigHome();
+    expect(existsSync(globalConfigPath())).toBe(false);
 
-    const second: string[] = [];
-    await ensureFirstRun((line) => second.push(line));
-    expect(second).toEqual([]);
+    setupHintLines();
+    setupHintLines();
 
-    const task = firstRunTask();
-    expect(task).toBeDefined();
+    expect(readdirSync(dir)).toEqual([]);
+    expect(existsSync(globalConfigPath())).toBe(false);
   });
 
-  it("tolerates a creation failure with a single warning", async () => {
+  it("goes quiet once the config exists", () => {
     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");
+    const path = globalConfigPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, "{}\n");
+
+    expect(setupHintLines()).toEqual([]);
   });
 });

package/src/kernel/config/firstRun.ts

@@ -1,91 +1,34 @@
 /**
- * First-run onboarding — welcome note + global config creation.
+ * The setup hint — the read-only replacement for first-run seeding.
  *
- * 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.
+ * Onboarding used to WRITE. A pipeline step ran before dispatch on every
+ * non-help invocation and created `$XDG_CONFIG_HOME/<bin>/config.json`, so
+ * `skill list` — a read — mutated the machine before the user had consented to
+ * anything, and a banner interleaved itself into the output of runs that were
+ * mutating something else entirely. The config layers already treat the missing
+ * file as "every field at its built-in default", so the write bought nothing.
  *
- * @returns Task yielding whether the config was created and its path.
- * @note Impure — checks/creates the global config file, emits log effects.
+ * Seeding is now a setup target, created inside a consented run. What is left
+ * here is a STATELESS hint: shown when the global config file is absent, on
+ * read-only surfaces only. There is no marker file — a marker is itself a
+ * pre-consent write, which is the exact defect being removed — because the
+ * presence of the config IS the state.
  */
-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 };
-  });
-}
+import { existsSync } from "node:fs";
+import { BIN_NAME, ISSUES_URL } from "../../constants.js";
+import { globalConfigPath } from "./paths.js";
 
 /**
- * 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).
+ * The hint lines for a machine that has not been set up, or none when it has.
  *
- * @param write - Stderr sink, injectable for tests.
- * @note Impure — filesystem effects + stderr.
+ * @returns The lines to print, or an empty array.
+ * @note Impure — probes the global config path.
  */
-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}`);
-  }
+export function setupHintLines(): string[] {
+  if (existsSync(globalConfigPath())) return [];
+  return [
+    `${BIN_NAME} is pre-release — report issues at ${ISSUES_URL}.`,
+    `Run \`${BIN_NAME} setup\` to configure this machine.`,
+  ];
 }

package/src/kernel/config/globalConfig.ts

@@ -1,8 +1,8 @@
 /**
  * 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
+ * The global layer holds cross-project machine state (channel, detail, tier).
+ * 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

package/src/kernel/config/index.ts

@@ -3,17 +3,16 @@
  *
  * `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.
+ * consumer — off the zod fast path. `defaults` is likewise not re-exported:
+ * it statically imports the distribution config and the validating schema.
  */
 
-export { default as defaults } from "./defaults.js";
 export { evaluateProjectConfig } from "./evaluateProjectConfig.js";
 export { findProjectConfig } from "./findProjectConfig.js";
-export { ensureFirstRun, firstRunTask } from "./firstRun.js";
+export { setupHintLines } from "./firstRun.js";
 export type { GlobalConfigRead } from "./globalConfig.js";
 export { readGlobalConfig } from "./globalConfig.js";
 export {
-  cacheDir,
   configCacheDir,
   configDir,
   globalConfigPath,
@@ -26,8 +25,8 @@ export type {
   ConfigLayers,
   ConfigOrigin,
   ConfigOrigins,
-  PackageDeclaration,
-  PackageEntry,
+  PackDeclaration,
+  PackSource,
   PragmaConfig,
   RawConfig,
 } from "./types.js";