# 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 worker is loaded from `RUN_REPO_DIR`, defaulting to the ignored nested `./run` checkout, and registers 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 does not require Docker-only infrastructure, external cloud services, real game binaries, raw credentials, raw AI keys, direct run sockets, or browser/plugin direct access to run.

## 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/local-debug-stop.sh` followed by `scripts/local-debug-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/local-debug-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/local-debug-start.sh
```

## Environment

The scripts source `scripts/local-debug-env.sh`.

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`
- `GOCACHE=.local-debug/go-build-cache`

Key run variables:

- `RUN_REPO_DIR=./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/local-debug-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/local-debug-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`.
- 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/local-debug-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/local-debug-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 `server-local-debug` server detail, 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/local-debug-stop.sh
```

## Reset

```bash
scripts/local-debug-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)
(cd "${RUN_REPO_DIR:-./run}" && go run ./cmd/run)
npm --prefix platform_web run dev -- --port 5173
```

The dev plugin fixture validation command is:

```bash
cd plugins && npm run validate:manifest
```