@minniexcode/codex-switch 0.0.11 → 0.1.0

package/README.md

@@ -1,217 +1,183 @@
-## @minniexcode/codex-switch
-
-`codex-switch` is a local-first CLI for managing and switching Codex provider/profile configuration safely.
-
-It is designed for users who work with multiple Codex providers, API keys, or profiles and want a repeatable, backup-first workflow instead of manually editing files under `~/.codex/`.
-
-中文版: [README.CN.md](./README.CN.md)
-
-## Overview
-
-What it does in `0.0.11`:
-
-- Initializes a dedicated `codex-switch` tool home
-- Adopts unmanaged runtime profiles from an existing Codex directory
-- Lists, shows, adds, edits, and removes provider records
-- Switches the active provider/profile safely
-- Supports explicit GitHub Copilot upstream onboarding
-- Manages the local Copilot bridge runtime explicitly
-- Imports and exports provider definitions
-- Runs diagnostics and detects local drift
-- Lists backups and rolls back to a previous managed state
-- Inspects `config.toml` profiles through structured read commands
-
-Current version: `0.0.11`
-
-## Install
-
-Install globally:
-
-```bash
-npm install -g @minniexcode/codex-switch
-```
-
-Or run directly:
-
-```bash
-npx @minniexcode/codex-switch --help
-```
-
-CLI entry:
-
-```bash
-codexs --help
-```
-
-## Quick Start
-
-Initialize tool state and adopt an existing Codex runtime:
-
-```bash
-codexs init
-codexs migrate
-```
-
-Inspect managed providers and config:
-
-```bash
-codexs list
-codexs show my-provider
-codexs config show
-```
-
-Add and switch a direct provider:
-
-```bash
-codexs add my-provider --profile my-provider --api-key sk-xxx
-codexs switch my-provider
-```
-
-Prepare GitHub Copilot and manage its bridge:
-
-```bash
-codexs login copilot
-codexs add copilot-main --copilot --profile copilot-main
-codexs bridge start copilot-main
-```
-
-Check runtime state:
-
-```bash
-codexs current
-codexs status
-codexs doctor
-```
-
-## Common Commands
-
-```bash
-codexs init
-codexs login copilot
-codexs migrate
-codexs list
-codexs show <provider>
-codexs current
-codexs status
-codexs config show [profile]
-codexs config list-profiles
-codexs add <provider> --profile <name> --api-key <key>
-codexs add <provider> --copilot --profile <name>
-codexs edit <provider>
-codexs switch <provider>
-codexs bridge start [provider]
-codexs bridge status [provider]
-codexs bridge stop [provider]
-codexs remove <provider> [--force] [--switch-to <profile>]
-codexs import <file> [--merge]
-codexs export <file> [--force]
-codexs backups list
-codexs rollback [backup-id]
-codexs doctor
-```
-
-Command help:
-
-```bash
-codexs help init
-codexs help login
-codexs help add
-codexs help bridge
-codexs help config
-codexs help migrate
-```
-
-## How It Works
-
-Starting in `0.0.11`, `codex-switch` uses a dual-path model.
-
-Tool home:
-
-```text
-~/.config/codex-switch/
-  codex-switch.json
-  providers.json
-  backups/
-  runtime/
-  runtimes/
-```
-
-Target Codex runtime:
-
-```text
-~/.codex/
-  config.toml
-  auth.json
-```
-
-Notes:
-
-- `providers.json` is the managed provider registry and now lives under the tool home
-- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`
-- `config.toml` is still the active runtime-routing file in the target Codex directory
-- `auth.json` is the active auth projection file
-- direct-provider switches rewrite `OPENAI_API_KEY`
-- Copilot bridge providers keep upstream login in the official Copilot runtime while `codex-switch` manages the local bridge secret, bridge state, and routing
-- mutating commands back up before writing and rollback stays available after failed or undesired changes
-
-Path overrides and resolution:
-
-- `--codex-dir <path>` explicitly targets a Codex runtime directory
-- `CODEXS_CODEX_DIR` sets the default target when `--codex-dir` is not passed
-- `CODEXS_HOME` overrides the tool home location
-
-## Automation
-
-This CLI supports both human TTY use and non-interactive automation.
-
-Current exceptions:
-
-- `login copilot` requires a real TTY and does not support `--json`
-- `migrate` remains intentionally interactive for adopt profile selection and provider detail collection
-
-Recommended global flags:
-
-```bash
---json
---codex-dir <path>
---help
---version
-```
-
-Recommendations:
-
-- use `--json` for stable machine-readable output
-- pass all required arguments explicitly in scripts or CI
-- use `--codex-dir <path>` for sandbox or test environments
-- use `CODEXS_HOME` when you want tool state isolated from your default workstation setup
-
-## Testing
-
-Build and test locally:
-
-```bash
-npm run build
-npm test
-npx tsc --noEmit
-```
-
-The repository includes a development fixture under `dev-codex/local-sandbox` plus dedicated test docs:
-
-- [Testing Guide](./docs/Tests/testing.md)
-- [Bridge Testing Notes](./docs/Tests/testing-bridge-v0.0.9.md)
-- [Test Report for 0.0.7](./docs/Tests/test-report-0.0.7.md)
-
-## Documentation
-
-- [Chinese README](./README.CN.md)
-- [AI README](./README.AI.md)
-- [Detailed CLI Usage](./docs/cli-usage.md)
-- [Testing Guide](./docs/Tests/testing.md)
-- [Product Overview](./docs/codex-switch-product-overview.md)
-- [Technical Architecture](./docs/codex-switch-technical-architecture.md)
-- [PRD 0.0.11](./docs/PRD/codex-switch-prd-v0.0.11.md)
-- [Design Doc 0.0.11](./docs/Design/codex-switch-v0.0.11-design.md)
-
-## License
-
-MIT
+# @minniexcode/codex-switch
+
+`@minniexcode/codex-switch` is a local-first CLI for managing and switching Codex provider and profile configuration safely.
+
+It keeps `codex-switch` tool state separate from the target Codex runtime, so provider management, backup flow, and runtime projection stay explicit instead of relying on manual file edits.
+
+Chinese version: [README.CN.md](./README.CN.md)
+
+## Version
+
+Current package version: `0.1.0`
+
+This is the first stable release line. The current release focuses on keeping the primary workflows, help text, operational boundaries, and release docs aligned with the implementation.
+
+## Install
+
+```bash
+npm install -g @minniexcode/codex-switch
+```
+
+Run without a global install:
+
+```bash
+npx @minniexcode/codex-switch --help
+```
+
+Built CLI entrypoint:
+
+```bash
+codexs --help
+```
+
+## Primary Workflows
+
+Direct provider workflow:
+
+```bash
+codexs init
+codexs add my-provider --profile my-provider --api-key sk-xxx
+codexs switch my-provider
+codexs status
+codexs doctor
+```
+
+GitHub Copilot workflow:
+
+```bash
+codexs init
+codexs login copilot
+codexs add copilot-main --copilot --profile copilot-main
+codexs switch copilot-main
+codexs status
+codexs doctor
+```
+
+Notes:
+
+- `init` prepares the `codex-switch` tool home and managed state.
+- `login copilot` handles upstream Copilot onboarding and auth readiness.
+- `add --copilot` does not perform login for you; it assumes Copilot login is already ready.
+- `status` is the main read command after switching.
+- `doctor` is the main repair-oriented diagnostic command.
+
+## Advanced Adopt Workflow
+
+Use `migrate` only when you already have Codex runtime state that should be adopted into managed `providers.json` state:
+
+```bash
+codexs init
+codexs migrate
+```
+
+`migrate` is an advanced adopt helper. It is not the default first step for a fresh install.
+
+## Command Surface
+
+```bash
+codexs init
+codexs login copilot
+codexs migrate
+codexs list
+codexs show <provider>
+codexs current
+codexs status
+codexs config show [profile]
+codexs config list-profiles
+codexs add <provider> --profile <name> --api-key <key>
+codexs add <provider> --copilot --profile <name>
+codexs edit <provider>
+codexs switch <provider>
+codexs remove <provider> [--force] [--switch-to <profile>]
+codexs import <file>
+codexs export <file> [--force]
+codexs bridge start [provider]
+codexs bridge status [provider]
+codexs bridge stop [provider]
+codexs backups list
+codexs rollback [backup-id]
+codexs doctor
+```
+
+`setup` still exists only as a deprecated compatibility entry that points callers to `init` or `migrate`.
+
+## Runtime Model
+
+`codex-switch` uses a dual-path model.
+
+Tool home:
+
+```text
+~/.config/codex-switch/
+  codex-switch.json
+  providers.json
+  backups/
+  runtime/
+  runtimes/
+```
+
+Target Codex runtime:
+
+```text
+~/.codex/
+  config.toml
+  auth.json
+```
+
+Key points:
+
+- `providers.json` is the managed provider registry and lives under the tool home.
+- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`.
+- `config.toml` remains the active runtime routing file in the target Codex directory.
+- `auth.json` remains the active auth projection file in the target Codex directory.
+- Direct providers rewrite `OPENAI_API_KEY` into the active runtime projection.
+- Copilot providers keep upstream GitHub authentication in the official Copilot runtime while `codex-switch` manages local bridge state and routing.
+
+Path controls:
+
+- `--codex-dir <path>` targets a specific Codex runtime directory.
+- `CODEXS_CODEX_DIR` provides the default target runtime when `--codex-dir` is not passed.
+- `CODEXS_HOME` overrides the tool home location.
+
+## Automation Notes
+
+This CLI supports both human TTY usage and non-interactive automation.
+
+Global flags:
+
+```bash
+--json
+--codex-dir <path>
+--help
+--version
+```
+
+Operational limits:
+
+- `login copilot` requires a real TTY and does not support `--json`.
+- `migrate` remains interactive when provider adoption requires human input.
+- Automation should pass explicit arguments and prefer `--json` for stable parsing.
+
+## Local Development
+
+```bash
+npm run build
+npm test
+npx tsc --noEmit
+node dist/cli.js --help
+npm pack --dry-run
+```
+
+## Documentation
+
+- [Chinese README](./README.CN.md)
+- [AI README](./README.AI.md)
+- [Detailed CLI Usage](./docs/cli-usage.md)
+- [Testing Guide](./docs/Tests/testing.md)
+- [Product Overview](./docs/codex-switch-product-overview.md)
+- [Release PRD 0.1.0](./docs/PRD/codex-switch-prd-v0.1.0.md)
+- [Release Gate PRD 0.1.0](./docs/PRD/codex-switch-prd-v0.1.0.md)
+
+## License
+
+MIT

package/dist/app/add-provider.js

@@ -99,6 +99,7 @@ async function addProvider(args) {
             provider: args.providerName,
         });
     }
+    const directBaseUrl = args.baseUrl;
     const upsertProfiles = !existingProfile && args.createProfile
         ? {
             [args.profile]: (0, config_1.validateManagedProfileCreation)(args.profile, {
@@ -107,15 +108,20 @@ async function addProvider(args) {
             }),
         }
         : undefined;
+    if (!args.copilot && !existingModelProvider && args.createProfile && (!directBaseUrl || directBaseUrl.trim() === "")) {
+        throw (0, errors_1.cliError)("MANAGED_PROFILE_FIELDS_MISSING", `Model provider "${args.profile}" requires base_url.`, {
+            profile: args.profile,
+            modelProvider: args.profile,
+            missingFields: ["base_url"],
+        });
+    }
     const upsertModelProviders = args.copilot
         ? {
             [args.profile]: (0, providers_1.buildCopilotModelProviderProjection)(runtime),
         }
         : !existingModelProvider && args.createProfile
             ? {
-                [args.profile]: {
-                    baseUrl: args.baseUrl ?? undefined,
-                },
+                [args.profile]: (0, providers_1.buildDirectModelProviderProjection)(args.profile, directBaseUrl),
             }
             : undefined;
     if (existingProfile) {

package/dist/app/edit-provider.js

@@ -53,6 +53,13 @@ function editProvider(args) {
                 provider: args.providerName,
             });
         }
+        if (!args.baseUrl || args.baseUrl.trim() === "") {
+            throw (0, errors_1.cliError)("MANAGED_PROFILE_FIELDS_MISSING", `Model provider "${newProfile}" requires base_url.`, {
+                profile: newProfile,
+                modelProvider: newProfile,
+                missingFields: ["base_url"],
+            });
+        }
         upsertProfiles = {
             [newProfile]: (0, config_1.validateManagedProfileCreation)(newProfile, {
                 model: args.model ?? undefined,
@@ -60,14 +67,21 @@ function editProvider(args) {
             }),
         };
         upsertModelProviders = {
-            [newProfile]: {
-                baseUrl: args.baseUrl ?? undefined,
-            },
+            [newProfile]: (0, providers_1.buildDirectModelProviderProjection)(newProfile, args.baseUrl),
         };
     }
     else {
         (0, config_repo_1.requireManagedProfileRuntime)(document, providers, newProfile);
     }
+    if (targetProfileExists &&
+        !current.runtime &&
+        args.baseUrl !== undefined &&
+        args.baseUrl !== null) {
+        upsertModelProviders = {
+            ...(upsertModelProviders ?? {}),
+            [newProfile]: (0, providers_1.buildDirectModelProviderProjection)(newProfile, args.baseUrl),
+        };
+    }
     const nextRecord = (0, providers_1.cleanProviderRecord)({
         profile: newProfile,
         apiKey: args.apiKey ?? current.apiKey,

package/dist/app/get-status.js

@@ -67,8 +67,10 @@ async function getStatus(codexDir, configPath, providersPath, authPath, options)
         }
     }
     const liveState = (0, runtime_state_1.inspectLiveStateDrift)(currentProfile, providers);
-    const activeProviderCandidates = currentProfile && providers ? (0, providers_1.findProvidersByProfile)(providers, currentProfile) : [];
-    const activeProvider = activeProviderCandidates.length === 1 && providers ? providers.providers[activeProviderCandidates[0]] : null;
+    const activeProviderCandidates = liveState.mappedProviders;
+    const activeProvider = liveState.providerResolvable && providers && liveState.mappedProvider
+        ? providers.providers[liveState.mappedProvider]
+        : null;
     const copilotInstall = (0, copilot_installer_1.probeCopilotSdkInstall)(options?.runtimesDir);
     const runtimeStateInspection = (0, runtime_state_repo_1.inspectCopilotBridgeState)(options?.runtimeDir);
     const runtimeState = runtimeStateInspection.state;
@@ -108,6 +110,9 @@ async function getStatus(codexDir, configPath, providersPath, authPath, options)
         // Surface unmanaged live state without mutating anything during a read-only status call.
         warnings.push("Current config profile is not mapped in providers.json. Backfill would be required before treating live state as managed.");
     }
+    if (liveState.reason === "shared-profile") {
+        warnings.push(`Current config profile "${currentProfile}" is shared by multiple providers in providers.json, so the active provider cannot be resolved uniquely.`);
+    }
     if (runtimeStateInspection.exists && !runtimeStateInspection.valid) {
         warnings.push(`Copilot bridge runtime state is unreadable: ${runtimeStateInspection.parseError ?? "unknown parse failure"}`);
     }
@@ -128,7 +133,7 @@ async function getStatus(codexDir, configPath, providersPath, authPath, options)
             currentProfile,
             currentProfileMapped: liveState.profileMapped,
             provider: liveState.mappedProvider,
-            activeProviderResolvable: activeProviderCandidates.length === 1,
+            activeProviderResolvable: liveState.providerResolvable,
             activeProviderCandidates,
             runtimeProvider: activeProvider && (0, providers_1.isCopilotBridgeProvider)(activeProvider) ? activeProvider.runtime?.kind ?? null : null,
             copilotSdk: {

package/dist/app/list-providers.js

@@ -1,16 +1,59 @@
 "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.listProviders = listProviders;
+const fs = __importStar(require("node:fs"));
+const providers_1 = require("../domain/providers");
+const runtime_state_1 = require("../domain/runtime-state");
+const config_repo_1 = require("../storage/config-repo");
 const providers_repo_1 = require("../storage/providers-repo");
 /**
  * Returns the sorted list of configured providers for display.
  */
-function listProviders(providersPath) {
+function listProviders(providersPath, configPath) {
     const providers = (0, providers_repo_1.readProvidersFile)(providersPath);
     const names = Object.keys(providers.providers).sort();
+    const currentProfile = configPath && fs.existsSync(configPath)
+        ? (0, config_repo_1.readStructuredConfig)(configPath).activeProfile
+        : null;
+    const liveState = (0, runtime_state_1.inspectLiveStateDrift)(currentProfile, providers);
     const items = names.map((name) => ({
         name,
         profile: providers.providers[name].profile,
+        providerType: (0, providers_1.isCopilotBridgeProvider)(providers.providers[name]) ? "copilot" : "direct",
+        isActive: liveState.providerResolvable && liveState.mappedProvider === name,
         note: providers.providers[name].note ?? null,
         tags: providers.providers[name].tags ?? [],
     }));
@@ -18,6 +61,10 @@ function listProviders(providersPath) {
         data: {
             providers: items,
             count: items.length,
+            currentProfile,
+            activeProvider: liveState.mappedProvider,
+            activeProviderResolvable: liveState.providerResolvable,
+            activeProviderCandidates: liveState.mappedProviders,
         },
     };
 }

package/dist/app/run-doctor.js

@@ -245,6 +245,10 @@ function renderConfigIssueMessage(issue) {
             return `Model provider section "${issue.modelProvider}" for profile "${issue.profile}" is missing from config.toml.`;
         case "MODEL_PROVIDER_BASE_URL_MISSING":
             return `Model provider section "${issue.modelProvider}" for profile "${issue.profile}" is missing base_url.`;
+        case "PROVIDER_BASE_URL_MISMATCH":
+            return issue.providerType === "direct"
+                ? `Direct provider "${issue.provider}" baseUrl does not match config.toml model provider "${issue.profile}" base_url.`
+                : String(issue.code ?? "UNKNOWN_ISSUE");
         case "ACTIVE_PROVIDER_UNRESOLVED":
             return `Active profile "${issue.profile}" maps to multiple providers, so the active managed provider cannot be resolved uniquely.`;
         case "AUTH_JSON_INVALID":