browser/docs/local-debug-workspace.md

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.

Start

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:

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:

scripts/local-debug-smoke.sh

For one-command verification in environments that clean up background processes when a command returns, run:

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:

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:

<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:

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

scripts/local-debug-stop.sh

Reset

scripts/local-debug-reset.sh

Reset stops the local debug processes and deletes only the documented local debug root. By default that root is:

.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:

(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:

cd plugins && npm run validate:manifest