Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

Flow and algorithm

Platform spec article

Flow and algorithm

Back to Project templates Open feature in platform map

Spec standingStandard

Owner
Piotr Mikstacki
Submitter
Piotr Mikstacki

Purpose and scope

Section titled “Purpose and scope”

Normative ordering for beskid new install, beskid new list, and beskid new <shortName> (and equivalents).

Install (beskid new install)

Section titled “Install (beskid new install)”
  1. Resolve source (registry id, --path, or --git).
  2. For registry: download .bpk or extract template roots per template packages; verify packageKind: template.
  3. Locate .beskid/template.json; parse and validate beskid.template.v1.
  4. Store snapshot in tooling cache keyed by identity.
  5. Register shortName → cache entry for beskid new list.

List (beskid new list)

Section titled “List (beskid new list)”
  1. Merge installed cache entries with optional registry search (when --online).
  2. Display: shortName, name, tags.type, package id + version, yanked marker if applicable.

Instantiate (beskid new)

Section titled “Instantiate (beskid new)”
sequenceDiagram
  participant User
  participant CLI as beskid new
  participant Cache
  participant Registry as pckg
  participant Engine as template engine
  participant FS as output filesystem
  User->>CLI: select template + output path
  CLI->>Cache: load snapshot
  alt registry template
    CLI->>Registry: query latest version
    Registry-->>CLI: version metadata
    CLI-->>User: warn if yanked or update available
  end
  CLI->>Engine: load template.json
  Engine->>User: interactive prompts optional
  CLI->>Engine: symbol values
  Engine->>FS: apply sources, placeholders, guids
  Engine->>CLI: postActions list
  CLI->>CLI: run postActions
  CLI->>CLI: ensure corelib via lock/fetch policy

Step detail

Section titled “Step detail”
  1. Resolve template — cache hit by shortName, or one-shot path/git without install.
  2. Update check — for registry-backed templates, query latest semver; if greater than cached, print: A newer template version is available: <id>@<ver>. Run 'beskid new install <id>' to update.
  3. Yanked check — if requested version is yanked, emit warning (see contracts).
  4. Load manifest — beskid.template.v1.
  5. Collect symbols — merge CLI flags, defaults, interactive prompts.
  6. Evaluate conditions — skip source blocks whose condition is false.
  7. Process sources — copy, text-process, rename; apply copyOnly without substitution.
  8. Substitute — {{ }}, sourceName, forms.
  9. Regenerate guids — per guids array.
  10. Post-actions — sequential; failures honor --strict-post-actions.
  11. Corelib — run default post-action beskidLock (or equivalent) so corelib is materialized without user declaring opt-out.

Workspace templates

Section titled “Workspace templates”
  1. Write Workspace.proj first (substituted).
  2. For each member in workspaceMembers symbol or fixed layout in sources, write member Project.proj and sources.
  3. Post-action beskidLock at workspace root must lock all members.

workspaceMembers is a choice or structured symbol when the template offers optional members; fixed layouts may omit the symbol.

Item templates

Section titled “Item templates”
  1. Resolve host Project.proj root.
  2. Apply sources with target relative to chosen file path.
  3. Must not run workspace-level lock unless --lock passed.

Git and path sources

Section titled “Git and path sources”
SourceBehavior
--pathRead .beskid/template.json directly; no cache unless --install
--gitClone to cache subdirectory keyed by url+ref; optional sparse checkout for subpath

Implementation anchors

Section titled “Implementation anchors”
  • compiler/crates/beskid_cli/src/commands/new.rs (planned)
  • compiler/crates/beskid_pckg registry fetch (existing client)