#Archived: Web Editor ↔ VS Code Extension Parity Audit

Historical record only. The self-hosted Web Editor and API were retired on 2026-09-26. Their frontend, server, and product-specific packages are no longer maintained. Shared contracts, SQL/runtime engines, and UI components remain in the repository where VS Code or companion extensions consume them.

Last updated: 2026-09-26

This document is the feature-by-feature parity audit between the two products formerly shipped from this repository:

• Desktop — the VS Code extension (src/, media/, extensions/, 158 core palette commands).
• Web — apps/web (React + Monaco + TanStack) + apps/api (Fastify server) running the shared SQL core.

This is a frozen historical snapshot, not an active backlog. Its Web statuses describe the product at retirement.

Companion implementation references: docs/LSP_FEATURE_MATRIX.md (LSP transport), docs/EDITOR_CAPABILITY_MATRIX.md (desktop editor capability status), the former Web Editor deployment guide, retained only in repository history. Cross-cutting readiness and quality gates are owned by docs/PROJECT_QUALITY_ROADMAP.md; parity status alone does not make a feature production-ready.

#Web renderer status at retirement

At retirement, the production Web entrypoint mounted DockyardWorkspace; SharedWebWorkspace remained only as a component-test fixture for portable reducer and presentation tests. There was no VITE_UI_MODE runtime switch or shared-renderer rollback path. The Web Dockyard implementation owned shell composition; this audit covered feature parity inside that shell.

The former shell owned durable query documents, per-document execution and result identities, multi-statement status/cancellation, typed result export, schema/database context, history, Explain, guarded designer flows, and the common React Result Grid through the shared ui-core/ui-react controllers. Persistence is a versioned, product-scoped envelope containing document metadata/content, document order, the active document, connection context, and the Dockyard layout snapshot; it excludes credentials, result rows, DOM nodes, and runtime handles.

Notebook, chart, tuning, and other host-specific database operations were explicit capability gaps rather than implied parity. VS Code keeps its own renderer and host lifecycle; the former Web product used the shared React renderer.

#1. Why parity is much closer than it looks

The web backend runs in Node and reuses the platform-neutral Netezza SQL core instead of a regex port:

• apps/api/src/lspProtocol.ts → apps/api/src/sqlCoreLsp.ts → @justybase/sql-core, which composes the Chevrotain parser, native NetezzaSqlSemanticValidator, completion/authoring helpers and QualityEngineCore with API-owned metadata and transport state.
• Completion and diagnostics in the web therefore already carry the same parser-backed behavior as the desktop, including SQL003/004/007/025/026 and completion ranking.
• Query execution, metadata listing and export reuse @justybase/database-runtime, @justybase/spreadsheet-tasks and the same operator contracts.

Consequence: most remaining "parity" work lives in the web surface (API+UI) and in shimming the other desktop LSP handlers into the API adapter, not in re-implementing SQL logic or importing desktop sources into sql-core.

#2. Legend

#Parity status

#Effort (for the missing/partial backlog items)

#Backlog priority

P0 = safety/regression risk, P1 = high value for cost, P2 = nice-to-have.

#3. Domain summary

Fast summary: web covers SQL authoring, single/smart/script execution, result exploration, guarded writes, and schema browsing well. The principal gaps are advanced desktop-only code actions and database administration, advanced result analysis, and remote multi-dialect runtimes. Test depth for the React surface is still behind its implemented functionality; see the quality roadmap.

#D1 – SQL Language / Editor Intelligence

D1 core wiring shipped 2026-08-09 — hover/definition/references/rename/inlayHints/signatureHelp/ documentSymbols/format are composed by apps/api/src/sqlCoreLsp.ts from the platform-neutral package, with JSON-RPC in apps/api/src/lspProtocol.ts and Monaco providers in apps/web/src/sqlLanguage.ts.

D1 leftovers shipped 2026-08-09 (same day) — semantic tokens, snippets, statement window also wired end-to-end by the API product adapter (apps/api/src/sqlCoreLsp.ts), with JSON-RPC textDocument/semanticTokens/full + justybase/statementNav, Monaco semantic-tokens provider

• snippet completions + Ctrl/Cmd+Up/Down statement nav. Core/API tests: apps/api/tests/sqlCoreFeatures.test.ts (8/8).

Commit 1 — NZ/NZP linter diagnostics shipped 2026-08-09 — SqlQualityEngine refactored into a thin VS Code adapter around the vscode-free QualityEngineCore in @justybase/sql-core (the desktop adapter is src/sqlParser/qualityEngineCore.ts); desktop behavior unchanged (guard: linterCodeActions, sqlQualityEngine.unified, linterRules.commentRegression, 83 tests). core.diagnostics() now runs NZ/NZP quality rules and transports parser suggestedFix via data.suggestedFix through JSON-RPC and Monaco markers. Core/API coverage lives in apps/api/tests/sqlCoreFeatures.test.ts and the shared browser gate.

D1 authoring parity refresh 2026-09-12 — the shared Web authoring path now exposes the complete connection-profile dialect catalog, live completion checks for PostgreSQL, Db2, ClickHouse, Oracle and MSSQL, and an Extension Host Definition Provider check for CTE navigation. Deterministic shared quick fixes are available through the same WebSocket LSP contract; full desktop refactor actions remain intentionally separate.

#D2 – Query Execution Pipeline

#D3 – Results Grid (shared Web renderer + desktop compatibility)

#D3 deep-dive — current web grid and remaining backlog

Key architecture fact: VS Code desktop is a DOM grid with a Node host; Web and Web uses the React/TanStack grid over an async REST/WS spool. Full-result aggregation and grouping already execute against the API SQLite spool; client features operate on the loaded page. Public request/response types remain additive and the Web renderer is shared without forcing the VS Code webview onto React.

Suggested order: version and deeply test grid state → harden guarded edit and copy semantics → improve pivot UX → consider advanced cards/charts only after the React coverage gate in the quality roadmap.

Regression risk: 🟢 none to desktop — this is apps/web + apps/api only. The one rule that applies is the shared-contracts additive rule: any new request/response types (QueryAggregateRequest, pivot spec) must add to @justybase/contracts/webApi.ts, never re-type existing fields.

#Architecture decision (updated 2026-09-12)

One renderer across VS Code and Web remains out of scope; the products retain their appropriate host boundaries.

• VS Code grid (media/resultPanel) is vanilla-DOM + disk-backed, wired to the VS Code host (protocol.ts); Web uses a React/TanStack renderer with an async REST/WS spool.
• Web consumes the shared @justybase/ui-react DataGrid and shared view, clipboard, context-action, and viewport contracts. This gives the two application shells identical behavior while preserving the low-risk VS Code renderer boundary.
• If pure logic sharing is ever wanted, extract it into a framework-agnostic @justybase/grid-core (formatting, aggregation math, clipboard generators, pivot/group SQL, edit-UPDATE builder) — additive, web-first, desktop adopts later. This remains a follow-up opportunity, not a prerequisite for Web/VS Code parity.

#D4 – Schema Explorer & Metadata

#D5 – Database Ops (import / DDL / DBA / maintenance)

Desktop-only note: Db2 and MySQL now have dedicated Index Designer and Partition Manager webviews in the VS Code extension. PostgreSQL and SQLite retain their existing command-based index/partition workflows; these are not webviews.

The generic write boundary is implemented: read-only profiles reject writes, mutable operations require an exact short-lived preview token and explicit confirmation, and execution is audited. Remaining D5 work is guided workflow depth and provider-specific SQL, not creation of an unguarded generic endpoint.

#D6 – Multi-dialect support

The shared connection contract and forms expose every supported DatabaseKind. Profiles retain the selected dialect, so Monaco completion, snippets, diagnostics, signature help, formatting and semantic authoring use the selected profile. The API runtime registry currently executes Netezza, SQLite and DuckDB; remote profiles are clearly labelled authoring-only and keep save/test/run/schema/DDL controls disabled until an explicit server-side driver/runtime adapter, metadata provider, capability declarations and live contract are added.

SQLite and DuckDB are already available in the web API for local profiles, metadata, query sessions, paging, aggregation and grouping. The remaining work is parity polish (file-SQL workflows, capability-specific runtime gates, and controlled remote runtime adapters). Add remote execution only with explicit runtime isolation and integration coverage.

#D7 – Platform / Security / Multi-user

(No desktop-parity backlog applies to web-native controls. Follow-up work is role-based connection sharing and deeper adversarial/security coverage.)

#D8 – Advanced / AI / MCP / Favorites / Syntax color

#Summary table

#Recommended backlog order

1. Quality foundation: add React component coverage, version and test persisted tab/grid state, and enforce the high-risk gates in the project quality roadmap.
2. Editor completion: expose the remaining context-sensitive NZ/NZP quick fixes and parser-backed refactors through the web LSP/code-action surface.
3. Grid hardening: deepen reload/race/accessibility tests, improve pivot UX, and close copy/edit semantics before considering charts and cards.
4. Database workflows: deepen DDL generation and import UX on top of the existing preview-token/read-only/audit boundary; add dedicated destructive actions only with provider contracts and confirmation tests.
5. Dialect expansion: polish SQLite/DuckDB capability parity, then add remote runtimes one at a time behind the common dialect contract and live coverage.

Copilot, visual ETL, the test-data generator, ERD/visualizers, and notebooks are P2 product decisions. They are not prerequisites for web editor quality or core database workflow parity.

#Regression risk model (does web-parity risk the desktop extension?)

Short answer: the desktop extension and web are runtime-isolated — dist/extension.js and the web server are separate processes, nothing in apps/web executes in desktop, and desktop is unaffected by web-only code. The shared Netezza package is platform-neutral; desktop and API adapters are separate composition layers, so the remaining risk is contract/parity drift rather than a hidden desktop import in the web build.

#Risk tiers per backlog area

#Desktop side-guardrails (already in place, do not relax)

npm run check-types && npm run lint && npm run build && npm run test:validate
LSP_BENCHMARK_ENFORCE=1 npm run benchmark:lsp      # parseCalls ≤ 1, latency budgets
npm run test:completion-parity && npm run test:quickfix-regression

#Hard rules to keep desktop regression-safe

1. No vscode import may enter sql-core. Add a lint/import guard if desired; the platform: node esbuild build fails loudly if it sneaks in.
2. Web must use the engines; never fork them. Duplicating a rule/engine in apps/ to save a refactor is the real drift/regression time-bomb. If something is vscode-bound, extract the pure core into src/ (shared) and keep a thin vscode wrapper, don't copy.
3. Desktop-first refactors (e.g. NZ linter extraction) ship as isolated commits with their own tests, never inside a web-feature commit.
4. Contracts changes are additive-only, with node scripts/version-sync.js check passing.

#Verification

Every completed item must keep these green:

# full desktop validation
npm run check-types && npm run lint && npm run build && npm run test:validate

# web + api
npm run build:all
npm run check-types:api && npm run test:api        # includes apps/api/tests/sqlCore*.test.ts
npm run check-types:web && npm run build:web && npm run test:web

# D1 core shared-surface regression (this hierarchy blocks desktop impact)
node scripts/build-sql-core.js && npm run test:api

LSP-parity work must add tests against the parser (never only integration) — per docs/EDITOR_CAPABILITY_MATRIX.md "First-class" standard.