Extension surface

Platform spec feature

Extension surface

Back to VS Code extension ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (5)

1. 0001-four-activity-bar-views Four views Accepted

   Four views

   Context

   Extension UX.

   Decision

   Four views under one container.

   Consequences

   beskid_vscode runtime.

   Verification anchors

   package.json; runtime tests.

   Open full ADR page

2. 0002-focused-project-uri focusedProjectUri Accepted

   focusedProjectUri

   Context

   Extension UX.

   Decision

   Single focus drives outline and packages.

   Consequences

   beskid_vscode runtime.

   Verification anchors

   package.json; runtime tests.

   Open full ADR page

3. 0003-pckg-client-only-http pckgClient only Accepted

   pckgClient only

   Context

   Extension UX.

   Decision

   Registry HTTP via pckgClient only.

   Consequences

   beskid_vscode runtime.

   Verification anchors

   package.json; runtime tests.

   Open full ADR page

4. 0004-lsp-graph-data-only LSP graph only Accepted

   LSP graph only

   Context

   Extension UX.

   Decision

   Graph via LSP executeCommand only.

   Consequences

   beskid_vscode runtime.

   Verification anchors

   package.json; runtime tests.

   Open full ADR page

5. 0005-shared-status-controller Status controller Accepted

   Status controller

   Context

   Extension UX.

   Decision

   One status bar for LSP, pckg, CLI.

   Consequences

   beskid_vscode runtime.

   Verification anchors

   package.json; runtime tests.

   Open full ADR page

Articles

• Contracts and edge cases focusedProjectUri, LSP executeCommand JSON, auth, and offline registry behavior. article Standard Reviewed Thu May 21
• Design model Extension layout, focus model, and status-bar phases for the Beskid VS Code extension. article Standard Reviewed Thu May 21
• Examples corelib workspace and single-app project scenarios. article Standard Reviewed Thu May 21
• FAQ and troubleshooting Common questions about focus, private registries, offline mode, and LSP restarts. article Standard Reviewed Thu May 21
• Flow and algorithm Activation through LSP init, tree refresh, and package search. article Standard Reviewed Thu May 21
• Verification and traceability Tests, CI, and smoke checks for the VS Code extension surface. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 14 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  VS Code extension

  Parent area

• Feature
  Workspace and project explorer

  Workspaces and Project tree views

• Feature
  Package manager panel

  Packages view and pckgClient

• Area
  LSP

  Language client and executeCommand host

• Area
  CLI

  Tasks and package mutations

• Feature
  Workspace and lock contracts

  defers-to — manifest and lock semantics

What this feature specifies

Extension surface is the cross-cutting contract for the Beskid VS Code extension: four activity-bar views, the focusedProjectUri focus model, language-client initialization and configuration sync, shared status-bar phases (LSP scan, registry, CLI), and palette commands that tie explorers, outline, packages, and tasks together.

Implementation anchors

• beskid_vscode/package.json — contributes.views, commands, configuration, taskDefinitions
• beskid_vscode/src/extension.ts, runtime/BeskidExtensionRuntime.ts, lsp/beskidLanguageClient.ts
• beskid_vscode/src/status/beskidStatusController.ts
• LSP: compiler/crates/beskid_lsp/src/server/init.rs, backend.rs

Contract statement

The extension must present Workspaces, Project, Outline, and Packages views under a single Beskid view container. Outline continues to reflect symbols for the focused project; Packages and Project must share focusedProjectUri. Registry HTTP must use pckgClient only; workspace graphs must use LSP executeCommands documented in workspace and project explorer.

Inputs and outputs

Input	Output
VS Code workspace folders	LSP workspace roots; explorer workspace list
User focus (tree, auto-select, beskid.selectProject)	focusedProjectUri → LSP + dependent views
Settings (beskid.cli.path, beskid.pckg.*, beskid.project.*)	Client behavior, registry URL, CLI spawn
LSP progress / scan	Status bar phases for analysis
User package/CLI actions	Status phases search, details, fetch, lock, build, …

State model

State	Storage	Consumers
focusedProjectUri	workspaceState + LSP server	Project tree, outline, packages ThisProject
Language client handle	Extension runtime	All LSP requests
Status controller snapshot	In-memory	Single status bar item
pckg caches	pckgClient	Packages view only

Algorithms and flow

See flow and algorithm for activation → LSP init → tree refresh → package search.

Edge cases and errors

• Server path change: Full language-client restart required.
• Focus-only change: Configuration notification only (see explorer feature).
• Offline registry: Packages registry section errors; LSP/local sections remain usable.
• Missing beskid on PATH: CLI commands must fail with explicit notification referencing beskid.cli.path.

Compatibility and versioning

• Extension engine pin and Open VSX platform matrix remain governed by publish workflow (darwin-arm64 / darwin-x64 LSP target pairing).
• selectedProjectUri deprecated in favor of focusedProjectUri for one release cycle.

Security and performance notes

• Secrets only in SecretStorage.
• Debounce file watchers and registry search.
• Do not restart LSP on focus churn.

Examples

See examples for corelib workspace and single-app project walkthroughs.

Verification and traceability

See verification and traceability for CI, unit, and smoke anchors.

Decisions

No open decisions. ADRs D-TOOL-VSC-0001 … 0005 under adr/; use the ADRs tab. Area index: decisions record.

Related features

• Workspace and project explorer
• Package manager panel
• Snapshot and refresh contract

Newcomer reading order

1. VS Code extension area
2. This hub → Design model → Contracts → Flow → Examples → Verification
3. Child features workspace explorer and package panel for depth

Articles

• Four viewsFour views
• Contracts and edge casesfocusedProjectUri, LSP executeCommand JSON, auth, and offline registry behavior.
• Design modelExtension layout, focus model, and status-bar phases for the Beskid VS Code extension.
• Examplescorelib workspace and single-app project scenarios.
• FAQ and troubleshootingCommon questions about focus, private registries, offline mode, and LSP restarts.
• Flow and algorithmActivation through LSP init, tree refresh, and package search.
• Verification and traceabilityTests, CI, and smoke checks for the VS Code extension surface.