|
| 1 | +## Context |
| 2 | + |
| 3 | +ccman already knows how to write Codex configuration safely, but a user who only downloads a single installer script cannot rely on `ccman` itself being available. Installing Codex is operationally different from switching providers because it touches system dependencies and varies by platform: |
| 4 | + |
| 5 | +- Codex depends on a working Node.js + npm environment. |
| 6 | +- Users may already have Node.js installed, but the version may be incompatible with the current Codex package. |
| 7 | +- Users may already manage Node.js with `volta`, `fnm`, `nvm`, `asdf`, or `mise`; the installer should reuse that instead of introducing a second manager. |
| 8 | +- macOS, Linux, and Windows have different system package paths (`brew`, `apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`, `winget`, `choco`, `scoop`), and some users have none of them. |
| 9 | +- Global npm installs can fail because of permissions when using a system Node.js. |
| 10 | + |
| 11 | +The installer therefore needs a staged bootstrap design rather than a single shell command. |
| 12 | + |
| 13 | +## Goals |
| 14 | + |
| 15 | +- Provide a one-click Codex bootstrap flow that can move a machine from "no Codex" to "Codex installed and configured" with minimal manual branching. |
| 16 | +- Reuse a compatible existing Node.js installation when available. |
| 17 | +- Prefer an already-installed Node.js version manager over introducing a new one. |
| 18 | +- Avoid forcing a version manager when the user's current runtime already satisfies Codex requirements. |
| 19 | +- When runtime remediation is needed, prefer per-user and reversible solutions over invasive system-wide upgrades. |
| 20 | +- Preserve the same effective Codex configuration defaults used by ccman while keeping the installer self-contained. |
| 21 | +- Ensure repository-side validation stays simulation-only and never performs real runtime installation during automated checks. |
| 22 | + |
| 23 | +## Non-Goals |
| 24 | + |
| 25 | +- Managing every possible shell initialization edge case for every version manager. |
| 26 | +- Supporting Codex IDE extension installation in the first version. |
| 27 | +- Replacing the user's primary package manager or shell profile wholesale. |
| 28 | +- Silently making irreversible system-level changes without confirmation. |
| 29 | + |
| 30 | +## Proposed Flow |
| 31 | + |
| 32 | +### 1. Bootstrap entrypoint |
| 33 | + |
| 34 | +Use thin platform-native launchers: |
| 35 | + |
| 36 | +- `scripts/install-codex.sh` for macOS/Linux |
| 37 | +- `scripts/install-codex.ps1` for Windows |
| 38 | + |
| 39 | +These launchers only do the minimum needed to enter the shared decision flow: |
| 40 | + |
| 41 | +1. Detect OS + architecture. |
| 42 | +2. Detect whether `node` is already available. |
| 43 | +3. If `node` is missing, obtain a working runtime through the runtime strategy below. |
| 44 | +4. Hand off to self-contained standalone logic for the rest of the flow. |
| 45 | + |
| 46 | +This split is necessary because bootstrap logic cannot assume a compatible Node runtime exists before remediation. |
| 47 | + |
| 48 | +### 2. Runtime requirement resolution |
| 49 | + |
| 50 | +The installer should determine the required Node.js semver range dynamically from the current Codex package metadata when possible, then fall back to an installer-maintained floor if lookup fails. |
| 51 | + |
| 52 | +Preferred resolution sequence: |
| 53 | + |
| 54 | +1. If `npm` is available, query the current package metadata for `@openai/codex`. |
| 55 | +2. If metadata lookup fails, use a conservative fallback floor stored in the installer. |
| 56 | +3. After any runtime install or upgrade, re-check the resolved requirement before proceeding. |
| 57 | + |
| 58 | +This avoids freezing a stale minimum Node version in the script. |
| 59 | + |
| 60 | +### 3. Runtime decision order |
| 61 | + |
| 62 | +The runtime decision tree should be: |
| 63 | + |
| 64 | +1. **Existing compatible Node.js present** |
| 65 | + - Reuse it. |
| 66 | + - Do not install a version manager. |
| 67 | + |
| 68 | +2. **Existing Node.js present but incompatible** |
| 69 | + - If an existing version manager is detected, use that manager to install or switch to a compatible Node.js. |
| 70 | + - If no manager is detected, recommend bootstrapping a per-user manager and explain why the current system Node is insufficient. |
| 71 | + |
| 72 | +3. **Node.js missing** |
| 73 | + - If a version manager is already installed, use it. |
| 74 | + - Otherwise offer the safest platform-appropriate bootstrap path, with a recommended default. |
| 75 | + |
| 76 | +### 4. Version manager preference |
| 77 | + |
| 78 | +Detection order should prioritize already-installed tools, not a fixed global preference: |
| 79 | + |
| 80 | +- `volta` |
| 81 | +- `fnm` |
| 82 | +- `nvm` |
| 83 | +- `asdf` |
| 84 | +- `mise` |
| 85 | + |
| 86 | +If none are installed and runtime remediation is needed, recommend: |
| 87 | + |
| 88 | +- **Default recommendation:** `volta` |
| 89 | + - per-user |
| 90 | + - cross-platform |
| 91 | + - low shell coupling |
| 92 | + - good fit for global CLI tooling like Codex |
| 93 | +- **Alternative paths:** system package manager install for users who explicitly prefer it |
| 94 | + |
| 95 | +The installer should not bootstrap a manager when the current Node.js is already compatible. |
| 96 | + |
| 97 | +### 5. System package fallback |
| 98 | + |
| 99 | +When users decline a version manager or when a version manager path is unavailable, offer system package paths: |
| 100 | + |
| 101 | +- macOS: `brew install node` if Homebrew exists; optionally bootstrap Homebrew first with explicit confirmation |
| 102 | +- Linux: distro package manager path if available, but always re-check compatibility because distro Node.js can lag behind current Codex requirements |
| 103 | +- Windows: `winget` first, then `choco` or `scoop` if available |
| 104 | + |
| 105 | +System package installation must be opt-in because it is more invasive than a per-user manager. |
| 106 | + |
| 107 | +### 6. Codex installation |
| 108 | + |
| 109 | +Once a compatible Node.js runtime is active: |
| 110 | + |
| 111 | +1. Detect existing `codex`. |
| 112 | +2. If present, record current version and decide whether to keep or upgrade. |
| 113 | +3. Install or upgrade Codex through npm. |
| 114 | +4. Verify with `codex --version`. |
| 115 | + |
| 116 | +If global npm install fails because of permissions and the runtime is a system Node.js without a manager, the installer should stop and recommend the version-manager path rather than attempting unsafe privilege escalation by default. |
| 117 | + |
| 118 | +### 7. Final Codex configuration |
| 119 | + |
| 120 | +After Codex installation succeeds, the standalone installer should write `~/.codex/config.toml` and `~/.codex/auth.json` by itself. |
| 121 | + |
| 122 | +Constraints: |
| 123 | + |
| 124 | +- the script must not require `ccman` to be globally installed |
| 125 | +- the script must not require a local repo checkout or prebuilt `packages/core/dist` |
| 126 | +- the written configuration should preserve the same intended defaults as ccman's Codex setup flow wherever practical |
| 127 | +- the script should back up existing Codex config/auth files before overwriting them |
| 128 | + |
| 129 | +This keeps the user experience "download and run" while preserving behavioral consistency with ccman. |
| 130 | + |
| 131 | +## UX Principles |
| 132 | + |
| 133 | +- Show what was detected before making changes. |
| 134 | +- Prefer "reuse what the user already has" over introducing new tools. |
| 135 | +- Make invasive actions explicit and confirmable. |
| 136 | +- Support a non-interactive mode later, but design the first version for an interactive and explainable flow. |
| 137 | +- Provide a dry-run mode for debugging decisions without changing the machine. |
| 138 | +- Keep automated verification inside the repo limited to dry-run plans, parser checks, and pure decision-logic tests. |
| 139 | + |
| 140 | +## Testing Strategy |
| 141 | + |
| 142 | +Because real runtime installation is machine-specific, testing should separate pure decision logic from side effects: |
| 143 | + |
| 144 | +- unit-test detector parsing and decision tree selection |
| 145 | +- unit-test manager and package-manager preference rules |
| 146 | +- unit-test dry-run planning output for representative environments |
| 147 | +- repository automation MUST NOT run real installation against the host machine |
| 148 | +- keep real installation validation as a manual, opt-in activity outside automated repo checks |
| 149 | + |
| 150 | +## Open Questions |
| 151 | + |
| 152 | +- Whether the first version should support only GMN-based Codex configuration or also an official OpenAI login handoff. |
| 153 | +- Whether a future version should additionally expose the same flow as a `ccman` top-level command. |
0 commit comments