Contracts and edge cases

Platform spec article

Contracts and edge cases

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
  Package kinds

  packageKind discriminators

Contracts

• HTTPS in production — Operators should configure BESKID_PCKG_URL with TLS endpoints; clients honor redirects per reqwest defaults.
• Auth mutual exclusion — Bearer and API key flags must not be combined on one invocation.
• Structured api.json — Library packs should include compiler-emitted .beskid/docs/api.json as the docs UI contract (see api.json contract).
• Readme artifact name — Packed readmes must appear as root README.md in the zip for dashboard listing.
• Template discriminator — Template packs must set packageKind: template and ship .beskid/template.json.

Edge cases

Case	Behavior
Missing Project.proj at pack root	Defaults to library profile without template metadata
Invalid manifest during pack	PckgError::Api with BAD_REQUEST semantics
Missing auth on publish	MissingAuthToken before HTTP
Large trees	Walkdir-based collection; operators exclude build outputs via manifest/layout conventions
iconUrl on publish	Server validates HTTP(S) URLs and length caps (PackageManifestMetadata)

Server rejection mirrors

Client-side pack should prevalidate paths the server will reject (docs layout, workspace member consistency) to avoid wasted uploads; integration tests live in pckg/src/Server.Tests/.