agentcohort 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Programmatic API.
+ *
+ * `agentcohort` is primarily a CLI, but the core install logic is exported
+ * so it can be embedded in other tooling and exercised directly by tests.
+ */
+export { runInit } from './installer';
+export type { InitOptions, InitResult, ActionRecord, Disposition, } from './installer';
+export { buildManifest } from './manifest';
+export type { ManifestEntry, EntryKind } from './manifest';
+export { upsertSection, hasSection, sectionMatches, buildInitialClaudeMd, SECTION_TITLE, } from './claudeMd';
+export { formatBackupSuffix, backupPathFor } from './fileOps';
+export { getVersion, getTemplatesDir } from './paths';
+export { createLogger } from './logger';
+export type { Logger } from './logger';
+export { createInteractiveResolver, fixedResolver } from './prompt';
+export type { ConflictResolver, ConflictDecision, Choice } from './prompt';

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixedResolver = exports.createInteractiveResolver = exports.createLogger = exports.getTemplatesDir = exports.getVersion = exports.backupPathFor = exports.formatBackupSuffix = exports.SECTION_TITLE = exports.buildInitialClaudeMd = exports.sectionMatches = exports.hasSection = exports.upsertSection = exports.buildManifest = exports.runInit = void 0;
+/**
+ * Programmatic API.
+ *
+ * `agentcohort` is primarily a CLI, but the core install logic is exported
+ * so it can be embedded in other tooling and exercised directly by tests.
+ */
+var installer_1 = require("./installer");
+Object.defineProperty(exports, "runInit", { enumerable: true, get: function () { return installer_1.runInit; } });
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "buildManifest", { enumerable: true, get: function () { return manifest_1.buildManifest; } });
+var claudeMd_1 = require("./claudeMd");
+Object.defineProperty(exports, "upsertSection", { enumerable: true, get: function () { return claudeMd_1.upsertSection; } });
+Object.defineProperty(exports, "hasSection", { enumerable: true, get: function () { return claudeMd_1.hasSection; } });
+Object.defineProperty(exports, "sectionMatches", { enumerable: true, get: function () { return claudeMd_1.sectionMatches; } });
+Object.defineProperty(exports, "buildInitialClaudeMd", { enumerable: true, get: function () { return claudeMd_1.buildInitialClaudeMd; } });
+Object.defineProperty(exports, "SECTION_TITLE", { enumerable: true, get: function () { return claudeMd_1.SECTION_TITLE; } });
+var fileOps_1 = require("./fileOps");
+Object.defineProperty(exports, "formatBackupSuffix", { enumerable: true, get: function () { return fileOps_1.formatBackupSuffix; } });
+Object.defineProperty(exports, "backupPathFor", { enumerable: true, get: function () { return fileOps_1.backupPathFor; } });
+var paths_1 = require("./paths");
+Object.defineProperty(exports, "getVersion", { enumerable: true, get: function () { return paths_1.getVersion; } });
+Object.defineProperty(exports, "getTemplatesDir", { enumerable: true, get: function () { return paths_1.getTemplatesDir; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "createLogger", { enumerable: true, get: function () { return logger_1.createLogger; } });
+var prompt_1 = require("./prompt");
+Object.defineProperty(exports, "createInteractiveResolver", { enumerable: true, get: function () { return prompt_1.createInteractiveResolver; } });
+Object.defineProperty(exports, "fixedResolver", { enumerable: true, get: function () { return prompt_1.fixedResolver; } });

package/dist/installer.d.ts

@@ -0,0 +1,32 @@
+import { EntryKind } from './manifest';
+import type { ConflictResolver } from './prompt';
+import type { Logger } from './logger';
+export type Disposition = 'created' | 'overwritten' | 'appended-section' | 'replaced-section' | 'skipped' | 'unchanged';
+export interface ActionRecord {
+    targetRelPath: string;
+    kind: EntryKind;
+    disposition: Disposition;
+    /** Absolute path of the backup that was (or would be) written, if any. */
+    backupPath?: string;
+    dryRun: boolean;
+}
+export interface InitOptions {
+    cwd: string;
+    yes: boolean;
+    dryRun: boolean;
+    force: boolean;
+    /** Force a backup before any destructive write, regardless of other choices. */
+    backup: boolean;
+    /** When false, conflicts are resolved by safe automatic defaults. */
+    interactive: boolean;
+    resolver?: ConflictResolver;
+    now?: () => Date;
+    logger?: Logger;
+    templatesDir?: string;
+}
+export interface InitResult {
+    projectRoot: string;
+    actions: ActionRecord[];
+    dryRun: boolean;
+}
+export declare function runInit(options: InitOptions): Promise<InitResult>;

package/dist/installer.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const fileOps_1 = require("./fileOps");
+const claudeMd_1 = require("./claudeMd");
+const manifest_1 = require("./manifest");
+const paths_1 = require("./paths");
+/** Pick a non-clobbering backup path (never overwrite an existing backup). */
+function uniqueBackupPath(target, date) {
+    const base = (0, fileOps_1.backupPathFor)(target, date);
+    if (!(0, node_fs_1.existsSync)(base))
+        return base;
+    let i = 1;
+    while ((0, node_fs_1.existsSync)(`${base}-${i}`))
+        i += 1;
+    return `${base}-${i}`;
+}
+async function runInit(options) {
+    const projectRoot = options.cwd;
+    const now = options.now ?? (() => new Date());
+    const log = options.logger;
+    const templatesDir = options.templatesDir ?? (0, paths_1.getTemplatesDir)();
+    const manifest = (0, manifest_1.buildManifest)(templatesDir, projectRoot);
+    if (manifest.length === 0) {
+        throw new Error('agentcohort: no templates found to install.');
+    }
+    const actions = [];
+    let sticky = null;
+    const decide = async (kind, targetRelPath) => {
+        // 1. --force always proceeds; backup only if explicitly requested.
+        if (options.force) {
+            return { proceed: true, backup: options.backup };
+        }
+        // 2. Non-interactive (--yes, --dry-run, or non-TTY): safe defaults.
+        if (!options.interactive) {
+            if (kind === 'claude-section') {
+                // Don't silently rewrite hand-editable routing rules.
+                return { proceed: false, backup: false };
+            }
+            // Deliver latest templates but never lose old content.
+            return { proceed: true, backup: true };
+        }
+        // 3. Interactive: ask (honoring a prior "apply to all" decision).
+        if (!options.resolver) {
+            throw new Error('agentcohort: interactive mode requires a resolver.');
+        }
+        const decision = sticky ?? (await options.resolver({ targetRelPath, kind }));
+        if (decision.applyToAll && !sticky)
+            sticky = decision;
+        if (decision.choice === 'skip')
+            return { proceed: false, backup: false };
+        if (decision.choice === 'overwrite') {
+            return { proceed: true, backup: options.backup };
+        }
+        return { proceed: true, backup: true }; // 'backup'
+    };
+    const record = (a) => {
+        actions.push(a);
+        if (!log)
+            return;
+        const tag = options.dryRun ? '[dry-run] ' : '';
+        const bk = a.backupPath ? `  (backup: ${(0, node_path_1.relative)(projectRoot, a.backupPath)})` : '';
+        switch (a.disposition) {
+            case 'created':
+                log.success(`${tag}create  ${a.targetRelPath}`);
+                break;
+            case 'overwritten':
+                log.success(`${tag}update  ${a.targetRelPath}${bk}`);
+                break;
+            case 'appended-section':
+                log.success(`${tag}append  ${a.targetRelPath} (Agentcohort Routing Rules)`);
+                break;
+            case 'replaced-section':
+                log.success(`${tag}update  ${a.targetRelPath} (Agentcohort Routing Rules)${bk}`);
+                break;
+            case 'unchanged':
+                log.info(`${tag}unchanged  ${a.targetRelPath}`);
+                break;
+            case 'skipped':
+                log.warn(`${tag}skip  ${a.targetRelPath}`);
+                break;
+        }
+    };
+    const doBackup = (target) => {
+        const path = uniqueBackupPath(target, now());
+        if (!options.dryRun)
+            (0, fileOps_1.backupFile)(target, path);
+        return path;
+    };
+    for (const entry of manifest) {
+        if (entry.kind === 'regular') {
+            await handleRegular(entry);
+        }
+        else {
+            await handleClaudeSection(entry);
+        }
+    }
+    return { projectRoot, actions, dryRun: options.dryRun };
+    // ---- per-entry handlers (closures over decide/record/doBackup) ----
+    async function handleRegular(entry) {
+        const template = (0, node_fs_1.readFileSync)(entry.templateAbsPath, 'utf8');
+        const existing = (0, fileOps_1.readIfExists)(entry.targetAbsPath);
+        if (existing === null) {
+            if (!options.dryRun)
+                (0, fileOps_1.writeFileEnsuringDir)(entry.targetAbsPath, template);
+            record({
+                targetRelPath: entry.targetRelPath,
+                kind: entry.kind,
+                disposition: 'created',
+                dryRun: options.dryRun,
+            });
+            return;
+        }
+        if ((0, fileOps_1.contentEquals)(existing, template)) {
+            record({
+                targetRelPath: entry.targetRelPath,
+                kind: entry.kind,
+                disposition: 'unchanged',
+                dryRun: options.dryRun,
+            });
+            return;
+        }
+        const policy = await decide(entry.kind, entry.targetRelPath);
+        if (!policy.proceed) {
+            record({
+                targetRelPath: entry.targetRelPath,
+                kind: entry.kind,
+                disposition: 'skipped',
+                dryRun: options.dryRun,
+            });
+            return;
+        }
+        let backupPath;
+        if (policy.backup)
+            backupPath = doBackup(entry.targetAbsPath);
+        if (!options.dryRun)
+            (0, fileOps_1.writeFileEnsuringDir)(entry.targetAbsPath, template);
+        record({
+            targetRelPath: entry.targetRelPath,
+            kind: entry.kind,
+            disposition: 'overwritten',
+            backupPath,
+            dryRun: options.dryRun,
+        });
+    }
+    async function handleClaudeSection(entry) {
+        const sectionMarkdown = (0, node_fs_1.readFileSync)(entry.templateAbsPath, 'utf8');
+        const existing = (0, fileOps_1.readIfExists)(entry.targetAbsPath);
+        if (existing === null) {
+            const content = (0, claudeMd_1.buildInitialClaudeMd)(sectionMarkdown);
+            if (!options.dryRun)
+                (0, fileOps_1.writeFileEnsuringDir)(entry.targetAbsPath, content);
+            record({
+                targetRelPath: entry.targetRelPath,
+                kind: entry.kind,
+                disposition: 'created',
+                dryRun: options.dryRun,
+            });
+            return;
+        }
+        if (!(0, claudeMd_1.hasSection)(existing)) {
+            const content = (0, claudeMd_1.upsertSection)(existing, sectionMarkdown).result;
+            if (!options.dryRun)
+                (0, fileOps_1.writeFileEnsuringDir)(entry.targetAbsPath, content);
+            record({
+                targetRelPath: entry.targetRelPath,
+                kind: entry.kind,
+                disposition: 'appended-section',
+                dryRun: options.dryRun,
+            });
+            return;
+        }
+        if ((0, claudeMd_1.sectionMatches)(existing, sectionMarkdown)) {
+            record({
+                targetRelPath: entry.targetRelPath,
+                kind: entry.kind,
+                disposition: 'unchanged',
+                dryRun: options.dryRun,
+            });
+            return;
+        }
+        const policy = await decide(entry.kind, entry.targetRelPath);
+        if (!policy.proceed) {
+            record({
+                targetRelPath: entry.targetRelPath,
+                kind: entry.kind,
+                disposition: 'skipped',
+                dryRun: options.dryRun,
+            });
+            return;
+        }
+        let backupPath;
+        if (policy.backup)
+            backupPath = doBackup(entry.targetAbsPath);
+        const content = (0, claudeMd_1.upsertSection)(existing, sectionMarkdown).result;
+        if (!options.dryRun)
+            (0, fileOps_1.writeFileEnsuringDir)(entry.targetAbsPath, content);
+        record({
+            targetRelPath: entry.targetRelPath,
+            kind: entry.kind,
+            disposition: 'replaced-section',
+            backupPath,
+            dryRun: options.dryRun,
+        });
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Minimal, dependency-free, cross-platform colored logger.
+ *
+ * Color is disabled automatically when:
+ *  - stdout is not a TTY (piped / redirected output), or
+ *  - the NO_COLOR env var is set (https://no-color.org), or
+ *  - FORCE_COLOR=0.
+ *
+ * The Logger is an injectable interface so tests can capture output instead
+ * of writing to the real console.
+ */
+export interface Logger {
+    info(msg: string): void;
+    success(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    plain(msg: string): void;
+}
+declare const RAW: {
+    readonly reset: `${string}[0m`;
+    readonly bold: `${string}[1m`;
+    readonly dim: `${string}[2m`;
+    readonly red: `${string}[31m`;
+    readonly green: `${string}[32m`;
+    readonly yellow: `${string}[33m`;
+    readonly blue: `${string}[34m`;
+    readonly cyan: `${string}[36m`;
+    readonly gray: `${string}[90m`;
+};
+type ColorName = keyof typeof RAW;
+export declare function colorEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function makePaint(enabled: boolean): (text: string, ...names: ColorName[]) => string;
+export interface ConsoleLike {
+    log(msg: string): void;
+    error(msg: string): void;
+}
+export declare function createLogger(opts?: {
+    console?: ConsoleLike;
+    color?: boolean;
+}): Logger;
+/** Shared painter for one-off styling outside the Logger (banners, summaries). */
+export declare const paint: (text: string, ...names: ColorName[]) => string;
+export {};

package/dist/logger.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Minimal, dependency-free, cross-platform colored logger.
+ *
+ * Color is disabled automatically when:
+ *  - stdout is not a TTY (piped / redirected output), or
+ *  - the NO_COLOR env var is set (https://no-color.org), or
+ *  - FORCE_COLOR=0.
+ *
+ * The Logger is an injectable interface so tests can capture output instead
+ * of writing to the real console.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paint = void 0;
+exports.colorEnabled = colorEnabled;
+exports.makePaint = makePaint;
+exports.createLogger = createLogger;
+const ESC = String.fromCharCode(27);
+const RAW = {
+    reset: `${ESC}[0m`,
+    bold: `${ESC}[1m`,
+    dim: `${ESC}[2m`,
+    red: `${ESC}[31m`,
+    green: `${ESC}[32m`,
+    yellow: `${ESC}[33m`,
+    blue: `${ESC}[34m`,
+    cyan: `${ESC}[36m`,
+    gray: `${ESC}[90m`,
+};
+function colorEnabled(env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return false;
+    if (env.FORCE_COLOR === '0')
+        return false;
+    if (env.FORCE_COLOR && env.FORCE_COLOR !== '0')
+        return true;
+    return Boolean(process.stdout && process.stdout.isTTY);
+}
+function makePaint(enabled) {
+    return (text, ...names) => {
+        if (!enabled || names.length === 0)
+            return text;
+        const open = names.map((n) => RAW[n]).join('');
+        return `${open}${text}${RAW.reset}`;
+    };
+}
+function createLogger(opts = {}) {
+    const sink = opts.console ?? {
+        log: (m) => process.stdout.write(m + '\n'),
+        error: (m) => process.stderr.write(m + '\n'),
+    };
+    const enabled = opts.color ?? colorEnabled();
+    const p = makePaint(enabled);
+    return {
+        plain: (m) => sink.log(m),
+        info: (m) => sink.log(`${p('•', 'cyan')} ${m}`),
+        success: (m) => sink.log(`${p('✓', 'green')} ${m}`),
+        warn: (m) => sink.log(`${p('!', 'yellow')} ${m}`),
+        error: (m) => sink.error(`${p('✗', 'red')} ${m}`),
+    };
+}
+/** Shared painter for one-off styling outside the Logger (banners, summaries). */
+exports.paint = makePaint(colorEnabled());

package/dist/manifest.d.ts

@@ -0,0 +1,18 @@
+export type EntryKind = 'regular' | 'claude-section';
+export interface ManifestEntry {
+    kind: EntryKind;
+    /** Absolute path to the source template inside the package. */
+    templateAbsPath: string;
+    /** Absolute path where it will be installed in the target project. */
+    targetAbsPath: string;
+    /** Forward-slash relative path for stable, readable CLI output. */
+    targetRelPath: string;
+}
+/**
+ * Build the install manifest by enumerating the bundled templates.
+ *
+ * Enumeration (rather than a hard-coded list) keeps the package
+ * maintainable: dropping a new `agents/*.md` template ships it with no
+ * code change.
+ */
+export declare function buildManifest(templatesDir: string, projectRoot: string): ManifestEntry[];

package/dist/manifest.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildManifest = buildManifest;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SECTION_FILE = 'CLAUDE.section.md';
+function listMarkdown(dir) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    return (0, node_fs_1.readdirSync)(dir)
+        .filter((f) => f.endsWith('.md'))
+        .sort();
+}
+/**
+ * Build the install manifest by enumerating the bundled templates.
+ *
+ * Enumeration (rather than a hard-coded list) keeps the package
+ * maintainable: dropping a new `agents/*.md` template ships it with no
+ * code change.
+ */
+function buildManifest(templatesDir, projectRoot) {
+    const entries = [];
+    for (const group of ['agents', 'commands']) {
+        const dir = (0, node_path_1.join)(templatesDir, group);
+        for (const file of listMarkdown(dir)) {
+            entries.push({
+                kind: 'regular',
+                templateAbsPath: (0, node_path_1.join)(dir, file),
+                targetAbsPath: (0, node_path_1.join)(projectRoot, '.claude', group, file),
+                targetRelPath: `.claude/${group}/${file}`,
+            });
+        }
+    }
+    const sectionTemplate = (0, node_path_1.join)(templatesDir, SECTION_FILE);
+    if ((0, node_fs_1.existsSync)(sectionTemplate)) {
+        entries.push({
+            kind: 'claude-section',
+            templateAbsPath: sectionTemplate,
+            targetAbsPath: (0, node_path_1.join)(projectRoot, 'CLAUDE.md'),
+            targetRelPath: 'CLAUDE.md',
+        });
+    }
+    return entries;
+}

package/dist/paths.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolve the bundled templates directory.
+ *
+ * Works in two layouts:
+ *  - Compiled:  dist/paths.js     -> dist/templates   (copied by build script)
+ *  - Tests/ts:  src/paths.ts      -> src/templates
+ *
+ * Both keep `templates/` as a sibling of this module, so __dirname is the
+ * single source of truth and no environment guessing is needed.
+ */
+export declare function getTemplatesDir(): string;
+/** Read the package version from package.json (sibling of dist/ or src/). */
+export declare function getVersion(): string;
+/** Normalize a user-supplied target directory to an absolute path. */
+export declare function resolveProjectRoot(cwd: string): string;

package/dist/paths.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTemplatesDir = getTemplatesDir;
+exports.getVersion = getVersion;
+exports.resolveProjectRoot = resolveProjectRoot;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Resolve the bundled templates directory.
+ *
+ * Works in two layouts:
+ *  - Compiled:  dist/paths.js     -> dist/templates   (copied by build script)
+ *  - Tests/ts:  src/paths.ts      -> src/templates
+ *
+ * Both keep `templates/` as a sibling of this module, so __dirname is the
+ * single source of truth and no environment guessing is needed.
+ */
+function getTemplatesDir() {
+    const local = (0, node_path_1.join)(__dirname, 'templates');
+    if ((0, node_fs_1.existsSync)(local))
+        return local;
+    throw new Error(`agentcohort: templates directory not found next to ${__dirname}. ` +
+        `The package may be corrupted; try reinstalling.`);
+}
+/** Read the package version from package.json (sibling of dist/ or src/). */
+function getVersion() {
+    const candidates = [
+        (0, node_path_1.join)(__dirname, '..', 'package.json'),
+        (0, node_path_1.join)(__dirname, '..', '..', 'package.json'),
+    ];
+    for (const c of candidates) {
+        try {
+            if (!(0, node_fs_1.existsSync)(c))
+                continue;
+            const pkg = JSON.parse((0, node_fs_1.readFileSync)(c, 'utf8'));
+            // Scope-resilient: matches "agentcohort" and "@scope/agentcohort".
+            if (typeof pkg.version === 'string' &&
+                typeof pkg.name === 'string' &&
+                pkg.name.replace(/^@[^/]+\//, '') === 'agentcohort') {
+                return pkg.version;
+            }
+        }
+        catch {
+            /* keep trying */
+        }
+    }
+    return '0.0.0';
+}
+/** Normalize a user-supplied target directory to an absolute path. */
+function resolveProjectRoot(cwd) {
+    return (0, node_path_1.resolve)(cwd);
+}

package/dist/prompt.d.ts

@@ -0,0 +1,32 @@
+import { Readable, Writable } from 'node:stream';
+export type Choice = 'skip' | 'overwrite' | 'backup';
+export interface ConflictContext {
+    targetRelPath: string;
+    /** 'regular' => file already exists & differs. 'claude-section' => our section already exists & differs. */
+    kind: 'regular' | 'claude-section';
+}
+export interface ConflictDecision {
+    choice: Choice;
+    /** Apply this same choice to every remaining conflict without re-asking. */
+    applyToAll: boolean;
+}
+export type ConflictResolver = (ctx: ConflictContext) => Promise<ConflictDecision>;
+/**
+ * Interactive resolver backed by readline.
+ *
+ * Key map (lowercase = this file only, UPPERCASE = all remaining conflicts):
+ *   s/S  skip
+ *   o/O  overwrite        (claude-section: replace our section in place)
+ *   b/B  backup + overwrite   <-- default for regular files
+ * For claude-section the safe default is "skip" (don't rewrite hand-edited
+ * routing rules unless asked).
+ */
+export declare function createInteractiveResolver(io?: {
+    input?: Readable;
+    output?: Writable;
+}): {
+    resolve: ConflictResolver;
+    close: () => void;
+};
+/** Non-interactive resolver: always returns the supplied safe decision. */
+export declare function fixedResolver(decision: ConflictDecision): ConflictResolver;

package/dist/prompt.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInteractiveResolver = createInteractiveResolver;
+exports.fixedResolver = fixedResolver;
+const promises_1 = require("node:readline/promises");
+/**
+ * Interactive resolver backed by readline.
+ *
+ * Key map (lowercase = this file only, UPPERCASE = all remaining conflicts):
+ *   s/S  skip
+ *   o/O  overwrite        (claude-section: replace our section in place)
+ *   b/B  backup + overwrite   <-- default for regular files
+ * For claude-section the safe default is "skip" (don't rewrite hand-edited
+ * routing rules unless asked).
+ */
+function createInteractiveResolver(io = {}) {
+    const rl = (0, promises_1.createInterface)({
+        input: io.input ?? process.stdin,
+        output: io.output ?? process.stdout,
+    });
+    const resolve = async (ctx) => {
+        const defaultChoice = ctx.kind === 'claude-section' ? 'skip' : 'backup';
+        const what = ctx.kind === 'claude-section'
+            ? `CLAUDE.md already has an "Agentcohort Routing Rules" section that differs`
+            : `${ctx.targetRelPath} already exists and differs`;
+        const defLabel = defaultChoice === 'skip' ? 's' : 'b';
+        const question = `\n${what}.\n` +
+            `  [s] skip   [o] overwrite   [b] backup + overwrite\n` +
+            `  (UPPERCASE applies to all remaining, default: ${defLabel}) > `;
+        // Loop until a valid answer (or EOF -> default).
+        for (;;) {
+            let answer;
+            try {
+                answer = (await rl.question(question)).trim();
+            }
+            catch {
+                return { choice: defaultChoice, applyToAll: true };
+            }
+            if (answer === '')
+                return { choice: defaultChoice, applyToAll: false };
+            const applyToAll = answer === answer.toUpperCase();
+            const key = answer[0].toLowerCase();
+            if (key === 's')
+                return { choice: 'skip', applyToAll };
+            if (key === 'o')
+                return { choice: 'overwrite', applyToAll };
+            if (key === 'b')
+                return { choice: 'backup', applyToAll };
+            // invalid -> ask again
+        }
+    };
+    return { resolve, close: () => rl.close() };
+}
+/** Non-interactive resolver: always returns the supplied safe decision. */
+function fixedResolver(decision) {
+    return async () => decision;
+}