codeharbor 0.1.0 → 0.1.1

package/README.md

@@ -37,7 +37,7 @@ Matrix Room -> MatrixChannel -> Orchestrator -> CodexExecutor (codex exec/resume
 
 ## Prerequisites
 
-- Node.js 20+
+- Node.js 22+
 - `codex` CLI installed and authenticated (`codex login`)
 - A Matrix bot user + access token
 
@@ -62,6 +62,64 @@ npm pack
 npm install -g ./codeharbor-<version>.tgz
 ```
 
+## GitHub CI/CD Publish
+
+CodeHarbor supports auto publish to npm from GitHub Actions.
+
+Setup once:
+
+1. Add repository secret `NPM_TOKEN` (npm token with publish permission).
+2. Push to `main` with a publish trigger commit message.
+
+Trigger rules:
+
+- `push` to `main` + commit message includes `[publish-npm]` -> run publish workflow
+- `push` to `main` + commit message includes both `release` and a semver version -> run publish workflow
+  - examples: `release v0.1.1`, `chore: release 0.1.2`
+- `workflow_dispatch` -> manual publish from GitHub Actions UI
+
+The workflow runs `typecheck`, `test`, `test:e2e` (Admin UI Playwright), `build`, `node dist/cli.js --help`, `npm pack --dry-run`, then publishes with:
+
+```bash
+npm publish --access public
+```
+
+If the same package version already exists on npm, publish is skipped automatically.
+
+Release checklist (recommended):
+
+1. Update version in `package.json` (`npm version patch|minor|major`).
+2. Push to `main` with `[publish-npm]` or `release vX.Y.Z` in commit message.
+3. Verify workflow status in GitHub Actions.
+4. Verify package on npm:
+
+```bash
+npm view codeharbor version
+```
+
+Run e2e locally:
+
+```bash
+npm run test:e2e
+```
+
+If your machine has no system Chrome, run:
+
+```bash
+PLAYWRIGHT_USE_SYSTEM_CHROME=false npm run e2e:install
+PLAYWRIGHT_USE_SYSTEM_CHROME=false npm run test:e2e
+```
+
+## Planning Docs
+
+- `REQUIREMENTS.md`: current baseline + next-stage requirements
+- `TASK_LIST.md`: implementation task breakdown and status
+- `docs/CONFIG_UI_DESIGN.md`: configuration UI MVP design
+- `docs/CONFIG_CATALOG.md`: consolidated configuration matrix (required/runtime/UI/effective timing)
+- `docs/ADMIN_STANDALONE_DEPLOY.md`: standalone admin deployment and Cloudflare Tunnel exposure guide
+- `docs/BACKUP_AUTOMATION.md`: scheduled config backup and restore operations
+- `docs/RELEASE.md`: release process and CI/publish policy
+
 ## Quick Start
 
 For local development from source:
@@ -75,7 +133,7 @@ npm install
 2. Configure environment:
 
 ```bash
-cp .env.example .env
+codeharbor init
 ```
 
 Required values:
@@ -97,10 +155,136 @@ npm run build
 node dist/cli.js start
 ```
 
+## Configuration Baseline
+
+Use this layered reference to avoid mixing boot-only and runtime tuning items:
+
+- [`docs/CONFIG_CATALOG.md`](docs/CONFIG_CATALOG.md)
+
+It documents:
+
+- which keys are required vs optional
+- which keys can be edited in Admin UI
+- whether changes are immediate or restart-scoped
+- recommended profiles for local/internal/public deployment
+
 ## Commands
 
+- `codeharbor init`: guided setup for `.env` (supports `--force` to overwrite directly)
 - `codeharbor start`: start service
 - `codeharbor doctor`: check `codex` and Matrix connectivity
+- `codeharbor admin serve`: start admin UI + config API server
+- `codeharbor config export`: export current config snapshot as JSON
+- `codeharbor config import <file>`: import config snapshot JSON (supports `--dry-run`)
+- `scripts/backup-config.sh`: export timestamped snapshot and keep latest N backups
+- `scripts/install-backup-timer.sh`: install/update user-level systemd timer for automatic backups
+- `npm run test:e2e`: run Admin UI end-to-end tests (Playwright)
+
+### Config Backup Script
+
+Create a timestamped snapshot in `backups/config` and keep latest 20 by default:
+
+```bash
+./scripts/backup-config.sh
+```
+
+Custom directory and retention:
+
+```bash
+./scripts/backup-config.sh --dir /var/backups/codeharbor --keep 30
+```
+
+Install/update automatic backup timer:
+
+```bash
+./scripts/install-backup-timer.sh --schedule "*-*-* 03:30:00" --dir /var/backups/codeharbor --keep 30
+```
+
+Full guide:
+
+- [`docs/BACKUP_AUTOMATION.md`](docs/BACKUP_AUTOMATION.md)
+
+## Admin UI And API
+
+Start server:
+
+```bash
+codeharbor admin serve
+```
+
+Optional overrides:
+
+```bash
+codeharbor admin serve --host 127.0.0.1 --port 8787
+```
+
+If you bind Admin to a non-loopback host and `ADMIN_TOKEN` is empty, startup is rejected by default.
+Explicit bypass exists but is not recommended:
+
+```bash
+codeharbor admin serve --host 0.0.0.0 --allow-insecure-no-token
+```
+
+Open these UI routes in browser:
+
+- `/` or `/settings/global`
+- `/settings/rooms`
+- `/health`
+- `/audit`
+
+Main endpoints:
+
+- `GET /api/admin/config/global`
+- `PUT /api/admin/config/global`
+- `GET /api/admin/config/rooms`
+- `GET /api/admin/config/rooms/:roomId`
+- `PUT /api/admin/config/rooms/:roomId`
+- `DELETE /api/admin/config/rooms/:roomId`
+- `GET /api/admin/health`
+- `GET /api/admin/audit?limit=50`
+
+When `ADMIN_TOKEN` is set, requests must include:
+
+```http
+Authorization: Bearer <ADMIN_TOKEN>
+```
+
+Access control options:
+
+- `ADMIN_TOKEN`: require bearer token for `/api/admin/*`
+- `ADMIN_IP_ALLOWLIST`: optional comma-separated client IP whitelist (for example `127.0.0.1,192.168.1.10`)
+- `ADMIN_ALLOWED_ORIGINS`: optional CORS origin allowlist for browser-based cross-origin admin access
+
+Note: `PUT /api/admin/config/global` writes to `.env` and marks changes as restart-required.
+
+### Admin UI Quick Walkthrough
+
+1. Start server: `codeharbor admin serve`.
+2. Open `/settings/global`, set `Admin Token` (if enabled), then click `Save Auth`.
+3. Adjust global fields and click `Save Global Config` (UI shows restart-required warning).
+4. Open `/settings/rooms`, fill `Room ID + Workdir`, then `Save Room`.
+5. Open `/health` to run connectivity checks (`codex` + Matrix).
+6. Open `/audit` to verify config revisions (actor/summary/payload).
+
+## Standalone Admin Deployment
+
+`codeharbor admin serve` can run as an independent service on target servers without browser/desktop.
+Access can come from your local browser through a gateway (for example Cloudflare Tunnel).
+
+See:
+
+- [`docs/ADMIN_STANDALONE_DEPLOY.md`](docs/ADMIN_STANDALONE_DEPLOY.md)
+
+## Startup Preflight
+
+Before `codeharbor start` and `codeharbor doctor`, CodeHarbor runs a preflight check for:
+
+- required Matrix env vars
+- `CODEX_BIN` availability
+- `CODEX_WORKDIR` validity
+- `.env` presence warning
+
+If any check fails, it prints actionable fix commands (for example `codeharbor init`).
 
 ## Message Rules