voidflow 0.8.1 → 0.9.0

package/README.md

@@ -1,158 +1,9 @@
 # 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 })
-```
-
-The same release is also published unscoped as `voidflow` (identical
-contents and version), so `bun add -d voidflow` and
-`import ... from 'voidflow/playwright'` work too. `@taraxvoid/voidflow` is the
-canonical name.
-
-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 with [release-please](https://github.com/googleapis/release-please)
-([`release-please.yml`](.github/workflows/release-please.yml)). It keeps a standing
-`chore(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.
-
-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 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
+This is the unscoped mirror of [`@taraxvoid/voidflow`](https://www.npmjs.com/package/@taraxvoid/voidflow), published from the same release with identical code and version. The scoped package is canonical; its README has the documentation.
 
 ```sh
-brew install just lefthook actionlint shellcheck yq act uv
-lefthook install
+bun add -d @taraxvoid/voidflow
 ```
 
-- `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
+Source, issues and docs: <https://github.com/taraxvoid/voidflow>

package/package.json

@@ -1,8 +1,21 @@
 {
     "name": "voidflow",
-    "version": "0.8.1",
+    "version": "0.9.0",
     "description": "Shared workflows, actions and tooling for @taraxvoid sites",
     "license": "MIT",
+    "keywords": [
+        "github-actions",
+        "ci",
+        "reusable-workflows",
+        "playwright",
+        "unlighthouse",
+        "astro",
+        "cloudflare"
+    ],
+    "homepage": "https://github.com/taraxvoid/voidflow#readme",
+    "bugs": {
+        "url": "https://github.com/taraxvoid/voidflow/issues"
+    },
     "repository": {
         "type": "git",
         "url": "git+https://github.com/taraxvoid/voidflow.git"
@@ -25,7 +38,16 @@
         "playwright",
         "scripts/unlighthouse"
     ],
+    "engines": {
+        "bun": ">=1.4.0"
+    },
+    "scripts": {
+        "test": "bun test"
+    },
     "peerDependencies": {
         "@playwright/test": ">=1.40"
+    },
+    "devDependencies": {
+        "@playwright/test": "^1.40.0"
     }
 }