@minniexcode/codex-switch 0.0.12 → 0.1.0

package/README.md

@@ -1,183 +1,183 @@
-# @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.0.12`
-
-This repository is still on a development-version line. The current release focuses on making the primary workflows, help text, and operational boundaries consistent 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` still depends on interactive profile selection and provider-detail collection in this release.
-- 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.0.12](./docs/PRD/codex-switch-prd-v0.0.12.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 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/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":

package/dist/cli/output.js

@@ -93,6 +93,9 @@ function renderHumanSuccess(command, data, warnings) {
                     if (!activeProviderResolvable && activeCandidates.length > 1) {
                         lines.push(`Current provider: ambiguous (${activeCandidates.join(", ")})`);
                     }
+                    else if (!activeProviderResolvable) {
+                        lines.push("Current provider: unmanaged or unresolved");
+                    }
                 }
                 for (const provider of providers) {
                     const tags = Array.isArray(provider.tags) && provider.tags.length > 0
@@ -265,6 +268,9 @@ function renderStatusHealth(data) {
     if (issues.some((issue) => issue.code === "ACTIVE_PROVIDER_UNRESOLVED")) {
         return "active provider ambiguous";
     }
+    if (issues.some((issue) => issue.code === "PROVIDER_BASE_URL_MISMATCH")) {
+        return "provider projection drift";
+    }
     if (activePathUsesCopilot && copilotSdk.installed === false) {
         return "copilot sdk missing";
     }
@@ -335,6 +341,8 @@ function renderDoctorIssueNextStep(issue) {
         case "ACTIVE_PROVIDER_UNRESOLVED":
         case "SHARED_PROFILE_REFERENCE":
             return "make provider-to-profile mappings unique before relying on current-provider detection";
+        case "PROVIDER_BASE_URL_MISMATCH":
+            return "rerun `codexs edit <provider> --base-url <url>` or `codexs switch <provider>` to repair the runtime projection";
         default:
             return "inspect the issue details and rerun `codexs doctor` after fixing the state";
     }

package/dist/commands/registry.js

@@ -150,9 +150,13 @@ exports.COMMANDS = [
         tokens: ["list"],
         handler: handlers_1.handleRegisteredCommand,
         group: "read",
-        summary: "List configured providers from providers.json.",
+        summary: "List managed providers with profile, type, and current-state hints.",
         usage: ["codexs list [--json] [--codex-dir <path>]"],
-        details: ["Reads providers.json and prints provider-to-profile mappings.", "Use --json for machine-readable automation output."],
+        details: [
+            "Reads providers.json and prints provider-to-profile mappings together with provider type.",
+            "When the active profile is shared by multiple providers, list surfaces the ambiguity instead of inventing one current provider.",
+            "Use --json for machine-readable automation output.",
+        ],
         examples: ["codexs list", "codexs list --json"],
     },
     {
@@ -184,12 +188,13 @@ exports.COMMANDS = [
         tokens: ["status"],
         handler: handlers_1.handleRegisteredCommand,
         group: "read",
-        summary: "Show tool-home, target-runtime, provider, and runtime-health status.",
+        summary: "Show tool-home, target-runtime, provider-path, and runtime-health status.",
         usage: ["codexs status [--json] [--codex-dir <path>]"],
         details: [
             "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.",
+            "Organizes the human-readable view around current state, health impact, and next step.",
             "Use doctor for deeper diagnostics.",
         ],
         examples: ["codexs status", "codexs status --json --codex-dir ./.tmp-codex"],
@@ -324,7 +329,7 @@ exports.COMMANDS = [
         tokens: ["doctor"],
         handler: handlers_1.handleRegisteredCommand,
         group: "recovery",
-        summary: "Run repair-oriented diagnostics across tool-home and target-runtime state.",
+        summary: "Run issue-first 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/config.js

@@ -268,6 +268,8 @@ function buildManagedProfileViews(document, providers) {
  */
 function collectConfigConsistencyIssues(document, providers) {
     const issues = [];
+    const providerMap = providers?.providers ?? null;
+    const profileLinkMap = buildProfileLinkMap(providers);
     for (const view of buildManagedProfileViews(document, providers)) {
         if (view.source === "orphaned-reference") {
             issues.push({
@@ -319,11 +321,34 @@ function collectConfigConsistencyIssues(document, providers) {
                         modelProvider: view.modelProvider,
                     });
                 }
+                else {
+                    const profileLinkInfo = profileLinkMap.get(view.name);
+                    if (profileLinkInfo &&
+                        profileLinkInfo.linkedProviders.length === 1 &&
+                        providerMap) {
+                        const providerName = profileLinkInfo.linkedProviders[0];
+                        const provider = providerMap[providerName];
+                        if (provider &&
+                            !provider.runtime &&
+                            typeof provider.baseUrl === "string" &&
+                            provider.baseUrl.trim() !== "" &&
+                            provider.baseUrl !== modelProviderSection.baseUrl) {
+                            issues.push({
+                                code: "PROVIDER_BASE_URL_MISMATCH",
+                                profile: view.name,
+                                provider: providerName,
+                                providerBaseUrl: provider.baseUrl,
+                                configBaseUrl: modelProviderSection.baseUrl,
+                                providerType: "direct",
+                            });
+                        }
+                    }
+                }
             }
         }
     }
     if (document.activeProfile) {
-        const activeLinkInfo = buildProfileLinkMap(providers).get(document.activeProfile);
+        const activeLinkInfo = profileLinkMap.get(document.activeProfile);
         if (!activeLinkInfo) {
             issues.push({
                 code: "UNMANAGED_ACTIVE_PROFILE",

package/dist/domain/providers.js

@@ -10,6 +10,7 @@ exports.isRuntimeBackedProvider = isRuntimeBackedProvider;
 exports.isCopilotBridgeProvider = isCopilotBridgeProvider;
 exports.buildCopilotBridgeBaseUrl = buildCopilotBridgeBaseUrl;
 exports.buildCopilotModelProviderProjection = buildCopilotModelProviderProjection;
+exports.buildDirectModelProviderProjection = buildDirectModelProviderProjection;
 /**
  * Validates and normalizes unknown JSON into the providers.json domain model.
  */
@@ -162,6 +163,21 @@ function buildCopilotModelProviderProjection(runtime) {
         wireApi: "responses",
     };
 }
+/**
+ * Builds the Codex-facing custom model_provider projection for a direct provider.
+ */
+function buildDirectModelProviderProjection(profile, baseUrl) {
+    const normalizedBaseUrl = baseUrl.trim();
+    if (!normalizedBaseUrl) {
+        throw new Error(`Direct model provider "${profile}" requires a non-empty base_url.`);
+    }
+    return {
+        baseUrl: normalizedBaseUrl,
+        name: profile.trim(),
+        requiresOpenAiAuth: true,
+        wireApi: "responses",
+    };
+}
 /**
  * Validates one runtime-backed provider block.
  */