@yhong91/cpac 0.1.0

package/README.md

@@ -0,0 +1,237 @@
+# CPA Companion (cpac)
+
+CPAC 将 Codex 和 Claude Code 接入远端 CLIProxyAPI（CPA）：
+
+- **Codex**：注入模型目录和 provider，并可逐字节恢复原配置。
+- **Claude Code**：通过临时环境变量启动，不修改 Claude Code 配置。
+
+实现基于 TypeScript + Node.js，运行时零依赖。
+
+## 要求
+
+- [Node.js](https://nodejs.org/) 20 或更新版本（npm 随 Node 安装）
+- 已安装需要使用的 agent：`codex` 或 `claude`
+- 有权访问的 CPA API key
+
+## 安装
+
+从 npm 安装后：
+
+```bash
+npm install -g @yhong91/cpac
+cpac
+```
+
+开发目录中安装：
+
+```bash
+npm install
+npm run build
+npm install -g .
+cpac
+```
+
+## 首次引导
+
+无参数运行 `cpac` 会显示当前 CPA、密钥状态和可用命令：
+
+```text
+CPA Companion
+
+CPA: https://cpa.vibetime.cc
+CPA_API_KEY: configured / not configured
+
+Commands:
+  cpac claude [args...]  Launch Claude Code through CPA
+  cpac inject            Inject CPA into Codex
+  cpac status            Show Codex injection status
+  cpac restore           Restore the original Codex config
+  cpac --help            Show command usage
+```
+
+默认 CPA 地址内置为 `https://cpa.vibetime.cc`，不需要创建 `~/.config/cpac/`。
+
+若 `CPA_API_KEY` 尚未设置，交互式引导会隐藏输入密钥，并将受 CPAC 标记管理的 export 区块写入当前 shell 的启动文件：
+
+| Shell | 写入位置 |
+| --- | --- |
+| zsh | `~/.zshrc` |
+| bash（macOS） | `~/.bash_profile` |
+| bash（Linux 等） | `~/.bashrc` |
+| sh / dash / ksh | `~/.profile` |
+
+写入内容形如：
+
+```bash
+# >>> CPAC CPA_API_KEY >>>
+export CPA_API_KEY='...'
+# <<< CPAC CPA_API_KEY <<<
+```
+
+CPAC 会保留启动文件中的其他设置；再次运行引导配置密钥时，受管区块会原位更新，不会重复追加。写入后按引导提示打开新终端，或在当前终端执行：
+
+```bash
+source ~/.zshrc # 使用引导实际显示的文件
+```
+
+程序无法直接修改已经运行的父 shell，所以 `source` 或新终端仍然是必要的。
+
+也可以跳过引导，自行设置：
+
+```bash
+export CPA_API_KEY='...'
+```
+
+## 命令
+
+### 引导和帮助
+
+```bash
+cpac
+cpac --help
+```
+
+### Claude Code
+
+通过 CPA 启动 Claude Code，后续参数原样传递：
+
+```bash
+cpac claude
+cpac claude --model claude-sonnet-4-5
+cpac claude -- -p "检查当前项目"
+```
+
+`cpac claude` 会为 Claude Code 子进程设置：
+
+```text
+ANTHROPIC_BASE_URL=<CPA 地址>
+ANTHROPIC_AUTH_TOKEN=<CPA_API_KEY>
+```
+
+同时清除可能覆盖网关选择的 `ANTHROPIC_API_KEY` 和 Claude Code 云 provider 环境变量。它不会修改 `~/.claude/`，并原样返回 Claude Code 的退出码。
+
+> CPA 服务端必须支持 Claude Code 使用的 Anthropic Messages API（`/v1/messages`）。CPAC 不负责协议转换，也不启动本地代理。
+
+### Codex
+
+注入 CPA 模型目录：
+
+```bash
+cpac inject
+```
+
+查看状态：
+
+```bash
+cpac status
+```
+
+恢复注入前的原配置：
+
+```bash
+cpac restore
+```
+
+`inject` 从 `/v1/models?client_version=1` 获取 Codex rich catalog，将根级 `model_provider`、`model_catalog_json` 指向 CPA，并追加 `[model_providers.cpac_cpa]`。其他用户 TOML 内容会保留；若已有同名 provider 且没有 CPAC state，CPAC 会拒绝接管。
+
+第一次注入时，原文件按原始 bytes 备份到 `state_dir/config.toml.backup`。重复注入不会覆盖首次备份，并会保留 CPAC 管理字段之外的用户编辑。`restore` 按原 mode 逐字节恢复首次备份；若原文件不存在，则删除注入创建的 `config.toml`。
+
+默认路径：
+
+```text
+Codex 配置：$CODEX_HOME/config.toml，未设置 CODEX_HOME 时为 ~/.codex/config.toml
+CPAC state：~/.cpac
+```
+
+为防止误删或覆盖，`state_dir` 不能是文件系统根目录、用户 home、系统临时目录，也不能包含 Codex 配置文件。
+
+## 环境变量
+
+| 变量 | 默认值 | 作用 |
+| --- | --- | --- |
+| `CPA_API_KEY` | 无 | CPA Bearer key；可由 `cpac` 首次引导写入 shell 启动文件 |
+| `CPA_BASE_URL` | `https://cpa.vibetime.cc` | 覆盖内置 CPA 地址 |
+| `CPAC_CONFIG` | `~/.config/cpac/config.json` | 指定可选 JSON 配置路径 |
+| `CODEX_HOME` | `~/.codex` | Codex home 目录 |
+
+CPAC CLI 可临时覆盖 CPA 地址：
+
+```bash
+CPA_BASE_URL='https://cpa.example.com' cpac claude
+```
+
+`pi-cpa.ts` 插件不读取此变量，固定连接远程 `https://cpa.vibetime.cc`，并且只从 Pi 进程环境读取 `CPA_API_KEY`；不读取用户 home 中的私有文件。
+
+## 可选 JSON 配置
+
+默认场景不需要配置文件，文件不存在时 CPAC 直接使用内置默认值，也不会创建目录。仅在需要覆盖 Codex 路径、state 目录或密钥变量名时创建配置，例如：
+
+```json
+{
+  "cpa_url": "https://cpa.example.com",
+  "api_key_env": "CPA_API_KEY",
+  "codex_config": "~/.codex/config.toml",
+  "state_dir": "~/.cpac"
+}
+```
+
+支持字段：
+
+- `cpa_url`：可选，绝对 `http(s)` URL，可带或不带 `/v1`
+- `api_key_env`：可选，密钥环境变量名，默认 `CPA_API_KEY`
+- `codex_config`：可选，Codex 配置路径
+- `state_dir`：可选，CPAC state 路径
+
+使用自定义配置：
+
+```bash
+cpac inject --config ./cpac.json
+cpac claude --config ./cpac.json -- --model claude-sonnet-4-5
+```
+
+也可以设置：
+
+```bash
+export CPAC_CONFIG=/path/to/cpac.json
+```
+
+## 安全行为
+
+- API key 不写入 CPAC JSON、Codex 配置、备份、state、catalog 或日志。
+- 引导输入不回显，写入 shell 时会正确引用特殊字符。
+- shell 启动文件和 Codex 配置均通过同目录临时文件原子替换。
+- CPA 请求失败、catalog 无效或 key 缺失时，首次注入不会修改 Codex 配置。
+- `restore` 只删除 CPAC 自有的 state、backup 和 catalog，不删除 `state_dir` 中的其他文件。
+
+## 开发
+
+```bash
+npm install
+npm test
+npm run check
+npm run build
+npm run check:pi
+npm run pack:check
+```
+
+发布包的 CLI 入口为 `dist/cpac.js`。`dist/` 是构建产物，不应手工编辑。
+
+## npm 发布
+
+`.github/workflows/publish.yml` 在推送 `v*` tag 或手动触发时执行测试、类型检查、构建并发布到 npm。tag 发布会校验 tag 必须等于 `v` 加 `package.json` 的版本，例如 `v0.1.0`。
+
+首次发布前：
+
+1. 在 npm 创建账号并启用 2FA。
+2. 因为新包尚不存在，先创建允许 publish 且可绕过 2FA 的 npm granular access token，在仓库的 **Settings → Secrets and variables → Actions** 添加 `NPM_TOKEN`，然后手动运行 `Publish to npm` workflow 完成首次发布。
+3. 首次发布后，在 npm 包 `@yhong91/cpac` 的设置中添加 Trusted Publisher：GitHub 用户 `yhong91`、仓库 `cpac`、workflow 文件 `publish.yml`，允许 `npm publish`。
+4. Trusted Publisher 生效后删除 GitHub 的 `NPM_TOKEN`；后续 workflow 自动使用 OIDC。
+
+正常发布新版本：
+
+```bash
+npm version patch   # 或 minor / major
+git push --follow-tags
+```
+
+仓库当前为 private，因此 npm Trusted Publishing 可以使用，但 npm 不会为发布包生成 provenance。

package/cpac.example.json

@@ -0,0 +1,4 @@
+{
+  "cpa_url": "https://cpa.example.com",
+  "api_key_env": "CPA_API_KEY"
+}

package/dist/cpac.js

@@ -0,0 +1,691 @@
+#!/usr/bin/env node
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, parse, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+export const PROVIDER = "cpac_cpa";
+const DEFAULT_CPA_URL = "https://cpa.vibetime.cc";
+const MAX_CATALOG_BYTES = 16 * 1024 * 1024;
+const CONFIG_KEYS = new Set([
+    "cpa_url",
+    "api_key_env",
+    "codex_config",
+    "state_dir",
+]);
+const STATE_KEYS = new Set(["config_path", "config_existed", "config_mode"]);
+const STATE_FILES = ["state.json", "config.toml.backup", "codex-models.json"];
+const ROOT_KEY = /^\s*(?:model_provider|"model_provider"|'model_provider'|model_catalog_json|"model_catalog_json"|'model_catalog_json')\s*=/;
+let atomicSequence = 0;
+export class CPACError extends Error {
+}
+function objectValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function expandUserPath(value) {
+    if (value === "~")
+        return homedir();
+    if (value.startsWith("~/") || value.startsWith("~\\"))
+        return join(homedir(), value.slice(2));
+    return value;
+}
+export function defaultConfigPath() {
+    return resolve(expandUserPath(process.env.CPAC_CONFIG || "~/.config/cpac/config.json"));
+}
+function normalizeCpaUrl(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new CPACError("cpa_url must be a non-empty string");
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new CPACError("cpa_url must be an absolute http(s) URL");
+    }
+    if (!["http:", "https:"].includes(parsed.protocol) ||
+        !parsed.hostname ||
+        parsed.username ||
+        parsed.password ||
+        parsed.search ||
+        parsed.hash) {
+        throw new CPACError("cpa_url must be an absolute http(s) URL without credentials, query, or fragment");
+    }
+    return value.trim().replace(/\/+$/, "");
+}
+export function loadConfig(path, useDefaultsIfMissing = false) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT" &&
+            useDefaultsIfMissing) {
+            value = {};
+        }
+        else if (error.code === "ENOENT") {
+            throw new CPACError(`config not found: ${path}`);
+        }
+        else {
+            throw new CPACError(`cannot read config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!objectValue(value))
+        throw new CPACError("config must be a JSON object");
+    const unknown = Object.keys(value)
+        .filter((key) => !CONFIG_KEYS.has(key))
+        .sort();
+    if (unknown.length)
+        throw new CPACError(`unknown config keys: ${unknown.join(", ")}`);
+    const cpaUrl = normalizeCpaUrl(value.cpa_url ?? process.env.CPA_BASE_URL?.trim() ?? DEFAULT_CPA_URL);
+    const apiKeyEnv = value.api_key_env ?? "CPA_API_KEY";
+    if (typeof apiKeyEnv !== "string" ||
+        !/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) {
+        throw new CPACError("api_key_env must be an environment variable name");
+    }
+    if (value.codex_config !== undefined &&
+        (typeof value.codex_config !== "string" || !value.codex_config.trim())) {
+        throw new CPACError("codex_config must be a non-empty string");
+    }
+    if (value.state_dir !== undefined &&
+        (typeof value.state_dir !== "string" || !value.state_dir.trim())) {
+        throw new CPACError("state_dir must be a non-empty string");
+    }
+    const codexHome = expandUserPath(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"));
+    const codexConfig = resolve(expandUserPath(value.codex_config ||
+        join(codexHome, "config.toml")));
+    const stateDir = resolve(expandUserPath(value.state_dir || join(homedir(), ".cpac")));
+    const stateToConfig = relative(stateDir, codexConfig);
+    if ([parse(stateDir).root, resolve(homedir()), resolve(tmpdir())].includes(stateDir) ||
+        stateToConfig === "" ||
+        (!stateToConfig.startsWith("..") && !isAbsolute(stateToConfig))) {
+        throw new CPACError("state_dir must not be a filesystem root, home/temp directory, or contain codex_config");
+    }
+    return {
+        cpa_url: cpaUrl,
+        api_key_env: apiKeyEnv,
+        codex_config: codexConfig,
+        state_dir: stateDir,
+    };
+}
+export function apiBase(cpaUrl) {
+    try {
+        const url = new URL(cpaUrl);
+        return url.pathname.replace(/\/+$/, "").endsWith("/v1")
+            ? cpaUrl
+            : `${cpaUrl}/v1`;
+    }
+    catch {
+        throw new CPACError("cpa_url must be an absolute http(s) URL");
+    }
+}
+export async function fetchCatalog(cpaUrl, apiKey) {
+    let response;
+    try {
+        response = await fetch(`${apiBase(cpaUrl)}/models?client_version=1`, {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                Accept: "application/json",
+            },
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        throw new CPACError("CPA catalog request failed");
+    }
+    if (!response.ok)
+        throw new CPACError(`CPA catalog request failed: HTTP ${response.status}`);
+    const declaredLength = response.headers.get("content-length");
+    if (declaredLength &&
+        /^\d+$/.test(declaredLength) &&
+        Number(declaredLength) > MAX_CATALOG_BYTES) {
+        await response.body?.cancel();
+        throw new CPACError("CPA catalog exceeds 16 MiB");
+    }
+    const chunks = [];
+    let length = 0;
+    const reader = response.body?.getReader();
+    if (reader) {
+        while (true) {
+            let result;
+            try {
+                result = await reader.read();
+            }
+            catch {
+                throw new CPACError("CPA catalog request failed");
+            }
+            if (result.done)
+                break;
+            length += result.value.byteLength;
+            if (length > MAX_CATALOG_BYTES) {
+                await reader.cancel();
+                throw new CPACError("CPA catalog exceeds 16 MiB");
+            }
+            chunks.push(result.value);
+        }
+    }
+    const body = Buffer.concat(chunks, length);
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+    }
+    catch {
+        throw new CPACError("CPA catalog is not valid JSON");
+    }
+    const models = objectValue(document) ? document.models : undefined;
+    if (!Array.isArray(models) || models.length === 0) {
+        throw new CPACError("CPA rich catalog must contain a non-empty models array");
+    }
+    if (models.some((model) => !objectValue(model) ||
+        typeof model.slug !== "string" ||
+        !model.slug.trim())) {
+        throw new CPACError("CPA catalog contains a model without a slug");
+    }
+    return {
+        bytes: Buffer.from(`${JSON.stringify(document, null, 2)}\n`),
+        modelCount: models.length,
+    };
+}
+export function tomlString(value) {
+    return JSON.stringify(value);
+}
+export function dominantEol(content) {
+    const crlf = (content.match(/\r\n/g) ?? []).length;
+    if (crlf === 0)
+        return "\n";
+    const bareLf = (content.match(/\n/g) ?? []).length - crlf;
+    return crlf >= bareLf ? "\r\n" : "\n";
+}
+function providerPatterns(provider = PROVIDER) {
+    const escaped = provider.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const modelProviders = `(?:model_providers|"model_providers"|'model_providers')`;
+    const providerToken = `(?:${escaped}|"${escaped}"|'${escaped}')`;
+    return {
+        header: new RegExp(`^\\s*\\[\\s*${modelProviders}\\s*\\.\\s*${providerToken}\\s*\\]\\s*(?:#.*)?$`),
+        arrayHeader: new RegExp(`^\\s*\\[\\[\\s*${modelProviders}\\s*\\.\\s*${providerToken}\\s*\\]\\]\\s*(?:#.*)?$`),
+        parentHeader: new RegExp(`^\\s*\\[\\s*${modelProviders}\\s*\\]\\s*(?:#.*)?$`),
+        inlineKey: new RegExp(`^\\s*${providerToken}\\s*=`),
+        dottedKey: new RegExp(`^\\s*${modelProviders}\\s*\\.\\s*${providerToken}\\s*=`),
+    };
+}
+function providerHeader(provider = PROVIDER) {
+    return providerPatterns(provider).header;
+}
+export function hasProviderTable(content, provider = PROVIDER) {
+    const patterns = providerPatterns(provider);
+    let inRoot = true;
+    let inModelProviders = false;
+    for (const line of content.split(/\r?\n/)) {
+        if (patterns.header.test(line) || patterns.arrayHeader.test(line))
+            return true;
+        if (/^\s*\[/.test(line)) {
+            inRoot = false;
+            inModelProviders = patterns.parentHeader.test(line);
+            continue;
+        }
+        if ((inModelProviders && patterns.inlineKey.test(line)) ||
+            (inRoot && patterns.dottedKey.test(line)))
+            return true;
+    }
+    return false;
+}
+function stripManagedConfig(content) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+    }
+    catch {
+        throw new CPACError("Codex config must be UTF-8");
+    }
+    const eol = dominantEol(text);
+    const header = providerHeader();
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    let inRoot = true;
+    let inProvider = false;
+    const kept = [];
+    for (const line of lines) {
+        if (inProvider && /^\s*\[/.test(line))
+            inProvider = false;
+        if (!inProvider && header.test(line)) {
+            inProvider = true;
+            continue;
+        }
+        if (inProvider)
+            continue;
+        if (/^\s*\[/.test(line))
+            inRoot = false;
+        if (inRoot && (ROOT_KEY.test(line) || line.startsWith("# CPAC managed;")))
+            continue;
+        kept.push(line);
+    }
+    const output = kept.join("\n");
+    return Buffer.from(eol === "\n" ? output : output.replace(/\n/g, "\r\n"));
+}
+export function buildCodexConfig(original, cpaUrl, apiKeyEnv, catalogPath) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(original);
+    }
+    catch {
+        throw new CPACError("Codex config must be UTF-8");
+    }
+    if (hasProviderTable(text)) {
+        throw new CPACError(`Codex config already contains [model_providers.${PROVIDER}]`);
+    }
+    const eol = dominantEol(text);
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    let inRoot = true;
+    const kept = lines.filter((line) => {
+        if (/^\s*\[/.test(line))
+            inRoot = false;
+        return !(inRoot && ROOT_KEY.test(line));
+    });
+    let body = kept.join("\n");
+    if (body && !body.endsWith("\n"))
+        body += "\n";
+    const root = [
+        "# CPAC managed; run CPAC 'restore' to restore the original file.",
+        `model_provider = ${tomlString(PROVIDER)}`,
+        `model_catalog_json = ${tomlString(catalogPath)}`,
+        "",
+    ].join("\n");
+    const provider = [
+        "",
+        `[model_providers.${PROVIDER}]`,
+        'name = "CPA"',
+        `base_url = ${tomlString(apiBase(cpaUrl))}`,
+        `env_key = ${tomlString(apiKeyEnv)}`,
+        'wire_api = "responses"',
+        "",
+    ].join("\n");
+    const output = root + body + provider;
+    return Buffer.from(eol === "\n" ? output : output.replace(/\n/g, "\r\n"));
+}
+export function atomicWrite(path, data, mode = 0o600) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.cpac.${process.pid}.${Date.now()}.${++atomicSequence}.tmp`;
+    let descriptor;
+    try {
+        descriptor = openSync(temporary, "wx", 0o600);
+        writeFileSync(descriptor, data);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        chmodSync(temporary, mode);
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch (closeError) {
+                void closeError;
+            }
+        }
+        try {
+            unlinkSync(temporary);
+        }
+        catch (unlinkError) {
+            void unlinkError;
+        }
+        throw error;
+    }
+}
+function readState(stateDir) {
+    const path = join(stateDir, "state.json");
+    if (!existsSync(path))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new CPACError(`cannot read state: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!objectValue(value) ||
+        Object.keys(value).some((key) => !STATE_KEYS.has(key)) ||
+        Object.keys(value).length !== STATE_KEYS.size) {
+        throw new CPACError("invalid state file");
+    }
+    if (typeof value.config_path !== "string" || !isAbsolute(value.config_path)) {
+        throw new CPACError("invalid config path in state");
+    }
+    if (typeof value.config_existed !== "boolean")
+        throw new CPACError("invalid config_existed value in state");
+    if (!Number.isInteger(value.config_mode) ||
+        value.config_mode < 0 ||
+        value.config_mode > 0o7777) {
+        throw new CPACError("invalid config_mode value in state");
+    }
+    return value;
+}
+function originalBytes(stateDir, state, expectedPath) {
+    if (state.config_path !== expectedPath) {
+        throw new CPACError(`active injection belongs to ${state.config_path}; restore it first`);
+    }
+    if (!state.config_existed)
+        return new Uint8Array();
+    try {
+        return readFileSync(join(stateDir, "config.toml.backup"));
+    }
+    catch (error) {
+        throw new CPACError(`cannot read original config backup: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function cleanupStateFiles(stateDir) {
+    for (const name of STATE_FILES)
+        rmSync(join(stateDir, name), { force: true });
+    try {
+        rmdirSync(stateDir);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT" && code !== "ENOTEMPTY" && code !== "EEXIST")
+            throw error;
+    }
+}
+export async function inject(config) {
+    const apiKey = process.env[config.api_key_env]?.trim();
+    if (!apiKey)
+        throw new CPACError(`environment variable ${config.api_key_env} is not set`);
+    const state = readState(config.state_dir);
+    let existed;
+    let original;
+    let originalMode;
+    if (state) {
+        const backup = originalBytes(config.state_dir, state, config.codex_config);
+        try {
+            original = existsSync(config.codex_config)
+                ? stripManagedConfig(readFileSync(config.codex_config))
+                : backup;
+        }
+        catch (error) {
+            if (error instanceof CPACError)
+                throw error;
+            throw new CPACError(`cannot read Codex config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        existed = state.config_existed;
+        originalMode = state.config_mode;
+    }
+    else {
+        existed = existsSync(config.codex_config);
+        try {
+            original = existed ? readFileSync(config.codex_config) : new Uint8Array();
+            originalMode = existed
+                ? statSync(config.codex_config).mode & 0o7777
+                : 0o600;
+        }
+        catch (error) {
+            throw new CPACError(`cannot read Codex config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const catalogPath = join(config.state_dir, "codex-models.json");
+    const injected = buildCodexConfig(original, config.cpa_url, config.api_key_env, catalogPath);
+    const catalog = await fetchCatalog(config.cpa_url, apiKey);
+    const stateDirExisted = existsSync(config.state_dir);
+    if (!state &&
+        STATE_FILES.some((name) => existsSync(join(config.state_dir, name)))) {
+        throw new CPACError("state_dir contains CPAC files without a valid state; refusing to overwrite them");
+    }
+    mkdirSync(config.state_dir, { recursive: true, mode: 0o700 });
+    if (!stateDirExisted)
+        chmodSync(config.state_dir, 0o700);
+    if (state) {
+        atomicWrite(catalogPath, catalog.bytes);
+        atomicWrite(config.codex_config, injected, originalMode);
+    }
+    else {
+        let configWritten = false;
+        try {
+            if (existed)
+                atomicWrite(join(config.state_dir, "config.toml.backup"), original);
+            atomicWrite(catalogPath, catalog.bytes);
+            atomicWrite(config.codex_config, injected, originalMode);
+            configWritten = true;
+            atomicWrite(join(config.state_dir, "state.json"), Buffer.from(`${JSON.stringify({
+                config_path: config.codex_config,
+                config_existed: existed,
+                config_mode: originalMode,
+            }, null, 2)}\n`));
+        }
+        catch (error) {
+            if (configWritten) {
+                try {
+                    if (existed)
+                        atomicWrite(config.codex_config, original, originalMode);
+                    else
+                        rmSync(config.codex_config, { force: true });
+                }
+                catch (rollbackError) {
+                    throw new CPACError(`injection failed and config rollback failed; backup retained in ${config.state_dir}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+                }
+            }
+            try {
+                cleanupStateFiles(config.state_dir);
+            }
+            catch (cleanupError) {
+                throw new CPACError(`injection failed and state cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+            }
+            throw error;
+        }
+    }
+    console.log(`Injected ${catalog.modelCount} CPA models into ${config.codex_config}`);
+}
+export function restore(config) {
+    const state = readState(config.state_dir);
+    if (!state)
+        throw new CPACError("no active CPAC injection");
+    const original = originalBytes(config.state_dir, state, config.codex_config);
+    if (state.config_existed)
+        atomicWrite(config.codex_config, original, state.config_mode);
+    else
+        rmSync(config.codex_config, { force: true });
+    try {
+        cleanupStateFiles(config.state_dir);
+    }
+    catch (error) {
+        throw new CPACError(`config restored, but state cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    console.log(`Restored ${config.codex_config}`);
+}
+export function status(config) {
+    const state = readState(config.state_dir);
+    if (!state) {
+        console.log("native");
+        return 1;
+    }
+    originalBytes(config.state_dir, state, config.codex_config);
+    if (!existsSync(config.codex_config)) {
+        console.log(`injected (config missing: ${config.codex_config})`);
+        return 2;
+    }
+    const digest = createHash("sha256")
+        .update(readFileSync(config.codex_config))
+        .digest("hex")
+        .slice(0, 12);
+    console.log(`injected: ${config.codex_config} sha256=${digest}`);
+    return 0;
+}
+function claudeBaseUrl(cpaUrl) {
+    return cpaUrl.replace(/\/v1$/, "");
+}
+async function promptSecret(name) {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        throw new CPACError(`environment variable ${name} is not set; run: export ${name}="..."`);
+    }
+    process.stderr.write(`Enter ${name}: `);
+    const silent = new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+    const prompt = createInterface({
+        input: process.stdin,
+        output: silent,
+        terminal: true,
+    });
+    try {
+        const value = (await prompt.question("")).trim();
+        process.stderr.write("\n");
+        if (!value)
+            throw new CPACError(`${name} must not be empty`);
+        return value;
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function resolveApiKey(name) {
+    return process.env[name]?.trim() || (await promptSecret(name));
+}
+function shellProfile() {
+    const shell = parse(process.env.SHELL || "").base;
+    if (shell === "zsh")
+        return join(homedir(), ".zshrc");
+    if (shell === "bash")
+        return join(homedir(), process.platform === "darwin" ? ".bash_profile" : ".bashrc");
+    if (["sh", "dash", "ksh"].includes(shell))
+        return join(homedir(), ".profile");
+    throw new CPACError(`unsupported shell ${shell || "unknown"}; run: export CPA_API_KEY="..."`);
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+export function saveApiKeyExport(profile, name, apiKey) {
+    const start = `# >>> CPAC ${name} >>>`;
+    const end = `# <<< CPAC ${name} <<<`;
+    const block = `${start}\nexport ${name}=${shellQuote(apiKey)}\n${end}`;
+    let content = existsSync(profile) ? readFileSync(profile, "utf8") : "";
+    const managed = new RegExp(`${start.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+    content = managed.test(content)
+        ? content.replace(managed, block)
+        : `${content}${content && !content.endsWith("\n") ? "\n" : ""}${block}\n`;
+    const mode = existsSync(profile) ? statSync(profile).mode & 0o7777 : 0o600;
+    atomicWrite(profile, Buffer.from(content), mode);
+}
+async function guide(config) {
+    console.log(`CPA Companion\n\nCPA: ${config.cpa_url}\nCPA_API_KEY: ${process.env[config.api_key_env]?.trim() ? "configured" : "not configured"}\n\nCommands:\n  cpac claude [args...]  Launch Claude Code through CPA\n  cpac inject            Inject CPA into Codex\n  cpac status            Show Codex injection status\n  cpac restore           Restore the original Codex config\n  cpac --help            Show command usage`);
+    if (process.env[config.api_key_env]?.trim())
+        return 0;
+    const apiKey = await promptSecret(config.api_key_env);
+    const profile = shellProfile();
+    saveApiKeyExport(profile, config.api_key_env, apiKey);
+    process.env[config.api_key_env] = apiKey;
+    console.log(`\nSaved ${config.api_key_env} to ${profile}. Open a new terminal or run:\n  source ${profile}`);
+    return 0;
+}
+export async function runClaude(config, args, executable = "claude") {
+    const apiKey = await resolveApiKey(config.api_key_env);
+    const env = {
+        ...process.env,
+        ANTHROPIC_BASE_URL: claudeBaseUrl(config.cpa_url),
+        ANTHROPIC_AUTH_TOKEN: apiKey,
+    };
+    delete env.ANTHROPIC_API_KEY;
+    delete env.CLAUDE_CODE_USE_ANTHROPIC_AWS;
+    delete env.CLAUDE_CODE_USE_BEDROCK;
+    delete env.CLAUDE_CODE_USE_FOUNDRY;
+    delete env.CLAUDE_CODE_USE_VERTEX;
+    return await new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { env, stdio: "inherit" });
+        child.once("error", (error) => {
+            reject(new CPACError(error instanceof Error && "code" in error && error.code === "ENOENT"
+                ? `${executable} not found`
+                : `cannot start ${executable}: ${error.message}`));
+        });
+        child.once("close", (code) => resolve(code ?? 1));
+    });
+}
+function usage() {
+    return [
+        "Usage: cpac",
+        "       cpac <inject|status|restore> [--config PATH]",
+        "       cpac claude [--config PATH] [--] [claude args...]",
+    ].join("\n");
+}
+function parseArgs(args) {
+    if (args.length === 0) {
+        return { command: "guide", configPath: defaultConfigPath() };
+    }
+    if (args[0] === "claude") {
+        let configPath = defaultConfigPath();
+        let index = 1;
+        if (args[index] === "--config") {
+            const value = args[++index];
+            if (!value)
+                throw new CPACError("--config requires a path");
+            configPath = resolve(expandUserPath(value));
+            index += 1;
+        }
+        if (args[index] === "--")
+            index += 1;
+        return { command: "claude", configPath, args: args.slice(index) };
+    }
+    if (args.includes("-h") || args.includes("--help")) {
+        console.log(usage());
+        return null;
+    }
+    let configPath = defaultConfigPath();
+    const positional = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--config") {
+            const value = args[++index];
+            if (!value)
+                throw new CPACError("--config requires a path");
+            configPath = resolve(expandUserPath(value));
+        }
+        else if (args[index].startsWith("-")) {
+            throw new CPACError(`unknown option: ${args[index]}`);
+        }
+        else
+            positional.push(args[index]);
+    }
+    if (positional.length !== 1 ||
+        !["inject", "status", "restore"].includes(positional[0])) {
+        throw new CPACError(usage());
+    }
+    return {
+        command: positional[0],
+        configPath,
+    };
+}
+export async function main(args = process.argv.slice(2)) {
+    try {
+        const parsed = parseArgs(args);
+        if (!parsed)
+            return 0;
+        const config = loadConfig(parsed.configPath, true);
+        if (parsed.command === "guide")
+            return await guide(config);
+        if (parsed.command === "claude")
+            return await runClaude(config, parsed.args);
+        if (parsed.command === "inject")
+            await inject(config);
+        else if (parsed.command === "restore")
+            restore(config);
+        else
+            return status(config);
+        return 0;
+    }
+    catch (error) {
+        console.error(`cpac: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return import.meta.url === pathToFileURL(entry).href;
+    }
+}
+if (isMainModule())
+    process.exitCode = await main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@yhong91/cpac",
+  "version": "0.1.0",
+  "description": "Connect Codex and Claude Code to a remote CLIProxyAPI gateway",
+  "type": "module",
+  "bin": {
+    "cpac": "dist/cpac.js"
+  },
+  "files": [
+    "dist/cpac.js",
+    "cpac.example.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yhong91/cpac.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yhong91/cpac/issues"
+  },
+  "homepage": "https://github.com/yhong91/cpac#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "node -e \"for (const d of ['dist','dist-test']) require('fs').rmSync(d,{recursive:true,force:true})\"",
+    "build": "npm run clean --if-present && tsc -p tsconfig.build.json && node -e \"const fs=require('fs');const p='dist/cpac.js';const s=fs.readFileSync(p,'utf8');if(!s.startsWith('#!'))fs.writeFileSync(p,'#!/usr/bin/env node\\n'+s);try{fs.chmodSync(p,0o755)}catch{}\"",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "check:pi": "tsc -p tsconfig.pi.json --noEmit",
+    "test": "npm run clean && tsc -p tsconfig.test.json && node --test --test-reporter=spec dist-test/cpac.test.js",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@types/node": "^22.13.10",
+    "typescript": "~5.8.2"
+  },
+  "license": "MIT"
+}