Skip to content

toolchain.md

Latest commit

 

History

History
137 lines (99 loc) · 5.51 KB

toolchain.md

File metadata and controls

137 lines (99 loc) · 5.51 KB
Raw

Toolchain

This document defines the recommended v0/v1 technical foundation. The goal is to choose boring, supportable tools where federal credibility matters, while leaving room for future experiments.

Decision summary

Area Decision Rationale
CLI runtime Node 24 LTS + TypeScript 6 + ESM Best npx/npm ergonomics; newest stable LTS runtime; easiest agency and contractor adoption.
Native validation engine ast-grep + tree-sitter Cross-language rules for JS, TS, HTML, and server templates; fast Rust binary.
Formatting / JS linting Biome Useful for formatting and JS/TS linting; ast-grep remains the cross-template validator.
Token source DTCG 2025.10 JSON Stable, vendor-neutral design token format.
Token compiler Terrazzo primary, Style Dictionary fallback Terrazzo has strong DTCG coverage; fallback reduces tool risk.
CSS authoring Semantic CSS + cascade layers Works everywhere, including CMS and static HTML stacks.
Tailwind First-class output target Emit Tailwind v4 @theme; do not make Tailwind a hard dependency.
Interactive components Lit Web Components Standards-aligned, small, USWDS Elements-aligned.
Behavior Zag statecharts + signals Portable behavior across Web Components and framework wrappers.
Signing Sigstore/cosign Verifiable provenance without long-lived signing keys.
Supply-chain model SLSA-informed provenance Aligns with federal security expectations.
AI interface Extended CEM + MCP + AGENTS.md Structured component contract plus tool access.
Zig Experimental only Promising, but not stable enough for core federal tooling yet.

See tooling-baseline.md for the exact pinned versions currently used by the repository.

CLI

The CLI should be a Node 24 LTS + TypeScript ESM package:

npx @blen/ashlar init
npx @blen/ashlar add button alert form-field
npx @blen/ashlar audit
npx @blen/ashlar verify
npx @blen/ashlar evidence button

Reasons:

  • npm and npx are familiar in federal web teams.
  • Package-manager alternatives (pnpm dlx, yarn dlx, bunx, deno run npm:) can be supported without changing the package shape.
  • Pure Node avoids binary-whitelisting friction for first installs.
  • Native tools such as ast-grep can be bundled as optional platform packages or downloaded in a controlled postinstall flow.

Validation engine

ashlar audit should use ast-grep rules generated from extended CEM and hand-authored rule packs.

Rule categories:

  • Component usage: invalid variants, missing required slots, invalid prop combinations.
  • Accessibility: missing labels, icon-only buttons without names, dialogs without titles, placeholder-only fields.
  • Federal Website Standards: page title, meta description, banner, identifier, contact page hooks, external-link indicators, language selector.
  • Token governance: hard-coded colors, theme override violations, contrast pair failures.
  • Migration: versioned codemods for breaking changes.

Output formats:

  • Human CLI output.
  • JSON for scripts.
  • SARIF for code scanning dashboards.
  • MCP result format for AI agents.

Tailwind relationship

Tailwind v4+ should be supported deeply but not required.

Canonical component source:

<button class="ashlar-button" data-variant="primary">Apply</button>

Canonical component CSS:

@layer ashlar.components {
  .ashlar-button {
    background: var(--ashlar-color-action-primary-bg);
    color: var(--ashlar-color-action-primary-fg);
  }
}

Tailwind output:

@theme {
  --color-ashlar-action-primary-bg: var(--ashlar-color-action-primary-bg);
  --radius-ashlar-control: var(--ashlar-radius-control);
}

This gives Tailwind users bg-ashlar-action-primary while preserving zero-Tailwind operation.

Zig posture

Zig should not be used for the v0/v1 critical path. It remains attractive for small, fast binaries and cross-compilation, but Zig 0.16 release notes still warn about known bugs and regressions.

Possible future experiments:

  • Standalone token compiler prototype.
  • Standalone registry verifier.
  • Tiny offline mirror utility.

Adoption condition:

  • Reconsider Zig only after the CLI, registry, and validation architecture are proven and a specific Zig implementation would materially improve distribution, performance, or offline operation.

Security tooling

The toolchain should produce:

  • Sigstore signatures for every capsule.
  • SLSA provenance for registry builds.
  • SBOMs for CLI and component packages.
  • Signed Git tags for registry mirrors.
  • Checksums in capsule manifests and ashlar-lock.json.
  • ashlar verify for local tamper detection.

AI tooling

The AI tooling surface should be treated as a first-class developer API:

  • Extended CEM is the source of truth.
  • MCP exposes policy-aware search, task suggestions, retrieval, validation, migration, evidence, and token tools.
  • AGENTS.md tells coding agents how to use Ashlar in the local codebase.
  • ashlar audit is the enforcement layer when generated code is wrong.

References