diff --git a/.github/workflows/check.yaml b/.github/workflows/check.yaml new file mode 100644 index 0000000..af51b7e --- /dev/null +++ b/.github/workflows/check.yaml @@ -0,0 +1,50 @@ +# Check: runs the checks AGENTS.md asks for after every change, on every PR and on main. +name: Check + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +concurrency: + group: check-${{ github.ref }} + cancel-in-progress: true + +jobs: + go: + name: ilttu-design + runs-on: ubuntu-latest + defaults: + run: + working-directory: ilttu-design + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: ilttu-design/go.mod + cache: false + + - name: Vet and test + run: | + go vet ./... + go test ./... + + plugins: + name: Plugin manifests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + # Validating needs no sign-in. The version is pinned, so a new Claude Code can't change what passes. + - name: Validate the marketplace and the plugin + run: | + npx --yes @anthropic-ai/claude-code@2.1.311 plugin validate . + npx --yes @anthropic-ai/claude-code@2.1.311 plugin validate plugins/ilttu diff --git a/.github/workflows/ilttu-design-release.yml b/.github/workflows/ilttu-design-release.yml deleted file mode 100644 index b5cdbb8..0000000 --- a/.github/workflows/ilttu-design-release.yml +++ /dev/null @@ -1,43 +0,0 @@ -# Builds ilttu-design for each platform the plugin's wrapper runs on, and publishes them as a GitHub release, when a tag ilttu-design-v is pushed. -# A tag push runs the workflow file at the tagged commit, so a release can be cut from a branch before it merges. -# After a release, pin its tag and each binary's SHA-256 in plugins/ilttu/bin/ilttu-design. -name: Release ilttu-design - -on: - push: - tags: - - "ilttu-design-v*" - -permissions: - contents: write - -jobs: - release: - runs-on: ubuntu-latest - defaults: - run: - working-directory: ilttu-design - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 - with: - go-version-file: ilttu-design/go.mod - cache: false - - name: Vet and test - run: | - go vet ./... - go test ./... - - name: Build - env: - TAG: ${{ github.ref_name }} - run: | - mkdir dist - for target in darwin/arm64 darwin/amd64 linux/arm64 linux/amd64; do - CGO_ENABLED=0 GOOS="${target%/*}" GOARCH="${target#*/}" go build -trimpath -ldflags "-s -w -X main.version=${TAG}" -o "dist/ilttu-design-${target%/*}-${target#*/}" . - done - (cd dist && sha256sum ilttu-design-* > SHA256SUMS && cat SHA256SUMS) - - name: Publish - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ github.ref_name }} - run: gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --verify-tag --title "$TAG" --notes "ilttu-design ${TAG#ilttu-design-}, built from ${GITHUB_SHA}. The plugin's wrapper, plugins/ilttu/bin/ilttu-design, pins each binary's SHA-256." diff --git a/.github/workflows/pr-title.yaml b/.github/workflows/pr-title.yaml new file mode 100644 index 0000000..85de256 --- /dev/null +++ b/.github/workflows/pr-title.yaml @@ -0,0 +1,36 @@ +# Checks the PR title is a Conventional Commit. +# +# Its own workflow, not a job in check.yaml, because it must rerun when a title is edited, and an edit event sharing that workflow's concurrency group cancels the code check in flight. +name: PR title + +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: {} + +concurrency: + group: pr-title-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + title: + name: Conventional Commit title + runs-on: ubuntu-latest + steps: + # release-please builds the changelogs from squash-merge titles, so the PR title is the commit message that matters. + # The title arrives through env, never interpolated into the script, so a crafted title cannot inject shell. + - name: Check the PR title + env: + TITLE: ${{ github.event.pull_request.title }} + run: | + pattern='^(feat|fix|docs|chore|refactor|test|ci|build|perf|revert|style)(\([a-z0-9-]+\))?!?: [^ ].*$' + if ! printf '%s' "$TITLE" | grep -Eq "$pattern"; then + echo "::error::PR title is not a Conventional Commit: $TITLE" + echo "Expected ()!: , e.g. feat(ilttu): preview a design on localhost" + exit 1 + fi + if [ "${#TITLE}" -gt 72 ]; then + echo "::error::PR title is ${#TITLE} characters, more than 72: $TITLE" + exit 1 + fi diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 0000000..f7f82c3 --- /dev/null +++ b/.github/workflows/release.yaml @@ -0,0 +1,150 @@ +# Release: release-please keeps one release PR open against main, built from the Conventional Commit titles of the squash merges since each package's last release. +# The packages are the ilttu plugin (plugins/ilttu, tagged ilttu-v) and ilttu-design (ilttu-design/, tagged ilttu-design-v); release-please-config.json names them. +# Merging the release PR bumps the plugin's version in plugin.json, writes each package's CHANGELOG.md, tags each package it releases and creates its GitHub Release. +# +# ilttu-design's release is created as a draft, with its tag made at once ("draft" and "force-tag-creation" in release-please-config.json). +# The ilttu-design job builds it from the tag, attaches the binaries and SHA256SUMS, and publishes it, so the release is never public without its assets. +# A failed build leaves an unpublished draft: rerun the failed job, which keeps release-please's outputs; a new run would not, since release-please creates each release only once. +# The pin job then opens a PR that pins the new release in plugins/ilttu/bin/ilttu-design, with scripts/pin-ilttu-design; merging it makes the next plugin release run it. +# +# release-please and the pin job act as the organisation's release GitHub App, with a token minted from the RELEASE_PLEASE_CLIENT_ID and RELEASE_PLEASE_PRIVATE_KEY org secrets, because a PR or tag made with GITHUB_TOKEN triggers no further workflows, and the release and pin PRs need their checks to run. +name: Release + +on: + push: + branches: [main] + # Reruns release-please after a transient failure without needing a new commit. + workflow_dispatch: + +permissions: {} + +# Never cancel a run partway: it could stop between tagging and creating a release, or between attaching the assets and publishing. +concurrency: + group: release + cancel-in-progress: false + +jobs: + release-please: + name: release-please + runs-on: ubuntu-latest + outputs: + design_released: ${{ steps.release.outputs['ilttu-design--release_created'] }} + design_tag: ${{ steps.release.outputs['ilttu-design--tag_name'] }} + steps: + # Without owner or repositories inputs the token is scoped to this repository; the permission inputs narrow it to what release-please uses. + - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + id: app-token + with: + client-id: ${{ secrets.RELEASE_PLEASE_CLIENT_ID }} + private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }} + permission-contents: write + permission-pull-requests: write + permission-issues: write + + - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0 + id: release + with: + token: ${{ steps.app-token.outputs.token }} + config-file: release-please-config.json + manifest-file: .release-please-manifest.json + + ilttu-design: + name: Build and publish ilttu-design + needs: release-please + if: needs.release-please.outputs.design_released == 'true' + runs-on: ubuntu-latest + permissions: + # Attaching the assets to the draft and publishing it. + contents: write + env: + TAG: ${{ needs.release-please.outputs.design_tag }} + defaults: + run: + working-directory: ilttu-design + steps: + # The tag, not main's tip: main may have moved on. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: refs/tags/${{ needs.release-please.outputs.design_tag }} + persist-credentials: false + + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: ilttu-design/go.mod + cache: false + + - name: Vet and test + run: | + go vet ./... + go test ./... + + # -trimpath and no cgo, so a build of the tag on any machine with the same Go makes the same bytes. + # The binaries go outside the checkout: a file left inside it makes Go stamp every later build vcs.modified=true. + - name: Build + run: | + mkdir "$RUNNER_TEMP/dist" + for target in darwin/arm64 darwin/amd64 linux/arm64 linux/amd64; do + CGO_ENABLED=0 GOOS="${target%/*}" GOARCH="${target#*/}" go build -trimpath -ldflags "-s -w -X main.version=${TAG}" -o "$RUNNER_TEMP/dist/ilttu-design-${target%/*}-${target#*/}" . + done + (cd "$RUNNER_TEMP/dist" && sha256sum ilttu-design-* > SHA256SUMS && cat SHA256SUMS) + changes="$(git status --porcelain --untracked-files=all)" + if [ -n "$changes" ]; then echo "::error::the build left files in the checkout"; echo "$changes"; exit 1; fi + + # --clobber makes a rerun replace what an earlier attempt attached. Publishing comes last. + - name: Attach the assets and publish + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release upload "$TAG" "$RUNNER_TEMP"/dist/* --repo "$GITHUB_REPOSITORY" --clobber + gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --draft=false + + pin: + name: Pin ilttu-design in the plugin + needs: [release-please, ilttu-design] + runs-on: ubuntu-latest + env: + TAG: ${{ needs.release-please.outputs.design_tag }} + steps: + - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + id: app-token + with: + client-id: ${{ secrets.RELEASE_PLEASE_CLIENT_ID }} + private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }} + permission-contents: write + permission-pull-requests: write + + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: main + token: ${{ steps.app-token.outputs.token }} + + # The sums come from the published release, the same file a person can check them against. + - name: Download the release's SHA256SUMS + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: gh release download "$TAG" --repo "$GITHUB_REPOSITORY" --pattern SHA256SUMS --dir "$RUNNER_TEMP" + + # No token in this step's env. Checkout keeps the App token in .git/config for the push below, which is acceptable: this job runs only on a push to main, and the script comes from main. + - name: Pin the release + run: | + scripts/pin-ilttu-design "$TAG" "$RUNNER_TEMP/SHA256SUMS" + git diff + + # A rerun force-pushes the same branch and reuses its PR, and does nothing once the pin is on main. + - name: Open the PR + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + SLUG: ${{ steps.app-token.outputs.app-slug }} + run: | + branch="pin/${TAG}" + title="fix(ilttu): run ilttu-design ${TAG#ilttu-design-}" + id="$(gh api "/users/${SLUG}[bot]" --jq .id)" + git config user.name "${SLUG}[bot]" + git config user.email "${id}+${SLUG}[bot]@users.noreply.github.com" + git switch -c "$branch" + if git diff --quiet; then echo "plugins/ilttu/bin/ilttu-design already pins ${TAG}"; exit 0; fi + git commit -am "$title" + git push --force origin "$branch" + if [ -z "$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$branch" --json number --jq '.[].number')" ]; then + gh pr create --repo "$GITHUB_REPOSITORY" --base main --head "$branch" --title "$title" --body "Pins \`plugins/ilttu/bin/ilttu-design\` to ${TAG} and the SHA-256s in its published \`SHA256SUMS\`: https://github.com/${GITHUB_REPOSITORY}/releases/tag/${TAG}." + fi diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 0000000..6406282 --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,4 @@ +{ + "plugins/ilttu": "0.3.1", + "ilttu-design": "0.1.1" +} diff --git a/AGENTS.md b/AGENTS.md index ea13fcb..b947f16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,14 +12,19 @@ ILTTU itself, its issues and its decisions are in `asteroid-computing/ilttu`, wh - `plugins/ilttu/skills/design/` - `/ilttu:design`: designing a page, previewing it as an ILTTU answer and revising it at the same link, with `SKILL.md` and its `references/`. - `plugins/ilttu/bin/ilttu-design` - the wrapper that downloads `ilttu-design`'s pinned release, checks its SHA-256 and runs it. - `ilttu-design/` - `ilttu-design`, a Go module on the standard library alone: `serve` previews a design's folder as ILTTU's answers' host serves it, and `init` copies in the design system vendored in `designsystem/`. -- `.github/workflows/ilttu-design-release.yml` - builds and publishes a release of `ilttu-design` when a tag `ilttu-design-v` is pushed. +- `release-please-config.json` and `.release-please-manifest.json` - the two packages release-please releases, `plugins/ilttu` tagged `ilttu-v` and `ilttu-design` tagged `ilttu-design-v`, and their last versions. +- `.github/workflows/release.yaml` - on main, keeps release-please's release PR open, and when `ilttu-design` releases, builds and publishes its binaries and opens a PR that pins them. +- `.github/workflows/check.yaml` and `pr-title.yaml` - the checks below and the PR title's, on every PR. +- `scripts/pin-ilttu-design` - pins a release's tag and SHA-256s in `plugins/ilttu/bin/ilttu-design`. ## Rules - **Validate after every change:** `claude plugin validate .` and `claude plugin validate plugins/ilttu`, and in `ilttu-design/`, `go vet ./...` and `go test ./...`. -- **A change to `ilttu-design/` reaches people only through a release:** push a tag `ilttu-design-v`, then pin that tag and each binary's SHA-256 from the release's `SHA256SUMS` in `plugins/ilttu/bin/ilttu-design`, and bump the plugin's version. +- **Releases come from release-please, never by hand:** merging its release PR tags each package it releases, so never push a tag or edit a version, a `CHANGELOG.md` or the manifest yourself. +- **A change to `ilttu-design/` reaches people in three merges:** its own PR, the release PR that releases `ilttu-design`, then the pin PR the Release workflow opens, which the next release PR ships in the plugin. - **`serve` sends what ILTTU's answers' host sends**, checked against `internal/edge` and `internal/cdk/answers` in `asteroid-computing/ilttu`, and its file types are a copy of ILTTU's `internal/filetypes`, so a change there is a change here too. -- **Change a plugin's `version` in `plugin.json` with every change to it**, because people stay on their copy until the version changes. +- **A plugin's change reaches people when its release PR merges**, which changes its `version` in `plugin.json`, because people stay on their copy until the version changes. + So a change under `plugins/ilttu/` needs a `feat` or `fix` title to be released at all. - **The connection's values are exact.** The URL is `https://mcp.ilttu.com/`, slash included, as Connect on ILTTU's workspace page gives it and as ILTTU's user pool identifies the resource agents sign in for. The `oauth` block must stay, because ILTTU's authorization server offers no dynamic client registration, so without a client ID Claude Code can't sign in. diff --git a/SECURITY.md b/SECURITY.md index cb4080b..bd4ad1e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -17,4 +17,5 @@ Do not commit tokens, workspace keys, local tool settings or generated authentic `plugins/ilttu/bin/ilttu-design` downloads one release of `ilttu-design` from this repository's GitHub Releases, over HTTPS, the first time it runs, into the plugin's data folder or the user's cache. It runs the binary only while its SHA-256 is the one pinned in the wrapper for that platform, and refuses it otherwise. -A release is built by `.github/workflows/ilttu-design-release.yml` from the tagged commit. +A release is built by `.github/workflows/release.yaml` from the tag release-please makes on `main`, and published only once its binaries and `SHA256SUMS` are attached. +The wrapper's pins change only through a reviewed PR, which the same workflow opens from the published `SHA256SUMS`. diff --git a/plugins/ilttu/bin/ilttu-design b/plugins/ilttu/bin/ilttu-design index 899e116..c1cdd25 100755 --- a/plugins/ilttu/bin/ilttu-design +++ b/plugins/ilttu/bin/ilttu-design @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Runs ilttu-design, which previews a design's folder on localhost as ILTTU will serve it, and copies the ilttu design system's assets into it. # On first use it downloads the release pinned below from GitHub, and runs it only while its SHA-256 is the one pinned here, for this platform. -# The release is built by .github/workflows/ilttu-design-release.yml from the Go module in ilttu-design/. +# The release is built by .github/workflows/release.yaml from the Go module in ilttu-design/, and scripts/pin-ilttu-design pins it here. set -euo pipefail TAG="ilttu-design-v0.1.1" diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 0000000..4d05568 --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "bump-minor-pre-major": true, + "bootstrap-sha": "ffd070302435abaebc8cea5fbecbb454dee296e6", + "packages": { + "plugins/ilttu": { + "release-type": "simple", + "component": "ilttu", + "extra-files": [ + { + "type": "json", + "path": ".claude-plugin/plugin.json", + "jsonpath": "$.version" + } + ] + }, + "ilttu-design": { + "release-type": "go", + "component": "ilttu-design", + "draft": true, + "force-tag-creation": true + } + } +} diff --git a/scripts/pin-ilttu-design b/scripts/pin-ilttu-design new file mode 100755 index 0000000..dc67e5f --- /dev/null +++ b/scripts/pin-ilttu-design @@ -0,0 +1,44 @@ +#!/usr/bin/env bash +# Pins plugins/ilttu/bin/ilttu-design to a release of ilttu-design: its tag, and each platform's SHA-256 from the release's SHA256SUMS. +# Usage: scripts/pin-ilttu-design +# The Release workflow runs it after it publishes a release; run it by hand only to pin an older release again. +set -euo pipefail + +if [ "$#" -ne 2 ]; then + echo "usage: $0 " >&2 + exit 2 +fi +tag="$1" +sums="$2" +wrapper="$(cd "$(dirname "$0")/.." && pwd)/plugins/ilttu/bin/ilttu-design" +platforms="darwin-arm64 darwin-amd64 linux-arm64 linux-amd64" + +if ! [[ "$tag" =~ ^ilttu-design-v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "not a tag of ilttu-design: ${tag}" >&2 + exit 1 +fi + +# sum prints the SHA-256 that SHA256SUMS gives for the platform $1. +sum() { awk -v f="ilttu-design-$1" '$2 == f { print $1 }' "$sums"; } + +# Every sum is checked before anything is written, so a short SHA256SUMS changes nothing. +for platform in $platforms; do + if ! [[ "$(sum "$platform")" =~ ^[0-9a-f]{64}$ ]]; then + echo "no SHA-256 for ilttu-design-${platform} in ${sums}" >&2 + exit 1 + fi +done + +pinned="$(mktemp)" +trap 'rm -f "$pinned" "${pinned}.bak"' EXIT +sed -E "s/^TAG=\"[^\"]*\"$/TAG=\"${tag}\"/" "$wrapper" > "$pinned" +for platform in $platforms; do + sed -i.bak -E "s/^( ${platform}\) echo \")[0-9a-f]{64}(\" ;;)$/\1$(sum "$platform")\2/" "$pinned" +done + +# Each line is checked, so a wrapper whose lines have changed shape fails here, not when someone runs it. +grep -qx "TAG=\"${tag}\"" "$pinned" || { echo "the wrapper has no TAG line to pin" >&2; exit 1; } +for platform in $platforms; do + grep -qx " ${platform}) echo \"$(sum "$platform")\" ;;" "$pinned" || { echo "the wrapper has no line for ${platform} to pin" >&2; exit 1; } +done +cat "$pinned" > "$wrapper"