@taraxvoid/voidflow 0.13.0-next.1 → 0.14.0-next

package/README.md

@@ -1,9 +1,9 @@
 # voidflow
 
-Shared CI and deploy pipeline for a small fleet of Astro sites on Cloudflare Workers. One set of reusable GitHub Actions workflows and composite actions keeps lint, type checks, license policy, Playwright and axe-core accessibility tests, Unlighthouse budgets, and deploys identical across every site.
+Shared CI and deploy pipeline for a small fleet of Astro sites on Cloudflare Workers, and the bun tools around them. One set of reusable GitHub Actions workflows and composite actions keeps lint, type checks, license policy, Playwright and axe-core accessibility tests, Unlighthouse budgets, and deploys identical across every site.
 
 - **SHA-pinned.** Every third-party action in this repo is pinned to a full commit SHA with a version comment.
-- **Audited.** Workflows are checked with [zizmor](https://github.com/zizmorcore/zizmor), [actionlint](https://github.com/rhysd/actionlint), check-jsonschema and shellcheck on every change (see [Self-validation](#self-validation)).
+- **Audited.** Workflows are checked with [zizmor](https://github.com/zizmorcore/zizmor), [jactionlint](https://github.com/jdx/jactionlint), check-jsonschema and shellcheck on every change (see [Self-validation](#self-validation)).
 - **In production.** It runs the pipelines for the sites listed under [Used by](#used-by), including the marketing site for [RavenFlight Industries, LLC](https://rvnflt.com/github).
 
 It is semi-opinionated: the defaults match how my own sites are built (bun, Astro, Playwright).
@@ -11,9 +11,22 @@ It is semi-opinionated: the defaults match how my own sites are built (bun, Astr
 ## Used by
 
 - [taraxvoid.net](https://taraxvoid.net), my portfolio
-- [Queer Omaha](https://queeromaha.net), [Synth Omaha](https://synthomaha.net) and [Soundry](https://soundryomaha.net), free community sites for Omaha's queer and music scenes
+- [Queer Omaha](https://queeromaha.net), [Synth Omaha](https://synthomaha.net) and [Soundry](https://soundryomaha.org), free community sites for Omaha's queer and music scenes
 - [ravenflight.io](https://ravenflight.io), RavenFlight's marketing site
 
+### Show you use it
+
+Optional. Paste this into your site's README. It follows light and dark mode.
+
+```html
+<a href="https://github.com/taraxvoid/voidflow">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/CI-voidflow-8b8fd9?labelColor=2b2d3a&style=flat">
+    <img alt="CI: voidflow" src="https://img.shields.io/badge/CI-voidflow-5a5fb8?labelColor=3a3d4d&style=flat">
+  </picture>
+</a>
+```
+
 ## Usage
 
 Point `uses` in your configuration at a workflow, e.g. in your `.github/workflows/ci.yml`. Pin to a release commit SHA with the version in a comment, the same way you would any third-party action (see [Versioning](#versioning)).
@@ -82,11 +95,45 @@ jobs:
       build-env: ${{ format('{{"PUBLIC_SITE_URL":"https://example.com","GIT_SHA":"{0}"}}', github.sha) }}
 ```
 
-With `pnpm`, the pnpm version comes from `packageManager` and Node from `volta`
-or `engines` in `package.json`. The lockfile (`bun.lock` or `pnpm-lock.yaml`)
+With `pnpm`, the pnpm version comes from `packageManager` and Node from 
+`engines` in `package.json`. The lockfile (`bun.lock` or `pnpm-lock.yaml`)
 follows the package manager. `build-env` is a JSON object, visible in logs, so
 no secrets.
 
+### Install-time security scanner (Socket)
+
+A bun site can set a security scanner in `bunfig.toml`, which checks every
+package on install:
+
+```toml
+[install.security]
+scanner = "@socketsecurity/bun-security-scanner"
+```
+
+CI skips it by default. The scanner calls a third-party API on every install,
+so a network blip or an API change could fail a build that otherwise passes,
+and rerunning the same commit could give a different result. `site-ci.yml`
+installs with a copy of `bunfig.toml` minus the scanner line (every other
+setting, e.g. `minimumReleaseAge`, still applies) and leaves a notice in the
+run. Local `bun install` reads `bunfig.toml` as is, so the scanner still runs
+on your machine.
+
+To run it in CI too, pass `socket-scanner: true` to `site-ci.yml`. A workflow
+that installs on its own (outside `site-ci.yml`) gets the same default from
+the composite action:
+
+```yaml
+- uses: oven-sh/setup-bun@<sha> # <version>
+- uses: taraxvoid/voidflow/actions/bun-install@<sha> # <version>
+  # with: { socket-scanner: 'true' }
+```
+
+The copy is checked by parsing both files: it must equal your `bunfig.toml`
+with only `install.security.scanner` removed. Set the scanner as a plain
+`scanner = "..."` line (or the dotted `security.scanner` form); if it can't be
+removed cleanly, e.g. an inline table, the install fails rather than run or
+skip the scanner silently. pnpm sites are unaffected.
+
 ## Workflow Types
 
 ### Validation / Checks
@@ -99,6 +146,39 @@ Runs lint, typecheck, check for GPL licenses, e2e with Playwright.
 `live`), and `test:e2e:lighthouse` (`live`). A script the site does not define
 is skipped with a notice, so none of them is required.
 
+### Tool validation
+
+`tool-ci.yml` is the validation job for bun tools and libraries (CLIs, TUIs,
+packages): gitleaks over the full history, install (with the same Socket
+scanner handling as `site-ci.yml`), tools from the repo's `mise.toml` when it
+has one, then whichever of `lint`, `check`, `build` and `test` `package.json`
+defines, and `check:licenses` when dependencies or `scripts/` changed. When
+workflows change it also runs jactionlint (same profile handling as
+`site-ci.yml`) and
+[zizmor](https://github.com/zizmorcore/zizmor). The bun version comes from
+`.bun-version` when present.
+
+```yaml
+name: CI
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  validate:
+    uses: taraxvoid/voidflow/.github/workflows/tool-ci.yml@<release SHA> # vX.Y.Z
+```
+
+The job reports as `validate / Validate`, the check the `tool()` entry in
+[`rulesets/index.ts`](#branch-rulesets-as-code) requires.
+
 ### Unlighthouse (performance / SEO budgets)
 
 `site-ci.yml` runs `bun run test:e2e:lighthouse` on PRs into `live`. Sites
@@ -124,8 +204,11 @@ and add `.unlighthouse/` to the site's `.gitignore`.
 
 `site-ci.yml` runs `bun run check:licenses` when the lockfile or `scripts/`
 change. Sites implement that script with the shared check, which runs
-`license-checker` in the site's repo root and fails on GPL, AGPL, SSPL and
-similar copyleft licenses (LGPL is allowed).
+`license-checker-rseidelsohn` in the site's repo root and fails on GPL, AGPL,
+SSPL and similar copyleft licenses (LGPL is allowed). Voidflow pins the
+checker to an exact version as its own dependency, so sites don't need to
+install it and every site runs the same version (sites that added
+`license-checker-rseidelsohn` as a devDependency for 0.12.2 can drop it).
 
 With `@taraxvoid/voidflow` as a devDependency, call the bin from the site's
 `package.json`:
@@ -141,6 +224,11 @@ the global `~/.bunfig.toml` rather than the site's, so a global
 locally (including in the pre-commit hook) for 3 days after every release.
 The devDependency's bins are installed under the site's own `bunfig.toml`.
 
+Both bins (`check-licenses`, `unlighthouse-runner`) are TypeScript run by Bun
+(`#!/usr/bin/env bun`), so `bun` must be on `PATH` even when the site uses
+npm or pnpm. The `@taraxvoid/voidflow/playwright` export is plain ESM and runs
+on Node 22+ without Bun.
+
 ### Playwright preview config
 
 Shared `playwright.config` for Astro sites that run e2e against
@@ -169,6 +257,31 @@ Options: `ciPort` (required in CI), `runner` (default `bun`, e.g. `pnpm`),
 `timeout` (default 30000), `projects` (default Pixel 7 and Desktop Chrome),
 `testDir` (default `./test/e2e`). Requires `@playwright/test` in the site.
 
+## Shared Biome config
+
+[`biome/base.json`](biome/base.json) is the house style for the fleet: 4-space
+indent, LF, width 80, single quotes, semicolons only where needed, trailing
+commas, the `recommended` rule preset, organized imports, CSS lint off, and
+unused-import/variable rules off in `.astro` files (Biome can't see template
+usage). With `@taraxvoid/voidflow` as a devDependency, the site's `biome.json`
+extends it and adds only what is specific to the site:
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
+  "extends": ["@taraxvoid/voidflow/biome"],
+  "files": {
+    "includes": ["**", "!**/bun.lock", "!public/admin/**"]
+  }
+}
+```
+
+Lists such as `files.includes` and `overrides` combine with the base's rather
+than replace them; single values set in the site win. The base has no ignore
+lists, so each site keeps its own. It needs Biome 2: the pre-commit hook and
+`site-ci.yml` print a warning (they don't fail) when a site has Biome 1.x
+installed.
+
 ## Dependency updates (Renovate)
 
 [`default.json`](default.json) is the shared Renovate preset. Sites add a
@@ -193,30 +306,43 @@ on the repo.
 
 ## Git hooks (lefthook)
 
-[`lefthook/site.yml`](lefthook/site.yml) is the shared hook set for the site
-stack, consumed as a lefthook remote. It calls the site's own `package.json`
-scripts (`<pm> run --if-present`, so a missing script is skipped; `<pm>` is pnpm
-when the repo has a `pnpm-lock.yaml`, bun otherwise):
+[`lefthook/base.yml`](lefthook/base.yml) is the shared hook set for any bun
+(or pnpm) repo, sites and tools alike, consumed as a lefthook remote. It calls
+the repo's own `package.json` scripts (`<pm> run --if-present`, so a missing
+script is skipped; `<pm>` is pnpm when the repo has a `pnpm-lock.yaml`, bun
+otherwise):
 
-- `pre-commit`: dependency guard, `format` (formatted files are re-staged),
+- `pre-commit`: dependency guard, Biome 1.x warning, `format` (formatted files are re-staged),
   `lint:actions`, `check`, `test:unit`, and `check:licenses` / `audit` when the
   lockfile changed.
 - `commit-msg`: advisory Conventional Commits hint (never blocks).
 - `pre-push`: bail if the remote branch is ahead, then `test:push`; skipped when
-  there is nothing new to push.
+  the push carries no commit the remote lacks (branch deletes, and tags or
+  branches at already-pushed commits).
+
+Before `test:unit` and `test:push`, the hooks unset the variables git exports to
+hooks (`GIT_DIR`, `GIT_INDEX_FILE`, ...; the list comes from
+`git rev-parse --local-env-vars`). Without that, a test that runs
+`git -C <tmpdir> commit` operates on, and commits into, the repo being hooked.
 
 ```yaml
-# lefthook.yml in the site
+# lefthook.yml in the repo
 remotes:
   - git_url: https://github.com/taraxvoid/voidflow
     ref: v0.10.0 # a tag or branch; lefthook passes it to `git clone --branch`
     configs:
-      - lefthook/site.yml
+      - lefthook/base.yml
 
 ```
 
+Upgrading from `lefthook/site.yml` (v0.13 and earlier): change the `configs`
+entry to `lefthook/base.yml` when you bump `ref`. The hooks are otherwise the
+same. `lefthook/site.yml` is now a stub whose `pre-commit` and `pre-push` fail
+with that instruction, so a `ref` bump (for example from Renovate) that leaves
+`configs` alone stops commits instead of turning the hooks off silently.
+
 Lefthook merges `lefthook.yml`, then remotes, then `lefthook-local.yml`, so a
-site's own `lefthook.yml` can add commands (for example image compression) but
+repo's own `lefthook.yml` can add commands (for example image compression) but
 cannot override ones defined here. Differences go through `package.json`
 scripts: define `test:unit:precommit` (for example excluding tests that need a
 built `dist/`) and the pre-commit unit step runs it instead of `test:unit`.
@@ -232,9 +358,23 @@ locally. Common uses:
   belong to any package. If the root `package.json` defines the same script
   as a recursive run, add `--filter '!{.}'` so it doesn't recurse.
 
-Install the binary through mise (`lefthook = "<version>"` in `mise.toml`) and
-set the `prepare` script so `bun install` wires the hooks, but make it tolerate a
-missing binary:
+Hook-level options merge too. Don't set `parallel: true` under `pre-commit:` in
+the repo's `lefthook.yml`: it applies to the merged hook, so every step,
+including the shared ones, starts at once and their `priority` order is ignored
+(tests that share a database or build output can then time out).
+
+Install the binaries through mise. A starter `mise.toml` for a repo using
+these hooks and voidflow CI:
+
+```toml
+[tools]
+lefthook = "2.2.1"
+gitleaks = "8.30.1"
+jactionlint = "2.1.0"
+```
+
+Renovate bumps `mise.toml` natively. Set the `prepare` script so `bun install`
+wires the hooks, but make it tolerate a missing binary:
 
 ```json
 "prepare": "lefthook install || echo 'lefthook not installed (run mise install); git hooks skipped'"
@@ -250,7 +390,10 @@ release tag.
 Branch protection for the fleet lives in [`rulesets/index.ts`](rulesets/index.ts):
 one canonical `main` / `next` / `live` definition (plus `prerelease` and `maintenance`
 tiers for repos with release channels) and a small per-repo table
-(Netlify or not, check names, CODEOWNERS, extra bypass actors). Hand-edited
+(Netlify or not, check names, CODEOWNERS, extra bypass actors). Sites use
+`site()` and tools use `tool()` (main only, no Netlify, requires
+`validate / Validate` from `tool-ci.yml`). Private repos are left out: on a
+plan without rulesets for private repos, the API returns 403. Hand-edited
 rulesets drift, and drift is how a `next` ruleset ends up requiring a check
 name that no workflow reports any more.
 
@@ -268,7 +411,11 @@ manages `main`, `prerelease` (`next`) and `maintenance` (`release/*`) and sets
 `linearHistory: false` so `next` can be promoted into `main` with a merge commit.
 Uses the `gh` CLI for auth (needs admin on the repos). Rulesets that are not in
 the config are reported and left alone; only `retire` entries are ever deleted,
-and only with `--prune`. It is repo tooling, not part of the published package.
+and only with `--prune`. Private repos on a plan without rulesets (GitHub answers
+403, e.g. a free personal account) are skipped and listed at the end rather than
+failing the run, so `--check` stays green and they pick up their rulesets once the
+repo goes public or the plan changes. It is repo tooling, not part of the published
+package.
 
 ## Deployments
 
@@ -342,16 +489,16 @@ Treat `@main` and `@next` as unstable.
 
 This repo validates its own workflows and composite actions (`.github/workflows/ci.yml`):
 
-- **actionlint**: workflow schema/logic; also shellchecks `run:` steps in `.github/workflows/*.yml` automatically (`shellcheck` ships on `ubuntu-latest`)
+- **jactionlint**: workflow schema/logic; also shellchecks `run:` steps in `.github/workflows/*.yml` automatically (`shellcheck` ships on `ubuntu-latest`)
 - **check-jsonschema**: schema-checks `actions/**/action.yml` and the workflow files against [SchemaStore](https://www.schemastore.org/)'s `github-action.json` / `github-workflow.json`
-- **shellcheck** (`scripts/shellcheck-actions.ts`): checks `run:` steps inside `actions/**/action.yml`, which actionlint doesn't reach
+- **shellcheck** (`scripts/shellcheck-actions.ts`): checks `run:` steps inside `actions/**/action.yml`, which jactionlint doesn't reach
 - **zizmor**: security audit (unpinned refs, script injection via `${{ }}` in `run:`, excess permissions, etc.)
 
 ### Local dev setup
 
 ```sh
-brew install just lefthook actionlint shellcheck bun act uv
-lefthook install
+mise install   # tools pinned in mise.toml
+bun install    # its prepare script runs `lefthook install`
 ```
 
 - `just validate`: run everything CI runs, locally

package/biome/base.json

@@ -0,0 +1,63 @@
+{
+    "vcs": {
+        "enabled": true,
+        "clientKind": "git",
+        "useIgnoreFile": true
+    },
+    "assist": {
+        "enabled": true,
+        "actions": {
+            "source": {
+                "organizeImports": "on"
+            }
+        }
+    },
+    "formatter": {
+        "enabled": true,
+        "indentStyle": "space",
+        "indentWidth": 4,
+        "lineEnding": "lf",
+        "lineWidth": 80,
+        "useEditorconfig": true
+    },
+    "javascript": {
+        "formatter": {
+            "arrowParentheses": "always",
+            "jsxQuoteStyle": "double",
+            "quoteProperties": "asNeeded",
+            "quoteStyle": "single",
+            "semicolons": "asNeeded",
+            "trailingCommas": "all"
+        }
+    },
+    "html": {
+        "formatter": {
+            "indentScriptAndStyle": false,
+            "selfCloseVoidElements": "always"
+        }
+    },
+    "css": {
+        "linter": {
+            "enabled": false
+        }
+    },
+    "linter": {
+        "enabled": true,
+        "rules": {
+            "preset": "recommended"
+        }
+    },
+    "overrides": [
+        {
+            "includes": ["**/*.astro"],
+            "linter": {
+                "rules": {
+                    "correctness": {
+                        "noUnusedImports": "off",
+                        "noUnusedVariables": "off"
+                    }
+                }
+            }
+        }
+    ]
+}

package/package.json

@@ -1,15 +1,17 @@
 {
     "name": "@taraxvoid/voidflow",
-    "version": "0.13.0-next.1",
-    "description": "Shared workflows, actions and tooling for @taraxvoid sites",
+    "version": "0.14.0-next",
+    "description": "Shared workflows, hooks and tooling for @taraxvoid repos",
     "license": "MIT",
     "keywords": [
         "github-actions",
         "ci",
         "reusable-workflows",
+        "lefthook",
+        "renovate",
+        "bun",
         "playwright",
         "unlighthouse",
-        "astro",
         "cloudflare"
     ],
     "homepage": "https://github.com/taraxvoid/voidflow#readme",
@@ -33,24 +35,37 @@
             "types": "./playwright/index.d.mts",
             "default": "./playwright/index.mjs"
         },
+        "./biome": "./biome/base.json",
         "./package.json": "./package.json"
     },
     "files": [
+        "biome",
         "playwright",
         "scripts/unlighthouse",
         "scripts/check-licenses.ts"
     ],
     "engines": {
-        "bun": ">=1.4.0"
+        "bun": ">=1.4.0",
+        "node": ">=22"
     },
     "scripts": {
+        "prepare": "lefthook install || echo 'lefthook not installed (run mise install); git hooks skipped'",
         "test": "bun test"
     },
     "peerDependencies": {
         "@playwright/test": ">=1.40"
     },
+    "peerDependenciesMeta": {
+        "@playwright/test": {
+            "optional": true
+        }
+    },
     "devDependencies": {
-        "@playwright/test": "^1.40.0",
-        "@socketsecurity/bun-security-scanner": "^1.1.3"
+        "@biomejs/biome": "2.5.14",
+        "@playwright/test": "1.64.0",
+        "@socketsecurity/bun-security-scanner": "1.1.3"
+    },
+    "dependencies": {
+        "license-checker-rseidelsohn": "5.0.1"
     }
 }

package/scripts/check-licenses.ts

@@ -2,14 +2,18 @@
 /**
  * Shared license policy check for the Astro/bun site stack: fail on GPL kudzu.
  *
- * Runs `license-checker` against the current working directory (the caller's
+ * Runs `license-checker-rseidelsohn` against the current working directory (the caller's
  * repo root) and exits non-zero if any installed package carries a blocked
- * license.
+ * license. The checker is voidflow's own exact-pinned dependency, resolved from
+ * voidflow's install rather than `bunx`, so every site runs the same version
+ * and nothing is fetched at check time.
  *
  * Usage: bun check-licenses.ts
  */
 
 import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 export const FAIL_ON = [
     'GPL-1.0',
@@ -41,15 +45,26 @@ export const FAIL_ON = [
     // modifying/statically linking the library, not on depending on it as-is.
 ].join(';')
 
+const checkerPkg = Bun.resolveSync(
+    'license-checker-rseidelsohn/package.json',
+    import.meta.dir,
+)
+const checkerBin = join(
+    dirname(checkerPkg),
+    JSON.parse(readFileSync(checkerPkg, 'utf8')).bin[
+        'license-checker-rseidelsohn'
+    ],
+)
+
 const result = spawnSync(
-    'bunx',
-    ['license-checker', '--summary', '--failOn', FAIL_ON],
+    process.execPath,
+    [checkerBin, '--summary', '--failOn', FAIL_ON],
     { cwd: process.cwd(), stdio: 'inherit' },
 )
 
 if (result.error) {
     console.error(
-        `\ncheck:licenses failed - could not run license-checker: ${result.error.message}`,
+        `\ncheck:licenses failed - could not run license-checker-rseidelsohn: ${result.error.message}`,
     )
     process.exit(1)
 }