codexpanel 0.0.1 → 0.1.1

package/README.md

@@ -0,0 +1,131 @@
+# codexpanel
+
+[中文版本](README.zh.md)
+
+codexpanel is a mobile control plane for managing local Codex work from a phone. It provides a Next.js web console, relay service, desktop agent, PostgreSQL-backed durable storage, shared protocol package, and reusable UI package in one monorepo.
+
+## Workspace
+
+- `apps/web`: Next.js marketing homepage, phone console at `/console/`, plus static admin, desktop setup migration, and project docs
+- `apps/relay`: HTTP/SSE/WSS relay service, PostgreSQL/SQLite storage, and device onboarding scripts
+- `apps/agent`: desktop-side agent entrypoint
+- `packages/protocol`: shared schemas and transport helpers
+- `packages/codex-app-server`: Codex app-server connector bindings
+- `packages/ui`: shared React UI primitives
+
+Human reference files, local databases, deployment bundles, server handoff notes, and old demo artifacts live outside the production tree in `files_for_human/` and are ignored by Git.
+
+## Commands
+
+```powershell
+npm run check
+npm run build
+npm run smoke:storage
+npm run release:local
+npm run verify:release
+npm run test:e2e
+```
+
+## Desktop agent install
+
+The public npm entrypoint is the primary one-line installer for Windows desktop agents:
+
+```powershell
+npx -y codexpanel
+```
+
+By default it connects to production at `https://codexpanel.com`. The installer first downloads and verifies the desktop resources, then asks the user to press Enter before opening the browser sign-in and device binding flow. After binding succeeds it installs or updates the desktop agent under `%LOCALAPPDATA%\CodexPanelAgent`, starts the agent, and opens a local status panel on `127.0.0.1` with a dynamic free port.
+
+Use `--server` to target another relay:
+
+```powershell
+npx -y codexpanel --server test
+npx -y codexpanel --server local
+npx -y codexpanel --server https://example.com
+```
+
+`--server test` uses `https://jd.6a.gs`. `--server local` dynamically finds a free local relay port instead of assuming `4871`. A full URL connects to a self-hosted relay. Useful options include `--device-name`, `--workspace`, `--terminal-login`, `--token-login`, `--no-browser`, `--no-autostart`, `--no-tunnel`, `--dry-run`, and `--print-command`.
+
+For terminal token login, open the printed `/desktop/setup?flowId=...` link, sign in, click the one-time terminal token button, then run `npx -y codexpanel login --token-login` and paste the token. The token is scoped to the current setup flow and expires quickly.
+
+Desktop setup no longer uses setup codes as an authentication mechanism. The browser flow uses a signed-in user session and the installed agent receives a long-lived device token. The server stores only the token hash.
+
+See [docs/desktop-npx-install-flow.md](docs/desktop-npx-install-flow.md) for the full Chinese explanation of the desktop npx install and binding flow.
+
+## Auth
+
+Web/admin login uses a session cookie. Configure at least one of these before exposing a relay:
+
+```env
+CODEXPANEL_ADMIN_USERNAME=admin
+CODEXPANEL_ADMIN_PASSWORD=change_me
+CODEXPANEL_SESSION_SECRET=long_random_secret
+CODEXPANEL_LOGIN_MAX_ATTEMPTS=8
+CODEXPANEL_LOGIN_WINDOW_MS=900000
+CODEXPANEL_LOGIN_LOCKOUT_MS=900000
+CODEXPANEL_REGISTRATION_ENABLED=true
+```
+
+Desktop setup uses browser login binding or terminal username/password/token login. Extra users can be provided with `CODEXPANEL_USERS_JSON` using `username`, `password`, `userId`, `role`, and `name`.
+
+`CODEXPANEL_REGISTRATION_ENABLED=true` opens self-service web registration and is the current default. New users are stored in the existing relay users table with PBKDF2 password hashes and receive `CODEXPANEL_REGISTRATION_DEFAULT_ROLE` (`operator` or `viewer`, default `operator`). Set it to `false` if you need to close public onboarding again.
+
+## First-batch user operations
+
+Use `/admin.html` with an admin session for first-batch testing:
+
+- Enable/disable users, change roles, and reset passwords. These actions invalidate existing local-user sessions.
+- Recharge, gift, or deduct balance through the wallet adjustment action. Every change requires an idempotency key and is recorded in the user wallet ledger; do not edit `balance` directly.
+- Grant, renew, or revoke monthly cards. Device quota is derived server-side from the user entitlement.
+- Bind devices to users or disable devices from the admin device table. Ordinary users cannot operate another user's device, and disabled devices are blocked for non-admin operation.
+
+Rollback for a test user is done by disabling the user, revoking the monthly card, reversing wallet changes with an opposite ledger entry, and disabling or rebinding their devices. Recent audit events are visible from `/api/log` for admin sessions.
+
+## Web entrypoints
+
+- `/`: public CodexPanel homepage.
+- `/console/`: mobile control console and PWA start URL.
+- `/desktop/setup`: browser sign-in and desktop device binding flow.
+- `/device.html`: migration page that points users to `npx -y codexpanel`.
+- `/admin.html` and `/project.html`: admin and product documentation pages.
+
+## Storage and deployment
+
+The relay uses `CODEXPANEL_DATABASE_URL` or `DATABASE_URL` for PostgreSQL. If neither is set, it falls back to the local SQLite file at `CODEXPANEL_DB_FILE` for development only. Production startup rejects accidental SQLite fallback unless `CODEXPANEL_ALLOW_SQLITE_IN_PRODUCTION=true` is explicitly set for an emergency.
+
+`npm run smoke:storage` always verifies the SQLite development fallback and the production guard. To verify the PostgreSQL path, set `CODEXPANEL_STORAGE_SMOKE_DATABASE_URL` to a disposable PostgreSQL database URL before running it; the smoke test rewrites its storage tables.
+
+`docker-compose.yml` starts PostgreSQL and the relay together. The auto-deploy script pulls the configured branch, rebuilds Docker Compose, and waits for `/api/health` before declaring the update complete.
+
+`jd.6a.gs` polls GitHub `main` and auto-deploys for testing. Production at
+`codexpanel.com` never polls GitHub; after test approval, release an exact
+GitHub SHA manually:
+
+```powershell
+npm run release:production
+```
+
+For the local Docker release loop:
+
+```powershell
+npm run release:local
+```
+
+For an already running relay, verify deployment, storage, and git sha evidence:
+
+```powershell
+npm run verify:release
+```
+
+## Architecture guardrails
+
+Read [docs/CTO_ARCHITECTURE_DIRECTIVE.md](docs/CTO_ARCHITECTURE_DIRECTIVE.md) before changing Next.js, relay, storage, deployment, auth, protocol, or agent behavior.
+
+- API compatibility is tracked in [docs/api-compatibility-matrix.md](docs/api-compatibility-matrix.md).
+- `npm run check` runs `npm run scan:encoding` before workspace checks.
+- Storage code lives under `apps/relay/src/storage/`; UI code must not import backend or database modules.
+
+See [docs/git-workflow.md](docs/git-workflow.md) for the day-to-day Git and GitHub workflow.
+See [docs/development-release-workflow.md](docs/development-release-workflow.md)
+for the two-computer release process and
+[docs/production-server-usage.md](docs/production-server-usage.md) for server operations.

package/README.zh.md

@@ -0,0 +1,126 @@
+# codexpanel
+
+[English version](README.md)
+
+codexpanel 是一个面向 Codex 本地工作的移动控制平面。它把手机端控制台、relay 服务、电脑端 agent、PostgreSQL 持久化存储、共享协议包和复用 UI 包放在同一个 monorepo 中，方便统一开发、部署和审计。
+
+## 工作区
+
+- `apps/web`：Next.js 首页、手机控制台 `/console/`，以及静态 admin、电脑端安装迁移页和项目文档。
+- `apps/relay`：HTTP/SSE/WSS relay 服务、PostgreSQL/SQLite 存储、设备接入脚本。
+- `apps/agent`：电脑端 agent 入口。
+- `packages/protocol`：共享 schema 和传输 helper。
+- `packages/codex-app-server`：Codex app-server 连接绑定。
+- `packages/ui`：共享 React UI 基础组件。
+
+人工参考文件、本地数据库、部署包、服务器交接说明和旧 demo 产物放在 `files_for_human/`，该目录不属于生产树并被 Git 忽略。
+
+## 常用命令
+
+```powershell
+npm run check
+npm run build
+npm run smoke:storage
+npm run release:local
+npm run verify:release
+npm run test:e2e
+```
+
+## 电脑端 agent 安装
+
+Windows 电脑端的公开 npm 入口是一条命令：
+
+```powershell
+npx -y codexpanel
+```
+
+默认连接正式生产域 `https://codexpanel.com`。安装器会先下载并校验电脑端资源，然后提示用户按 Enter 打开浏览器登录和绑定设备。绑定成功后，安装器会把 agent 安装或更新到 `%LOCALAPPDATA%\CodexPanelAgent`，启动 agent，并在 `127.0.0.1` 的动态可用端口打开本地状态面板。
+
+切换 relay：
+
+```powershell
+npx -y codexpanel --server test
+npx -y codexpanel --server local
+npx -y codexpanel --server https://example.com
+```
+
+`--server test` 使用 `https://jd.6a.gs`。`--server local` 会动态寻找可用本地端口，不再假定 `4871`。完整 URL 会连接自部署 relay。常用参数包括 `--device-name`、`--workspace`、`--terminal-login`、`--token-login`、`--no-browser`、`--no-autostart`、`--no-tunnel`、`--dry-run` 和 `--print-command`。
+
+终端 token 登录的使用方式是：打开安装器打印的 `/desktop/setup?flowId=...` 链接，在浏览器登录后点击一次性终端 token 按钮，再运行 `npx -y codexpanel login --token-login` 并粘贴 token。该 token 只绑定当前安装流，过期很快。
+
+电脑端安装不再使用访问码。浏览器流程使用已登录用户 session 审批绑定，安装后的 agent 使用长期 device token；服务端只保存 token hash，不保存明文 token。
+
+完整中文安装与工作原理说明见 [docs/desktop-npx-install-flow.md](docs/desktop-npx-install-flow.md)。
+
+## 认证
+
+Web/admin 登录使用 session cookie。公网暴露 relay 前至少配置以下变量：
+
+```env
+CODEXPANEL_ADMIN_USERNAME=admin
+CODEXPANEL_ADMIN_PASSWORD=change_me
+CODEXPANEL_SESSION_SECRET=long_random_secret
+CODEXPANEL_LOGIN_MAX_ATTEMPTS=8
+CODEXPANEL_LOGIN_WINDOW_MS=900000
+CODEXPANEL_LOGIN_LOCKOUT_MS=900000
+CODEXPANEL_REGISTRATION_ENABLED=true
+```
+
+电脑端 setup 支持浏览器登录绑定、终端用户名密码登录和终端一次性 token 登录。额外用户可以通过 `CODEXPANEL_USERS_JSON` 提供，字段包括 `username`、`password`、`userId`、`role` 和 `name`。
+
+`CODEXPANEL_REGISTRATION_ENABLED=true` 会打开自助注册，目前默认开启。新用户写入 relay 的 users 表，密码使用 PBKDF2 hash，角色来自 `CODEXPANEL_REGISTRATION_DEFAULT_ROLE`，默认 `operator`。需要关闭公开接入时设为 `false`。
+
+## 第一批用户运营
+
+使用 admin session 打开 `/admin.html` 进行第一批测试：
+
+- 启用/禁用用户、调整角色、重置密码。这些操作会让对应本地用户旧 session 失效。
+- 通过钱包调整操作充值、赠送或扣减余额。每次变更都需要幂等键，并写入钱包流水；不要直接改 `balance`。
+- 开通、续期或撤销月卡。设备额度由服务端根据用户权益计算。
+- 在 admin 设备表中绑定设备到用户，或禁用设备。普通用户不能操作他人设备，非 admin 不能操作禁用设备。
+
+测试用户回滚方式是禁用用户、撤销月卡、用反向流水抵消钱包变化，并禁用或重新绑定设备。admin session 可从 `/api/log` 查看最近审计事件。
+
+## Web 入口
+
+- `/`：公开 CodexPanel 首页。
+- `/console/`：手机控制台和 PWA start URL。
+- `/desktop/setup`：浏览器登录和电脑设备绑定流程。
+- `/device.html`：迁移页，引导用户改用 `npx -y codexpanel`。
+- `/admin.html` 和 `/project.html`：管理后台和产品文档页。
+
+## 存储与部署
+
+relay 使用 `CODEXPANEL_DATABASE_URL` 或 `DATABASE_URL` 连接 PostgreSQL。未配置时只在开发环境回退到本地 SQLite 文件 `CODEXPANEL_DB_FILE`。生产环境会拒绝意外 SQLite fallback，除非显式设置 `CODEXPANEL_ALLOW_SQLITE_IN_PRODUCTION=true` 作为紧急兜底。
+
+`npm run smoke:storage` 始终验证 SQLite 开发 fallback 和生产 guard。如需验证 PostgreSQL 路径，先把 `CODEXPANEL_STORAGE_SMOKE_DATABASE_URL` 指向一次性 PostgreSQL 数据库；该 smoke 会重写它的存储表。
+
+`docker-compose.yml` 会同时启动 PostgreSQL 和 relay。自动部署脚本会拉取配置分支、重建 Docker Compose，并等待 `/api/health` 通过后宣布更新完成。
+
+`jd.6a.gs` 会轮询 GitHub `main` 并自动部署测试环境。生产 `codexpanel.com` 不轮询 GitHub；测试确认后，必须人工发布 GitHub 上明确的 SHA：
+
+```powershell
+npm run release:production
+```
+
+本地 Docker 发布循环：
+
+```powershell
+npm run release:local
+```
+
+已运行 relay 的发布、存储和 git sha 证据验证：
+
+```powershell
+npm run verify:release
+```
+
+## 架构护栏
+
+修改 Next.js、relay、存储、部署、认证、协议或 agent 行为前，请先阅读 [docs/CTO_ARCHITECTURE_DIRECTIVE.md](docs/CTO_ARCHITECTURE_DIRECTIVE.md)。
+
+- API 兼容性记录在 [docs/api-compatibility-matrix.md](docs/api-compatibility-matrix.md)，中文版本见 [docs/api-compatibility-matrix.zh.md](docs/api-compatibility-matrix.zh.md)。
+- `npm run check` 会先运行 `npm run scan:encoding`，再检查各 workspace。
+- 存储代码位于 `apps/relay/src/storage/`；UI 代码不得导入后端或数据库模块。
+
+日常 Git/GitHub 流程见 [docs/git-workflow.md](docs/git-workflow.md)，中文版本见 [docs/git-workflow.zh.md](docs/git-workflow.zh.md)。双电脑发布流程见 [docs/development-release-workflow.md](docs/development-release-workflow.md)。服务器操作见 [docs/production-server-usage.md](docs/production-server-usage.md)。