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

package/dist/conflicts.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Compares `templates/core` (after token substitution) against a target
  * directory, file by file, without writing anything. `package.json` and any
@@ -5,10 +7,13 @@
  * a whole-file conflict on `package.json` is a useless finding, since the
  * answer is always a merge, never "pick one file wholesale".
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { basename, join, relative } from "node:path";
 import { restoreDotfilePath } from "./assets.js";
 import { parseJsonc } from "./jsonc.js";
+import { isRecord } from "./merge-json.js";
+import { blockedAbsentNote } from "./survey/internal/blocked-path.js";
+import { probePath, probeSubject, readFailure, recordedReadCode, unreadableNote, } from "./survey/internal/read-guard.js";
 import { applyTokens } from "./tokens.js";
 function isKeyLevelJsonFile(relPath) {
     const name = basename(relPath);
@@ -20,8 +25,14 @@ function compareJsonKeys(baselineContent, targetContent) {
     if (!baseline.ok || !target.ok) {
         return undefined;
     }
+    // Valid JSON need not be an object (`null`, a number, an array): a key-level
+    // compare is meaningless there, so take the same whole-file fallback as an
+    // unparseable file.
     const baselineValue = baseline.value;
     const targetValue = target.value;
+    if (!isRecord(baselineValue) || !isRecord(targetValue)) {
+        return undefined;
+    }
     const keys = new Set([
         ...Object.keys(baselineValue),
         ...Object.keys(targetValue),
@@ -34,11 +45,57 @@ function compareJsonKeys(baselineContent, targetContent) {
     }
     return diffs;
 }
-function compareFile(relPath, baselineContent, targetPath) {
-    if (!existsSync(targetPath)) {
-        return { relPath, status: "absent", keyDiffs: undefined };
+/**
+ * Appends `note` unless already present: adopt mode passes the survey's own
+ * list, and a pack and the baseline can name the same path.
+ */
+function recordOnce(undetermined, note) {
+    if (!undetermined.includes(note))
+        undetermined.push(note);
+}
+function compareFile(relPath, baselineContent, targetPath, targetDir, undetermined) {
+    // A real `stat`, never `existsSync`: a file under a directory this process
+    // cannot search must not read as "absent" (a clean add `/customize` would
+    // then write straight over). Something there this process cannot reach is
+    // divergent -- it cannot be shown identical, and adopt mode never
+    // overwrites -- with the errno recorded. Any other errno throws.
+    const probe = probePath(targetPath);
+    if (probe.kind === "absent") {
+        // `absent` also covers a dangling symlink at the path or an ancestor
+        // (`ENOENT`) and a regular file where an ancestor directory should be
+        // (`ENOTDIR`): both are something in the project's tree a write would
+        // have to go through, so they are divergent, recorded once, never a
+        // silent clean add.
+        const note = blockedAbsentNote(targetPath, targetDir);
+        if (note === undefined) {
+            return { relPath, status: "absent", keyDiffs: undefined };
+        }
+        recordOnce(undetermined, note);
+        return { relPath, status: "divergent", keyDiffs: undefined };
+    }
+    if (probe.kind === "unresolvable") {
+        // A permission failure names the enclosing directory (the `stat` needed
+        // search permission there, not on the file), so every baseline file
+        // under one locked directory shares a single note; a symlink loop names
+        // the path itself.
+        recordOnce(undetermined, unreadableNote(probeSubject(targetPath, probe.code), probe.code));
+        return { relPath, status: "divergent", keyDiffs: undefined };
+    }
+    // A read failure that is a property of the project's tree (a permission
+    // failure, a directory where the baseline has a file) is divergent too --
+    // it cannot be shown identical -- and is recorded naming the path, so the
+    // report never shows "divergent" with no reason behind it.
+    let targetContent;
+    try {
+        targetContent = readFileSync(targetPath, "utf8");
+    }
+    catch (error) {
+        const code = recordedReadCode(error);
+        if (code === undefined)
+            throw readFailure(targetPath, error);
+        recordOnce(undetermined, unreadableNote(targetPath, code));
+        return { relPath, status: "divergent", keyDiffs: undefined };
     }
-    const targetContent = readFileSync(targetPath, "utf8");
     if (isKeyLevelJsonFile(relPath)) {
         const keyDiffs = compareJsonKeys(baselineContent, targetContent);
         if (keyDiffs !== undefined) {
@@ -56,22 +113,43 @@ function compareFile(relPath, baselineContent, targetPath) {
         keyDiffs: undefined,
     };
 }
-function walkTemplate(root, currentDir, targetDir, tokens, results) {
+function walkTemplate(root, currentDir, targetDir, tokens, results, undetermined) {
     for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
         const sourcePath = join(currentDir, entry.name);
         const relPath = restoreDotfilePath(applyTokens(relative(root, sourcePath), tokens));
         if (entry.isDirectory()) {
-            walkTemplate(root, sourcePath, targetDir, tokens, results);
+            walkTemplate(root, sourcePath, targetDir, tokens, results, undetermined);
             continue;
         }
         const baselineContent = applyTokens(readFileSync(sourcePath, "utf8"), tokens);
-        results.push(compareFile(relPath, baselineContent, join(targetDir, relPath)));
+        results.push(compareFile(relPath, baselineContent, join(targetDir, relPath), targetDir, undetermined));
     }
 }
-/** Compares every file `templates/core` would emit against what `targetDir` already has. */
-export function planConflicts(templateRoot, targetDir, tokens) {
+/**
+ * Compares every file `templates/core` (or a pack's `files/`) would emit
+ * against what `targetDir` already has. A target path this process cannot
+ * reach (`EACCES`/`EPERM`/`ELOOP`) is never reported `absent`: it is
+ * `divergent`, and a note naming the errno is appended to `undetermined`
+ * once (adopt mode passes the survey's own list, so the report shows it) --
+ * naming the enclosing directory for a permission failure on the `stat`, the
+ * path itself for a symlink loop, or for a permission failure or a
+ * directory-where-a-file-was-expected (`EISDIR`) on the read. A dangling
+ * symlink at the target path is `divergent` too, recorded naming the path;
+ * so is a dangling symlink at one of its ancestors below `targetDir`,
+ * recorded once naming that ancestor. A regular file where an enclosing
+ * directory should be (`ENOTDIR`) is `divergent`, recorded once naming that
+ * blocking ancestor. A genuinely missing path is `absent`; any other errno
+ * throws.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const conflicts = planConflicts(templateRoot, targetDir, tokens, undetermined);
+ * ```
+ */
+export function planConflicts(templateRoot, targetDir, tokens, undetermined = []) {
     const results = [];
-    walkTemplate(templateRoot, templateRoot, targetDir, tokens, results);
+    walkTemplate(templateRoot, templateRoot, targetDir, tokens, results, undetermined);
     return results;
 }
 //# sourceMappingURL=conflicts.js.map

package/dist/customize-paths.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The skill's entry file: the one payload file that lives under the plugin
+ * source's `skills/customize/` (every other one lives under its `src/`), and
+ * the one whose presence makes Claude Code load the skill -- which is why
+ * {@link CUSTOMIZE_SKILL_WRITE_ORDER} writes it last.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_ENTRY_FILE } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_ENTRY_FILE; // "SKILL.md"
+ * ```
+ */
+export declare const CUSTOMIZE_SKILL_ENTRY_FILE = "SKILL.md";
+/**
+ * Every payload file's name inside an installed copy of the skill.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_FILE_NAMES } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_FILE_NAMES.includes("SKILL.md"); // true
+ * ```
+ */
+export declare const CUSTOMIZE_SKILL_FILE_NAMES: readonly ["SKILL.md", "kind-facet-map.ts", "domain-map.ts", "pack-map.ts", "plugin-map.ts"];
+/**
+ * The order an install writes the payload in: every backing-data file
+ * first, {@link CUSTOMIZE_SKILL_ENTRY_FILE} last. A run that fails part-way
+ * (and whose rollback cannot remove everything) therefore never leaves a
+ * loadable `SKILL.md` beside missing or stale data files -- given the
+ * precondition that no `SKILL.md` already sits at the destination. Wherever
+ * an install replaces existing entries -- fresh mode's
+ * `.claude/skills/customize/` (a `--force` re-run over an earlier install)
+ * and the CLI-owned `.groundwork/customize/` -- `plugin.ts` establishes that
+ * precondition by removing any existing `SKILL.md` entry before the first
+ * data file is rewritten. Adopt mode's additive `.claude/skills/customize/`
+ * install only ever writes there when no `SKILL.md` entry exists.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_WRITE_ORDER } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_WRITE_ORDER.at(-1); // "SKILL.md"
+ * ```
+ */
+export declare const CUSTOMIZE_SKILL_WRITE_ORDER: readonly ["kind-facet-map.ts", "domain-map.ts", "pack-map.ts", "plugin-map.ts", "SKILL.md"];
+/**
+ * The fresh-mode destination -- and adopt mode's, when nothing is there yet
+ * or an earlier install was interrupted before its `SKILL.md` -- as path
+ * segments relative to the project root.
+ *
+ * @example
+ * ```ts
+ * import { join } from "node:path";
+ * import { CLAUDE_DEST_SEGMENTS } from "./customize-paths.js";
+ *
+ * join(...CLAUDE_DEST_SEGMENTS); // ".claude/skills/customize"
+ * ```
+ */
+export declare const CLAUDE_DEST_SEGMENTS: readonly [".claude", "skills", "customize"];
+/**
+ * The adopt-mode fallback destination, as path segments relative to the
+ * project root. Used whenever {@link CLAUDE_DEST_SEGMENTS} cannot be written
+ * additively: a project-owned entry under any of the skill's payload names
+ * that is not this CLI's current copy (a differing file, a symlink, a
+ * directory, a `SKILL.md` without its data), or a component of
+ * `.claude/skills/customize` that is a symlink or not a directory.
+ *
+ * @example
+ * ```ts
+ * import { join } from "node:path";
+ * import { GROUNDWORK_DEST_SEGMENTS } from "./customize-paths.js";
+ *
+ * join(...GROUNDWORK_DEST_SEGMENTS); // ".groundwork/customize"
+ * ```
+ */
+export declare const GROUNDWORK_DEST_SEGMENTS: readonly [".groundwork", "customize"];
+/**
+ * Every path, relative to the project root, that either install location
+ * could write -- so a caller can scope-check them before anything is
+ * written.
+ *
+ * @example
+ * ```ts
+ * import { plannedCustomizeSkillPaths } from "./customize-paths.js";
+ *
+ * plannedCustomizeSkillPaths();
+ * // [".claude/skills/customize/SKILL.md", ..., ".groundwork/customize/plugin-map.ts"]
+ * ```
+ */
+export declare function plannedCustomizeSkillPaths(): readonly string[];
+//# sourceMappingURL=customize-paths.d.ts.map

package/dist/customize-paths.js

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * Where the `/customize` skill install (`plugin.ts`) writes, owned in one
+ * place so `main.ts`'s adopt-mode write-scope check can validate the planned
+ * destinations before `plugin.ts` writes anything. Pure data, no I/O.
+ */
+import { join } from "node:path";
+/**
+ * The skill's entry file: the one payload file that lives under the plugin
+ * source's `skills/customize/` (every other one lives under its `src/`), and
+ * the one whose presence makes Claude Code load the skill -- which is why
+ * {@link CUSTOMIZE_SKILL_WRITE_ORDER} writes it last.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_ENTRY_FILE } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_ENTRY_FILE; // "SKILL.md"
+ * ```
+ */
+export const CUSTOMIZE_SKILL_ENTRY_FILE = "SKILL.md";
+/** The backing-data payload files, all sourced from the plugin's `src/`. */
+const CUSTOMIZE_SKILL_DATA_FILE_NAMES = [
+    "kind-facet-map.ts",
+    "domain-map.ts",
+    "pack-map.ts",
+    "plugin-map.ts",
+];
+/**
+ * Every payload file's name inside an installed copy of the skill.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_FILE_NAMES } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_FILE_NAMES.includes("SKILL.md"); // true
+ * ```
+ */
+export const CUSTOMIZE_SKILL_FILE_NAMES = [
+    CUSTOMIZE_SKILL_ENTRY_FILE,
+    ...CUSTOMIZE_SKILL_DATA_FILE_NAMES,
+];
+/**
+ * The order an install writes the payload in: every backing-data file
+ * first, {@link CUSTOMIZE_SKILL_ENTRY_FILE} last. A run that fails part-way
+ * (and whose rollback cannot remove everything) therefore never leaves a
+ * loadable `SKILL.md` beside missing or stale data files -- given the
+ * precondition that no `SKILL.md` already sits at the destination. Wherever
+ * an install replaces existing entries -- fresh mode's
+ * `.claude/skills/customize/` (a `--force` re-run over an earlier install)
+ * and the CLI-owned `.groundwork/customize/` -- `plugin.ts` establishes that
+ * precondition by removing any existing `SKILL.md` entry before the first
+ * data file is rewritten. Adopt mode's additive `.claude/skills/customize/`
+ * install only ever writes there when no `SKILL.md` entry exists.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_WRITE_ORDER } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_WRITE_ORDER.at(-1); // "SKILL.md"
+ * ```
+ */
+export const CUSTOMIZE_SKILL_WRITE_ORDER = [
+    ...CUSTOMIZE_SKILL_DATA_FILE_NAMES,
+    CUSTOMIZE_SKILL_ENTRY_FILE,
+];
+/**
+ * The fresh-mode destination -- and adopt mode's, when nothing is there yet
+ * or an earlier install was interrupted before its `SKILL.md` -- as path
+ * segments relative to the project root.
+ *
+ * @example
+ * ```ts
+ * import { join } from "node:path";
+ * import { CLAUDE_DEST_SEGMENTS } from "./customize-paths.js";
+ *
+ * join(...CLAUDE_DEST_SEGMENTS); // ".claude/skills/customize"
+ * ```
+ */
+export const CLAUDE_DEST_SEGMENTS = [".claude", "skills", "customize"];
+/**
+ * The adopt-mode fallback destination, as path segments relative to the
+ * project root. Used whenever {@link CLAUDE_DEST_SEGMENTS} cannot be written
+ * additively: a project-owned entry under any of the skill's payload names
+ * that is not this CLI's current copy (a differing file, a symlink, a
+ * directory, a `SKILL.md` without its data), or a component of
+ * `.claude/skills/customize` that is a symlink or not a directory.
+ *
+ * @example
+ * ```ts
+ * import { join } from "node:path";
+ * import { GROUNDWORK_DEST_SEGMENTS } from "./customize-paths.js";
+ *
+ * join(...GROUNDWORK_DEST_SEGMENTS); // ".groundwork/customize"
+ * ```
+ */
+export const GROUNDWORK_DEST_SEGMENTS = [".groundwork", "customize"];
+/**
+ * Every path, relative to the project root, that either install location
+ * could write -- so a caller can scope-check them before anything is
+ * written.
+ *
+ * @example
+ * ```ts
+ * import { plannedCustomizeSkillPaths } from "./customize-paths.js";
+ *
+ * plannedCustomizeSkillPaths();
+ * // [".claude/skills/customize/SKILL.md", ..., ".groundwork/customize/plugin-map.ts"]
+ * ```
+ */
+export function plannedCustomizeSkillPaths() {
+    return [CLAUDE_DEST_SEGMENTS, GROUNDWORK_DEST_SEGMENTS].flatMap((segments) => CUSTOMIZE_SKILL_FILE_NAMES.map((name) => join(...segments, name)));
+}
+//# sourceMappingURL=customize-paths.js.map

package/dist/emit.d.ts

@@ -1,7 +1,56 @@
 import type { TokenTable } from "./tokens.js";
+/**
+ * True when `target`, once resolved, is `root` itself or lies inside it.
+ * Exact match or proper prefix plus a separator -- never a bare
+ * `startsWith`, which would wrongly accept a sibling path that merely shares
+ * `root`'s name as a prefix (e.g. `/foo/bar-evil` against `/foo/bar`).
+ *
+ * @example
+ * ```ts
+ * isPathContained("/foo/bar/x", "/foo/bar"); // true
+ * isPathContained("/foo/bar", "/foo/bar"); // true
+ * isPathContained("/foo/bar-evil/x", "/foo/bar"); // false
+ * ```
+ */
+export declare function isPathContained(target: string, root: string): boolean;
 export interface EmitResult {
     filesWritten: string[];
 }
-/** Recursively copies `sourceDir` into `targetDir`, applying `tokens`. */
+/**
+ * Refuses, before anything is written, when any destination that emitting
+ * each of `sourceDirs` into `targetDir` would touch is a symlink (dangling
+ * or not) or a non-directory where a directory is needed. `targetDir`
+ * itself and its ancestors are not checked -- only paths strictly below it.
+ * The error names the offending path and ends with fresh mode's single
+ * `--fresh --force` retry instruction; nothing is written either way.
+ *
+ * @throws `Error` naming the first offending destination path.
+ *
+ * @example
+ * ```ts
+ * import { assertSafeEmitDestinations, emitTemplate } from "./emit.js";
+ *
+ * // Validate the baseline AND a pack's payload before writing either.
+ * assertSafeEmitDestinations(["/tpl/core", "/tpl/packs/x/files"], "/work/app", {});
+ * emitTemplate("/tpl/core", "/work/app", {});
+ * ```
+ */
+export declare function assertSafeEmitDestinations(sourceDirs: readonly string[], targetDir: string, tokens: TokenTable): void;
+/**
+ * Recursively copies `sourceDir` into `targetDir`, applying `tokens`. Every
+ * destination is validated first (see {@link assertSafeEmitDestinations}),
+ * so a refusal writes nothing.
+ *
+ * @throws `Error` naming a symlinked or non-directory destination component.
+ *
+ * @example
+ * ```ts
+ * import { emitTemplate } from "./emit.js";
+ *
+ * const { filesWritten } = emitTemplate("/tpl/core", "/work/app", {
+ *   PROJECT_NAME: "app",
+ * });
+ * ```
+ */
 export declare function emitTemplate(sourceDir: string, targetDir: string, tokens: TokenTable): EmitResult;
 //# sourceMappingURL=emit.d.ts.map

package/dist/emit.js

@@ -1,35 +1,142 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Copies `templates/core` into a target directory, applying token
  * substitution to both file contents and path segments (so a token in a
  * directory or file NAME, not just its content, is honored). A published
  * tarball stores `.gitignore`/`.npmrc` as `_gitignore`/`_npmrc` (npm strips
  * the real names); they are restored here -- see `assets.ts`.
+ *
+ * Every destination path is planned and `lstat`-checked before the first
+ * write ({@link assertSafeEmitDestinations}), so a symlink or a misplaced
+ * file below the target refuses the whole emit rather than redirecting a
+ * write outside it.
  */
 import { readdirSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, } from "node:fs";
-import { join, relative, dirname, extname } from "node:path";
+import assert from "node:assert/strict";
+import { join, relative, dirname, extname, resolve, sep } from "node:path";
 import { restoreDotfilePath } from "./assets.js";
+import { assertDirectoryComponent, assertFileDestination, FRESH_SYMLINK_ADVICE, } from "./fs-guard.js";
 import { applyTokens } from "./tokens.js";
 // Extensions copied byte-for-byte, never text-decoded -- token substitution
 // only makes sense for text content.
 const BINARY_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".ico"]);
-/** Recursively copies `sourceDir` into `targetDir`, applying `tokens`. */
+/**
+ * True when `target`, once resolved, is `root` itself or lies inside it.
+ * Exact match or proper prefix plus a separator -- never a bare
+ * `startsWith`, which would wrongly accept a sibling path that merely shares
+ * `root`'s name as a prefix (e.g. `/foo/bar-evil` against `/foo/bar`).
+ *
+ * @example
+ * ```ts
+ * isPathContained("/foo/bar/x", "/foo/bar"); // true
+ * isPathContained("/foo/bar", "/foo/bar"); // true
+ * isPathContained("/foo/bar-evil/x", "/foo/bar"); // false
+ * ```
+ */
+export function isPathContained(target, root) {
+    const resolvedTarget = resolve(target);
+    const resolvedRoot = resolve(root);
+    return (resolvedTarget === resolvedRoot ||
+        resolvedTarget.startsWith(resolvedRoot + sep));
+}
+/** Every destination `sourceDir` would emit under `targetRoot`, in walk order (a directory before its contents). */
+function planEmit(sourceDir, targetRoot, tokens) {
+    const entries = [];
+    const visit = (currentSourceDir) => {
+        for (const entry of readdirSync(currentSourceDir, {
+            withFileTypes: true,
+        })) {
+            const sourcePath = join(currentSourceDir, entry.name);
+            const relPath = restoreDotfilePath(applyTokens(relative(sourceDir, sourcePath), tokens));
+            const targetPath = join(targetRoot, relPath);
+            // CWE-22 invariant (docs/assurance-case.md): a token value substituted
+            // into a path segment must never walk the write out of `targetRoot`.
+            assert.ok(isPathContained(targetPath, targetRoot), `emitTemplate: target path ${resolve(targetPath)} escapes ${resolve(targetRoot)}`);
+            const isDirectory = entry.isDirectory();
+            entries.push({ sourcePath, relPath, isDirectory });
+            if (isDirectory)
+                visit(sourcePath);
+        }
+    };
+    visit(sourceDir);
+    return entries;
+}
+/**
+ * `lstat`-checks every destination of `entries` under `targetRoot`: each
+ * directory component strictly below `targetRoot` must be missing or a real
+ * directory, and each destination file must not be a symlink. Ancestors are
+ * checked before descendants, so the topmost offending path is the one named.
+ */
+function assertPlanSafe(targetRoot, entries) {
+    const checked = new Set();
+    for (const { relPath, isDirectory } of entries) {
+        const segments = relPath.split(sep);
+        const dirCount = isDirectory ? segments.length : segments.length - 1;
+        for (let depth = 1; depth <= dirCount; depth++) {
+            const dirPath = join(targetRoot, ...segments.slice(0, depth));
+            if (checked.has(dirPath))
+                continue;
+            checked.add(dirPath);
+            assertDirectoryComponent(dirPath, FRESH_SYMLINK_ADVICE);
+        }
+        if (!isDirectory) {
+            assertFileDestination(join(targetRoot, relPath), FRESH_SYMLINK_ADVICE);
+        }
+    }
+}
+/**
+ * Refuses, before anything is written, when any destination that emitting
+ * each of `sourceDirs` into `targetDir` would touch is a symlink (dangling
+ * or not) or a non-directory where a directory is needed. `targetDir`
+ * itself and its ancestors are not checked -- only paths strictly below it.
+ * The error names the offending path and ends with fresh mode's single
+ * `--fresh --force` retry instruction; nothing is written either way.
+ *
+ * @throws `Error` naming the first offending destination path.
+ *
+ * @example
+ * ```ts
+ * import { assertSafeEmitDestinations, emitTemplate } from "./emit.js";
+ *
+ * // Validate the baseline AND a pack's payload before writing either.
+ * assertSafeEmitDestinations(["/tpl/core", "/tpl/packs/x/files"], "/work/app", {});
+ * emitTemplate("/tpl/core", "/work/app", {});
+ * ```
+ */
+export function assertSafeEmitDestinations(sourceDirs, targetDir, tokens) {
+    for (const sourceDir of sourceDirs) {
+        assertPlanSafe(targetDir, planEmit(sourceDir, targetDir, tokens));
+    }
+}
+/**
+ * Recursively copies `sourceDir` into `targetDir`, applying `tokens`. Every
+ * destination is validated first (see {@link assertSafeEmitDestinations}),
+ * so a refusal writes nothing.
+ *
+ * @throws `Error` naming a symlinked or non-directory destination component.
+ *
+ * @example
+ * ```ts
+ * import { emitTemplate } from "./emit.js";
+ *
+ * const { filesWritten } = emitTemplate("/tpl/core", "/work/app", {
+ *   PROJECT_NAME: "app",
+ * });
+ * ```
+ */
 export function emitTemplate(sourceDir, targetDir, tokens) {
+    const entries = planEmit(sourceDir, targetDir, tokens);
+    assertPlanSafe(targetDir, entries);
     const filesWritten = [];
-    walk(sourceDir, sourceDir, targetDir, tokens, filesWritten);
-    return { filesWritten };
-}
-function walk(root, currentSourceDir, targetRoot, tokens, filesWritten) {
-    for (const entry of readdirSync(currentSourceDir, { withFileTypes: true })) {
-        const sourcePath = join(currentSourceDir, entry.name);
-        const relPath = restoreDotfilePath(applyTokens(relative(root, sourcePath), tokens));
-        const targetPath = join(targetRoot, relPath);
-        if (entry.isDirectory()) {
+    for (const { sourcePath, relPath, isDirectory } of entries) {
+        const targetPath = join(targetDir, relPath);
+        if (isDirectory) {
             mkdirSync(targetPath, { recursive: true });
-            walk(root, sourcePath, targetRoot, tokens, filesWritten);
             continue;
         }
         mkdirSync(dirname(targetPath), { recursive: true });
-        if (BINARY_EXTENSIONS.has(extname(entry.name))) {
+        if (BINARY_EXTENSIONS.has(extname(sourcePath))) {
             copyFileSync(sourcePath, targetPath);
         }
         else {
@@ -38,5 +145,6 @@ function walk(root, currentSourceDir, targetRoot, tokens, filesWritten) {
         }
         filesWritten.push(relPath);
     }
+    return { filesWritten };
 }
 //# sourceMappingURL=emit.js.map

package/dist/fatal.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Reports a fatal `error`: sets the exit code first -- 2 when
+ * `isUsageError(error)` says it is a usage error, 1 otherwise, including
+ * when `isUsageError` itself throws -- then prints the report through
+ * `io.print`. For a usage error the report is exactly
+ * `formatErrorChain(error)`. For any other failure it is
+ * `formatFatalError(error, { withName: true, withStack: debug })` (both in
+ * `./format-error.ts`): the same chain, its top line prefixed `<name>: `
+ * when `error` is an `Error` with a readable, non-blank `name` other than
+ * `Error` and a non-blank message (`TypeError: boom`), and, when `debug` is
+ * set, the stack frames appended as `formatFatalError` describes
+ * (control-escaped, header dropped, capped at its `MAX_STACK_LINES`). Only
+ * the top error's own stack is printed: a `cause`'s stack is deliberately
+ * omitted, since the chain already names every cause. If that print
+ * throws, the fallbacks never touch `io.print` again (it is the channel
+ * that just failed -- in the CLI, the one that paints colour), so `print`
+ * is called exactly once: `io.printRaw` prints the same report, so the
+ * cause chain (and any name prefix and stack) survives a failing `print`;
+ * if that throws, `io.printRaw` prints `String(error.stack ?? error)`,
+ * control-escaped the same way the chain is (`escapeControls` in
+ * `./format-error.ts`); if that throws, `io.printRaw` prints
+ * `[unprintable error]`; if even that throws, gives up silently, the exit
+ * code already set. Never throws. A `setExitCode` that throws is swallowed
+ * and not retried -- the report is still attempted -- but it is not
+ * otherwise handled: assigning Node's `process.exitCode` cannot throw, so
+ * the CLI never hits that case.
+ *
+ * @param error - The value the CLI's `main()` threw.
+ * @param io - Where the exit code and the report go: `print` for the
+ * formatted chain, `printRaw` -- a plain write with nothing in it that can
+ * fail the way `print` did -- for all three fallbacks.
+ * @param isUsageError - Whether `error` is a bad invocation rather than a
+ * runtime failure.
+ * @param debug - Append the top error's own stack (never a cause's) to a
+ * runtime failure's report (never to a usage error's); defaults to `false`.
+ * The CLI sets it when `M3L_DEBUG` is non-empty.
+ *
+ * @example
+ * ```ts
+ * import { CliUsageError, main } from "./main.js";
+ * import { handleFatal } from "./fatal.js";
+ *
+ * try {
+ *   main(process.argv.slice(2));
+ * } catch (error) {
+ *   handleFatal(
+ *     error,
+ *     {
+ *       setExitCode: (code) => {
+ *         process.exitCode = code;
+ *       },
+ *       print: (text) => {
+ *         console.error(text);
+ *       },
+ *       printRaw: (text) => {
+ *         console.error(text);
+ *       },
+ *     },
+ *     (e) => e instanceof CliUsageError,
+ *     (process.env["M3L_DEBUG"] ?? "") !== "",
+ *   );
+ * }
+ * ```
+ */
+export declare function handleFatal(error: unknown, io: {
+    setExitCode(code: number): void;
+    print(text: string): void;
+    printRaw(text: string): void;
+}, isUsageError: (error: unknown) => boolean, debug?: boolean): void;
+//# sourceMappingURL=fatal.d.ts.map