first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-08
|
||||
@@ -0,0 +1,77 @@
|
||||
## Context
|
||||
|
||||
The architecture stream now has API-backed platform, run, platform_web, and plugin proof, plus a documented local debug workspace that can start the real stack, seed `game.example`, create `server-local-debug`, and verify a manual browser walkthrough. The remaining gap is repeatability: browser acceptance currently lives as task evidence and operator procedure, so regressions can slip in when route text, auth behavior, local fixture setup, plugin marketplace data, lifecycle operation surfaces, or safety redaction drift.
|
||||
|
||||
The automated suite should preserve the existing architecture boundaries. Browser checks must exercise platform_web through platform-owned API routes, not direct run or plugin transports. Fixture setup should reuse the local debug scripts and safe dev plugin manifest instead of inventing a second seed path. The suite should be useful locally and in CI-like verification while staying scoped to the game server management platform.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Provide one automated browser acceptance command that verifies the API-backed local debug console path end to end.
|
||||
- Reuse or orchestrate the documented local debug stack and smoke fixture so acceptance data matches the manual proof path.
|
||||
- Verify login and required first-party routes: 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
||||
- Verify server detail and core plugin/server operation surfaces, including plugin marketplace data, lifecycle controls or operation-history proof, and log/artifact references.
|
||||
- Fail when platform_web uses local/demo fallback data, when required API-backed evidence is missing, or when visible content exposes forbidden sensitive fragments.
|
||||
- Record deterministic evidence that can be cited from OpenSpec tasks.
|
||||
|
||||
**Non-Goals:**
|
||||
- Do not change product behavior, visual direction, authorization semantics, or plugin/runtime contracts.
|
||||
- Do not implement a cloud, billing, host marketplace, or unrelated SaaS workflow.
|
||||
- Do not require Docker-only infrastructure, real game binaries, raw credentials, raw AI keys, direct sockets, or plugin/browser direct access to run.
|
||||
- Do not replace unit, API, manifest, or local-debug smoke tests; this suite complements those checks by verifying browser-visible behavior.
|
||||
- Do not broaden acceptance into full visual regression testing or screenshot comparison.
|
||||
|
||||
## Decisions
|
||||
|
||||
1. Reuse the local debug workspace as the acceptance fixture.
|
||||
|
||||
The suite should either self-start the documented local debug stack or require an explicit command that does so, then run `scripts/local-debug-smoke.sh` to seed and verify the platform/run/plugin fixture before browser checks. This keeps the browser acceptance data aligned with `docs/local-debug-workspace.md` and avoids parallel fixture drift.
|
||||
|
||||
Alternative considered: seed browser acceptance through a separate frontend-only mock. That would make the suite faster but would not prove real platform/run/plugin integration or prevent demo-only regressions.
|
||||
|
||||
2. Put the acceptance harness near platform_web but keep stack orchestration at repository script level.
|
||||
|
||||
Browser route assertions are frontend-facing and should live with platform_web tests or a clearly named acceptance harness. Starting platform, run, smoke, and frontend should remain in scripts so contributors can run one documented command without learning test internals.
|
||||
|
||||
Alternative considered: hide all service orchestration inside a test file. That makes local failures harder to diagnose because logs, ports, and reset behavior become less visible than the existing local debug workflow.
|
||||
|
||||
3. Assert stable user-visible and route-level signals, not screenshots.
|
||||
|
||||
The suite should inspect URLs, visible text, buttons/links, and API-backed markers such as `数据已加载`, `账号 API 已连接`, `game.example`, `server-local-debug`, `run-local-debug`, lifecycle controls, and marketplace bridge actions. It should avoid brittle pixel assertions and should not depend on decorative theme details beyond preserving the existing UI test/build gates.
|
||||
|
||||
Alternative considered: screenshot or visual diff acceptance. That is higher maintenance and better suited for a later design-polish workflow.
|
||||
|
||||
4. Centralize fallback and forbidden-fragment scanning.
|
||||
|
||||
Every route check should run a shared scanner for fallback/demo indicators and forbidden fragments: `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details. Keeping this scanner shared makes new route coverage safer to add.
|
||||
|
||||
Alternative considered: duplicate string checks per page. That is easy to start but likely to drift and miss new route surfaces.
|
||||
|
||||
5. Produce machine-readable and human-readable evidence.
|
||||
|
||||
The acceptance command should print concise pass/fail output and write an evidence artifact, such as JSON or markdown, listing routes visited, assertions passed, stack URLs, seed evidence directory, and any failure details. OpenSpec tasks should cite that evidence after the command actually runs.
|
||||
|
||||
Alternative considered: rely only on terminal output. Terminal output is useful but too easy to lose during long stream handoffs.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Port collisions -> Allow configurable local debug ports and make the acceptance command print resolved URLs and log paths.
|
||||
- Browser automation flakiness -> Use deterministic local data, stable route URLs, bounded waits for specific page states, and concise route assertions rather than long click chains.
|
||||
- Long-running service cleanup -> Reuse `scripts/local-debug-reset.sh` and ensure self-started acceptance runs stop tracked processes on success and failure.
|
||||
- False positives from sensitive text inside docs or forms -> Scan only visible browser content and acceptance evidence intended for users, while still treating sensitive visible strings as failures.
|
||||
- Fixture drift from smoke data -> Run or require `scripts/local-debug-smoke.sh` before browser assertions and fail if expected local debug IDs are missing.
|
||||
- Sandbox limitations around localhost listeners or browser tooling -> Document when elevated permissions are needed for local listener tests, while keeping the suite command itself explicit and reproducible.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Add the browser acceptance harness and repository command wrapper.
|
||||
2. Reuse the local debug smoke fixture and add evidence output for route assertions and forbidden-fragment scanning.
|
||||
3. Run the new acceptance command against a clean local debug root.
|
||||
4. Run frontend typecheck/tests/build, relevant local debug smoke checks, `scripts/check-structure.sh`, and strict OpenSpec validation.
|
||||
5. Update stream evidence and next pointer after the change is implemented.
|
||||
|
||||
Rollback is straightforward: remove the acceptance harness and command wrapper if it proves unstable; no product runtime state or persisted user data model changes are introduced.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None currently. During implementation, follow existing platform_web test tooling and local debug script conventions rather than adding a new browser framework if a suitable one already exists in the repository.
|
||||
@@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
The architecture stream now has a repeatable local debug workspace and a manually verified API-backed browser walkthrough, but the walkthrough still depends on an operator remembering route checks, seed order, and forbidden-fragment scans. An automated browser acceptance suite is needed now so required first-party console flows stay real, API-backed, and safe as platform, run, platform_web, and plugin features keep evolving.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add an automated browser acceptance suite for the local debug/API-backed console path.
|
||||
- Cover login and navigation across 首页、服务器管理、插件市场、用户管理、AI 提供商管理, plus server detail and core plugin/server operation surfaces.
|
||||
- Require the suite to seed or reuse the documented local debug fixture before browser checks run.
|
||||
- Require fallback/demo-only data rejection and visible forbidden-fragment scanning on every accepted route.
|
||||
- Require concrete commands that can run the suite locally and in CI-like verification without relying on manual browser-only evidence.
|
||||
- No breaking changes are expected; this change automates an existing verified workflow instead of changing product behavior.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `browser-acceptance-suite`: Defines automated browser acceptance coverage for the API-backed management console, local debug fixture prerequisites, required route assertions, plugin/server lifecycle proof, fallback rejection, forbidden-fragment scanning, and verification commands.
|
||||
|
||||
### Modified Capabilities
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected roots: `platform_web/`, `scripts/`, documentation, and potentially shared local debug fixtures under `platform/`, `run/`, and `plugins/` only as needed to support deterministic acceptance setup.
|
||||
- Expected implementation areas: browser acceptance test harness, local debug stack orchestration or reuse hooks, visible content assertions, forbidden-fragment scanner, route coverage fixtures, and task evidence.
|
||||
- Validation impact: requires frontend typecheck/tests/build, automated browser acceptance command, local debug smoke prerequisites, `scripts/check-structure.sh`, and `openspec validate implement-browser-acceptance-suite --strict`.
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Acceptance suite runs against the real local debug stack
|
||||
The repository SHALL provide an automated browser acceptance suite that verifies platform_web against the API-backed local debug stack and safe game plugin fixture.
|
||||
|
||||
#### Scenario: Suite prepares local debug fixture
|
||||
- **WHEN** the acceptance suite is run from a clean checkout with documented local debug prerequisites
|
||||
- **THEN** it MUST start or reuse platform, run worker, platform_web, and the dev game plugin fixture through documented local debug commands and MUST seed or verify `game.example`, `server-local-debug`, and `run-local-debug` before browser assertions begin
|
||||
|
||||
#### Scenario: Suite uses platform-owned browser API path
|
||||
- **WHEN** platform_web is exercised by the acceptance suite
|
||||
- **THEN** browser requests MUST go through the configured platform API proxy with `VITE_PLATFORM_API_BASE_URL=/api/v1` and MUST NOT require direct run URLs, run credentials, or plugin-owned transports in browser code or visible output
|
||||
|
||||
### Requirement: Acceptance suite verifies first-party console areas
|
||||
The browser acceptance suite SHALL verify the required first-party platform_web areas with an API-backed user session.
|
||||
|
||||
#### Scenario: Suite logs in with local debug user
|
||||
- **WHEN** the acceptance suite opens platform_web
|
||||
- **THEN** it MUST log in with the documented local debug operator account and confirm the session lands on an API-backed workspace rather than local fallback data
|
||||
|
||||
#### Scenario: Suite verifies required routes
|
||||
- **WHEN** browser acceptance route checks run
|
||||
- **THEN** they MUST open 首页、服务器管理、插件市场、用户管理、AI 提供商管理 and assert stable API-backed content for each route
|
||||
|
||||
#### Scenario: Suite rejects fallback content
|
||||
- **WHEN** any required route renders fallback, mock, demo-only, or local-auth fallback content
|
||||
- **THEN** the acceptance suite MUST fail and report the route, visible evidence, and failed assertion
|
||||
|
||||
### Requirement: Acceptance suite verifies plugin and server operation surfaces
|
||||
The browser acceptance suite SHALL verify core plugin/server operation surfaces that prove the console is connected to platform-mediated lifecycle and plugin data.
|
||||
|
||||
#### Scenario: Suite verifies server detail lifecycle surface
|
||||
- **WHEN** the suite opens the local debug server detail route
|
||||
- **THEN** it MUST assert that `Local Debug Example Server`, `server-local-debug`, `game.example`, `run-local-debug`, lifecycle controls, operation history, log entry points, and artifact or artifact-reference entry points are visible or otherwise represented through platform-owned UI state
|
||||
|
||||
#### Scenario: Suite verifies plugin marketplace data
|
||||
- **WHEN** the suite opens the plugin marketplace route or plugin detail surface
|
||||
- **THEN** it MUST assert that `game.example`, manifest reference metadata, installed state, platform-mediated permissions, bridge actions, and lifecycle capabilities are visible without exposing unsafe runtime transport details
|
||||
|
||||
#### Scenario: Suite verifies operation proof without direct run access
|
||||
- **WHEN** the suite triggers or inspects a lifecycle operation
|
||||
- **THEN** it MUST verify platform-owned job or operation-history evidence and MUST NOT rely on platform_web or plugin pages contacting run directly
|
||||
|
||||
### Requirement: Acceptance suite scans visible safety boundaries
|
||||
The browser acceptance suite SHALL scan accepted browser-visible content for fallback indicators and forbidden sensitive fragments.
|
||||
|
||||
#### Scenario: Suite scans each accepted route
|
||||
- **WHEN** a required route or plugin/server operation surface is accepted
|
||||
- **THEN** the suite MUST scan visible text for `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details
|
||||
|
||||
#### Scenario: Suite fails on forbidden visible fragments
|
||||
- **WHEN** any forbidden sensitive fragment is visible on an accepted route
|
||||
- **THEN** the suite MUST fail and report the route, matched fragment class, and enough nearby evidence to debug the leak without printing raw credentials
|
||||
|
||||
### Requirement: Acceptance suite produces reproducible evidence
|
||||
The browser acceptance suite SHALL provide concrete commands and evidence outputs that can be used to close OpenSpec tasks.
|
||||
|
||||
#### Scenario: Suite command is documented
|
||||
- **WHEN** contributors read the change documentation or tasks
|
||||
- **THEN** they MUST find concrete commands for running local debug smoke, browser acceptance, frontend checks, structure checks, and strict OpenSpec validation
|
||||
|
||||
#### Scenario: Suite writes acceptance evidence
|
||||
- **WHEN** browser acceptance passes
|
||||
- **THEN** it MUST write or print evidence including stack URLs, seed evidence directory, routes checked, required assertions, fallback scan results, forbidden-fragment scan results, and plugin/server operation proof
|
||||
|
||||
#### Scenario: Suite cleans up self-started services
|
||||
- **WHEN** the suite starts local debug services itself
|
||||
- **THEN** it MUST stop or reset only the documented local debug root after completion or failure, using the same safe reset scope as the local debug workspace
|
||||
@@ -0,0 +1,65 @@
|
||||
## 1. Acceptance Harness and Command Shape
|
||||
|
||||
- [x] 1.1 Add an automated browser acceptance harness in the existing platform_web test/tooling structure, keeping route assertions near frontend code and stack orchestration in repository scripts.
|
||||
- [x] 1.2 Add a repository command wrapper for running browser acceptance against the local debug stack, with configurable `LOCAL_DEBUG_PLATFORM_PORT`, `LOCAL_DEBUG_WEB_PORT`, and `LOCAL_DEBUG_ROOT`.
|
||||
- [x] 1.3 Ensure the command can self-start or explicitly reuse the documented local debug stack, and records the resolved platform URL, platform_web URL, log paths, and evidence directory.
|
||||
- [x] 1.4 Ensure self-started runs clean up with `scripts/local-debug-reset.sh` and only remove allowed local debug roots.
|
||||
|
||||
## 2. Local Debug Fixture Prerequisites
|
||||
|
||||
- [x] 2.1 Reuse `scripts/local-debug-smoke.sh` or equivalent platform-owned setup before browser assertions so `game.example`, `server-local-debug`, and `run-local-debug` exist.
|
||||
- [x] 2.2 Fail early when platform health, API login, plugin manifest validation, plugin registration, run heartbeat, server lifecycle fixture creation, or job/log/artifact/marketplace references are missing.
|
||||
- [x] 2.3 Preserve the existing browser/API boundary: platform_web must use `PLATFORM_API_PROXY` and `VITE_PLATFORM_API_BASE_URL=/api/v1`, with `VITE_ENABLE_LOCAL_AUTH_FALLBACK=false`.
|
||||
- [x] 2.4 Keep fixture commands harmless and bounded, with no Docker-only dependency, real game binaries, raw credentials, raw AI keys, direct sockets, or browser/plugin direct access to run.
|
||||
|
||||
## 3. Browser Route Assertions
|
||||
|
||||
- [x] 3.1 Automate login at platform_web with `operator.local@example.test` / `operator-local` and verify the session lands on an API-backed workspace.
|
||||
- [x] 3.2 Verify 首页 `#/home` includes API-backed platform overview signals such as `平台概览`, `数据已加载`, game/plugin instance counts, and run node state.
|
||||
- [x] 3.3 Verify 服务器管理 `#/servers` includes `Local Debug Example Server` and `server-local-debug`.
|
||||
- [x] 3.4 Verify 插件市场 `#/plugins` includes `game.example`, installed state, manifest reference metadata, lifecycle capabilities, platform-mediated permissions, and bridge actions.
|
||||
- [x] 3.5 Verify 用户管理 `#/users` includes API-connected account data for `operator.local@example.test`.
|
||||
- [x] 3.6 Verify AI 提供商管理 `#/aiProviders` includes API-backed provider rows with redacted key references only.
|
||||
|
||||
## 4. Plugin and Server Operation Surface Assertions
|
||||
|
||||
- [x] 4.1 Verify server detail `#/servers/server-local-debug` includes `Local Debug Example Server`, `game.example@0.1.0`, `run-local-debug`, lifecycle controls, logs, config, plugin controls, AI assistant, and operation history entry points.
|
||||
- [x] 4.2 Trigger or inspect a platform-mediated lifecycle operation and verify platform-owned job or operation-history evidence without requiring direct run access from browser or plugin pages.
|
||||
- [x] 4.3 Verify log and artifact entry points are represented by logical IDs, platform routes, log refs, artifact refs, or safe metadata only.
|
||||
- [x] 4.4 Record route-level assertion results in machine-readable evidence, including URL, required markers, and plugin/server operation proof.
|
||||
|
||||
## 5. Safety and Fallback Scanning
|
||||
|
||||
- [x] 5.1 Add a shared fallback scanner that fails on local/demo/fallback workspace indicators on all accepted routes.
|
||||
- [x] 5.2 Add a shared visible-content forbidden-fragment scanner for `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details.
|
||||
- [x] 5.3 Ensure scanner failures report the route, matched fragment class, and safe nearby evidence without printing raw credentials.
|
||||
- [x] 5.4 Confirm sensitive values remain hidden from browser-visible output while safe redacted references such as `secret://...` or `env://...` are allowed when expected.
|
||||
|
||||
## 6. Documentation and Verification
|
||||
|
||||
- [x] 6.1 Document the browser acceptance command and expected evidence output in the appropriate local debug or frontend development documentation.
|
||||
- [x] 6.2 Run `LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance <browser-acceptance-command>` and record the exact final command after implementation.
|
||||
- [x] 6.3 Run `LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/local-debug-smoke.sh` or document why the acceptance command already ran the same smoke prerequisite.
|
||||
- [x] 6.4 Run `cd platform_web && npm run typecheck && npm test && npm run build` and record evidence.
|
||||
- [x] 6.5 Run relevant touched-root checks, including `cd plugins && npm run typecheck && npm run test && npm run validate:manifest`, `cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1`, and `cd run && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1` when implementation touches those roots or local debug orchestration.
|
||||
- [x] 6.6 Run `scripts/check-structure.sh` and record evidence.
|
||||
- [x] 6.7 Run `openspec validate implement-browser-acceptance-suite --strict` and record evidence.
|
||||
- [x] 6.8 Update `openspec/changes/architecture-delivery-stream/delivery-plan.md` and `openspec/changes/architecture-delivery-stream/NEXT_CHANGE.md` after implementation evidence exists, then stop without implementing `polish-platform-interaction-design` unless explicitly asked.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Implemented `platform_web/acceptance/browser-acceptance.mjs`, `scripts/browser-acceptance.sh`, `platform_web` package script `acceptance:browser`, and documentation in `docs/local-debug-workspace.md` plus `platform_web/README.md`.
|
||||
- `node --check platform_web/acceptance/browser-acceptance.mjs` passed.
|
||||
- `bash -n scripts/browser-acceptance.sh` passed.
|
||||
- `LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh` passed after clearing a stale listener from an earlier interrupted run.
|
||||
- Browser acceptance evidence: `/private/tmp/browser-local-debug-acceptance/browser-acceptance/browser-acceptance-evidence.json`, checked at `2026-07-08T05:13:43.494Z`.
|
||||
- Acceptance command ran `scripts/local-debug-smoke.sh` as a prerequisite and wrote seed evidence under `/private/tmp/browser-local-debug-acceptance/smoke`.
|
||||
- Browser routes verified: 首页, 服务器管理, 插件市场, 用户管理, AI 提供商管理, 服务器详情, and 服务器详情 / 插件控制.
|
||||
- Operation proof verified platform API accepted `process.start` for `server-local-debug`, platform-owned jobs endpoint returned `server-lifecycle:server-local-debug:start:e93f12eb71c03646`, and browser operation history exposed platform task records without direct run access.
|
||||
- `cd platform_web && npm run typecheck && npm test && npm run build` passed: 11 test files and 49 tests passed, Vite production build succeeded.
|
||||
- `cd plugins && npm run typecheck && npm run test` passed: 1 test file and 11 tests passed.
|
||||
- `cd plugins && npm run validate:manifest` passed after an escalated rerun because sandboxed `tsx` IPC failed with `listen EPERM`.
|
||||
- `cd platform && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1` passed.
|
||||
- `cd run && GOCACHE=/private/tmp/browser-go-build-cache go test ./... -count=1` passed after an escalated rerun because sandboxed `httptest` localhost binding failed with `listen tcp6 [::1]:0: bind: operation not permitted`.
|
||||
- `scripts/check-structure.sh` passed.
|
||||
- `openspec validate implement-browser-acceptance-suite --strict` passed. OpenSpec emitted PostHog DNS flush warnings after validation, but the command exited 0 and reported `Change 'implement-browser-acceptance-suite' is valid`.
|
||||
Reference in New Issue
Block a user