Package kinds

Platform spec feature

Package kinds

Back to Registry client ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

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

   packageKind field

   Context

   Registry taxonomy.

   Decision

   Explicit packageKind on package manifest.

   Consequences

   Validators and UI.

   Verification anchors

   Server tests.

   Open full ADR page

2. 0002-tool-kind-reserved tool reserved (superseded) Accepted

   Historical reservation of `packageKind: tool` without a normative profile; superseded by D-TOOL-PCKG-0004.

   Context

   When the packageKind field was introduced on beskid.package.v1, two kinds (library, template) had concrete validator profiles and dashboard routing; tool was anticipated but not yet specified. The team did not want the absence of tool rules to be interpreted as silent acceptance.

   Decision

   Reserve tool as a known-but-not-Standard packageKind value. The pckg server accepted the literal string but did not commit to validator behavior, dashboard routing, or CLI flags. Publishers were warned that the contract would land in a follow-up decision.

   Consequences

   • Validators recognised the kind without expanding the supported set: any deviation from the library profile would be a future, opt-in change.
   • The dashboard fell back to the library rendering for tool artifacts, which made the kind effectively invisible to users.
   • CLI tooling (beskid pckg pack) had no --package-kind flag, so publishers could not deliberately mark an artifact as tool.

   Verification anchors

   Verification responsibility transferred to D-TOOL-PCKG-0004; see 0004-tool-kind-standard.mdx for the current test surface.

   Open full ADR page

3. 0003-beskid-templates-prefix beskid.templates.* Accepted

   beskid.templates.*

   Context

   Registry taxonomy.

   Decision

   First-party templates use beskid.templates.* prefix.

   Consequences

   Validators and UI.

   Verification anchors

   Server tests.

   Open full ADR page

4. 0004-tool-kind-standard tool kind lifted to Standard Accepted

   Normative validator profile, CLI routing, and dashboard surface for packageKind tool.

   Context

   D-TOOL-PCKG-0002 reserved tool as a forbidden packageKind while validator profiles, CLI routing, and registry UI surfaces remained undefined. By the v0.3 baseline, three concrete needs converged:

   1. External tool packs (custom diagnostics, formatter rule packs, language-server extensions) want to ship through pckg without being mis-classified as library (which forces api.json generation) or template (which forces .beskid/template.json).
   2. The registry dashboard already routes library and template kinds to distinct surfaces via PackageDetails.razor. A third surface — with no Docs / Source tabs — is straightforward to add given the existing _isTemplatePackage pattern.
   3. The Beskid CLI already supports per-profile packing in beskid_pckg::pack::PackProfile. Extending the enum with a Tool variant and a --package-kind tool CLI flag is a localized change.

   The platform-spec leads code: this ADR makes the validator profile, CLI routing, and dashboard surface normative so the implementation can land without ambiguity.

   Decision

   Lift packageKind: tool from Reserved to Standard with the following normative profile:

   1. Server validator (PackageArtifactValidator) must accept packageKind: tool artifacts. The artifact must not contain .beskid/template.json; the artifact may contain .beskid/docs/api.json, but it must not be required by Pckg:Publish:RequireStructuredApiDoc. The packed package.json must not include documentation.apiJson for the tool kind.
   2. Publish persistence must record the resolved packageKind in the version metadata via the existing PackageManifestMetadataReader path.
   3. Dashboard routing (PackageDetails.razor) must mirror the template-kind pattern: an _isToolPackage flag selects an install/usage card and suppresses the Docs / Source tabs by default. The Ratings tab and Versions tab remain unchanged.
   4. Rust pack flow (beskid_pckg::pack) must add a PackProfile::Tool variant and the build_package_json path must emit "packageKind": "tool" without a documentation block. A new strip_tool_pack_excludes helper must remove .beskid/docs/api.json from the artifact body when the tool profile is selected.
   5. CLI surface (beskid_pckg::cli) must add a --package-kind <library|template|tool> flag to pack. When set to tool, the CLI must skip the api.json pre-generation pass in beskid_cli::cli::maybe_generate_docs_for_pack. The flag must refuse to combine with a Project.proj whose project.type = Template.

   Consequences

   • Forwards-compatible: Existing library and template artifacts are unaffected; pre-existing tool-rejection tests are updated rather than removed.
   • Server-side migration: PackageKinds.IsSupported now returns true for tool. Operators running validator policy RequireStructuredApiDoc = true see no behavior change for library packages; tool packages explicitly bypass that requirement.
   • CLI ergonomics: Publishers who want to ship a developer tool through the registry no longer need to hand-author package.json; the beskid pckg pack --package-kind tool flow handles it.
   • Dashboard parity: The pckg UI uses Fluent UI Blazor patterns for the new tool card, matching the existing template install card. No new design tokens are introduced.

   Verification anchors

   • pckg/src/Server.Tests/Unit/PackageArtifactValidatorTests.cs::ValidateAsync_Accepts_Tool_Artifact_Without_Api_Json
   • pckg/src/Server.Tests/Unit/PackageArtifactValidatorTests.cs::ValidateAsync_Rejects_Tool_With_Template_Json
   • pckg/src/Server.Tests/Integration/ToolPackagePublishIntegrationTests.cs
   • compiler/crates/beskid_pckg/src/pack.rs::tests::build_package_json_tool_profile_omits_api_doc_pointer
   • compiler/crates/beskid_pckg/src/pack.rs::tests::strip_tool_pack_excludes_removes_api_json
   • compiler/crates/beskid_pckg/src/cli.rs::tests::pack_args_accepts_package_kind_tool

   Open full ADR page

Articles

• No directly attached article pages for this node.

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 11 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
  Registry client

  Parent area

• Feature
  Template packages

  template kind

• Feature
  api.json contract

  library kind

• Feature
  Formatter

  a representative tool package consumer

• Feature
  Project manifest contract

  project.type parallels packageKind

What this feature specifies

The packageKind field on beskid.package.v1 — discriminates library, template, and tool packages, each with a normative validator profile, dashboard surface, and CLI routing. tool is Standard as of D-TOOL-PCKG-0004 (this feature) — the previous Reserved status (D-TOOL-PCKG-0002) is superseded.

Implementation anchors

• pckg/src/Server/Services/PackageKinds.cs — kind constants and IsSupported / IsTemplate / IsTool predicates
• pckg/src/Server/Services/PackageArtifactValidator.cs — per-kind validator profiles (library / template / tool)
• pckg/src/Server/Services/PackagePublishDocumentation.cs — exempts template and tool from structured api.json requirements
• pckg/src/Server/Components/Pages/PackageDetails.razor(.cs) — Fluent UI dashboard routing (badge, install-instructions card, hidden Documentation / Source tabs for template and tool)
• compiler/crates/beskid_pckg/src/pack.rs and cli.rs — Rust PackProfile (Library / Template / Tool), detect_pack_profile_with_override, strip_tool_pack_excludes, and beskid pckg pack --package-kind {auto,tool}

Contract statement

Every published beskid.package.v1 artifact must declare its role through packageKind. Kinds drive validator profiles, registry UI routing, and CLI behavior. Unknown packageKind values must be rejected at publish time with a structured BadRequest diagnostic, never a 500.

project.type on Project.proj is the project-tree analogue (Host, Mod, Template, …); packageKind is the registry artifact analogue—they are related but not interchangeable.

Normative kinds

packageKind	Purpose	api.json requirement	.beskid/template.json	Primary CLI
library (default)	Beskid source package consumed as dependency	Required when server policy mandates api.json	Forbidden	beskid pckg pack, consumer beskid fetch
template	Scaffold package for beskid new	Forbidden in artifact body; structured docs hidden in UI	Required	beskid new install, beskid new <shortName>
tool	CLI / developer-tool binaries and CLI-only packages distributed via pckg	Optional — server does not require it, validator does not reject its absence	Forbidden (tool and template are mutually exclusive)	beskid pckg pack --package-kind tool, consumer beskid pckg download <name> --version <v> --output <path>

Unknown packageKind values must be rejected at publish time. The server must reject a tool artifact that contains .beskid/template.json (and vice versa) with a deterministic message naming the conflicting file.

Validator profile per kind

The pckg server applies the kind-specific validator profile during publish:

• library — when the server enforces structured docs, the artifact must carry .beskid/docs/api.json; the artifact must not carry .beskid/template.json.
• template — the artifact must carry .beskid/template.json and must not carry .beskid/docs/api.json (server treats template-kind artifacts as scaffold-only; the dashboard hides the Documentation and Source tabs).
• tool — the artifact may omit .beskid/docs/api.json entirely (no docs-required diagnostic fires); it must not carry .beskid/template.json. The dashboard renders a Tool package Fluent badge and an install-instructions card with the registry download command (beskid pckg download …).

All kinds remain subject to the shared safeguards: zip-bomb / path-traversal guards, package-id authorization, and per-package owner gating.

CLI routing

The Beskid CLI surfaces packageKind through beskid pckg pack --package-kind {auto, tool}:

• auto (default) — reproduces the historical manifest-driven detection. Project.proj with type = Template packs a template artifact (template summary copied from .beskid/template.json); any other manifest or a missing manifest packs a library artifact.
• tool — packs a tool artifact even when Project.proj is absent, which is the expected layout for CLI-only tool packages. --package-kind tool must reject template projects (manifest with type = Template) so a template payload is never silently lost; the error message must name --package-kind tool so users can correct it.

tool pack runs strip generated .beskid/docs/** entries from the artifact (strip_tool_pack_excludes); tool package.json omits documentation.apiJson and the schema version pointer.

Consumers download tool artifacts with beskid pckg download <name> --version <v> --output <path>; the dashboard install card surfaces the exact command (e.g. beskid pckg download beskid-fmt-extra --version 0.1.0 --output ./beskid-fmt-extra.bpk).

Project.type alignment

project.type	Typical packageKind when published
(absent) / Host	library (or tool via --package-kind tool for CLI-only packages with no Project.proj)
Mod	library
Template	template

A library package must not publish with type: Template on Project.proj. A template package must include .beskid/template.json. A tool package must not include .beskid/template.json; it does not require Project.proj at all.

Versioning

All kinds share: registry-assigned publish semver, immutability per version, yank, checksum verification, and download URLs.

Decisions

• D-TOOL-PCKG-0001 — Explicit packageKind field on beskid.package.v1 (see adr/0001-explicit-package-kind-field.mdx).
• D-TOOL-PCKG-0002 — Superseded. tool packageKind no longer reserved; see adr/0002-tool-kind-reserved.mdx for the historical record and adr/0004-tool-kind-standard.mdx for the active decision.
• D-TOOL-PCKG-0003 — beskid.templates.* identity prefix for template packages (see adr/0003-beskid-templates-prefix.mdx).
• D-TOOL-PCKG-0004 — tool packageKind is Standard with a normative validator profile, CLI override, and dashboard routing (adr/0004-tool-kind-standard.mdx).

Use the ADRs tab to expand each decision.

Verification and traceability

• pckg/src/Server.Tests/Unit/PackageArtifactValidatorTests.cs — ValidateAsync_Accepts_Tool_Artifact_Without_Api_Json, ValidateAsync_Accepts_Tool_Artifact_With_Optional_Api_Json, ValidateAsync_Rejects_Tool_With_Template_Json, ValidateAsync_Rejects_Unknown_Package_Kind.
• pckg/src/Server.Tests/Unit/PackagePublishDocumentationTests.cs — EnsureStructuredApiDoc_skips_tool_packages.
• pckg/src/Server.Tests/Integration/ToolPackagePublishIntegrationTests.cs — end-to-end tool publish with structured docs absent, kind persisted on the version summary.
• compiler/crates/beskid_pckg/src/pack.rs tests — pack_profile_helpers_track_variant, build_package_json_tool_profile_omits_api_doc_pointer, strip_tool_pack_excludes_removes_generated_docs, detect_pack_profile_with_override_forces_tool_when_no_manifest, detect_pack_profile_with_override_rejects_template_project, detect_pack_profile_auto_matches_legacy_behavior.
• compiler/crates/beskid_pckg/src/cli.rs tests — pack_args_default_package_kind_is_auto, pack_args_package_kind_tool_flag_parses, pack_args_package_kind_rejects_unknown_value.

Related features

• Template packages — the template packageKind.
• pckg client contract — publish / download surface used by tool packages.
• Formatter — representative tool delivered via beskid format (a possible future packageKind: tool distribution candidate).
• api.json contract — applies to library packages; does not apply to tool artifacts.