@taraxvoid/voidflow 0.13.0-next → 0.13.0

package/README.md

@@ -14,6 +14,19 @@ It is semi-opinionated: the defaults match how my own sites are built (bun, Astr
 - [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
 - [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)).
@@ -87,6 +100,40 @@ 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.
 
+### 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
@@ -124,8 +171,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`:
@@ -220,10 +270,35 @@ site'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`.
+Likewise, define `check:precommit` and the typecheck step runs it instead of
+`check`. CI keeps calling the full scripts, so these only narrow what runs
+locally. Common uses:
+
+- bun: `"test:unit:precommit": "bun test --changed"` runs only the test files
+  whose imports reach an uncommitted change.
+- pnpm workspace: `pnpm -r --filter '...[HEAD]' run <script>` runs only the
+  changed packages and their dependents. Fall back to the full run when a
+  root-level file (lockfile, shared tsconfig) changed, since those don't
+  belong to any package. If the root `package.json` defines the same script
+  as a recursive run, add `--filter '!{.}'` so it doesn't recurse.
+
+Hook-level options merge too. Don't set `parallel: true` under `pre-commit:` in
+the site'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 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.
+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'"
+```
+
+A bare `lefthook install` fails the whole install step (exit 127) on any runner
+without the `lefthook` binary, which includes GitHub-hosted and self-hosted CI
+images, and CI never runs git hooks anyway. `ref` cannot be a commit SHA; pin a
+release tag.
 
 ## Branch rulesets as code
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@taraxvoid/voidflow",
-    "version": "0.13.0-next",
+    "version": "0.13.0",
     "description": "Shared workflows, actions and tooling for @taraxvoid sites",
     "license": "MIT",
     "keywords": [
@@ -49,8 +49,16 @@
     "peerDependencies": {
         "@playwright/test": ">=1.40"
     },
+    "peerDependenciesMeta": {
+        "@playwright/test": {
+            "optional": true
+        }
+    },
     "devDependencies": {
-        "@playwright/test": "^1.40.0",
-        "@socketsecurity/bun-security-scanner": "^1.1.3"
+        "@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)
 }