Design model

Platform spec article

Design model

Back to Template packages ◎ Open feature 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

• Feature
  Template packages

  Parent feature hub

Purpose and scope

Normative beskid.package.v1 extensions and artifact layout for template packages.

package.json fields

Key	Required	Meaning
schema	yes	beskid.package.v1
id	yes	Registry package name
version	yes	Artifact version string
packageKind	yes for template profile	template
template	recommended	Summary: shortName, identity, tags.type copied from .beskid/template.json at pack time
documentation	—	Must not include apiJson pointer for packageKind: template

Default packageKind when omitted remains library for backward compatibility.

Reserved kinds

packageKind	Status
library	Current default; requires api.json when server policy RequireStructuredApiDoc is true
template	This feature
tool	Reserved; normative contract deferred to Package kinds

.bpk required entries (template profile)

Entry	Required
package.json with packageKind: template	yes
Project.proj	yes (authoring manifest; may be type: Template)
checksums.sha256	yes
.beskid/template.json	yes
src/** or template content roots	yes — at least one scaffold file
.beskid/docs/api.json	no

pckg package page (template mode)

When packageKind === template, the server and dashboard must:

1. Hide API documentation tabs, symbol browser, and api.json download.
2. Show template metadata card: shortName, tags.type, classifications, description.
3. Show install snippet: beskid new install <id> and beskid new <shortName>.
4. Show readme / root markdown when present.
5. Show version list with yank badges (same as libraries).

Category field on PackageEntity may mirror tags.type for filtering (Template, Console, etc.) but packageKind is authoritative for routing.

Workspace publish

Workspace bundles may include template member packages. Each member .bpk must declare its own packageKind. Mixed workspaces (libraries + templates) are allowed.

Diagram

flowchart LR
  PACK[beskid pckg pack]
  BPK[.bpk artifact]
  VAL[PackageArtifactValidator]
  REG[pckg registry]
  UI[Template package page]
  NEW[beskid new install]
  PACK --> BPK --> VAL --> REG --> UI
  REG --> NEW

Code anchors

• pckg/src/Server/Services/PackageArtifactValidator.cs
• pckg/src/Server/Components/Pages/ package detail views
• compiler/crates/beskid_pckg pack command (planned packageKind emission)