Contracts and edge cases

Platform spec article

Contracts and edge cases

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

Testable rules for template resolution, instantiation, registry interaction, and diagnostics (E1901–E1999).

Resolution

ID	Rule
T-R01	beskid new must accept exactly one template selector: shortName, --package <id>[@version], --path <dir>, or --git <url> (with optional --git-ref, --git-subpath).
T-R02	Registry resolution must require packageKind: template on the resolved package.json.
T-R03	First-party ids under beskid.templates.* must be preferred when shortName is ambiguous and registry is configured.
T-R04	On every template use, tooling must compare cached install (if any) to latest non-yanked registry version and must print an informational message when a newer version exists.
T-R05	When the resolved version is yanked, tooling must print a warning naming the package and version; exit code 0 if the user proceeds via --allow-yanked or interactive confirmation.

Instantiation

ID	Rule
T-I01	Project templates must create the output directory when missing; must error when non-empty without --force.
T-I02	Workspace templates must emit Workspace.proj at the workspace root and member Project.proj files at declared member paths.
T-I03	Item templates must require -o / --output pointing at a file or directory under a folder containing Project.proj (or pass --project to disambiguate).
T-I04	After substitution, no {{ }} placeholder tokens may remain in output files.
T-I05	All guids entries must be replaced in output; leftover source guids must fail with E1906.
T-I06	Instantiated host projects must receive corelib per design model; templates must not emit opt-out flags.
T-I07	Templates may scaffold Mod, multi-target, or FFI-heavy projects without restriction.

Interactive and flags

ID	Rule
T-U01	When stdin is a TTY and preferInteractive is true or any required symbol lacks a value, the CLI must prompt.
T-U02	When --no-interactive is set, only flags and defaults may be used; missing required symbols must fail with E1903.
T-U03	--symbol (repeatable) and -n / --name for the primary name symbol must be supported.

Post-actions

ID	Rule
T-P01	postActions is an ordered array of { "actionId": string, "args": object }.
T-P02	There is no platform whitelist; hosts must document supported actionId values.
T-P03	Unknown actionId should log a warning and continue unless --strict-post-actions.
T-P04	Built-in actions must include at minimum: runCommand, beskidLock, beskidFetch, openReadme.

Builtin forms

Form id	Input	Output
identity	string	unchanged
lowerCase	string	lowercase
upperCase	string	uppercase
safeName	string	filesystem-safe identifier
namespace	string	dotted namespace from path-like name

Edge cases

• Git shallow clone failure → E1907 with remediation (network, auth, ref).
• Template package contains packageKind: library → E1902 reject for beskid new install.
• Item template overwrites existing file → require --force or interactive confirm.
• Workspace template with duplicate member ids → E1908 at validation time (before write).

Diagnostic band E1901–E1999

Code	Meaning
E1901	Template manifest missing or invalid schema
E1902	Package kind is not template
E1903	Required symbol not provided
E1904	Output path conflict
E1905	Item template outside project root
E1906	GUID replacement incomplete
E1907	Git template source failed
E1908	Workspace template invalid member graph
E1999	Reserved internal template engine error