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

package/dist/merge-json.d.ts

@@ -6,9 +6,41 @@
  * YAML or JavaScript. Every merge is append-only (it never rebuilds an
  * object wholesale, which would risk reordering keys Prettier would
  * otherwise preserve) and idempotent (merging the same fragment twice
- * produces the same result as merging it once).
+ * produces the same result as merging it once). Every key taken from a
+ * caller fragment is checked against `__proto__`/`constructor`/`prototype`
+ * ({@link isPrototypeSensitiveKey}) before it is read or written, and such a
+ * key is rejected with a thrown error rather than merged. For a pack's wiring
+ * this merge-time check is defence in depth: `packs.ts`'s `loadPack` already
+ * refuses the same keys in `wiring.settings`, `wiring.settingsTopLevel` and
+ * `wiring.packageScripts` before fresh mode writes anything and before adopt
+ * mode touches `.groundwork/`. Adopt mode's CLI never calls these merges at
+ * all -- `/customize` applies a staged pack's wiring by hand, so the guard
+ * that covers that path is `loadPack`'s refusal to stage such a pack, not
+ * this module. The hazard this closes is local, not global: assigning
+ * `obj["__proto__"] = v` on the spread-copied plain objects these merges build
+ * swaps _that object's own_ prototype instead of creating an own key, so
+ * `JSON.stringify` later drops the key without a word. It never reached the
+ * shared `Object.prototype`; CWE-1321 is cited only because that is how the
+ * weakness is catalogued.
  */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * True when `key` is exactly `__proto__`, `constructor` or `prototype` -- the
+ * names every merge in this module refuses to take from a caller fragment.
+ * This is the single source of truth for that list: `packs.ts`'s `loadPack`
+ * calls it to reject such a key in a pack's wiring before either CLI mode
+ * writes anything, and this module's own merges check the same list again at
+ * merge time as defence in depth. The match is exact and case-sensitive.
+ *
+ * @example
+ * ```ts
+ * import { isPrototypeSensitiveKey } from "./merge-json.js";
+ *
+ * isPrototypeSensitiveKey("__proto__"); // true
+ * isPrototypeSensitiveKey("statusLine"); // false
+ * ```
+ */
+export declare function isPrototypeSensitiveKey(key: string): boolean;
 interface SettingsHookCommand {
     type: string;
     command: string;
@@ -27,7 +59,10 @@ export type SettingsHooksFragment = Record<string, SettingsHookEntry[]>;
  * entry, only `hooks` commands not already present (compared by exact
  * `command` string) are appended. A command that matches on `command` but
  * differs in its other fields (`if`, `timeout`) is a hard collision, never
- * a silent overwrite.
+ * a silent overwrite. An event name of `__proto__`, `constructor` or
+ * `prototype` throws: the check runs per key inside the loop, before that
+ * key is read or written, and nothing escapes the failed merge -- `existing`
+ * is never mutated and no partial result is returned.
  */
 export declare function mergeSettingsHooks(existing: unknown, fragment: SettingsHooksFragment): Record<string, unknown>;
 export type SettingsTopLevelFragment = Record<string, unknown>;
@@ -39,7 +74,11 @@ export type SettingsTopLevelFragment = Record<string, unknown>;
  * silently clobbering it. A key not yet present is appended; one already
  * present with an identical value is a no-op; one present with a different
  * value is a hard collision, never a silent overwrite -- an adopted project's
- * own `statusLine` is the user's to replace deliberately.
+ * own `statusLine` is the user's to replace deliberately. A fragment key of
+ * `__proto__`, `constructor` or `prototype` throws: the check runs per key
+ * inside the loop, before that key is read or written, and nothing escapes the
+ * failed merge -- `existing` is never mutated and no partial result is
+ * returned.
  */
 export declare function mergeSettingsTopLevel(existing: unknown, fragment: SettingsTopLevelFragment): Record<string, unknown>;
 interface ScriptCollision {
@@ -55,7 +94,11 @@ export interface MergePackageScriptsResult {
  * Merges a pack's `package.json` script additions into the existing
  * `scripts` block. Never overwrites a differing existing script -- the
  * collision is returned for the caller to report, consistent with adopt
- * mode's "report, then the user decides per conflict" policy.
+ * mode's "report, then the user decides per conflict" policy. An addition
+ * named `__proto__`, `constructor` or `prototype` is not a collision: it
+ * throws. The check runs per key inside the loop, before that key is read or
+ * written, and nothing escapes the failed merge -- `existing` is never mutated
+ * and no partial result is returned.
  */
 export declare function mergePackageScripts(existing: Record<string, string> | undefined, additions: Record<string, string>): MergePackageScriptsResult;
 export interface VerifyStepAddition {

package/dist/merge-json.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Pure, deterministic merges over parsed JSON -- the entire mechanism that
  * lets a pack extend `.claude/settings.json` (its `hooks` block and a few
@@ -6,11 +8,102 @@
  * YAML or JavaScript. Every merge is append-only (it never rebuilds an
  * object wholesale, which would risk reordering keys Prettier would
  * otherwise preserve) and idempotent (merging the same fragment twice
- * produces the same result as merging it once).
+ * produces the same result as merging it once). Every key taken from a
+ * caller fragment is checked against `__proto__`/`constructor`/`prototype`
+ * ({@link isPrototypeSensitiveKey}) before it is read or written, and such a
+ * key is rejected with a thrown error rather than merged. For a pack's wiring
+ * this merge-time check is defence in depth: `packs.ts`'s `loadPack` already
+ * refuses the same keys in `wiring.settings`, `wiring.settingsTopLevel` and
+ * `wiring.packageScripts` before fresh mode writes anything and before adopt
+ * mode touches `.groundwork/`. Adopt mode's CLI never calls these merges at
+ * all -- `/customize` applies a staged pack's wiring by hand, so the guard
+ * that covers that path is `loadPack`'s refusal to stage such a pack, not
+ * this module. The hazard this closes is local, not global: assigning
+ * `obj["__proto__"] = v` on the spread-copied plain objects these merges build
+ * swaps _that object's own_ prototype instead of creating an own key, so
+ * `JSON.stringify` later drops the key without a word. It never reached the
+ * shared `Object.prototype`; CWE-1321 is cited only because that is how the
+ * weakness is catalogued.
  */
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * Structural equality over parsed JSON: leaves by `Object.is`, arrays by
+ * length and per-index recursion, plain objects by the same key set (in any
+ * order) and per-key recursion. Unlike comparing `JSON.stringify` output, two
+ * objects whose keys were merely inserted in a different order are equal --
+ * which is what separates an idempotent re-merge from a real collision.
+ *
+ * @example
+ * ```ts
+ * deepEqual({ a: 1, b: [2] }, { b: [2], a: 1 }); // true
+ * deepEqual([1, 2], [2, 1]); // false
+ * ```
+ */
+function deepEqual(a, b) {
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return (Array.isArray(a) &&
+            Array.isArray(b) &&
+            a.length === b.length &&
+            a.every((item, index) => deepEqual(item, b[index])));
+    }
+    if (isRecord(a) && isRecord(b)) {
+        const aKeys = Object.keys(a);
+        return (aKeys.length === Object.keys(b).length &&
+            aKeys.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key])));
+    }
+    return Object.is(a, b);
+}
+/**
+ * Key names {@link isPrototypeSensitiveKey} matches and {@link assertSafeKey}
+ * rejects. A three-name denylist is complete here, not an allowlist, because
+ * every key comes from a caller fragment merged onto a plain object, where
+ * `__proto__` is the only key with special setter behaviour; `constructor`
+ * and `prototype` are defence in depth.
+ */
+const PROTOTYPE_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * True when `key` is exactly `__proto__`, `constructor` or `prototype` -- the
+ * names every merge in this module refuses to take from a caller fragment.
+ * This is the single source of truth for that list: `packs.ts`'s `loadPack`
+ * calls it to reject such a key in a pack's wiring before either CLI mode
+ * writes anything, and this module's own merges check the same list again at
+ * merge time as defence in depth. The match is exact and case-sensitive.
+ *
+ * @example
+ * ```ts
+ * import { isPrototypeSensitiveKey } from "./merge-json.js";
+ *
+ * isPrototypeSensitiveKey("__proto__"); // true
+ * isPrototypeSensitiveKey("statusLine"); // false
+ * ```
+ */
+export function isPrototypeSensitiveKey(key) {
+    return PROTOTYPE_KEYS.has(key);
+}
+/**
+ * Throws when `key` (taken from a caller fragment) is one of the
+ * prototype-sensitive names {@link isPrototypeSensitiveKey} matches. `context`
+ * names the merge in the error message.
+ *
+ * Only `__proto__` is actually exploitable here: on a plain object,
+ * `obj["__proto__"] = v` invokes the inherited setter, swapping that one
+ * object's prototype rather than storing an own key, so the value is silently
+ * dropped by `JSON.stringify` (the shape CWE-1321 catalogues, though nothing
+ * global is polluted). `constructor` and `prototype` assign as ordinary own
+ * keys on a plain object; they are rejected anyway as cheap defence in depth,
+ * since no shipped pack uses either name.
+ */
+function assertSafeKey(key, context) {
+    if (isPrototypeSensitiveKey(key)) {
+        throw new Error(`${context} merge: refusing prototype-sensitive key "${key}"`);
+    }
+}
 /**
  * Merges a pack's `.claude/settings.json` hook fragment into an existing
  * settings object. Per event, an entry is matched by `matcher` (both absent
@@ -18,7 +111,10 @@ export function isRecord(value) {
  * entry, only `hooks` commands not already present (compared by exact
  * `command` string) are appended. A command that matches on `command` but
  * differs in its other fields (`if`, `timeout`) is a hard collision, never
- * a silent overwrite.
+ * a silent overwrite. An event name of `__proto__`, `constructor` or
+ * `prototype` throws: the check runs per key inside the loop, before that
+ * key is read or written, and nothing escapes the failed merge -- `existing`
+ * is never mutated and no partial result is returned.
  */
 export function mergeSettingsHooks(existing, fragment) {
     const settings = isRecord(existing)
@@ -29,6 +125,7 @@ export function mergeSettingsHooks(existing, fragment) {
         ? { ...existingHooks }
         : {};
     for (const [event, entries] of Object.entries(fragment)) {
+        assertSafeKey(event, "settings.json hooks");
         const existingEntries = Array.isArray(hooks[event])
             ? [...hooks[event]]
             : [];
@@ -46,7 +143,7 @@ export function mergeSettingsHooks(existing, fragment) {
             for (const hookCmd of entry.hooks) {
                 const duplicate = mergedHooks.find((candidate) => candidate.command === hookCmd.command);
                 if (duplicate) {
-                    if (JSON.stringify(duplicate) !== JSON.stringify(hookCmd)) {
+                    if (!deepEqual(duplicate, hookCmd)) {
                         throw new Error(`settings.json merge collision: "${event}" (matcher ${JSON.stringify(entry.matcher)}) already has a hook for "${hookCmd.command}" with different config`);
                     }
                     continue; // Identical entry already present -- idempotent no-op.
@@ -67,13 +164,18 @@ export function mergeSettingsHooks(existing, fragment) {
  * silently clobbering it. A key not yet present is appended; one already
  * present with an identical value is a no-op; one present with a different
  * value is a hard collision, never a silent overwrite -- an adopted project's
- * own `statusLine` is the user's to replace deliberately.
+ * own `statusLine` is the user's to replace deliberately. A fragment key of
+ * `__proto__`, `constructor` or `prototype` throws: the check runs per key
+ * inside the loop, before that key is read or written, and nothing escapes the
+ * failed merge -- `existing` is never mutated and no partial result is
+ * returned.
  */
 export function mergeSettingsTopLevel(existing, fragment) {
     const settings = isRecord(existing)
         ? { ...existing }
         : {};
     for (const [key, value] of Object.entries(fragment)) {
+        assertSafeKey(key, "settings.json");
         if (key === "hooks") {
             throw new Error('settings.json merge: "hooks" is owned by mergeSettingsHooks and cannot be set as a top-level key');
         }
@@ -81,7 +183,7 @@ export function mergeSettingsTopLevel(existing, fragment) {
             settings[key] = value;
             continue;
         }
-        if (JSON.stringify(settings[key]) !== JSON.stringify(value)) {
+        if (!deepEqual(settings[key], value)) {
             throw new Error(`settings.json merge collision: "${key}" is already set with a different value`);
         }
         // Identical value already present -- idempotent no-op.
@@ -92,13 +194,23 @@ export function mergeSettingsTopLevel(existing, fragment) {
  * Merges a pack's `package.json` script additions into the existing
  * `scripts` block. Never overwrites a differing existing script -- the
  * collision is returned for the caller to report, consistent with adopt
- * mode's "report, then the user decides per conflict" policy.
+ * mode's "report, then the user decides per conflict" policy. An addition
+ * named `__proto__`, `constructor` or `prototype` is not a collision: it
+ * throws. The check runs per key inside the loop, before that key is read or
+ * written, and nothing escapes the failed merge -- `existing` is never mutated
+ * and no partial result is returned.
  */
 export function mergePackageScripts(existing, additions) {
     const scripts = { ...(existing ?? {}) };
     const collisions = [];
     for (const [name, cmd] of Object.entries(additions)) {
-        const currentValue = scripts[name];
+        assertSafeKey(name, "package.json scripts");
+        // Object.hasOwn, not `scripts[name] !== undefined`: bracket access walks
+        // the prototype chain, so an addition named `toString`/`valueOf`
+        // would otherwise "collide" with an inherited Object.prototype member.
+        const currentValue = Object.hasOwn(scripts, name)
+            ? scripts[name]
+            : undefined;
         if (currentValue !== undefined) {
             if (currentValue !== cmd) {
                 collisions.push({ name, existing: currentValue, incoming: cmd });
@@ -125,7 +237,7 @@ export function mergeVerifySteps(existing, additions) {
             continue;
         }
         const existingStep = current[existingIndex];
-        if (JSON.stringify(existingStep) !== JSON.stringify(step)) {
+        if (!deepEqual(existingStep, step)) {
             throw new Error(`verify-steps.packs.json merge collision: step "${step.id}" is already registered with different config`);
         }
         // Identical entry already present -- idempotent no-op.

package/dist/mode.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Decides whether the CLI is writing a fresh project into an empty directory
  * or adopting an already-established one. Adopt mode never overwrites
@@ -21,8 +23,16 @@ export function detectMode(dir) {
     if (entries.some((entry) => entry.isFile() && entry.name === "package.json")) {
         return { mode: "adopt", signal: "found package.json" };
     }
-    if (entries.some((entry) => entry.isDirectory() && entry.name === ".git")) {
-        return { mode: "adopt", signal: "found a .git directory" };
+    // A worktree or submodule checkout has `.git` as a file (`gitdir: <path>`),
+    // not a directory -- both mean an established repository.
+    const gitEntry = entries.find((entry) => entry.name === ".git");
+    if (gitEntry !== undefined) {
+        return {
+            mode: "adopt",
+            signal: gitEntry.isDirectory()
+                ? "found a .git directory"
+                : "found a .git file (a worktree or submodule)",
+        };
     }
     const looseSource = entries.find((entry) => entry.isFile() && LOOSE_SOURCE_EXTENSIONS.has(extname(entry.name)));
     if (looseSource !== undefined) {

package/dist/pack-stage.d.ts

@@ -0,0 +1,210 @@
+import type { Pack } from "./packs.js";
+import type { TokenTable } from "./tokens.js";
+/**
+ * The project-relative directory every pack is staged under; a pack's own
+ * staging directory is `${STAGED_PACKS_DIR}/<name>`.
+ *
+ * @example
+ * ```ts
+ * const dir = `${STAGED_PACKS_DIR}/quality`; // ".groundwork/packs/quality"
+ * ```
+ */
+export declare const STAGED_PACKS_DIR: string;
+/**
+ * The install name of a pack's manifest; it is staged as
+ * `pack.json` + `.staged` beside the pack's `files/` directory.
+ *
+ * @example
+ * ```ts
+ * const staged = `${STAGED_PACK_MANIFEST}.staged`; // "pack.json.staged"
+ * ```
+ */
+export declare const STAGED_PACK_MANIFEST = "pack.json";
+/**
+ * One staged pack file: its install path, its staged name, and the sha256 of
+ * the staged bytes, so `/customize` can verify the copy it installs.
+ *
+ * @example
+ * ```ts
+ * const file: StagedPackFile = {
+ *   path: ".claude/hooks/guard-readonly-bash.mjs",
+ *   staged: ".claude/hooks/guard-readonly-bash.mjs.staged",
+ *   sha256: "e3b0c442...", // hex digest of the staged bytes
+ * };
+ * ```
+ */
+export interface StagedPackFile {
+    /** The project-relative path the file installs to (for the manifest: `pack.json`). */
+    path: string;
+    /** The staged file's name: `path` + `.staged`, relative to the pack's `files/` directory (for the manifest: to the pack's own directory). */
+    staged: string;
+    /** Lowercase hex sha256 of the staged bytes. */
+    sha256: string;
+}
+/**
+ * One staged pack, as recorded in `inventory.json`'s `stagedPacks`.
+ *
+ * @example
+ * ```ts
+ * const pack: StagedPack = {
+ *   name: "quality",
+ *   dir: ".groundwork/packs/quality",
+ *   suffix: ".staged",
+ *   manifest: { path: "pack.json", staged: "pack.json.staged", sha256: "…" },
+ *   files: [{ path: "bin/check-file-budget.mjs", staged: "bin/check-file-budget.mjs.staged", sha256: "…" }],
+ * };
+ * ```
+ */
+export interface StagedPack {
+    /** The pack's manifest name, also its directory name under {@link STAGED_PACKS_DIR}. */
+    name: string;
+    /** The pack's project-relative staging directory, `/`-separated: `.groundwork/packs/<name>`. */
+    dir: string;
+    /** The suffix every staged name carries: `.staged`. */
+    suffix: string;
+    /** The staged `pack.json`, at `<dir>/pack.json.staged`. */
+    manifest: StagedPackFile;
+    /** The pack's `files/` tree, each at `<dir>/files/<staged>`, sorted by `path`. */
+    files: StagedPackFile[];
+}
+/**
+ * The validated plan for one {@link stagePacks} run: every path it would
+ * write, plus everything it needs to write them -- each pack's serialized
+ * manifest and its files' install paths and sources -- so staging never
+ * re-walks a pack's `files/` tree. Built by {@link planPackStaging}.
+ *
+ * @example
+ * ```ts
+ * import { planPackStaging, stagePacks } from "./pack-stage.js";
+ * const plan = planPackStaging(packs, groundworkDir, tokens);
+ * stagePacks(packs, groundworkDir, tokens, plan);
+ * ```
+ */
+export interface PackStagingPlan {
+    /** The `groundworkDir` the plan was computed for; {@link stagePacks} refuses the plan for any other. */
+    readonly groundworkDir: string;
+    /** Every path the run writes, under `<groundworkDir>/packs/`: per pack, its `pack.json.staged`, then each `files/<path>.staged`. */
+    readonly paths: readonly string[];
+    /** Each pack's validated projection, in `packs` order: its name, serialized manifest, and each file's install path and source, sorted by path. */
+    readonly packs: readonly {
+        readonly name: string;
+        readonly manifestBytes: Buffer;
+        readonly files: readonly {
+            readonly path: string;
+            readonly sourcePath: string;
+        }[];
+    }[];
+}
+/**
+ * Validates `packs` and computes the plan {@link stagePacks} writes from:
+ * every path under `<groundworkDir>/packs/` -- each pack's
+ * `pack.json.staged` and every `files/<path>.staged` -- and each file's
+ * source, so adopt mode can scope-check `paths` before any pack is written
+ * and then hand the same plan to {@link stagePacks}. Reads the packs'
+ * source trees; writes nothing.
+ *
+ * @throws The same plan `Error`s as {@link stagePacks}.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * const plan = planPackStaging(packs, groundworkDir, tokens);
+ * assertAdoptWriteScope(targetDir, plan.paths);
+ * stagePacks(packs, groundworkDir, tokens, plan);
+ * ```
+ */
+export declare function planPackStaging(packs: readonly Pack[], groundworkDir: string, tokens: TokenTable): PackStagingPlan;
+/**
+ * Every path {@link stagePacks} would write for `packs` -- a thin wrapper
+ * returning {@link planPackStaging}'s `paths`. Reads the packs' source
+ * trees; writes nothing.
+ *
+ * @throws The same plan `Error`s as {@link stagePacks}.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * assertAdoptWriteScope(targetDir, plannedPackStagingPaths(packs, groundworkDir, tokens));
+ * ```
+ */
+export declare function plannedPackStagingPaths(packs: readonly Pack[], groundworkDir: string, tokens: TokenTable): string[];
+/**
+ * Stages every pack in `packs` into `<groundworkDir>/packs/`: for each, its
+ * manifest as `<name>/pack.json.staged` (`JSON.stringify(manifest, null, 2)`
+ * plus a newline) and every file of its `filesDir` tree as
+ * `<name>/files/<path>.staged`, copied byte-for-byte -- no token
+ * substitution into content, which is `/customize`'s job at install time.
+ * `tokens` only substitutes into install paths (and dotfile names are
+ * restored), the same derivation `planConflicts` uses. Recorded `path`/
+ * `staged` values use forward slashes; `dir` is the literal
+ * `.groundwork/packs/<name>`, whatever `groundworkDir` was passed.
+ *
+ * What is guaranteed:
+ * - The plan is validated first, before anything is deleted or written (or,
+ *   when `plan` is passed, was already validated by {@link planPackStaging}
+ *   and the packs' trees are not walked again): a pack name that is not a
+ *   single directory name, contains `:`, or is used by two packs (ignoring
+ *   case and Unicode normalization), a missing `filesDir`, two files in one
+ *   pack installing to the same path, an install path containing `:`, a
+ *   staged name that would escape its pack's staging directory, or two
+ *   staged names in one pack landing on the same file (equal once
+ *   NFC-normalized and case-folded, or one a directory prefix of the other)
+ *   throws its own
+ *   `Error`, leaving `.groundwork/` exactly as it was. A `filesDir` that
+ *   cannot be inspected (a permission error) throws a plan `Error` naming
+ *   the pack and path, with the failure as `cause`.
+ * - Then, still before anything is deleted or written, `groundworkDir` and
+ *   `<groundworkDir>/packs` are checked not to be symlinks, and every
+ *   `.packs-*` entry of the CLI-owned `groundworkDir` -- meant for work
+ *   directories a crashed earlier run left, but removed whatever created
+ *   it, so a concurrent run against the same directory can lose its
+ *   in-progress work directory and fail with the incomplete/re-run error
+ *   -- is removed (best effort; a failure to remove one only warns, a
+ *   failure to list `groundworkDir` throws). `.baseline-*`
+ *   entries are left alone.
+ * - When `packs` is empty, any previous `packs/` is removed and nothing is
+ *   created.
+ * - Otherwise every pack is written into one temporary `.packs-*` sibling
+ *   directory (each file created exclusively, `wx`) and swapped in by rename
+ *   only after every copy succeeded, so `packs/` is never half-written and a
+ *   failure leaves any previous `packs/` intact; a previous `packs/` is
+ *   replaced wholesale (a pack no longer passed, or a file a pack dropped,
+ *   does not linger).
+ * - With a previous `packs/`, the swap is two renames: the previous one is
+ *   parked inside the temporary directory, then the new one moved into
+ *   place. A process killed between the two leaves `packs/` absent and the
+ *   previous copy at `.packs-XXXXXX/previous`; the next run's sweep removes
+ *   it and regenerates the staging.
+ * - If the final swap rename fails, the previous `packs/` is renamed back.
+ *   Only if that restore also fails is `packs/` left absent: the previous
+ *   staging then survives, parked inside the temporary directory, which is
+ *   deliberately not removed (a later run's stale-dir sweep does).
+ * - The temporary directory is otherwise always removed; a failure to remove
+ *   it only warns, naming its path.
+ *
+ * @throws `Error` (no re-run advice; no `cause` except for an uninspectable
+ * `filesDir`) for an invalid plan, as above; `Error` before any delete or
+ * write when `groundworkDir` or
+ * `<groundworkDir>/packs` is a symlink; `AggregateError` of the swap and
+ * restore failures, naming where the previous `packs/` is parked, when both
+ * renames fail; the `AssertionError` itself, unwrapped, if the staged-path
+ * containment invariant ever fails while writing; otherwise an `Error` with
+ * `cause`, including the cause's message, saying `.groundwork/` is
+ * incomplete and the CLI should be re-run.
+ *
+ * @param plan - The plan {@link planPackStaging} computed for these same
+ * `packs`, `groundworkDir` and `tokens`; computed here when omitted. A plan
+ * whose `groundworkDir` resolves to a different directory throws a plain
+ * `Error` naming both ("the plan was built for …") before anything is
+ * deleted or written.
+ *
+ * @example
+ * ```ts
+ * import { listPackNames, loadPack } from "./packs.js";
+ * const packs = listPackNames().map((name) => loadPack(name));
+ * const staged = stagePacks(packs, "/work/app/.groundwork", { PROJECT_NAME: "app" });
+ * // staged[0]: { name: "github", dir: ".groundwork/packs/github", suffix: ".staged", … }
+ * ```
+ */
+export declare function stagePacks(packs: readonly Pack[], groundworkDir: string, tokens: TokenTable, plan?: PackStagingPlan): StagedPack[];
+//# sourceMappingURL=pack-stage.d.ts.map