Merge pull request #90 from CedaryCat/develop

docs: document Command System V2 and Atelier REPL

Author: CedaryCat

GitVersion.yml

@@ -23,7 +23,7 @@ commit-date-format: 'yyyy-MM-dd'
 # Ignore merge commits (except those that should trigger releases)
 merge-message-formats: '^Merge (branch|tag|pull request)'
 
-next-version: 'v0.2.1'
+next-version: 'v0.3.1'
 
 # Branch-specific configuration
 branches:

README.md

@@ -77,6 +77,8 @@ These are reachable directions, even though the launcher does not currently ship
 | 🛡 **Bundled TShock port** | Ships with a USP-adapted TShock baseline ready for use |
 | 💻 **Per-context console isolation** | Independent, auto-reconnecting console I/O windows for each world context, plus semantic readline prompts and live status bars |
 | 🚀 **RID-targeted publishing** | Publisher produces reproducible, runtime-specific directory trees |
+| ⚡ **Command System V2** | A brand-new declarative command framework — 200+ TShock commands already migrated, with smart context-aware completion built in. Plugins define commands as structured declarations; the framework handles binding, permissions, output, and audit logging across terminal, player, and REST endpoints |
+| 🧪 **Atelier REPL** | A Roslyn-powered C# workspace running inside the live runtime. Write and run code against real server state, get IDE-quality completion and diagnostics, and iterate without restarting — a proper workbench for operators and developers alike |
 
 ---
 
@@ -555,6 +557,8 @@ graph LR
 | **Config registration** | Configs stored in `config/<PluginName>/`, supports auto-reload (`TriggerReloadOnExternalChange(true)`) |
 | **Collectible contexts** | `ModuleLoadContext` enables unloadable plugin domains |
 
+Command System V2 is the recommended way to expose commands from plugins. Controllers are declared with attributes, and the framework handles discovery, endpoint binding, parameter parsing, and permission checks automatically. The same declaration also drives completion candidates, help text generation, and audit logging — so there is no separate usage string to maintain.
+
 → Full guide: [Plugin Development Guide](./docs/dev-plugin.md)
 
 ---
@@ -596,6 +600,8 @@ This table reflects the currently maintained/documented packaging targets, not e
 | `linux-arm` | ⚠️ Partial support / needs manual verification |
 | `osx-x64` | ✅ Supported |
 
+If you want to inspect or script against a running world without writing a full plugin, Atelier REPL gives you a Roslyn workspace attached to the live runtime. You can run persistent C# sessions, query server state, call plugin APIs, and run background tasks — all without restarting. See [docs/dev-overview.md](./docs/dev-overview.md#28-atelier-repl) for session setup and meta-command reference.
+
 ---
 
 <a id="resources"></a>

docs/README.zh-cn.md

@@ -77,6 +77,8 @@ UnifierTSL 把 [OTAPI Unified Server Process](https://github.com/CedaryCat/OTAPI
 | 🛡 **内置 TShock 移植基线** | 内置适配 USP 的 TShock 基线，开箱可用 |
 | 💻 **上下文级控制台隔离** | 默认为每个世界实例提供独立、自动重连的控制台窗口 IO，以及语义化 readline 提示与实时状态栏 |
 | 🚀 **按 RID 发布** | Publisher 生成可复现、面向目标运行时的目录结构 |
+| ⚡ **命令系统 V2** | 全新声明式命令体系——200+ 条 TShock 命令已完成迁移，并内置智能上下文感知补全。插件通过属性标注声明命令结构，框架统一处理绑定、权限、输出和审计日志，覆盖终端、玩家和 REST 三类入口 |
+| 🧪 **Atelier REPL** | 直接运行在运行时内部的 Roslyn C# 工作台。针对真实服务器状态编写并执行代码，享有媲美 IDE 的补全与诊断体验，无需重启即可迭代——运维和开发都能用得上的正经工具 |
 
 ---
 
@@ -556,6 +558,8 @@ graph LR
 | **配置注册** | 配置存放在 `config/<PluginName>/`，支持自动重载（`TriggerReloadOnExternalChange(true)`） |
 | **可回收上下文** | `ModuleLoadContext` 支持可卸载的插件域 |
 
+命令系统 V2 是插件暴露命令的推荐方式。控制器通过属性标注声明，框架负责发现、端点绑定、参数解析和权限检查，同一份声明还会自动派生出补全候选、帮助文本和审计日志，不需要单独维护 usage 字符串。完整的 API 参考和代码示例可以在插件开发指南里找到。
+
 → 完整指南：[插件开发指南](./dev-plugin.zh-cn.md)
 
 ---
@@ -597,6 +601,8 @@ dotnet run --project src/UnifierTSL.Publisher/UnifierTSL.Publisher.csproj -- \
 | `linux-arm` | ⚠️ 部分支持 / 仍需人工验证 |
 | `osx-x64` | ✅ 支持 |
 
+如果你想在不写完整插件的情况下探索或操作运行中的世界，Atelier REPL 提供了一个直接附着在运行时上的 Roslyn 工作台。你可以在持久会话里逐步构建脚本、查询服务器状态、调用插件 API，也可以把长时间运行的操作放到后台执行——整个过程不需要重启。会话配置和元命令参考可以在 [dev-overview.zh-cn.md](./dev-overview.zh-cn.md#28-atelier-repl) 里找到。
+
 ---
 
 <a id="resources"></a>

docs/dev-overview.md

@@ -15,6 +15,8 @@ Welcome! This doc walks you through how the UnifierTSL runtime is put together o
   - [2.4 Networking & Coordinator](#24-networking--coordinator)
   - [2.5 Logging Infrastructure](#25-logging-infrastructure)
   - [2.6 Configuration Service](#26-configuration-service)
+  - [2.7 Command System V2](#27-command-system-v2)
+  - [2.8 Atelier REPL](#28-atelier-repl)
 - [3. USP Integration Points](#3-usp-integration-points)
 - [4. Public API Surface](#4-public-api-surface)
   - [4.1 Facade (`UnifierApi`)](#41-facade-unifierapi)
@@ -55,6 +57,8 @@ Welcome! This doc walks you through how the UnifierTSL runtime is put together o
 - `ModuleAssemblyLoader` – takes care of module staging, dependency extraction, collectible load contexts, and unload order.
 - `EventHub` – the central event registry that bridges MonoMod detours into priority-sorted event pipelines.
 - `Logging` subsystem – lightweight, allocation-friendly logging with metadata injection and pluggable writers.
+- `CommandSystem` – the declarative command framework: catalog, endpoint compiler, dispatcher, Prompt projection, and audit integration.
+- `AtelierPlugin` + `ReplSession` – the Roslyn-based interactive REPL, providing persistent sessions, real-time diagnostics, code completion, and a Surface-based windowed UI.
 
 ## 2. Core Services & Subsystems
 
@@ -1495,7 +1499,171 @@ For more logging examples, see `src/Plugins/TShockAPI/TShock.cs` and `src/Unifie
 - Startup precedence for launcher settings is `config/config.json` -> CLI overrides -> interactive fallback for missing port/password, and the effective startup snapshot is persisted back to `config/config.json`. After startup, edits to `config/config.json` apply to the launcher settings that support reload.
 - Root-config hot reload applies `launcher.serverPassword`, `launcher.joinServer`, additive `launcher.autoStartServers`, `launcher.listenPort` (via listener rebind), `launcher.colorfulConsoleStatus`, and `launcher.consoleStatus`.
 
-## 3. USP Integration Points
+<a id="27-command-system-v2"></a>
+### 2.7 Command System V2
+
+The command system v2 replaces the traditional string-callback model with a declarative, attribute-driven framework. Controllers are `static` classes; actions are static methods. The framework discovers these at install time, compiles them into endpoint-specific catalogs, and handles dispatch, parameter binding, permission checks, and output formatting — all from the same set of declarations.
+
+<details>
+<summary><strong>Expand Command System V2 implementation deep dive</strong></summary>
+
+#### Architecture Overview
+
+The system has five distinct layers, each handling a specific concern:
+
+**Discovery layer** (`src/UnifierTSL/Commanding`): `CommandSystemDiscovery` reflects over controller types to build a `CommandCatalog` — an immutable snapshot of all registered commands, their action paths, parameter signatures, and metadata. Reflection only happens at install time; runtime dispatch never touches it again.
+
+**Compilation layer** (`src/UnifierTSL/Commanding/Endpoints`): `CommandEndpointCatalogCompiler` takes the generic catalog and produces endpoint-specific bindings. Each endpoint type (terminal, TShock player, REST) has its own context requirements. Actions that don't satisfy an endpoint's constraints are excluded from that endpoint's catalog at compile time, not at dispatch time.
+
+**Dispatch layer** (`src/UnifierTSL/Commanding/Execution`): `CommandDispatchCoordinator` receives raw input, tokenizes it via `CommandLineLexer`, routes to the matching root and action, runs guard checks, binds parameters, invokes the action, and hands the `CommandOutcome` to the appropriate outcome writer.
+
+**Prompt layer** (`src/UnifierTSL/Commanding/Prompting`): `CommandPrompting` projects endpoint bindings into `PromptAlternativeSpec` objects. The same command definition that drives execution also drives completion candidates, semantic highlighting, and parameter hints.
+
+**TShock layer** (`src/Plugins/TShockAPI/Commanding`): Adds TShock-specific endpoint types, permission model, domain binders (player, group, region, warp, etc.), and audit log integration. The core layer stays generic; TShock semantics live entirely in the plugin. Importantly, this is an integration and extension of Command System V2 rather than a separate parallel stack, so TShock-oriented plugins can usually build directly on that existing surface instead of inventing their own command bridge.
+
+In practice, the UTSL-TS command architecture is split by ownership:
+
+- **UTSL core owns the neutral command engine**: discovery, catalog building, endpoint compilation, dispatch, generic binding rules, and prompt projection.
+- **TShock owns the game/admin-facing adaptation**: player/REST-facing endpoints, TShock permission semantics, domain binders, and TShock-specific outcome/audit behavior.
+- **Plugins choose the highest-level surface that already matches their needs**: if you are building a TShock-style admin/gameplay command, you usually attach at the TShock layer instead of re-expressing those same semantics from scratch over raw V2 primitives.
+
+#### Data Flow
+
+```
+CommandSystem.Install(configure)
+    ↓
+CommandSystemDiscovery → CommandCatalog (immutable snapshot)
+    ↓
+CommandEndpointCatalogCompiler → per-endpoint root/action bindings
+    ↓
+CommandPrompting → PromptAlternativeSpec (completion / highlighting)
+
+[User input arrives]
+    ↓
+CommandDispatchCoordinator
+    ↓
+CommandLineLexer: tokenize → prefix, root, args
+    ↓
+CommandEndpointDispatcher: path match → guard checks → parameter binding
+    ↓
+Action invoked → CommandOutcome
+    ↓
+OutcomeWriter: receipt + attachment + log → terminal / player / REST
+```
+
+#### Immutable Catalog and Atomic Swap
+
+`CommandSystem` maintains a registration dictionary. Each install or uninstall rebuilds `CommandSystemState` under the registration lock, then replaces the current snapshot. External readers consume that snapshot through `Volatile.Read`, so they always see a consistent state. Registration IDs keep ordering stable across rebuilds, which matters for help text and completion candidate stability.
+
+`ValidateConflicts` runs during install to catch duplicate root names and aliases before any user can hit the ambiguity at runtime.
+
+#### Static Controllers and the No-State Rule
+
+`CommandSystemDiscovery` requires controllers to be `static` classes with static methods. This is a deliberate constraint: controllers are declaration containers, not service instances. Runtime state flows in through injected parameters (`CommandInvocationContext`, `CancellationToken`, and `[FromAmbientContext]` values such as `ServerContext` or `TSExecutionContext`). This makes the catalog easy to snapshot, rebuild, and unload, and it prevents plugins from smuggling mutable instance state into the command lifecycle.
+
+#### Endpoint Binding Validation
+
+The endpoint compiler validates parameter constraints at compile time. If an action requires a server-scoped ambient value such as `[FromAmbientContext] ServerContext`, but the endpoint can't provide one, the compile fails at install time rather than at dispatch time. This catches mismatches before any user can trigger them.
+
+#### Mismatch Handlers
+
+Each controller can have at most one `[MismatchHandler]`. It fires when the root matches but the action path or parameters don't. Mismatch handlers can only consume injected values — they can't declare user-bound parameters. This prevents error handling from becoming a second command parser.
+
+#### Parameter Binding Sources
+
+| Source | Description |
+|--------|-------------|
+| User tokens | Positional arguments from the command line |
+| Remaining text / args | Everything after the last bound token, as string or `string[]` |
+| Flags | Named options extracted from any position in the token list |
+| Invocation context | `CommandInvocationContext` |
+| Cancellation token | For long-running or background operations |
+| Ambient context | `[FromAmbientContext]` values such as `ServerContext`, `TSExecutionContext`, and background activity feedback objects |
+
+Scalar types (`string`, `bool`, `int`, numeric types, `enum`) bind directly from tokens. Complex types use `CommandBindingAttribute` subclasses. TShock adds domain-specific binders for `TSPlayer`, `Group`, `Region`, `Warp`, `UserAccount`, and more. `CommandInvocationContext` and `CancellationToken` are recognized implicitly; other runtime values come from the ambient execution context when explicitly marked.
+
+</details>
+
+#### Best Practices
+
+1. **Keep controllers stateless** — inject context through parameters, not fields
+2. **Declare permissions on TShock actions** — the dispatcher enforces them before binding
+3. **Prefer the TShock integration when that's your target surface** — plugins like `CommandTeleport` can use the TShock-facing V2 facilities directly instead of building a second command-access layer
+4. **Use implicit bindings for common domain types** — register them once in the binding registry
+5. **Add a mismatch handler** — it's the user-facing error surface for your command tree
+6. **Let the catalog drive help text** — don't maintain separate usage strings
+7. **Validate at install time** — declare context requirements so the compiler catches mismatches early
+
+<a id="28-atelier-repl"></a>
+### 2.8 Atelier REPL
+
+Atelier is a Roslyn-based interactive C# workspace embedded in the Unifier runtime. It goes well beyond "run a script" — it provides persistent sessions with incremental compilation, real-time diagnostics, code completion, signature help, semantic highlighting, virtual bracket pairing, console output redirection, background task tracking, and a Surface-based windowed UI.
+
+<details>
+<summary><strong>Expand Atelier REPL implementation deep dive</strong></summary>
+
+#### Session Model
+
+`ReplSession` (`src/Plugins/Atelier/Session`) maintains a Roslyn `ScriptState` that grows incrementally with each submission. Two execution modes are available:
+
+- **Persistent submit**: compiles on top of the current state and updates session state. Variables, imports, and definitions persist across submissions.
+- **Transient run**: executes against the current state but discards the result. Useful for one-off queries or validation without polluting session state.
+
+Sessions can target the launcher context or a specific running server. The target determines which globals are in scope — every session gets `Launcher`, `Log`, `HostLabel`, `TargetLabel`, `Cancellation`, `PendingTasks`, and `LastTask`, while server-targeted sessions additionally expose `Server`, a wrapper around the target `ServerContext` with dispatcher, peer, and snapshot helpers.
+
+#### Roslyn Workspace Integration
+
+The REPL maintains a Roslyn workspace alongside the execution state (`src/Plugins/Atelier/Session/Roslyn`). The workspace tracks the current document and provides language services:
+
+- **Diagnostics**: real-time error/warning markers as you type, before you submit
+- **Completion**: context-aware candidate lists triggered by `.` or manual request
+- **Signature help**: method overload display when you open a call's parenthesis
+- **Semantic highlighting**: type-aware coloring beyond syntax
+
+A warmup pass runs after initialization to pre-load Roslyn's core assemblies, reducing first-use latency.
+
+#### Draft vs. Source
+
+The REPL maintains two text buffers:
+
+- **Draft**: what the user sees, including virtual bracket hints and other visual aids
+- **Source**: the actual source text used for compilation and execution
+
+This separation lets the UI provide rich visual feedback without corrupting the code that Roslyn actually compiles.
+
+#### Surface Window Lifecycle
+
+The REPL window uses `ISurfaceSession` and an interaction scope (`src/Plugins/Atelier/Presentation/Window`). On close, the system terminates the scope, unsubscribes events, unbinds the console, cancels pending reads, drains the command queue, cancels processing, disposes the surface session, and finally releases the `ReplSession`. This sequence ensures clean resource release with no dangling references.
+
+#### Plugin Assembly References
+
+The REPL can reference currently loaded plugin assemblies, giving scripts direct access to plugin public APIs. When a referenced assembly changes (plugin reload or unload), the session is marked invalid. Users see a prompt explaining why and can open a fresh session against the updated assemblies.
+
+#### Meta-Commands
+
+Meta-commands start with `:` and control the REPL itself rather than executing C# code:
+
+| Command | Effect |
+|---------|--------|
+| `:help` | Show available meta-commands |
+| `:reset` | Reset session state |
+| `:clear` | Clear the output area |
+| `:imports` | List baseline/effective imports and reference paths |
+| `:target` | Show the current target and invocation host |
+| `:paste [on|off]` | Toggle paste mode for multi-line submissions |
+| `:transient <code>` | Run transient code without committing it |
+
+Background work is tracked through `PendingTasks` and `LastTask`; there is no separate `:jobs` or `:cancel` meta-command in the current implementation.
+
+</details>
+
+#### Best Practices
+
+1. **Use transient mode for queries** — it doesn't pollute session state
+2. **Target the right context** — launcher context for global state, server context for world-specific operations
+3. **Watch for session invalidation** — plugin reloads will mark your session stale
+4. **Use background tasks for long operations** — the REPL stays responsive while they run
+5. **Prefer `:reset` over closing and reopening** — it's faster when you just want a clean slate
 
 - `ServerContext` inherits USP's `RootContext`, plugging Unifier services into the context (custom console, packet receiver, logging metadata). Everything that touches Terraria world/game state goes through this context.
 - The networking patcher (`UnifiedNetworkPatcher`) detours `NetplaySystemContext` functions to share buffers and coordinate send/receive paths across servers.