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

package/dist/report.d.ts

@@ -1,4 +1,23 @@
 import type { Inventory } from "./inventory.js";
-/** Renders the full adoption report as Markdown. */
-export declare function renderReport(inventory: Inventory): string;
+/**
+ * Renders the full adoption report as Markdown.
+ *
+ * @param inventory - The inventory this report describes.
+ * @param nextStep - The sentence that leads the `## Next step` paragraph in
+ * place of the generic "Open this project in Claude Code and run
+ * `/customize`." -- a leading `Next: ` is removed, the rest trimmed and its
+ * first character upper-cased; the rest of the paragraph is kept. When
+ * omitted, or blank once the `Next: ` prefix is removed and the rest
+ * trimmed, the output is the generic sentence, unchanged.
+ *
+ * @example
+ * ```ts
+ * import { renderReport } from "./report.js";
+ *
+ * // inventory: the value buildInventory (inventory.ts) returned for this run
+ * const markdown = renderReport(inventory, "Next: run the plugin's own /customize.");
+ * // "...## Next step\n\nRun the plugin's own /customize. It reads this report..."
+ * ```
+ */
+export declare function renderReport(inventory: Inventory, nextStep?: string): string;
 //# sourceMappingURL=report.d.ts.map

package/dist/report.js

@@ -1,4 +1,8 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 import { CAP_LIMITS, countBaselineCaps } from "./caps.js";
+import { STAGED_PACKS_DIR, STAGED_PACK_MANIFEST } from "./pack-stage.js";
+import { STAGED_SUFFIX } from "./staging.js";
 /**
  * Estimates the post-merge total against each cap: the baseline's own count
  * plus whatever the existing project already has, on the (approximate)
@@ -187,10 +191,13 @@ function renderCapsSection(inventory) {
         ? "| --- | --- | --- | --- | --- | --- |"
         : "| --- | --- | --- | --- | --- |";
     const row = (label, key, existingCount, cap) => {
+        // The shown total (and its over-cap flag) includes the "+ all packs"
+        // column, so a pack that tips a cap over is flagged, not just listed.
+        const total = postMerge[key] + (hasPacks ? packBudget[key] : 0);
         const cells = [label, String(baseline[key]), String(existingCount)];
         if (hasPacks)
             cells.push(`+${packBudget[key]}`);
-        cells.push(`${postMerge[key]}${overCap(postMerge[key], cap)}`, String(cap));
+        cells.push(`${total}${overCap(total, cap)}`, String(cap));
         return `| ${cells.join(" | ")} |`;
     };
     const lines = [
@@ -201,6 +208,8 @@ function renderCapsSection(inventory) {
         row("Agents", "agents", inventory.survey.harness.agents.length, CAP_LIMITS.agents),
         row("Skills", "skills", inventory.survey.harness.skills.length, CAP_LIMITS.skills),
         row("Hooks", "hooks", inventory.survey.harness.hooks.length, CAP_LIMITS.hooks),
+        row("Workflows", "workflows", inventory.survey.toolchain.workflows.files.length, CAP_LIMITS.workflows),
+        row("Scripts", "scripts", Object.keys(inventory.survey.toolchain.scripts).length, CAP_LIMITS.scripts),
         "",
         "This is an approximate count assuming no name overlap; `/customize`'s Step 0 resolves it for real.",
     ];
@@ -243,6 +252,14 @@ function renderPacksSection(inventory) {
         .replace(/\n{3,}/g, "\n\n")
         .trimEnd();
 }
+/** The "; N staged for /customize at …" clause, or nothing when no file was actually staged. */
+function stagedClause(stagedBaseline) {
+    const { dir, suffix, files } = stagedBaseline;
+    if (files.length === 0) {
+        return "";
+    }
+    return `; ${files.length} staged for /customize at ${dir}/ (inert copies, each with a ${suffix} suffix)`;
+}
 function renderConflictsSection(inventory) {
     const { conflicts } = inventory;
     const absent = conflicts.filter((c) => c.status === "absent");
@@ -251,7 +268,7 @@ function renderConflictsSection(inventory) {
     const lines = [
         "## What groundwork would change",
         "",
-        `- ${absent.length} file(s) would be added cleanly (no collision).`,
+        `- ${absent.length} file(s) would be added cleanly (no collision)${stagedClause(inventory.stagedBaseline)}.`,
         `- ${identical.length} file(s) already match the baseline.`,
         `- ${divergent.length} file(s) conflict and need a decision.`,
     ];
@@ -275,8 +292,78 @@ function renderUndeterminedSection(inventory) {
     }
     return lines.join("\n");
 }
-/** Renders the full adoption report as Markdown. */
-export function renderReport(inventory) {
+/**
+ * The closing paragraph (plus its trailing blank line) about the inert staged
+ * copies -- the baseline's and the packs' -- or nothing when neither staged
+ * anything.
+ */
+function renderStagedFilesNote(stagedBaseline, stagedPacks) {
+    const parts = [];
+    const dirs = [];
+    if (stagedBaseline.files.length > 0) {
+        parts.push(`the baseline files staged under \`${stagedBaseline.dir}/\``);
+        dirs.push(stagedBaseline.dir);
+    }
+    if (stagedPacks.length > 0) {
+        parts.push(`the ${stagedPacks.length} pack(s) staged under \`${STAGED_PACKS_DIR}/\` ` +
+            `(each pack's \`${STAGED_PACK_MANIFEST}\` included)`);
+        dirs.push(STAGED_PACKS_DIR);
+    }
+    const subject = parts.join(" and ");
+    if (subject === "") {
+        return [];
+    }
+    const ignoreLines = dirs.map((dir) => `\`${dir}/\``).join(" and a ");
+    return [
+        `${subject.charAt(0).toUpperCase()}${subject.slice(1)} are inert copies, never ` +
+            `installed: each carries a \`${STAGED_SUFFIX}\` suffix so no tool in this ` +
+            "project picks one up, and `/customize` installs one only after you " +
+            `confirm it. Decide whether to commit or ignore those \`${STAGED_SUFFIX}\` ` +
+            "files before your next commit: they are verbatim template copies, so " +
+            "a strict license-header check, or any gate that runs over every " +
+            `tracked file, may flag them. To keep them out of git, add a ` +
+            `${ignoreLines} line to \`.gitignore\`.`,
+        "",
+    ];
+}
+/** The `## Next step` lead sentence used when the caller supplies none. */
+const DEFAULT_NEXT_STEP = "Open this project in Claude Code and run `/customize`.";
+/**
+ * `nextStep` with a leading `Next: ` removed, trimmed, and its first
+ * character upper-cased; {@link DEFAULT_NEXT_STEP} when omitted or when
+ * nothing but whitespace is left.
+ */
+function nextStepLead(nextStep) {
+    if (nextStep === undefined) {
+        return DEFAULT_NEXT_STEP;
+    }
+    const lead = (nextStep.startsWith("Next: ") ? nextStep.slice("Next: ".length) : nextStep).trim();
+    if (lead === "") {
+        return DEFAULT_NEXT_STEP;
+    }
+    return `${lead.charAt(0).toUpperCase()}${lead.slice(1)}`;
+}
+/**
+ * Renders the full adoption report as Markdown.
+ *
+ * @param inventory - The inventory this report describes.
+ * @param nextStep - The sentence that leads the `## Next step` paragraph in
+ * place of the generic "Open this project in Claude Code and run
+ * `/customize`." -- a leading `Next: ` is removed, the rest trimmed and its
+ * first character upper-cased; the rest of the paragraph is kept. When
+ * omitted, or blank once the `Next: ` prefix is removed and the rest
+ * trimmed, the output is the generic sentence, unchanged.
+ *
+ * @example
+ * ```ts
+ * import { renderReport } from "./report.js";
+ *
+ * // inventory: the value buildInventory (inventory.ts) returned for this run
+ * const markdown = renderReport(inventory, "Next: run the plugin's own /customize.");
+ * // "...## Next step\n\nRun the plugin's own /customize. It reads this report..."
+ * ```
+ */
+export function renderReport(inventory, nextStep) {
     const sections = [
         "# Adoption report",
         "",
@@ -305,13 +392,14 @@ export function renderReport(inventory) {
         "",
         "## Next step",
         "",
-        "Open this project in Claude Code and run `/customize`. It reads this " +
+        `${nextStepLead(nextStep)} It reads this ` +
             "report and `.groundwork/inventory.json`, does a deeper read of " +
             "anything above marked as needing one, and asks you to confirm before " +
             "changing anything. Did this report miss something about your " +
             "project? Say so when `/customize` asks -- that confirmation round " +
             "is the point where it's caught.",
         "",
+        ...renderStagedFilesNote(inventory.stagedBaseline, inventory.stagedPacks),
         "`.groundwork/` itself was not added to this project's `.gitignore` -- " +
             "that choice is yours. It's disposable (regenerate it any time by " +
             "re-running the CLI), so most projects gitignore it; some prefer to " +

package/dist/staging.d.ts

@@ -0,0 +1,176 @@
+import type { TokenTable } from "./tokens.js";
+export { toPosixPath } from "./assets.js";
+/**
+ * The suffix every staged file carries, so no extension-based glob
+ * (`**\/*.ts`, `**\/*.md`, `vitest.config.*`) ever matches a staged copy.
+ *
+ * @example
+ * ```ts
+ * const staged = `eslint.config.js${STAGED_SUFFIX}`; // "eslint.config.js.staged"
+ * ```
+ */
+export declare const STAGED_SUFFIX = ".staged";
+/**
+ * The staged name for a project-relative `path`: `path` + {@link STAGED_SUFFIX}.
+ * The single derivation every stager and adopt mode's write-scope check use.
+ *
+ * @example
+ * ```ts
+ * stagedNameFor("src/index.ts"); // "src/index.ts.staged"
+ * ```
+ */
+export declare function stagedNameFor(path: string): string;
+/**
+ * Finds the first pair of staged paths that would land on the same file on
+ * some supported file system: two paths equal once folded -- NFC-normalized
+ * (macOS's APFS treats a precomposed `é` and `e` + U+0301 as one name) and
+ * case-folded (macOS and Windows default to case-insensitive) -- or one path
+ * a proper directory prefix of another once folded (`x.staged` as both a
+ * file and the directory holding `x.staged/y.staged`). Either collision
+ * makes the second exclusive (`wx`) write fail mid-staging; a plan checks
+ * for it first so the defect surfaces as its own error instead. Folding is
+ * `toLowerCase()` after `normalize("NFC")`, not a full Unicode case fold, so
+ * it is a best-effort approximation of each file system's own rules. Paths
+ * are otherwise compared as given -- pass them `/`-separated
+ * ({@link toPosixPath}).
+ *
+ * @returns A description naming both colliding paths, or `undefined` when
+ * none collide.
+ *
+ * @example
+ * ```ts
+ * findStagedPathCollision(["README.md.staged", "readme.md.staged"]); // "README.md.staged and readme.md.staged …"
+ * findStagedPathCollision(["a.staged", "b.staged"]); // undefined
+ * ```
+ */
+export declare function findStagedPathCollision(stagedPaths: readonly string[]): string | undefined;
+/**
+ * Maps every file under `root` to its install path (tokens applied, dotfile
+ * name restored) -- the same derivation `planConflicts` uses -- keyed by
+ * install path, valued by absolute source path.
+ *
+ * @throws `Error` (no `cause`) naming the install path and both sources when
+ * two files map to the same install path (`_gitignore` beside `.gitignore`),
+ * rather than silently letting the later one win.
+ *
+ * @example
+ * ```ts
+ * const files = collectTemplateFiles("/repo/templates/core", { PROJECT_NAME: "acme" });
+ * files.get(".gitignore"); // "/repo/templates/core/_gitignore"
+ * ```
+ */
+export declare function collectTemplateFiles(root: string, tokens: TokenTable): Map<string, string>;
+/**
+ * Refuses a staging plan computed for a different `.groundwork/` than the
+ * one a stager was handed: the plan's scope-checked paths would otherwise
+ * not be the paths written. Directories are compared after `path.resolve`,
+ * so two spellings of one directory match. A caller defect, so a plain
+ * `Error` (never an `AssertionError`), thrown before anything is written.
+ *
+ * @throws `Error` naming both directories when they differ.
+ *
+ * @example
+ * ```ts
+ * assertPlanBuiltFor("stagePacks", plan.groundworkDir, groundworkDir);
+ * ```
+ */
+export declare function assertPlanBuiltFor(caller: string, planGroundworkDir: string, groundworkDir: string): void;
+/**
+ * One staging area under `.groundwork/`: the directory `dirName` that
+ * {@link stageAtomically} writes, and the `noun` its messages use.
+ *
+ * @example
+ * ```ts
+ * const target: StagingTarget = {
+ *   groundworkDir: "/work/app/.groundwork",
+ *   dirName: "packs",
+ *   noun: "packs",
+ *   plural: true,
+ * };
+ * ```
+ */
+export interface StagingTarget {
+    /** The `.groundwork/` directory the staging area lives in. */
+    readonly groundworkDir: string;
+    /** The staging directory's name under `groundworkDir`; its work directories are named `.<dirName>-XXXXXX`. */
+    readonly dirName: string;
+    /** What is being staged, for messages: `"baseline"`, `"packs"`. */
+    readonly noun: string;
+    /** Whether `noun` takes a plural verb in messages ("the previous packs were", not "was"). */
+    readonly plural: boolean;
+}
+/**
+ * The first step of every staging run: refuses a symlinked `groundworkDir`
+ * or `<groundworkDir>/<dirName>` (before anything is deleted or written),
+ * then sweeps the `.<dirName>-*` work directories a crashed earlier run
+ * left. The sweep removes **every** entry of the CLI-owned `.groundwork/`
+ * whose name matches `.<dirName>-*`, whatever created it -- including a
+ * concurrent run's in-progress work directory, so two runs against the same
+ * directory can fail each other with the standard incomplete/re-run error;
+ * a failure to remove one only warns. Returns the staging directory's path.
+ *
+ * @throws `Error` naming the path when either directory is a symlink; the
+ * standard `.groundwork/ is incomplete -- re-run` `Error`, with `cause`, when
+ * `groundworkDir` cannot be listed for the sweep.
+ *
+ * @example
+ * ```ts
+ * const destDir = prepareStaging({ groundworkDir, dirName: "packs", noun: "packs", plural: true });
+ * ```
+ */
+export declare function prepareStaging(target: StagingTarget): string;
+/**
+ * Removes the staging directory outright -- what a run with nothing to
+ * stage does, so no previous staging outlives it.
+ *
+ * @throws {@link incompleteStagingError}, with the removal failure as `cause`.
+ *
+ * @example
+ * ```ts
+ * clearStaging({ groundworkDir, dirName: "packs", noun: "packs" });
+ * ```
+ */
+export declare function clearStaging(target: StagingTarget): void;
+/**
+ * Writes `bytes` to `<rootDir>/<stagedName>` with the exclusive `wx` flag
+ * (creating parent directories) and returns their lowercase hex sha256.
+ * Re-asserts the CWE-22 containment invariant (docs/assurance-case.md)
+ * against the directory actually written to; the caller's plan must already
+ * have refused an escaping name.
+ *
+ * @throws `AssertionError` (message prefixed by `caller`) when the staged
+ * path escapes `rootDir`; any write error unchanged.
+ *
+ * @example
+ * ```ts
+ * const sha256 = writeStagedBytes("stagePacks", bytes, newDir, "pack.json.staged");
+ * ```
+ */
+export declare function writeStagedBytes(caller: string, bytes: Uint8Array, rootDir: string, stagedName: string): string;
+/**
+ * Runs `write` against a fresh `<groundworkDir>/.<dirName>-XXXXXX/<dirName>`
+ * directory and, only once it returns, swaps that directory over
+ * `<groundworkDir>/<dirName>` by rename -- so a failure part-way through
+ * leaves any previous staging intact, and a previous staging is replaced
+ * wholesale. Call {@link prepareStaging} first.
+ *
+ * - If the swap's final rename fails, the previous staging is renamed back.
+ *   Only if that restore also fails is the staging directory left absent:
+ *   the previous staging then survives, parked inside the work directory,
+ *   which is deliberately not removed (a later run's stale-dir sweep does).
+ * - The work directory is otherwise always removed; a failure to remove it
+ *   only warns, naming its path.
+ *
+ * @throws {@link ParkedStagingError} when both renames fail; an
+ * `AssertionError` unwrapped (a broken invariant is a bug, not something a
+ * re-run fixes); otherwise {@link incompleteStagingError} with `cause`.
+ *
+ * @example
+ * ```ts
+ * const files = stageAtomically(target, (newDir) =>
+ *   [writeStagedBytes("stagePacks", bytes, newDir, "a.txt.staged")],
+ * );
+ * ```
+ */
+export declare function stageAtomically<T>(target: StagingTarget, write: (newDir: string) => T): T;
+//# sourceMappingURL=staging.d.ts.map