Project scaffolding

Platform spec area

Project scaffolding

Back to Tooling ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs

No architecture decision records under adr/ for this feature yet. Standard features must publish at least one ADR or keep a ## Decisions summary on the hub.

Articles

• Project scaffolding - Decisions record (legacy index) Migration index for ADRs under project-scaffolding features—normative text lives in adr/ files. article Standard Reviewed Fri May 22

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKarea · 10 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
scope	yes	yes
features	no	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Domain
  Tooling

  Parent domain

• Area
  Manifests and lockfiles

  Project and workspace manifests consumed after instantiation

• Area
  Registry client

  Template packages are published and resolved through pckg

• Area
  CLI

  beskid new is the primary consumer entrypoint

Scope

Formal contracts for project, workspace, and item templates; beskid new; packageKind: template on pckg; and project.type = Template authoring projects. Out of scope: language syntax, compiler-mod execution, and library API shape (see sibling domains).

Area contract

Project scaffolding defines how Beskid users create new workspaces, projects, and source files from templates: versioned, packagable starter layouts distributed through pckg, installable from local paths and git URLs, and invoked through beskid new.

This area does not redefine language semantics, dependency injection rules, or compiler-mod contracts; it specifies discovery, packaging, instantiation, and registry presentation only.

Responsibility boundaries

Owned here	Owned elsewhere
beskid.template.v1 engine schema, symbols, {{ }} replacement, GUID regeneration	Project manifest contract — shape of emitted Project.proj / Workspace.proj
packageKind on beskid.package.v1 (template, reserved tool)	Package kinds — registry taxonomy and UI routing
Template package .bpk layout and pckg page mode	api.json contract — library packages only
beskid new command families	Command surface — global CLI taxonomy
Post-instantiation beskid lock / fetch orchestration	Workspace and lock contracts
Implicit corelib on every instantiated project	Corelib discovery and packaging

Internal model

flowchart LR
  subgraph sources [Template sources]
    PCKG[pckg template package]
    PATH[local path]
    GIT[git URL]
  end
  subgraph cache [Tooling cache]
    INST[installed template snapshot]
  end
  subgraph engine [Template engine]
    MAN[beskid.template.v1]
    SYM[symbols and forms]
    RPL["{{ }} replacement"]
    GUID[guid regeneration]
  end
  subgraph out [Output]
    WS[Workspace.proj optional]
    PR[Project.proj plus Src]
    IT[item files in existing project]
  end
  PCKG --> INST
  PATH --> MAN
  GIT --> MAN
  INST --> MAN
  MAN --> SYM --> RPL --> GUID
  RPL --> WS
  RPL --> PR
  RPL --> IT

1. Resolve a template identity (registry package version, path, or git ref).
2. Check for updates when the template is used (compare cached snapshot to source).
3. Collect parameters (interactive prompts and CLI flags).
4. Materialize files per sources rules; apply {{ }} and sourceName rewriting; regenerate listed GUIDs.
5. Run post-actions (unrestricted catalog; hosts document supported action ids).
6. Ensure corelib is present in the dependency graph without a user-visible opt-out flag.

Feature index

Use the tiles below for normative feature contracts in this area.

Failure and diagnostics model

Template and scaffolding failures must use stable codes in the E1901–E1999 band (see Diagnostic code registry). Categories include: unknown template, invalid beskid.template.v1, symbol validation failure, output path collision, git/path resolution failure, and yanked registry package (warning, not hard error, when policy allows proceed).

Verification matrix

Check	Anchor
Template schema parsing	compiler/crates/beskid_cli (planned template engine crate)
beskid new integration tests	compiler/crates/beskid_tests (planned projects/templates/)
Template .bpk validation	pckg/src/Server/Services/PackageArtifactValidator.cs (template profile)
First-party packages	Registry packages under beskid.templates.* namespace

Operational guidance

• First-party templates (beskid.templates.console, beskid.templates.lib, beskid.templates.project, and future beskid.templates.*) must be consumed from pckg when the registry is reachable; the CLI must not rely on a permanent embedded copy when a newer registry version exists.
• Template authors use project.type = Template and publish with packageKind: template; see Template packages.

Related areas

• VS Code extension — may invoke the same engine as beskid new (future article).
• Compiler resolution — Template projects are excluded from host compile graphs until instantiated output exists.

Decisions

Area-wide ADR index: decisions record. Per-feature normative ADRs live under each feature adr/ with ids D-TOOL-SCAFF-NNNN.

Features

• beskid new commandNormative CLI for listing, installing, and instantiating Beskid templates.
• Project scaffolding - Decisions record (legacy index)Migration index for ADRs under project-scaffolding features—normative text lives in adr/ files.
• Project templatesBeskid template engine (`beskid.template.v1`), project and item templates, workspace scaffolds, and instantiation semantics.
• Template packagesRegistry package kind `template`, `.bpk` artifact layout, validation profile, and pckg UI behavior.