@minniexcode/codex-switch 0.0.9 → 0.0.11

package/dist/commands/handlers.js

@@ -55,10 +55,13 @@ 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 setup_1 = require("../domain/setup");
 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 copilot_adapter_1 = require("../runtime/copilot-adapter");
+const copilot_cli_1 = require("../runtime/copilot-cli");
 const copilot_installer_1 = require("../runtime/copilot-installer");
 const config_repo_1 = require("../storage/config-repo");
 const codex_paths_1 = require("../storage/codex-paths");
@@ -68,6 +71,10 @@ 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)()) {
+    const packageVersion = require("../../package.json").version ?? "0.0.0";
+    if (!ctx.options.codexDir) {
+        throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "No Codex directory could be resolved.");
+    }
     let setupPaths = (0, codex_paths_1.createCodexPaths)(ctx.options.codexDir);
     const paths = setupPaths;
     switch (ctx.command) {
@@ -90,12 +97,17 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
         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);
+            return (0, get_status_1.getStatus)(paths.codexDir, paths.configPath, paths.providersPath, paths.authPath, {
+                runtimeDir: paths.runtimeDir,
+                runtimesDir: paths.runtimesDir,
+            });
         case "bridge-start": {
             const providerName = parsed.positionals[0] ?? null;
             return (0, bridge_1.startBridge)({
                 providersPath: paths.providersPath,
                 configPath: paths.configPath,
+                runtimeDir: paths.runtimeDir,
+                runtimesDir: paths.runtimesDir,
                 providerName,
                 runtime,
                 json: ctx.options.json,
@@ -106,6 +118,8 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             return (0, bridge_1.stopBridge)({
                 providersPath: paths.providersPath,
                 configPath: paths.configPath,
+                runtimeDir: paths.runtimeDir,
+                runtimesDir: paths.runtimesDir,
                 providerName,
                 runtime,
                 json: ctx.options.json,
@@ -116,57 +130,103 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             return (0, bridge_1.statusBridge)({
                 providersPath: paths.providersPath,
                 configPath: paths.configPath,
+                runtimeDir: paths.runtimeDir,
+                runtimesDir: paths.runtimesDir,
                 providerName,
                 runtime,
                 json: ctx.options.json,
             });
         }
         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];
-                }
+            return (0, init_codex_1.initCodex)({
+                toolHomeDir: setupPaths.toolHomeDir,
+                toolConfigPath: setupPaths.toolConfigPath,
+                providersPath: setupPaths.providersPath,
+                version: packageVersion,
+                defaultCodexDir: ctx.options.codexDirExplicit ? setupPaths.codexDir : null,
+            });
+        }
+        case "login": {
+            const upstream = (parsed.positionals[0] ?? "").toLowerCase();
+            if (ctx.options.json || !runtime.isInteractive()) {
+                throw (0, errors_1.cliError)("COPILOT_LOGIN_REQUIRES_TTY", "login requires an interactive TTY and does not support --json.");
             }
-            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,
+            if (upstream !== "copilot" && upstream !== "github-copilot") {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", `Unsupported upstream "${parsed.positionals[0] ?? ""}".`, {
+                    supportedUpstreams: ["copilot", "github-copilot"],
+                });
+            }
+            const installed = (0, copilot_installer_1.probeCopilotSdkInstall)(paths.runtimesDir);
+            let installedNow = false;
+            if (!installed.installed) {
+                const confirmInstall = await runtime.confirmAction("The Copilot SDK runtime is not installed. Install it now?", {
+                    defaultValue: true,
+                });
+                if (!confirmInstall) {
+                    throw (0, errors_1.cliError)("COPILOT_SDK_MISSING", "The optional Copilot SDK runtime is not installed.", {
+                        installDir: installed.installDir,
+                        packageName: installed.packageName,
                     });
                 }
-                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,
+                runtime.writeLine("Installing Copilot SDK runtime...");
+                (0, copilot_installer_1.installCopilotSdk)(paths.runtimesDir);
+                installedNow = true;
+            }
+            try {
+                await (0, copilot_adapter_1.readCopilotAuthState)(paths.runtimesDir);
+                return {
+                    data: {
+                        upstream: "github-copilot",
+                        sdkInstalled: true,
+                        sdkInstalledNow: installedNow,
+                        authReady: true,
+                        loginLaunched: false,
+                    },
+                };
+            }
+            catch (error) {
+                const normalized = (0, errors_1.normalizeError)(error);
+                if (normalized.code !== "COPILOT_AUTH_REQUIRED") {
+                    throw error;
+                }
+            }
+            const availability = (0, copilot_cli_1.checkCopilotCliAvailable)(paths.runtimesDir);
+            if (!availability.ok) {
+                throw (0, errors_1.cliError)("COPILOT_CLI_MISSING", "The official Copilot CLI could not be resolved from the installed runtime or PATH.", {
+                    cause: availability.cause,
+                    source: availability.source ?? null,
+                    command: availability.command ?? null,
+                });
+            }
+            try {
+                (0, copilot_cli_1.runCopilotLogin)({ runtimesDir: paths.runtimesDir });
+            }
+            catch (error) {
+                throw (0, errors_1.cliError)("COPILOT_LOGIN_LAUNCH_FAILED", "Failed to launch `copilot login`.", {
+                    cause: error instanceof Error ? error.message : String(error),
+                });
+            }
+            try {
+                await (0, copilot_adapter_1.readCopilotAuthState)(paths.runtimesDir);
+            }
+            catch (error) {
+                const normalized = (0, errors_1.normalizeError)(error);
+                if (normalized.code === "COPILOT_AUTH_REQUIRED") {
+                    throw (0, errors_1.cliError)("COPILOT_LOGIN_RECHECK_FAILED", "Copilot login completed but auth readiness recheck still failed.", {
+                        ...(normalized.details ?? {}),
                     });
                 }
+                throw error;
             }
-            return (0, init_codex_1.initCodex)({
-                codexDir: setupPaths.codexDir,
-                providersPath: setupPaths.providersPath,
-                configPath: setupPaths.configPath,
-                authPath: setupPaths.authPath,
-                createCodexDir,
-            });
+            return {
+                data: {
+                    upstream: "github-copilot",
+                    sdkInstalled: true,
+                    sdkInstalledNow: installedNow,
+                    authReady: true,
+                    loginLaunched: true,
+                },
+            };
         }
         case "config-show":
             return (0, show_config_1.showConfig)({
@@ -188,15 +248,20 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for switch command.");
             }
             if ((0, args_1.hasFlag)(parsed.commandOptions, "--install-copilot-sdk")) {
-                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "--install-copilot-sdk is only supported with add --copilot.");
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "--install-copilot-sdk is no longer supported with switch. Run `codexs login copilot` instead.", {
+                    suggestion: "Run `codexs login copilot` first, then rerun switch without --install-copilot-sdk.",
+                });
             }
             return (0, switch_provider_1.switchProvider)({
                 codexDir: paths.codexDir,
+                lockPath: paths.lockPath,
                 backupsDir: paths.backupsDir,
                 latestBackupPath: paths.latestBackupPath,
                 configPath: paths.configPath,
                 providersPath: paths.providersPath,
                 authPath: paths.authPath,
+                runtimeDir: paths.runtimeDir,
+                runtimesDir: paths.runtimesDir,
                 providerName,
             });
         }
@@ -220,6 +285,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             }
             return (0, import_providers_1.importProviders)({
                 codexDir: paths.codexDir,
+                lockPath: paths.lockPath,
                 backupsDir: paths.backupsDir,
                 latestBackupPath: paths.latestBackupPath,
                 providersPath: paths.providersPath,
@@ -257,43 +323,74 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             let tags = parsed.commandOptions.get("--tag") ?? [];
             let createProfile = (0, args_1.hasFlag)(parsed.commandOptions, "--create-profile");
             const copilot = (0, args_1.hasFlag)(parsed.commandOptions, "--copilot");
-            const bridgeHost = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-host", false);
+            let bridgeHost = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-host", false);
             const bridgePortValue = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-port", false);
-            const bridgeApiKey = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-api-key", false);
-            let installCopilotSdk = (0, args_1.hasFlag)(parsed.commandOptions, "--install-copilot-sdk");
-            const bridgePort = bridgePortValue ? Number(bridgePortValue) : null;
+            let bridgeApiKey = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-api-key", false);
+            const installCopilotSdk = (0, args_1.hasFlag)(parsed.commandOptions, "--install-copilot-sdk");
+            let bridgePort = bridgePortValue ? Number(bridgePortValue) : null;
             if (copilot && apiKey) {
                 throw (0, errors_1.cliError)("INVALID_ARGUMENT", "--copilot does not allow --api-key. Use --bridge-api-key for the local bridge secret.");
             }
+            if (copilot && installCopilotSdk) {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "--install-copilot-sdk is no longer supported with add --copilot. Run `codexs login copilot` instead.", {
+                    suggestion: "Run `codexs login copilot` first, then rerun add --copilot.",
+                });
+            }
             if (bridgePortValue && (!Number.isInteger(bridgePort) || bridgePort === null || bridgePort <= 0)) {
                 throw (0, errors_1.cliError)("INVALID_ARGUMENT", "--bridge-port must be a positive integer.");
             }
-            if (copilot && !installCopilotSdk && (0, interactive_1.canPrompt)(runtime, ctx.options.json) && !(0, copilot_installer_1.probeCopilotSdkInstall)().installed) {
-                installCopilotSdk = await runtime.confirmAction("The optional Copilot SDK runtime is not installed. Install it now?");
-            }
             if (!providerName || !profile || (!apiKey && !copilot)) {
                 if (ctx.options.json || !runtime.isInteractive()) {
-                    throw (0, add_interactive_1.createNonInteractiveAddError)();
+                    throw (0, add_interactive_1.createNonInteractiveAddError)({ copilot });
+                }
+                if (copilot) {
+                    const prompted = await (0, add_interactive_1.collectCopilotAddInput)(runtime, {
+                        providerName,
+                        profile,
+                        model,
+                        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)), {
+                        bridgeHost,
+                        bridgePort,
+                        bridgeApiKey,
+                    });
+                    providerName = prompted.providerName;
+                    profile = prompted.profile;
+                    model = prompted.model ?? null;
+                    note = prompted.note ?? null;
+                    tags = prompted.tags;
+                    createProfile = createProfile || prompted.createProfile;
+                    baseUrl = null;
+                    bridgeHost = prompted.bridgeHost ?? bridgeHost;
+                    bridgePort = prompted.bridgePort ?? bridgePort;
+                    bridgeApiKey = prompted.bridgeApiKey ?? bridgeApiKey;
+                }
+                else {
+                    const prompted = await (0, add_interactive_1.collectAddInput)(runtime, {
+                        providerName,
+                        profile,
+                        apiKey,
+                        model,
+                        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;
                 }
-                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,
+                toolHomeDir: paths.toolHomeDir,
+                lockPath: paths.lockPath,
+                runtimesDir: paths.runtimesDir,
                 backupsDir: paths.backupsDir,
                 latestBackupPath: paths.latestBackupPath,
                 providersPath: paths.providersPath,
@@ -311,8 +408,6 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 bridgeHost,
                 bridgePort,
                 bridgeApiKey,
-                installCopilotSdk,
-                interactive: (0, interactive_1.canPrompt)(runtime, ctx.options.json),
             });
         }
         case "edit": {
@@ -355,6 +450,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             }
             return (0, edit_provider_1.editProvider)({
                 codexDir: paths.codexDir,
+                lockPath: paths.lockPath,
                 backupsDir: paths.backupsDir,
                 latestBackupPath: paths.latestBackupPath,
                 providersPath: paths.providersPath,
@@ -389,6 +485,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             }
             return (0, remove_provider_1.removeProvider)({
                 codexDir: paths.codexDir,
+                lockPath: paths.lockPath,
                 backupsDir: paths.backupsDir,
                 latestBackupPath: paths.latestBackupPath,
                 providersPath: paths.providersPath,
@@ -403,6 +500,8 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 configPath: paths.configPath,
                 providersPath: paths.providersPath,
                 authPath: paths.authPath,
+                runtimeDir: paths.runtimeDir,
+                runtimesDir: paths.runtimesDir,
             });
         case "migrate": {
             let codexDir = ctx.options.codexDir;
@@ -433,9 +532,25 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             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) {
+            const document = (0, config_repo_1.readStructuredConfig)(setupPaths.configPath);
+            const currentProviders = providersExists ? (0, providers_1.validateProvidersShape)((0, providers_repo_1.readProvidersFileIfExists)(setupPaths.providersPath)) : null;
+            const adoptability = (0, setup_1.collectMigrateAdoptability)(document, currentProviders);
+            if (adoptability.availableProfiles.length === 0) {
+                throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", "No profiles were found in config.toml.", {
+                    file: setupPaths.configPath,
+                });
+            }
+            if (adoptability.adoptableProfiles.length === 0) {
+                throw (0, errors_1.cliError)("MIGRATE_NO_ADOPTABLE_PROFILES", "No adoptable profiles were found for migrate.", {
+                    availableProfiles: adoptability.availableProfiles,
+                    adoptableProfiles: adoptability.adoptableProfiles,
+                    blockingReasonsByProfile: adoptability.blockingReasonsByProfile,
+                });
+            }
+            let strategy = overwrite ? "overwrite" : merge ? "merge" : null;
+            const registryIsEmpty = !currentProviders || Object.keys(currentProviders.providers).length === 0;
+            if (providersExists && strategy === null && !registryIsEmpty) {
                 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,
@@ -447,44 +562,47 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 }
                 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();
+            const adoptableProfiles = adoptability.adoptableProfileDetails;
             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) => {
+                const collectedDetails = 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;
                 }, {}));
+                providerDetailsByProfile = Object.fromEntries(Object.entries(collectedDetails).map(([profile, detail]) => [
+                    profile,
+                    {
+                        providerName: detail.providerName,
+                        apiKey: detail.apiKey,
+                        baseUrl: detail.baseUrl,
+                        note: detail.note,
+                        tags: detail.tags,
+                    },
+                ]));
             }
             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,
+                    availableProfiles: adoptability.availableProfiles,
+                    adoptableProfiles: adoptability.adoptableProfiles,
+                    blockingReasonsByProfile: adoptability.blockingReasonsByProfile,
                     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,
+                lockPath: setupPaths.lockPath,
                 configPath: setupPaths.configPath,
                 providersPath: setupPaths.providersPath,
                 authPath: setupPaths.authPath,
+                runtimeDir: setupPaths.runtimeDir,
+                runtimesDir: setupPaths.runtimesDir,
                 backupsDir: setupPaths.backupsDir,
                 latestBackupPath: setupPaths.latestBackupPath,
                 strategy: strategy ?? "overwrite",

package/dist/commands/help.js

@@ -44,6 +44,7 @@ function buildHelpText(commandName) {
             "  --version          Print the current CLI version.",
             "",
             "Environment:",
+            "  CODEXS_HOME        Override the codex-switch tool home directory.",
             "  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.",
             "",
@@ -60,6 +61,7 @@ function buildHelpText(commandName) {
             "",
             "Examples:",
             "  codexs init",
+            "  codexs login copilot",
             "  codexs migrate",
             "  codexs list",
             "  codexs switch",

package/dist/commands/registry.js

@@ -64,7 +64,7 @@ exports.COMMANDS = [
         usage: ["codexs bridge stop [provider] [--json] [--codex-dir <path>]"],
         details: [
             "Prefers the runtime-state instance when present and uses an explicit provider as a guard.",
-            "Clears the runtime-state manifest without mutating providers.json or auth.json.",
+            "Clears the runtime-state manifest without mutating providers.json or Codex auth state.",
             "Is idempotent when no managed bridge is currently running.",
         ],
         examples: ["codexs bridge stop", "codexs bridge stop copilot-main"],
@@ -88,16 +88,32 @@ exports.COMMANDS = [
         tokens: ["init"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Initialize a Codex directory with an empty managed providers registry.",
+        summary: "Initialize the codex-switch tool home and registry files.",
         usage: ["codexs init [--json] [--codex-dir <path>]"],
         details: [
-            "Creates providers.json with an empty providers object when it does not exist yet.",
-            "Does not require codex CLI, config.toml, or auth.json, and does not run doctor.",
-            "TTY mode can resolve ambiguous Codex directories and confirm creating a missing directory.",
-            "Non-TTY and --json runs never prompt and fail when the target directory is missing.",
+            "Creates codex-switch.json and providers.json under the tool home when they do not exist yet.",
+            "Does not create or validate config.toml, auth.json, or the target Codex directory.",
+            "When --codex-dir is passed explicitly and codex-switch.json does not exist yet, init persists it as defaultCodexDir.",
+            "Otherwise init stays scoped to tool-home state and does not persist fallback Codex directory resolution.",
         ],
         examples: ["codexs init", "codexs init --json --codex-dir ~/.codex"],
     },
+    {
+        id: "login",
+        tokens: ["login"],
+        handler: handlers_1.handleRegisteredCommand,
+        group: "write",
+        summary: "Complete upstream onboarding for interactive providers such as GitHub Copilot.",
+        usage: ["codexs login <upstream>"],
+        details: [
+            "Currently supports copilot and github-copilot as the same upstream.",
+            "Installs the local Copilot SDK under the tool home when needed, then checks login readiness.",
+            "When login is not ready, launches the bundled Copilot CLI from the runtime when available, otherwise falls back to PATH, then rechecks before succeeding.",
+            "Copilot login is shared across the local Copilot runtime, so logging into a different GitHub account replaces the upstream auth used by all Copilot providers.",
+            "Requires an interactive TTY and does not support --json.",
+        ],
+        examples: ["codexs login copilot", "codexs login github-copilot"],
+    },
     {
         id: "migrate",
         tokens: ["migrate"],
@@ -108,7 +124,7 @@ exports.COMMANDS = [
         details: [
             "Reads config.toml profiles, collects complete provider records, then writes providers.json under managed backup flow.",
             "TTY mode can collect missing provider details and choose merge or overwrite when providers.json already exists.",
-            "Migrate adopts only runtime profiles that already expose model, model_provider, matching base_url, and env_key.",
+            "Migrate adopts only runtime profiles that already expose model, model_provider, and matching base_url.",
             "Non-TTY and --json runs still fail fast because migrate profile selection and provider details remain interactive in this release.",
         ],
         examples: ["codexs migrate", "codexs migrate --overwrite --json --codex-dir ~/.codex"],
@@ -213,12 +229,16 @@ exports.COMMANDS = [
             "Confirm API key when prompted interactively because the hidden prompt asks twice before writing.",
             "Interactive tags use preset multi-select only.",
             "Automation and non-TTY environments must pass all required values explicitly.",
-            "Creating a missing profile section requires --create-profile together with --model and --base-url.",
+            "Creating a missing direct-provider profile section requires --create-profile together with --model and --base-url.",
+            "Creating a missing Copilot profile section requires --create-profile together with --model; the local bridge base_url is derived automatically.",
             "Use --copilot to create a GitHub Copilot bridge provider backed by the official SDK.",
+            "Copilot providers require SDK install and login readiness to already be satisfied via codexs login copilot.",
+            "For Copilot providers, provider apiKey stores only the local bridge secret; upstream GitHub Copilot auth stays shared in the official runtime login.",
+            "--install-copilot-sdk is kept only as a rejected compatibility flag that points to codexs login copilot.",
         ],
         examples: [
             "codexs add packycode --profile packycode --api-key sk-xxx",
-            "codexs add copilot-main --copilot --profile copilot-main --install-copilot-sdk",
+            "codexs add copilot-main --copilot --profile copilot-main",
             "codexs add",
         ],
     },
@@ -227,14 +247,15 @@ exports.COMMANDS = [
         tokens: ["switch"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Switch to a provider and rewrite the managed auth mirror.",
+        summary: "Switch the active config profile to a provider.",
         usage: ["codexs switch <provider> [--json] [--codex-dir <path>]"],
         details: [
             "When <provider> is omitted in a TTY, an interactive provider selector is shown.",
             "When <provider> is passed explicitly, switch proceeds directly without extra confirmation.",
-            "Switch updates the active config profile and rewrites auth.json from the provider envKey/apiKey pair.",
+            "Direct providers update the active config profile and rewrite auth.json with auth_mode=apikey plus OPENAI_API_KEY.",
+            "Copilot bridge providers also rewrite OPENAI_API_KEY to the local bridge secret while managing runtime routing and bridge state.",
             "Copilot bridge providers probe the optional official SDK before switching and fail fast if it is missing.",
-            "Backs up config.toml and auth.json, then rolls back on failure.",
+            "Backs up config.toml and auth.json and rolls back on failure.",
         ],
         examples: ["codexs switch freemodel", "codexs switch packycode --json"],
     },

package/dist/domain/backups.js

@@ -61,9 +61,6 @@ function validateBackupManifest(input) {
     if (typeof manifest.reason !== "string" || manifest.reason.trim() === "") {
         throw new Error("Backup manifest is missing reason.");
     }
-    if (typeof manifest.rootDir !== "string" || manifest.rootDir.trim() === "") {
-        throw new Error("Backup manifest is missing rootDir.");
-    }
     if (typeof manifest.backupDir !== "string" || manifest.backupDir.trim() === "") {
         throw new Error("Backup manifest is missing backupDir.");
     }
@@ -74,7 +71,10 @@ function validateBackupManifest(input) {
         if (!entry || typeof entry !== "object") {
             throw new Error("Backup manifest contains an invalid file entry.");
         }
-        if (typeof entry.relativePath !== "string" || typeof entry.existed !== "boolean") {
+        if (typeof entry.relativePath !== "string" ||
+            typeof entry.restorePath !== "string" ||
+            entry.restorePath.trim() === "" ||
+            typeof entry.existed !== "boolean") {
             throw new Error("Backup manifest contains an invalid file entry.");
         }
         if (entry.backupFileName !== null && typeof entry.backupFileName !== "string") {