@quef/bonsai

A CLI that renders a Spec-Driven Development repo into a static, browsable Spec Preview site. It auto-detects the spec format (OpenSpec or Spec Kit), renders the specs, and writes a self-contained static site you can publish to any static host (GitLab/GitHub Pages, S3, etc.).

The published binary is exposed as both specpreview and bonsai.

Requirements

• Node.js >= 22

Usage

Run it directly with npx — no install needed:

npx @quef/bonsai build \
  --input ./openspec \
  --output ./public \
  --commit "$CI_COMMIT_SHA" \
  --repo .

build options

| Flag | Description | | ---------------- | ----------------------------------------------------------------- | | --input <dir> | Directory containing the spec files to render (e.g. ./openspec). | | --output <dir> | Directory to write the static site into (e.g. ./public). | | --commit <sha> | Commit SHA stamped onto rendered source positions. | | --repo <dir> | Path to the repository root (used for adapter/format detection). |

All four flags are required.

Output

The --output directory receives a static site:

• index.html (plus assets/) — the interactive Spec Preview viewer.
• corpus.json — the rendered spec documents.
• sourcemap.json — (file, startLine, endLine, commitSha) for every requirement.
• search-index.json — a prebuilt client-side search index.

Serve that directory with any static file server to browse it.

CI

For a ready-to-use GitLab Pages job, see infra/templates/gitlab-ci.spec-preview.yml.