Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
37 changes: 37 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ on:

permissions:
contents: read
# scripts/ci-tested lists the tested-tree artifacts.
actions: read

# A new push to the same branch makes the previous run's result obsolete, and
# leaving it running lets a stale result report after the newer one.
Expand All @@ -30,6 +32,20 @@ jobs:
with:
fetch-depth: 0

# A push whose tree a pull request run already passed -- a merge, squash
# or fast-forward onto a base that has not moved since -- would prove that
# tree twice. scripts/ci-tested looks for the tree the run recorded at the
# end of this job, and every doubt runs the checks. Only on a self-hosted
# runner: it is the operator's machine that pays for the second run, and
# it keeps toolchain caches on disk, while on a hosted runner a skipped
# push stops main saving the caches every pull request restores.
- name: Find a passing run on this tree
id: tested
if: github.event_name == 'push' && vars.RUNNER != ''
env:
GH_TOKEN: ${{ github.token }}
run: scripts/ci-tested >> "$GITHUB_OUTPUT"

# adr-index-test and commitlint-test both skip their hook-wiring cases
# when pre-commit is absent, and those cases are the ones that catch a
# hook pre-commit never invokes -- the failure both suites exist for.
Expand All @@ -43,11 +59,13 @@ jobs:
# path of this job, which was accepted rather than shipping a
# commit-message rule to every generated repository unproven.
- name: Install pre-commit
if: steps.tested.outputs.skip != 'true'
run: pipx install pre-commit

# Before the toolchains, since these install none and verify both the
# language-capabilities wiring and the local/hosted check boundary.
- name: Verify repository scripts
if: steps.tested.outputs.skip != 'true'
run: scripts/script-tests

# The hook receives the same base-to-head file range a push does. It
Expand All @@ -63,7 +81,26 @@ jobs:
--from-ref "$BASE_SHA" --to-ref "$HEAD_SHA"

- name: Set up toolchains
if: steps.tested.outputs.skip != 'true'
uses: ./.github/actions/setup-toolchains

- name: Run CI checks
if: steps.tested.outputs.skip != 'true'
run: scripts/ci

# The tree this run just passed, the merge ref's, for scripts/ci-tested
# on the push that lands it. Reached only when every check above passed.
- name: Name the tested tree
id: tree
if: github.event_name == 'pull_request' && vars.RUNNER != ''
run: |
git rev-parse 'HEAD^{tree}' > "$RUNNER_TEMP/tested-tree"
echo "tree=$(cat "$RUNNER_TEMP/tested-tree")" >> "$GITHUB_OUTPUT"

- name: Record the tested tree
if: steps.tree.outcome == 'success'
uses: actions/upload-artifact@v7
with:
name: ci-tested-tree-${{ steps.tree.outputs.tree }}
path: ${{ runner.temp }}/tested-tree
retention-days: 30
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Use these instead of per-language tools; each detects the languages present and

- `scripts/doctor` — verify local toolchains, dependencies, hooks, and configuration without contacting hosted services
- `scripts/repo-settings check` — inspect GitHub-hosted security and branch settings; run explicitly, since it needs the network and administration visibility
- `scripts/check` — the full local gate: `doctor`, `structure` and `payload-parity`, then lint, format, type check, test, and build with the script tests beside them, the security audit, and pre-commit over every file, tracked and untracked. It prints only the Result table and always writes the full run to `tmp/check.log`; `--verbose` streams everything. It reads no hosted GitHub state but is not offline: `commitlint-test` and pre-commit's hook environments fetch on first use
- `scripts/check` — the full local gate: `doctor`, `structure` and `payload-parity`, then lint, format, type check, test, and build with the script tests beside them, the security audit, and pre-commit over every file, tracked and untracked. It prints only the Result table and always writes the full run to `tmp/check.log`; `--verbose` streams everything; `--fast` leaves out `build`, which CI runs on the pull request. It reads no hosted GitHub state but is not offline: `commitlint-test` and pre-commit's hook environments fetch on first use
- `scripts/fix` — the write half of `check`: lint autofix, then formatting, for every stack, unconditionally and in that order so the formatter lays out what the linter rewrote. Go, Swift and Kotlin have no lint autofix and report `lint-fix` `not-applicable`. A `lint-fix` FAIL means findings remain that need hand work
- `scripts/summarize <command…>` — run a check and print only its Result table with findings, then a verdict line of its exit status and a count per state, exiting with that status; read `ci` and other commands through this, since `check` already does
- `scripts/clean` — recursively delete build output and tool caches (`dist`, `build`, `coverage`, `__pycache__`, `.*_cache`, `*.pyc`)
Expand All @@ -53,7 +53,7 @@ The only non-shell code here is the Python under `apps/repo-builder/`, declared
## Git

- Pre-commit blocks commits to `main` and `master`; branch first.
- Run `scripts/check` before committing. It runs CI's checks plus pre-commit over every file, but with the machine's tool versions rather than CI's fresh installs, so a lint can pass here and fail there; `scripts/CLAUDE.md` carries the rule.
- Run `scripts/check --fast` before committing, and the whole `scripts/check` when the change could break the build. It runs CI's checks plus pre-commit over every file, `--fast` leaving the build to CI, but with the machine's tool versions rather than CI's fresh installs, so a lint can pass here and fail there; `scripts/CLAUDE.md` carries the rule.
- These prompt for approval: `git reset --hard`, `git clean`, `git rebase`, `rm`, `git rm`, and the `gh` commands that merge pull requests, cut releases, or delete the repository. Edits do not: this repository's `.claude/settings.json` allows `Edit(/**)`, anchored at the session's starting directory, so a session started at the checkout root edits or writes any file without a prompt, root files and dotfiles included. Claude Code's built-in protected paths, such as `.claude/`, `.git/`, `.devcontainer/`, and `.pre-commit-config.yaml`, stay gated whatever an allow rule says, and so do the files the operator's global `ask` rules name, such as `.env`, `*.pem`, and `secrets/`, since an `ask` outranks an `allow`.
- Work reaches `main` through a pull request under `.github/PULL_REQUEST_TEMPLATE.md`; a ruleset enforces it (Repository settings below).
- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification): `type(optional scope): subject`, a blank line, then the body. commitlint enforces it at `commit-msg`, with rules in `.commitlintrc.yaml`. The subject is lowercase after the type, with no trailing period. A body is expected: it is the only surviving record of why.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ type: Note

### GitHub Automation

`.github/workflows/ci.yml`: Runs tests, linting, formatting checks, type checks, and builds on every push and pull request.
`.github/workflows/ci.yml`: Runs tests, linting, formatting checks, type checks, and builds on every pull request and every push to `main`. On a self-hosted runner, a passing pull request run records the tree it tested as an artifact, and a push whose tree one of those records names skips the checks and goes green; `scripts/ci-tested` decides.

`.github/workflows/release.yml`: Validates a tagged release and publishes it, both through `scripts/release`.

Expand Down Expand Up @@ -79,7 +79,9 @@ The specific operating parameters for the AI agent.

`scripts/script-tests`: Runs every `scripts/tests/*-test` concurrently, one per CPU, and prints each one's output whole once all have finished, naming every test that failed. Called by `scripts/check` and by `ci.yml`, so both run the suites the same way. The suites spend their time waiting on git and child processes, so running them side by side cuts the wall time several-fold.

`scripts/check`: The full local gate. By default it prints only the Result table and the findings under any check that failed, by running itself under `scripts/summarize`, and it writes the complete run to `tmp/check.log` every time, passing or failing, since a pre-commit fixer repairs the file and a re-run no longer reproduces the failure. `--verbose` streams the whole run live, still writing the log. Exits with the gate's status either way. `scripts/script-tests` runs beside `scripts/ci`, since neither fills the CPUs, with its output printed once `ci` ends; the pre-commit sweep runs last, because its fixers rewrite files the other two read, and skips the hooks that repeat a step the gate already ran over the whole tree.
`scripts/check`: The full local gate. By default it prints only the Result table and the findings under any check that failed, by running itself under `scripts/summarize`, and it writes the complete run to `tmp/check.log` every time, passing or failing, since a pre-commit fixer repairs the file and a re-run no longer reproduces the failure. `--verbose` streams the whole run live, still writing the log. `--fast` is the commit-time gate: every step but `build`, which CI runs on the same commit before it can land. Exits with the gate's status either way. `scripts/script-tests` runs beside `scripts/ci`, since neither fills the CPUs, with its output printed once `ci` ends; the pre-commit sweep runs last, because its fixers rewrite files the other two read, and skips the hooks that repeat a step the gate already ran over the whole tree.

`scripts/ci-tested`: Called by `ci.yml` on a push to `main` on a self-hosted runner, and nowhere else, since it reads hosted run state. Prints `skip=true` when an unexpired `ci-tested-tree-<tree>` artifact from a same-repository pull request run names the push's tree: a merge, squash or fast-forward onto a base that has not moved since that run. Anything else, including a failed query, prints `skip=false` and the checks run.

`scripts/summarize`: Runs a check command and prints only its Result table — one line per check, the findings under any that failed — dropping every other thing the command wrote. Exits with that command's status, so it can stand in for the command rather than only report on it, and ends with a verdict line naming that status and a count per state. `scripts/check` is its first caller; it stays the way to read `scripts/ci` and any other command. It is the one consumer of the printed layout `scripts/libs/result.sh` documents, which is where a change to the column widths has to be reflected.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ on:

permissions:
contents: read
# scripts/ci-tested lists the tested-tree artifacts.
actions: read

# A new push to the same branch makes the previous run's result obsolete, and
# leaving it running lets a stale result report after the newer one.
Expand All @@ -30,6 +32,20 @@ jobs:
with:
fetch-depth: 0

# A push whose tree a pull request run already passed -- a merge, squash
# or fast-forward onto a base that has not moved since -- would prove that
# tree twice. scripts/ci-tested looks for the tree the run recorded at the
# end of this job, and every doubt runs the checks. Only on a self-hosted
# runner: it is the operator's machine that pays for the second run, and
# it keeps toolchain caches on disk, while on a hosted runner a skipped
# push stops main saving the caches every pull request restores.
- name: Find a passing run on this tree
id: tested
if: github.event_name == 'push' && vars.RUNNER != ''
env:
GH_TOKEN: ${{ github.token }}
run: scripts/ci-tested >> "$GITHUB_OUTPUT"

# adr-index-test and commitlint-test both skip their hook-wiring cases
# when pre-commit is absent, and those cases are the ones that catch a
# hook pre-commit never invokes -- the failure both suites exist for.
Expand All @@ -43,11 +59,13 @@ jobs:
# path of this job, which was accepted rather than shipping a
# commit-message rule to every generated repository unproven.
- name: Install pre-commit
if: steps.tested.outputs.skip != 'true'
run: pipx install pre-commit

# Before the toolchains, since these install none and verify both the
# language-capabilities wiring and the local/hosted check boundary.
- name: Verify repository scripts
if: steps.tested.outputs.skip != 'true'
run: scripts/script-tests

# The hook receives the same base-to-head file range a push does. It
Expand All @@ -63,7 +81,26 @@ jobs:
--from-ref "$BASE_SHA" --to-ref "$HEAD_SHA"

- name: Set up toolchains
if: steps.tested.outputs.skip != 'true'
uses: ./.github/actions/setup-toolchains

- name: Run CI checks
if: steps.tested.outputs.skip != 'true'
run: scripts/ci

# The tree this run just passed, the merge ref's, for scripts/ci-tested
# on the push that lands it. Reached only when every check above passed.
- name: Name the tested tree
id: tree
if: github.event_name == 'pull_request' && vars.RUNNER != ''
run: |
git rev-parse 'HEAD^{tree}' > "$RUNNER_TEMP/tested-tree"
echo "tree=$(cat "$RUNNER_TEMP/tested-tree")" >> "$GITHUB_OUTPUT"

- name: Record the tested tree
if: steps.tree.outcome == 'success'
uses: actions/upload-artifact@v7
with:
name: ci-tested-tree-${{ steps.tree.outputs.tree }}
path: ${{ runner.temp }}/tested-tree
retention-days: 30
2 changes: 1 addition & 1 deletion apps/github-repository-template/src/base-repo/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ These sections are identical in every repository built from the template. Do not

Use these instead of per-language tools. `check` and `fix` run for every language present and report `pass`, `not-applicable`, `unavailable`, or `FAIL`.

- `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, structure, then lint, format, type check, test, and build with the script tests beside them, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything
- `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, structure, then lint, format, type check, test, and build with the script tests beside them, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything; `--fast`, the commit-time gate, leaves `build` to CI and so is no superset of it
- `scripts/fix` — lint autofix, then formatting
- `scripts/summarize <command…>` — run a check and print only its Result table, then a verdict line of its exit status and a count per state; read `ci` and other commands through this, since `check` already does
- `scripts/run [unit] [--entry <name>] [-- args…]` — start a unit; the unit name is required when `apps/` holds several
Expand Down
43 changes: 34 additions & 9 deletions apps/github-repository-template/src/base-repo/scripts/check
Original file line number Diff line number Diff line change
Expand Up @@ -20,23 +20,44 @@ cd "$repo_root"
# the cause is gone; the log is what a failure outside the table is diagnosed
# from. --verbose streams the same text live. --gate is the internal entry that
# runs the steps below and nothing else, so the tee wraps exactly one run.
case "${1:-}" in
#
# --fast is the commit-time gate: every step below except build, which CI runs
# on the same commit before it can land and which costs more than the rest of
# the gate together in a repository that compiles. It rides through each entry,
# and tmp/check.log opens by saying build was left out, so a fast run's log
# never reads as the full gate's.
usage() {
echo "usage: scripts/check [--fast] [--verbose]" >&2
exit 2
}
mode=""
fast=()
for arg in "$@"; do
case "$arg" in
--verbose | --gate)
[[ -z "$mode" ]] || usage
mode="$arg"
;;
--fast) fast=(--fast) ;;
*) usage ;;
esac
done
case "$mode" in
"")
exec scripts/summarize scripts/check --verbose
exec scripts/summarize scripts/check --verbose "${fast[@]}"
;;
--verbose)
mkdir -p tmp
# pipefail (set above) makes the pipeline's status the gate's, not tee's.
scripts/check --gate 2>&1 | tee tmp/check.log
scripts/check --gate "${fast[@]}" 2>&1 | tee tmp/check.log
exit "${PIPESTATUS[0]}"
;;
--gate) ;;
*)
echo "usage: scripts/check [--verbose]" >&2
exit 2
;;
esac

if (( ${#fast[@]} )); then
echo "scripts/check --fast: build is left to CI."
fi

if [[ ! -x scripts/doctor ]]; then
echo "scripts/doctor is missing or not executable."
exit 1
Expand Down Expand Up @@ -100,8 +121,12 @@ trap 'exit 130' INT
trap 'exit 143' TERM
trap 'exit 141' PIPE

ci_args=()
if (( ${#fast[@]} )); then
ci_args=(--no-build)
fi
ci_status=0
scripts/ci || ci_status=$?
scripts/ci "${ci_args[@]}" || ci_status=$?
script_tests_status=0
wait "$script_tests_pid" || script_tests_status=$?
# Reaped, so its PID may now belong to another process.
Expand Down
15 changes: 14 additions & 1 deletion apps/github-repository-template/src/base-repo/scripts/ci
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,19 @@ cd "$repo_root"
# shellcheck source=libs/detect.sh
source "$repo_root/scripts/libs/detect.sh"

# --no-build leaves build out, for `scripts/check --fast`: the commit-time gate
# drops the slowest check CI repeats on the same commit before it can land.
# CI itself never passes it.
capabilities=(lint format-check typecheck test build)
case "${1:-}" in
"") ;;
--no-build) capabilities=(lint format-check typecheck test) ;;
*)
echo "usage: scripts/ci [--no-build]" >&2
exit 2
;;
esac

# The shared policy: orphan search before the checks, which would run green over
# the package none of them sees; the no-manifest early-out; the dry run.
capability_command check lint format-check typecheck test build
capability_command check "${capabilities[@]}"
39 changes: 39 additions & 0 deletions apps/github-repository-template/src/base-repo/scripts/ci-tested
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
#!/usr/bin/env bash
set -euo pipefail

# Whether a passing pull request run of ci.yml already tested the tree a push to
# the default branch landed, so ci.yml can skip its checks instead of proving
# the same tree twice. Prints `skip=true` or `skip=false` for $GITHUB_OUTPUT
# and the reason on stderr, which the job log keeps.
#
# scripts/ci-tested
#
# A pull request run that passes uploads an artifact named for the tree it
# tested, its merge ref's: ci-tested-tree-<tree>. The push skips when an
# unexpired one of those names HEAD's tree, so any merge, squash or
# fast-forward whose result is a tree some run already passed skips, and one
# onto a base that moved since does not. Only the name says the run passed, and
# a pull request can rewrite the workflow that uploads it, so artifacts from a
# fork's run, or with no run at all, are ignored. A branch in this repository
# is trusted the same way: whoever can push one can already push to the
# default branch.
#
# Called by ci.yml alone: it reads hosted run state, which no local command does.
# Every doubt answers skip=false, since running the checks again costs minutes
# and skipping them wrongly leaves the branch unproven.

decide() {
echo "ci-tested: $2" >&2
echo "skip=$1"
exit 0
}

tree="$(git rev-parse 'HEAD^{tree}')"
count="$(gh api "repos/${GITHUB_REPOSITORY:?}/actions/artifacts?name=ci-tested-tree-$tree&per_page=100" \
--jq '[.artifacts[] | select((.expired | not) and .workflow_run.repository_id != null
and .workflow_run.head_repository_id == .workflow_run.repository_id)] | length' \
2>/dev/null)" || decide false "could not read the tested-tree artifacts"

[[ "$count" =~ ^[1-9] ]] ||
decide false "no passing pull request run tested tree $tree"
decide true "a passing pull request run tested tree $tree, the tree now on the branch"
Loading