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>
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.