@minniexcode/codex-switch 0.0.5 → 0.0.7

package/dist/commands/handlers.js

@@ -0,0 +1,460 @@
+"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.handleRegisteredCommand = handleRegisteredCommand;
+const fs = __importStar(require("node:fs"));
+const add_provider_1 = require("../app/add-provider");
+const edit_provider_1 = require("../app/edit-provider");
+const export_providers_1 = require("../app/export-providers");
+const get_current_profile_1 = require("../app/get-current-profile");
+const get_status_1 = require("../app/get-status");
+const init_codex_1 = require("../app/init-codex");
+const import_providers_1 = require("../app/import-providers");
+const list_config_profiles_1 = require("../app/list-config-profiles");
+const list_backups_1 = require("../app/list-backups");
+const list_providers_1 = require("../app/list-providers");
+const remove_provider_1 = require("../app/remove-provider");
+const rollback_backup_1 = require("../app/rollback-backup");
+const run_doctor_1 = require("../app/run-doctor");
+const setup_codex_1 = require("../app/setup-codex");
+const show_config_1 = require("../app/show-config");
+const show_provider_1 = require("../app/show-provider");
+const switch_provider_1 = require("../app/switch-provider");
+const config_1 = require("../domain/config");
+const errors_1 = require("../domain/errors");
+const providers_1 = require("../domain/providers");
+const add_interactive_1 = require("../interaction/add-interactive");
+const interactive_1 = require("../interaction/interactive");
+const prompt_1 = require("../interaction/prompt");
+const config_repo_1 = require("../storage/config-repo");
+const codex_paths_1 = require("../storage/codex-paths");
+const providers_repo_1 = require("../storage/providers-repo");
+const args_1 = require("./args");
+/**
+ * Executes one command handler selected from the shared command registry.
+ */
+async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.createPromptRuntime)()) {
+    let setupPaths = (0, codex_paths_1.createCodexPaths)(ctx.options.codexDir);
+    const paths = setupPaths;
+    switch (ctx.command) {
+        case "list":
+            return (0, list_providers_1.listProviders)(paths.providersPath);
+        case "show": {
+            let providerName = parsed.positionals[0] ?? null;
+            if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to show");
+            }
+            if (!providerName) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing provider name for show command.");
+            }
+            return (0, show_provider_1.showProvider)({
+                providersPath: paths.providersPath,
+                providerName,
+                includeSecret: ctx.options.json,
+            });
+        }
+        case "current":
+            return (0, get_current_profile_1.getCurrentProfile)(paths.configPath);
+        case "status":
+            return (0, get_status_1.getStatus)(paths.codexDir, paths.configPath, paths.providersPath, paths.authPath);
+        case "init": {
+            let codexDir = ctx.options.codexDir;
+            const candidates = (0, config_repo_1.findCodexDirCandidates)(ctx.options.codexDirExplicit ? ctx.options.codexDir : null);
+            if (!ctx.options.codexDirExplicit) {
+                if (candidates.length > 1) {
+                    if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                        throw (0, errors_1.cliError)("CODEX_DIR_AMBIGUOUS", "Multiple Codex directories were found.", {
+                            candidates,
+                        });
+                    }
+                    codexDir = await (0, interactive_1.chooseCodexDir)(runtime, candidates);
+                }
+                else if (candidates.length === 0) {
+                    if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                        throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "No Codex directory could be found.", {
+                            codexDir: ctx.options.codexDir,
+                        });
+                    }
+                    codexDir = await (0, interactive_1.chooseCodexDir)(runtime, candidates);
+                }
+                else {
+                    codexDir = candidates[0];
+                }
+            }
+            setupPaths = (0, codex_paths_1.createCodexPaths)(codexDir);
+            let createCodexDir = false;
+            if (!fs.existsSync(setupPaths.codexDir)) {
+                if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                    throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "The requested Codex directory does not exist.", {
+                        codexDir: setupPaths.codexDir,
+                    });
+                }
+                createCodexDir = await (0, interactive_1.confirmCreateCodexDir)(runtime, setupPaths.codexDir);
+                if (!createCodexDir) {
+                    throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "The requested Codex directory does not exist.", {
+                        codexDir: setupPaths.codexDir,
+                    });
+                }
+            }
+            return (0, init_codex_1.initCodex)({
+                codexDir: setupPaths.codexDir,
+                providersPath: setupPaths.providersPath,
+                configPath: setupPaths.configPath,
+                authPath: setupPaths.authPath,
+                createCodexDir,
+            });
+        }
+        case "config-show":
+            return (0, show_config_1.showConfig)({
+                configPath: paths.configPath,
+                providersPath: paths.providersPath,
+                profileName: parsed.positionals[0] ?? null,
+            });
+        case "config-list-profiles":
+            return (0, list_config_profiles_1.listConfigProfilesView)({
+                configPath: paths.configPath,
+                providersPath: paths.providersPath,
+            });
+        case "switch": {
+            let providerName = parsed.positionals[0] ?? null;
+            if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to switch to");
+            }
+            if (!providerName) {
+                throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for switch command.");
+            }
+            return (0, switch_provider_1.switchProvider)({
+                codexDir: paths.codexDir,
+                backupsDir: paths.backupsDir,
+                latestBackupPath: paths.latestBackupPath,
+                configPath: paths.configPath,
+                providersPath: paths.providersPath,
+                authPath: paths.authPath,
+                providerName,
+            });
+        }
+        case "import": {
+            const sourceFile = parsed.positionals[0];
+            if (!sourceFile) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing import file path.");
+            }
+            const merge = (0, args_1.hasFlag)(parsed.commandOptions, "--merge");
+            if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                await (0, interactive_1.confirmImport)(runtime, sourceFile, merge);
+                const document = (0, config_repo_1.readStructuredConfig)(paths.configPath);
+                const imported = (0, providers_1.validateProvidersShape)(JSON.parse(fs.readFileSync(sourceFile, "utf8")));
+                const current = (0, providers_repo_1.readProvidersFileIfExists)(paths.providersPath);
+                const next = merge ? (0, providers_repo_1.mergeProviders)(current, imported) : imported;
+                // Precompute orphaned references during confirmation so the interactive path fails before mutation.
+                (0, config_1.buildManagedProfileViews)(document, next)
+                    .filter((view) => view.source === "orphaned-reference")
+                    .map((view) => view.name)
+                    .sort();
+            }
+            return (0, import_providers_1.importProviders)({
+                codexDir: paths.codexDir,
+                backupsDir: paths.backupsDir,
+                latestBackupPath: paths.latestBackupPath,
+                providersPath: paths.providersPath,
+                configPath: paths.configPath,
+                sourceFile,
+                merge,
+            });
+        }
+        case "export": {
+            const targetFile = parsed.positionals[0];
+            if (!targetFile) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing export file path.");
+            }
+            let force = (0, args_1.hasFlag)(parsed.commandOptions, "--force");
+            if (!force && (0, interactive_1.canPrompt)(runtime, ctx.options.json) && (0, interactive_1.exportTargetExists)(targetFile)) {
+                const confirmed = await (0, interactive_1.confirmExportOverwrite)(runtime, targetFile);
+                if (!confirmed) {
+                    throw (0, errors_1.cliError)("PROMPT_CANCELLED", "Export cancelled.");
+                }
+                force = true;
+            }
+            return (0, export_providers_1.exportProviders)({
+                providersPath: paths.providersPath,
+                targetFile,
+                force,
+            });
+        }
+        case "add": {
+            let providerName = parsed.positionals[0] ?? null;
+            let profile = (0, args_1.getSingleOption)(parsed.commandOptions, "--profile");
+            let apiKey = (0, args_1.getSingleOption)(parsed.commandOptions, "--api-key");
+            let baseUrl = (0, args_1.getSingleOption)(parsed.commandOptions, "--base-url", false);
+            let model = (0, args_1.getSingleOption)(parsed.commandOptions, "--model", false);
+            let note = (0, args_1.getSingleOption)(parsed.commandOptions, "--note", false);
+            let tags = parsed.commandOptions.get("--tag") ?? [];
+            let createProfile = (0, args_1.hasFlag)(parsed.commandOptions, "--create-profile");
+            if (!providerName || !profile || !apiKey) {
+                if (ctx.options.json || !runtime.isInteractive()) {
+                    throw (0, add_interactive_1.createNonInteractiveAddError)();
+                }
+                const prompted = await (0, add_interactive_1.collectAddInput)(runtime, {
+                    providerName,
+                    profile,
+                    apiKey,
+                    baseUrl,
+                    note,
+                    tags,
+                }, (candidate) => Boolean((0, providers_repo_1.readProvidersFileIfExists)(paths.providersPath).providers[candidate]), (candidate) => Boolean((0, config_repo_1.readStructuredConfig)(paths.configPath).profiles.find((profileView) => profileView.name === candidate)));
+                providerName = prompted.providerName;
+                profile = prompted.profile;
+                apiKey = prompted.apiKey;
+                model = prompted.model ?? null;
+                baseUrl = prompted.baseUrl ?? null;
+                note = prompted.note ?? null;
+                tags = prompted.tags;
+                createProfile = createProfile || prompted.createProfile;
+            }
+            return (0, add_provider_1.addProvider)({
+                codexDir: paths.codexDir,
+                backupsDir: paths.backupsDir,
+                latestBackupPath: paths.latestBackupPath,
+                providersPath: paths.providersPath,
+                configPath: paths.configPath,
+                authPath: paths.authPath,
+                providerName,
+                profile,
+                apiKey,
+                baseUrl,
+                model,
+                note,
+                tags,
+                createProfile,
+            });
+        }
+        case "edit": {
+            let providerName = parsed.positionals[0] ?? null;
+            if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to edit");
+            }
+            if (!providerName) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing provider name for edit command.");
+            }
+            let profile = (0, args_1.getSingleOption)(parsed.commandOptions, "--profile", false) ?? undefined;
+            let apiKey = (0, args_1.getSingleOption)(parsed.commandOptions, "--api-key", false) ?? undefined;
+            let baseUrl = (0, args_1.getSingleOption)(parsed.commandOptions, "--base-url", false) ?? undefined;
+            let model = (0, args_1.getSingleOption)(parsed.commandOptions, "--model", false) ?? undefined;
+            let note = (0, args_1.getSingleOption)(parsed.commandOptions, "--note", false) ?? undefined;
+            let tags = parsed.commandOptions.has("--tag") ? parsed.commandOptions.get("--tag") ?? [] : undefined;
+            const createProfile = (0, args_1.hasFlag)(parsed.commandOptions, "--create-profile");
+            const switchToProfile = (0, args_1.getSingleOption)(parsed.commandOptions, "--switch-to", false) ?? undefined;
+            if (profile === undefined &&
+                apiKey === undefined &&
+                baseUrl === undefined &&
+                model === undefined &&
+                note === undefined &&
+                tags === undefined &&
+                (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                const provider = (0, providers_repo_1.readProvidersFileIfExists)(paths.providersPath).providers[providerName];
+                if (!provider) {
+                    throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", `Provider "${providerName}" was not found.`);
+                }
+                // Prompted edit starts from the stored record so blank answers can safely preserve current values.
+                const prompted = await (0, interactive_1.collectEditInput)(runtime, provider);
+                profile = prompted.profile;
+                apiKey = prompted.apiKey;
+                baseUrl = prompted.baseUrl;
+                note = prompted.note;
+                tags = prompted.tags;
+            }
+            if (profile === undefined && apiKey === undefined && baseUrl === undefined && model === undefined && note === undefined && tags === undefined) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "edit requires at least one field to update.");
+            }
+            return (0, edit_provider_1.editProvider)({
+                codexDir: paths.codexDir,
+                backupsDir: paths.backupsDir,
+                latestBackupPath: paths.latestBackupPath,
+                providersPath: paths.providersPath,
+                configPath: paths.configPath,
+                authPath: paths.authPath,
+                providerName,
+                profile,
+                apiKey,
+                baseUrl,
+                model,
+                note,
+                tags,
+                createProfile,
+                switchToProfile,
+            });
+        }
+        case "remove": {
+            let providerName = parsed.positionals[0] ?? null;
+            const force = (0, args_1.hasFlag)(parsed.commandOptions, "--force");
+            const switchToProfile = (0, args_1.getSingleOption)(parsed.commandOptions, "--switch-to", false) ?? undefined;
+            if (!providerName && (0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, "Choose a provider to remove");
+            }
+            if (!providerName) {
+                throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for remove command.");
+            }
+            if (!force && !(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "remove requires --force.");
+            }
+            if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                await (0, interactive_1.confirmProviderRemoval)(runtime, providerName);
+            }
+            return (0, remove_provider_1.removeProvider)({
+                codexDir: paths.codexDir,
+                backupsDir: paths.backupsDir,
+                latestBackupPath: paths.latestBackupPath,
+                providersPath: paths.providersPath,
+                configPath: paths.configPath,
+                providerName,
+                switchToProfile,
+            });
+        }
+        case "doctor":
+            return (0, run_doctor_1.runDoctor)({
+                codexDir: paths.codexDir,
+                configPath: paths.configPath,
+                providersPath: paths.providersPath,
+                authPath: paths.authPath,
+            });
+        case "migrate": {
+            let codexDir = ctx.options.codexDir;
+            const candidates = (0, config_repo_1.findCodexDirCandidates)(ctx.options.codexDirExplicit ? ctx.options.codexDir : null);
+            if (!ctx.options.codexDirExplicit) {
+                if (candidates.length > 1) {
+                    if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                        throw (0, errors_1.cliError)("CODEX_DIR_AMBIGUOUS", "Multiple Codex directories were found.", {
+                            candidates,
+                        });
+                    }
+                    // Ambiguous auto-discovery must be resolved before path-dependent flags are interpreted.
+                    codexDir = await (0, interactive_1.chooseCodexDir)(runtime, candidates);
+                }
+                else if (candidates.length === 0) {
+                    if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                        throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "No Codex directory could be found.");
+                    }
+                    codexDir = await (0, interactive_1.chooseCodexDir)(runtime, candidates);
+                }
+                else {
+                    codexDir = candidates[0];
+                }
+            }
+            setupPaths = (0, codex_paths_1.createCodexPaths)(codexDir);
+            const overwrite = (0, args_1.hasFlag)(parsed.commandOptions, "--overwrite");
+            const merge = (0, args_1.hasFlag)(parsed.commandOptions, "--merge");
+            if (overwrite && merge) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "migrate does not allow both --merge and --overwrite.");
+            }
+            let strategy = overwrite ? "overwrite" : merge ? "merge" : null;
+            const providersExists = fs.existsSync(setupPaths.providersPath);
+            if (providersExists && strategy === null) {
+                if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                    throw (0, errors_1.cliError)("PROVIDERS_ALREADY_EXISTS", "providers.json already exists. Pass --merge or --overwrite.", {
+                        file: setupPaths.providersPath,
+                    });
+                }
+                const selected = await (0, interactive_1.chooseSetupStrategy)(runtime);
+                if (selected === "cancel") {
+                    throw (0, errors_1.cliError)("PROMPT_CANCELLED", "Setup cancelled.");
+                }
+                strategy = selected;
+            }
+            const document = (0, config_repo_1.readStructuredConfig)(setupPaths.configPath);
+            const adoptableProfiles = (0, config_1.buildManagedProfileViews)(document, null)
+                .filter((view) => view.source === "unmanaged" && view.model && view.modelProvider === view.name && view.baseUrl && view.envKey)
+                .map((view) => ({
+                name: view.name,
+                model: view.model,
+                baseUrl: view.baseUrl,
+                envKey: view.envKey,
+            }))
+                .sort((left, right) => left.name.localeCompare(right.name));
+            const selectedProfiles = Array.from((0, config_repo_1.listConfigProfiles)(setupPaths.configPath)).sort();
+            let adoptProfiles = [];
+            let providerDetailsByProfile = {};
+            if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                adoptProfiles = await (0, interactive_1.chooseSetupProfiles)(runtime, adoptableProfiles);
+                // Defaults are derived from config.toml so interactive setup only asks for missing provider metadata.
+                providerDetailsByProfile = await (0, interactive_1.collectSetupProviderDetails)(runtime, adoptProfiles, adoptableProfiles.reduce((accumulator, profile) => {
+                    accumulator[profile.name] = {
+                        providerName: profile.name,
+                        envKey: profile.envKey,
+                        baseUrl: profile.baseUrl,
+                    };
+                    return accumulator;
+                }, {}));
+            }
+            else {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "migrate currently requires an interactive TTY to choose adoptable profiles and collect provider details.", {
+                    adoptableProfiles,
+                    availableProfiles: selectedProfiles,
+                    suggestion: "Run `codexs migrate` in an interactive terminal. Non-interactive migrate flags for profile selection and provider secrets are not available in this release.",
+                });
+            }
+            return (0, setup_codex_1.migrateCodex)({
+                codexDirOption: ctx.options.codexDir,
+                codexDir: setupPaths.codexDir,
+                configPath: setupPaths.configPath,
+                providersPath: setupPaths.providersPath,
+                authPath: setupPaths.authPath,
+                backupsDir: setupPaths.backupsDir,
+                latestBackupPath: setupPaths.latestBackupPath,
+                strategy: strategy ?? "overwrite",
+                adoptProfiles,
+                providerDetailsByProfile,
+            });
+        }
+        case "setup":
+            throw (0, errors_1.cliError)("COMMAND_DEPRECATED", "setup has been split into init and migrate.", {
+                replacements: ["init", "migrate"],
+            });
+        case "backups-list":
+            return (0, list_backups_1.listBackupEntries)(paths.backupsDir);
+        case "rollback":
+            if (parsed.positionals.length > 1) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "rollback accepts at most one backup id.");
+            }
+            if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                await (0, interactive_1.confirmRollback)(runtime, paths.latestBackupPath, paths.backupsDir, parsed.positionals[0] ?? null);
+            }
+            return (0, rollback_backup_1.rollbackBackup)({
+                latestBackupPath: paths.latestBackupPath,
+                backupsDir: paths.backupsDir,
+                backupId: parsed.positionals[0] ?? null,
+            });
+        default:
+            throw (0, errors_1.cliError)("UNKNOWN_COMMAND", `Unknown command: ${ctx.command}`);
+    }
+}

package/dist/commands/help.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKnownCommandNames = getKnownCommandNames;
+exports.isKnownCommandNameForHelp = isKnownCommandNameForHelp;
+exports.buildHelpText = buildHelpText;
+const registry_1 = require("./registry");
+const GROUP_TITLES = {
+    read: "Read Commands",
+    write: "Change Commands",
+    recovery: "Diagnostics And Recovery",
+};
+/**
+ * Returns the known command names.
+ */
+function getKnownCommandNames() {
+    return (0, registry_1.getPublicCommandNames)();
+}
+/**
+ * Checks whether the requested topic is a known command.
+ */
+function isKnownCommandNameForHelp(commandName) {
+    return (0, registry_1.isKnownHelpTopic)(commandName);
+}
+/**
+ * Builds the command help text for the top-level help page or a specific topic.
+ */
+function buildHelpText(commandName) {
+    if (!commandName) {
+        return [
+            "codex-switch",
+            "",
+            "Manage and switch local Codex provider/profile configuration safely.",
+            "",
+            "Usage:",
+            "  codexs <command> [options]",
+            "  codexs help <command>",
+            "",
+            ...renderGroupedCommands(),
+            "",
+            "Global options:",
+            "  --json             Output the standard JSON envelope and disable all prompts.",
+            "  --codex-dir <path> Target a specific Codex directory instead of ~/.codex.",
+            "  --help             Show top-level or command-specific help.",
+            "  --version          Print the current CLI version.",
+            "",
+            "Environment:",
+            "  CODEXS_CODEX_DIR   Default Codex directory when --codex-dir is not passed.",
+            "  NODE_ENV=development defaults to ./dev-codex/local-sandbox when no override is set.",
+            "",
+            "Interactive rules:",
+            "  Progressive prompts only run in a real TTY and never run under --json.",
+            "  Human write commands may guide missing inputs or ask for dangerous-action confirmation.",
+            "  Automation should pass explicit arguments and prefer --json for stable parsing.",
+            "",
+            "Dangerous commands:",
+            "  remove deletes provider records.",
+            "  import replaces or merges providers.json.",
+            "  export may overwrite a target file.",
+            "  rollback restores files from a managed backup.",
+            "",
+            "Examples:",
+            "  codexs init",
+            "  codexs migrate",
+            "  codexs list",
+            "  codexs switch",
+            "  codexs add packycode --profile packycode --api-key sk-xxx",
+            "  codexs config show",
+            "  codexs remove freemodel",
+            "  codexs backups list",
+            "  codexs rollback",
+            "  codexs help add",
+        ].join("\n");
+    }
+    const nestedCommands = (0, registry_1.getNestedCommandTokens)(commandName);
+    if (nestedCommands.length > 0) {
+        return [
+            `codexs ${commandName}`,
+            "",
+            `Available ${commandName} commands:`,
+            ...nestedCommands.map((name) => `  ${name}`),
+            "",
+            "Use `codexs help <command>` for detailed usage.",
+        ].join("\n");
+    }
+    const command = (0, registry_1.findCommandDefinitionByTokens)(commandName.split(" "));
+    if (!command) {
+        return [
+            `Unknown help topic: ${commandName}`,
+            "",
+            "Available commands:",
+            ...getKnownCommandNames().map((name) => `  ${name}`),
+        ].join("\n");
+    }
+    return [
+        `codexs ${command.tokens.join(" ")}`,
+        "",
+        command.summary,
+        "",
+        "Usage:",
+        ...command.usage.map((usage) => `  ${usage}`),
+        "",
+        "Details:",
+        ...command.details.map((detail) => `  ${detail}`),
+        "",
+        "Examples:",
+        ...command.examples.map((example) => `  ${example}`),
+    ].join("\n");
+}
+function renderGroupedCommands() {
+    const lines = [];
+    for (const group of ["read", "write", "recovery"]) {
+        lines.push(`${GROUP_TITLES[group]}:`);
+        for (const command of registry_1.COMMANDS.filter((candidate) => candidate.group === group)) {
+            lines.push(`  ${command.tokens.join(" ").padEnd(12, " ")} ${command.summary}`);
+        }
+        lines.push("");
+    }
+    lines.pop();
+    return lines;
+}