@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.4

package/dist/harness/types.d.ts

@@ -5,24 +5,37 @@
  * distilled from Anthropic's published guidance and only ever warn -- a
  * subjective rule must never block a push.
  */
+/** How severe a finding is: `structural` fails the gate; `rubric` only ever warns. */
 export type RuleLevel = "structural" | "rubric";
+/** Which area of the harness (settings, hooks, skills, agents, rules, claude-md) a finding is about. */
 export type HarnessCategory = "settings" | "hooks" | "skills" | "agents" | "rules" | "claude-md";
+/** Every {@link HarnessCategory}, as an ordered list -- so rubric tallies are iterated in a fixed order. */
 export declare const HARNESS_CATEGORIES: readonly HarnessCategory[];
+/** One rule's result against one subject. */
 export interface HarnessFinding {
+    /** The id of the rule this finding came from. */
     ruleId: string;
+    /** Whether this finding fails the gate (`structural`) or only warns (`rubric`). */
     level: RuleLevel;
+    /** Which harness area this finding is about. */
     category: HarnessCategory;
     /** The file, skill, agent, or registration the finding is about. */
     subject: string;
+    /** Human-readable description of what the rule found. */
     message: string;
 }
 /** How many subjects a set of rules examined, and how many of those failed. */
 export interface CheckTally {
+    /** How many subjects the rules examined. */
     checked: number;
+    /** How many of the examined subjects failed. */
     failed: number;
 }
+/** The full result of grading one project's harness. */
 export interface HarnessGrade {
+    /** Every finding from every rule, in rule order. */
     findings: HarnessFinding[];
+    /** The tally of structural checks: how many were checked and how many failed. */
     structural: CheckTally;
     /** Rubric tallies per category -- the absolute-quality measurement. */
     rubric: Record<HarnessCategory, CheckTally>;

package/dist/harness/types.js

@@ -1,3 +1,6 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/** Every {@link HarnessCategory}, as an ordered list -- so rubric tallies are iterated in a fixed order. */
 export const HARNESS_CATEGORIES = [
     "settings",
     "hooks",

package/dist/inventory.d.ts

@@ -1,13 +1,36 @@
+import type { StagedBaselineFile } from "./baseline-stage.js";
 import type { CapCounts } from "./caps.js";
 import type { FileConflict } from "./conflicts.js";
 import type { HarnessConformance } from "./harness/conformance.js";
 import type { HarnessGrade } from "./harness/types.js";
 import type { ModeDetection } from "./mode.js";
+import type { StagedPack } from "./pack-stage.js";
 import type { PackWiring } from "./packs.js";
 import type { ProjectSurvey } from "./survey/survey.js";
 import type { ToolchainConformance } from "./toolchain/conformance.js";
 import type { ToolchainGrade } from "./toolchain/types.js";
-export declare const INVENTORY_SCHEMA_VERSION = 4;
+export declare const INVENTORY_SCHEMA_VERSION = 5;
+/**
+ * Where adopt mode staged the baseline files the project lacks entirely
+ * (`baseline-stage.ts`), and how each staged copy is named.
+ *
+ * @example
+ * ```ts
+ * const stagedBaseline: StagedBaseline = {
+ *   dir: ".groundwork/baseline",
+ *   suffix: ".staged",
+ *   files: [{ path: "eslint.config.js", staged: "eslint.config.js.staged", sha256: "…" }],
+ * };
+ * ```
+ */
+export interface StagedBaseline {
+    /** The staging directory, relative to the project root (e.g. `.groundwork/baseline`). */
+    dir: string;
+    /** The suffix every staged file name carries (`.staged`), so no toolchain glob ever matches one. */
+    suffix: string;
+    /** The staged files: install path, staged name relative to `dir`, and sha256 of the staged bytes. */
+    files: StagedBaselineFile[];
+}
 export interface PackSurvey {
     name: string;
     modes: string[];
@@ -25,10 +48,15 @@ export interface Inventory {
     cliVersion: string;
     generatedAt: string;
     modeSignal: string;
+    /** The template tree's absolute path, in the platform's native form (not normalized). */
     templateRoot: string;
+    /** The adopted project's absolute path, in the platform's native form (not normalized). */
     targetDir: string;
+    /** The project survey; its paths are native, not normalized. */
     survey: ProjectSurvey;
+    /** Baseline-vs-project file collisions; every `relPath` uses `/` on every platform (normalized by `buildInventory`). */
     conflicts: FileConflict[];
+    /** Per-pack surveys; every `fileConflicts[].relPath` uses `/` on every platform, like `conflicts`. */
     packs: PackSurvey[];
     /** Wiring integrity and rubric quality of the project's existing harness. Absent when schemaVersion is below 3. */
     harnessGrade: HarnessGrade;
@@ -38,6 +66,10 @@ export interface Inventory {
     toolchainGrade: ToolchainGrade;
     /** How far the project's toolchain files have drifted from the baseline's -- information, never a defect. Absent when schemaVersion is below 4. */
     toolchainConformance: ToolchainConformance;
+    /** The "absent" baseline files, copied verbatim as inert `<path>.staged` copies for `/customize` to install from. Absent when schemaVersion is below 5; `dir` is project-relative, and `dir` and every `files[].path`/`files[].staged` use `/` on every platform. */
+    stagedBaseline: StagedBaseline;
+    /** Every pack, staged as inert `.staged` copies (manifest included) under `.groundwork/packs/<name>/` for `/customize` to install from after confirmation; one entry per pack, `dir` project-relative, and `dir` and every `path`/`staged` use `/` on every platform. Absent from inventories written before pack staging became inert (see the module header). */
+    stagedPacks: StagedPack[];
 }
 /**
  * Resolves this CLI package's own declared version. `packageJsonPath`
@@ -55,9 +87,51 @@ export interface BuildInventoryParams {
     packs: PackSurvey[];
     harnessGrade: HarnessGrade;
     toolchainGrade: ToolchainGrade;
+    stagedBaseline: StagedBaseline;
+    stagedPacks: StagedPack[];
 }
-/** Builds the inventory object. Does not write anything -- see `writeInventory`. */
+/**
+ * Builds the inventory object. Does not write anything -- see `writeInventory`.
+ *
+ * Exactly these paths use `/` on every platform: each `conflicts[].relPath`
+ * and each `packs[].fileConflicts[].relPath`, normalized here once with
+ * {@link toPosixPath}, plus `stagedBaseline.dir` (built by the caller as a
+ * `/`-joined literal) and each `stagedBaseline.files[].path`/`.staged`
+ * (already normalized by `stageBaselineAdditions` with the same
+ * {@link toPosixPath}, so the conflict and staged paths agree), and
+ * `stagedPacks` (passed through verbatim: `stagePacks` builds each `dir` as
+ * a `/`-joined literal and normalizes every `path`/`staged` the same way).
+ * The harness/toolchain conformance
+ * summaries are computed from the normalized conflict paths. Every other
+ * path -- `templateRoot`, `targetDir`, and every path inside `survey` -- is
+ * passed through in the platform's native form. The caller's `conflicts` and
+ * `packs` are never mutated; new objects are returned.
+ *
+ * @example
+ * ```ts
+ * const inventory = buildInventory({ detection, templateRoot, targetDir, survey,
+ *   conflicts, packs, harnessGrade, toolchainGrade, stagedBaseline, stagedPacks });
+ * inventory.conflicts[0]?.relPath; // "src/index.ts", even on Windows
+ * ```
+ */
 export declare function buildInventory(params: BuildInventoryParams): Inventory;
-/** Writes `inventory.json` into `groundworkDir`, creating it if needed. */
+/**
+ * Writes `inventory.json` into `groundworkDir`, creating it if needed.
+ *
+ * The write is atomic: the JSON goes to `inventory.json.tmp` first and is
+ * renamed over `inventory.json` only once complete, so a reader never sees a
+ * half-written file. On failure -- creating `groundworkDir` included -- the
+ * temp file is removed (best effort: a
+ * failed removal only warns, naming the temp file), any existing
+ * `inventory.json` is left untouched, and an `Error` is thrown, with the
+ * original failure as its `cause`, saying `.groundwork/` is incomplete and
+ * the CLI should be re-run.
+ *
+ * @example
+ * ```ts
+ * const path = writeInventory(inventory, ".groundwork");
+ * // path: ".groundwork/inventory.json"
+ * ```
+ */
 export declare function writeInventory(inventory: Inventory, groundworkDir: string): string;
 //# sourceMappingURL=inventory.d.ts.map

package/dist/inventory.js

@@ -1,20 +1,35 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Serializes a survey + conflict plan + pack survey into
  * `.groundwork/inventory.json` -- the machine-readable handoff
- * `/customize`'s Step 0 reads instead of re-deriving the survey itself.
+ * `/customize`'s Step 0 (the adopt-mode reconcile step in `/customize`)
+ * reads instead of re-deriving the survey itself.
  * Schema-versioned so a future CLI release can tell an old inventory apart
  * from a current one; `/customize` must tolerate an older inventory
  * rather than crash on one -- `schemaVersion: 1` predates packs (no `packs`
  * field), `schemaVersion` below 3 predates the harness grade (no
  * `harnessGrade`/`harnessConformance`), and `schemaVersion` below 4 predates
- * the toolchain grade (no `toolchainGrade`/`toolchainConformance`).
+ * the toolchain grade (no `toolchainGrade`/`toolchainConformance`), and
+ * `schemaVersion` below 5 predates staged baseline additions (no
+ * `stagedBaseline`) -- `/customize` then falls back to reading absent files
+ * from `templateRoot`. From schema 5 on, each staged file is an inert copy
+ * named `<path>` + `stagedBaseline.suffix` (`.staged`) and carries the sha256
+ * of its staged bytes, so `/customize` can verify a copy before installing it.
+ * Schema 5 also carries `stagedPacks`, added additively without a version
+ * bump: every pack staged the same inert way under `.groundwork/packs/<name>/`
+ * (`pack-stage.ts`), its manifest included. No published release has
+ * written schema 5 yet; an inventory without `stagedPacks` came only from an
+ * unreleased development build, which staged packs unsuffixed at the same
+ * location.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { toPosixPath } from "./assets.js";
 import { summarizeHarnessConformance } from "./harness/conformance.js";
 import { summarizeToolchainConformance } from "./toolchain/conformance.js";
-export const INVENTORY_SCHEMA_VERSION = 4;
+export const INVENTORY_SCHEMA_VERSION = 5;
 /** Resolves this CLI package's own `package.json`, relative to this module's runtime location. */
 function defaultPackageJsonPath() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -38,8 +53,44 @@ export function resolveCliVersion(packageJsonPath = defaultPackageJsonPath()) {
         return "unknown";
     }
 }
-/** Builds the inventory object. Does not write anything -- see `writeInventory`. */
+/**
+ * Returns new `FileConflict` objects whose `relPath` uses `/`, leaving the
+ * caller's array and objects untouched (main.ts keeps the native form for
+ * real file operations).
+ */
+function toPosixConflicts(conflicts) {
+    return conflicts.map((c) => ({ ...c, relPath: toPosixPath(c.relPath) }));
+}
+/**
+ * Builds the inventory object. Does not write anything -- see `writeInventory`.
+ *
+ * Exactly these paths use `/` on every platform: each `conflicts[].relPath`
+ * and each `packs[].fileConflicts[].relPath`, normalized here once with
+ * {@link toPosixPath}, plus `stagedBaseline.dir` (built by the caller as a
+ * `/`-joined literal) and each `stagedBaseline.files[].path`/`.staged`
+ * (already normalized by `stageBaselineAdditions` with the same
+ * {@link toPosixPath}, so the conflict and staged paths agree), and
+ * `stagedPacks` (passed through verbatim: `stagePacks` builds each `dir` as
+ * a `/`-joined literal and normalizes every `path`/`staged` the same way).
+ * The harness/toolchain conformance
+ * summaries are computed from the normalized conflict paths. Every other
+ * path -- `templateRoot`, `targetDir`, and every path inside `survey` -- is
+ * passed through in the platform's native form. The caller's `conflicts` and
+ * `packs` are never mutated; new objects are returned.
+ *
+ * @example
+ * ```ts
+ * const inventory = buildInventory({ detection, templateRoot, targetDir, survey,
+ *   conflicts, packs, harnessGrade, toolchainGrade, stagedBaseline, stagedPacks });
+ * inventory.conflicts[0]?.relPath; // "src/index.ts", even on Windows
+ * ```
+ */
 export function buildInventory(params) {
+    const conflicts = toPosixConflicts(params.conflicts);
+    const packs = params.packs.map((pack) => ({
+        ...pack,
+        fileConflicts: toPosixConflicts(pack.fileConflicts),
+    }));
     return {
         schemaVersion: INVENTORY_SCHEMA_VERSION,
         cliVersion: resolveCliVersion(),
@@ -48,19 +99,59 @@ export function buildInventory(params) {
         templateRoot: params.templateRoot,
         targetDir: params.targetDir,
         survey: params.survey,
-        conflicts: params.conflicts,
-        packs: params.packs,
+        conflicts,
+        packs,
         harnessGrade: params.harnessGrade,
-        harnessConformance: summarizeHarnessConformance(params.conflicts),
+        harnessConformance: summarizeHarnessConformance(conflicts),
         toolchainGrade: params.toolchainGrade,
-        toolchainConformance: summarizeToolchainConformance(params.conflicts),
+        toolchainConformance: summarizeToolchainConformance(conflicts),
+        stagedBaseline: params.stagedBaseline,
+        stagedPacks: params.stagedPacks,
     };
 }
-/** Writes `inventory.json` into `groundworkDir`, creating it if needed. */
+/**
+ * Writes `inventory.json` into `groundworkDir`, creating it if needed.
+ *
+ * The write is atomic: the JSON goes to `inventory.json.tmp` first and is
+ * renamed over `inventory.json` only once complete, so a reader never sees a
+ * half-written file. On failure -- creating `groundworkDir` included -- the
+ * temp file is removed (best effort: a
+ * failed removal only warns, naming the temp file), any existing
+ * `inventory.json` is left untouched, and an `Error` is thrown, with the
+ * original failure as its `cause`, saying `.groundwork/` is incomplete and
+ * the CLI should be re-run.
+ *
+ * @example
+ * ```ts
+ * const path = writeInventory(inventory, ".groundwork");
+ * // path: ".groundwork/inventory.json"
+ * ```
+ */
 export function writeInventory(inventory, groundworkDir) {
-    mkdirSync(groundworkDir, { recursive: true });
     const path = join(groundworkDir, "inventory.json");
-    writeFileSync(path, `${JSON.stringify(inventory, null, 2)}\n`);
+    const tmpPath = `${path}.tmp`;
+    try {
+        mkdirSync(groundworkDir, { recursive: true });
+        // Remove whatever already sits at the temp path (a crashed run's
+        // leftover, or a symlink planted there), then create it exclusively:
+        // "wx" fails rather than following a symlink raced in between.
+        rmSync(tmpPath, { force: true });
+        writeFileSync(tmpPath, `${JSON.stringify(inventory, null, 2)}\n`, {
+            flag: "wx",
+        });
+        renameSync(tmpPath, path);
+    }
+    catch (cause) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch (cleanupError) {
+            // Best effort: the write failure below is the error worth reporting,
+            // so a failed cleanup only warns, naming the leftover file.
+            console.warn(`warning: could not remove the temporary file ${tmpPath} -- delete it by hand (${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)})`);
+        }
+        throw new Error(`writing ${path} failed, so .groundwork/ is incomplete -- fix the cause and re-run the CLI`, { cause });
+    }
     return path;
 }
 //# sourceMappingURL=inventory.js.map

package/dist/jsonc.d.ts

@@ -1,14 +1,61 @@
+/**
+ * The outcome of reading/parsing JSONC. A failure says which step failed:
+ * `"read"` (the file is missing, unreadable, unresolvable or not a regular
+ * file) or `"parse"` (its text is not JSONC) -- so a caller never reports an
+ * unreadable file as unparseable.
+ */
 export type JsoncReadResult = {
     ok: true;
     value: unknown;
 } | {
     ok: false;
+    stage: "read" | "parse";
     error: string;
 };
-/** Strips `//` and block comments and trailing commas from JSONC source. */
+/**
+ * Strips `//` and block comments and trailing commas from JSONC source. A
+ * trailing comma is removed in the same pass that tracks string literals, so
+ * a `,}` or `,]` inside a string (value or key) is never touched.
+ */
 export declare function stripJsoncNoise(content: string): string;
+/**
+ * Strips `//` and block comments from JavaScript/TypeScript source, leaving
+ * single-quoted, double-quoted and template-literal strings alone. Unlike {@link stripJsoncNoise}
+ * it keeps trailing commas -- they are valid JS syntax, and removing them is
+ * a JSON-only cleanup.
+ *
+ * A character scanner, not a parser: a regex literal containing a quote
+ * (`/["']/`) or `//` can be misread as opening a string or a comment, and a
+ * `${...}` expression inside a template literal containing its own backtick
+ * or quote can close the outer template early. Neither shape appears in this
+ * project's actual `eslint.config.js`/`vitest.config.ts`/`verify-steps.mjs`
+ * files.
+ *
+ * @example
+ * ```ts
+ * import { stripJsComments } from "./jsonc.js";
+ * stripJsComments("const g = ['**' + '/*.js']; // note");
+ * // => "const g = ['**' + '/*.js']; "
+ * ```
+ */
+export declare function stripJsComments(content: string): string;
 /** Parses JSONC source text, returning a structured result rather than throwing. */
 export declare function parseJsonc(content: string): JsoncReadResult;
-/** Reads and parses a JSONC file. A missing file is reported, not thrown. */
+/**
+ * Reads and parses a JSONC file. A missing (`ENOENT`/`ENOTDIR`), unreadable
+ * (`EACCES`/`EPERM`), unresolvable (a symlink loop's `ELOOP`), not a regular
+ * file (a directory's `EISDIR`) or unparseable file is reported, not thrown
+ * -- each is a property of the file. The existence check is a real `stat`, never `existsSync`, so a file
+ * under a directory this process cannot search is reported with its errno
+ * rather than as absent. Any other failure, on the check or the read
+ * (`EIO`, `EMFILE`, ...), throws an `Error` naming the path, with the
+ * original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * const read = readJsoncFile("/path/to/project/tsconfig.json");
+ * if (!read.ok) console.log(read.error);
+ * ```
+ */
 export declare function readJsoncFile(path: string): JsoncReadResult;
 //# sourceMappingURL=jsonc.d.ts.map

package/dist/jsonc.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * A tolerant reader for JSON-with-comments (JSONC) -- `tsconfig.json` and
  * friends use `//`/`/* *\/` comments and trailing commas that `JSON.parse`
@@ -6,13 +8,23 @@
  * to `JSON.parse`. It is not a full JSON5 parser -- no unquoted keys, no
  * single-quoted strings -- tsconfig-shaped input is the only intended use.
  */
-import { existsSync, readFileSync } from "node:fs";
-/** Strips `//` and block comments and trailing commas from JSONC source. */
+import { readFileSync, statSync } from "node:fs";
+import { errnoCode, isAbsentError, readFailure, unresolvableCode, } from "./survey/internal/read-guard.js";
+/** Matches exactly the whitespace class `\s` covers, so a trailing comma is recognized across the same gaps as before. */
+const WHITESPACE = /\s/;
+/**
+ * Strips `//` and block comments and trailing commas from JSONC source. A
+ * trailing comma is removed in the same pass that tracks string literals, so
+ * a `,}` or `,]` inside a string (value or key) is never touched.
+ */
 export function stripJsoncNoise(content) {
     let result = "";
     let inString = false;
     let inLineComment = false;
     let inBlockComment = false;
+    // Index in `result` of the last comma emitted outside a string with only
+    // whitespace (or stripped comments) after it; -1 when there is none.
+    let pendingComma = -1;
     for (let i = 0; i < content.length; i++) {
         const ch = content[i];
         const next = content[i + 1];
@@ -44,6 +56,89 @@ export function stripJsoncNoise(content) {
         }
         if (ch === '"') {
             inString = true;
+            pendingComma = -1;
+            result += ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        if ((ch === "}" || ch === "]") && pendingComma !== -1) {
+            result = result.slice(0, pendingComma) + result.slice(pendingComma + 1);
+        }
+        if (ch === ",") {
+            pendingComma = result.length;
+        }
+        else if (ch !== undefined && !WHITESPACE.test(ch)) {
+            pendingComma = -1;
+        }
+        result += ch;
+    }
+    return result;
+}
+/**
+ * Strips `//` and block comments from JavaScript/TypeScript source, leaving
+ * single-quoted, double-quoted and template-literal strings alone. Unlike {@link stripJsoncNoise}
+ * it keeps trailing commas -- they are valid JS syntax, and removing them is
+ * a JSON-only cleanup.
+ *
+ * A character scanner, not a parser: a regex literal containing a quote
+ * (`/["']/`) or `//` can be misread as opening a string or a comment, and a
+ * `${...}` expression inside a template literal containing its own backtick
+ * or quote can close the outer template early. Neither shape appears in this
+ * project's actual `eslint.config.js`/`vitest.config.ts`/`verify-steps.mjs`
+ * files.
+ *
+ * @example
+ * ```ts
+ * import { stripJsComments } from "./jsonc.js";
+ * stripJsComments("const g = ['**' + '/*.js']; // note");
+ * // => "const g = ['**' + '/*.js']; "
+ * ```
+ */
+export function stripJsComments(content) {
+    let result = "";
+    let quote;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        const next = content[i + 1];
+        if (inLineComment) {
+            if (ch === "\n") {
+                inLineComment = false;
+                result += ch;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (ch === "*" && next === "/") {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (quote !== undefined) {
+            result += ch;
+            if (ch === "\\") {
+                result += next ?? "";
+                i++;
+                continue;
+            }
+            if (ch === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
             result += ch;
             continue;
         }
@@ -59,7 +154,7 @@ export function stripJsoncNoise(content) {
         }
         result += ch;
     }
-    return result.replace(/,(\s*[}\]])/g, "$1");
+    return result;
 }
 /** Parses JSONC source text, returning a structured result rather than throwing. */
 export function parseJsonc(content) {
@@ -69,15 +164,53 @@ export function parseJsonc(content) {
     catch (error) {
         return {
             ok: false,
+            stage: "parse",
             error: error instanceof Error ? error.message : String(error),
         };
     }
 }
-/** Reads and parses a JSONC file. A missing file is reported, not thrown. */
+/**
+ * Reads and parses a JSONC file. A missing (`ENOENT`/`ENOTDIR`), unreadable
+ * (`EACCES`/`EPERM`), unresolvable (a symlink loop's `ELOOP`), not a regular
+ * file (a directory's `EISDIR`) or unparseable file is reported, not thrown
+ * -- each is a property of the file. The existence check is a real `stat`, never `existsSync`, so a file
+ * under a directory this process cannot search is reported with its errno
+ * rather than as absent. Any other failure, on the check or the read
+ * (`EIO`, `EMFILE`, ...), throws an `Error` naming the path, with the
+ * original failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * const read = readJsoncFile("/path/to/project/tsconfig.json");
+ * if (!read.ok) console.log(read.error);
+ * ```
+ */
 export function readJsoncFile(path) {
-    if (!existsSync(path)) {
-        return { ok: false, error: `${path} does not exist` };
+    let content;
+    try {
+        statSync(path);
+        content = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (isAbsentError(error)) {
+            return { ok: false, stage: "read", error: `${path} does not exist` };
+        }
+        if (errnoCode(error) === "EISDIR") {
+            return {
+                ok: false,
+                stage: "read",
+                error: `${path} is not a regular file`,
+            };
+        }
+        const code = unresolvableCode(error);
+        if (code === undefined)
+            throw readFailure(path, error);
+        return {
+            ok: false,
+            stage: "read",
+            error: `${path} is unreadable (${code})`,
+        };
     }
-    return parseJsonc(readFileSync(path, "utf8"));
+    return parseJsonc(content);
 }
 //# sourceMappingURL=jsonc.js.map

package/dist/main.d.ts

@@ -30,10 +30,69 @@ export declare class CliUsageError extends Error {
 export declare function parseArgs(argv: string[]): CliOptions;
 /** Resolves `templates/core` for a source checkout or a published tarball -- see `assets.ts`. */
 export declare function templatesCoreDir(): string;
-/** The post-`--pack`-install caps summary line(s) printed to fresh-mode's console output. */
+/**
+ * The result of {@link formatCapsSummary}: the rendered summary text plus an
+ * explicit over-cap flag, so a caller never has to string-match the text to
+ * decide how to present it.
+ *
+ * @example
+ * ```ts
+ * const summary: CapsSummary = { text: "= 5 agents, ...", overCap: false };
+ * console.log(summary.overCap ? `warning: ${summary.text}` : summary.text);
+ * ```
+ */
+export interface CapsSummary {
+    /** The summary line(s), newline-joined, exactly as printed. */
+    readonly text: string;
+    /** `true` when the baseline plus installed packs exceeds any cap in `CAP_LIMITS`. */
+    readonly overCap: boolean;
+}
+/**
+ * The post-`--pack`-install caps summary line(s) printed to fresh-mode's
+ * console output, plus whether any cap is exceeded.
+ *
+ * @example
+ * ```ts
+ * const summary = formatCapsSummary(baselineCounts, [
+ *   { name: "harness-extras", budget: packBudget },
+ * ]);
+ * console.log(summary.text);
+ * ```
+ */
 export declare function formatCapsSummary(baseline: CapCounts, installed: {
     name: string;
     budget: CapCounts;
-}[]): string;
-export declare function main(argv: string[]): void;
+}[]): CapsSummary;
+/**
+ * Adopt mode's write-scope invariant (docs/assurance-case.md's trust
+ * boundary around the adopted project): every path it writes resolves under
+ * `<targetDir>/.groundwork/` or the guarded `/customize` install at
+ * `<targetDir>/.claude/skills/customize/` -- never an existing project file.
+ * `paths` may be absolute or relative to `targetDir`. Containment is
+ * {@link isPathContained}'s, so a sibling that merely shares a root's name
+ * as a prefix (`.groundwork-evil/`) is rejected. Both roots are derived from
+ * `customize-paths.ts`'s segment constants, so they cannot drift from where
+ * the install actually writes. The check is lexical -- it never touches the
+ * filesystem, so it does not detect a symlinked directory component; that
+ * refusal lives in the writers themselves (`fs-guard.ts`).
+ *
+ * @throws `AssertionError` (from `node:assert/strict`) naming the first path
+ * that escapes both allowed roots.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ *
+ * assertAdoptWriteScope("/work/app", [".groundwork/inventory.json"]); // ok
+ * assertAdoptWriteScope("/work/app", ["/work/app/package.json"]); // throws
+ * ```
+ */
+export declare function assertAdoptWriteScope(targetDir: string, paths: readonly string[]): void;
+/**
+ * Runs the CLI. `platform` is injectable so fresh mode's Windows refusal
+ * (a runtime error, exit 1, raised before anything is written) is
+ * unit-testable on any OS; it defaults to `process.platform`. Adopt mode and
+ * `--help`/`--version`/`--list-packs` run on every platform.
+ */
+export declare function main(argv: string[], platform?: NodeJS.Platform): void;
 //# sourceMappingURL=main.d.ts.map