@williamthorsen/overlay 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Thorsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,114 @@
-Placeholder for `@williamthorsen/overlay` — awaiting first release.
+<!-- section:release-notes -->
+## Release notes — v0.2.0 (2026-06-04)
+
+### 🎉 Features
+
+- Add chezmoi-backed overlay CLI with verify/create/force modes (#96)
+
+  Adds `overlay`, a command-line tool (installable as `@williamthorsen/overlay`) that brings a target directory into line with a directory of canonical scaffolding files — adding what's missing, removing what's been marked for deletion, and running any normalization steps. Three modes set how much it will change: `--verify` (the default) reports what's out of sync without touching anything; `--create` brings everything into line except files you've changed locally, which it will not overwrite; and `--force` brings everything into line and overwrites your local changes too. The same behavior is also available as a typed function for use from other TypeScript code.
+<!-- /section:release-notes -->
+
+# @williamthorsen/overlay
+
+Overlay a canonical set of scaffolding files onto a target directory you do not control, and idempotently converge it: create what is missing, delete what is declared for removal, run normalization scripts, and refuse to silently clobber content it does not own.
+
+Overlay is built on [chezmoi](https://www.chezmoi.io/), whose source-state model fits exactly — `dot_`-encoded filenames, `executable_`/`run_` attributes, and `--source`/`--destination` to drive any source tree into any target. Overlay adds three modes (`--verify`, `--create`, `--force`) computed from a parsed `chezmoi status`, plus one guarantee chezmoi lacks natively: `--create` never overwrites a differing managed file.
+
+## Installation
+
+Overlay shells out to the `chezmoi` binary, which must be on your `PATH`:
+
+```bash
+brew install chezmoi
+```
+
+Install overlay for personal use via npm or a local link:
+
+```bash
+pnpm add -g @williamthorsen/overlay
+# or, from a checkout:
+pnpm link --global
+```
+
+chezmoi `2.46.0` or later is required; overlay preflights the version and exits with an actionable error otherwise.
+
+## Usage
+
+```
+overlay <source-dir> [target-dir] [--verify|--create|--force] [--json] [--help]
+```
+
+- `<source-dir>` — a chezmoi source directory describing the files the target should have.
+- `[target-dir]` — the directory to converge (defaults to the current working directory).
+- Modes are mutually exclusive; the default is `--verify`.
+- `--json` prints the structured result instead of the text report.
+
+### Exit codes
+
+| Code | Meaning                                                                                                 |
+| ---- | ------------------------------------------------------------------------------------------------------- |
+| `0`  | Converged / clean.                                                                                      |
+| `1`  | Drift (`--verify`) or unresolved conflicts (`--create`).                                                |
+| `2`  | Hard error: chezmoi missing or below the minimum version, a `run_` script failed, or invalid arguments. |
+
+Exit `2` is deliberately distinct from drift so callers can tell a real failure apart from "the target has drifted".
+
+## Modes
+
+Each mode is computed from the **second (apply-side) column** of `chezmoi status`, whose codes overlay reads as:
+
+| Status code | Meaning                                       | `--verify`                                              | `--create`                       | `--force`         |
+| ----------- | --------------------------------------------- | ------------------------------------------------------- | -------------------------------- | ----------------- |
+| `A`         | addition (missing in target)                  | report drift                                            | create                           | create            |
+| `D`         | native removal (`.chezmoiremove` / `remove_`) | report drift                                            | delete                           | delete            |
+| `M`         | differing managed file                        | report drift                                            | **conflict** (never overwritten) | overwrite         |
+| `R`         | `run_` script will run                        | surfaced informationally; **never affects the verdict** | run (live output)                | run (live output) |
+
+`--create` and `--force` differ only in the differing-file (`M`) column: `--create` refuses to overwrite, `--force` overwrites.
+
+### `--verify`
+
+Read-only. Drift is any `A`/`M`/`D` row; overlay exits `1` if any exists, `0` otherwise. Pending `R` scripts are reported as "N script(s) would run" but never make verify fail.
+
+`--verify` confirms **file convergence, not script execution.** It cannot know what a `run_` script would do to the target, so it reports the script as pending and moves on.
+
+**Verify-enforceability guideline:** if you want `--verify` to enforce a deletion, express it as a chezmoi-native removal (`.chezmoiremove` or a `remove_` entry), which surfaces as a `D` row that verify counts as drift. Reserve `run_` scripts for imperative normalization that has no static target-state for verify to check.
+
+### Why overlay does not use `chezmoi verify` directly
+
+Overlay runs every chezmoi invocation with a **throwaway `--persistent-state`** (a temp file discarded after each run). Because chezmoi keeps no memory across runs, it always believes `run_once_` / `run_onchange_` scripts are still pending — so `chezmoi verify` exits non-zero on a fully file-converged target. Overlay therefore parses `chezmoi status` itself and ignores the `R` rows for the verdict, which is the only way to get a clean verify on a converged target.
+
+### `--create`
+
+Creates missing entries (`A`), performs native removals (`D`), runs `run_` scripts (`R`), and reports differing files (`M`) as conflicts that are **never written**. The fix-it hint suggests re-running with `--force` to overwrite.
+
+Mechanically, overlay applies only the `A`/`D` entries by **absolute target path** (`chezmoi apply --include=files,dirs,remove -- <abs paths>`), skipping that apply entirely when no `A`/`D` entries exist — a bare apply would converge every file and clobber the `M` entries the mode exists to protect. Scripts then run in a separate `--include=scripts` pass.
+
+### `--force`
+
+A full `chezmoi apply`: overwrite differing files, perform removals, run scripts. `conflicts` is always `0`.
+
+## How script results are surfaced
+
+Under `--create` / `--force`, `run_` script stdout and stderr stream **live to overlay's stderr** — keeping overlay's stdout clean for the text report or `--json`. `OverlayResult.scripts` records `{ ran, ok }`. A script that exits non-zero aborts chezmoi's apply; overlay maps that to exit `2` and surfaces chezmoi's diagnostic. chezmoi provides no per-script structured output, so overlay does not invent any.
+
+## Idempotency contract
+
+Because each invocation uses a throwaway persistent-state, chezmoi keeps no cross-run memory: `run_once_` / `run_onchange_` scripts effectively run on **every** `--create` / `--force`. Source `run_` scripts must therefore be **idempotent**. This is intentional — it keeps runs isolated, pollutes no host state, and behaves predictably across targets.
+
+## Source-state filename grammar
+
+Overlay uses chezmoi-native source-state filenames: `dot_` (a leading dot), `executable_` (executable bit), and `run_` (scripts, including `run_once_` / `run_onchange_` / `run_before_` / `run_after_`). Symlink overlays (`symlink_`) are deferred to a future `--link`.
+
+## Programmatic use
+
+The CLI is a thin shell over an importable core:
+
+```ts
+import { overlay } from '@williamthorsen/overlay';
+
+const result = await overlay({ source: './scaffold', target: './repo', mode: 'create' });
+// result: { mode, entries, scripts, counts, exitCode }
+```
+
+`overlay(options)` returns a structured `OverlayResult` — never printed text — so other TypeScript code can compose with it.

package/bin/overlay.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/bin/overlay.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('overlay: build output not found — run `pnpm run build` first\n');
+  } else {
+    process.stderr.write(`overlay: failed to load: ${error.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/esm/.cache

@@ -0,0 +1 @@
+c05d5373bd5fcaeff5cb8ae65a6e653dba2366f75d48de79c6cc6df67b7c9890

package/dist/esm/bin/overlay.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/bin/overlay.js

@@ -0,0 +1,3 @@
+import process from "node:process";
+import { run } from "./run.js";
+process.exit(await run(process.argv.slice(2)));

package/dist/esm/bin/parseArgs.d.ts

@@ -0,0 +1,11 @@
+import type { OverlayMode } from '../types.ts';
+export type ParsedCommand = {
+    kind: 'help';
+} | {
+    kind: 'run';
+    source: string;
+    target: string | undefined;
+    mode: OverlayMode;
+    json: boolean;
+};
+export declare function parseArgs(argv: string[]): ParsedCommand;

package/dist/esm/bin/parseArgs.js

@@ -0,0 +1,36 @@
+import { parseArgs as nodeParseArgs } from "node:util";
+function parseArgs(argv) {
+  const { values, positionals } = nodeParseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      verify: { type: "boolean" },
+      create: { type: "boolean" },
+      force: { type: "boolean" },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help === true) {
+    return { kind: "help" };
+  }
+  const mode = resolveMode(values.verify === true, values.create === true, values.force === true);
+  const [source, target] = positionals;
+  if (source === void 0) {
+    throw new Error("missing required argument: <source-dir>");
+  }
+  return { kind: "run", source, target, mode, json: values.json === true };
+}
+function resolveMode(verify, create, force) {
+  const selected = [verify ? "verify" : void 0, create ? "create" : void 0, force ? "force" : void 0].filter(
+    (value) => value !== void 0
+  );
+  if (selected.length > 1) {
+    throw new Error("choose only one of --verify, --create, --force");
+  }
+  return selected[0] ?? "verify";
+}
+export {
+  parseArgs
+};

package/dist/esm/bin/run.d.ts

@@ -0,0 +1,2 @@
+export declare const HELP = "overlay \u2014 overlay a chezmoi source tree onto a target directory\n\nUsage:\n  overlay <source-dir> [target-dir] [--verify|--create|--force] [--json] [--help]\n\nArguments:\n  <source-dir>   chezmoi source directory describing the files the target should have.\n  [target-dir]   Directory to converge (default: current working directory).\n\nModes (mutually exclusive; default --verify):\n  --verify   Read-only. Report drift (missing, differing, or to-be-removed files)\n             and exit non-zero if any exists. Pending run_ scripts are surfaced\n             but never affect the verdict; verify confirms file convergence, not\n             script execution.\n  --create   Create missing files, perform native removals, run run_ scripts, and\n             report differing files as conflicts without overwriting them.\n  --force    Full convergence: overwrite differing files, perform removals, run\n             run_ scripts.\n\nOptions:\n  --json     Print the structured result as JSON instead of the text report.\n  -h, --help Show this help.\n\nExit codes:\n  0  Converged / clean.\n  1  Drift (verify) or unresolved conflicts (create).\n  2  Hard error: chezmoi missing or below the minimum version, a script failed, or\n     invalid arguments.\n";
+export declare function run(argv: string[]): Promise<number>;

package/dist/esm/bin/run.js

@@ -0,0 +1,66 @@
+import process from "node:process";
+import { formatJsonError } from "../formatJsonError.js";
+import { formatReport } from "../formatReport.js";
+import { overlay } from "../overlay.js";
+import { extractMessage } from "../utils/error-handling.js";
+import { parseArgs } from "./parseArgs.js";
+const HELP = `overlay \u2014 overlay a chezmoi source tree onto a target directory
+
+Usage:
+  overlay <source-dir> [target-dir] [--verify|--create|--force] [--json] [--help]
+
+Arguments:
+  <source-dir>   chezmoi source directory describing the files the target should have.
+  [target-dir]   Directory to converge (default: current working directory).
+
+Modes (mutually exclusive; default --verify):
+  --verify   Read-only. Report drift (missing, differing, or to-be-removed files)
+             and exit non-zero if any exists. Pending run_ scripts are surfaced
+             but never affect the verdict; verify confirms file convergence, not
+             script execution.
+  --create   Create missing files, perform native removals, run run_ scripts, and
+             report differing files as conflicts without overwriting them.
+  --force    Full convergence: overwrite differing files, perform removals, run
+             run_ scripts.
+
+Options:
+  --json     Print the structured result as JSON instead of the text report.
+  -h, --help Show this help.
+
+Exit codes:
+  0  Converged / clean.
+  1  Drift (verify) or unresolved conflicts (create).
+  2  Hard error: chezmoi missing or below the minimum version, a script failed, or
+     invalid arguments.
+`;
+async function run(argv) {
+  try {
+    const command = parseArgs(argv);
+    if (command.kind === "help") {
+      process.stdout.write(HELP);
+      return 0;
+    }
+    const result = await overlay({
+      source: command.source,
+      mode: command.mode,
+      ...command.target === void 0 ? {} : { target: command.target }
+    });
+    if (command.json) {
+      process.stdout.write(`${JSON.stringify(result)}
+`);
+    } else {
+      process.stdout.write(`${formatReport(result)}
+`);
+    }
+    return result.exitCode;
+  } catch (error) {
+    const message = extractMessage(error);
+    process.stderr.write(`${formatJsonError(message)}
+`);
+    return 2;
+  }
+}
+export {
+  HELP,
+  run
+};

package/dist/esm/chezmoi/parseStatus.d.ts

@@ -0,0 +1,6 @@
+export type StatusCode = 'A' | 'M' | 'D' | 'R';
+export interface StatusEntry {
+    path: string;
+    code: StatusCode;
+}
+export declare function parseStatus(stdout: string): StatusEntry[];

package/dist/esm/chezmoi/parseStatus.js

@@ -0,0 +1,19 @@
+const APPLY_CODES = /* @__PURE__ */ new Set(["A", "M", "D", "R"]);
+function parseStatus(stdout) {
+  const entries = [];
+  for (const line of stdout.split("\n")) {
+    if (line.length < 4) continue;
+    const code = line[1];
+    if (code === void 0 || !isStatusCode(code)) continue;
+    const path = line.slice(3).trim();
+    if (path === "") continue;
+    entries.push({ path, code });
+  }
+  return entries;
+}
+function isStatusCode(value) {
+  return APPLY_CODES.has(value);
+}
+export {
+  parseStatus
+};

package/dist/esm/chezmoi/readStatus.d.ts

@@ -0,0 +1,2 @@
+import type { ChezmoiContext } from './runChezmoi.ts';
+export declare function readStatus(context: ChezmoiContext): Promise<string>;

package/dist/esm/chezmoi/readStatus.js

@@ -0,0 +1,12 @@
+import { runChezmoiCaptured } from "./runChezmoi.js";
+async function readStatus(context) {
+  const { stdout, stderr, code } = await runChezmoiCaptured(context, ["status"]);
+  if (code !== 0) {
+    const detail = stderr.trim() === "" ? `exit code ${code}` : stderr.trim();
+    throw new Error(`chezmoi status failed: ${detail}`);
+  }
+  return stdout;
+}
+export {
+  readStatus
+};

package/dist/esm/chezmoi/runChezmoi.d.ts

@@ -0,0 +1,11 @@
+export interface CapturedResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface ChezmoiContext {
+    source: string;
+    target: string;
+}
+export declare function runChezmoiCaptured(context: ChezmoiContext, args: string[]): Promise<CapturedResult>;
+export declare function runChezmoiStreamed(context: ChezmoiContext, args: string[]): Promise<number>;

package/dist/esm/chezmoi/runChezmoi.js

@@ -0,0 +1,68 @@
+import { execFile, spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+function buildArgs(context, persistentStatePath, configPath, args) {
+  return [
+    `--source=${context.source}`,
+    `--destination=${context.target}`,
+    `--persistent-state=${persistentStatePath}`,
+    `--config=${configPath}`,
+    "--no-tty",
+    ...args
+  ];
+}
+async function withSandbox(context, args, body) {
+  const sandboxDir = await mkdtemp(path.join(tmpdir(), "overlay-chezmoi-"));
+  const persistentStatePath = path.join(sandboxDir, "state.boltdb");
+  const configPath = path.join(sandboxDir, "chezmoi.toml");
+  try {
+    await writeFile(configPath, "");
+    const fullArgs = buildArgs(context, persistentStatePath, configPath, args);
+    return await body(fullArgs);
+  } finally {
+    await rm(sandboxDir, { recursive: true, force: true });
+  }
+}
+async function runChezmoiCaptured(context, args) {
+  return withSandbox(context, args, async (fullArgs) => {
+    try {
+      const { stdout, stderr } = await execFileAsync("chezmoi", fullArgs);
+      return { stdout, stderr, code: 0 };
+    } catch (error) {
+      return interpretExecFileError(error);
+    }
+  });
+}
+async function runChezmoiStreamed(context, args) {
+  return withSandbox(context, args, async (fullArgs) => {
+    return new Promise((resolve, reject) => {
+      const child = spawn("chezmoi", fullArgs, { stdio: ["ignore", process.stderr, process.stderr] });
+      child.on("error", reject);
+      child.on("close", (code) => resolve(code ?? 1));
+    });
+  });
+}
+function interpretExecFileError(error) {
+  if (isExecFileError(error)) {
+    if (error.code === "ENOENT") {
+      throw new Error("chezmoi not found on PATH \u2014 install it (e.g. `brew install chezmoi`)");
+    }
+    return {
+      stdout: typeof error.stdout === "string" ? error.stdout : "",
+      stderr: typeof error.stderr === "string" ? error.stderr : "",
+      code: typeof error.code === "number" ? error.code : 1
+    };
+  }
+  throw error;
+}
+function isExecFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error;
+}
+export {
+  runChezmoiCaptured,
+  runChezmoiStreamed
+};

package/dist/esm/chezmoi/version.d.ts

@@ -0,0 +1,10 @@
+import type { ChezmoiContext } from './runChezmoi.ts';
+interface SemverParts {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export declare const MIN_CHEZMOI_VERSION: string;
+export declare function assertChezmoiVersion(context: ChezmoiContext): Promise<void>;
+export declare function parseVersion(text: string): SemverParts | undefined;
+export {};

package/dist/esm/chezmoi/version.js

@@ -0,0 +1,36 @@
+import { runChezmoiCaptured } from "./runChezmoi.js";
+const MINIMUM = { major: 2, minor: 46, patch: 0 };
+const MIN_CHEZMOI_VERSION = formatVersion(MINIMUM);
+async function assertChezmoiVersion(context) {
+  const { stdout, code } = await runChezmoiCaptured(context, ["--version"]);
+  if (code !== 0) {
+    throw new Error("chezmoi is not available \u2014 install it (e.g. `brew install chezmoi`)");
+  }
+  const installed = parseVersion(stdout);
+  if (installed === void 0) {
+    throw new Error(`could not determine chezmoi version from: ${stdout.trim()}`);
+  }
+  if (compareVersions(installed, MINIMUM) < 0) {
+    throw new Error(`chezmoi ${MIN_CHEZMOI_VERSION} or later is required; found ${formatVersion(installed)}`);
+  }
+}
+function parseVersion(text) {
+  const match = text.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (match === null) return void 0;
+  const [, major, minor, patch] = match;
+  if (major === void 0 || minor === void 0 || patch === void 0) return void 0;
+  return { major: Number(major), minor: Number(minor), patch: Number(patch) };
+}
+function compareVersions(a, b) {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  return a.patch - b.patch;
+}
+function formatVersion(parts) {
+  return `${parts.major}.${parts.minor}.${parts.patch}`;
+}
+export {
+  MIN_CHEZMOI_VERSION,
+  assertChezmoiVersion,
+  parseVersion
+};

package/dist/esm/formatJsonError.d.ts

@@ -0,0 +1 @@
+export declare function formatJsonError(message: string): string;

package/dist/esm/formatJsonError.js

@@ -0,0 +1,6 @@
+function formatJsonError(message) {
+  return JSON.stringify({ error: message });
+}
+export {
+  formatJsonError
+};

package/dist/esm/formatReport.d.ts

@@ -0,0 +1,2 @@
+import type { OverlayResult } from './types.ts';
+export declare function formatReport(result: OverlayResult): string;

package/dist/esm/formatReport.js

@@ -0,0 +1,47 @@
+import { pluralizeWithCount } from "./utils/pluralize.js";
+function formatReport(result) {
+  const lines = [];
+  for (const entry of result.entries) {
+    lines.push(`  ${OUTCOME_LABELS[entry.outcome]} ${entry.path}`);
+  }
+  if (result.entries.length > 0) {
+    lines.push("");
+  }
+  lines.push(summarizeCounts(result), summarizeScripts(result));
+  if (result.counts.conflicts > 0) {
+    lines.push("", "Conflicts left untouched. Re-run with `overlay --force` to overwrite differing files.");
+  }
+  return lines.join("\n");
+}
+const OUTCOME_LABELS = {
+  created: "create ",
+  deleted: "delete ",
+  forced: "force  ",
+  conflict: "conflict"
+};
+function summarizeCounts(result) {
+  if (result.mode === "verify") {
+    if (result.counts.pending === 0) {
+      return "Target is converged: no drift.";
+    }
+    return `Drift: ${pluralizeWithCount(result.counts.pending, "entry", "entries")}.`;
+  }
+  const parts = [
+    result.counts.created > 0 ? `${result.counts.created} created` : void 0,
+    result.counts.deleted > 0 ? `${result.counts.deleted} deleted` : void 0,
+    result.counts.forced > 0 ? `${result.counts.forced} forced` : void 0,
+    result.counts.conflicts > 0 ? pluralizeWithCount(result.counts.conflicts, "conflict") : void 0
+  ].filter((part) => part !== void 0);
+  if (parts.length === 0) {
+    return "Nothing to do.";
+  }
+  return parts.join(", ") + ".";
+}
+function summarizeScripts(result) {
+  const verb = result.mode === "verify" ? "would run" : "ran";
+  const status = result.scripts.ok ? "" : " (a script failed)";
+  return `${pluralizeWithCount(result.scripts.ran, "script")} ${verb}${status}.`;
+}
+export {
+  formatReport
+};

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export { overlay } from './overlay.ts';
+export type { EntryOutcome, OverlayCounts, OverlayEntry, OverlayMode, OverlayOptions, OverlayResult, ScriptsSummary, } from './types.ts';

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+import { overlay } from "./overlay.js";
+export {
+  overlay
+};

package/dist/esm/modes/buildEntries.d.ts

@@ -0,0 +1,9 @@
+import type { StatusCode, StatusEntry } from '../chezmoi/parseStatus.ts';
+import type { EntryOutcome, OverlayEntry } from '../types.ts';
+export type OutcomeMap = Partial<Record<StatusCode, EntryOutcome>>;
+export interface PartitionedStatus {
+    entries: OverlayEntry[];
+    pendingScripts: number;
+}
+export declare function partitionStatus(status: StatusEntry[], outcomes: OutcomeMap): PartitionedStatus;
+export declare function countOutcome(entries: OverlayEntry[], outcome: EntryOutcome): number;

package/dist/esm/modes/buildEntries.js

@@ -0,0 +1,22 @@
+function partitionStatus(status, outcomes) {
+  const entries = [];
+  let pendingScripts = 0;
+  for (const entry of status) {
+    if (entry.code === "R") {
+      pendingScripts += 1;
+      continue;
+    }
+    const outcome = outcomes[entry.code];
+    if (outcome !== void 0) {
+      entries.push({ path: entry.path, outcome });
+    }
+  }
+  return { entries, pendingScripts };
+}
+function countOutcome(entries, outcome) {
+  return entries.filter((entry) => entry.outcome === outcome).length;
+}
+export {
+  countOutcome,
+  partitionStatus
+};

package/dist/esm/modes/create.d.ts

@@ -0,0 +1,3 @@
+import type { ChezmoiContext } from '../chezmoi/runChezmoi.ts';
+import type { OverlayResult } from '../types.ts';
+export declare function runCreate(context: ChezmoiContext): Promise<OverlayResult>;

package/dist/esm/modes/create.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { parseStatus } from "../chezmoi/parseStatus.js";
+import { readStatus } from "../chezmoi/readStatus.js";
+import { runChezmoiStreamed } from "../chezmoi/runChezmoi.js";
+import { countOutcome, partitionStatus } from "./buildEntries.js";
+async function runCreate(context) {
+  const { entries, pendingScripts } = partitionStatus(parseStatus(await readStatus(context)), {
+    A: "created",
+    D: "deleted",
+    M: "conflict"
+  });
+  const applyPaths = entries.filter((entry) => entry.outcome === "created" || entry.outcome === "deleted").map((entry) => path.join(context.target, entry.path));
+  const conflicts = countOutcome(entries, "conflict");
+  const counts = {
+    created: countOutcome(entries, "created"),
+    deleted: countOutcome(entries, "deleted"),
+    forced: 0,
+    conflicts,
+    pending: 0
+  };
+  const applyCode = applyPaths.length > 0 ? await runChezmoiStreamed(context, ["apply", "--include=files,dirs,remove", "--", ...applyPaths]) : 0;
+  if (applyCode !== 0) {
+    return { mode: "create", entries, scripts: { ran: pendingScripts, ok: false }, counts, exitCode: 2 };
+  }
+  const scriptsCode = pendingScripts > 0 ? await runChezmoiStreamed(context, ["apply", "--include=scripts"]) : 0;
+  const ok = scriptsCode === 0;
+  return {
+    mode: "create",
+    entries,
+    scripts: { ran: pendingScripts, ok },
+    counts,
+    exitCode: computeExitCode(ok, conflicts)
+  };
+}
+function computeExitCode(ok, conflicts) {
+  if (!ok) return 2;
+  if (conflicts > 0) return 1;
+  return 0;
+}
+export {
+  runCreate
+};

package/dist/esm/modes/force.d.ts

@@ -0,0 +1,3 @@
+import type { ChezmoiContext } from '../chezmoi/runChezmoi.ts';
+import type { OverlayResult } from '../types.ts';
+export declare function runForce(context: ChezmoiContext): Promise<OverlayResult>;

package/dist/esm/modes/force.js

@@ -0,0 +1,29 @@
+import { parseStatus } from "../chezmoi/parseStatus.js";
+import { readStatus } from "../chezmoi/readStatus.js";
+import { runChezmoiStreamed } from "../chezmoi/runChezmoi.js";
+import { countOutcome, partitionStatus } from "./buildEntries.js";
+async function runForce(context) {
+  const { entries, pendingScripts } = partitionStatus(parseStatus(await readStatus(context)), {
+    A: "created",
+    D: "deleted",
+    M: "forced"
+  });
+  const applyCode = await runChezmoiStreamed(context, ["apply"]);
+  const ok = applyCode === 0;
+  return {
+    mode: "force",
+    entries,
+    scripts: { ran: pendingScripts, ok },
+    counts: {
+      created: countOutcome(entries, "created"),
+      deleted: countOutcome(entries, "deleted"),
+      forced: countOutcome(entries, "forced"),
+      conflicts: 0,
+      pending: 0
+    },
+    exitCode: ok ? 0 : 2
+  };
+}
+export {
+  runForce
+};

package/dist/esm/modes/verify.d.ts

@@ -0,0 +1,3 @@
+import type { ChezmoiContext } from '../chezmoi/runChezmoi.ts';
+import type { OverlayResult } from '../types.ts';
+export declare function runVerify(context: ChezmoiContext): Promise<OverlayResult>;

package/dist/esm/modes/verify.js

@@ -0,0 +1,20 @@
+import { parseStatus } from "../chezmoi/parseStatus.js";
+import { readStatus } from "../chezmoi/readStatus.js";
+import { partitionStatus } from "./buildEntries.js";
+async function runVerify(context) {
+  const { entries, pendingScripts } = partitionStatus(parseStatus(await readStatus(context)), {
+    A: "created",
+    D: "deleted",
+    M: "conflict"
+  });
+  return {
+    mode: "verify",
+    entries,
+    scripts: { ran: pendingScripts, ok: true },
+    counts: { created: 0, deleted: 0, forced: 0, conflicts: 0, pending: entries.length },
+    exitCode: entries.length > 0 ? 1 : 0
+  };
+}
+export {
+  runVerify
+};

package/dist/esm/overlay.d.ts

@@ -0,0 +1,2 @@
+import type { OverlayOptions, OverlayResult } from './types.ts';
+export declare function overlay(options: OverlayOptions): Promise<OverlayResult>;

package/dist/esm/overlay.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import process from "node:process";
+import { assertChezmoiVersion } from "./chezmoi/version.js";
+import { runCreate } from "./modes/create.js";
+import { runForce } from "./modes/force.js";
+import { runVerify } from "./modes/verify.js";
+async function overlay(options) {
+  const mode = options.mode ?? "verify";
+  const context = {
+    source: path.resolve(options.source),
+    target: path.resolve(options.target ?? process.cwd())
+  };
+  await assertChezmoiVersion(context);
+  if (mode === "create") return runCreate(context);
+  if (mode === "force") return runForce(context);
+  return runVerify(context);
+}
+export {
+  overlay
+};

package/dist/esm/types.d.ts

@@ -0,0 +1,29 @@
+export type OverlayMode = 'verify' | 'create' | 'force';
+export interface OverlayOptions {
+    source: string;
+    target?: string;
+    mode?: OverlayMode;
+}
+export type EntryOutcome = 'created' | 'deleted' | 'forced' | 'conflict';
+export interface OverlayEntry {
+    path: string;
+    outcome: EntryOutcome;
+}
+export interface ScriptsSummary {
+    ran: number;
+    ok: boolean;
+}
+export interface OverlayCounts {
+    created: number;
+    deleted: number;
+    forced: number;
+    conflicts: number;
+    pending: number;
+}
+export interface OverlayResult {
+    mode: OverlayMode;
+    entries: OverlayEntry[];
+    scripts: ScriptsSummary;
+    counts: OverlayCounts;
+    exitCode: 0 | 1 | 2;
+}

package/dist/esm/utils/error-handling.d.ts

@@ -0,0 +1 @@
+export declare function extractMessage(error: unknown): string;

package/dist/esm/utils/error-handling.js

@@ -0,0 +1,6 @@
+function extractMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  extractMessage
+};

package/dist/esm/utils/pluralize.d.ts

@@ -0,0 +1,2 @@
+export declare function pluralize(count: number, singular: string, plural?: string): string;
+export declare function pluralizeWithCount(count: number, singular: string, plural?: string): string;

package/dist/esm/utils/pluralize.js

@@ -0,0 +1,10 @@
+function pluralize(count, singular, plural = `${singular}s`) {
+  return Math.abs(count) === 1 ? singular : plural;
+}
+function pluralizeWithCount(count, singular, plural = `${singular}s`) {
+  return `${count} ${pluralize(count, singular, plural)}`;
+}
+export {
+  pluralize,
+  pluralizeWithCount
+};

package/dist/esm/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.2.0";

package/dist/esm/version.js

@@ -0,0 +1,4 @@
+const VERSION = "0.2.0";
+export {
+  VERSION
+};

package/package.json

@@ -1,4 +1,47 @@
 {
   "name": "@williamthorsen/overlay",
-  "version": "0.0.0"
-}
+  "version": "0.2.0",
+  "private": false,
+  "description": "Idempotently overlay a canonical set of scaffolding files onto a target directory, backed by chezmoi",
+  "keywords": [
+    "chezmoi",
+    "overlay",
+    "scaffold",
+    "verify"
+  ],
+  "homepage": "https://github.com/williamthorsen/workshop/tree/main/packages/overlay#readme",
+  "bugs": {
+    "url": "https://github.com/williamthorsen/workshop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/williamthorsen/workshop.git",
+    "directory": "packages/overlay"
+  },
+  "license": "MIT",
+  "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "sideEffects": [
+    "./dist/esm/bin/overlay.js"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/esm/index.d.ts"
+    }
+  },
+  "bin": {
+    "overlay": "bin/overlay.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {}
+}