eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
Imports the previously untracked working tree as-is so that the review
changes that follow (requirements -> design -> implementation) can be
reviewed as diffs and reverted if needed. No content changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:18:04 +08:00
..

WishForge Theia application

This independent Node/browser application pins Eclipse Theia 1.76.0 and @theia/collaboration. It is intentionally excluded from the root npm workspaces because Theia has a large dependency tree and native modules. Its own lockfile is the reproducible installation boundary. It provides the actual IDE framework, not the console's source-code preview panel.

cd apps/ide
PUPPETEER_SKIP_DOWNLOAD=true npm ci
npm run plugins:download
npm run build
npm start

The local address is http://127.0.0.1:4300. Start OCT using the ide Compose profile for isolated protocol checks only. Room admission uses an isolated instance per workspace behind the gateway. The local @wishforge/ide-policy extension disables room commands/status unless WF_COLLABORATION_GATEWAY_URL names the current authenticated workspace route; the start wrapper blocks public OCT fallback. WISHFORGE_WORKSPACE_PATH selects the workspace directory. Native builds need Python, make/C++ and the OS development libraries; Linux prerequisites are included in the Dockerfile.

The pinned VS Code built-in extension archive supplies the Git, language and JavaScript debugging extensions. Its vscode.python package supplies Python syntax/grammar support; it is not a Python debugger. plugins:download also installs the separately pinned ms-python.python 2026.4.0 dependency and ms-python.debugpy 2026.6.0, with the debugger's bundled Python libraries, and ms-pyright.pyright 1.1.402 for Python completion, hover and diagnostics. No global pip installation is needed. Python itself must be present in the workspace image or a project virtual environment; set its path in launch.json. Download completion and each runtime interaction must be checked. Theia 1.76 no longer publishes the legacy @theia/git or @theia/preview packages; this package uses SCM/plugin support and @theia/editor-preview.

Python debugger installation and acceptance

npm run plugins:download:python downloads only these three pinned Python packages. The lockfile at scripts/python-debugger.lock.json pins official Open VSX VSIX checksums for Linux x64/ARM64 and macOS x64/ARM64. Unsupported platforms fail explicitly. The downloader checks the SHA-256, package identity, size and extraction paths, then unpacks each extension atomically: Theia's system local-dir loader does not load a bare VSIX. For an offline build, supply the three already-downloaded files:

npm run plugins:download:python -- --archive /path/to/debugpy.vsix --python-archive /path/to/python.vsix --pyright-archive /path/to/pyright.vsix
npm run plugins:verify

The local macOS ARM64 acceptance used Theia 1.76.0 and Python 3.14.5 through the authenticated gateway. Without a debugger lease F5 was rejected by the backend; after acquiring control, a real Python process paused at a line-2 breakpoint with count: 1, and F10 advanced to line 3 with count: 2. The call stack and variables were visible. The debug process was stopped and the prior Node launch config restored. Evidence: /private/tmp/wishforge-python-debug-ui.json and /private/tmp/wishforge-python-debug-controller.png.

The same local browser also verified Python/Pyright and the existing bundled TypeScript service separately: string-method completion, a typed function hover, and an invalid numeric argument reported by Pyright(reportArgumentType) and ts(2345) respectively. Temporary source fixtures were removed afterward; no package installation or network pip command was involved. Evidence: /private/tmp/wishforge-language-services-ui.json, with language-specific completion/hover/diagnostic PNGs under /private/tmp/wishforge-. The upstream INVALID tab diagnostic remains recorded; these checks do not assert that every IDE interaction is warning-free.

Linux and macOS x64 packages are pinned but have not received runtime acceptance. Pylance and Python Environments are recommendations, not installed dependencies; their workflows are outside this acceptance. Pyright provides the separately verified language services. The backend still reports upstream localization/activation and Node-version warnings, so this is not a zero-warning compatibility claim.

Operator-managed extensions

Extensions can be viewed in the IDE, whose extension view is marked “管理员管理”. Dynamic registry/VSIX installation, updates, removal and enable/disable requests are rejected by the backend with EXTENSIONS_MANAGED_BY_ADMIN, including requests that claim to be system extensions. Direct deployer/bulk paths are also closed. This applies in development and production; hiding a button is not the enforcement mechanism.

At startup the backend loads only the image's fixed system directory. It ignores user extension directories, THEIA_PLUGINS, recommendations and injected install arguments. The initial catalog contains 92 built-in extensions from the official 1.108.2 archive plus the three Python extensions (95 in total). Every builtin's ID, version and file-content digest must match policy/managed-plugins.lock.json; Python files must match their SHA-pinned official VSIX contents. Missing, extra or altered extensions fail closed. npm run plugins:verify runs the same checks at image build time. Python bytecode generation is disabled to keep installed content immutable.

The builtin catalog is generated from the exact upstream archive, whose published SHA-256 is 05a20cf3e671c8d328b04d9ce72b25688b0e762e4a3f5592f31a21ee38280367. node scripts/catalog-builtin-plugins.mjs /path/to/vscode-builtin-extensions-1.108.2.tar.gz reproduces it only after verifying that archive. It does not approve or sign an arbitrary runtime plugin directory. Changes to approved packages require an operator-reviewed lockfile/image update and compatibility acceptance.

Seven focused tests cover the real Theia server/deployer classes, forged system arguments, direct/bulk mutation calls, retained installed-plugin reads, additional plugins, altered content/version and symlinks. In the rebuilt local IDE a real “Install Extension VSIX” action reached ManagedPluginServer.install and was rejected with EXTENSIONS_MANAGED_BY_ADMIN; the administrator notice and existing Python/debugger entries remained visible. Evidence is recorded in /private/tmp/wishforge-managed-extensions-ui.json.

The Docker image leaves the application, plugins and catalog root-owned; only the workspace is handed to the runtime user. Production also requires the provisioner's read-only root filesystem. A local writable checkout and a terminal running as the backend's same UID can still alter that backend or its policy: these installation gates are not hard isolation against hostile users sharing such a workspace.

Production boundary

Theia itself is a privileged workspace process: terminal, file, plugin and debug APIs must sit behind an authenticated workspace gateway and tenant-specific runtime. Never expose port 4300 directly. The start wrapper requires WISHFORGE_GATEWAY_ENFORCED=true in production; that flag is an operator assertion, not an implemented gateway or a security test. Use TLS, per-workspace origins/cookies, WebSocket origin checks, short-lived audience-bound sessions, and authorize every upgrade and API request.

Only project owners/editors may enter an editing workspace or OCT room. Viewers use the console's read-only code review surface; they must not receive an IDE session or room token. Theia 1.76's built-in collaboration read-only controls are not complete, so a hidden button is not an authorization boundary. The workspace ACL-to-OCT bridge and actual two-browser co-edit/save flow have local acceptance evidence. The policy extension also implements coordinated saved revisions, IndexedDB draft comparison recovery and a backend-enforced debugger lease; see policy/README.md. Production CNI and hostile-terminal isolation remain separate requirements. Collaboration is disabled when the dedicated instance and current workspace gateway path are absent.

OCT 0.3.1 stores session state in memory. A volume or a saved room ID does not make the CRDT/session durable. On restart, restore saved workspace files and metadata, start a new room, reauthorize members, and show that unsaved edits may be absent. Do not claim lossless room recovery, multi-host failover or horizontal scaling.

Before agent integration/build/deploy, a save barrier must gather active editor acknowledgements at one revision, persist changes, freeze a commit/snapshot and bind validation to its digest. A timeout or concurrent edit invalidates the barrier. The policy extension now implements this coordinated snapshot command using actual editor callbacks and a durable revision store. The human commits the saved workspace and explicitly imports that snapshot into the run. The API and worker compare its exact Git bytes, revision and activity before integration/build, and hold a fenced project integration lease. A new edit invalidates the input and returns the run to waiting. This gate is implemented; automatic human-repository synchronization remains separate. See workspace handoff and verified status.

Sources: Theia architecture, Theia 1.76 collaboration source, OCT 0.3.1 source, official builtin release, Python debugger, Open VSX debugger package, fixed Pyright package.