codex-model-router 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Honguan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# codex-model-router
+
+A small Node.js CLI that installs a Codex skill and two custom subagents without replacing unrelated user configuration.
+
+Routing is advisory: Terra reads the skill and decides when to delegate. This package does not intercept prompts or guarantee a hard model switch.
+
+## Requirements
+
+- Node.js 18 or newer
+- A current Codex release with custom agents and local skills
+
+## Install
+
+From npm after publication:
+
+```sh
+npx codex-model-router install
+```
+
+From GitHub:
+
+```sh
+npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v1.1.0.tar.gz
+codex-model-router install
+```
+
+Project scope is the default. Use `--global` only when the setup should apply to every project:
+
+```sh
+codex-model-router install --global
+```
+
+A normal install preserves an existing main model. To explicitly set Terra/high and make the change reversible:
+
+```sh
+codex-model-router install --set-default
+```
+
+Preview without writing anything:
+
+```sh
+codex-model-router install --set-default --dry-run
+codex-model-router uninstall --dry-run
+```
+
+## What is changed
+
+Project scope manages only:
+
+```text
+.codex/config.toml
+.codex/agents/luna.toml
+.codex/agents/sol.toml
+.agents/skills/model-router/SKILL.md
+```
+
+Global scope uses `$CODEX_HOME` or `~/.codex` for Codex files and `~/.agents/skills/model-router/` for the skill.
+
+A plain install adds Terra/high only when the top-level values are absent. Existing values are preserved. `--set-default` replaces only `model` and `model_reasoning_effort`, records the exact prior values, and restores them during uninstall only when the user has not changed them afterward.
+
+Existing Luna, Sol, or skill files are never overwritten. Uninstall removes only unchanged package-owned files. Unrelated TOML settings, comments, BOM, ordering, and LF/CRLF line endings are preserved.
+
+## Installed routing
+
+- Terra/high: normal questions, coding, debugging, fixes, tests, and implementation
+- Luna/high: deterministic repeated edits, bulk patterns, searches, formatting, counting, extraction, and summaries
+- Sol/medium/workspace-write: security-sensitive or high-regression-risk review and implementation
+- Sol normally reviews first; it may edit files when Terra explicitly delegates implementation or a confirmed fix
+- Simple questions do not spawn a subagent
+
+Users may edit model names, reasoning levels, and `sandbox_mode` directly in the generated TOML files. Later installs preserve those manual edits and `doctor` reports them as user-modified.
+
+## Commands
+
+```text
+codex-model-router install [--global] [--set-default] [--dry-run]
+codex-model-router uninstall [--global] [--dry-run]
+codex-model-router doctor [--global]
+codex-model-router --version
+```
+
+`doctor` is read-only. Exit code `0` means healthy; exit code `1` reports missing, invalid, user-modified, overridden, or unsafe state.
+
+## Automatic npm publication
+
+Create a GitHub Actions repository secret named `NPM_TOKEN`:
+
+```text
+Repository Settings
+→ Secrets and variables
+→ Actions
+→ New repository secret
+```
+
+Paste the npm access token as the secret value. Never place the real token in this repository or in the workflow YAML.
+
+The `Release` workflow runs after a pull request is merged into `main`, or when started manually. It:
+
+1. Runs syntax checks, tests, and the packed-package smoke test.
+2. Reads the name and version from `package.json`.
+3. Creates the matching GitHub release when missing.
+4. Checks whether that exact version already exists on npm.
+5. Publishes only a version that is not already present.
+
+Before merging a new release, update `package.json` and `CHANGELOG.md` to the new version. Merges without a version change do not republish the package.
+
+The npm token must have package read/write permission and must be permitted to publish without an interactive OTP when the account or package requires 2FA.
+
+To publish the current version after adding the secret, open `Actions → Release → Run workflow`.
+
+## Manual npm publication
+
+The package name is unscoped and public. Before the first publish, confirm the name is available and sign in:
+
+```sh
+npm view codex-model-router
+npm login
+npm whoami
+```
+
+Review exactly what will be uploaded:
+
+```sh
+npm run check
+npm test
+npm run test:package
+npm pack --dry-run
+npm publish --dry-run
+```
+
+Publish from the package root:
+
+```sh
+npm publish
+```
+
+After publication, verify:
+
+```sh
+npm view codex-model-router version
+npx codex-model-router --version
+```
+
+For maximum security, npm Trusted Publishing can replace the long-lived token later.
+
+## Safety behavior
+
+- Refuses malformed or unsafe configuration before writing
+- Uses atomic file replacement and rolls back failed multi-file upgrades where possible
+- Stores a small package-owned state file and one backup only when an existing config is changed
+- Never modifies `AGENTS.md`, shell profiles, editor settings, hooks, MCP servers, telemetry, or environment variables
+- Dry-run creates no files, directories, backups, or temporary state
+
+Restart Codex if newly installed agents or skills are not immediately visible.
+
+Codex references: [Subagents](https://developers.openai.com/codex/subagents), [Build skills](https://developers.openai.com/codex/build-skills), and [Configuration reference](https://developers.openai.com/codex/config-reference).

package/bin/codex-model-router.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../lib/router.js";
+
+process.exitCode = await run(process.argv.slice(2), { output: console.log });