@bitkyc08/opencodex 2.5.7-preview.20260627 → 2.6.0

package/README.ko.md

@@ -34,7 +34,7 @@ Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provi
 
 ```bash
 # 설치 (Bun 런타임이 자동으로 번들됩니다 — Node 18+ 만 있으면 됩니다)
-npm install -g @bitkyc08/opencodex      # 또는: bun install -g @bitkyc08/opencodex
+npm install -g @bitkyc08/opencodex
 
 # 대화형 설정 (config 작성 + Codex 주입 + 자동 시작 shim 설치 선택)
 ocx init
@@ -134,7 +134,7 @@ ocx logout <provider>          # 저장된 로그인 정보 삭제
 ocx gui                        # 웹 대시보드 열기
 ocx codex-shim install         # codex 실행 시 `ocx ensure` 실행
 ocx service <install|start|stop|status|uninstall>   # 백그라운드 서비스 (launchd/systemd/schtasks)
-ocx update                     # opencodex를 최신 버전으로 업데이트
+ocx update [--tag preview]     # opencodex 업데이트; preview 설치는 @preview 유지
 ```
 
 ### 자동 시작: service vs shim
@@ -143,7 +143,7 @@ opencodex에는 프록시를 자동 시작하는 두 가지 방법이 있습니
 
 | | `ocx service install` | `ocx codex-shim install` |
 |---|---|---|
-| **방식** | OS 서비스 관리자 (launchd / systemd / schtasks) | `codex` 바이너리를 래퍼 스크립트로 교체 |
+| **방식** | OS 서비스 관리자 (launchd / systemd / schtasks) | `codex` 스크립트 런처를 래핑하며 실제 `codex.exe`는 건드리지 않음 |
 | **시점** | 로그인 후 항상 실행 | 온디맨드 — `codex` 실행 시 `ocx ensure` 실행 |
 | **재시작** | 크래시 시 자동 재시작 | `codex` 호출마다 한 번 시작 |
 | **Codex 업데이트** | 영향 없음 | `ocx codex-shim install` 또는 `ocx update` 시 복구 |
@@ -155,11 +155,11 @@ shim 자동 시작은 기본으로 켜져 있으며 GUI 대시보드에서 끌
 
 ### 삭제
 
-npm/bun 패키지를 지우기 전에 로컬 상태를 먼저 정리하세요:
+npm 패키지를 지우기 전에 로컬 상태를 먼저 정리하세요:
 
 ```bash
 ocx uninstall
-npm uninstall -g @bitkyc08/opencodex   # 또는: bun remove -g @bitkyc08/opencodex
+npm uninstall -g @bitkyc08/opencodex
 ```
 
 `ocx uninstall`은 프록시 중지, 설치된 service 제거, Codex shim 제거, Codex config/catalog/history
@@ -219,7 +219,8 @@ export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
 ocx start
 ```
 
-비루프백 바인딩 시 이 환경 변수가 없으면 프록시 시작이 거부됩니다.
+비루프백 바인딩 시 이 환경 변수가 없으면 프록시 시작이 거부됩니다. LAN 접근용 백그라운드
+서비스를 설치할 때도 같은 셸에서 이 변수를 먼저 설정한 뒤 `ocx service install`을 실행해야 합니다.
 클라이언트(스크립트, 원격 머신)는 모든 요청에 토큰을 포함해야 합니다:
 
 ```
@@ -247,6 +248,16 @@ bun run dev          # dev 모드로 프록시 시작
 bun x tsc --noEmit   # 타입 체크
 ```
 
+`bun run dev`는 프록시 API(`/healthz`, `/v1/responses`, `/api/*`)만 시작합니다. 패키징된
+대시보드 `/`를 함께 서빙하지 않습니다. 대시보드는 설치된 `ocx gui`를 쓰거나, 프론트엔드를
+수정할 때는 별도로 실행하세요:
+
+```bash
+cd gui
+bun install
+bun dev
+```
+
 **[기여하기](https://lidge-jun.github.io/opencodex/ko/contributing/)** 를 참고하세요.
 
 ## 면책 조항

package/README.md

@@ -58,7 +58,7 @@ Requires [Node](https://nodejs.org) 18+. The Bun runtime is bundled automaticall
 
 ```bash
 # Install (bundles the Bun runtime automatically — only Node 18+ required)
-npm install -g @bitkyc08/opencodex      # or: bun install -g @bitkyc08/opencodex
+npm install -g @bitkyc08/opencodex
 
 # Interactive setup (writes config, injects into Codex, and offers autostart shim install)
 ocx init
@@ -197,7 +197,7 @@ ocx login <xai|anthropic|kimi> # OAuth login
 ocx logout <provider>          # remove a stored login
 ocx gui                        # open the web dashboard
 ocx service <install|start|stop|status|uninstall>   # background service (launchd/systemd/schtasks)
-ocx update                     # update opencodex to the latest published version
+ocx update [--tag preview]     # update opencodex; preview installs stay on @preview
 ```
 
 ### Autostart: service vs shim
@@ -206,7 +206,7 @@ opencodex has two ways to auto-start the proxy:
 
 | | `ocx service install` | `ocx codex-shim install` |
 |---|---|---|
-| **How** | OS service manager (launchd / systemd / schtasks) | Replaces the `codex` binary with a wrapper script |
+| **How** | OS service manager (launchd / systemd / schtasks) | Wraps script launchers for `codex`; real `codex.exe` is left untouched |
 | **When** | Always running after login | On-demand — runs `ocx ensure` when `codex` is launched |
 | **Restart** | Auto-restarts on crash | Starts once per `codex` invocation |
 | **Codex updates** | Unaffected | Repairs on next `ocx codex-shim install` or `ocx update` |
@@ -219,11 +219,11 @@ automatically picks another free local port and updates Codex to use it.
 
 ### Uninstall
 
-Before removing the npm/bun package, clean up local state:
+Before removing the npm package, clean up local state:
 
 ```bash
 ocx uninstall
-npm uninstall -g @bitkyc08/opencodex   # or: bun remove -g @bitkyc08/opencodex
+npm uninstall -g @bitkyc08/opencodex
 ```
 
 `ocx uninstall` stops the proxy, removes any installed service, removes the Codex shim, restores
@@ -302,7 +302,9 @@ export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
 ocx start
 ```
 
-The proxy refuses to start without this variable when binding beyond loopback.
+The proxy refuses to start without this variable when binding beyond loopback. If you install a
+background service for LAN access, export the same variable before `ocx service install` so the
+service manager receives it.
 Clients (scripts, remote machines) must include the token in every request:
 
 ```
@@ -338,10 +340,20 @@ Maintainer source-of-truth notes live under [`structure/`](./structure). Histori
 git clone https://github.com/lidge-jun/opencodex.git
 cd opencodex
 bun install
-bun run dev          # start the proxy in dev mode
+bun run dev:proxy    # start the proxy API in dev mode
+bun run dev:gui      # start the dashboard dev server in another terminal
 bun x tsc --noEmit   # typecheck
 ```
 
+`bun run dev` remains an alias for `bun run dev:proxy` for compatibility. In a source checkout,
+the proxy API exposes `/healthz`, `/v1/responses`, and `/api/*`; `GET /` serves the packaged
+dashboard only after `bun run build:gui` has produced `gui/dist`. While hacking on the dashboard,
+run the frontend separately:
+
+```bash
+bun run dev:gui
+```
+
 See **[Contributing](https://lidge-jun.github.io/opencodex/contributing/)**.
 
 ## Disclaimer

package/README.zh-CN.md

@@ -33,7 +33,7 @@ Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provi
 
 ```bash
 # 安装（自动打包 Bun 运行时 —— 只需 Node 18+）
-npm install -g @bitkyc08/opencodex      # 或者: bun install -g @bitkyc08/opencodex
+npm install -g @bitkyc08/opencodex
 
 # 交互式初始化（写入配置 + 注入 Codex）
 ocx init
@@ -126,7 +126,7 @@ ocx logout <provider>          # 移除已保存的登录
 ocx gui                        # 打开 Web 仪表盘
 ocx codex-shim install         # 运行 codex 时自动启动代理
 ocx service <install|start|stop|status|uninstall>   # 后台服务（launchd/systemd/schtasks）
-ocx update                     # 更新到最新版
+ocx update [--tag preview]     # 更新 opencodex；preview 安装保持 @preview
 ```
 
 ### 自动启动：service vs shim
@@ -135,7 +135,7 @@ opencodex 提供两种自动启动代理的方式：
 
 | | `ocx service install` | `ocx codex-shim install` |
 |---|---|---|
-| **方式** | OS 服务管理器（launchd / systemd / schtasks） | 将 `codex` 二进制替换为包装脚本 |
+| **方式** | OS 服务管理器（launchd / systemd / schtasks） | 包装 `codex` 脚本启动器；不会改动真实 `codex.exe` |
 | **时机** | 登录后始终运行 | 按需 — 仅在运行 `codex` 时启动 |
 | **重启** | 崩溃后自动重启 | 每次调用 `codex` 时启动一次 |
 | **Codex 更新** | 不受影响 | 下次运行 `ocx codex-shim install` 或 `ocx update` 时修复 |
@@ -209,6 +209,15 @@ bun run dev          # 以开发模式启动代理
 bun x tsc --noEmit   # 类型检查
 ```
 
+`bun run dev` 只启动代理 API（`/healthz`、`/v1/responses`、`/api/*`）。它不会同时在 `/`
+提供打包后的仪表盘。要打开仪表盘，请使用已安装的 `ocx gui`；如果要开发前端，请单独运行：
+
+```bash
+cd gui
+bun install
+bun dev
+```
+
 参阅 **[贡献指南](https://lidge-jun.github.io/opencodex/zh-cn/contributing/)**。
 
 ## 免责声明

package/bin/ocx.mjs

@@ -10,14 +10,96 @@
  */
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { existsSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+const PKG = "@bitkyc08/opencodex";
 const require = createRequire(import.meta.url);
 const here = dirname(fileURLToPath(import.meta.url));
 const cliPath = join(here, "..", "src", "cli.ts");
 
+function isNodeModulesInstall() {
+  return here.split(/[\\/]/).includes("node_modules");
+}
+
+function isBunGlobalInstall() {
+  return /[\\/]\.bun[\\/]/.test(here);
+}
+
+function npmBin() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function currentPackageVersion() {
+  try {
+    return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version ?? "?";
+  } catch {
+    return "?";
+  }
+}
+
+function updateTag(currentVersion) {
+  const tagIndex = process.argv.indexOf("--tag");
+  if (tagIndex !== -1 && process.argv[tagIndex + 1]) return process.argv[tagIndex + 1];
+  return String(currentVersion).includes("-preview.") ? "preview" : "latest";
+}
+
+function configDir() {
+  return resolve(process.env.OPENCODEX_HOME?.trim() || join(homedir(), ".opencodex"));
+}
+
+function shouldRepairCodexShim() {
+  return existsSync(join(configDir(), "codex-shim.json"));
+}
+
+function repairCodexShimIfNeeded() {
+  if (!shouldRepairCodexShim()) return;
+  const launcher = fileURLToPath(import.meta.url);
+  const res = spawnSync(process.execPath, [launcher, "codex-shim", "install"], {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  if (res.status !== 0) {
+    console.warn(`opencodex: Codex shim repair failed (${res.status ?? "unknown exit"}). Try: ocx codex-shim install`);
+  }
+}
+
+function runNpmSelfUpdate() {
+  const current = currentPackageVersion();
+  const tag = updateTag(current);
+  const npm = npmBin();
+  const latestResult = spawnSync(npm, ["view", `${PKG}@${tag}`, "version"], {
+    encoding: "utf8",
+    timeout: 12000,
+    windowsHide: true,
+  });
+  const latest = latestResult.status === 0 ? latestResult.stdout.trim() : "";
+
+  console.log(`opencodex v${current} (installed via npm, tag ${tag})`);
+  if (latest && latest === current) {
+    console.log(`Already on the latest ${tag} version (v${latest}).`);
+    process.exit(0);
+  }
+
+  console.log(`Updating${latest ? ` to v${latest}` : ""}...\n$ ${npm} install -g ${PKG}@${tag}`);
+  const res = spawnSync(npm, ["install", "-g", `${PKG}@${tag}`], {
+    stdio: "inherit",
+    timeout: 180000,
+    windowsHide: true,
+  });
+  if (res.status === 0) {
+    console.log(`\nUpdated${latest ? ` to v${latest}` : ""}.`);
+    repairCodexShimIfNeeded();
+    console.log("Restart the proxy:  ocx stop && ocx start");
+    console.log("If a background service is installed, refresh its baked path:  ocx service install");
+    process.exit(0);
+  }
+  console.error(`\nUpdate failed (${npm} exit ${res.status ?? "?"}). Try manually:  ${npm} install -g ${PKG}@${tag}`);
+  process.exit(1);
+}
+
 function bunBinDir() {
   // Resolve the `bun` dependency's directory without hardcoding the platform
   // package — npm's os/cpu/libc resolution already picked the right @oven/bun-*.
@@ -73,6 +155,10 @@ function resolveBun() {
   return bin;
 }
 
+if (process.argv[2] === "update" && isNodeModulesInstall() && !isBunGlobalInstall()) {
+  runNpmSelfUpdate();
+}
+
 const bun = resolveBun();
 const res = spawnSync(bun, [cliPath, ...process.argv.slice(2)], { stdio: "inherit" });
 if (res.error) {

package/bin/package-main.mjs

@@ -0,0 +1,9 @@
+export const packageName = "@bitkyc08/opencodex";
+export const cliCommand = "ocx";
+
+export async function loadBunApi() {
+  if (typeof Bun === "undefined") {
+    throw new Error("The opencodex programmatic API requires the Bun runtime. Use `ocx` for the CLI entrypoint.");
+  }
+  return import("../src/index.ts");
+}