feat(snapshot): write v2 and expose the history API #36
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: API Reference Drift | |
| # Fails when a committed self-hosted API reference no longer matches what its | |
| # generator produces from the package's source of truth. The markdown lives in | |
| # site/src/content/apidocs/*.md and feeds the /api/{python,typescript} pages; | |
| # the node-only site build just renders it, so it must be regenerated and | |
| # committed on release — fix drift by running `just apidocs` and committing. | |
| # See knowledge/operations/documentation.md ("API reference hosting"). | |
| # | |
| # Per AGENTS.md commit-attribution rules this workflow never auto-commits; it | |
| # only fails so a human regenerates and commits under a real identity. | |
| # | |
| # Two jobs, two cost profiles: | |
| # python — griffe statically parses the type stubs; no build needed, so | |
| # it runs on every PR that can change the surface. | |
| # typescript — the .ts wrappers import types from the napi-generated | |
| # index.d.ts, so regeneration needs a Rust build. Too heavy for | |
| # per-PR; runs on the weekly schedule and on demand only. | |
| on: | |
| pull_request: | |
| paths: | |
| - 'crates/bashkit-python/bashkit/**' | |
| - 'scripts/gen_python_apidocs.py' | |
| - 'site/src/content/apidocs/python.md' | |
| - '.github/workflows/apidocs-drift.yml' | |
| schedule: | |
| # Weekly Mondays 06:00 UTC, after the builtins (05:30) and coreutils (05:00) runs. | |
| - cron: '0 6 * * 1' | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| jobs: | |
| python: | |
| name: Regenerate and diff Python API reference | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| with: | |
| persist-credentials: false | |
| - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 | |
| with: | |
| python-version: "3.12" | |
| # Pinned: griffe parses the stubs; an upgrade could shift the parsed | |
| # surface and flag false drift. Bump deliberately, then regenerate. | |
| - name: Install griffe | |
| run: pip install "griffe==2.1.0" | |
| - name: Regenerate Python API reference | |
| run: python3 scripts/gen_python_apidocs.py | |
| - name: Fail on drift | |
| run: | | |
| if ! git diff --exit-code -- site/src/content/apidocs/python.md; then | |
| echo "::error::site/src/content/apidocs/python.md is stale — run 'just apidocs-python' and commit the result" | |
| exit 1 | |
| fi | |
| typescript: | |
| name: Regenerate and diff TypeScript API reference | |
| # Needs a Rust napi build to materialize index.d.ts; keep it off per-PR. | |
| if: github.event_name != 'pull_request' | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 25 | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| with: | |
| persist-credentials: false | |
| - name: Install Rust toolchain | |
| uses: dtolnay/rust-toolchain@e081816240890017053eacbb1bdf337761dc5582 # 1.95.0 | |
| - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2 | |
| with: | |
| workspaces: crates/bashkit-js | |
| - name: Setup pnpm | |
| uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6 | |
| # pnpm/action-setup v6 no longer ships a default version; it reads | |
| # `packageManager` from the root package.json, which this repo does | |
| # not have (the field lives in crates/bashkit-js/package.json). Pin | |
| # the version explicitly, matching js.yml / publish-js.yml. | |
| with: | |
| version: 10.33.0 | |
| - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v6 | |
| with: | |
| node-version: "22" | |
| cache: pnpm | |
| cache-dependency-path: crates/bashkit-js/pnpm-lock.yaml | |
| - name: Install JS deps | |
| run: pnpm install --frozen-lockfile | |
| working-directory: crates/bashkit-js | |
| - name: Build napi addon (generates index.cjs + type declarations) | |
| # wrapper.ts imports from ./index.cjs, but napi emits index.js / | |
| # index.d.ts. The build:cjs script renames them to index.cjs / | |
| # index.d.cts (same as the published `build`). Without it typedoc | |
| # cannot resolve ./index.cjs (TS2307) and every type that flows from | |
| # the native module collapses to `any`, producing spurious implicit- | |
| # any errors so the drift check never runs. | |
| run: | | |
| pnpm exec napi build --platform | |
| pnpm run build:cjs | |
| working-directory: crates/bashkit-js | |
| - name: Regenerate TypeScript API reference | |
| # npx fetches the pinned typedoc at generation time (network required). | |
| run: node scripts/gen_ts_apidocs.mjs | |
| - name: Fail on drift | |
| run: | | |
| if ! git diff --exit-code -- site/src/content/apidocs/typescript.md; then | |
| echo "::error::site/src/content/apidocs/typescript.md is stale — run 'just apidocs-ts' and commit the result" | |
| exit 1 | |
| fi |