README.md
README.md is a file in Bane's Lab Build Scripts. 109 lines of code and 0 definitions.
<!-- Auto-generated 2026-10-04T16:25Z v9 -->
# @banes-lab/build-scripts
<!-- concern:overview -->
## Purpose
The web member's vite config registers one plugin, `sitePlugin` (`core/plugins/site.plugin.ts`), which runs every build step through the site pipeline (`core/pipelines/site.pipeline.ts`). Each build concern is a step file under `core/steps/` that registers itself through `defineStep` (`core/factories/step.factory.ts`) and drives a coordinator under `core/coordinators/` over the converters, formatters, loaders, persistence, resolvers and validators beside it. A step declares its phase, its modes, what it needs and what it gives. The pipeline derives the order from those contracts, runs the steps whose needs are met together, and refuses an unmet need, a key two steps give, a cycle and an undeclared result. The start phase runs at build start and at dev-server start, except the diagram step, which declares the build mode only. The close phase runs when the bundle closes in a build. Before the config resolves in a build, the config calls `deriveAnatomy` in `core/coordinators/anatomy.coordinator.ts`, which snapshots every tree the web member's tree registry declares for the anatomy page, and fails when a reference that resolved to one target in the last build does not resolve to it now. The graph step merges whatever the producer registry holds: each edge kind is a `*.producer.ts` file under `core/producers/` that registers itself through `defineProducer` (`core/factories/producer.factory.ts`). The dev server reads the diagram vectors and the anatomy files the last build wrote. The entry points under `runtime/entrypoints/` run on their own. `server.entrypoint.ts` supervises every dev server, and `validation.entrypoint.ts` validates the built site, which the gate runs as its discovery step.
<!-- /concern:overview -->
<!-- concern:use -->
## When to use
- Adding a build step. The step is a `*.step.ts` file under `core/steps/` that calls `defineStep` with its phase, needs and gives, beside a coordinator that does the work. The pipeline finds it, and the vite config stays as it is.
- Adding an edge kind to the site graph. The producer is a `*.producer.ts` file under `core/producers/` that calls `defineProducer` with its name and a `produce` function over the graph context, and its relation is one record in `RELATIONS` in the web member's graph constants.
- Starting the local site with `npm run dev` from the workspace root.
- Checking a build before a deploy by running the discovery validator over `_builds/web`.
## When NOT to use
- A standalone check the gate runs on its own belongs in `project.scripts`, since nothing in the application imports it.
- A deploy step belongs in the deploy member.
<!-- /concern:use -->
<!-- concern:charts -->
## Architecture charts
The structure, logical-flow and dependency diagrams derived from the source AST live in [_code.info.generated/mermaid-charts.generated.md](./_code.info.generated/mermaid-charts.generated.md).
<!-- /concern:charts -->
<!-- concern:install -->
## Install
Hoisted from the root workspace. A build and the dev server need a Chrome or Edge binary for the diagram renderer.
## Quick start
```bash EXAMPLE: Start the dev servers
npm run dev
```
```bash EXAMPLE: Build the site through every step
npm run build -w @banes-lab/web
```
```bash EXAMPLE: Validate the built site
node banes-lab.root/banes-lab.build.scripts/runtime/entrypoints/validation.entrypoint.ts
```
<!-- /concern:install -->
<!-- concern:api -->
## API
- `function cacheDecision(step: SiteStep, state: SiteState, ledger: FingerprintIndex): CacheDecision`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `default export`
- `function devPortPlugin(key: PortKey): Plugin`
- `function discoverSteps(): Promise<readonly SiteStep[]>`
- `function runPhase(steps: readonly SiteStep[], phase: SitePhase, state: SiteState, write: (line: string) => void): Promise<SiteState>` — Runs one phase of the registered steps. It derives the waves from the needs and gives, runs each wave's steps together over one build state, merges what each gives, and logs each step's time.
- `function sitePlugin(diagrams: DiagramWalk): Plugin` — The one vite plugin. It discovers the steps when the config resolves, runs the start phase at build start and the close phase when the bundle closes, and serves the dev catalog and payloads.
- `function wavesOf(steps: readonly SiteStep[], phase: SitePhase, mode: SiteMode): Waves`
<!-- /concern:api -->
<!-- concern:config -->
## Configuration
- `configuration/constants/server.constants.ts` — the dev, social and capture ports and the dev command's declared arguments.
- `configuration/constants/diagram.constants.ts` — the diagram library and layout engine bundles, the stage page's routes, the fonts and theme tokens it loads, and the vector filename shape.
- `configuration/constants/catalog.constants.ts` — the query catalog's address segments and the segments it reserves.
- `configuration/constants/anatomy.constants.ts` — the tree options a build without the web member's resolvers falls back to. The trees themselves are declared in the web member's tree registry.
<!-- /concern:config -->
<!-- concern:deps -->
## Dependencies
- `@banes-lab/content`
- `@banes-lab/web`
- `@govlab/argv`
- `@govlab/canonical-write`
- `@govlab/constants`
- `@govlab/content-fingerprint`
- `@govlab/context`
- `@govlab/docs`
- `@govlab/patterns`
- `@govlab/pipeline`
- `@govlab/quality`
- `@govlab/stats`
- `@ssot/govlab`
- `@ssot/paths`
- `@ssot/secrets`
<!-- /concern:deps -->
<!-- concern:ai-context -->
## AI context
- A script the application imports or a package script runs belongs here, and a standalone check belongs in `project.scripts`.
- Every location resolves through `@ssot/paths`, and every generated file is written through the canonical writer.
- Copy printed by a step lives in `configuration/strings/`.
<!-- /concern:ai-context -->
<!-- concern:domains -->
## Domains
This package serves these software domains, which `_manifest.json` declares in `domains` from the two-tier software-domain vocabulary (`meta → sub`):
- **developer-tooling** — build-tooling
<!-- /concern:domains -->
<!-- concern:quality-governance -->
## Quality governance
The canonical quality catalog resolves the quality concepts that govern this package. `_manifest.json` declares them in `governedBy`, and a lint package derives them from the concepts its own rules enforce. Each maps to the custom lint rules that enforce it:
- **separation-of-concerns** — _complexity_
- **type-safety** — _correctness_
<!-- /concern:quality-governance -->
<!-- concern:disposal -->
## Disposal
- Remove the `sitePlugin` import from the web member's vite config.
- Remove the member's workspace entry from the root `package.json` and its `MEMBERS` row from the stage planner.
- Remove its governed-root entry from `containers` and `specialContainers` in `.govlab/shared/configs/taxonomy.config.ts`, and the `app.build`, `app.buildSteps` and `app.graphProducers` keys from `project.paths/paths.yaml`.
- Delete the directory, reinstall, run the gate.
<!-- /concern:disposal -->
<!-- concern:metrics -->
---
experimental · 19 exports · 15 deps · 0 principles · 2 concepts
<!-- /concern:metrics -->