feat(scum): add file config workbench

2026-07-28 14:43:24 +08:00
parent e739dd9c79
commit e4ef4024a8
22 changed files with 397 additions and 109 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-28
@@ -0,0 +1,43 @@
+## Context
+
+The SCUM plugin already declares runtime config mappings and log sources, while Platform exposes safe configuration read/diff/approval APIs and a scoped file-operation dispatcher. Its current plugin page is an operations overview with semantic logs; this does not match the operator's configuration-first workflow.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make plugin-owned logical file declarations the single catalog for SCUM configuration and log file scopes.
+- Model safe configuration fields separately from the raw INI content, then compose changes into the existing Platform diff-preview and approval flow.
+- Present declared log files and their Platform log-stream contents in the same workbench.
+- Redirect historical SCUM page keys to the default `files-config` page without breaking shared plugin routing.
+
+**Non-Goals:**
+
+- Arbitrary filesystem browsing, path entry, terminals, FTP/rsync controls, raw secrets, or host/socket exposure.
+- Raw text as the default configuration editor, write access for unknown fields, or a new run-side protocol.
+- Changing global server-list behavior or non-SCUM plugin pages.
+
+## Decisions
+
+1. Add `fileWorkspace` to the plugin manifest/runtime projection. It contains safe logical directories/files and modeled fields, rather than host paths or unbounded schemas. This makes a page contract auditable and keeps ownership with the plugin.
+2. Give every modeled field an owning logical file key, Chinese operational metadata, and constrained control details. The frontend uses only these fields to compose proposed INI content; unmapped lines remain visible as read-only field records.
+3. Reuse `GET /config`, config diff preview, and config approval for the declared primary config file. Log-file selection maps declared logical files to existing Platform log streams; no new direct file-read API is introduced.
+4. Move SCUM from `operations` to `files-config`; the route resolver redirects old `overview`, `config`, `logs`, and `operations` keys only for `game.scum`. Other plugins keep their declared page keys unchanged.
+5. Build page content from existing shared console form/list/diff classes. No page-owned surface system or global decoration is added.
+
+## Risks / Trade-offs
+
+- [A config document may contain extra keys] → preserve them in the proposed content and show them as read-only, unmodeled rows.
+- [Existing installations still link old route keys] → normalize those keys in the common resolver before page lookup.
+- [A declared log stream is absent] → show an explicit unavailable state and never fall back to a filesystem path.
+- [INI parsing has formatting limits] → patch only declared simple key/value fields and rely on Platform preview before approval.
+
+## Migration Plan
+
+1. Ship manifest and Platform declaration validation/projection with the SCUM `files-config` page.
+2. Deploy the frontend route normalization and workbench; old SCUM links resolve to `files-config`.
+3. Rollback by restoring the previous manifest page declaration; no persisted migration or write protocol needs reversal.
+
+## Open Questions
+
+None. The first field catalog uses existing SCUM deployment mappings and can be expanded through manifest declarations later.
@@ -0,0 +1,25 @@
+## Why
+
+SCUM operators currently reach separate overview, configuration, and semantic-log surfaces, even though their routine operational work begins with declared files and safe, modeled settings. The default SCUM work surface needs to make configuration actionable without revealing host paths or turning raw text editing into the normal workflow.
+
+## What Changes
+
+- Replace the SCUM overview-first experience with a unified `文件与配置` workbench whose default scope is the plugin-declared configuration directory.
+- Add plugin-declared logical file directories/files and a modeled configuration-field catalog, including Chinese labels, help, control metadata, constraints, defaults, restart impact, and owning file.
+- Reuse Platform-mediated file requests and the existing configuration diff-preview/approval/write flow so modeled changes are previewed before dispatch.
+- Expose logs as declared log files inside the same workbench, with separate safe log-file scope; retain unknown configuration fields as read-only information.
+- Safely migrate legacy SCUM overview/config/log routes to the new workbench.
+
+## Capabilities
+
+### New Capabilities
+- `scum-file-config-workbench`: Declared SCUM file scopes, modeled configuration editing, log-file viewing, and safe route migration.
+
+### Modified Capabilities
+- `config-write-and-file-dispatch`: File dispatch and config approval now consume declared logical directories/files and field ownership metadata.
+- `scum-operations`: SCUM's primary operator surface changes from an overview to the file-and-configuration workbench.
+
+## Impact
+
+- Affects the SCUM plugin manifest/declarations, Platform plugin validation and safe file/config DTO handling, and SCUM frontend contracts/routes/components.
+- Reuses `files.request`, existing server configuration diff/approval/write APIs, and the SCUM runtime profile without expanding filesystem or remote-access authority.
@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: Declared field ownership constrains config editing
+Platform-projected plugin declarations SHALL associate each modeled configuration field with a declared logical file key so the frontend can invoke existing diff and approval APIs without accepting arbitrary file targets.
+
+#### Scenario: Preview uses an owning declared config file
+- **WHEN** a modeled field change is previewed
+- **THEN** the frontend MUST use the field's declared logical file key and MUST NOT accept a host path or user-supplied target key
@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: SCUM declares safe file workspace catalog
+The SCUM plugin SHALL declare logical configuration and log directories/files and a bounded modeled configuration-field catalog without raw host paths, secrets, credentials, sockets, or arbitrary schemas.
+
+#### Scenario: Default configuration scope is declared
+- **WHEN** an authorized operator opens the SCUM file-and-configuration page
+- **THEN** the page MUST select the plugin-declared configuration directory and list only its declared logical files
+
+#### Scenario: Unsafe declaration is rejected
+- **WHEN** a plugin manifest includes an absolute path, traversal key, secret-like value, or unsupported field control
+- **THEN** Platform MUST reject the manifest before it is registered
+
+### Requirement: Modeled SCUM fields are configuration-first
+The SCUM workbench SHALL render modeled fields with Chinese label, explanation, input type, constraint, default, restart impact, and owning file, and SHALL keep unmodeled fields read-only.
+
+#### Scenario: Operator changes a modeled field
+- **WHEN** an operator changes a declared editable field
+- **THEN** the workbench MUST compose only that field into the owning configuration file and require a diff preview before approval
+
+#### Scenario: Unknown configuration is encountered
+- **WHEN** the loaded configuration includes a key outside the declared field catalog
+- **THEN** the workbench MUST show it as read-only and MUST NOT present it as a safe editable control
+
+### Requirement: Logs are file scope in the same workbench
+The SCUM workbench SHALL present plugin-declared log files as a log-file scope and display their Platform-mediated stream content.
+
+#### Scenario: Operator opens a declared log file
+- **WHEN** an operator selects a declared SCUM log file
+- **THEN** the page MUST query only its declared Platform log stream and show readable file content without host-path disclosure
+
+### Requirement: Legacy SCUM pages migrate safely
+The frontend SHALL migrate legacy SCUM overview, config, logs, and operations page keys to the `files-config` page while leaving non-SCUM routing unchanged.
+
+#### Scenario: Legacy SCUM operations link is opened
+- **WHEN** a user opens a SCUM plugin URL with the legacy `operations` key
+- **THEN** the frontend MUST resolve it to the declared `files-config` workbench for the same server context
@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: SCUM primary surface is file and configuration workbench
+The SCUM plugin SHALL expose `files-config` as its primary operator page rather than an overview-first or semantic-log-dashboard page.
+
+#### Scenario: SCUM plugin page opens
+- **WHEN** a user opens the declared primary SCUM page for a server instance
+- **THEN** the page MUST prioritize declared configuration files and modeled configuration controls before log-file browsing
@@ -0,0 +1,16 @@
+## 1. Plugin and Platform declaration contract
+
+- [x] 1.1 Add safe logical file-directory/file and modeled-field contracts to plugin manifests, Platform domain/DTO projections, copying, and validation.
+- [x] 1.2 Declare SCUM configuration/log files and bounded Chinese configuration field metadata, then remove legacy SCUM overview page declarations.
+- [x] 1.3 Add focused Platform validation/projection tests for safe declaration and field ownership behavior.
+
+## 2. SCUM file and configuration workbench
+
+- [x] 2.1 Add frontend declaration contracts and resolver for the SCUM `files-config` default workbench and legacy route migration.
+- [x] 2.2 Build the shared-theme file list, modeled configuration form, read-only unknown-field list, preview diff, and approval experience.
+- [x] 2.3 Add declared log-file scope and Platform log stream content reading without path exposure.
+
+## 3. Verification
+
+- [x] 3.1 Add/update focused backend, plugin, route, contract, and component tests.
+- [x] 3.2 Run strict OpenSpec validation, relevant backend/plugin/frontend checks, and scripts/check-structure.sh.