browser/openspec/changes/add-scum-file-config-workbench/specs/scum-file-config-workbench/spec.md

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: Raw file content is a bounded declared-file snapshot

Platform SHALL expose raw configuration or log text only from the latest completed files.read result for the same server and a plugin-declared logical file key.

Scenario: Declared file result is ready

• WHEN an authorized operator requests the raw view of a declared file after its read job completes
• THEN Platform MUST return only that file's bounded content, logical key, version, checksum, and read state
• AND THEN the response MUST NOT contain a host path, a generic job execution payload, or another file's content

Scenario: Declared file is not read yet

• WHEN no successful declared-file read is available for the selected file
• THEN Platform MUST return an explicit pending or not-read state without inventing file contents

Scenario: Raw file contains a secret-like assignment

• WHEN a completed declared-file result includes a secret-like key=value assignment
• THEN Platform MUST redact the assignment value before returning the raw snapshot

Requirement: SCUM workbench has one active file surface

The SCUM workbench SHALL keep declared directory/file navigation separate from the selected file content, rather than stacking every declared file and every unrelated SCUM feature on one page.

Scenario: Operator selects a declared configuration file

• WHEN an operator selects ServerSettings.ini or another declared configuration file
• THEN the workbench MUST show only that file's metadata and supported modes in the content pane
• AND THEN modeled fields MUST be limited to fields owned by that selected file

Scenario: Operator switches a selected configuration file to raw mode

• WHEN an operator activates the raw configuration mode for a selected declared configuration file
• THEN the workbench MUST show only the most recent Platform-mediated file result or an explicit not-yet-read state
• AND THEN an editable declared configuration file MAY expose a raw editor only after a completed read snapshot is available
• AND THEN raw-mode changes MUST require a visible diff preview before dispatching a declared logical files.write request
• AND THEN it MUST NOT expose a host path, arbitrary file selector, or unrestricted text editor

Scenario: Operator selects a declared log file

• WHEN an operator selects a declared log file
• THEN the workbench MUST replace the configuration controls with that log file's declared read surface
• AND THEN the log raw view MUST stay read-only and support switching between UTF-8 and UTF-16 LE display

Requirement: Embedded SCUM file management avoids duplicate page chrome

When the SCUM workbench is rendered inside a server detail section, the frontend SHALL render it without a second plugin page frame, host-context panel, or unrelated Companion feature panels.

Scenario: Server detail opens SCUM file management

• WHEN an operator opens the SCUM 文件管理 section in server detail
• THEN the first workbench surface MUST be the declared directory/file navigation and selected file content
• AND THEN the page MUST NOT render a nested PLUGIN PAGE title or 平台托管上下文 panel

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