veric-extension

VS Code Web extension that lets users open Veric workspaces inside their existing VS Code, Cursor, or VS Code Web (vscode.dev / github.dev) install. Dual-published to the Microsoft Marketplace (veric.veric-extension) and Open VSX (veric/veric-extension).

Design doc: docs/multi-surface-uplift/surface-3-extension.md.

Targeting

This extension is web-targeted — the manifest sets browser (not main), the esbuild config sets platform: "browser", and the source must not import any Node-only API (fs, child_process, path.resolve, etc.). A web-targeted extension is the only form that runs in all three of vscode.dev, desktop VS Code, and Cursor (see design doc §2).

Scope (0.3.0)

Phases 3.1 – 3.8 are now live:

• Commands veric.hello, veric.run, veric.showResult, veric.showTransportLog, veric.importFile, veric.exportFile.
• VericFsProvider against the in-memory bridge shim (src/fs/bridge-shim.ts). A real remote-VFS swap-in is queued for Phase 4.8.
• vscode-languageclient/browser language client for .while files, configured via the veric.lspUrl setting.
• vscode.AuthenticationProvider (id veric) + OAuth URI handler.
• Result webview panel mounting <ResultCard/> from @veric/views-react over a WebView HostBridge transport.
• Direct kernel transport (0.3.0). veric.run resolves a kernel bridge from the cross-realm Symbol.for("veric.ide.kernel-bridge") first (so the embedded /ide route stays a thin client); when no bridge is published, the extension self-constructs one against the veric.kernelUrl endpoint (default wss://kernel.veric.dev/rpc). Bearer auth is plumbed via the Sec-WebSocket-Protocol subprotocol carrier.

Settings

Every contributed veric.* setting is listed here in one place; this table is the human-readable mirror of apps/extension/package.json contributes.configuration. A CI gate (pnpm settings-doc-check → scripts/check-settings-doc.mjs) fails any PR that adds a setting to the manifest without documenting it here, and vice-versa.

Scripts

Two test layers

The extension has two complementary test layers:

1. vitest unit tests under tests/ mock the vscode module via tests/setup.ts. They run on plain Node, cover every provider / command handler in detail, and are the workhorse for TDD iteration.
2. Mocha real-host smoke under test/host/ runs inside a real VS Code spawned by @vscode/test-electron or @vscode/test-web. It asserts that the manifest + the bundled dist/extension.js actually register the contributed commands / FS provider / auth provider against the genuine host. The CI publish workflow gates on pnpm test (the unit layer); the host suite is run locally and in nightly CI to catch manifest / bundler regressions that the mock layer can't see.

Release process (Phase 3.6)

Dual-publish is automated by .github/workflows/extension-publish.yml. The workflow fires on tags matching extension-v* (e.g. extension-v0.2.1) and on manual workflow_dispatch runs (dispatch defaults to dry_run=true — it builds + packages but skips the actual Marketplace / Open VSX uploads).

To cut a release:

1. Bump version in apps/extension/package.json to the new semver.
2. Open a PR with just the bump, get it merged to main.
3. From a clean checkout of main:

   git pull
   VERSION=$(node -p "require('./apps/extension/package.json').version")
   git tag "extension-v${VERSION}"
   git push origin "extension-v${VERSION}"
   

4. Watch the workflow under Actions → extension-publish. On green, the new version is live on the Microsoft Marketplace (veric.veric-extension) and Open VSX (veric/veric-extension) within a few minutes.

Required repo secrets (one-time setup)

Before the first release, configure the following GitHub repo secrets in Settings → Secrets and variables → Actions:

The workflow has no fallback — if either secret is unset when a tag lands, the corresponding publish step fails loudly. That's intentional: missing secrets must not silently skip publishing.