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
50 changes: 50 additions & 0 deletions .github/workflows/check.yaml
Original file line number Diff line number Diff line change
@@ -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
43 changes: 0 additions & 43 deletions .github/workflows/ilttu-design-release.yml

This file was deleted.

36 changes: 36 additions & 0 deletions .github/workflows/pr-title.yaml
Original file line number Diff line number Diff line change
@@ -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 <type>(<scope>)!: <description>, 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
150 changes: 150 additions & 0 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -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<version>) and ilttu-design (ilttu-design/, tagged ilttu-design-v<version>); 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 }}
Comment thread
ajbeck marked this conversation as resolved.
Resolved
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"
Comment thread
ajbeck marked this conversation as resolved.
Resolved
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
4 changes: 4 additions & 0 deletions .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"plugins/ilttu": "0.3.1",
"ilttu-design": "0.1.1"
}
11 changes: 8 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<version>` is pushed.
- `release-please-config.json` and `.release-please-manifest.json` - the two packages release-please releases, `plugins/ilttu` tagged `ilttu-v<version>` and `ilttu-design` tagged `ilttu-design-v<version>`, 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<version>`, 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.
Expand Down
3 changes: 2 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
2 changes: 1 addition & 1 deletion plugins/ilttu/bin/ilttu-design
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
24 changes: 24 additions & 0 deletions release-please-config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
"bump-minor-pre-major": true,
Comment thread
ajbeck marked this conversation as resolved.
Resolved
"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
}
}
}
44 changes: 44 additions & 0 deletions scripts/pin-ilttu-design
Original file line number Diff line number Diff line change
@@ -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 <tag> <SHA256SUMS>
# 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 <tag> <SHA256SUMS>" >&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"
Loading