204 lines
8.5 KiB
Markdown
204 lines
8.5 KiB
Markdown
# Local Debug Workspace
|
|
|
|
The local debug workspace runs the real platform API, run worker, platform_web console, and the development game plugin fixture together. It is for API-backed local proof, not demo-only fallback.
|
|
|
|
## Scope
|
|
|
|
- Platform listens on `http://127.0.0.1:18080` by default.
|
|
- platform_web listens on `http://127.0.0.1:5173` by default and proxies `/api/v1` plus `/healthz` to platform.
|
|
- Run editable source is loaded from `RUN_SOURCE_DIR` / legacy `RUN_REPO_DIR`, defaulting to the ignored nested `./run` checkout.
|
|
- Run source is snapshotted into `.local-debug/run/build-buckets/source/current`; the platform mounts that snapshot read-only into the dedicated `browser-platform-distribution-builder:1.0.0` image, and the local bootstrap worker is built into `.local-debug/run/build-buckets/bootstrap/bin/run` before registering as `run-local-debug`.
|
|
- Disposable state lives under `.local-debug/`.
|
|
- Logs live under `.local-debug/logs/`.
|
|
- PIDs live under `.local-debug/pids/`.
|
|
- Go build cache for local services lives under `.local-debug/go-build-cache/`.
|
|
- The dev plugin fixture is `plugins/examples/dev-game-plugin/manifest.json`.
|
|
|
|
The workflow requires a local Docker daemon for the platform-owned distribution builder. It does not require external cloud services, real game binaries, raw AI keys, direct run sockets, or browser/plugin direct access to run. Component auth keys remain inside the platform and the ephemeral builder input.
|
|
|
|
## Port Discipline
|
|
|
|
Use the managed local debug scripts for browser-facing verification. Do not start extra ad hoc platform or platform_web processes on random ports when the standard stack is already available.
|
|
|
|
- Default platform API: `http://127.0.0.1:18080`.
|
|
- Default platform_web: `http://127.0.0.1:5173`.
|
|
- Default local debug root: `.local-debug/`.
|
|
- Restart with `scripts/dev-stop.sh` followed by `scripts/dev-start.sh`.
|
|
- Use `LOCAL_DEBUG_PLATFORM_PORT`, `LOCAL_DEBUG_WEB_PORT`, and `LOCAL_DEBUG_ROOT` only when a task explicitly needs an isolated stack.
|
|
- When debugging an already-running local page, prefer the current `5173`/`18080` stack and inspect `.local-debug/logs/` before starting anything else.
|
|
|
|
## Start
|
|
|
|
```bash
|
|
git clone git@git.npc0.com:admin343/run.git run # once, if the ignored local checkout is missing
|
|
scripts/dev-start.sh
|
|
```
|
|
|
|
The script prints the resolved platform URL, platform_web URL, log files, and the exact local account for browser login:
|
|
|
|
- Account: `operator.local@example.test`
|
|
- Password: `operator-local`
|
|
|
|
Useful defaults can be overridden before running the script:
|
|
|
|
```bash
|
|
LOCAL_DEBUG_PLATFORM_PORT=18081 LOCAL_DEBUG_WEB_PORT=5174 scripts/dev-start.sh
|
|
```
|
|
|
|
## Environment
|
|
|
|
The public commands use shared local debug helpers under `scripts/local-debug/`.
|
|
|
|
Key platform variables:
|
|
|
|
- `PLATFORM_ADDR=127.0.0.1:18080`
|
|
- `PLATFORM_STORAGE_BACKEND=file`
|
|
- `PLATFORM_DATA_DIR=.local-debug/platform`
|
|
- `PLATFORM_METADATA_PATH=.local-debug/platform/metadata.json`
|
|
- `PLATFORM_LOG_BODY_BACKEND=file`
|
|
- `PLATFORM_LOG_DIR=.local-debug/platform/logs`
|
|
- `PLATFORM_BUILDER_DOCKER_BINARY=docker`
|
|
- `PLATFORM_BUILDER_IMAGE=browser-platform-distribution-builder:1.0.0`
|
|
- `PLATFORM_BUILDER_SOURCE_DIR=.local-debug/run/build-buckets/source/current`
|
|
- `PLATFORM_BUILDER_WORKSPACE_DIR=.local-debug/platform/distribution-builds`
|
|
- `PLATFORM_BUILDER_CACHE_DIR=.local-debug/platform/distribution-build-cache`
|
|
- `PLATFORM_BUILDER_TIMEOUT_SECONDS=1800`
|
|
- `GOCACHE=.local-debug/go-build-cache`
|
|
|
|
Key run variables:
|
|
|
|
- `RUN_SOURCE_DIR=./run`
|
|
- `RUN_REPO_DIR=./run` as a legacy alias for `RUN_SOURCE_DIR`
|
|
- `RUN_BUILD_BUCKET_ROOT=.local-debug/run/build-buckets`
|
|
- `RUN_BUILD_SOURCE_ROOT=.local-debug/run/build-buckets/source/current`
|
|
- `RUN_BOOTSTRAP_BIN=.local-debug/run/build-buckets/bootstrap/bin/run`
|
|
- `RUN_MODE=worker`
|
|
- `RUN_PLATFORM_URL=http://127.0.0.1:18080`
|
|
- `RUN_ENDPOINT_ID=run-local-debug`
|
|
- `RUN_WORKSPACE_ROOT=.local-debug/run/workspace`
|
|
- `RUN_SPOOL_ROOT=.local-debug/run/spool`
|
|
|
|
Key frontend variables:
|
|
|
|
- `PLATFORM_API_PROXY=http://127.0.0.1:18080`
|
|
- `VITE_PLATFORM_API_BASE_URL=/api/v1`
|
|
- `VITE_ENABLE_LOCAL_AUTH_FALLBACK=false`
|
|
|
|
`VITE_ENABLE_LOCAL_AUTH_FALLBACK=false` is required. Local fallback data is a smoke failure for this workspace.
|
|
|
|
## Smoke
|
|
|
|
Start the stack, then run:
|
|
|
|
```bash
|
|
scripts/dev-smoke.sh
|
|
```
|
|
|
|
For one-command verification in environments that clean up background processes when a command returns, run:
|
|
|
|
```bash
|
|
LOCAL_DEBUG_SELF_START=true scripts/dev-smoke.sh
|
|
```
|
|
|
|
The smoke command verifies:
|
|
|
|
- platform health at `/healthz`.
|
|
- API-backed login for the seeded local platform administrator.
|
|
- dev plugin manifest validation and registration through `POST /api/v1/game-plugins/register-manifest`.
|
|
- run endpoint heartbeat through `GET /api/v1/run/endpoints?status=online`.
|
|
- server lifecycle fixture setup through `POST /api/v1/server-instances/workflows/create`.
|
|
- minimal server creation with plugin type and name only, followed by an explicit post-creation runtime binding.
|
|
- host-native Run generation through the platform-owned Docker builder, artifact download and execution, then generated Run registration plus a subsequent heartbeat without `distribution.build` authority.
|
|
- SCUM run package generation through the platform-owned Docker builder, without any Run endpoint advertising `distribution.build`.
|
|
- latest run download opening through `POST /api/v1/server-instances/{id}/run/download`.
|
|
- generated artifact content reads through `/api/v1/artifacts/{id}/content` with chunk, total size, and checksum verification.
|
|
- job, log stream, artifact, marketplace, and server list references.
|
|
- `PLATFORM_API_PROXY` and `VITE_PLATFORM_API_BASE_URL=/api/v1`.
|
|
- `VITE_ENABLE_LOCAL_AUTH_FALLBACK=false`.
|
|
- absence of forbidden fragments in API evidence: `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details.
|
|
|
|
Smoke evidence is written to `.local-debug/smoke/`.
|
|
|
|
## Automated Browser Acceptance
|
|
|
|
Run the automated browser acceptance suite when you need repeatable proof for the API-backed console routes:
|
|
|
|
```bash
|
|
LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh
|
|
```
|
|
|
|
By default the command safely resets the configured local debug root, starts platform, run worker, and platform_web, runs `scripts/dev-smoke.sh`, verifies browser-facing route contracts, and cleans up the self-started stack. Set `BROWSER_ACCEPTANCE_SELF_START=false` to run against an already-started local debug stack.
|
|
|
|
Acceptance evidence is written to:
|
|
|
|
```text
|
|
<LOCAL_DEBUG_ROOT>/browser-acceptance/browser-acceptance-evidence.json
|
|
```
|
|
|
|
The evidence records stack URLs, the smoke seed evidence directory, first-party route checks, plugin/server operation proof, fallback scans, and forbidden-fragment scans.
|
|
|
|
## Browser Walkthrough
|
|
|
|
After `scripts/dev-smoke.sh` passes, open platform_web:
|
|
|
|
```text
|
|
http://127.0.0.1:5173
|
|
```
|
|
|
|
Required walkthrough:
|
|
|
|
- Login with `operator.local@example.test` / `operator-local`.
|
|
- Confirm no local fallback banner, local fallback workspace, or demo-only session is visible.
|
|
- Open 首页.
|
|
- Open 服务器管理.
|
|
- Open 插件市场.
|
|
- Open 用户管理.
|
|
- Open AI 提供商管理.
|
|
- Inspect the invocation-scoped example server ID recorded in `.local-debug/smoke/run-build-config.env`, its generated Run endpoint, plugin controls or marketplace detail, operation history, log references, and artifact references.
|
|
- Scan visible browser text for forbidden fragments: `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details.
|
|
|
|
Acceptance requires logical IDs, platform routes, job refs, log refs, artifact refs, and safe metadata only.
|
|
|
|
## Stop
|
|
|
|
```bash
|
|
scripts/dev-stop.sh
|
|
```
|
|
|
|
## Reset
|
|
|
|
```bash
|
|
scripts/dev-reset.sh
|
|
```
|
|
|
|
Reset stops the local debug processes and deletes only the documented local debug root. By default that root is:
|
|
|
|
```text
|
|
.local-debug
|
|
```
|
|
|
|
The reset script refuses unexpected roots. It allows only:
|
|
|
|
- `<repo>/.local-debug`
|
|
- `/private/tmp/browser-local-debug-*`
|
|
- `/tmp/browser-local-debug-*`
|
|
|
|
## Manual Commands
|
|
|
|
The start script wraps these commands with the local debug environment:
|
|
|
|
```bash
|
|
(cd platform && go run ./cmd/platform)
|
|
source scripts/local-debug/env.sh
|
|
local_debug_prepare_distribution_builder
|
|
local_debug_build_bootstrap_run
|
|
"$RUN_BOOTSTRAP_BIN"
|
|
npm --prefix platform_web run dev -- --port 5173
|
|
```
|
|
|
|
The dev plugin fixture validation command is:
|
|
|
|
```bash
|
|
cd plugins && npm run validate:manifest
|
|
```
|