admin343/browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
browser/docs/local-debug-workspace.md
T

8.5 KiB
Raw Permalink Blame History

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 kept as an independent checkout. The platform-owned builder refreshes the configured repository revision for every Run build, exports a clean per-job source workspace, injects package configuration, and compiles before publishing the artifact. The local bootstrap worker is built from the checkout 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

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:

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=./run
  • PLATFORM_BUILDER_SOURCE_REPOSITORY=git@git.npc0.com:admin343/run.git
  • PLATFORM_BUILDER_SOURCE_REVISION=main
  • 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_SOURCE_REPOSITORY=git@git.npc0.com:admin343/run.git
  • RUN_SOURCE_REVISION=main
  • 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:

scripts/dev-smoke.sh

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

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:

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:

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

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

scripts/dev-stop.sh

Reset

scripts/dev-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)
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:

cd plugins && npm run validate:manifest
Reference in New Issue View Git Blame Copy Permalink