Build

Repository Build Shape

This repository has one Python package at the root and two independently runnable, copy-owned reference projects under docs/templates/. The root package is built with uv and Hatchling. The TypeSpec contract and Lit activity references are pinned npm projects and are packaged as clean, version-matched resources in the wheel.

Required Tools And Setup

This package is a Python package built with uv, Hatchling, Ruff, Pyright, pytest, and the local Python hygiene signoff script. Install all development dependencies and verify the committed lock with:

uv sync --all-extras
uv lock --check

Node.js and the npm version declared by each template's packageManager field are additionally required when changing either shipped template or running complete release signoff. There is no root Node project: run npm commands inside the applicable template.

Fast Python Development Loop

uv run rack run L0_foundation
uv run rack run L99_signoff

The individual Rack strata are useful during focused work. Before a release-facing change is reviewed, run the complete signoff sequence below.

TypeSpec Reference Development

cd docs/templates/typespec-contract
npm ci
npm run signoff

The signoff command compiles TypeSpec, regenerates and freshness-checks projections, type-checks the TypeScript consumer, runs Node and Python conformance tests, and audits dependencies. TypeSpec source is authoritative; generated JSON Schema, OpenAPI, and TypeScript output must not be hand-edited.

Lit Activity Reference Development

cd docs/templates/web/lit-activity
npm ci
npm run dev

Open the URL printed by Vite for the live reference. Use npm run signoff before review; it runs strict TypeScript, Biome plus architecture-boundary linting, Vitest, the production Vite build, and the dependency audit. The Vite dist/ directory is transient and is not included in the source tree or packaged template.

Full Repository Signoff

uv run dev-std audit .
uv run rack run --all
uv run python -m build
uv run twine check dist/*

The release-facing Rack suite copies both templates into clean temporary directories, installs their pinned dependencies, audits their declared capabilities, and runs their complete signoff scripts. This proves the examples work without relying on local template working directories.

Outputs And Artifacts

Normal Python package builds produce transient wheel and sdist output under dist/. Those outputs are not committed. Governance HTML under docs/generated/ is derivative output and should be regenerated from the authored Markdown, HTML, and TOML governance sources.

build_hooks/template_resources.py stages filtered copies of docs/templates/typespec-contract/ and docs/templates/web/lit-activity/ into the wheel. Working directories such as node_modules/, dist/, caches, coverage, and virtual environments must never enter a distribution. Release builds also fail if a template contains environment files, credential configuration, private keys, or similar sensitive inputs. Release CI inspects the archives and exercises template copying through an installed wheel before publication.

Validation And Signoff

Release signoff runs governance audits, tests, lint, type checking, Python hygiene, both nested template signoffs, package construction, archive inspection, and installed-wheel template smoke tests. The release process is documented separately in docs/setup.html and the release notes under docs/releases/.