Design model

Platform spec article

Design model

Back to Package manager panel ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-single-pckg-client-boundary pckgClient boundary Accepted

   pckgClient boundary

   Context

   HTTP scatter.

   Decision

   HTTP via pckgClient.ts only.

   Consequences

   Shared auth.

   Verification anchors

   Grep fetch in packages/.

   Open full ADR page

2. 0002-cli-for-lock-mutations CLI for lock Accepted

   CLI for lock

   Context

   Lock integrity.

   Decision

   Use beskid fetch/lock via CLI.

   Consequences

   Shared resolver.

   Verification anchors

   Panel CLI invocations.

   Open full ADR page

Articles

• Contracts and edge cases pckgClient HTTP rules, authentication, caching, and package command contracts. article Standard Reviewed Thu May 21
• Decisions record (legacy index) Migration index for package manager panel ADRs. article Standard Reviewed Fri May 22
• Design model PackageTreeItem sections, pckgClient surface, cache keys, and Packages view chrome. article Standard Reviewed Thu May 21
• Examples Corelib locked dependencies and registry search in the Packages view. article Standard Reviewed Thu May 21
• Flow and algorithm Package search, details expansion, fetch/lock, and focus-driven refresh sequences. 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 · 5 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

• Feature
  Package manager panel

  Parent feature hub

Purpose and scope

Tree structure for beskidPackagesView, the pckgClient TypeScript contract, and status-bar activity phases shared with LSP and CLI.

View layout

The Packages view lives in container beskidViews alongside Workspaces, Project, and Outline (see extension surface design model).

flowchart TB
  subgraph packagesView [beskidPackagesView]
    TP[ThisProject section]
    RS[RegistrySearch section]
    TP --> D1[Declared/Locked dependency rows]
    RS --> Q[Search results]
    Q --> V[Version nodes]
    V --> Dep[Dependency leaves]
  end

Root sections must always be visible (not hidden behind empty search).

PackageTreeItem kinds

section	kind	Children
ThisProject	section	Dependency rows from LSP
ThisProject	dependency	Optional context actions only
RegistrySearch	section	Search prompt or results
RegistrySearch	searchResult	Package summary node
RegistrySearch	version	Collapsible version metadata
RegistrySearch	registryDependency	Dependency of selected version

Icons: dependency package; unresolved warning; registry package cloud-download.

pckgClient functions (normative)

Function	HTTP	Cache key
searchPackages({ q, limit, registryBaseUrl })	GET {base}/api/search?q=…&limit=…	search:{base}:{q}:{limit} ~30s TTL
getPackageDetails({ name, registryBaseUrl })	GET {base}/api/packages/{name}	details:{base}:{name}
buildRegistryPackageUrl({ name, version, registryBaseUrl })	—	N/A (string builder)
createPckgFetch(context)	—	Injects auth from SecretStorage

All functions must use createPckgFetch for transport.

Response typing (camelCase)

Align TypeScript types with pckg records:

• PackageSearchResponse: { package, reviewCount, health }
• PackageDetailsResponse: { package, versions, dependencies, dependentsCount, readme, health, … }
• PackageDependencyResponse: { name, version, source, registry }

Registry base URL resolution

1. If focused project belongs to a workspace, use registries entry with alias: "default" from beskid.getWorkspaceSummary.
2. Else vscode.workspace.getConfiguration('beskid.pckg').get('baseUrl').
3. Else http://localhost:5000.

Status-bar phases

Extend shared PckgActivityPhase (and CLI phases) with:

Phase	When
search	Registry search in flight
details	Package details fetch
fetch	beskid fetch running
lock	beskid lock running

LSP scan phases remain separate on the same status controller.

View title and welcome actions

Action	Command
Search	beskid.packages.search
Refresh	beskid.packages.refresh
Fetch	beskid.packages.fetch
Lock	beskid.packages.lock

View welcome content should offer “Search registry…” when RegistrySearch is empty.

Related topics

• Contracts — auth and endpoint tables
• pckg client contract