sela-core 0.1.0-alpha.1

package/dist/cli/ui/LocatorPicker.d.ts

@@ -0,0 +1,8 @@
+import type { LocatorEnumeration } from '../../services/SourceLinkService.js';
+/**
+ * Presents an interactive list when a source line contains multiple locators.
+ * Returns the 0-based index of the user's selection.
+ * Pre-selects the entry whose selector matches currentSelector (normalized comparison).
+ */
+export declare function pickLocator(locators: LocatorEnumeration[], currentSelector: string): Promise<number>;
+//# sourceMappingURL=LocatorPicker.d.ts.map

package/dist/cli/ui/LocatorPicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocatorPicker.d.ts","sourceRoot":"","sources":["../../../src/cli/ui/LocatorPicker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAE9E;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,MAAM,CAAC,CAsBjB"}

package/dist/cli/ui/LocatorPicker.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickLocator = pickLocator;
+const enquirer_js_1 = require("../../vendor/enquirer.js");
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Presents an interactive list when a source line contains multiple locators.
+ * Returns the 0-based index of the user's selection.
+ * Pre-selects the entry whose selector matches currentSelector (normalized comparison).
+ */
+async function pickLocator(locators, currentSelector) {
+    const norm = currentSelector.trim();
+    const defaultIdx = locators.findIndex((l) => l.selector.trim() === norm);
+    const choices = locators.map((l) => {
+        const isCurrent = l.selector.trim() === norm;
+        const hint = isCurrent ? chalk_1.default.dim('  ← current DNA selector') : '';
+        return {
+            name: String(l.index),
+            message: `[${l.index}]  ${chalk_1.default.yellow(l.preview)}${hint}`,
+        };
+    });
+    const prompt = new enquirer_js_1.Select({
+        name: 'locatorIndex',
+        message: `Line has ${locators.length} locators. Which are you refactoring?`,
+        choices,
+        initial: defaultIdx >= 0 ? defaultIdx : 0,
+    });
+    const result = (await prompt.run());
+    return parseInt(result, 10);
+}

package/dist/cli/ui/ProgressReporter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Wraps ora spinners. Pass silent=true (e.g. when --json active) to skip all
+ * spinner output and run the task directly. All spinner output goes to stderr
+ * so stdout stays pipe-clean.
+ */
+export declare class ProgressReporter {
+    private silent;
+    constructor(silent?: boolean);
+    run<T>(label: string, fn: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=ProgressReporter.d.ts.map

package/dist/cli/ui/ProgressReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgressReporter.d.ts","sourceRoot":"","sources":["../../../src/cli/ui/ProgressReporter.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAU;gBAEZ,MAAM,UAAQ;IAIpB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAY9D"}

package/dist/cli/ui/ProgressReporter.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProgressReporter = void 0;
+const ora_1 = __importDefault(require("ora"));
+/**
+ * Wraps ora spinners. Pass silent=true (e.g. when --json active) to skip all
+ * spinner output and run the task directly. All spinner output goes to stderr
+ * so stdout stays pipe-clean.
+ */
+class ProgressReporter {
+    silent;
+    constructor(silent = false) {
+        this.silent = silent;
+    }
+    async run(label, fn) {
+        if (this.silent)
+            return fn();
+        const spinner = (0, ora_1.default)({ text: label, stream: process.stderr }).start();
+        try {
+            const result = await fn();
+            spinner.succeed();
+            return result;
+        }
+        catch (err) {
+            spinner.fail();
+            throw err;
+        }
+    }
+}
+exports.ProgressReporter = ProgressReporter;

package/dist/cli/ui/RefactorWizard.d.ts

@@ -0,0 +1,26 @@
+import type { IDnaIndexService } from "../../services/DnaIndexService.js";
+import type { IDnaEditorService } from "../../services/DnaEditorService.js";
+import type { ISourceLinkService } from "../../services/SourceLinkService.js";
+export interface WizardOptions {
+    noSource?: boolean;
+    dryRun?: boolean;
+}
+interface WizardServices {
+    dnaIndex: IDnaIndexService;
+    dnaEditor: IDnaEditorService;
+    sourceLink: ISourceLinkService;
+}
+export declare class RefactorWizard {
+    private readonly svc;
+    private readonly opts;
+    constructor(svc: WizardServices, opts?: WizardOptions);
+    run(initialKey?: string): Promise<void>;
+    private resolveKey;
+    private selectDna;
+    private selectField;
+    private editValue;
+    private confirm;
+    private buildDnaPatch;
+}
+export {};
+//# sourceMappingURL=RefactorWizard.d.ts.map

package/dist/cli/ui/RefactorWizard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RefactorWizard.d.ts","sourceRoot":"","sources":["../../../src/cli/ui/RefactorWizard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAM9E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,cAAc;IACtB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,iBAAiB,CAAC;IAC7B,UAAU,EAAE,kBAAkB,CAAC;CAChC;AA6HD,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,GAAG,EAAE,cAAc,EACnB,IAAI,GAAE,aAAkB;IAGrC,GAAG,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwH7C,OAAO,CAAC,UAAU;YAUJ,SAAS;YAwBT,WAAW;YA+BX,SAAS;YA4BT,OAAO;IAKrB,OAAO,CAAC,aAAa;CAMtB"}

package/dist/cli/ui/RefactorWizard.js

@@ -0,0 +1,295 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefactorWizard = void 0;
+const enquirer_js_1 = require("../../vendor/enquirer.js");
+const chalk_1 = __importDefault(require("chalk"));
+const path_1 = __importDefault(require("path"));
+const LocatorPicker_js_1 = require("./LocatorPicker.js");
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function formatValue(v) {
+    if (v === null || v === undefined)
+        return chalk_1.default.dim("null");
+    if (typeof v === "object")
+        return JSON.stringify(v, null, 2);
+    return String(v);
+}
+function parseInput(field, raw) {
+    if (field === "text")
+        return raw.trim() === "" ? null : raw;
+    if (field === "attributes" || field === "anchors") {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return raw;
+}
+function getFieldValue(field, record, snap) {
+    switch (field) {
+        case "selector":
+            return record.selector;
+        case "text":
+            return record.text;
+        case "tagName":
+            return record.tagName;
+        case "attributes":
+            return snap.attributes;
+        case "anchors":
+            return snap.anchors;
+    }
+}
+function validateField(field, value) {
+    const errs = [];
+    switch (field) {
+        case "selector":
+            if (typeof value !== "string" || value.trim() === "")
+                errs.push("selector must not be empty");
+            if (value === "undefined")
+                errs.push('selector must not be the string "undefined"');
+            if (typeof value === "string" && /[\r\n]/.test(value))
+                errs.push("selector must not contain raw newlines");
+            break;
+        case "text":
+            if (value !== null && typeof value !== "string")
+                errs.push("text must be a string or null");
+            if (typeof value === "string" && value.length >= 2000)
+                errs.push("text must be fewer than 2000 characters");
+            break;
+        case "tagName":
+            if (typeof value !== "string" || !/^[a-z][a-z0-9-]*$/.test(value))
+                errs.push("tagName must match /^[a-z][a-z0-9-]*$/");
+            break;
+        case "attributes":
+            if (typeof value !== "object" || value === null || Array.isArray(value))
+                errs.push("attributes must be a plain object (JSON)");
+            break;
+        case "anchors":
+            if (typeof value !== "object" || value === null)
+                errs.push("anchors must be an object (JSON)");
+            break;
+    }
+    return errs;
+}
+function showRecordCard(record) {
+    const w = 62;
+    const line = (label, value) => {
+        const content = `  ${chalk_1.default.dim(label.padEnd(14))}  ${value}`;
+        process.stdout.write(content + "\n");
+    };
+    process.stdout.write("\n" + chalk_1.default.dim("─".repeat(w)) + "\n");
+    line("Key", chalk_1.default.dim(record.key));
+    line("Selector", chalk_1.default.yellow(record.selector));
+    line("Tag", record.tagName);
+    line("Text", record.text ? chalk_1.default.cyan(record.text.slice(0, 40)) : chalk_1.default.dim("-"));
+    if (record.sourceFile) {
+        const rel = path_1.default.relative(process.cwd(), record.sourceFile);
+        line("Source", `${rel}:${record.sourceLine}`);
+    }
+    line("Last Healed", record.lastHealed
+        ? new Date(record.lastHealed).toLocaleDateString()
+        : chalk_1.default.dim("never"));
+    line("Status", record.isOrphaned
+        ? chalk_1.default.red("orphaned")
+        : record.lastHealed
+            ? chalk_1.default.green("healed")
+            : chalk_1.default.cyan("active"));
+    process.stdout.write(chalk_1.default.dim("─".repeat(w)) + "\n\n");
+}
+function showDiff(field, oldVal, newVal) {
+    process.stdout.write("\n");
+    process.stdout.write(`  ${chalk_1.default.bold("Preview - " + field)}\n`);
+    process.stdout.write(`  ${"─".repeat(56)}\n`);
+    process.stdout.write(`  ${chalk_1.default.red("−")} ${chalk_1.default.red(formatValue(oldVal))}\n`);
+    process.stdout.write(`  ${chalk_1.default.green("+")} ${chalk_1.default.green(formatValue(newVal))}\n`);
+    process.stdout.write("\n");
+}
+// ── RefactorWizard ────────────────────────────────────────────────────────────
+class RefactorWizard {
+    svc;
+    opts;
+    constructor(svc, opts = {}) {
+        this.svc = svc;
+        this.opts = opts;
+    }
+    async run(initialKey) {
+        // ── SELECT_DNA ────────────────────────────────────────────────
+        let record = initialKey
+            ? this.resolveKey(initialKey)
+            : await this.selectDna();
+        // Load full snapshot once (needed for attributes/anchors fields)
+        let snap = await this.svc.dnaEditor.read(record.key);
+        // Edit loop - user can edit multiple fields per session
+        for (;;) {
+            // ── SHOW_CURRENT ──────────────────────────────────────────
+            showRecordCard(record);
+            // ── SELECT_FIELD ──────────────────────────────────────────
+            const field = await this.selectField();
+            // ── LOCATOR_DISAMBIGUATE (selector field only) ────────────
+            let locatorIndex = 0;
+            if (field === "selector" && record.sourceFile && record.sourceLine > 0) {
+                const locators = this.svc.sourceLink.enumerateLocatorsOnLine(record.sourceFile, record.sourceLine);
+                if (locators.length > 1) {
+                    locatorIndex = await (0, LocatorPicker_js_1.pickLocator)(locators, record.selector);
+                }
+            }
+            // ── EDIT_VALUE + VALIDATE (loop on error) ─────────────────
+            const oldValue = getFieldValue(field, record, snap);
+            let newValue;
+            for (;;) {
+                newValue = await this.editValue(field, oldValue);
+                const errs = validateField(field, newValue);
+                if (errs.length === 0)
+                    break;
+                process.stdout.write("\n");
+                for (const e of errs) {
+                    process.stdout.write(`  ${chalk_1.default.red("✗")} ${e}\n`);
+                }
+                process.stdout.write("\n");
+            }
+            // ── PREVIEW_DIFF ──────────────────────────────────────────
+            showDiff(field, oldValue, newValue);
+            // ── CONFIRM ───────────────────────────────────────────────
+            const apply = await this.confirm("Apply changes?");
+            if (!apply) {
+                const again = await this.confirm("Edit another field?");
+                if (!again)
+                    break;
+                continue;
+            }
+            // ── APPLY_SOURCE? ─────────────────────────────────────────
+            let applySource = false;
+            if (!this.opts.noSource &&
+                field === "selector" &&
+                record.sourceFile &&
+                record.sourceLine > 0) {
+                applySource = await this.confirm("Also update .spec.ts source file?");
+            }
+            // ── COMMIT ────────────────────────────────────────────────
+            const patch = {
+                key: record.key,
+                field,
+                oldValue,
+                newValue,
+                applySourceUpdate: applySource,
+                locatorIndex,
+            };
+            if (this.opts.dryRun) {
+                process.stdout.write(`\n  ${chalk_1.default.yellow("[dry-run]")} Would write: ${JSON.stringify({ field, newValue })}\n\n`);
+            }
+            else {
+                const bakPath = await this.svc.dnaEditor.write(record.key, this.buildDnaPatch(field, newValue));
+                process.stdout.write(`\n  ${chalk_1.default.green("✓")} DNA written. Backup: ${chalk_1.default.dim(path_1.default.basename(bakPath))}\n`);
+                if (applySource) {
+                    const result = await this.svc.sourceLink.applySourceUpdate(record, patch);
+                    if (result.success) {
+                        process.stdout.write(`  ${chalk_1.default.green("✓")} Source updated on line ${result.lineUpdated ?? record.sourceLine}\n`);
+                    }
+                    else {
+                        process.stdout.write(`  ${chalk_1.default.yellow("⚠")} Source update: ${result.reason}\n`);
+                    }
+                }
+                // Refresh record from index after write
+                snap = await this.svc.dnaEditor.read(record.key);
+                const refreshed = this.svc.dnaIndex.getByKey(record.key);
+                if (refreshed)
+                    record = refreshed;
+            }
+            // ── DONE / CONTINUE? ─────────────────────────────────────
+            const another = await this.confirm("Edit another field?");
+            if (!another)
+                break;
+        }
+        process.stdout.write("\n" + chalk_1.default.dim("Wizard complete.") + "\n\n");
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    resolveKey(key) {
+        const record = this.svc.dnaIndex.getByKey(key);
+        if (!record) {
+            const err = new Error(`DNA not found: ${key}`);
+            err.code = "DNA_NOT_FOUND";
+            throw err;
+        }
+        return record;
+    }
+    async selectDna() {
+        const records = this.svc.dnaIndex.getIndex().records;
+        if (records.length === 0) {
+            const err = new Error("No DNA records found in snapshot directory");
+            err.code = "SNAPSHOT_DIR_MISSING";
+            throw err;
+        }
+        const choices = records.map((r) => ({
+            name: r.key,
+            message: `${chalk_1.default.dim(r.key.slice(0, 8))}  ${r.selector.padEnd(40).slice(0, 40)}  ${chalk_1.default.dim(r.testTitle.slice(0, 30))}`,
+        }));
+        const prompt = new enquirer_js_1.AutoComplete({
+            name: "dna",
+            message: "Search DNA record (type to filter)",
+            limit: 10,
+            choices,
+        });
+        const key = (await prompt.run());
+        return this.resolveKey(key);
+    }
+    async selectField() {
+        const prompt = new enquirer_js_1.Select({
+            name: "field",
+            message: "Which field to edit?",
+            choices: [
+                {
+                    name: "selector",
+                    message: `${chalk_1.default.yellow("selector")}    CSS/Playwright selector`,
+                },
+                {
+                    name: "text",
+                    message: `${chalk_1.default.cyan("text")}        Visible element text`,
+                },
+                {
+                    name: "tagName",
+                    message: `${chalk_1.default.dim("tagName")}     HTML tag name`,
+                },
+                {
+                    name: "attributes",
+                    message: `${chalk_1.default.dim("attributes")}  Element attributes (JSON)`,
+                },
+                {
+                    name: "anchors",
+                    message: `${chalk_1.default.dim("anchors")}     Anchor context (JSON)`,
+                },
+            ],
+        });
+        return (await prompt.run());
+    }
+    async editValue(field, current) {
+        const initialStr = current === null || current === undefined
+            ? ""
+            : typeof current === "object"
+                ? JSON.stringify(current, null, 2)
+                : String(current);
+        const hint = field === "text"
+            ? " (leave blank for null)"
+            : field === "attributes" || field === "anchors"
+                ? " (JSON)"
+                : "";
+        const prompt = new enquirer_js_1.Input({
+            name: "value",
+            message: `New ${field}${hint}`,
+            initial: initialStr,
+        });
+        const raw = (await prompt.run());
+        return parseInput(field, raw);
+    }
+    async confirm(message) {
+        const prompt = new enquirer_js_1.Confirm({ name: "ok", message });
+        return (await prompt.run());
+    }
+    buildDnaPatch(field, newValue) {
+        return { [field]: newValue };
+    }
+}
+exports.RefactorWizard = RefactorWizard;

package/dist/config/ConfigLoader.d.ts

@@ -0,0 +1,16 @@
+import { ResolvedConfig } from "./SelaConfig";
+export declare class ConfigLoader {
+    private static resolved;
+    private static branch;
+    /**
+     * Returns the fully resolved config.  First call does all I/O; subsequent
+     * calls return the cached result at zero cost.
+     */
+    static getInstance(): ResolvedConfig;
+    private static logEnvBanners;
+    /** Returns the detected Git branch name, or null if detection failed. */
+    static getBranch(): string | null;
+    /** Clears the singleton cache - useful for testing. */
+    static reset(): void;
+}
+//# sourceMappingURL=ConfigLoader.d.ts.map

package/dist/config/ConfigLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigLoader.d.ts","sourceRoot":"","sources":["../../src/config/ConfigLoader.ts"],"names":[],"mappings":"AAQA,OAAO,EAAc,cAAc,EAAiB,MAAM,cAAc,CAAC;AA6GzE,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA+B;IACtD,OAAO,CAAC,MAAM,CAAC,MAAM,CAAuB;IAE5C;;;OAGG;IACH,MAAM,CAAC,WAAW,IAAI,cAAc;IAuCpC,OAAO,CAAC,MAAM,CAAC,aAAa;IAW5B,yEAAyE;IACzE,MAAM,CAAC,SAAS,IAAI,MAAM,GAAG,IAAI;IAMjC,uDAAuD;IACvD,MAAM,CAAC,KAAK,IAAI,IAAI;CAIrB"}

package/dist/config/ConfigLoader.js

@@ -0,0 +1,185 @@
+"use strict";
+// src/config/ConfigLoader.ts
+// Locates sela.config.ts|js, detects the current Git branch, deep-merges
+// the base config with any branch override, and caches the resolved result
+// for the lifetime of the process (singleton pattern).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const SelaConfig_1 = require("./SelaConfig");
+const logger_1 = require("../utils/logger");
+// ─────────────────────────────────────────────────────────────────
+// FILE DISCOVERY
+// ─────────────────────────────────────────────────────────────────
+function findConfigFile(startDir) {
+    let dir = startDir;
+    while (true) {
+        for (const name of ["sela.config.ts", "sela.config.js"]) {
+            const candidate = path.join(dir, name);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null; // reached filesystem root
+        dir = parent;
+    }
+}
+// ─────────────────────────────────────────────────────────────────
+// GIT BRANCH DETECTION
+// ─────────────────────────────────────────────────────────────────
+function getCurrentBranch() {
+    try {
+        // Fail fast if not a git repo or git is unavailable
+        const branch = (0, child_process_1.execSync)("git rev-parse --abbrev-ref HEAD", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        if (branch === "HEAD") {
+            // Detached HEAD (common in CI with explicit SHA checkout)
+            logger_1.logger.warn("Detached HEAD detected - branch overrides skipped");
+            return null;
+        }
+        return branch;
+    }
+    catch {
+        logger_1.logger.warn("Git branch detection failed - branch overrides skipped");
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────
+// CONFIG FILE LOADING
+// ─────────────────────────────────────────────────────────────────
+function loadRawConfig(configPath) {
+    try {
+        // Works in Playwright test context (TypeScript loader registered by @playwright/test)
+        // and in Jest context (ts-jest). Falls back gracefully if neither is active.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require(configPath);
+        const config = mod?.default ?? mod ?? {};
+        if (typeof config !== "object" || config === null) {
+            logger_1.logger.warn(`sela.config did not export an object - using defaults`);
+            return {};
+        }
+        return config;
+    }
+    catch (err) {
+        logger_1.logger.warn(`Failed to load ${path.basename(configPath)}: ${err.message}`);
+        return {};
+    }
+}
+// ─────────────────────────────────────────────────────────────────
+// DEEP MERGE  (plain objects only - arrays are replaced, not merged)
+// ─────────────────────────────────────────────────────────────────
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        const baseVal = result[key];
+        const overrideVal = override[key];
+        if (overrideVal !== null &&
+            typeof overrideVal === "object" &&
+            !Array.isArray(overrideVal) &&
+            baseVal !== null &&
+            typeof baseVal === "object" &&
+            !Array.isArray(baseVal)) {
+            result[key] = deepMerge(baseVal, overrideVal);
+        }
+        else if (overrideVal !== undefined) {
+            result[key] = overrideVal;
+        }
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────
+// SINGLETON LOADER
+// ─────────────────────────────────────────────────────────────────
+class ConfigLoader {
+    static resolved = null;
+    static branch = null;
+    /**
+     * Returns the fully resolved config.  First call does all I/O; subsequent
+     * calls return the cached result at zero cost.
+     */
+    static getInstance() {
+        if (ConfigLoader.resolved)
+            return ConfigLoader.resolved;
+        const configPath = findConfigFile(process.cwd());
+        if (!configPath) {
+            // Zero-breaking-change guarantee: no config → pure defaults
+            ConfigLoader.resolved = (0, SelaConfig_1.resolveConfig)({});
+            ConfigLoader.logEnvBanners(ConfigLoader.resolved);
+            return ConfigLoader.resolved;
+        }
+        logger_1.logger.debug(`Loaded config from: ${path.relative(process.cwd(), configPath)}`);
+        let rawConfig = loadRawConfig(configPath);
+        // Apply branch overrides using exact-string matching
+        const detectedBranch = getCurrentBranch();
+        ConfigLoader.branch = detectedBranch;
+        if (rawConfig.branchOverrides && detectedBranch) {
+            const override = rawConfig.branchOverrides[detectedBranch];
+            if (override) {
+                logger_1.logger.debug(`Applying branch override for: ${detectedBranch}`);
+                rawConfig = deepMerge(rawConfig, override);
+            }
+        }
+        ConfigLoader.resolved = (0, SelaConfig_1.resolveConfig)(rawConfig);
+        ConfigLoader.logEnvBanners(ConfigLoader.resolved);
+        return ConfigLoader.resolved;
+    }
+    static logEnvBanners(resolved) {
+        if (resolved.dryRun) {
+            logger_1.logger.info("DRY RUN active (SELA_DRY_RUN) - disk writes & git commits suppressed.");
+        }
+        if (resolved.noCache) {
+            logger_1.logger.info("Cache disabled (SELA_NO_CACHE).");
+        }
+    }
+    /** Returns the detected Git branch name, or null if detection failed. */
+    static getBranch() {
+        // Ensure getInstance() has been called at least once
+        if (!ConfigLoader.resolved)
+            ConfigLoader.getInstance();
+        return ConfigLoader.branch;
+    }
+    /** Clears the singleton cache - useful for testing. */
+    static reset() {
+        ConfigLoader.resolved = null;
+        ConfigLoader.branch = null;
+    }
+}
+exports.ConfigLoader = ConfigLoader;

package/dist/config/DryRunGuard.d.ts

@@ -0,0 +1,14 @@
+export declare const DryRunGuard: {
+    /**
+     * Returns true when `SELA_DRY_RUN` is set to a truthy value in the current
+     * process environment. Throws via `parseEnvBoolean` when the value is not
+     * one of the accepted tokens - fail-fast keeps misconfigured CI loud.
+     */
+    active(env?: NodeJS.ProcessEnv): boolean;
+    /**
+     * Centralised log line for skipped writes so the diff between a dry run
+     * and a real run is auditable in test output and CI logs.
+     */
+    logSkippedWrite(label: string, target: string): void;
+};
+//# sourceMappingURL=DryRunGuard.d.ts.map

package/dist/config/DryRunGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DryRunGuard.d.ts","sourceRoot":"","sources":["../../src/config/DryRunGuard.ts"],"names":[],"mappings":"AA4BA,eAAO,MAAM,WAAW;IACtB;;;;OAIG;iBACS,MAAM,CAAC,UAAU,GAAiB,OAAO;IAIrD;;;OAGG;2BACoB,MAAM,UAAU,MAAM,GAAG,IAAI;CAIrD,CAAC"}