codeharbor 0.1.0 → 0.1.2

package/.env.example

@@ -0,0 +1,78 @@
+MATRIX_HOMESERVER=https://matrix.biglone.tech
+MATRIX_USER_ID=@codeharbor-bot:example.com
+MATRIX_ACCESS_TOKEN=
+
+# Optional explicit trigger in groups; can be empty to disable prefix trigger.
+MATRIX_COMMAND_PREFIX=!code
+
+CODEX_BIN=codex
+CODEX_MODEL=
+CODEX_WORKDIR=/Users/biglone/workspace
+CODEX_DANGEROUS_BYPASS=false
+CODEX_EXEC_TIMEOUT_MS=600000
+CODEX_SANDBOX_MODE=
+CODEX_APPROVAL_POLICY=
+# Optional extra CLI args, space separated (example: --search --no-alt-screen)
+CODEX_EXTRA_ARGS=
+# Optional JSON object for additional environment variables passed to codex child process.
+CODEX_EXTRA_ENV_JSON=
+
+# SQLite state database path.
+STATE_DB_PATH=data/state.db
+# Legacy JSON path for one-time migration import.
+STATE_PATH=data/state.json
+
+MAX_PROCESSED_EVENTS_PER_SESSION=200
+MAX_SESSION_AGE_DAYS=30
+MAX_SESSIONS=5000
+REPLY_CHUNK_SIZE=3500
+
+MATRIX_PROGRESS_UPDATES=true
+MATRIX_PROGRESS_MIN_INTERVAL_MS=2500
+MATRIX_TYPING_TIMEOUT_MS=10000
+SESSION_ACTIVE_WINDOW_MINUTES=20
+
+# Group trigger defaults.
+GROUP_TRIGGER_ALLOW_MENTION=true
+GROUP_TRIGGER_ALLOW_REPLY=true
+GROUP_TRIGGER_ALLOW_ACTIVE_WINDOW=true
+GROUP_TRIGGER_ALLOW_PREFIX=true
+
+# Optional room-level trigger overrides (JSON object).
+# ROOM_TRIGGER_POLICY_JSON={"!room:example.com":{"allowMention":true,"allowReply":true,"allowActiveWindow":false,"allowPrefix":false}}
+ROOM_TRIGGER_POLICY_JSON=
+
+# Rate limiting / anti-abuse.
+RATE_LIMIT_WINDOW_SECONDS=60
+RATE_LIMIT_MAX_REQUESTS_PER_USER=20
+RATE_LIMIT_MAX_REQUESTS_PER_ROOM=120
+RATE_LIMIT_MAX_CONCURRENT_GLOBAL=8
+RATE_LIMIT_MAX_CONCURRENT_PER_USER=1
+RATE_LIMIT_MAX_CONCURRENT_PER_ROOM=4
+
+# CLI compatibility mode (IM shell approximation of codex CLI).
+CLI_COMPAT_MODE=false
+CLI_COMPAT_PASSTHROUGH_EVENTS=true
+CLI_COMPAT_PRESERVE_WHITESPACE=true
+CLI_COMPAT_DISABLE_REPLY_CHUNK_SPLIT=false
+CLI_COMPAT_PROGRESS_THROTTLE_MS=300
+CLI_COMPAT_FETCH_MEDIA=true
+# Optional JSONL output path for executed prompt recording (for replay benchmarking).
+CLI_COMPAT_RECORD_PATH=
+
+DOCTOR_HTTP_TIMEOUT_MS=10000
+
+# Admin API server (for config UI/backend).
+ADMIN_BIND_HOST=127.0.0.1
+ADMIN_PORT=8787
+# Token protection for /api/admin/* endpoints.
+# Strongly recommended for any non-localhost access.
+# Required when exposing admin via reverse proxy/tunnel/public domain.
+ADMIN_TOKEN=
+# Optional IP allowlist (comma-separated, for example: 127.0.0.1,192.168.1.10).
+ADMIN_IP_ALLOWLIST=
+# Optional browser origin allowlist for CORS (comma-separated).
+# Example: https://admin.example.com,https://ops.example.com
+ADMIN_ALLOWED_ORIGINS=
+
+LOG_LEVEL=info

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
 
@@ -49,6 +49,44 @@ Install globally from npm (after publish):
 npm install -g codeharbor
 ```
 
+Linux one-command install (creates `/opt/codeharbor`, sets ownership, installs latest package):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/biglone/CodeHarbor/main/scripts/install-linux.sh | bash
+```
+
+Linux easy mode (install + write `.env` + enable/start systemd in one run):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/biglone/CodeHarbor/main/scripts/install-linux-easy.sh | bash -s -- \
+  --matrix-homeserver https://matrix.example.com \
+  --matrix-user-id @bot:example.com \
+  --matrix-access-token 'your-token'
+```
+
+Enable Admin service at install time:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/biglone/CodeHarbor/main/scripts/install-linux-easy.sh | bash -s -- \
+  --matrix-homeserver https://matrix.example.com \
+  --matrix-user-id @bot:example.com \
+  --matrix-access-token 'your-token' \
+  --enable-admin-service \
+  --admin-token 'replace-with-strong-token'
+```
+
+Run local script with custom options:
+
+```bash
+./scripts/install-linux.sh --app-dir /srv/codeharbor --package codeharbor@0.1.1 --init
+```
+
+Runtime home behavior:
+
+- By default, all `codeharbor` commands use `/opt/codeharbor` for `.env` and relative data paths.
+- No manual `cd /opt/codeharbor` is required after installation.
+- To use a custom runtime directory, set `CODEHARBOR_HOME` (for example `export CODEHARBOR_HOME=/srv/codeharbor`).
+
 Install directly from GitHub:
 
 ```bash
@@ -62,6 +100,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 +171,8 @@ npm install
 2. Configure environment:
 
 ```bash
-cp .env.example .env
+export CODEHARBOR_HOME="$(pwd)"
+codeharbor init
 ```
 
 Required values:
@@ -87,6 +184,7 @@ Required values:
 3. Run in dev mode:
 
 ```bash
+export CODEHARBOR_HOME="$(pwd)"
 npm run dev
 ```
 
@@ -94,13 +192,142 @@ npm run dev
 
 ```bash
 npm run build
+export CODEHARBOR_HOME="$(pwd)"
 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/install-linux.sh`: Linux bootstrap installer (creates runtime dir + installs npm package)
+- `scripts/install-linux-easy.sh`: one-shot Linux install + config + systemd auto-start
+- `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