Project templates

Platform spec feature

Project templates

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 (10)

1. 0001-beskid-template-v1-engine Beskid-native template engine schema Accepted

   Use beskid.template.v1 only

   Context

   Foreign template engines would split validation and documentation across ecosystems.

   Decision

   The platform must use beskid.template.v1 only. Foreign engine schemas are forbidden in spec, CLI, and pckg.

   Consequences

   Single parser and validator in tooling; template docs stay in-repo.

   Verification anchors

   CI grep excluding foreign schema identifiers under compiler/ and platform-spec tooling tree.

   Open full ADR page

2. 0002-placeholder-delimiters Human-readable {{ }} placeholders Accepted

   Use {{symbolId}} delimiters in template text

   Context

   Template authors need delimiter syntax distinct from Beskid source.

   Decision

   Text files must use {{symbolName}} placeholders; optional sourceName rewriting applies to paths and identifiers.

   Consequences

   Editors can highlight unmatched braces; substitution tests stay deterministic.

   Verification anchors

   Golden substitution tests under planned beskid_tests template fixtures.

   Open full ADR page

3. 0003-no-runnable-template-root Templates need not build at template root Accepted

   Validation runs on instantiation output only, not template project build.

   Context

   Requiring beskid build on template sources slows authoring and blocks non-host template layouts.

   Decision

   Template packages need not compile at the template project root. Tooling must validate via instantiation output builds.

   Consequences

   Faster template iteration; CI runs instantiate-then-build on consumer output.

   Verification anchors

   beskid.templates.* CI pipeline; planned beskid_tests template fixtures.

   Open full ADR page

4. 0004-corelib-always-on Implicit corelib Accepted

   Implicit corelib

   Context

   Hosts need standard library.

   Decision

   Inject corelib; forbid noCorelib flags.

   Consequences

   Simpler manifests.

   Verification anchors

   E18xx linter.

   Open full ADR page

5. 0005-template-kinds-v1 Three template kinds Accepted

   Three template kinds

   Context

   Workspace, project, item flows.

   Decision

   Support all three via tags.type.

   Consequences

   One engine.

   Verification anchors

   Three beskid_tests fixtures.

   Open full ADR page

6. 0006-path-and-git-sources Path and git sources Accepted

   Path and git sources

   Context

   Local workflows.

   Decision

   Resolve registry, path, and git.

   Consequences

   beskid new flags.

   Verification anchors

   Git/path integration tests.

   Open full ADR page

7. 0007-no-constraint-blocks No constraints Accepted

   No constraints

   Context

   DSL delay.

   Decision

   No constraint blocks in schema.

   Consequences

   Simpler v1.

   Verification anchors

   Reject constraints key.

   Open full ADR page

8. 0008-unrestricted-post-actions Post-actions Accepted

   Post-actions

   Context

   Extensibility.

   Decision

   Documented action ids, no v1 whitelist.

   Consequences

   Operator sandbox policy.

   Verification anchors

   Action registry docs.

   Open full ADR page

9. 0009-update-check-on-use Update on use Accepted

   Update on use

   Context

   Stale cache.

   Decision

   Compare cache on every use when online.

   Consequences

   Update prompts.

   Verification anchors

   Mock HTTP test.

   Open full ADR page

10. 0010-yanked-template-warning Yanked warning Accepted

    Yanked warning

    Context

    Yank policy.

    Decision

    Warn on yanked; optional continue flag.

    Consequences

    Registry alignment.

    Verification anchors

    Yank API test.

    Open full ADR page

Articles

• Contracts and edge cases Normative MUST/SHOULD rules for template instantiation, updates, yanked packages, and post-actions. article Standard Reviewed Thu May 21
• Decisions record (legacy index) Migration index pointing to per-decision ADR files under adr/. article Standard Reviewed Fri May 22
• Design model `beskid.template.v1` schema, symbols, sources, placeholders, GUIDs, and corelib policy. article Standard Reviewed Thu May 21
• Examples Sample `beskid.template.v1` manifests and first-party `beskid.templates.*` packages. article Standard Reviewed Thu May 21
• FAQ and troubleshooting Common questions about Beskid templates and `beskid new`. article Standard Reviewed Thu May 21
• Flow and algorithm End-to-end lifecycle for install, update check, and instantiate. article Standard Reviewed Thu May 21
• Verification and traceability Tests, CI, and registry checks for template conformance. 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 · 13 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
  Template packages

  Packaging and registry profile for templates

• Feature
  beskid new command

  CLI entrypoint

• Feature
  Project manifest contract

  project.type = Template and emitted manifests

• Feature
  Workspace and lock contracts

  Workspace templates emit `Workspace.proj`

• Feature
  Package kinds

  packageKind template on registry artifacts

What this feature specifies

Project templates — beskid.template.v1, project/workspace/item scaffolding, {{ }} placeholders, GUID regeneration, path/git/registry sources, update checks, and corelib policy on instantiated hosts.

Implementation anchors

• Planned template engine under compiler/crates/beskid_cli/src/template/
• compiler/crates/beskid_analysis/src/projects/model.rs — ProjectKind::Template
• pckg/src/Server/Services/PackageArtifactValidator.cs — template profile
• First-party packages beskid.templates.console, beskid.templates.lib, beskid.templates.project

Contract statement

Beskid templates are versioned trees of files plus a beskid.template.v1 manifest that drives project, workspace, and item scaffolding. Templates may be sourced from a pckg template package, a local directory, or a git URL (with optional subdirectory and ref). Instantiation must support interactive prompts and non-interactive CLI flags for the same symbol set.

Template content is not required to build as a standalone runnable project before instantiation; authors validate templates by instantiating into a scratch directory and running beskid build / beskid test on the output.

Any host project shape (Host, Mod, or future kinds) may appear in template output—templates impose no restriction on scaffolded project.type or targets.

Inputs and outputs

Input	Description
Template source	Registry package (packageKind: template), filesystem path, or git remote + ref
User parameters	Symbol values from flags and/or prompts
Output location	New directory, existing project root (item templates), or workspace root
Output	Files on disk: optional Workspace.proj, one or more Project.proj trees, .bd sources, supporting assets
Side effects	Post-actions (see flow); beskid lock recommended for project/workspace outputs
Corelib	Every instantiated host project must resolve corelib implicitly—see design model

State model

State	Location	Lifecycle
Installed template snapshot	User-level tooling cache (exact path normative in beskid new)	Updated on beskid new install and when update check finds a newer registry version
Template manifest	.beskid/template.json at template root inside package or git checkout	Immutable for a given package version / git ref
Authoring project	Project.proj with type: Template	Published as template package; excluded from normal app compile graphs
Instantiation session	Ephemeral	Symbol table → file operations → post-actions

Algorithms and flow

High-level flow is specified in flow and algorithm. Update detection runs on each use of a template (registry, path, or git) before instantiation.

Edge cases and errors

• Yanked registry template version: CLI must emit a warning and may continue if the user does not abort (see contracts).
• Output exists: project/workspace templates must fail by default when the target directory is non-empty unless --force (exact flag in beskid new).
• Item template target not inside a discovered Project.proj: must error with E19xx diagnostic.
• Invalid {{ }}: unresolved placeholders after substitution must fail instantiation.
• GUID list: every guid in the guids array must be replaced with a newly generated guid preserving source format—see design model.

Compatibility and versioning

• Engine schema: beskid.template.v1 (breaking changes require new schema id and migration notes).
• Template packages use the same registry-assigned semver as library packages; template identity string includes package id and version.
• No host constraints block (OS, SDK version, etc.)—templates are always eligible when installed.

Security and performance notes

• Post-actions are not whitelist-gated; manifest declares action ids and arguments. Hosts must document supported actions; unknown actions should warn and skip (not fail entire run) unless --strict-post-actions is set (see beskid new).
• Git templates must pin ref by default (--git-ref); floating default branch is allowed only when explicitly requested.
• Large template trees should use sources.exclude aggressively to avoid copying build artifacts.

Examples

See examples for console app, class library, workspace, item, and template-authoring samples.

Verification and traceability

• Schema fixtures: beskid.template.v1 golden files under planned compiler/crates/beskid_tests/src/projects/templates/
• Round-trip: instantiate → beskid lock → beskid build for first-party beskid.templates.*
• Item template: add file under existing Project.proj → beskid analyze clean

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-TOOL-SCAFF-0001 … D-TOOL-SCAFF-0010); use the reader ADRs tab for detail. Legacy decisions record is a migration index only.

Related features

• Template packages — packageKind, .bpk layout, pckg UI
• beskid new — commands and cache
• Package kinds — template vs library vs reserved tool

Articles

• Beskid-native template engine schemaUse beskid.template.v1 only
• Contracts and edge casesNormative MUST/SHOULD rules for template instantiation, updates, yanked packages, and post-actions.
• Decisions record (legacy index)Migration index pointing to per-decision ADR files under adr/.
• Design model`beskid.template.v1` schema, symbols, sources, placeholders, GUIDs, and corelib policy.
• ExamplesSample `beskid.template.v1` manifests and first-party `beskid.templates.*` packages.
• FAQ and troubleshootingCommon questions about Beskid templates and `beskid new`.
• Flow and algorithmEnd-to-end lifecycle for install, update check, and instantiate.
• Verification and traceabilityTests, CI, and registry checks for template conformance.