@minniexcode/codex-switch 0.0.10 → 0.0.12

package/dist/commands/handlers.js

@@ -71,15 +71,19 @@ 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) {
         case "list":
-            return (0, list_providers_1.listProviders)(paths.providersPath);
+            return (0, list_providers_1.listProviders)(paths.providersPath, paths.configPath);
         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");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to show");
             }
             if (!providerName) {
                 throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing provider name for show command.");
@@ -93,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,
@@ -109,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,
@@ -119,57 +130,107 @@ 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.");
+            }
+            if (upstream !== "copilot" && upstream !== "github-copilot") {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", `Unsupported upstream "${parsed.positionals[0] ?? ""}".`, {
+                    supportedUpstreams: ["copilot", "github-copilot"],
+                });
             }
-            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,
+            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;
+            }
+            const availability = (0, copilot_cli_1.checkCopilotCliAvailable)(paths.runtimesDir);
+            try {
+                await (0, copilot_adapter_1.readCopilotAuthState)(paths.runtimesDir);
+                return {
+                    data: {
+                        upstream: "github-copilot",
+                        sdkInstalled: true,
+                        sdkInstalledNow: installedNow,
+                        authReady: true,
+                        loginLaunched: false,
+                        cliSource: availability.ok ? availability.source ?? null : null,
+                        cliCommand: availability.command ?? null,
+                    },
+                };
+            }
+            catch (error) {
+                const normalized = (0, errors_1.normalizeError)(error);
+                if (normalized.code !== "COPILOT_AUTH_REQUIRED") {
+                    throw error;
                 }
             }
-            return (0, init_codex_1.initCodex)({
-                codexDir: setupPaths.codexDir,
-                providersPath: setupPaths.providersPath,
-                configPath: setupPaths.configPath,
-                authPath: setupPaths.authPath,
-                createCodexDir,
-            });
+            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 {
+                data: {
+                    upstream: "github-copilot",
+                    sdkInstalled: true,
+                    sdkInstalledNow: installedNow,
+                    authReady: true,
+                    loginLaunched: true,
+                    cliSource: availability.source ?? null,
+                    cliCommand: availability.command ?? null,
+                },
+            };
         }
         case "config-show":
             return (0, show_config_1.showConfig)({
@@ -185,21 +246,26 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
         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");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to switch to");
             }
             if (!providerName) {
                 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,
             });
         }
@@ -223,6 +289,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,
@@ -263,21 +330,19 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             let bridgeHost = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-host", false);
             const bridgePortValue = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-port", false);
             let bridgeApiKey = (0, args_1.getSingleOption)(parsed.commandOptions, "--bridge-api-key", false);
-            let installCopilotSdk = (0, args_1.hasFlag)(parsed.commandOptions, "--install-copilot-sdk");
+            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 = await ensureCopilotReadyForAdd({
-                    runtime,
-                    json: ctx.options.json,
-                    installCopilotSdk,
-                });
-            }
             if (!providerName || !profile || (!apiKey && !copilot)) {
                 if (ctx.options.json || !runtime.isInteractive()) {
                     throw (0, add_interactive_1.createNonInteractiveAddError)({ copilot });
@@ -327,6 +392,9 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             }
             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,
@@ -344,14 +412,12 @@ 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": {
             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");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to edit");
             }
             if (!providerName) {
                 throw (0, errors_1.cliError)("INVALID_ARGUMENT", "Missing provider name for edit command.");
@@ -388,6 +454,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,
@@ -409,7 +476,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             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");
+                providerName = await (0, interactive_1.promptForProviderSelection)(runtime, paths.providersPath, paths.configPath, "Choose a provider to remove");
             }
             if (!providerName) {
                 throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", "Missing provider name for remove command.");
@@ -422,6 +489,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,
@@ -436,6 +504,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;
@@ -531,9 +601,12 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             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",
@@ -563,107 +636,3 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             throw (0, errors_1.cliError)("UNKNOWN_COMMAND", `Unknown command: ${ctx.command}`);
     }
 }
-/**
- * Runs the deterministic Copilot onboarding preflight before any provider persistence.
- */
-async function ensureCopilotReadyForAdd(args) {
-    let installCopilotSdk = args.installCopilotSdk;
-    const interactive = (0, interactive_1.canPrompt)(args.runtime, args.json);
-    if (interactive) {
-        args.runtime.writeLine("Checking Copilot SDK runtime...");
-    }
-    if (!(0, copilot_installer_1.probeCopilotSdkInstall)().installed) {
-        if (!interactive) {
-            if (!installCopilotSdk) {
-                const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)();
-                throw (0, errors_1.cliError)("COPILOT_SDK_INSTALL_REQUIRES_TTY", "The optional Copilot SDK runtime is not installed. Pass --install-copilot-sdk when running non-interactively.", {
-                    installDir: installStatus.installDir,
-                    packageName: installStatus.packageName,
-                });
-            }
-            (0, copilot_installer_1.installCopilotSdk)();
-        }
-        else {
-            if (!installCopilotSdk) {
-                installCopilotSdk = await args.runtime.confirmAction("The optional Copilot SDK runtime is not installed. Install it now?");
-            }
-            if (!installCopilotSdk) {
-                const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)();
-                throw (0, errors_1.cliError)("COPILOT_SDK_MISSING", "The optional Copilot SDK runtime is not installed. Re-run with --install-copilot-sdk or confirm installation interactively.", {
-                    installDir: installStatus.installDir,
-                    packageName: installStatus.packageName,
-                });
-            }
-            if (interactive) {
-                args.runtime.writeLine("Installing Copilot SDK runtime...");
-            }
-            (0, copilot_installer_1.installCopilotSdk)();
-            if (interactive) {
-                args.runtime.writeLine("Copilot SDK runtime installed.");
-            }
-        }
-    }
-    if (interactive) {
-        args.runtime.writeLine("Checking GitHub Copilot login...");
-    }
-    try {
-        await (0, copilot_adapter_1.readCopilotAuthState)();
-        return installCopilotSdk;
-    }
-    catch (error) {
-        const normalized = (0, errors_1.normalizeError)(error);
-        if (normalized.code !== "COPILOT_AUTH_REQUIRED") {
-            throw error;
-        }
-        if (!interactive) {
-            throw (0, errors_1.cliError)("COPILOT_AUTH_REQUIRED", "Copilot authentication is required before the local bridge can be added.", {
-                ...(normalized.details ?? {}),
-                manualLoginCommand: "copilot login",
-                suggestion: "Run `copilot login` manually or provide supported Copilot SDK credentials, then rerun add --copilot.",
-            });
-        }
-        args.runtime.writeLine("GitHub Copilot login is required. Starting official copilot login...");
-        let loginLaunchCause;
-        try {
-            const availability = (0, copilot_cli_1.checkCopilotCliAvailable)();
-            if (!availability.ok) {
-                throw new Error(availability.cause ?? "copilot CLI is unavailable");
-            }
-            (0, copilot_cli_1.runCopilotLogin)();
-        }
-        catch (launchError) {
-            loginLaunchCause = launchError instanceof Error ? launchError.message : String(launchError);
-            args.runtime.writeLine("Unable to launch the official Copilot login automatically.");
-            args.runtime.writeLine("Run this command in the current terminal: copilot login");
-            args.runtime.writeLine("GitHub's official device flow should open the browser or show the verification URL and code.");
-        }
-        args.runtime.writeLine("GitHub Copilot login completed. Rechecking session...");
-        const retry = await args.runtime.confirmAction("Recheck GitHub Copilot login now?", {
-            defaultValue: true,
-        });
-        if (!retry) {
-            throw (0, errors_1.cliError)("COPILOT_AUTH_REQUIRED", "Copilot authentication is required before the local bridge can be added.", {
-                ...(normalized.details ?? {}),
-                manualLoginCommand: "copilot login",
-                loginLaunchCause,
-                suggestion: "Complete GitHub Copilot login with the official tooling, then rerun add --copilot.",
-            });
-        }
-        try {
-            await (0, copilot_adapter_1.readCopilotAuthState)();
-            return installCopilotSdk;
-        }
-        catch (recheckError) {
-            const rechecked = (0, errors_1.normalizeError)(recheckError);
-            if (rechecked.code !== "COPILOT_AUTH_REQUIRED") {
-                throw recheckError;
-            }
-            throw (0, errors_1.cliError)("COPILOT_AUTH_REQUIRED", "Copilot authentication is required before the local bridge can be added.", {
-                ...(rechecked.details ?? {}),
-                manualLoginCommand: "copilot login",
-                loginLaunchCause,
-                suggestion: "Complete GitHub Copilot login with the official tooling, then rerun add --copilot.",
-            });
-        }
-    }
-}

package/dist/commands/help.js

@@ -30,6 +30,10 @@ function buildHelpText(commandName) {
             "codex-switch",
             "",
             "Manage and switch local Codex provider/profile configuration safely.",
+            "Primary workflows: direct providers use init -> add -> switch -> status -> doctor.",
+            "Primary workflows: Copilot providers use init -> login copilot -> add --copilot -> switch -> status -> doctor.",
+            "Advanced adopt flows use migrate only when you already have Codex runtime state to import.",
+            "Deprecated entry: setup still exists only to point callers to init or migrate.",
             "",
             "Usage:",
             "  codexs <command> [options]",
@@ -44,6 +48,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,13 +65,14 @@ function buildHelpText(commandName) {
             "",
             "Examples:",
             "  codexs init",
-            "  codexs migrate",
-            "  codexs list",
-            "  codexs switch",
-            "  codexs bridge start",
             "  codexs add packycode --profile packycode --api-key sk-xxx",
+            "  codexs switch packycode",
+            "  codexs status",
+            "  codexs doctor",
+            "  codexs login copilot",
+            "  codexs add copilot-main --copilot --profile copilot-main",
+            "  codexs migrate",
             "  codexs config show",
-            "  codexs remove freemodel",
             "  codexs backups list",
             "  codexs rollback",
             "  codexs help add",

package/dist/commands/registry.js

@@ -88,28 +88,46 @@ 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 for the primary workflow.",
         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.",
+            "Use init first for fresh direct-provider or Copilot setups.",
         ],
         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"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Adopt unmanaged Codex config profiles into providers.json.",
+        summary: "Adopt existing Codex runtime profiles into managed providers.json state.",
         usage: ["codexs migrate [--json] [--codex-dir <path>] [--merge|--overwrite]"],
         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, and matching base_url.",
             "Non-TTY and --json runs still fail fast because migrate profile selection and provider details remain interactive in this release.",
+            "Treat migrate as an advanced adopt helper for existing runtime state, not the default first step for fresh installs.",
         ],
         examples: ["codexs migrate", "codexs migrate --overwrite --json --codex-dir ~/.codex"],
     },
@@ -118,12 +136,12 @@ exports.COMMANDS = [
         tokens: ["setup"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Deprecated. Use init or migrate instead.",
+        summary: "Deprecated. Kept only to point callers to init or migrate.",
         usage: ["codexs setup"],
         details: [
             "setup no longer performs initialization or migration work.",
-            "Use init for AI-friendly idempotent providers.json initialization.",
-            "Use migrate for interactive adoption from existing config.toml profiles.",
+            "Use init for the primary fresh-install workflow.",
+            "Use migrate only when adopting from existing config.toml profiles.",
         ],
         examples: ["codexs help init", "codexs help migrate"],
     },
@@ -166,12 +184,12 @@ exports.COMMANDS = [
         tokens: ["status"],
         handler: handlers_1.handleRegisteredCommand,
         group: "read",
-        summary: "Show a quick status summary for the local Codex directory.",
+        summary: "Show tool-home, target-runtime, provider, and runtime-health status.",
         usage: ["codexs status [--json] [--codex-dir <path>]"],
         details: [
-            "Reports file presence, current profile, and whether the live profile is mapped.",
-            "When the active provider uses a local runtime bridge, status also reports bridge and SDK state.",
-            "Surfaces config consistency signals without mutating any files.",
+            "Reports the target Codex runtime, tool-home storage roles, current profile, and whether the live profile is mapped.",
+            "When the active provider uses a local runtime bridge, status also reports bridge, Copilot SDK, and upstream auth state.",
+            "Surfaces dual-path config consistency signals without mutating any files.",
             "Use doctor for deeper diagnostics.",
         ],
         examples: ["codexs status", "codexs status --json --codex-dir ./.tmp-codex"],
@@ -200,7 +218,7 @@ exports.COMMANDS = [
         tokens: ["add"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Add a provider with explicit flags or progressive TTY prompts.",
+        summary: "Add a managed provider for the primary direct or Copilot workflows.",
         usage: [
             "codexs add <provider> --profile <name> --api-key <key> [--base-url <url>] [--note <text>] [--tag <tag> ...]",
             "codexs add <provider> --copilot --profile <name> [--bridge-host <host>] [--bridge-port <port>] [--bridge-api-key <secret>] [--install-copilot-sdk]",
@@ -213,13 +231,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.",
-            "TTY add --copilot checks SDK install and GitHub Copilot login before it asks for Copilot provider fields.",
+            "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",
         ],
     },
@@ -228,14 +249,15 @@ exports.COMMANDS = [
         tokens: ["switch"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Switch the active config profile to a provider.",
+        summary: "Switch the active runtime to a managed 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.",
             "Direct providers update the active config profile and rewrite auth.json with auth_mode=apikey plus OPENAI_API_KEY.",
-            "Copilot bridge providers still manage runtime routing and bridge state instead of rewriting 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.",
+            "Switch succeeds only after the managed profile projection is written to the target runtime.",
             "Backs up config.toml and auth.json and rolls back on failure.",
         ],
         examples: ["codexs switch freemodel", "codexs switch packycode --json"],
@@ -302,7 +324,7 @@ exports.COMMANDS = [
         tokens: ["doctor"],
         handler: handlers_1.handleRegisteredCommand,
         group: "recovery",
-        summary: "Run configuration and environment diagnostics.",
+        summary: "Run repair-oriented diagnostics across tool-home and target-runtime state.",
         usage: ["codexs doctor [--json] [--codex-dir <path>]"],
         details: [
             "Checks the expected config files, provider/profile consistency, and Codex CLI availability.",

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") {