@taraxvoid/voidflow 0.8.3 → 0.10.0

package/README.md

@@ -43,11 +43,61 @@ 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
+jobs:
+  validate:
+    uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@<sha> # <version>
+    with:
+      package-manager: pnpm # default: bun
+      e2e-extra-paths: '["wrangler.jsonc", "site.vars.json"]' # JSON array of globs
+      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`)
+follows the package manager. `build-env` is a JSON object, visible in logs, so
+no secrets.
+
 ## Workflow Types
 
 ### Validation / Checks
 
-Runs lint, typecheck, check for GPL licenses, e2e with Playwright
+Runs lint, typecheck, check for GPL licenses, e2e with Playwright.
+
+`site-ci.yml` runs these `package.json` scripts: `lint`, `check`, `build`,
+`test:unit`, `check:licenses`, `test:e2e:full` (PRs into `main`),
+`test:e2e:all` (PRs into `next` and `live`), `test:e2e:a11y` (`next` and
+`live`), and `test:e2e:lighthouse` (`live`). A script the site does not define
+is skipped with a notice, so none of them is required.
 
 ### Unlighthouse (performance / SEO budgets)
 
@@ -69,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
@@ -97,6 +160,84 @@ 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 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`.
+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
@@ -125,6 +266,11 @@ jobs:
           cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 ```
 
+Sites with a single production environment and per-PR previews (no `next` or
+`live` branch) pass `with: { single-environment: true }` to `resolve-env.yml`
+(or the same input on `actions/branch-env-map`). `main` then maps to `prod` and
+`pull_request` events map to `preview`; any other ref fails.
+
 ### Versioning
 
 This project uses semver, released with [release-please](https://github.com/googleapis/release-please)
@@ -149,13 +295,13 @@ This repo validates its own workflows and composite actions (`.github/workflows/
 
 - **actionlint**: 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.sh`): 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 actionlint 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 yq act uv
+brew install just lefthook actionlint shellcheck bun act uv
 lefthook install
 ```
 
@@ -166,6 +312,6 @@ lefthook install
 
 **Colima users:** `.actrc` already disables the docker-socket mount (`--container-daemon-socket -`). `act` binds `/var/run/docker.sock` by default, which doesn't exist under Colima and fails with `operation not supported`. None of these workflow steps need docker-in-docker, so this is safe.
 
-**Run `just dry-run` from a normal checkout, not a linked git worktree.** `act` copies the working tree via `docker cp` rather than a real clone, so a worktree's `.git` pointer back to the parent repo doesn't resolve inside the container, so `git ls-files`-based steps (schema validation, `scripts/shellcheck-actions.sh`) silently see zero files instead of erroring. Verified clean end-to-end (`🏁 Job succeeded`) from a plain clone.
+**Run `just dry-run` from a normal checkout, not a linked git worktree.** `act` copies the working tree via `docker cp` rather than a real clone, so a worktree's `.git` pointer back to the parent repo doesn't resolve inside the container, so `git ls-files`-based steps (schema validation, `scripts/shellcheck-actions.ts`) silently see zero files instead of erroring. Verified clean end-to-end (`🏁 Job succeeded`) from a plain clone.
 
 Provided as is under the [MIT license](LICENSE). Issues and pull requests are welcome.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@taraxvoid/voidflow",
-    "version": "0.8.3",
+    "version": "0.10.0",
     "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.',
+)