agentcohort 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentcohort contributors
+
+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

@@ -0,0 +1,187 @@
+# agentcohort
+
+> Install a principal/staff-level **AI software-engineering organization** for
+> [Claude Code](https://docs.claude.com/en/docs/claude-code) into any project
+> with one command.
+
+`agentcohort` is not just a template copier. It installs a coordinated set of
+**15 subagents**, **7 workflow commands**, and **routing rules** that make
+Claude Code work like a disciplined engineering org: explore before changing,
+prove root cause before fixing, measure before optimizing, and review before
+shipping.
+
+---
+
+## Install
+
+```bash
+npm i agentcohort
+```
+
+Or run it without installing:
+
+```bash
+npx agentcohort init
+```
+
+> The npm package is `agentcohort`; the CLI command it installs is
+> just `agentcohort`.
+
+## Quick start
+
+From the root of the project you want to equip:
+
+```bash
+agentcohort init
+```
+
+Then open Claude Code in that project and run:
+
+```
+/auto-flow <describe your task, bug, or paste a diff>
+```
+
+`/auto-flow` classifies the work and routes it to the right pipeline.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `agentcohort init` | Install agents, commands and routing rules into the current project. |
+| `agentcohort init --yes` | Non-interactive. Safe defaults (see below). |
+| `agentcohort init --dry-run` | Print exactly what *would* change. Writes nothing. |
+| `agentcohort init --force` | Overwrite conflicts / replace the routing section without prompting. |
+| `agentcohort init --backup` | Always back up a file before overwriting it. |
+| `agentcohort --version` | Print the version. |
+| `agentcohort --help` | Show help. |
+
+Flags compose: `agentcohort init --yes --backup`, `--force --backup`, etc.
+
+## What files are created
+
+```
+.claude/
+  agents/
+    repo-scout.md            solution-architect.md   feature-planner.md
+    feature-implementer.md   test-verifier.md        final-reviewer.md
+    bug-hunter.md            root-cause-analyst.md   reproduction-engineer.md
+    regression-guard.md      bug-fixer.md
+    performance-hunter.md    perf-optimizer.md       perf-reviewer.md
+    expert-council.md
+  commands/
+    auto-flow.md   dev-flow.md   bug-audit.md   bug-fix-approved.md
+    perf-hunt.md   review-diff.md   fix-blockers.md
+CLAUDE.md                          # a "# Agentcohort Routing Rules" section
+```
+
+A full example tree is in [`examples/generated-claude/`](./examples/generated-claude).
+
+## The philosophy
+
+**Core:** Explore → Architect → Plan → Implement → Test → Review
+
+**Bugs:** Hunt → Evidence → Root Cause → Expert Council → **Human Approval** →
+Fix → Regression Test → Verify → Review
+
+**Performance:** Measure/Evidence → Bottleneck → Safe Optimization → Verify →
+Performance Review
+
+Every agent operates at a top-1% principal/staff standard: root-cause first,
+production-grade correctness, no shallow fixes, no fixing without evidence, and
+**a bug audit never fixes** — it produces a recommendation and stops at a human
+approval gate.
+
+## Using the workflow commands (inside Claude Code)
+
+| Command | Pipeline | Use it for |
+|---|---|---|
+| `/auto-flow` | classify → route | When unsure — it picks the flow. |
+| `/dev-flow` | scout → architect\* → planner → implementer → test-verifier → final-reviewer | Features & refactors. |
+| `/bug-audit` | bug-hunter → root-cause-analyst → reproduction-engineer → expert-council | Bugs / regressions / bad data / stability. **No fixing.** |
+| `/bug-fix-approved` | bug-fixer → regression-guard → test-verifier → final-reviewer | Implement a fix you already approved. |
+| `/perf-hunt` | performance-hunter → architect\* → perf-optimizer → test-verifier → perf-reviewer | Slowness / bottlenecks. |
+| `/review-diff` | final-reviewer | Review the current diff/PR. |
+| `/fix-blockers` | feature-implementer → test-verifier | Fix only the blockers a review listed. |
+
+\* the architect stage runs only when the change is architecture-sensitive.
+
+### Model strategy
+
+- **Haiku** — cheap exploration / scouting.
+- **Sonnet** — implementation, testing, bug & performance hunting.
+- **Opus** — architecture, root-cause analysis, expert council, final review.
+
+## Customizing agents
+
+The installed files are plain Markdown and **yours to edit**:
+
+- Tune any agent in `.claude/agents/*.md` (role, rules, output format, the
+  `model:`/`tools:` frontmatter).
+- Adjust a pipeline in `.claude/commands/*.md`.
+- Put **your own** project notes in `CLAUDE.md` *outside* the
+  `# Agentcohort Routing Rules` section — that section is owned by the tool and
+  may be updated by a future `init`; everything else is never touched.
+
+Re-running `agentcohort init` later will detect your edits as conflicts and ask
+before changing them (or back them up with `--backup`).
+
+## Safety notes
+
+`agentcohort` is conservative by design:
+
+- **Never deletes** your files.
+- **Never silently overwrites.** Existing, differing files trigger a prompt
+  (skip / overwrite / backup + overwrite), or an explicit flag.
+- **Idempotent.** Re-running on identical content reports *unchanged* and does
+  nothing.
+- **CLAUDE.md is surgical.** A missing file is created; a file without our
+  section gets the section *appended* (your content preserved); an existing,
+  differing section is **left alone** in non-interactive mode (use `--force`
+  to update it). Only the delimited section is ever touched.
+- **`--yes` safe defaults:** new files created; conflicting files
+  **backed up then updated**; an existing CLAUDE.md routing section **left
+  untouched**.
+- **`--dry-run`** performs zero writes and zero backups.
+- Backups are written next to the original as
+  `&lt;file&gt;.backup-YYYYMMDD-HHMMSS` and never overwrite an existing backup.
+- Cross-platform (Windows/macOS/Linux), zero runtime dependencies, no
+  shell-specific behavior.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc -> dist/, then copies templates
+npm test           # vitest
+```
+
+## Releases
+
+Publishing is automated. **The version in `package.json` is the version that
+gets published.** Every push to `main` runs the
+[`Release`](.github/workflows/release.yml) workflow, which:
+
+1. installs, builds and runs the full test suite;
+2. publishes the **current** `package.json` version to npm —
+   https://www.npmjs.com/package/agentcohort (so the very first
+   release is exactly `0.1.0`, nothing skipped);
+3. creates the annotated git tag `vX.Y.Z` on the published commit;
+4. bumps to the next dev version (`patch` by default) and pushes a
+   `chore(release): published vX.Y.Z, open vX.Y.(Z+1) [skip ci]` commit back
+   to `main`.
+
+So: to cut a normal release, just push to `main`. To release a `minor`/`major`
+instead, bump `package.json` yourself in a regular commit before pushing (or
+use the *Run workflow* button to control how the **next** pending version is
+opened). If the pending version is already on npm, publish is skipped and the
+job still succeeds (safe re-runs). The `[skip ci]` marker stops the release
+commit from re-triggering the workflow (no publish loop).
+
+**One-time setup:** add an npm **Automation** access token as the repository
+secret `NPM_TOKEN` (GitHub → Settings → Secrets and variables → Actions →
+*New repository secret*). Until that secret exists, the workflow's *Publish*
+step will fail while build/test still pass.
+
+## License
+
+MIT

package/dist/args.d.ts

@@ -0,0 +1,13 @@
+export interface ParsedArgs {
+    command: string | null;
+    yes: boolean;
+    dryRun: boolean;
+    force: boolean;
+    backup: boolean;
+    help: boolean;
+    version: boolean;
+    unknown: string[];
+}
+/** Pure, deterministic argument parser. Unknown tokens are collected, not thrown. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function helpText(): string;

package/dist/args.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.helpText = helpText;
+const logger_1 = require("./logger");
+const FLAGS = {
+    '--yes': 'yes',
+    '-y': 'yes',
+    '--dry-run': 'dryRun',
+    '--force': 'force',
+    '--backup': 'backup',
+    '--help': 'help',
+    '-h': 'help',
+    '--version': 'version',
+    '-v': 'version',
+};
+/** Pure, deterministic argument parser. Unknown tokens are collected, not thrown. */
+function parseArgs(argv) {
+    const parsed = {
+        command: null,
+        yes: false,
+        dryRun: false,
+        force: false,
+        backup: false,
+        help: false,
+        version: false,
+        unknown: [],
+    };
+    for (const arg of argv) {
+        if (arg.startsWith('-')) {
+            const key = FLAGS[arg];
+            if (key) {
+                parsed[key] = true;
+            }
+            else {
+                parsed.unknown.push(arg);
+            }
+        }
+        else if (parsed.command === null) {
+            parsed.command = arg;
+        }
+        else {
+            parsed.unknown.push(arg);
+        }
+    }
+    return parsed;
+}
+function helpText() {
+    const b = (s) => (0, logger_1.paint)(s, 'bold');
+    return `
+${b('agentcohort')} — install a principal/staff-level Claude Code AI engineering org.
+
+${b('USAGE')}
+  agentcohort <command> [options]
+
+${b('COMMANDS')}
+  init                 Install agents, workflow commands and routing rules
+                       into ./.claude and ./CLAUDE.md of the current project.
+
+${b('OPTIONS')}
+  --yes, -y            Non-interactive. Safe defaults: new files created;
+                       existing conflicting files backed up then updated;
+                       an existing CLAUDE.md routing section is left untouched.
+  --dry-run            Print exactly what would be created/updated. Writes
+                       nothing. Implies non-interactive (safe defaults).
+  --force              Overwrite conflicting files / replace the routing
+                       section without prompting (no backup unless --backup).
+  --backup             Always back up a file before overwriting it.
+                       Backup name: <file>.backup-YYYYMMDD-HHMMSS
+  --help, -h           Show this help.
+  --version, -v        Print the version.
+
+${b('WHAT GETS INSTALLED')}
+  .claude/agents/      15 subagents (scout, architect, planner, implementer,
+                       reviewer, bug-hunter, root-cause-analyst, ...).
+  .claude/commands/    7 workflow commands.
+  CLAUDE.md            Appends a "# Agentcohort Routing Rules" section.
+
+${b('WORKFLOW COMMANDS (run inside Claude Code)')}
+  /auto-flow           Classify the task and pick the right workflow.
+  /dev-flow            Feature/refactor: scout -> architect -> plan ->
+                       implement -> test -> review.
+  /bug-audit           Investigate ONLY (no fixes): hunt -> evidence ->
+                       root cause -> expert council -> recommendation.
+  /bug-fix-approved    Fix an approved bug: fix -> regression -> test -> review.
+  /perf-hunt           Measure -> bottleneck -> safe optimize -> verify -> review.
+  /review-diff         Final reviewer on the current diff.
+  /fix-blockers        Fix only listed blockers, then verify.
+
+Existing files are NEVER deleted and NEVER silently overwritten.
+`;
+}

package/dist/claudeMd.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure helpers for managing the Agentcohort section inside a project CLAUDE.md.
+ *
+ * Design goals:
+ *  - Never destroy the user's existing CLAUDE.md content.
+ *  - Only ever touch our own clearly-delimited section.
+ *  - Preserve the rest of the file byte-for-byte (no global EOL rewrites):
+ *    we splice by string index instead of split/join.
+ *  - Be fenced-code-block aware so a `# ...` line inside ``` ``` is not
+ *    mistaken for a real heading boundary.
+ */
+export declare const SECTION_TITLE = "# Agentcohort Routing Rules";
+/** Index where our section heading line starts, fenced-code-aware. -1 if absent. */
+export declare function findSectionStart(content: string): number;
+export declare function hasSection(content: string): boolean;
+/** The exact current section block (heading through just before next heading/EOF). */
+export declare function extractSection(content: string): string | null;
+/** True when the existing section already equals the template (ignoring edge whitespace). */
+export declare function sectionMatches(content: string, sectionMarkdown: string): boolean;
+export type UpsertMode = 'append' | 'replace';
+export interface UpsertResult {
+    result: string;
+    mode: UpsertMode;
+}
+/**
+ * Insert or replace the Agentcohort section.
+ *  - Absent  -> appended at the end, separated by a blank line.
+ *  - Present -> the existing section block is replaced in place; everything
+ *               before and after is preserved verbatim.
+ */
+export declare function upsertSection(content: string, sectionMarkdown: string): UpsertResult;
+/** Minimal CLAUDE.md created when the project has none. */
+export declare function buildInitialClaudeMd(sectionMarkdown: string): string;

package/dist/claudeMd.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Pure helpers for managing the Agentcohort section inside a project CLAUDE.md.
+ *
+ * Design goals:
+ *  - Never destroy the user's existing CLAUDE.md content.
+ *  - Only ever touch our own clearly-delimited section.
+ *  - Preserve the rest of the file byte-for-byte (no global EOL rewrites):
+ *    we splice by string index instead of split/join.
+ *  - Be fenced-code-block aware so a `# ...` line inside ``` ``` is not
+ *    mistaken for a real heading boundary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECTION_TITLE = void 0;
+exports.findSectionStart = findSectionStart;
+exports.hasSection = hasSection;
+exports.extractSection = extractSection;
+exports.sectionMatches = sectionMatches;
+exports.upsertSection = upsertSection;
+exports.buildInitialClaudeMd = buildInitialClaudeMd;
+exports.SECTION_TITLE = '# Agentcohort Routing Rules';
+function* iterateLines(content) {
+    let i = 0;
+    const n = content.length;
+    while (i <= n) {
+        let nl = content.indexOf('\n', i);
+        if (nl === -1)
+            nl = n;
+        let contentEnd = nl;
+        if (contentEnd > i && content[contentEnd - 1] === '\r')
+            contentEnd -= 1;
+        yield {
+            start: i,
+            contentEnd,
+            next: nl === n ? n : nl + 1,
+            text: content.slice(i, contentEnd),
+        };
+        if (nl === n)
+            break;
+        i = nl + 1;
+    }
+}
+const FENCE_RE = /^\s{0,3}(```+|~~~+)/;
+const TOP_HEADING_RE = /^# (?!#)/; // exactly one '#', then space, not '##'
+/** Index where our section heading line starts, fenced-code-aware. -1 if absent. */
+function findSectionStart(content) {
+    let inFence = false;
+    let fenceToken = '';
+    for (const line of iterateLines(content)) {
+        const fence = FENCE_RE.exec(line.text);
+        if (fence) {
+            const token = fence[1][0]; // '`' or '~'
+            if (!inFence) {
+                inFence = true;
+                fenceToken = token;
+            }
+            else if (token === fenceToken) {
+                inFence = false;
+                fenceToken = '';
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (line.text.trimEnd() === exports.SECTION_TITLE)
+            return line.start;
+    }
+    return -1;
+}
+/** Index where the section ends (start of the next top-level heading) or EOF. */
+function findSectionEnd(content, sectionStart) {
+    let inFence = false;
+    let fenceToken = '';
+    let passedHeading = false;
+    for (const line of iterateLines(content)) {
+        if (line.start < sectionStart)
+            continue;
+        if (!passedHeading) {
+            // This is our own heading line; skip it then start scanning.
+            passedHeading = true;
+            continue;
+        }
+        const fence = FENCE_RE.exec(line.text);
+        if (fence) {
+            const token = fence[1][0];
+            if (!inFence) {
+                inFence = true;
+                fenceToken = token;
+            }
+            else if (token === fenceToken) {
+                inFence = false;
+                fenceToken = '';
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (TOP_HEADING_RE.test(line.text))
+            return line.start;
+    }
+    return content.length;
+}
+function hasSection(content) {
+    return findSectionStart(content) !== -1;
+}
+/** The exact current section block (heading through just before next heading/EOF). */
+function extractSection(content) {
+    const start = findSectionStart(content);
+    if (start === -1)
+        return null;
+    const end = findSectionEnd(content, start);
+    return content.slice(start, end);
+}
+/** True when the existing section already equals the template (ignoring edge whitespace). */
+function sectionMatches(content, sectionMarkdown) {
+    const current = extractSection(content);
+    if (current === null)
+        return false;
+    return current.trim() === sectionMarkdown.trim();
+}
+/**
+ * Insert or replace the Agentcohort section.
+ *  - Absent  -> appended at the end, separated by a blank line.
+ *  - Present -> the existing section block is replaced in place; everything
+ *               before and after is preserved verbatim.
+ */
+function upsertSection(content, sectionMarkdown) {
+    const body = sectionMarkdown.replace(/\s+$/, '') + '\n';
+    const start = findSectionStart(content);
+    if (start === -1) {
+        const base = content.length === 0 ? '' : content.replace(/\s+$/, '') + '\n';
+        const separator = base === '' ? '' : '\n';
+        return { result: base + separator + body, mode: 'append' };
+    }
+    const end = findSectionEnd(content, start);
+    const prefix = content.slice(0, start);
+    const suffix = content.slice(end);
+    let result = prefix + body;
+    if (suffix.length > 0) {
+        // Ensure exactly one blank line between our section and the next heading.
+        result += '\n' + suffix.replace(/^\n+/, '');
+    }
+    return { result, mode: 'replace' };
+}
+/** Minimal CLAUDE.md created when the project has none. */
+function buildInitialClaudeMd(sectionMarkdown) {
+    const header = [
+        '# Project Guidance for Claude Code',
+        '',
+        'This file is read by Claude Code at the start of every session.',
+        'The section below was installed by `agentcohort` and wires up the',
+        'AI software-engineering organization (agents + workflows).',
+        '',
+    ].join('\n');
+    return upsertSection(header, sectionMarkdown).result;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const installer_1 = require("./installer");
+const prompt_1 = require("./prompt");
+const logger_1 = require("./logger");
+const paths_1 = require("./paths");
+const args_1 = require("./args");
+function printSummary(result) {
+    const counts = new Map();
+    let backups = 0;
+    for (const a of result.actions) {
+        counts.set(a.disposition, (counts.get(a.disposition) ?? 0) + 1);
+        if (a.backupPath)
+            backups += 1;
+    }
+    const part = (label, key) => {
+        const n = counts.get(key) ?? 0;
+        return n > 0 ? `${n} ${label}` : null;
+    };
+    const segments = [
+        part('created', 'created'),
+        part('updated', 'overwritten'),
+        part('section appended', 'appended-section'),
+        part('section updated', 'replaced-section'),
+        part('unchanged', 'unchanged'),
+        part('skipped', 'skipped'),
+    ].filter((x) => x !== null);
+    process.stdout.write('\n');
+    const head = result.dryRun ? 'Dry run complete' : 'Agentcohort installed';
+    process.stdout.write(`${(0, logger_1.paint)(head, 'bold', 'green')}  ${segments.join(' · ')}\n`);
+    if (backups > 0) {
+        process.stdout.write(`${(0, logger_1.paint)('•', 'cyan')} ${backups} backup(s) written alongside the originals.\n`);
+    }
+    if (!result.dryRun && ((counts.get('created') ?? 0) || (counts.get('overwritten') ?? 0))) {
+        process.stdout.write(`${(0, logger_1.paint)('•', 'cyan')} Next: open Claude Code in this project and run ${(0, logger_1.paint)('/auto-flow', 'bold')}.\n`);
+    }
+    if (result.dryRun) {
+        process.stdout.write(`${(0, logger_1.paint)('•', 'cyan')} Re-run without ${(0, logger_1.paint)('--dry-run', 'bold')} to apply.\n`);
+    }
+}
+async function main(argv = process.argv.slice(2)) {
+    const args = (0, args_1.parseArgs)(argv);
+    if (args.unknown.length > 0) {
+        process.stderr.write((0, logger_1.paint)(`✗ Unknown argument(s): ${args.unknown.join(', ')}\n`, 'red'));
+        process.stdout.write((0, args_1.helpText)() + '\n');
+        return 1;
+    }
+    if (args.version) {
+        process.stdout.write((0, paths_1.getVersion)() + '\n');
+        return 0;
+    }
+    if (args.help || args.command === null) {
+        process.stdout.write((0, args_1.helpText)() + '\n');
+        return 0;
+    }
+    if (args.command !== 'init') {
+        process.stderr.write((0, logger_1.paint)(`✗ Unknown command: ${args.command}\n`, 'red'));
+        process.stdout.write((0, args_1.helpText)() + '\n');
+        return 1;
+    }
+    const stdinTTY = Boolean(process.stdin.isTTY);
+    const stdoutTTY = Boolean(process.stdout.isTTY);
+    const interactive = !args.yes && !args.force && !args.dryRun && stdinTTY && stdoutTTY;
+    const logger = (0, logger_1.createLogger)();
+    let resolverHandle = null;
+    process.stdout.write((0, logger_1.paint)('\nagentcohort', 'bold', 'cyan') + (0, logger_1.paint)(`  v${(0, paths_1.getVersion)()}\n`, 'gray'));
+    if (args.dryRun) {
+        logger.info('Dry run — no files will be written.');
+    }
+    else if (!interactive && !args.yes && !args.force) {
+        logger.info('Non-interactive environment detected — using safe defaults (like --yes).');
+    }
+    try {
+        if (interactive)
+            resolverHandle = (0, prompt_1.createInteractiveResolver)();
+        const result = await (0, installer_1.runInit)({
+            cwd: process.cwd(),
+            yes: args.yes,
+            dryRun: args.dryRun,
+            force: args.force,
+            backup: args.backup,
+            interactive,
+            resolver: resolverHandle?.resolve,
+            logger,
+        });
+        printSummary(result);
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write((0, logger_1.paint)(`\n✗ ${message}\n`, 'red'));
+        return 1;
+    }
+    finally {
+        resolverHandle?.close();
+    }
+}
+// Auto-run only when executed as the bin (not when imported by tests/tooling).
+if (require.main === module) {
+    main()
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        process.stderr.write((0, logger_1.paint)(`\n✗ Fatal: ${String(err)}\n`, 'red'));
+        process.exit(1);
+    });
+}

package/dist/fileOps.d.ts

@@ -0,0 +1,15 @@
+/** Read a file's UTF-8 content, or null if it does not exist. */
+export declare function readIfExists(path: string): string | null;
+/** Exact byte-for-byte comparison (drives idempotency: identical => "unchanged"). */
+export declare function contentEquals(a: string, b: string): boolean;
+/**
+ * Backup filename suffix using LOCAL time: `backup-YYYYMMDD-HHMMSS`.
+ * Local time is intentional so the timestamp matches the user's wall clock.
+ */
+export declare function formatBackupSuffix(date: Date): string;
+/** Absolute path of the backup file for `target` at `date`. */
+export declare function backupPathFor(target: string, date: Date): string;
+/** Copy an existing file to its backup path. Never deletes the original. */
+export declare function backupFile(target: string, backupPath: string): void;
+/** Create parent directories (recursive) then write the file as UTF-8. */
+export declare function writeFileEnsuringDir(path: string, content: string): void;

package/dist/fileOps.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readIfExists = readIfExists;
+exports.contentEquals = contentEquals;
+exports.formatBackupSuffix = formatBackupSuffix;
+exports.backupPathFor = backupPathFor;
+exports.backupFile = backupFile;
+exports.writeFileEnsuringDir = writeFileEnsuringDir;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Read a file's UTF-8 content, or null if it does not exist. */
+function readIfExists(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    return (0, node_fs_1.readFileSync)(path, 'utf8');
+}
+/** Exact byte-for-byte comparison (drives idempotency: identical => "unchanged"). */
+function contentEquals(a, b) {
+    return a === b;
+}
+/** Two-digit / four-digit zero padded. */
+function pad(n, width = 2) {
+    return String(n).padStart(width, '0');
+}
+/**
+ * Backup filename suffix using LOCAL time: `backup-YYYYMMDD-HHMMSS`.
+ * Local time is intentional so the timestamp matches the user's wall clock.
+ */
+function formatBackupSuffix(date) {
+    const y = pad(date.getFullYear(), 4);
+    const mo = pad(date.getMonth() + 1);
+    const d = pad(date.getDate());
+    const h = pad(date.getHours());
+    const mi = pad(date.getMinutes());
+    const s = pad(date.getSeconds());
+    return `backup-${y}${mo}${d}-${h}${mi}${s}`;
+}
+/** Absolute path of the backup file for `target` at `date`. */
+function backupPathFor(target, date) {
+    return `${target}.${formatBackupSuffix(date)}`;
+}
+/** Copy an existing file to its backup path. Never deletes the original. */
+function backupFile(target, backupPath) {
+    (0, node_fs_1.copyFileSync)(target, backupPath);
+}
+/** Create parent directories (recursive) then write the file as UTF-8. */
+function writeFileEnsuringDir(path, content) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, content, 'utf8');
+}