@minniexcode/codex-switch 0.0.1 → 0.0.2

package/README.md

@@ -17,12 +17,9 @@ codexs
 
 ## Status
 
-This scoped package is currently being reserved and scaffolded for the first public release.
+The repository now contains the first end-to-end modular CLI implementation for the MVP command set defined in `docs/`.
 
-The product scope is already defined, but the full CLI feature set is not implemented yet. The first published versions may be bootstrap releases used to reserve the npm package name and establish the command entrypoint.
-
-If you install the package now, expect a minimal CLI shell rather than the complete switching workflow.
-The project is scaffolded as a TypeScript CLI and publishes compiled output from `dist/`.
+The project is implemented as a TypeScript CLI, builds into `dist/`, and is organized into `cli`, `app`, `domain`, and `infra` layers for maintainability.
 
 ## Why This Exists
 
@@ -55,15 +52,17 @@ Managing multiple Codex providers or profiles locally usually falls into two bad
 
 Core design principles:
 
-- `config.toml` remains the source of the active top-level `profile`
-- `providers.json` stores provider-to-profile and provider-to-key mappings
+- `providers.json` is the management-state single source of truth for provider metadata and mappings
+- `config.toml` and `auth.json` are runtime mirrors that codex-switch synchronizes safely
+- `backups/latest.json` tracks rollback state for the latest managed mutation window
 - all writes should be backed up first
 - failures should trigger rollback
+- write operations should execute under a lightweight single-process file lock
 - CLI output should stay stable and machine-readable
 
-## Planned MVP
+## MVP Commands
 
-The planned MVP command surface is:
+The current MVP command surface is:
 
 ```bash
 codexs list
@@ -78,7 +77,7 @@ codexs doctor
 codexs rollback
 ```
 
-Planned shared flags:
+Shared flags:
 
 ```bash
 --json
@@ -119,7 +118,7 @@ One-off execution:
 npx @minniexcode/codex-switch
 ```
 
-Current bootstrap behavior:
+Current CLI entry check:
 
 ```bash
 codexs --help
@@ -127,22 +126,46 @@ codexs --help
 
 ## Current Repository Contents
 
-This repository currently contains the product definition and PRD used to shape the first implementation:
+This repository contains both the product documents and the CLI implementation:
 
 - [Product Overview](./docs/codex-switch-product-overview.md)
 - [Product Research](./docs/codex-switch-product-research.md)
 - [PRD](./docs/codex-switch-prd.md)
+- [Technical Architecture](./docs/codex-switch-technical-architecture.md)
+- [Command Design](./docs/codex-switch-command-design.md)
+
+## Implementation Notes
+
+Current implementation characteristics:
+
+- modular TypeScript architecture split into `app`, `domain`, `infra`, and `cli`
+- repository-style infra modules for providers, config, backups, and write locks
+- a shared mutation orchestration contract that wraps backup, rollback, and lock handling
+- safe write flows with backup manifests under `backups/`
+- rollback support for `config.toml` and optional `auth.json`
+- `status` and `doctor` expose live-state drift so future backfill/edit/sync flows can reuse the same core model
+- stable `--json` envelopes for automation
+- test coverage in `tests/` using a custom serial runner (`tests/run-tests.js`) because the current environment hits `node --test` worker/spawn restrictions
+
+## Storage Model
 
-## Roadmap
+The current storage model is intentionally split:
 
-Near-term priorities:
+- management state: `providers.json`
+- runtime state: `config.toml` and `auth.json`
+- rollback state: `backups/latest.json` and timestamped backup manifests
 
-- publish the package name and CLI entrypoint
-- implement provider storage and validation
-- implement config backup and rollback
-- implement safe switching flow around `config.toml`
-- support structured `--json` output for automation
-- add cross-platform tests for Windows, macOS, and Linux paths
+That keeps the MVP file-based while preserving the same boundary a future database-backed registry would use.
+
+## Concurrency And Drift
+
+Current write semantics are intentionally lightweight:
+
+- every mutating command runs inside `~/.codex/.codex-switch.lock`
+- each mutation creates a backup first and rolls back on failure
+- `status` and `doctor` detect when the active runtime profile in `config.toml` is no longer mapped in `providers.json`
+
+That drift signal is the contract for future `edit`, `sync`, and explicit backfill flows. The current version detects and reports drift, but does not silently write live runtime changes back into the management registry.
 
 ## Non-Goals for MVP
 
@@ -156,13 +179,12 @@ The first version is not trying to be:
 
 ## Development
 
-At this stage the package is a bootstrap CLI shell. The implementation will follow the product documents in `docs/`.
-
 Local development:
 
 ```bash
 npm install
 npm run build
+npm test
 node dist/cli.js --help
 ```
 

package/dist/app/add-provider.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addProvider = addProvider;
+const providers_1 = require("../domain/providers");
+const errors_1 = require("../domain/errors");
+const fs_utils_1 = require("../infra/fs-utils");
+const providers_repo_1 = require("../infra/providers-repo");
+const run_mutation_1 = require("./run-mutation");
+/**
+ * Adds a new provider record to the managed providers registry.
+ */
+function addProvider(args) {
+    (0, fs_utils_1.ensureDir)(args.codexDir);
+    const providers = (0, providers_repo_1.readProvidersFileIfExists)(args.providersPath);
+    if (providers.providers[args.providerName]) {
+        throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", `Provider "${args.providerName}" already exists.`);
+    }
+    const next = {
+        providers: {
+            ...providers.providers,
+            [args.providerName]: (0, providers_1.cleanProviderRecord)({
+                profile: args.profile,
+                apiKey: args.apiKey,
+                baseUrl: args.baseUrl ?? undefined,
+                note: args.note ?? undefined,
+                tags: args.tags,
+            }),
+        },
+    };
+    return (0, run_mutation_1.runMutation)({
+        codexDir: args.codexDir,
+        backupsDir: args.backupsDir,
+        latestBackupPath: args.latestBackupPath,
+        operation: "add",
+        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        mutate: () => {
+            // Persist only the normalized provider payload so later reads are deterministic.
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, next);
+            return {
+                provider: args.providerName,
+                profile: args.profile,
+            };
+        },
+    });
+}

package/dist/app/export-providers.js

@@ -0,0 +1,62 @@
+"use strict";
+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.exportProviders = exportProviders;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const errors_1 = require("../domain/errors");
+const fs_utils_1 = require("../infra/fs-utils");
+const providers_repo_1 = require("../infra/providers-repo");
+/**
+ * Exports the current providers registry to a user-specified file.
+ */
+function exportProviders(args) {
+    const absoluteTarget = path.resolve(args.targetFile);
+    if (fs.existsSync(absoluteTarget) && !args.force) {
+        throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "Export target already exists. Re-run with --force to overwrite.", {
+            file: absoluteTarget,
+        });
+    }
+    const providers = (0, providers_repo_1.readProvidersFile)(args.providersPath);
+    // Create the target directory first so exports work for nested paths.
+    (0, fs_utils_1.ensureDir)(path.dirname(absoluteTarget));
+    (0, providers_repo_1.writeProvidersFile)(absoluteTarget, providers);
+    return {
+        data: {
+            exportedTo: absoluteTarget,
+            count: Object.keys(providers.providers).length,
+        },
+    };
+}

package/dist/app/get-current-profile.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentProfile = getCurrentProfile;
+const config_repo_1 = require("../infra/config-repo");
+/**
+ * Returns the currently active top-level Codex profile.
+ */
+function getCurrentProfile(configPath) {
+    return {
+        data: {
+            profile: (0, config_repo_1.readCurrentProfile)(configPath),
+        },
+    };
+}

package/dist/app/get-status.js

@@ -0,0 +1,75 @@
+"use strict";
+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.getStatus = getStatus;
+const fs = __importStar(require("node:fs"));
+const config_1 = require("../domain/config");
+const runtime_state_1 = require("../domain/runtime-state");
+const providers_repo_1 = require("../infra/providers-repo");
+/**
+ * Reports the current on-disk runtime state and how it maps back to managed providers.
+ */
+function getStatus(codexDir, configPath, providersPath) {
+    const configExists = fs.existsSync(configPath);
+    const providersExists = fs.existsSync(providersPath);
+    let currentProfile = null;
+    const warnings = [];
+    const providers = providersExists ? (0, providers_repo_1.readProvidersFile)(providersPath) : null;
+    if (configExists) {
+        const configContent = fs.readFileSync(configPath, "utf8");
+        currentProfile = (0, config_1.parseTopLevelProfile)(configContent);
+        if (!currentProfile) {
+            warnings.push("config.toml exists but has no top-level profile.");
+        }
+    }
+    const liveState = (0, runtime_state_1.inspectLiveStateDrift)(currentProfile, providers);
+    if (liveState.canBackfillActiveProvider) {
+        // Surface unmanaged live state without mutating anything during a read-only status call.
+        warnings.push("Current config profile is not mapped in providers.json. Backfill would be required before treating live state as managed.");
+    }
+    return {
+        warnings,
+        data: {
+            codexDir,
+            storage: (0, runtime_state_1.getStorageRoles)(),
+            configExists,
+            providersExists,
+            currentProfile,
+            currentProfileMapped: liveState.profileMapped,
+            provider: liveState.mappedProvider,
+            liveState,
+        },
+    };
+}

package/dist/app/import-providers.js

@@ -0,0 +1,74 @@
+"use strict";
+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.importProviders = importProviders;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const providers_1 = require("../domain/providers");
+const errors_1 = require("../domain/errors");
+const fs_utils_1 = require("../infra/fs-utils");
+const providers_repo_1 = require("../infra/providers-repo");
+const run_mutation_1 = require("./run-mutation");
+/**
+ * Imports provider definitions from an external JSON file into the managed registry.
+ */
+function importProviders(args) {
+    const absoluteSource = path.resolve(args.sourceFile);
+    let imported;
+    try {
+        // Validate before writing so malformed imports never touch the managed file.
+        imported = (0, providers_1.validateProvidersShape)(JSON.parse(fs.readFileSync(absoluteSource, "utf8")));
+    }
+    catch (error) {
+        throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "Import file is not valid providers.json data.", {
+            file: absoluteSource,
+            cause: (0, errors_1.normalizeError)(error).message,
+        });
+    }
+    (0, fs_utils_1.ensureDir)(args.codexDir);
+    return (0, run_mutation_1.runMutation)({
+        codexDir: args.codexDir,
+        backupsDir: args.backupsDir,
+        latestBackupPath: args.latestBackupPath,
+        operation: "import",
+        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        mutate: () => {
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, imported);
+            return {
+                importedProviders: Object.keys(imported.providers).sort(),
+            };
+        },
+    });
+}

package/dist/app/list-providers.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listProviders = listProviders;
+const providers_repo_1 = require("../infra/providers-repo");
+/**
+ * Returns the sorted list of configured providers for display.
+ */
+function listProviders(providersPath) {
+    const providers = (0, providers_repo_1.readProvidersFile)(providersPath);
+    const names = Object.keys(providers.providers).sort();
+    const items = names.map((name) => ({
+        name,
+        profile: providers.providers[name].profile,
+        note: providers.providers[name].note ?? null,
+        tags: providers.providers[name].tags ?? [],
+    }));
+    return {
+        data: {
+            providers: items,
+            count: items.length,
+        },
+    };
+}

package/dist/app/remove-provider.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeProvider = removeProvider;
+const errors_1 = require("../domain/errors");
+const providers_repo_1 = require("../infra/providers-repo");
+const run_mutation_1 = require("./run-mutation");
+/**
+ * Removes a provider from the managed providers registry.
+ */
+function removeProvider(args) {
+    const providers = (0, providers_repo_1.readProvidersFile)(args.providersPath);
+    if (!providers.providers[args.providerName]) {
+        throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", `Provider "${args.providerName}" was not found.`);
+    }
+    const nextProviders = { ...providers.providers };
+    // Delete against a copied object so the original parsed state stays untouched.
+    delete nextProviders[args.providerName];
+    return (0, run_mutation_1.runMutation)({
+        codexDir: args.codexDir,
+        backupsDir: args.backupsDir,
+        latestBackupPath: args.latestBackupPath,
+        operation: "remove",
+        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        mutate: () => {
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, { providers: nextProviders });
+            return {
+                provider: args.providerName,
+            };
+        },
+    });
+}

package/dist/app/rollback-latest.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rollbackLatest = rollbackLatest;
+const errors_1 = require("../domain/errors");
+const backup_repo_1 = require("../infra/backup-repo");
+/**
+ * Restores the most recent mutation backup recorded by codex-switch.
+ */
+function rollbackLatest(latestBackupPath) {
+    const manifest = (0, backup_repo_1.loadLatestManifest)(latestBackupPath);
+    try {
+        (0, backup_repo_1.restoreManifest)(manifest);
+        return {
+            data: {
+                restoredFiles: manifest.files.map((file) => file.relativePath),
+                backupPath: manifest.backupDir,
+            },
+        };
+    }
+    catch (error) {
+        throw (0, errors_1.cliError)("ROLLBACK_FAILED", "Rollback failed.", {
+            cause: (0, errors_1.normalizeError)(error).message,
+            backupPath: manifest.backupDir,
+        });
+    }
+}

package/dist/app/run-doctor.js

@@ -0,0 +1,130 @@
+"use strict";
+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.runDoctor = runDoctor;
+const fs = __importStar(require("node:fs"));
+const config_1 = require("../domain/config");
+const runtime_state_1 = require("../domain/runtime-state");
+const codex_cli_1 = require("../infra/codex-cli");
+const providers_repo_1 = require("../infra/providers-repo");
+const errors_1 = require("../domain/errors");
+/**
+ * Performs consistency checks across config.toml, providers.json, and the local Codex CLI.
+ */
+function runDoctor(args) {
+    const issues = [];
+    let configProfiles = new Set();
+    let currentProfile = null;
+    let providers = null;
+    if (!fs.existsSync(args.configPath)) {
+        issues.push({
+            code: "CONFIG_NOT_FOUND",
+            message: "config.toml does not exist.",
+            file: args.configPath,
+        });
+    }
+    else {
+        const configContent = fs.readFileSync(args.configPath, "utf8");
+        configProfiles = (0, config_1.parseProfileNames)(configContent);
+        currentProfile = (0, config_1.parseTopLevelProfile)(configContent);
+        if (!currentProfile) {
+            issues.push({
+                code: "PROFILE_NOT_FOUND",
+                message: "config.toml has no top-level profile.",
+                file: args.configPath,
+            });
+        }
+    }
+    if (!fs.existsSync(args.providersPath)) {
+        issues.push({
+            code: "PROVIDERS_NOT_FOUND",
+            message: "providers.json does not exist.",
+            file: args.providersPath,
+        });
+    }
+    else {
+        try {
+            providers = (0, providers_repo_1.readProvidersFile)(args.providersPath);
+            // Every managed provider must map to a profile that still exists in config.toml.
+            for (const [name, provider] of Object.entries(providers.providers)) {
+                if (!configProfiles.has(provider.profile)) {
+                    issues.push({
+                        code: "PROFILE_NOT_FOUND",
+                        message: `Provider "${name}" maps to missing profile "${provider.profile}".`,
+                        provider: name,
+                        profile: provider.profile,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            const normalized = (0, errors_1.normalizeError)(error);
+            issues.push({
+                code: normalized.code,
+                message: normalized.message,
+                ...(normalized.details ?? {}),
+            });
+        }
+    }
+    const drift = (0, runtime_state_1.inspectLiveStateDrift)(currentProfile, providers);
+    if (drift.canBackfillActiveProvider) {
+        // Distinguish unmanaged live state from hard parse/configuration errors.
+        issues.push({
+            code: "LIVE_STATE_DRIFT",
+            message: `Active profile "${drift.currentProfile}" is present in config.toml but not mapped by providers.json.`,
+            currentProfile: drift.currentProfile,
+            suggestedAction: "backfill-active-provider",
+            storage: (0, runtime_state_1.getStorageRoles)(),
+        });
+    }
+    const codexCheck = (0, codex_cli_1.checkCodexAvailable)();
+    if (!codexCheck.ok) {
+        issues.push({
+            code: "CODEX_LOGIN_FAILED",
+            message: "codex CLI is not available.",
+            cause: codexCheck.cause,
+        });
+    }
+    return {
+        data: {
+            healthy: issues.length === 0,
+            issues,
+            codexDir: args.codexDir,
+            storage: (0, runtime_state_1.getStorageRoles)(),
+            liveState: drift,
+        },
+        warnings: issues.length === 0 ? [] : [`doctor found ${issues.length} issue(s)`],
+    };
+}

package/dist/app/run-mutation.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMutation = runMutation;
+const errors_1 = require("../domain/errors");
+const backup_repo_1 = require("../infra/backup-repo");
+const lock_repo_1 = require("../infra/lock-repo");
+/**
+ * Runs a write operation under a lock with automatic backup and rollback handling.
+ */
+function runMutation(args) {
+    return (0, lock_repo_1.withCodexLock)(args.codexDir, args.operation, () => {
+        const backup = (0, backup_repo_1.createBackup)(args.codexDir, args.backupsDir, args.operation, args.files);
+        try {
+            const data = args.mutate({ backup });
+            // Record the successful backup only after the mutation completes.
+            (0, backup_repo_1.saveLatestManifest)(args.latestBackupPath, backup);
+            return {
+                data: {
+                    ...data,
+                    backupPath: backup.backupDir,
+                    managedState: {
+                        transaction: "single-process-file-lock",
+                        backupFiles: listBackedUpFiles(backup.files),
+                    },
+                },
+            };
+        }
+        catch (error) {
+            try {
+                // Roll back the managed files to their pre-mutation state on any failure.
+                (0, backup_repo_1.restoreManifest)(backup);
+            }
+            catch (rollbackError) {
+                throw (0, errors_1.cliError)("ROLLBACK_FAILED", `${capitalize(args.operation)} failed and rollback was not successful.`, {
+                    cause: (0, errors_1.normalizeError)(error).message,
+                    rollbackReason: (0, errors_1.normalizeError)(rollbackError).message,
+                    backupPath: backup.backupDir,
+                });
+            }
+            const baseError = (0, errors_1.normalizeError)(error);
+            throw (0, errors_1.cliError)(baseError.code, baseError.message, {
+                ...(baseError.details ?? {}),
+                rollbackApplied: true,
+                backupPath: backup.backupDir,
+            });
+        }
+    });
+}
+/**
+ * Lists the files that existed before the mutation and were captured in the backup.
+ */
+function listBackedUpFiles(files) {
+    return files.filter((entry) => entry.existed).map((entry) => entry.relativePath);
+}
+/**
+ * Uppercases the first character for human-readable operation names.
+ */
+function capitalize(value) {
+    if (value.length === 0) {
+        return value;
+    }
+    return `${value[0].toUpperCase()}${value.slice(1)}`;
+}