@taraxvoid/voidflow 0.9.0 → 0.11.0-next

package/README.md

@@ -43,6 +43,33 @@ jobs:
       runner: my-hosted-runner
 ```
 
+### Single-environment sites
+
+Sites with one production environment and no `next`/`live` branches (`main`
+deploys to prod, pull requests get previews) pass `single-environment: true`,
+the same flag `resolve-env` and `branch-env-map` take:
+
+```yaml
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+jobs:
+  validate:
+    uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@<sha> # <version>
+    with:
+      single-environment: true
+```
+
+`main` then gets the production test tier (`test:e2e:all`, `test:e2e:a11y`,
+`test:e2e:lighthouse`) instead of only `test:e2e:full`. Include the `push`
+trigger so a direct push to `main` is validated too; the e2e steps resolve the
+branch from the pushed ref.
+
 ### pnpm sites, build env, extra e2e paths
 
 ```yaml
@@ -92,6 +119,19 @@ Unlighthouse version). Start from
 [`scripts/unlighthouse/unlighthouse.config.example.ts`](scripts/unlighthouse/unlighthouse.config.example.ts)
 and add `.unlighthouse/` to the site's `.gitignore`.
 
+### License policy
+
+`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).
+
+In the site's `package.json` (pin the tag):
+
+```json
+"check:licenses": "bunx --package @taraxvoid/voidflow@<version> check-licenses"
+```
+
 ### Playwright preview config
 
 Shared `playwright.config` for Astro sites that run e2e against
@@ -120,6 +160,87 @@ 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.
 
+## Dependency updates (Renovate)
+
+[`default.json`](default.json) is the shared Renovate preset. Sites add a
+`renovate.json`:
+
+```json
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>taraxvoid/voidflow"]
+}
+```
+
+It builds on `config:best-practices` (which pins GitHub Action digests), holds
+updates for 3 days like `minimumReleaseAge` in `bunfig.toml` (except our own
+package and security alerts), uses `chore(deps):` Conventional Commits, groups
+actions, astro, biome and playwright, and runs on Monday mornings. Custom
+managers keep three things current that Dependabot cannot see: the
+`@taraxvoid/voidflow@x.y.z` pin inside `package.json` scripts, a lefthook
+remote's `ref` tag, and tool versions in a `justfile` (annotate the line above
+with `# renovate: datasource=... depName=...`). Requires the Renovate GitHub App
+on the repo.
+
+||||||| 4041a59
+## 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 (`bun run --if-present`, so a missing script is skipped):
+
+- `pre-commit`: dependency guard, `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.
+
+```yaml
+# lefthook.yml in the site
+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
+
+# Site-specific differences override the remote by name, e.g. skip tests that
+# need a built dist/ before commit:
+pre-commit:
+  commands:
+    unit:
+      run: bun run test:unit -- --exclude 'test/build.test.ts'
+```
+
+Install the binary through mise (`lefthook = "<version>"` in `mise.toml`) and
+set `"prepare": "lefthook install"` so `bun install` wires the hooks. `ref`
+cannot be a commit SHA; pin a release tag.
+
+## Branch rulesets as code
+
+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
+rulesets drift, and drift is how a `next` ruleset ends up requiring a check
+name that no workflow reports any more.
+
+```sh
+just rulesets-plan                  # read-only: diff every repo against the config
+just rulesets-plan --repo soundry
+just rulesets-plan --check          # exit 1 on drift, for CI
+just rulesets-apply                 # create/update rulesets to match
+just rulesets-apply --prune         # also delete rulesets a repo lists under `retire`
+```
+
+Single-environment sites (a stable `main` that deploys to prod) manage only the
+`main` tier; their old `next`/`live` rulesets are listed under `retire`. voidflow itself
+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.
+
 ## Deployments
 
 Example deployment job added to your workflow above. `resolve-env` maps the
@@ -155,21 +276,38 @@ Sites with a single production environment and per-PR previews (no `next` or
 
 ### Versioning
 
-This project uses semver, released with [release-please](https://github.com/googleapis/release-please)
-([`release-please.yml`](.github/workflows/release-please.yml)). It keeps a standing
-`chore(main): release X.Y.Z` PR open against `main`, updated as commits land. Merging it bumps
-`package.json` and [`CHANGELOG.md`](CHANGELOG.md), tags `vX.Y.Z`, creates the GitHub release,
-and publishes to npm. The PR is opened with the org's release-bot GitHub App token
-(`RELEASE_BOT_CLIENT_ID` / `RELEASE_BOT_APP_PRIVATE_KEY`) so CI runs on it.
+Semver, released with [release-please](https://github.com/googleapis/release-please)
+([`release-please.yml`](.github/workflows/release-please.yml)) on three branch-based channels
+(full flow in [`RELEASING.md`](RELEASING.md)):
+
+| Channel | Branch | Example | npm dist-tag |
+|---|---|---|---|
+| stable | `main` | `0.10.0` | `latest` |
+| prerelease | `next` | `0.10.0-next`, `0.10.0-next.1` | `next` |
+| maintenance | `release/N.x` | `0.9.4` | `release-N.x` |
+
+release-please keeps a standing release PR open on each channel's branch, updated as commits land.
+Merging it bumps `package.json` (and [`CHANGELOG.md`](CHANGELOG.md) on stable), tags `vX.Y.Z` (`vX.Y.Z-next[.N]` on `next`),
+creates the GitHub release and publishes to npm and JSR under the channel's dist-tag. The PR is
+opened with the org's release-bot GitHub App token (`RELEASE_BOT_CLIENT_ID` /
+`RELEASE_BOT_APP_PRIVATE_KEY`) so CI runs on it.
+
+Feature PRs target `next`; promotion to `main` is a merge-commit PR (`just promote`).
 
 Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org),
 enforced loosely, as an advisory `commit-msg` hint (see
 [`scripts/check-commit-msg.sh`](scripts/check-commit-msg.sh)), not a blocking check. They
 drive the version bump and generated changelog.
 
-Treat `@main` as unstable. Consumers should pin to the commit SHA of a release tag and
-keep the version in a trailing comment, e.g. `@15caea2... # v0.8.1`, so a Renovate or
-Dependabot config can bump it. There is no floating major-version tag (`@v1`) to track yet.
+Ways to consume a release:
+
+- **Floating major tag**: `@v0` follows the newest stable 0.x release. Easiest to track, and
+  mutable like any floating tag.
+- **SHA pin with a version comment**, e.g. `@15caea2... # v0.8.1`: what I use. Same hardening
+  as any third-party action, and Renovate or Dependabot can bump it.
+- **Try unreleased changes**: pin the commit SHA of a `vX.Y.Z-next` / `vX.Y.Z-next.N` prerelease tag.
+
+Treat `@main` and `@next` as unstable.
 
 ## Self-validation
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@taraxvoid/voidflow",
-    "version": "0.9.0",
+    "version": "0.11.0-next",
     "description": "Shared workflows, actions and tooling for @taraxvoid sites",
     "license": "MIT",
     "keywords": [
@@ -25,7 +25,8 @@
         "provenance": true
     },
     "bin": {
-        "unlighthouse-runner": "scripts/unlighthouse/run.ts"
+        "unlighthouse-runner": "scripts/unlighthouse/run.ts",
+        "check-licenses": "scripts/check-licenses.ts"
     },
     "exports": {
         "./playwright": {
@@ -36,7 +37,8 @@
     },
     "files": [
         "playwright",
-        "scripts/unlighthouse"
+        "scripts/unlighthouse",
+        "scripts/check-licenses.ts"
     ],
     "engines": {
         "bun": ">=1.4.0"
@@ -48,6 +50,7 @@
         "@playwright/test": ">=1.40"
     },
     "devDependencies": {
-        "@playwright/test": "^1.40.0"
+        "@playwright/test": "^1.40.0",
+        "@socketsecurity/bun-security-scanner": "^1.1.3"
     }
 }

package/scripts/check-licenses.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+/**
+ * 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
+ * repo root) and exits non-zero if any installed package carries a blocked
+ * license.
+ *
+ * Usage: bun check-licenses.ts
+ */
+
+import { spawnSync } from 'node:child_process'
+
+export const FAIL_ON = [
+    'GPL-1.0',
+    'GPL-1.0-only',
+    'GPL-1.0-or-later',
+    'GPL-2.0',
+    'GPL-2.0-only',
+    'GPL-2.0-or-later',
+    'GPL-3.0',
+    'GPL-3.0-only',
+    'GPL-3.0-or-later',
+    'AGPL-1.0',
+    'AGPL-1.0-only',
+    'AGPL-1.0-or-later',
+    'AGPL-2.0',
+    'AGPL-2.0-only',
+    'AGPL-2.0-or-later',
+    'AGPL-3.0',
+    'AGPL-3.0-only',
+    'AGPL-3.0-or-later',
+    'SSPL-1.0',
+    'OSL-2.1',
+    'OSL-3.0',
+    'CPAL-1.0',
+    'EUPL-1.1',
+    'EUPL-1.2',
+    'CECILL-2.1',
+    // LGPL is deliberately NOT in this list - it only imposes obligations on
+    // modifying/statically linking the library, not on depending on it as-is.
+].join(';')
+
+const result = spawnSync(
+    'bunx',
+    ['license-checker', '--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}`,
+    )
+    process.exit(1)
+}
+
+if (result.status !== 0) {
+    console.error(
+        '\ncheck:licenses failed - at least one disallowed license was found.',
+    )
+    process.exit(1)
+}
+
+console.log(
+    '\ncheck:licenses passed - no blocked licenses found in any workspace.',
+)