@minniexcode/codex-switch 0.1.0 → 0.1.2

package/README.md

@@ -1,183 +1,224 @@
-# @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
+# @minniexcode/codex-switch
+
+`@minniexcode/codex-switch` is a local-first CLI for managing and switching Codex provider and model-provider routing 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.2`
+
+This is the current stable documentation line. `0.1.2` is the Copilot runtime repair release, including the managed SDK pin and the Copilot-only `stream_idle_timeout_ms = 300000` projection used to prevent long prompt idle timeouts.
+
+## 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 --model gpt-5.5 --base-url https://gateway.example.com/v1 --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 --model gpt-4.1
+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.
+- Copilot support is an experimental local bridge. The managed installer defaults to `@github/copilot-sdk@1.0.2`, Copilot runtime paths require Node.js `>=20`, and runtime checks separately reject older or prerelease SDK installs while validating API shape when the client or session is used.
+- `switch` projects the selected provider into the target Codex runtime as top-level `model` plus `model_provider`.
+- `status` is the main read command after switching.
+- `doctor` is the main repair-oriented diagnostic command.
+
+## Runtime Routing Model
+
+For Codex `0.134.0+`, the active runtime route is selected through top-level `model` and `model_provider` in `config.toml`.
+
+`codex-switch` treats that route as the runtime contract:
+
+- top-level `model` selects the active model id
+- top-level `model_provider` selects the active provider route
+- managed `[model_providers.<id>]` entries are the projected runtime provider definitions
+- `--profile` is only an alias for the managed `model_provider` id, not the primary runtime selector
+
+Direct-provider projection writes:
+
+- top-level `model`
+- top-level `model_provider`
+- `[model_providers.<id>]`
+- `auth.json` with `OPENAI_API_KEY`
+
+Managed direct-provider projection does not keep `env_key` or `env_key_instructions` in the generated runtime config. `switch`, `add`, and `edit` clean old legacy projection fields before writing the active route.
+
+For managed OpenAI-compatible routes, the projected provider entry keeps the fixed runtime shape:
+
+```toml
+model = "gpt-5.5"
+model_provider = "my-provider"
+
+[model_providers.my-provider]
+name = "my-provider"
+base_url = "https://gateway.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+Managed Copilot projection additionally writes:
+
+```toml
+stream_idle_timeout_ms = 300000
+```
+
+## 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> --model <model> --api-key <key> [--base-url <url>]
+codexs add <provider> --copilot --model <model>
+codexs edit <provider>
+codexs switch <provider>
+codexs remove <provider> [--force] [--switch-to <provider>]
+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
+
+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)
+- [PRD 0.1.0](./docs/PRD/codex-switch-prd-v0.1.0.md)
+- [PRD 0.1.1](./docs/PRD/codex-switch-prd-v0.1.1.md)
+- [PRD 0.1.2](./docs/PRD/codex-switch-prd-v0.1.2.md)
+- [Design 0.1.2](./docs/Design/codex-switch-v0.1.2-design.md)
+
+## License
+
+MIT

package/dist/app/add-provider.js

@@ -35,7 +35,6 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addProvider = addProvider;
 const crypto = __importStar(require("node:crypto"));
-const config_1 = require("../domain/config");
 const providers_1 = require("../domain/providers");
 const errors_1 = require("../domain/errors");
 const config_repo_1 = require("../storage/config-repo");
@@ -68,6 +67,7 @@ async function addProvider(args) {
         }
         : undefined;
     if (args.copilot) {
+        (0, copilot_installer_1.assertCopilotNodeRuntimeSupported)();
         const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)(args.runtimesDir);
         if (!installStatus.installed) {
             throw (0, errors_1.cliError)("COPILOT_SDK_MISSING", "The optional Copilot SDK runtime is not installed. Run `codexs login copilot` first.", {
@@ -91,24 +91,19 @@ async function addProvider(args) {
         }
     }
     const document = (0, config_repo_1.readStructuredConfig)(args.configPath);
-    const existingProfile = document.profiles.find((profile) => profile.name === args.profile);
     const existingModelProvider = document.modelProviders.find((entry) => entry.name === args.profile);
-    if (!existingProfile && !args.createProfile) {
-        throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", `Profile "${args.profile}" does not exist in config.toml.`, {
-            profile: args.profile,
+    const inheritedModel = document.currentModel ?? undefined;
+    const providerModel = args.model ?? inheritedModel;
+    if (!providerModel) {
+        throw (0, errors_1.cliError)("MANAGED_PROFILE_FIELDS_MISSING", `Provider "${args.providerName}" requires a model.`, {
             provider: args.providerName,
+            modelProvider: args.profile,
+            missingFields: ["model"],
+            suggestion: "Pass `--model <name>` or set a top-level model in config.toml first.",
         });
     }
     const directBaseUrl = args.baseUrl;
-    const upsertProfiles = !existingProfile && args.createProfile
-        ? {
-            [args.profile]: (0, config_1.validateManagedProfileCreation)(args.profile, {
-                model: args.model ?? undefined,
-                modelProvider: args.profile,
-            }),
-        }
-        : undefined;
-    if (!args.copilot && !existingModelProvider && args.createProfile && (!directBaseUrl || directBaseUrl.trim() === "")) {
+    if (!args.copilot && (!directBaseUrl || directBaseUrl.trim() === "") && !existingModelProvider) {
         throw (0, errors_1.cliError)("MANAGED_PROFILE_FIELDS_MISSING", `Model provider "${args.profile}" requires base_url.`, {
             profile: args.profile,
             modelProvider: args.profile,
@@ -119,14 +114,9 @@ async function addProvider(args) {
         ? {
             [args.profile]: (0, providers_1.buildCopilotModelProviderProjection)(runtime),
         }
-        : !existingModelProvider && args.createProfile
-            ? {
-                [args.profile]: (0, providers_1.buildDirectModelProviderProjection)(args.profile, directBaseUrl),
-            }
-            : undefined;
-    if (existingProfile) {
-        (0, config_repo_1.requireManagedProfileRuntime)(document, providers, args.profile);
-    }
+        : {
+            [args.profile]: (0, providers_1.buildDirectModelProviderProjection)(args.profile, (directBaseUrl ?? existingModelProvider?.baseUrl ?? "").trim()),
+        };
     const apiKey = args.copilot ? args.bridgeApiKey ?? crypto.randomBytes(24).toString("hex") : args.apiKey;
     const baseUrl = args.copilot ? (0, providers_1.buildCopilotBridgeBaseUrl)(runtime) : args.baseUrl ?? undefined;
     const next = {
@@ -135,6 +125,7 @@ async function addProvider(args) {
             [args.providerName]: (0, providers_1.cleanProviderRecord)({
                 profile: args.profile,
                 apiKey,
+                model: providerModel,
                 baseUrl,
                 note: args.note ?? undefined,
                 tags: args.tags,
@@ -153,14 +144,16 @@ async function addProvider(args) {
         ],
         mutate: () => {
             const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
-                upsertProfiles,
                 upsertModelProviders,
+                scrubModelProviderEnvKeys: [args.profile],
             });
             // Persist only the normalized provider payload so later reads are deterministic.
             (0, providers_repo_1.writeProvidersFile)(args.providersPath, next);
             (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
             return {
                 provider: args.providerName,
+                model: providerModel,
+                modelProvider: args.profile,
                 profile: args.profile,
                 runtimeKind: runtime?.kind ?? null,
                 createdProfileSections: configPlan.createdProfileSections,

package/dist/app/bridge.js

@@ -29,7 +29,7 @@ async function startBridge(args) {
         preferRuntimeState: false,
     });
     await requireBridgeRuntimeReadiness(args.runtimesDir);
-    const bridge = await (0, copilot_bridge_1.ensureCopilotBridge)(target.providerName, target.provider, args.runtimeDir);
+    const bridge = await (0, copilot_bridge_1.ensureCopilotBridge)(target.providerName, target.provider, args.runtimeDir, args.runtimesDir);
     const nextProvider = bridge.portChanged ? rewriteBridgeProviderPort(target.provider, bridge.port) : target.provider;
     if (bridge.portChanged) {
         try {
@@ -242,6 +242,7 @@ async function promptForCopilotBridgeSelection(runtime, targets, commandName) {
  * Verifies that the local Copilot bridge prerequisites are available before startup.
  */
 async function requireBridgeRuntimeReadiness(runtimesDir) {
+    (0, copilot_installer_1.assertCopilotNodeRuntimeSupported)();
     const installStatus = (0, copilot_installer_1.probeCopilotSdkInstall)(runtimesDir);
     if (!installStatus.installed) {
         throw (0, errors_1.cliError)("COPILOT_SDK_MISSING", "The optional Copilot SDK runtime is not installed.", {