@minniexcode/codex-switch 0.0.3 → 0.0.5

package/dist/app/list-config-profiles.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listConfigProfilesView = listConfigProfilesView;
+const config_1 = require("../domain/config");
+const config_repo_1 = require("../infra/config-repo");
+const providers_repo_1 = require("../infra/providers-repo");
+/**
+ * Returns the lightweight config profile listing.
+ */
+function listConfigProfilesView(args) {
+    const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
+    const providers = (0, providers_repo_1.readProvidersFileIfExists)(args.providersPath);
+    const profiles = (0, config_1.buildManagedProfileViews)(document, providers).map((profile) => ({
+        name: profile.name,
+        managed: profile.managed,
+        isActive: profile.isActive,
+        linkedProviders: profile.linkedProviders,
+        model: profile.model,
+        baseUrl: profile.baseUrl,
+        source: profile.source,
+    }));
+    return {
+        data: {
+            activeProfile: document.activeProfile,
+            profiles,
+            count: profiles.length,
+        },
+    };
+}

package/dist/app/remove-provider.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeProvider = removeProvider;
 const errors_1 = require("../domain/errors");
+const config_1 = require("../domain/config");
+const config_repo_1 = require("../infra/config-repo");
 const providers_repo_1 = require("../infra/providers-repo");
 const run_mutation_1 = require("./run-mutation");
 /**
@@ -9,22 +11,52 @@ const run_mutation_1 = require("./run-mutation");
  */
 function removeProvider(args) {
     const providers = (0, providers_repo_1.readProvidersFile)(args.providersPath);
-    if (!providers.providers[args.providerName]) {
+    const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
+    const current = providers.providers[args.providerName];
+    if (!current) {
         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];
+    const remainingLinksByProfile = new Map();
+    for (const [name, provider] of Object.entries(nextProviders)) {
+        const list = remainingLinksByProfile.get(provider.profile) ?? [];
+        list.push(name);
+        remainingLinksByProfile.set(provider.profile, list);
+    }
+    const lifecycle = (0, config_1.planProfileLifecycleOutcome)({
+        providerName: args.providerName,
+        oldProfile: current.profile,
+        newProfile: null,
+        activeProfile: document.activeProfile,
+        remainingLinksByProfile,
+        switchToProfile: args.switchToProfile ?? null,
+    });
     return (0, run_mutation_1.runMutation)({
         codexDir: args.codexDir,
         backupsDir: args.backupsDir,
         latestBackupPath: args.latestBackupPath,
         operation: "remove",
-        files: [{ absolutePath: args.providersPath, relativePath: "providers.json" }],
+        files: [
+            { absolutePath: args.providersPath, relativePath: "providers.json" },
+            { absolutePath: args.configPath, relativePath: "config.toml" },
+        ],
         mutate: () => {
+            const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
+                deleteProfiles: lifecycle.deletedProfileSections,
+                setActiveProfile: lifecycle.nextActiveProfile,
+            });
             (0, providers_repo_1.writeProvidersFile)(args.providersPath, { providers: nextProviders });
+            (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
             return {
                 provider: args.providerName,
+                createdProfileSections: configPlan.createdProfileSections,
+                deletedProfileSections: configPlan.deletedProfileSections,
+                keptSharedProfiles: lifecycle.keptSharedProfiles,
+                switchedActiveProfile: lifecycle.switchedActiveProfile,
+                adoptedProfiles: [],
+                repairedProfiles: [],
             };
         },
     });

package/dist/app/rollback-backup.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rollbackBackup = rollbackBackup;
+const errors_1 = require("../domain/errors");
+const backup_repo_1 = require("../infra/backup-repo");
+/**
+ * Restores either the latest backup or a specific historical backup by id.
+ */
+function rollbackBackup(args) {
+    const manifest = args.backupId
+        ? (0, backup_repo_1.loadManifestById)(args.backupsDir, args.backupId)
+        : (0, backup_repo_1.loadLatestManifest)(args.latestBackupPath);
+    try {
+        (0, backup_repo_1.restoreManifest)(manifest);
+        return {
+            data: {
+                restoredFiles: manifest.files.map((file) => file.relativePath),
+                backupId: args.backupId ?? null,
+                backupPath: manifest.backupDir,
+            },
+        };
+    }
+    catch (error) {
+        throw (0, errors_1.cliError)("ROLLBACK_FAILED", "Rollback failed.", {
+            cause: (0, errors_1.normalizeError)(error).message,
+            backupPath: manifest.backupDir,
+            backupId: args.backupId ?? null,
+        });
+    }
+}

package/dist/app/run-doctor.js

@@ -38,6 +38,7 @@ 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 config_repo_1 = require("../infra/config-repo");
 const providers_repo_1 = require("../infra/providers-repo");
 const errors_1 = require("../domain/errors");
 /**
@@ -45,9 +46,9 @@ const errors_1 = require("../domain/errors");
  */
 function runDoctor(args) {
     const issues = [];
-    let configProfiles = new Set();
     let currentProfile = null;
     let providers = null;
+    let document = null;
     if (!fs.existsSync(args.configPath)) {
         issues.push({
             code: "CONFIG_NOT_FOUND",
@@ -56,9 +57,8 @@ function runDoctor(args) {
         });
     }
     else {
-        const configContent = fs.readFileSync(args.configPath, "utf8");
-        configProfiles = (0, config_1.parseProfileNames)(configContent);
-        currentProfile = (0, config_1.parseTopLevelProfile)(configContent);
+        document = (0, config_repo_1.readStructuredConfig)(args.configPath);
+        currentProfile = document.activeProfile;
         if (!currentProfile) {
             issues.push({
                 code: "PROFILE_NOT_FOUND",
@@ -77,14 +77,11 @@ function runDoctor(args) {
     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)) {
+            if (document) {
+                for (const issue of (0, config_1.collectConfigConsistencyIssues)(document, providers)) {
                     issues.push({
-                        code: "PROFILE_NOT_FOUND",
-                        message: `Provider "${name}" maps to missing profile "${provider.profile}".`,
-                        provider: name,
-                        profile: provider.profile,
+                        ...issue,
+                        message: renderConfigIssueMessage(issue),
                     });
                 }
             }
@@ -99,16 +96,6 @@ function runDoctor(args) {
         }
     }
     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({
@@ -128,3 +115,17 @@ function runDoctor(args) {
         warnings: issues.length === 0 ? [] : [`doctor found ${issues.length} issue(s)`],
     };
 }
+function renderConfigIssueMessage(issue) {
+    switch (issue.code) {
+        case "ORPHANED_PROFILE_REFERENCE":
+            return `Profile "${issue.profile}" is referenced by providers but missing from config.toml.`;
+        case "UNMANAGED_ACTIVE_PROFILE":
+            return `Active profile "${issue.profile}" is not mapped by providers.json.`;
+        case "SHARED_PROFILE_REFERENCE":
+            return `Profile "${issue.profile}" is shared by multiple providers.`;
+        case "ORPHANED_PROFILE_SECTION":
+            return `Profile section "${issue.profile}" is not linked to any provider.`;
+        case "DESTRUCTIVE_REMOVE_BLOCKED":
+            return `Provider "${issue.provider}" cannot be removed while "${issue.activeProfile}" remains active.`;
+    }
+}

package/dist/app/setup-codex.js

@@ -0,0 +1,155 @@
+"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.setupCodex = setupCodex;
+const fs = __importStar(require("node:fs"));
+const setup_1 = require("../domain/setup");
+const errors_1 = require("../domain/errors");
+const config_1 = require("../domain/config");
+const codex_cli_1 = require("../infra/codex-cli");
+const config_repo_1 = require("../infra/config-repo");
+const fs_utils_1 = require("../infra/fs-utils");
+const providers_repo_1 = require("../infra/providers-repo");
+const run_doctor_1 = require("./run-doctor");
+const run_mutation_1 = require("./run-mutation");
+const MIN_CODEX_VERSION = "0.0.1";
+/**
+ * Bootstraps a managed providers.json from the existing Codex directory.
+ */
+function setupCodex(args) {
+    const available = (0, codex_cli_1.checkCodexAvailable)();
+    if (!available.ok) {
+        throw (0, errors_1.cliError)("CODEX_NOT_INSTALLED", "codex CLI is not available.", {
+            cause: available.cause,
+        });
+    }
+    const version = (0, codex_cli_1.checkCodexVersion)(MIN_CODEX_VERSION);
+    if (!version.ok) {
+        throw (0, errors_1.cliError)("CODEX_VERSION_UNSUPPORTED", "codex CLI version is below the supported minimum.", {
+            minimumVersion: MIN_CODEX_VERSION,
+            currentVersion: version.currentVersion ?? null,
+            cause: version.cause,
+        });
+    }
+    if (!fs.existsSync(args.codexDir)) {
+        throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "The requested Codex directory does not exist.", {
+            codexDir: args.codexDir,
+        });
+    }
+    const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
+    const profileViews = (0, config_1.buildManagedProfileViews)(document, null);
+    const adoptableProfiles = profileViews
+        .filter((view) => view.source === "unmanaged" && view.model && view.baseUrl)
+        .map((view) => view.name)
+        .sort();
+    if (profileViews.length === 0) {
+        throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", "No profiles were found in config.toml.", {
+            file: args.configPath,
+        });
+    }
+    const invalidAdoptProfiles = args.adoptProfiles.filter((profile) => !adoptableProfiles.includes(profile));
+    if (invalidAdoptProfiles.length > 0) {
+        throw (0, errors_1.cliError)("INVALID_ARGUMENT", "setup only adopts unmanaged profiles that already contain model and base_url.", {
+            invalidProfiles: invalidAdoptProfiles.sort(),
+            adoptableProfiles,
+        });
+    }
+    if (args.adoptProfiles.length === 0) {
+        throw (0, errors_1.cliError)("INVALID_ARGUMENT", "setup requires at least one explicit profile to adopt.", {
+            adoptableProfiles,
+        });
+    }
+    const drafts = (0, setup_1.buildSetupDrafts)(args.adoptProfiles, args.providerDetailsByProfile);
+    const incompleteProfiles = (0, setup_1.findIncompleteSetupProfiles)(drafts);
+    if (incompleteProfiles.length > 0) {
+        throw (0, errors_1.cliError)("INVALID_ARGUMENT", "setup requires complete provider data for every selected profile.", {
+            incompleteProfiles,
+        });
+    }
+    (0, fs_utils_1.ensureDir)(args.codexDir);
+    const currentProviders = (0, providers_repo_1.readProvidersFileIfExists)(args.providersPath);
+    const providersExists = fs.existsSync(args.providersPath);
+    if (providersExists && args.strategy !== "merge" && args.strategy !== "overwrite") {
+        throw (0, errors_1.cliError)("PROVIDERS_ALREADY_EXISTS", "providers.json already exists.", {
+            file: args.providersPath,
+        });
+    }
+    const nextProviders = {
+        providers: drafts.reduce((accumulator, draft) => {
+            accumulator[draft.providerName] = draft.record;
+            return accumulator;
+        }, {}),
+    };
+    const finalProviders = args.strategy === "merge" ? (0, providers_repo_1.mergeProviders)(currentProviders, nextProviders) : nextProviders;
+    const result = (0, run_mutation_1.runMutation)({
+        codexDir: args.codexDir,
+        backupsDir: args.backupsDir,
+        latestBackupPath: args.latestBackupPath,
+        operation: "setup",
+        files: [
+            { absolutePath: args.providersPath, relativePath: "providers.json" },
+            { absolutePath: args.configPath, relativePath: "config.toml" },
+        ],
+        mutate: () => {
+            const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {});
+            (0, providers_repo_1.writeProvidersFile)(args.providersPath, finalProviders);
+            (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
+            return {
+                codexDir: args.codexDir,
+                strategy: args.strategy,
+                providersInitialized: Object.keys(nextProviders.providers).length,
+                providerNames: Object.keys(finalProviders.providers).sort(),
+                createdProfileSections: configPlan.createdProfileSections,
+                deletedProfileSections: configPlan.deletedProfileSections,
+                keptSharedProfiles: [],
+                switchedActiveProfile: false,
+                adoptedProfiles: [...args.adoptProfiles].sort(),
+                repairedProfiles: [],
+            };
+        },
+    });
+    const doctor = (0, run_doctor_1.runDoctor)({
+        codexDir: args.codexDir,
+        configPath: args.configPath,
+        providersPath: args.providersPath,
+    });
+    return {
+        data: {
+            ...result.data,
+            doctor: doctor.data,
+        },
+        warnings: doctor.warnings,
+    };
+}

package/dist/app/show-config.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showConfig = showConfig;
+const config_1 = require("../domain/config");
+const errors_1 = require("../domain/errors");
+const config_repo_1 = require("../infra/config-repo");
+const providers_repo_1 = require("../infra/providers-repo");
+/**
+ * Returns the structured config view, optionally filtered to one profile.
+ */
+function showConfig(args) {
+    const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
+    const providers = (0, providers_repo_1.readProvidersFileIfExists)(args.providersPath);
+    const views = (0, config_1.buildManagedProfileViews)(document, providers);
+    let selectedProfile = null;
+    let profiles = views;
+    if (args.profileName) {
+        const found = views.find((view) => view.name === args.profileName);
+        if (!found) {
+            throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", `Profile "${args.profileName}" was not found.`, {
+                profile: args.profileName,
+            });
+        }
+        selectedProfile = args.profileName;
+        profiles = [found];
+    }
+    return {
+        data: {
+            activeProfile: document.activeProfile,
+            selectedProfile,
+            profiles,
+        },
+    };
+}

package/dist/app/show-provider.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showProvider = showProvider;
+const providers_1 = require("../domain/providers");
+const providers_repo_1 = require("../infra/providers-repo");
+/**
+ * Returns a single provider record, with text-mode callers able to use a masked preview.
+ */
+function showProvider(args) {
+    const provider = (0, providers_repo_1.readProviderRecord)(args.providersPath, args.providerName);
+    return {
+        data: {
+            providerName: args.providerName,
+            provider: args.includeSecret
+                ? provider
+                : {
+                    ...provider,
+                    apiKey: (0, providers_1.maskSecret)(provider.apiKey),
+                },
+        },
+    };
+}

package/dist/app/switch-provider.js

@@ -17,7 +17,7 @@ function switchProvider(args) {
             availableProviders: Object.keys(providers.providers).sort(),
         });
     }
-    const configContent = (0, config_repo_1.ensureProfileExists)(args.configPath, provider.profile, args.providerName);
+    const document = (0, config_repo_1.ensureProfileExists)(args.configPath, provider.profile, args.providerName);
     return (0, run_mutation_1.runMutation)({
         codexDir: args.codexDir,
         backupsDir: args.backupsDir,
@@ -28,8 +28,11 @@ function switchProvider(args) {
             { absolutePath: args.authPath, relativePath: "auth.json" },
         ],
         mutate: () => {
+            const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
+                setActiveProfile: provider.profile,
+            });
             // Update the runtime profile first so any subsequent login is associated with the new target.
-            (0, config_repo_1.updateTopLevelProfile)(args.configPath, configContent, provider.profile);
+            (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
             if (!args.noLogin) {
                 (0, codex_cli_1.runCodexLogin)(provider.apiKey, args.codexDir);
             }

package/dist/cli/add-interactive.js

@@ -1,29 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMON_TAG_CHOICES = void 0;
 exports.collectAddInput = collectAddInput;
 exports.createNonInteractiveAddError = createNonInteractiveAddError;
-const config_repo_1 = require("../infra/config-repo");
+exports.promptTags = promptTags;
+exports.parseTags = parseTags;
 const errors_1 = require("../domain/errors");
+exports.COMMON_TAG_CHOICES = ["free", "paid", "daily", "backup"];
 /**
  * Collects add command inputs interactively when required values are missing.
  */
-async function collectAddInput(runtime, defaults, providerExists, configPath) {
+async function collectAddInput(runtime, defaults, providerExists) {
     runtime.writeLine("Interactive add mode");
     runtime.writeLine("Provide the missing required fields. Press Enter to skip optional fields.");
     const providerName = defaults.providerName
         ? normalizeRequiredValue(defaults.providerName)
         : await promptProviderName(runtime, providerExists);
-    const profile = defaults.profile
-        ? normalizeRequiredValue(defaults.profile)
-        : await promptProfile(runtime, configPath);
+    const profile = defaults.profile ? normalizeRequiredValue(defaults.profile) : await promptRequiredValue(runtime, "Profile");
     const apiKey = defaults.apiKey
         ? normalizeRequiredValue(defaults.apiKey)
         : await promptConfirmedSecret(runtime, "API key", "Confirm API key");
     const baseUrl = defaults.baseUrl ?? normalizeOptionalValue(await runtime.inputText("Base URL (optional)"));
     const note = defaults.note ?? normalizeOptionalValue(await runtime.inputText("Note (optional)"));
-    const tags = defaults.tags.length > 0
-        ? defaults.tags
-        : parseTags(await runtime.inputText("Tags (optional, comma-separated)"));
+    const tags = defaults.tags.length > 0 ? defaults.tags : await promptTags(runtime);
     return {
         providerName,
         profile,
@@ -37,7 +36,7 @@ async function collectAddInput(runtime, defaults, providerExists, configPath) {
  * Throws a consistent error when interactive add is unavailable.
  */
 function createNonInteractiveAddError() {
-    return (0, errors_1.cliError)("INVALID_IMPORT_FILE", "add requires <provider>, --profile, and --api-key when running without an interactive TTY.", {
+    return (0, errors_1.cliError)("INVALID_ARGUMENT", "add requires <provider>, --profile, and --api-key when running without an interactive TTY.", {
         suggestion: "Run in a terminal TTY or pass all required values explicitly.",
     });
 }
@@ -51,26 +50,6 @@ async function promptProviderName(runtime, providerExists) {
         return providerName;
     }
 }
-async function promptProfile(runtime, configPath) {
-    const profileChoices = loadProfileChoices(configPath);
-    if (profileChoices.length > 0) {
-        return runtime.selectOne("Profile", profileChoices);
-    }
-    return promptRequiredValue(runtime, "Profile");
-}
-function loadProfileChoices(configPath) {
-    try {
-        return Array.from((0, config_repo_1.listConfigProfiles)(configPath))
-            .sort()
-            .map((profileName) => ({
-            value: profileName,
-            label: profileName,
-        }));
-    }
-    catch {
-        return [];
-    }
-}
 async function promptRequiredValue(runtime, label) {
     while (true) {
         const value = normalizeRequiredValue(await runtime.inputText(label));
@@ -106,9 +85,24 @@ function normalizeOptionalValue(value) {
     const normalized = value.trim();
     return normalized === "" ? null : normalized;
 }
+async function promptTags(runtime, defaults = []) {
+    const defaultPresetTags = defaults.filter(isCommonTag);
+    const defaultCustomTags = defaults.filter((tag) => !isCommonTag(tag));
+    const presetTags = await runtime.selectMany("Select tags (optional)", exports.COMMON_TAG_CHOICES.map((tag) => ({ value: tag, label: tag })), { defaultValues: defaultPresetTags });
+    const customTags = parseTags(await runtime.inputText("Custom tags (optional, comma-separated)", {
+        defaultValue: defaultCustomTags.join(", "),
+    }));
+    return dedupeTags([...presetTags, ...customTags]);
+}
 function parseTags(value) {
-    return value
+    return dedupeTags(value
         .split(",")
         .map((tag) => tag.trim())
-        .filter((tag) => tag.length > 0);
+        .filter((tag) => tag.length > 0));
+}
+function isCommonTag(tag) {
+    return exports.COMMON_TAG_CHOICES.includes(tag);
+}
+function dedupeTags(tags) {
+    return Array.from(new Set(tags));
 }

package/dist/cli/args.js

@@ -11,6 +11,7 @@ const codex_paths_1 = require("../infra/codex-paths");
 function parseArgs(argv) {
     let json = false;
     let codexDir = (0, codex_paths_1.resolveCodexDir)();
+    let codexDirExplicit = false;
     const remaining = [];
     for (let index = 0; index < argv.length; index += 1) {
         const value = argv[index];
@@ -21,25 +22,28 @@ function parseArgs(argv) {
         if (value === "--codex-dir") {
             const next = argv[index + 1];
             if (!next) {
-                throw (0, errors_1.cliError)("INVALID_IMPORT_FILE", "--codex-dir requires a path value.");
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "--codex-dir requires a path value.");
             }
             codexDir = (0, codex_paths_1.resolveCodexDir)(next);
+            codexDirExplicit = true;
             index += 1;
             continue;
         }
         remaining.push(value);
     }
     if (remaining[0] === "help") {
+        const helpTarget = remaining[1] === "backups" && remaining[2] === "list" ? "backups" : remaining[1] ?? null;
         return {
             command: null,
             positionals: [],
             globalOptions: {
                 json,
                 codexDir,
+                codexDirExplicit,
             },
             commandOptions: new Map(),
             helpRequested: true,
-            helpTarget: remaining[1] ?? null,
+            helpTarget,
             versionRequested: false,
         };
     }
@@ -51,11 +55,19 @@ function parseArgs(argv) {
             versionRequested: true,
         });
     }
-    const command = remaining[0] ?? null;
+    const commandToken = remaining[0] ?? null;
+    const command = commandToken === "backups" && remaining[1] === "list"
+        ? "backups-list"
+        : commandToken === "config" && remaining[1] === "show"
+            ? "config-show"
+            : commandToken === "config" && remaining[1] === "list-profiles"
+                ? "config-list-profiles"
+                : commandToken;
     const positionals = [];
     const commandOptions = new Map();
     let helpRequested = false;
-    for (let index = 1; index < remaining.length; index += 1) {
+    const startIndex = command === "backups-list" || command === "config-show" || command === "config-list-profiles" ? 2 : 1;
+    for (let index = startIndex; index < remaining.length; index += 1) {
         const value = remaining[index];
         if (value === "--help" || value === "-h") {
             helpRequested = true;
@@ -83,10 +95,11 @@ function parseArgs(argv) {
         globalOptions: {
             json,
             codexDir,
+            codexDirExplicit,
         },
         commandOptions,
         helpRequested,
-        helpTarget: helpRequested ? command : null,
+        helpTarget: helpRequested ? (command === "backups-list" ? "backups" : command) : null,
         versionRequested: false,
     };
 }
@@ -100,6 +113,7 @@ function defaultParsed(command, overrides) {
         globalOptions: {
             json: overrides?.json ?? false,
             codexDir: overrides?.codexDir ?? (0, codex_paths_1.resolveCodexDir)(),
+            codexDirExplicit: false,
         },
         commandOptions: new Map(),
         helpRequested: overrides?.helpRequested ?? false,