Template packages

Platform spec feature

Template packages

Back to Project scaffolding ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0001-explicit-package-kind Explicit packageKind Accepted

   Explicit packageKind

   Context

   Registry taxonomy.

   Decision

   Explicit packageKind on beskid.package.v1.

   Consequences

   pckg validators.

   Verification anchors

   Validator tests.

   Open full ADR page

2. 0002-template-registry-ui-mode Template UI mode Accepted

   Template UI mode

   Context

   Registry taxonomy.

   Decision

   Template pages hide API docs.

   Consequences

   pckg validators.

   Verification anchors

   Validator tests.

   Open full ADR page

3. 0003-no-api-json-for-templates No api.json Accepted

   No api.json

   Context

   Registry taxonomy.

   Decision

   template kind must not require api.json.

   Consequences

   pckg validators.

   Verification anchors

   Validator tests.

   Open full ADR page

Articles

• Contracts and edge cases Publish-time and UI rules for template packages on pckg. article Standard Reviewed Thu May 21
• Design model `packageKind`, `.bpk` layout, and pckg registry presentation for template packages. article Standard Reviewed Thu May 21
• Verification and traceability Server and CLI tests for template package profile. 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 · 10 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
  Project scaffolding

  Parent area

• Feature
  Project templates

  Engine consumes template packages

• Feature
  Package kinds

  Taxonomy

• Feature
  api.json contract

  Library packages only

• Feature
  pckg client contract

  Publish and download

What this feature specifies

Template packages — packageKind: template on beskid.package.v1, .bpk validation without api.json, and pckg registry UI that hides API documentation.

Implementation anchors

• pckg/src/Server/Services/PackageArtifactValidator.cs
• pckg package detail components (template page mode)
• beskid pckg pack — emit packageKind and .beskid/template.json

Contract statement

A template package is a published .bpk artifact whose root package.json declares packageKind: template. Template packages distribute .beskid/template.json and scaffold sources. They use the same versioning, yank, checksum, and registry-assigned publish semver as library packages, but different validation and pckg UI.

Inputs and outputs

Field	Rule
schema	beskid.package.v1 (unchanged)
id	Package id; first-party beskid.templates.*
packageKind	template (required for this profile)
version	Present in artifact; registry may assign publish version independently
Output	Downloaded .bpk → extracted template root for beskid new install

State model

Template packages must not be required to expose structured API documentation on the registry. The package detail route must use template page mode: readme, template metadata (shortName, tags.type, classifications), install command, and version history—no api.json viewer, no docs tree tabs for API reference.

Algorithms and flow

Pack: beskid pckg pack on a type: Template project must set packageKind: template in generated package.json and include .beskid/template.json plus template sources roots.

Publish: Same POST /api/packages/<id>/publish and workspace publish flows; server selects validator profile by packageKind.

Consume: beskid new install <id> downloads version, verifies kind, registers cache entry.

Edge cases and errors

• Library package accidentally packed without api.json — existing rule; template profile must not require api.json.
• Template package missing .beskid/template.json — reject at publish with HTTP 400.
• packageKind: library with template manifest present — reject or require repack as template.

Compatibility and versioning

Identical to library packages: immutable versions, yank semantics, registry-assigned bumps on upload.

Decisions

No open decisions. ADRs D-TOOL-SCAFF-0001 … 0003 (explicit packageKind, template registry UI, no api.json) under adr/; use the ADRs tab.

Verification and traceability

• pckg/src/Server/Services/PackageArtifactValidator.cs — template profile branch
• pckg Blazor package detail routing by packageKind
• Server tests: template .bpk publish without api.json

Articles

• Explicit packageKindExplicit packageKind
• Contracts and edge casesPublish-time and UI rules for template packages on pckg.
• Design model`packageKind`, `.bpk` layout, and pckg registry presentation for template packages.
• Verification and traceabilityServer and CLI tests for template package profile.