Examples

Platform spec article

Examples

Back to Project templates ◎ Open feature 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

• Feature
  Project templates

  Parent feature hub

Purpose and scope

Illustrative templates for the three first-party packages and common user flows.

Console application (beskid.templates.console)

tags.type: project

{
  "schema": "beskid.template.v1",
  "identity": "beskid.templates.console::1.0.0",
  "name": "Beskid Console Application",
  "shortName": "console",
  "description": "Executable app with Main.bd and App target",
  "tags": { "type": "project" },
  "sourceName": "MyApp",
  "symbols": {
    "name": {
      "type": "string",
      "description": "Project name",
      "defaultValue": "MyApp",
      "isRequired": true
    }
  },
  "sources": [{ "source": "./content/", "target": "./" }],
  "postActions": [
    { "actionId": "beskidLock", "args": {} },
    { "actionId": "openReadme", "args": { "path": "README.md" } }
  ]
}

Generated Project.proj (excerpt—note no corelib opt-out; no explicit corelib dependency required in template):

project {
  name    = "{{name}}"
  version = "0.1.0"
  root    = "Src"
}

target "app" {
  kind  = App
  entry = "Main.bd"
}

CLI: beskid new console -n MyGame -o ./MyGame

Class library (beskid.templates.lib)

tags.type: project

{
  "schema": "beskid.template.v1",
  "identity": "beskid.templates.lib::1.0.0",
  "name": "Beskid Class Library",
  "shortName": "lib",
  "tags": { "type": "project" },
  "sourceName": "MyLib",
  "symbols": {
    "name": { "type": "string", "isRequired": true, "defaultValue": "MyLib" }
  },
  "sources": [{ "source": "./content/", "target": "./" }]
}

target "lib" {
  kind  = Lib
  entry = "Lib.bd"
}

Template authoring (beskid.templates.project)

tags.type: project (scaffolds a type: Template authoring tree)

{
  "schema": "beskid.template.v1",
  "identity": "beskid.templates.project::1.0.0",
  "name": "Beskid Template Package",
  "shortName": "template",
  "tags": { "type": "project" },
  "symbols": {
    "name": { "type": "string", "isRequired": true },
    "shortName": { "type": "string", "isRequired": true }
  },
  "sources": [{ "source": "./content/", "target": "./" }]
}

Emitted author Project.proj:

project {
  name    = "{{name}}"
  version = "0.1.0"
  type    = Template
  template {
    shortName = "{{shortName}}"
    identity  = "{{name}}"
  }
}

Includes stub .beskid/template.json with placeholders for the author to complete.

Workspace template (illustrative)

{
  "schema": "beskid.template.v1",
  "identity": "beskid.templates.workspace-demo::1.0.0",
  "name": "Two-member workspace",
  "shortName": "workspace-demo",
  "tags": { "type": "workspace" },
  "symbols": {
    "workspaceName": { "type": "string", "defaultValue": "MyWorkspace" }
  },
  "sources": [
    { "source": "./workspace/", "target": "./" }
  ]
}

Item template — contract file

{
  "schema": "beskid.template.v1",
  "identity": "beskid.templates.contract-item::1.0.0",
  "name": "Contract stub",
  "shortName": "contract",
  "tags": { "type": "item" },
  "symbols": {
    "contractName": { "type": "string", "isRequired": true }
  },
  "sources": [
    {
      "source": "./item/Contract.bd",
      "target": "./Src/{{contractName}}.bd"
    }
  ]
}

CLI: beskid new contract --symbol contractName=Payment -o ./Src/Payment.bd --project ./MyApp

Git and path usage

beskid new --path ./local-templates/console -n Demo -o ./Demo
beskid new --git https://example.com/templates.git --git-ref v1.2.0 --git-subpath console -n Demo -o ./Demo
beskid new install beskid.templates.console