@minniexcode/codex-switch 0.1.0 → 0.1.1

package/README.md

@@ -1,183 +1,215 @@
-# @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.1`
+
+This is the current stable release line. `0.1.1` aligns the public docs with the Codex `0.134.0+` runtime contract where top-level `model` and `model_provider` select the active route.
+
+## 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.
+- `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
+```
+
+## 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)
+- [Release PRD 0.1.1](./docs/PRD/codex-switch-prd-v0.1.1.md)
+- [Release Design 0.1.1](./docs/Design/codex-switch-v0.1.1-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");
@@ -91,24 +90,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 +113,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 +124,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 +143,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/edit-provider.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.editProvider = editProvider;
 const errors_1 = require("../domain/errors");
-const config_1 = require("../domain/config");
 const providers_1 = require("../domain/providers");
 const config_repo_1 = require("../storage/config-repo");
 const fs_utils_1 = require("../storage/fs-utils");
@@ -24,6 +23,7 @@ function editProvider(args) {
     }
     const updatedFields = [];
     const nextProfile = args.profile ?? current.profile;
+    const nextModel = args.model === null ? undefined : args.model ?? current.model;
     if (args.profile !== undefined && args.profile !== current.profile) {
         updatedFields.push("profile");
     }
@@ -33,6 +33,9 @@ function editProvider(args) {
     if (args.baseUrl !== undefined && (args.baseUrl ?? undefined) !== current.baseUrl) {
         updatedFields.push("baseUrl");
     }
+    if (args.model !== undefined && args.model !== current.model) {
+        updatedFields.push("model");
+    }
     if (args.note !== undefined && (args.note ?? undefined) !== current.note) {
         updatedFields.push("note");
     }
@@ -41,87 +44,46 @@ function editProvider(args) {
     }
     const oldProfile = current.profile;
     const newProfile = nextProfile;
-    const targetSection = document.profiles.find((profile) => profile.name === newProfile) ?? null;
     const targetModelProviderSection = document.modelProviders.find((entry) => entry.name === newProfile) ?? null;
-    const targetProfileExists = Boolean(targetSection);
-    let upsertProfiles;
     let upsertModelProviders;
-    if (!targetProfileExists) {
-        if (!args.createProfile) {
-            throw (0, errors_1.cliError)("PROFILE_NOT_FOUND", `Profile "${newProfile}" does not exist in config.toml.`, {
-                profile: newProfile,
-                provider: args.providerName,
-            });
-        }
-        if (!args.baseUrl || args.baseUrl.trim() === "") {
+    const resolvedBaseUrl = (args.baseUrl ?? current.baseUrl ?? targetModelProviderSection?.baseUrl ?? "").trim();
+    if (!current.runtime) {
+        if (!resolvedBaseUrl) {
             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,
-                modelProvider: newProfile,
-            }),
-        };
         upsertModelProviders = {
-            [newProfile]: (0, providers_1.buildDirectModelProviderProjection)(newProfile, args.baseUrl),
+            [newProfile]: (0, providers_1.buildDirectModelProviderProjection)(newProfile, resolvedBaseUrl),
         };
     }
-    else {
-        (0, config_repo_1.requireManagedProfileRuntime)(document, providers, newProfile);
-    }
-    if (targetProfileExists &&
-        !current.runtime &&
-        args.baseUrl !== undefined &&
-        args.baseUrl !== null) {
+    else if (targetModelProviderSection || args.profile !== undefined) {
         upsertModelProviders = {
             ...(upsertModelProviders ?? {}),
-            [newProfile]: (0, providers_1.buildDirectModelProviderProjection)(newProfile, args.baseUrl),
+            [newProfile]: {
+                ...(current.runtime
+                    ? {
+                        baseUrl: current.baseUrl ?? targetModelProviderSection?.baseUrl ?? "",
+                        name: "copilot",
+                        requiresOpenAiAuth: true,
+                        wireApi: "responses",
+                    }
+                    : (0, providers_1.buildDirectModelProviderProjection)(newProfile, resolvedBaseUrl)),
+            },
         };
     }
     const nextRecord = (0, providers_1.cleanProviderRecord)({
         profile: newProfile,
         apiKey: args.apiKey ?? current.apiKey,
+        model: nextModel,
         baseUrl: args.baseUrl === null ? undefined : args.baseUrl ?? current.baseUrl,
         note: args.note === null ? undefined : args.note ?? current.note,
         tags: args.tags ?? current.tags,
+        runtime: current.runtime,
     });
-    if (targetProfileExists && args.model !== undefined) {
-        upsertProfiles = {
-            [newProfile]: {
-                ...(args.model !== undefined && args.model !== null ? { model: args.model } : {}),
-            },
-        };
-        if (args.model !== undefined && targetSection?.model !== args.model && !updatedFields.includes("model")) {
-            updatedFields.push("model");
-        }
-    }
-    // Compute profile link ownership after the edit so lifecycle planning can decide whether sections stay, move, or delete.
-    const remainingLinksByProfile = new Map();
-    for (const [name, provider] of Object.entries(providers.providers)) {
-        if (name === args.providerName) {
-            continue;
-        }
-        const list = remainingLinksByProfile.get(provider.profile) ?? [];
-        list.push(name);
-        remainingLinksByProfile.set(provider.profile, list);
-    }
-    if (newProfile !== oldProfile) {
-        const list = remainingLinksByProfile.get(newProfile) ?? [];
-        list.push(args.providerName);
-        remainingLinksByProfile.set(newProfile, list);
-    }
-    const lifecycle = (0, config_1.planProfileLifecycleOutcome)({
-        providerName: args.providerName,
-        oldProfile,
-        newProfile,
-        activeProfile: document.activeProfile,
-        remainingLinksByProfile,
-        switchToProfile: args.switchToProfile ?? null,
-    });
+    const isActive = document.currentModelProvider === oldProfile;
     return (0, run_mutation_1.runMutation)({
         lockPath: args.lockPath,
         backupsDir: args.backupsDir,
@@ -133,10 +95,12 @@ function editProvider(args) {
         ],
         mutate: () => {
             const configPlan = (0, config_repo_1.createConfigMutationPlan)(document, {
-                upsertProfiles,
                 upsertModelProviders,
-                deleteProfiles: lifecycle.deletedProfileSections,
-                setActiveProfile: lifecycle.nextActiveProfile,
+                setCurrentModel: isActive ? nextModel ?? document.currentModel : undefined,
+                setCurrentModelProvider: isActive ? newProfile : undefined,
+                deleteLegacyProfile: isActive,
+                deleteLegacyProfilesByName: isActive ? [newProfile] : [],
+                scrubModelProviderEnvKeys: [newProfile],
             });
             const nextProviders = {
                 providers: {
@@ -149,12 +113,13 @@ function editProvider(args) {
             (0, config_repo_1.applyConfigMutation)(args.configPath, document, configPlan);
             return {
                 provider: args.providerName,
+                modelProvider: newProfile,
                 updatedFields,
                 createdProfileSections: configPlan.createdProfileSections,
                 createdModelProviderSections: configPlan.createdModelProviderSections,
                 deletedProfileSections: configPlan.deletedProfileSections,
-                keptSharedProfiles: lifecycle.keptSharedProfiles,
-                switchedActiveProfile: lifecycle.switchedActiveProfile,
+                keptSharedProfiles: [],
+                switchedActiveProfile: isActive && newProfile !== oldProfile,
                 adoptedProfiles: [],
                 repairedProfiles: [],
             };