browser/openspec/changes/implement-local-debug-workspace/tasks.md

1. Local Debug Workflow Definition

• 1.1 Add or update repository documentation for the local debug workspace, including startup, ports, env vars, data roots, log files, reset, smoke verification, and browser walkthrough.
• 1.2 Add scripts or command wrappers for starting platform, run worker, and platform_web with explicit local debug configuration.
• 1.3 Add a reset/cleanup path that removes only the documented local debug root and prints or documents exactly what it deletes.
• 1.4 Ensure the workflow does not require Docker-only infrastructure, external cloud services, real game binaries, raw credentials, raw AI keys, direct sockets, or browser/plugin direct access to run.

2. Safe Plugin and Server Fixture

• 2.1 Add or document setup for one local game management plugin fixture using the existing dev plugin manifest or a safe local proof plugin.
• 2.2 Add setup steps that create or reuse at least one server instance through platform-owned data/API paths and scoped run workspace lifecycle templates.
• 2.3 Ensure fixture commands are harmless and bounded, and that API/platform_web responses expose only logical IDs, platform routes, job refs, log refs, artifact refs, and safe metadata.
• 2.4 Add tests or smoke checks that reject raw host paths, raw credentials, run session tokens, direct sockets, raw AI provider keys, shell launchers, and plugin-owned transport details in fixture outputs.

3. Smoke Verification Commands

• 3.1 Add concrete smoke commands for platform health, run endpoint registration/heartbeat, plugin registration/installation, server instance lifecycle state, lifecycle jobs, and log/artifact references.
• 3.2 Add smoke verification that platform_web is configured with PLATFORM_API_PROXY and VITE_PLATFORM_API_BASE_URL=/api/v1, and that demo/local fallback data is treated as a failure.
• 3.3 Run the documented backend smoke commands and record evidence.
• 3.4 Run relevant unit/build checks for touched roots, such as cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1, cd run && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1, cd plugins && npm run typecheck && npm run test && npm run validate:manifest, and cd platform_web && npm run typecheck && npm test && npm run build as applicable, then record evidence.

4. Browser Walkthrough

• 4.1 Start the documented local debug stack and log the exact platform, run worker, and platform_web commands used.
• 4.2 In a browser with an API-backed user session, open 首页、服务器管理、插件市场、用户管理、AI 提供商管理 and confirm no page is using local fallback data.
• 4.3 Use the browser to inspect a local debug plugin/server lifecycle path, including server detail, plugin detail or marketplace data, operation history, and log/artifact references.
• 4.4 Scan visible browser content for forbidden fragments: /Users/, /private/, unix://, tcp://, Bearer , sk-, password=, apiKeyRef, rawApiKey, run session tokens, direct run URLs, and plugin-owned transport details.
• 4.5 Record browser walkthrough evidence in this tasks file only after the walkthrough has actually run.

5. Final Verification and Stream Handoff

• 5.1 Record implementation evidence in this tasks file only after each command, smoke check, or browser walkthrough has actually run.
• 5.2 Run scripts/check-structure.sh and record evidence.
• 5.3 Run openspec validate implement-local-debug-workspace --strict and record evidence.
• 5.4 Update openspec/changes/architecture-delivery-stream/delivery-plan.md to mark implement-local-debug-workspace complete only after evidence exists and move the next queue item to active.
• 5.5 Update openspec/changes/architecture-delivery-stream/NEXT_CHANGE.md with the next implementation/generator handoff after this change closes.

Evidence

• Added local debug documentation and repository pointers:
  • docs/local-debug-workspace.md documents startup, ports, env vars, data roots, log files, reset scope, smoke verification, browser walkthrough, account credentials, and manual commands.
  • README.md points contributors to scripts/local-debug-start.sh, scripts/local-debug-smoke.sh, LOCAL_DEBUG_SELF_START=true, and the local debug guide.
  • plugins/docs/local-development.md documents the dev plugin fixture and safe API-backed proof path.
• Added local debug scripts:
  • scripts/local-debug-env.sh centralizes LOCAL_DEBUG_*, platform, run, frontend, and forbidden-fragment settings.
  • scripts/local-debug-start.sh starts platform, run worker, and platform_web with explicit logs, PIDs, ports, data roots, run workspace root, run spool root, Vite proxy, and fallback disabled.
  • scripts/local-debug-stop.sh stops only tracked local-debug PIDs.
  • scripts/local-debug-reset.sh refuses unexpected roots and deletes only <repo>/.local-debug, /private/tmp/browser-local-debug-*, or /tmp/browser-local-debug-*.
  • scripts/local-debug-smoke.sh verifies platform health, API login, dev plugin manifest validation, plugin registration, run heartbeat, server lifecycle workflow creation, jobs, log streams, artifacts, marketplace refs, frontend proxy env, fallback disabled, and forbidden-fragment absence.
• Script syntax check passed:
  • bash -n scripts/local-debug-env.sh scripts/local-debug-start.sh scripts/local-debug-stop.sh scripts/local-debug-reset.sh scripts/local-debug-smoke.sh
• Frontend verification passed:
  • cd platform_web && npm run typecheck
  • cd platform_web && npm test -> 11 test files, 49 tests passed.
  • cd platform_web && npm run build -> Vite production build completed.
• Plugin verification passed:
  • cd plugins && npm run typecheck
  • cd plugins && npm run test -> 1 test file, 11 tests passed.
  • cd plugins && npm run validate:manifest initially failed in the sandbox because tsx could not create an IPC pipe (listen EPERM .../tsx-501/...pipe); rerunning with elevated sandbox permissions passed and validated examples/dev-game-plugin/manifest.json.
• Backend verification passed:
  • cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1 passed for platform API, config, domain, DTO, model, repo, service, and validator packages.
  • cd run && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1 initially failed in the sandbox because httptest could not bind local listeners; rerunning with elevated sandbox permissions passed for run API, config, protocol, runtime, and spool packages.
• Self-start local debug smoke passed:
  • LOCAL_DEBUG_PLATFORM_PORT=18187 LOCAL_DEBUG_WEB_PORT=5181 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-final LOCAL_DEBUG_SELF_START=true scripts/local-debug-smoke.sh
  • Evidence directory: /private/tmp/browser-local-debug-final/smoke
  • Output confirmed platform health, dev plugin manifest validation, plugin API registration, run endpoint heartbeat, server lifecycle workflow creation, job/log/artifact/marketplace reference checks, and forbidden-fragment rejection.
• Browser walkthrough stack and seed smoke passed:
  • Reset: LOCAL_DEBUG_PLATFORM_PORT=18188 LOCAL_DEBUG_WEB_PORT=5182 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-walkthrough scripts/local-debug-reset.sh
  • Stack command: /bin/zsh -lc 'LOCAL_DEBUG_PLATFORM_PORT=18188 LOCAL_DEBUG_WEB_PORT=5182 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-walkthrough scripts/local-debug-reset.sh; LOCAL_DEBUG_PLATFORM_PORT=18188 LOCAL_DEBUG_WEB_PORT=5182 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-walkthrough scripts/local-debug-start.sh; sleep 1200'
  • Seed smoke: LOCAL_DEBUG_PLATFORM_PORT=18188 LOCAL_DEBUG_WEB_PORT=5182 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-walkthrough scripts/local-debug-smoke.sh
  • Evidence directory: /private/tmp/browser-local-debug-walkthrough/smoke
• Browser walkthrough evidence:
  • Logged in at http://127.0.0.1:5182 with operator.local@example.test / operator-local; login landed on #/home with API-backed platform data.
  • Opened 首页 #/home: showed 平台概览, 数据已加载, game.example：1 个实例, and 运行节点 1; no fallback/demo text and no forbidden fragments.
  • Opened 服务器管理 #/servers: showed Local Debug Example Server / server-local-debug; no fallback/demo text and no forbidden fragments.
  • Opened 插件市场 #/plugins: showed game.example, artifact://manifests/game.example/0.1.0, process.install, process.start, process.stop, server.instances.read, jobs.dispatch, logs.query, and artifacts.open; no fallback/demo text and no forbidden fragments.
  • Opened 用户管理 #/users: showed operator.local@example.test, 账号 API 已连接, and local admin metadata; no fallback/demo text and no forbidden fragments.
  • Opened AI 提供商管理 #/aiProviders: showed API-backed provider rows with redacted secret refs (secret://providers/openai, env://OLLAMA_API_KEY); no fallback/demo text and no forbidden fragments.
  • Opened server detail #/servers/server-local-debug: showed Local Debug Example Server, game.example@0.1.0, run-local-debug, lifecycle buttons, 日志, 配置, 插件控制, AI 助手, and 操作历史; no fallback/demo text and no forbidden fragments.
  • The browser DOM snapshot helper failed with incrementalAriaSnapshot is not a function, so the walkthrough used read-only page evaluation to inspect visible text, buttons, URLs, and forbidden fragments.
• Final verification commands:
  • scripts/check-structure.sh passed after implementation evidence was recorded.
  • openspec validate implement-local-debug-workspace --strict passed after implementation evidence and stream handoff were updated; PostHog telemetry DNS errors, if emitted after success, do not affect the validation result.