Flow and algorithm

Platform spec article

Flow and algorithm

Back to pckg client contract ◎ 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-hub-authority Hub authority Accepted

   Hub authority

   Context

   One client story.

   Decision

   Hub owns HTTP and auth.

   Consequences

   Extension defers.

   Verification anchors

   beskid_pckg; pckgClient.

   Open full ADR page

2. 0002-registry-assigned-versions Registry versions Accepted

   Registry versions

   Context

   Manual semver drift.

   Decision

   Registry-assigned publish versions in routine flows.

   Consequences

   UI shows server version.

   Verification anchors

   publish API tests.

   Open full ADR page

Articles

• Contracts and edge cases Registry client guarantees and failure modes. article Standard
• Design model Conceptual model for the Beskid pckg registry client (`beskid_pckg`). article Standard
• Examples Example `beskid pckg` invocations and configuration. article Standard
• FAQ and troubleshooting Common pckg client and registry issues. article Standard
• Flow and algorithm Pack, upload, and query flows for the pckg registry client. article Standard
• Verification and traceability Tests and traceability for the pckg client contract. article Standard

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 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
  pckg client contract

  Parent feature hub

beskid pckg pack algorithm

flowchart TD
  A[Resolve source root] --> B[detect_pack_profile]
  B --> C[collect_pack_entries walk]
  C --> D[apply_pack_readme]
  D --> E[build_package_json]
  E --> F[ZipWriter + SHA256]
  F --> G[.bpk artifact]

1. Read Project.proj when present; choose PackProfile::Library or Template.
2. Walk files (respect template exclude strips via strip_template_pack_excludes).
3. Include .beskid/docs/** and package docs for library profiles.
4. Copy resolved readme to zip root README.md when not already present.
5. Emit package.json metadata (registry assigns version on publish—clients do not invent release versions in normal flows).

Publish / upload

1. Build or locate .bpk bytes.
2. PckgClient::send_multipart to registry upload endpoint with publisher auth.
3. Server runs PackageArtifactValidator + documentation ingestion; failures return structured API errors mapped to PckgError::Api.

Fetch into workspace

beskid fetch (CLI command in beskid_cli) uses registry URLs from Workspace.proj and downloads through PckgClient, writing materialized roots recorded later in Project.lock. Version resolution follows registry-assigned versions, not ad-hoc client version strings.

Version state file

Pack may persist local version hints in .beskid/pckg state (PackVersionState) for iterative dev publishes; production CI should rely on server-assigned versions after upload.

Error handling

All HTTP failures surface as PckgError with status, message, and optional body text suitable for --verbose CLI output.