first commit

openspec/changes/implement-local-debug-workspace/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-08

openspec/changes/implement-local-debug-workspace/design.md

@@ -0,0 +1,66 @@
+## Context
+
+The platform now has real local capabilities across `platform/`, `run/`, `platform_web/`, and `plugins/`: platform can serve API-backed metadata, run can register and execute lifecycle jobs, platform_web can operate against platform APIs, and the local proof plugin can drive server lifecycle through platform-mediated contracts. The remaining local-development gap is repeatability. Contributors currently need to reconstruct proof commands, temporary data roots, setup payloads, frontend proxy settings, browser walkthrough steps, and cleanup procedures from scattered task evidence.
+
+This change creates a first-party local debug workspace. It should make the real stack easy to boot, reset, inspect, and verify without introducing production deployment scope or bypassing platform mediation.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide one documented and/or scripted local workflow for platform, run worker, platform_web, and the dev game plugin path.
+- Use explicit local ports, environment variables, data roots, spool roots, log roots, and reset commands.
+- Include smoke checks for platform health, run registration/heartbeat, plugin registration/installation, server lifecycle, logs/artifact references, and API-backed frontend behavior.
+- Include browser walkthrough requirements for 首页、服务器管理、插件市场、用户管理、AI 提供商管理 and one plugin lifecycle path.
+- Keep all plugin/browser operations platform-mediated and prove no raw host paths, credentials, direct sockets, run tokens, raw AI keys, or plugin-owned transport details are visible.
+
+**Non-Goals:**
+- Do not add cloud deployment, billing, host sales, agent-provider flows, or unrelated SaaS marketplace behavior.
+- Do not add Docker-only requirements; local workflow may coexist with Docker but must be runnable with repository commands.
+- Do not replace the existing magical-girl crystal-moonlight platform_web style.
+- Do not make plugins connect directly to run or expose run sockets/tokens to platform_web.
+- Do not implement the later automated browser acceptance suite here; this change may define a manual/semiautomated walkthrough that a later change can automate.
+
+## Decisions
+
+1. Use repository-owned local scripts/docs instead of only OpenSpec task notes.
+
+   The workflow must survive after the implementation chat. A script plus a short markdown guide is preferable to evidence-only commands because contributors need a stable entry point. The script should print the exact platform, run, and frontend commands and write logs to predictable local files.
+
+   Alternative considered: keep commands solely in `tasks.md`. That satisfies the change once but does not improve day-to-day local debugging.
+
+2. Keep local data under a disposable workspace root.
+
+   Platform metadata, platform log bodies, run workspace files, and run spool files should live under an explicit root such as `.local-debug/` or `/private/tmp/browser-local-debug-workspace`. Reset must remove only that root and should never delete broad user directories.
+
+   Alternative considered: reuse `.platform-data` and `.run-workspace` defaults. That is convenient but makes reset behavior less auditable and can mix unrelated local experiments.
+
+3. Use the existing API-backed platform and Vite proxy shape.
+
+   The frontend should run with `PLATFORM_API_PROXY=http://127.0.0.1:<platform-port>` and `VITE_PLATFORM_API_BASE_URL=/api/v1`, proving browser calls go through platform-owned APIs. Browser/plugin pages must not receive direct run URLs or run credentials.
+
+   Alternative considered: have platform_web point directly at a run worker or plugin dev server. That violates the architecture boundaries and is explicitly out of scope.
+
+4. Seed only safe local fixtures.
+
+   The local workflow may create a dev plugin, one or more server instances, and lifecycle action templates under the scoped run workspace. Fixtures must use logical IDs and harmless commands. They must not require real game binaries, raw credentials, shell launchers, direct sockets, absolute host paths in API payloads, or raw AI keys.
+
+   Alternative considered: require a real game server installation. That would make the debug workflow too heavy and environment-specific for this stream step.
+
+## Risks / Trade-offs
+
+- Port collisions -> Provide configurable env vars and print the resolved ports before starting services.
+- Background process cleanup is brittle -> Prefer explicit log/PID files and a stop/reset command over hidden shell process management.
+- Smoke setup can drift from APIs -> Implement smoke using the same public/local API routes and plugin manifest validation used elsewhere.
+- Browser walkthrough remains manual -> Record exact pages, expected API-backed signals, and forbidden-fragment scan requirements so the later acceptance-suite change can automate it.
+- Reset can become dangerous -> Scope cleanup to the local debug root and document what is removed before removing it.
+
+## Migration Plan
+
+1. Add local debug documentation and scripts or command wrappers under the appropriate repository location.
+2. Add or update tests/smoke checks for generated commands, safe reset scope, and API-backed local fixture setup.
+3. Run the documented local stack and browser/API walkthrough.
+4. Record evidence in `tasks.md`, run structure checks and strict OpenSpec validation, and advance the stream pointer.
+
+## Open Questions
+
+- None currently. If implementation reveals an existing script location convention, follow it rather than inventing a parallel tool layout.

openspec/changes/implement-local-debug-workspace/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+The architecture stream now has real platform, run, platform_web, and plugin lifecycle proof, but reproducing that stack still requires ad hoc commands, temporary paths, manual fixture setup, and scattered evidence. A first-party local debug workspace is needed so contributors can boot the same API-backed workflow repeatedly, inspect logs clearly, reset state safely, and prove the console is not falling back to demo-only data.
+
+## What Changes
+
+- Add a local debug workflow that starts platform, run worker, platform_web, and one local game management plugin path with documented ports, environment variables, data roots, and log locations.
+- Add reset and cleanup steps for local platform metadata, log body storage, run workspace state, run spool state, and frontend dev-server state.
+- Add smoke verification that proves platform health, run registration/heartbeat, plugin registration/installation, server instance lifecycle, log/artifact references, and browser/API-backed console navigation.
+- Add safety checks proving browser/plugin page surfaces do not expose host paths, raw credentials, run session tokens, direct sockets, raw AI provider keys, or plugin-owned transport details.
+- Add concrete commands and browser walkthrough requirements so future implementation chats can verify the local debug workflow without inventing a new proof path.
+- No breaking changes are expected; this change standardizes local orchestration and verification around existing roots.
+
+## Capabilities
+
+### New Capabilities
+- `local-debug-workspace`: Defines the local developer workflow for running platform, run, platform_web, and one game management plugin together with clear logs, reset steps, API-backed smoke checks, and browser walkthrough evidence.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Affected roots: `platform/`, `run/`, `platform_web/`, `plugins/`, `scripts/`, and documentation.
+- Expected implementation areas: local workflow scripts or docs, fixture/setup helpers, reset commands, smoke verification commands, browser walkthrough checklist, and OpenSpec task evidence.
+- Validation impact: requires platform/run/plugin/frontend command checks where relevant, `scripts/check-structure.sh`, `openspec validate implement-local-debug-workspace --strict`, and a browser walkthrough for the API-backed console path.

openspec/changes/implement-local-debug-workspace/specs/local-debug-workspace/spec.md

@@ -0,0 +1,67 @@
+## ADDED Requirements
+
+### Requirement: Local debug workspace starts the real stack
+The repository SHALL provide a local debug workflow that starts platform, run worker, platform_web, and one local game management plugin path using explicit local configuration.
+
+#### Scenario: Developer starts local debug services
+- **WHEN** a developer follows the local debug workflow
+- **THEN** the workflow MUST provide concrete commands or scripts for platform, run worker, and platform_web with explicit local ports, data directories, log directories, run workspace root, run spool root, frontend API proxy, and Vite API base URL
+
+#### Scenario: Local debug uses API-backed frontend
+- **WHEN** platform_web is started by the local debug workflow
+- **THEN** it MUST use platform-owned API routes through the configured proxy and MUST NOT require platform_web to connect directly to run or plugin-owned transports
+
+### Requirement: Local debug workspace can be reset safely
+The repository SHALL provide reset or cleanup steps that remove only local debug workspace state and leave unrelated user files, repository source files, and non-debug service data untouched.
+
+#### Scenario: Developer resets local debug state
+- **WHEN** a developer runs the documented reset path
+- **THEN** platform metadata, platform log bodies, run workspace files, run spool files, local fixture state, and local service logs for the debug workspace MUST be removed or reinitialized only within the documented local debug root
+
+#### Scenario: Reset scope is auditable
+- **WHEN** a contributor inspects the reset command or script
+- **THEN** the command MUST show the exact local debug paths it removes and MUST NOT remove broad directories such as the repository root, home directory, `/Users`, `/private`, `/tmp`, or unrelated service data
+
+### Requirement: Local debug workflow seeds a safe game plugin lifecycle fixture
+The local debug workflow SHALL seed or document a safe local game plugin fixture that can create and manage at least one server instance through platform-mediated lifecycle APIs.
+
+#### Scenario: Developer prepares lifecycle fixture
+- **WHEN** the local debug setup creates plugin/server lifecycle data
+- **THEN** it MUST register or reuse a local game plugin manifest, install the plugin through platform data, create at least one logical server instance, and use scoped run workspace lifecycle templates with harmless commands
+
+#### Scenario: Fixture preserves safety boundaries
+- **WHEN** plugin lifecycle data is visible through platform APIs or platform_web
+- **THEN** responses MUST NOT expose raw host paths, raw credentials, run session tokens, direct sockets, raw AI provider keys, shell launchers, or plugin-owned transport details
+
+### Requirement: Local debug workflow includes smoke verification
+The local debug workflow SHALL include concrete smoke commands that prove the stack is healthy and API-backed before browser acceptance is claimed.
+
+#### Scenario: Smoke commands verify backend state
+- **WHEN** smoke verification runs
+- **THEN** it MUST check platform health, run endpoint registration or heartbeat, plugin registration/installation, server instance lifecycle state, queued or completed lifecycle jobs, and safe log/artifact references through platform APIs
+
+#### Scenario: Smoke commands reject demo-only fallback
+- **WHEN** smoke verification inspects frontend or API state
+- **THEN** it MUST prove platform_web is using the configured platform API and MUST flag local/demo fallback data as a failed smoke condition
+
+### Requirement: Browser walkthrough verifies first-party areas and safety
+The local debug workflow SHALL include a browser walkthrough that verifies the API-backed console across required first-party areas and one plugin lifecycle path.
+
+#### Scenario: Browser walkthrough opens first-party areas
+- **WHEN** the browser walkthrough runs
+- **THEN** it MUST open 首页、服务器管理、插件市场、用户管理、AI 提供商管理 with an API-backed user session and confirm the pages are not local fallback views
+
+#### Scenario: Browser walkthrough verifies plugin lifecycle path
+- **WHEN** the browser walkthrough operates a local debug server instance
+- **THEN** it MUST use platform_web to inspect plugin/server details, trigger or verify a platform-mediated lifecycle action, observe operation history or job state, and confirm sibling/log/artifact references remain safe
+
+#### Scenario: Browser walkthrough scans visible sensitive fragments
+- **WHEN** the browser walkthrough inspects visible page content
+- **THEN** it MUST fail if `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, or plugin-owned transport details are visible
+
+### Requirement: Local debug workflow is documented and verified
+The change SHALL include documentation, tests or smoke checks, and final verification commands proving the local debug workflow is reproducible.
+
+#### Scenario: Verification commands run
+- **WHEN** the change is complete
+- **THEN** the documented test/build/smoke commands, `scripts/check-structure.sh`, and `openspec validate implement-local-debug-workspace --strict` MUST pass, and browser walkthrough evidence MUST be recorded if platform_web pages are touched or verified

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

@@ -0,0 +1,83 @@
+## 1. Local Debug Workflow Definition
+
+- [x] 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.
+- [x] 1.2 Add scripts or command wrappers for starting platform, run worker, and platform_web with explicit local debug configuration.
+- [x] 1.3 Add a reset/cleanup path that removes only the documented local debug root and prints or documents exactly what it deletes.
+- [x] 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
+
+- [x] 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.
+- [x] 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.
+- [x] 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.
+- [x] 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
+
+- [x] 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.
+- [x] 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.
+- [x] 3.3 Run the documented backend smoke commands and record evidence.
+- [x] 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
+
+- [x] 4.1 Start the documented local debug stack and log the exact platform, run worker, and platform_web commands used.
+- [x] 4.2 In a browser with an API-backed user session, open 首页、服务器管理、插件市场、用户管理、AI 提供商管理 and confirm no page is using local fallback data.
+- [x] 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.
+- [x] 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.
+- [x] 4.5 Record browser walkthrough evidence in this tasks file only after the walkthrough has actually run.
+
+## 5. Final Verification and Stream Handoff
+
+- [x] 5.1 Record implementation evidence in this tasks file only after each command, smoke check, or browser walkthrough has actually run.
+- [x] 5.2 Run `scripts/check-structure.sh` and record evidence.
+- [x] 5.3 Run `openspec validate implement-local-debug-workspace --strict` and record evidence.
+- [x] 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.
+- [x] 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.