Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
830d789
refactor(repo): delete the starter seed package
systemfsoftware-maker Oct 6, 2026
4179da4
docs(repo): name the repository xstate
systemfsoftware-maker Oct 6, 2026
9da0125
ci(ci): move mutation to a release gate on main
systemfsoftware-maker Oct 6, 2026
6e30cfb
build(deps): pin the starter's lake1 toolchain and run dependency cod…
systemfsoftware-maker Oct 6, 2026
cfaf9b9
build(repo): fail the commit-msg hook when git cannot list the staged…
systemfsoftware-maker Oct 6, 2026
499af37
build(deps): pin systemfsoftware to the #606 head that builds on aarc…
systemfsoftware-maker Oct 6, 2026
d89b662
build(deps): trust mitm-cache's CA in the pnpm store build on darwin
systemfsoftware-maker Oct 6, 2026
d719638
build(deps): replay the pnpm store's registry over plain http
systemfsoftware-maker Oct 6, 2026
1f1909a
build(deps): pin pnpm-release-management to the #8 head for the darwi…
systemfsoftware-maker Oct 6, 2026
ebd5967
fix(repo): let the sandbox proofs and script tests run on macOS
systemfsoftware-maker Oct 6, 2026
a2479e7
ci(ci): build the workspace tarballs in the dist leg
systemfsoftware-maker Oct 6, 2026
dde24c0
ci(ci): plan release-gate mutation from each stryker config and the d…
systemfsoftware-maker Oct 6, 2026
391e662
ci(ci): test the release cycle and fix the release PR opener
systemfsoftware-maker Oct 6, 2026
20dc69e
build(repo): pass dprint arguments through unchanged
systemfsoftware-maker Oct 6, 2026
c097d75
ci(ci): run sandboxed workflow steps through one composite action
systemfsoftware-maker Oct 6, 2026
d239af5
test(repo): spawn every sandbox proof without the dynamic-loader envi…
systemfsoftware-maker Oct 6, 2026
fcca4be
build(repo): seed the dprint plugin cache as a writable copy
systemfsoftware-maker Oct 6, 2026
75c246f
test(ci): cover the release PR opener against an open PR
systemfsoftware-maker Oct 6, 2026
8d1fb03
ci(ci): let the release notes steps fetch octokit
systemfsoftware-maker Oct 6, 2026
35d774d
feat(release): release the packages listed in release-set.json
systemfsoftware-maker Oct 6, 2026
70decf6
ci(ci): let the release-set readers fetch effect
systemfsoftware-maker Oct 6, 2026
e3f209b
test(repo): pin the hooks a git-hooks proof commit runs
systemfsoftware-maker Oct 7, 2026
dbab32b
ci(release): merge main's shared release toolchain into the scaffold
systemfsoftware-maker Oct 7, 2026
87461df
build(deps): pin systemfsoftware to the merged #606
systemfsoftware-maker Oct 7, 2026
17dfabd
build(deps): build the release gate's stryker from source and plan it…
systemfsoftware-maker Oct 7, 2026
1915c98
ci(ci): run the intent check in the dev shell
systemfsoftware-maker Oct 7, 2026
ee2c8a7
build(repo): build every from-source package through one parameterize…
systemfsoftware-maker Oct 7, 2026
13349a7
build(repo): build from-source packages inside the nix sandbox
systemfsoftware-maker Oct 7, 2026
caf106e
build(repo): keep the starter package in the scaffold
systemfsoftware-maker Oct 7, 2026
f29c1fe
build(deps): pin release-tools to the pnpm-release-management main th…
systemfsoftware-maker Oct 7, 2026
273516f
build(repo): pack from-source tarballs without the registry's changelog
systemfsoftware-maker Oct 7, 2026
9c5e0da
build(deps): build the attw CLI and its effect-cell-types 7 from source
systemfsoftware-maker Oct 7, 2026
17073a5
ci(repo): gate the starter on lint:tsgo and attw
systemfsoftware-maker Oct 7, 2026
59f3b22
ci(repo): run the assert-local-sfs guard on the committed lockfiles
systemfsoftware-maker Oct 7, 2026
38dce3c
build(repo): merge main's darwin and macOS removal into the scaffold
systemfsoftware-maker Oct 7, 2026
8a375d7
build(repo): merge main's @effect/tsgo 0.50 catalog bump into the sca…
systemfsoftware-maker Oct 7, 2026
5417a60
build(repo): merge main's comment-checker and nixpkgs Dependabot bump…
systemfsoftware-maker Oct 7, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/actions/dev-shell/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
name: Dev shell and sandbox
description: >-
Installs Nix, lets the sandbox create user namespaces on ubuntu-24.04,
creates .cache/ (where sandboxed steps leave files for the host, since
the runner's $GITHUB_OUTPUT and /tmp are outside the sandbox), and
installs the workspace through the sandbox, offline from the Nix pnpm
store.
inputs:
install:
description: Install the workspace through the sandbox
default: "true"
runs:
using: composite
steps:
- uses: cachix/install-nix-action@v31
- name: Lift the ubuntu-24.04 AppArmor block on user namespaces
if: runner.os == 'Linux'
shell: bash
run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
- name: Create the sandbox's output directory
shell: bash
run: mkdir -p .cache
- name: Install through the sandbox, offline from the Nix pnpm store
if: inputs.install == 'true'
shell: bash
run: nix develop --command pnpm bootstrap
37 changes: 37 additions & 0 deletions .github/actions/sandbox/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: Sandbox
description: >-
Runs a command in the dependency sandbox — the project directory
read-write, an empty $HOME, a cleared environment and only the listed hosts
reachable over HTTPS — leaving host-side reads and writes, such as
appending a file to $GITHUB_OUTPUT, to a following step. Secrets reach the
sandbox only through the calling step's env: and the pass-env list.
inputs:
hosts:
description: Egress hosts to allow, one HOST or HOST:PORT per line
default: ""
pass-env:
description: Environment variable names to keep inside the sandbox, one per line
default: ""
command:
description: The command the sandbox runs
required: true
runs:
using: composite
steps:
- name: Run in the sandbox
shell: bash
env:
SANDBOX_HOSTS: ${{ inputs.hosts }}
SANDBOX_PASS_ENV: ${{ inputs.pass-env }}
SANDBOX_COMMAND: ${{ inputs.command }}
run: |
args=()
while IFS= read -r host; do
[ -n "$host" ] || continue
args+=(--allow-host "$host")
done <<< "$SANDBOX_HOSTS"
while IFS= read -r name; do
[ -n "$name" ] || continue
args+=(--pass-env "$name")
done <<< "$SANDBOX_PASS_ENV"
nix develop --command sandbox "${args[@]}" -- bash -c "$SANDBOX_COMMAND"
19 changes: 15 additions & 4 deletions .github/workflows/changeset-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,18 @@ permissions:
pull-requests: read

jobs:
check:
uses: systemfsoftware/pnpm-release-management/.github/workflows/changeset-check.yml@main
with:
tools-ref: main
require-intent:
name: a publishable-package change needs an intent
if: github.head_ref != 'changeset-release/main'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false
- uses: ./.github/actions/dev-shell
- name: Require an intent for every publishable-package change
uses: ./.github/actions/sandbox
with:
command: changeset-management check ${{ github.event.pull_request.base.sha }}
16 changes: 6 additions & 10 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -41,16 +41,9 @@ jobs:
OXLINT_FORMAT: github
steps:
- uses: actions/checkout@v7
- uses: cachix/install-nix-action@v31
- name: dprint from the flake
run: echo "$(nix build --no-link --print-out-paths .#dprint)/bin" >> "$GITHUB_PATH"
# pnpm/setup replaces pnpm/action-setup for pnpm v11+ and folds
# actions/setup-node into the same step. The node version lives here now.
- uses: pnpm/setup@v2
with:
runtime: node@24
cache: true
- run: pnpm install --frozen-lockfile
persist-credentials: false
- uses: ./.github/actions/dev-shell
- name: Turbo cache
uses: actions/cache@v6
with:
Expand All @@ -60,4 +53,7 @@ jobs:
turbo-${{ runner.os }}-dist-
turbo-${{ runner.os }}-
- name: Gate
run: ${{ matrix.gate }}
run: nix develop --command ${{ matrix.gate }}
- name: Workspace tarballs
if: matrix.leg == 'dist'
run: nix build --no-link --print-build-logs .#workspace-tarballs
11 changes: 5 additions & 6 deletions .github/workflows/commitlint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,13 @@ jobs:
if: github.actor != 'dependabot[bot]'
name: lint PR commits
runs-on: ubuntu-latest
timeout-minutes: 5
timeout-minutes: 15
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: pnpm/setup@v2
persist-credentials: false
- uses: ./.github/actions/dev-shell
- uses: ./.github/actions/sandbox
with:
runtime: node@24
cache: true
- run: pnpm install --frozen-lockfile
- run: pnpm exec commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
command: pnpm exec commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
109 changes: 109 additions & 0 deletions .github/workflows/release-gate.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
name: Release gate

on:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: release-gate-${{ github.ref }}
cancel-in-progress: false

jobs:
plan:
name: plan · mutation shards
runs-on: ubuntu-latest
timeout-minutes: 30
outputs:
matrix: ${{ steps.publish.outputs.matrix }}
has-shards: ${{ steps.publish.outputs.has-shards }}
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: ./.github/actions/dev-shell
- name: Discover mutation projects
uses: ./.github/actions/sandbox
with:
hosts: jsr.io
command: >-
deno run --config=scripts/deno.json --allow-read --allow-write
scripts/stryker-plan-gate.ts projects --out .cache/mutation-projects.txt
- id: projects
name: Publish the project list
run: echo "projects=$(cat .cache/mutation-projects.txt)" >> "$GITHUB_OUTPUT"
- name: Plan mutation shards
if: steps.projects.outputs.projects != ''
uses: ./.github/actions/sandbox
env:
MUTATION_PROJECTS: ${{ steps.projects.outputs.projects }}
with:
hosts: |
jsr.io
registry.npmjs.org
pass-env: MUTATION_PROJECTS
command: ./node_modules/.bin/stryker plan --target-seconds 900 --projects "$MUTATION_PROJECTS" --out .cache/stryker-plan.json
- name: Gate the plan
uses: ./.github/actions/sandbox
with:
hosts: jsr.io
command: >-
deno run --config=scripts/deno.json --allow-read --allow-write
scripts/stryker-plan-gate.ts gate --plan .cache/stryker-plan.json --out .cache/mutation-plan.out
- id: publish
name: Publish the plan
run: cat .cache/mutation-plan.out >> "$GITHUB_OUTPUT"
- if: always()
uses: actions/upload-artifact@v6
with:
name: stryker-plan
path: .cache/stryker-plan.json
if-no-files-found: ignore

mutation:
name: mutation · shard ${{ matrix.shard }}
needs: [plan]
if: needs.plan.outputs.has-shards == 'true'
runs-on: ubuntu-latest
timeout-minutes: 75
strategy:
fail-fast: false
matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}
env:
CI: "true"
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: ./.github/actions/dev-shell
- name: Download the shard plan
uses: actions/download-artifact@v6
with:
name: stryker-plan
path: .cache
- name: Stryker incremental cache
uses: actions/cache@v6
with:
path: |
packages/*/reports/stryker-incremental.json
.cache/reports/shards/**/stryker-incremental.json
key: stryker-shard-${{ matrix.shard }}-${{ github.sha }}
restore-keys: stryker-shard-${{ matrix.shard }}-
- name: Mutation at break 100
uses: ./.github/actions/sandbox
env:
MUTATION_SHARD: ${{ matrix.shard }}
with:
pass-env: MUTATION_SHARD
command: ./node_modules/.bin/stryker run --plan .cache/stryker-plan.json --shard "$MUTATION_SHARD"
- if: always()
uses: actions/upload-artifact@v6
with:
name: mutation-shard-${{ strategy.job-index }}
path: |
.cache/reports/shards/**
packages/*/reports/mutation-report.*
if-no-files-found: ignore
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,5 @@ reports/
.direnv/
result
result-*
.sfs-deps
.cache/
2 changes: 1 addition & 1 deletion .husky/commit-msg
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
#!/usr/bin/env bash
set -e
pnpm exec commitlint --edit "$1"
sandbox --pass-env GIT_INDEX_FILE --pass-env GIT_DIR --pass-env GIT_WORK_TREE -- pnpm exec commitlint --edit "$1"
2 changes: 1 addition & 1 deletion .husky/pre-commit
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ if [ -e "$(git rev-parse --git-path MERGE_HEAD)" ]; then
exit 0
fi

pnpm precommit
sandbox --pass-env GIT_INDEX_FILE --pass-env GIT_DIR --pass-env GIT_WORK_TREE -- pnpm precommit
12 changes: 6 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# starter
# xstate

Starter template for TypeScript / Effect libraries and tools.
The `@systemfsoftware/xstate*` packages: systemfsoftware's owned fork of XState v6 on Effect 4.

## Boundaries

Expand All @@ -21,14 +21,14 @@ Starter template for TypeScript / Effect libraries and tools.
| `START-3` | All test suites pass | `pnpm test` |
| `START-4` | Full CI validation passes before completion | `pnpm check:ci` |

Workspace roots: `packages/` holds libraries, `apps/` holds publishable
applications — both are workspace globs in `pnpm-workspace.yaml`. Turbo declares
`dist/**` as each package's build output; `pnpm gate:dist` runs that build.
Turbo declares `dist/**` as each package's build output; `pnpm gate:dist` runs
that build. `nix build .#workspace-tarballs` packs every public workspace package
through pnpm-release-management's `mkPnpmWorkspacePackages`.

## CI

- Every job runs on GitHub-hosted runners: `ubuntu-latest`, and `macos-latest` for the macOS `check:ci` leg. This repository is public, and the org's self-hosted fleet runner group admits only private repositories (fork safety), so a `[self-hosted, systemfsoftware-runner, *]` job here queues forever. Gate: review of the workflow diff.
- Heavy suites split across parallel hosted jobs instead of a larger runner: Linux `check:ci` runs as one job per part (format, lint, typecheck, test, dist), and mutation on `main` runs one job per package. Gate: review of the workflow diff.
- Heavy suites split across parallel hosted jobs instead of a larger runner: Linux `check:ci` runs as one job per part (format, lint, typecheck, test, dist), and mutation on `main` runs one job per shard of the `stryker plan` fan-out. Gate: review of the workflow diff.

## End of Session

Expand Down
21 changes: 15 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,23 @@ Contributions are welcome. Follow these instructions to set up the development e

## Prerequisites

- [Node.js](https://nodejs.org/) `>=24`
- [pnpm](https://pnpm.io/) `>=12.4.2` (the `packageManager` field pins the exact version; Corepack resolves it)
- [Nix](https://nixos.org/download/) with flakes enabled. Its dev shell pins Node.js, pnpm, Deno and dprint, and carries the sandbox that every command running dependency code goes through.
- On Linux, unprivileged user namespaces, which the sandbox needs. Ubuntu 24.04 blocks them by default; lift the block with `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`.
- Optional: [direnv](https://direnv.net/), which enters the dev shell when you `cd` into the repository.

## Setup

Clone the repository and install dependencies:
Clone the repository, enter the dev shell and install:

```bash
git clone <your-repo-url>
cd <your-repo>
pnpm install
git clone https://github.com/systemfsoftware/xstate
cd xstate
nix develop # or: direnv allow
pnpm bootstrap
```

Dependency code never runs on your machine directly. Installs, builds, tests and git hooks run inside the sandbox, which reaches only the network hosts a command declares and writes only inside the project. `pnpm bootstrap` installs offline from the Nix pnpm store, then runs the allowed build scripts and `prepare` inside the sandbox. A plain `pnpm install` runs no scripts at all (`ignoreScripts` in `pnpm-workspace.yaml`), so it leaves the tree without its builds and patches; run `pnpm bootstrap` instead. pnpm never installs on its own before a script (`verifyDepsBeforeRun: warn`): when a script warns that your node_modules are out of sync with the lockfile, rerun `pnpm bootstrap`.

## Workflows and Commands

The project uses [Turbo](https://turbo.build/) to orchestrate tasks across workspaces:
Expand All @@ -42,8 +46,13 @@ pnpm lint

# Run all CI gates locally
pnpm check:ci

# Pack every public package into a tarball
nix build .#workspace-tarballs
```

Mutation testing is not part of `pnpm check:ci`. The release gate (`.github/workflows/release-gate.yml`) runs `stryker plan` once over every workspace package that declares a `mutation` script, then `stryker run` for each planned shard at a break threshold of 100 on every push to `main`.

## Pull Requests & Commits

- We follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat(cli): ...`, `fix(core): ...`).
Expand Down
Loading
Loading