voidflow 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tara \X/ Void
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# voidflow
+
+Semi-opinionated GitHub Actions workflows for my personal sites and consultancy shop [RavenFlight Industries, LLC](https://rvnflt.com/github)
+
+## Usage
+
+Point `uses`  in your configuration to a workflow, e.g. in your `.github/workflows/ci.yml` 
+
+```yaml
+name: CI
+on:
+  pull_request:
+    branches: [main, next, live]
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+jobs:
+  validate:
+    uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@main
+```
+
+### Non-GitHub / self-hosted runners
+
+Pass `runner` (defaults to GitHub runner `ubuntu-latest`)
+
+```yaml
+jobs:
+  validate:
+    uses: taraxvoid/voidflow/.github/workflows/site-ci.yml@main
+    with:
+      runner: my-hosted-runner
+```
+
+## Workflow Types
+
+### Validation / Checks
+
+Runs lint, typecheck, check for GPL licenses, e2e with Playwright
+
+### Unlighthouse (performance / SEO budgets)
+
+`site-ci.yml` runs `bun run test:e2e:lighthouse` on PRs into `live`. Sites
+implement that script with the shared runner here, which serves the built
+static directory on a free port and runs
+[Unlighthouse](https://unlighthouse.dev/) against it, reusing Playwright's
+Chromium. It exits non-zero if a category budget in the site's config fails.
+
+In the site's `package.json` (pin the tag):
+
+```json
+"test:e2e:lighthouse": "bun run build && bunx --package @taraxvoid/voidflow@0.6.0 unlighthouse-runner --dir dist"
+```
+
+Options: `--dir` (default `dist`, use `dist/client` for Cloudflare adapter
+builds), `--config` (default `unlighthouse.config.ts`), `--version` (pinned
+Unlighthouse version). Start from
+[`scripts/unlighthouse/unlighthouse.config.example.ts`](scripts/unlighthouse/unlighthouse.config.example.ts)
+and add `.unlighthouse/` to the site's `.gitignore`.
+
+### Playwright preview config
+
+Shared `playwright.config` for Astro sites that run e2e against
+`astro preview`. It picks a free port outside CI, sets
+`ASTRO_PREVIEW_BACKGROUND=false` (Astro backgrounds `preview` in agent
+environments, which makes Playwright think the server exited), and drops the
+`webServer` when `PLAYWRIGHT_BASE_URL` is set.
+
+```sh
+bun add -d @taraxvoid/voidflow   # or: pnpm add -D @taraxvoid/voidflow
+```
+
+```js
+// playwright.config.js
+import { definePreviewConfig } from '@taraxvoid/voidflow/playwright'
+
+export default definePreviewConfig({ ciPort: 4141 })
+```
+
+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.
+
+## Deployments
+
+Example deployment job added to your workflow above. `resolve-env` maps the
+branch to dev/staging/prod once, up front, so its output can be used both to
+drive the deploy and to label the job (`Deploy [dev]`, `Deploy [staging]`,
+`Deploy [prod]`) — a job's `name:` can reference `needs.<job>.outputs.*` but
+not a step output from within itself, hence the split:
+
+```yaml
+jobs:
+  resolve-env:
+    needs: validate
+    if: github.event_name == 'push'
+    uses: taraxvoid/voidflow/.github/workflows/resolve-env.yml@main
+
+  deploy:
+    name: Deploy [${{ needs.resolve-env.outputs.env }}]
+    needs: resolve-env
+    if: github.event_name == 'push'
+    environment: ${{ needs.resolve-env.outputs.env }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: taraxvoid/voidflow/actions/cloudflare-deploy@main
+        with:
+          env: ${{ needs.resolve-env.outputs.env }}
+          cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+```
+
+### Versioning
+
+This project uses semver, released manually in two steps (`main` requires PRs, so nothing
+can push straight to it — not even Actions):
+
+1. Dispatch [`release.yml`](.github/workflows/release.yml) (`workflow_dispatch`, with a
+   `version` input) — it regenerates [`CHANGELOG.md`](CHANGELOG.md) via git-cliff, validates,
+   and opens a `chore(release): prepare for vX.Y.Z` PR.
+2. Merging that PR triggers [`tag-release.yml`](.github/workflows/tag-release.yml), which
+   tags the merge commit and publishes the GitHub release. (Tag pushes aren't covered by
+   `main`'s branch protection, only branch pushes are.)
+
+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 generated changelog.
+
+Treat `@main` as unstable. Consumers should pin to an exact release tag, e.g. `@v0.3.0` —
+there is no floating major-version tag (`@v1`) to track yet.
+
+## Self-validation
+
+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`)
+- **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
+- **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
+lefthook install
+```
+
+- `just validate` — run everything CI runs, locally
+- `just lint-workflows` / `lint-actions` / `lint-shell` / `security` — run one check at a time
+- `just dry-run` — full local run of `ci.yml` via [`act`](https://github.com/nektos/act) (needs Docker running); pass extra args, e.g. `just dry-run -j validation`
+- lefthook runs the fast checks (`lint-workflows`, `lint-actions`, `lint-shell`) on `pre-commit`, and `zizmor` on `pre-push`
+
+**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 — `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.
+
+YMMV, caveat emptor, your satisfaction **not** guaranteed

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "voidflow",
+    "version": "0.0.0",
+    "description": "Shared workflows, actions and tooling for @taraxvoid sites",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/taraxvoid/voidflow.git"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "bin": {
+        "unlighthouse-runner": "scripts/unlighthouse/run.ts"
+    },
+    "exports": {
+        "./playwright": {
+            "types": "./playwright/index.d.mts",
+            "default": "./playwright/index.mjs"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "playwright",
+        "scripts/unlighthouse"
+    ],
+    "peerDependencies": {
+        "@playwright/test": ">=1.40"
+    }
+}

package/playwright/index.d.mts

@@ -0,0 +1,20 @@
+import type { PlaywrightTestConfig, Project } from '@playwright/test'
+
+export interface PreviewConfigOptions {
+    /** Fixed port used when `CI` is set. Required in CI. */
+    ciPort?: number
+    /** Package manager that runs the `preview` script. Default `bun`. */
+    runner?: 'bun' | 'pnpm' | 'npm' | 'yarn' | (string & {})
+    /** Test and web server timeout in ms. Default 30000. */
+    timeout?: number
+    /** Playwright projects. Default: mobile-chrome (Pixel 7) and desktop-chrome. */
+    projects?: Project[]
+    /** Default `./test/e2e`. */
+    testDir?: string
+}
+
+export const defaultProjects: Project[]
+
+export function definePreviewConfig(
+    options?: PreviewConfigOptions,
+): PlaywrightTestConfig

package/playwright/index.mjs

@@ -0,0 +1,69 @@
+/*
+ * Shared Playwright config for Astro sites that e2e against `astro preview`.
+ *
+ *   import { definePreviewConfig } from '@taraxvoid/voidflow/playwright'
+ *   export default definePreviewConfig({ ciPort: 4141 })
+ */
+import { createServer } from 'node:net'
+import { devices } from '@playwright/test'
+
+function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer()
+        srv.unref()
+        srv.on('error', reject)
+        srv.listen(0, () => {
+            const { port } = srv.address()
+            srv.close(() => resolve(port))
+        })
+    })
+}
+
+// Worktrees run tests concurrently, so a fixed port would collide (or reuse
+// another worktree's server). Outside CI, ask the OS for a free port. The
+// result is cached in PLAYWRIGHT_TEST_PORT because the config is reloaded in
+// the runner and in every worker; each reload must agree on one port.
+if (!process.env.CI && !process.env.PLAYWRIGHT_TEST_PORT) {
+    process.env.PLAYWRIGHT_TEST_PORT = String(await getFreePort())
+}
+
+export const defaultProjects = [
+    { name: 'mobile-chrome', use: devices['Pixel 7'] },
+    { name: 'desktop-chrome', use: devices['Desktop Chrome'] },
+]
+
+export function definePreviewConfig({
+    ciPort,
+    runner = 'bun',
+    timeout = 30_000,
+    projects = defaultProjects,
+    testDir = './test/e2e',
+} = {}) {
+    if (process.env.CI && ciPort === undefined) {
+        throw new Error('definePreviewConfig: ciPort is required in CI')
+    }
+    const port = process.env.CI ? ciPort : process.env.PLAYWRIGHT_TEST_PORT
+    const external = process.env.PLAYWRIGHT_BASE_URL
+    const baseURL = external ?? `http://localhost:${port}`
+
+    return {
+        testDir,
+        timeout,
+        fullyParallel: true,
+        use: { baseURL, serviceWorkers: 'block' },
+        // Set PLAYWRIGHT_BASE_URL to test a deployed site or preview instead.
+        webServer: external
+            ? undefined
+            : {
+                  command: `${runner} run preview --port ${port}`,
+                  url: baseURL,
+                  reuseExistingServer: !process.env.CI,
+                  timeout,
+                  // Astro backgrounds `astro preview` in agentic environments
+                  // (CLAUDECODE, AI_AGENT), which makes Playwright think the
+                  // server exited early. Any non-empty value skips detection.
+                  env: { ASTRO_PREVIEW_BACKGROUND: 'false' },
+              },
+        projects,
+    }
+}

package/scripts/unlighthouse/run.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env bun
+/*
+ * Shared Unlighthouse CI runner for the Astro/bun site stack.
+ *
+ * Serves a built static directory on a free local port, then runs
+ * `unlighthouse-ci` against it with the caller's config file and exits with
+ * its status (non-zero when a category budget fails). Reuses the Chromium that
+ * Playwright already installed, so no second Chrome download.
+ *
+ * Usage:
+ *   bun run.ts [--dir dist] [--config unlighthouse.config.ts] [--version 0.19.0]
+ *
+ * Paths are relative to the current working directory (the caller's repo root).
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+
+const { values } = parseArgs({
+    options: {
+        dir: { type: 'string', default: 'dist' },
+        config: { type: 'string', default: 'unlighthouse.config.ts' },
+        version: { type: 'string', default: '0.19.0' },
+    },
+})
+
+const dir = resolve(values.dir as string)
+const config = resolve(values.config as string)
+
+if (!existsSync(dir)) {
+    console.error(`dist directory not found: ${dir} (run the build first)`)
+    process.exit(2)
+}
+if (!existsSync(config)) {
+    console.error(`unlighthouse config not found: ${config}`)
+    process.exit(2)
+}
+
+function findPlaywrightChromium(): string | null {
+    const base =
+        process.platform === 'darwin'
+            ? join(homedir(), 'Library', 'Caches', 'ms-playwright')
+            : process.platform === 'win32'
+              ? join(homedir(), 'AppData', 'Local', 'ms-playwright')
+              : join(homedir(), '.cache', 'ms-playwright')
+    if (!existsSync(base)) return null
+
+    const relPaths = [
+        'chrome-linux64/chrome',
+        'chrome-linux/chrome',
+        'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        'chrome-mac/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        'chrome-win64/chrome.exe',
+        'chrome-win/chrome.exe',
+    ]
+    for (const entry of readdirSync(base, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        for (const rel of relPaths) {
+            const candidate = join(base, entry.name, rel)
+            if (existsSync(candidate)) return candidate
+        }
+    }
+    return null
+}
+
+// Resolve a request path to a file the way static hosts do: exact file,
+// then <path>/index.html, then <path>.html.
+function resolveFile(pathname: string): string | null {
+    const rel = decodeURIComponent(pathname).replace(/^\/+/, '')
+    const candidates = [rel, join(rel, 'index.html'), `${rel}.html`]
+    for (const c of candidates) {
+        const full = resolve(dir, c)
+        if (!full.startsWith(`${dir}/`) && full !== dir) continue
+        if (existsSync(full) && statSync(full).isFile()) return full
+    }
+    return null
+}
+
+const server = Bun.serve({
+    port: 0,
+    fetch(req) {
+        const file = resolveFile(new URL(req.url).pathname)
+        if (file) return new Response(Bun.file(file))
+        const notFound = resolveFile('/404.html')
+        return notFound
+            ? new Response(Bun.file(notFound), { status: 404 })
+            : new Response('Not found', { status: 404 })
+    },
+})
+
+const site = `http://localhost:${server.port}`
+const chrome = findPlaywrightChromium()
+const env: Record<string, string | undefined> = { ...process.env }
+if (chrome) {
+    env.CHROME_PATH = chrome
+    env.PUPPETEER_EXECUTABLE_PATH = chrome
+    console.log(`Using Chromium: ${chrome}`)
+} else {
+    console.log('No Playwright Chromium found; relying on system Chrome lookup.')
+}
+console.log(`Serving ${dir} at ${site}`)
+
+const child = spawn(
+    'bunx',
+    [
+        '--package',
+        `unlighthouse@${values.version}`,
+        'unlighthouse-ci',
+        '--site',
+        site,
+        '--config-file',
+        config,
+    ],
+    { env, stdio: 'inherit' },
+)
+
+child.on('error', (err) => {
+    console.error('failed to start unlighthouse-ci:', err.message)
+    server.stop(true)
+    process.exit(1)
+})
+child.on('close', (code) => {
+    server.stop(true)
+    process.exit(code ?? 1)
+})

package/scripts/unlighthouse/unlighthouse.config.example.ts

@@ -0,0 +1,23 @@
+// Example per-repo config, copy to the repo root as `unlighthouse.config.ts`.
+// The runner supplies `site`, so it is not set here.
+export default {
+    scanner: {
+        samples: 1,
+        device: 'mobile',
+        // Keep the run short: explicit routes, no crawling.
+        // urls: ['/', '/friends', '/friends/o4us'],
+        dynamicSampling: 3,
+        skipJavascript: true,
+    },
+    lighthouseOptions: {
+        onlyCategories: ['seo', 'performance'],
+    },
+    ci: {
+        // Per-category minimum scores (0-100); the run exits non-zero if any fail.
+        budget: {
+            seo: 80,
+            performance: 90,
+        },
+        buildStatic: false,
+    },
+}