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
4 changes: 4 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,17 @@ updates:
directory: /
schedule:
interval: weekly
cooldown:
default-days: 7
groups:
actions:
patterns: ["*"]
- package-ecosystem: npm
directory: /
schedule:
interval: weekly
cooldown:
default-days: 7
groups:
dependencies:
patterns: ["*"]
1 change: 0 additions & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,4 @@
## Checks

- [ ] `npm run check` passes.
- [ ] User-visible changes have an entry under `## Unreleased` in `CHANGELOG.md`.
- [ ] The README matches the new behavior.
37 changes: 28 additions & 9 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ on:
permissions:
contents: read

env:
PI_PACKAGES: >-
@earendil-works/chord @earendil-works/pi-agent-core @earendil-works/pi-ai @earendil-works/pi-codemode
@earendil-works/pi-coding-agent @earendil-works/pi-mcp @earendil-works/pi-telemetry @earendil-works/pi-tui

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
Expand All @@ -25,23 +30,37 @@ jobs:
# Pi requires Node 22.19 or later.
node: [22, 24]
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-node@v7
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci
- run: npm run check
- name: Validate version change
if: github.event_name == 'pull_request'
run: node scripts/release.ts check "$BASE_SHA"
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
# Pi's packages depend on each other with caret ranges, so each one is pinned to match a real install.
- name: Check oldest supported Pi
if: matrix.node == 24
run: |
read -ra packages <<< "$PI_PACKAGES"
npm install --no-save --package-lock=false "${packages[@]/%/@1.0.3}"
npm run check
- name: Check latest Pi
if: matrix.node == 24
run: |
npm install --no-save --package-lock=false @earendil-works/pi-ai@latest @earendil-works/pi-coding-agent@latest
read -ra packages <<< "$PI_PACKAGES"
npm install --no-save --package-lock=false "${packages[@]/%/@latest}"
npm run check

workflow-security:
name: Workflow security
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# Repository settings allow only GitHub-owned actions, so zizmor runs from PyPI.
- run: pipx run zizmor==1.32.0 --format=github .github
env:
GH_TOKEN: ${{ github.token }}
76 changes: 23 additions & 53 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
name: Publish release
run-name: Publish ${{ inputs.tag }}
run-name: Publish ${{ github.event.release.tag_name }}

on:
workflow_dispatch:
inputs:
tag:
description: 'Existing tag to publish to npm (latest), for example v1.2.3'
required: true
type: string
release:
types: [published]

permissions:
contents: read
Expand All @@ -22,68 +18,42 @@ concurrency:

jobs:
release:
if: github.ref == format('refs/tags/{0}', inputs.tag) && github.actor == github.repository_owner && github.triggering_actor == github.repository_owner
name: Publish
if: github.actor == github.repository_owner && github.triggering_actor == github.repository_owner && !github.event.release.prerelease
runs-on: ubuntu-latest
environment: npm
permissions:
actions: read
contents: write
id-token: write
actions: read # read CI runs of the release commit
id-token: write # npm trusted publishing and provenance
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.sha }}
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-node@v7
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
registry-url: https://registry.npmjs.org
cache: npm
- name: Resolve and validate the requested tag
id: target
run: node scripts/release.ts target "$RELEASE_TAG" >> "$GITHUB_OUTPUT"
env:
RELEASE_TAG: ${{ inputs.tag }}
- name: Require successful CI on the exact commit
package-manager-cache: false
- name: Require a tested main commit
run: |
test "$COMMIT" = "$GITHUB_SHA"
conclusion=$(gh api --paginate "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?head_sha=$COMMIT&branch=main" | jq --slurp --raw-output '[.[].workflow_runs[]] | max_by(.run_number) | .conclusion')
if [[ ! "$TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
echo "Release tag must be vX.Y.Z, got $TAG." >&2
exit 1
fi
git merge-base --is-ancestor "$GITHUB_SHA" origin/main
conclusion=$(gh api --paginate "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?head_sha=$GITHUB_SHA&branch=main" | jq --slurp --raw-output '[.[].workflow_runs[]] | max_by(.run_number) | .conclusion')
if [ "$conclusion" != "success" ]; then
echo "The latest CI run for $COMMIT on main must succeed before publication." >&2
echo "The latest CI run for $GITHUB_SHA on main must succeed before publication." >&2
exit 1
fi
printf '### Publication target\n- Tag: `%s`\n- Commit: `%s`\n' "$RELEASE_TAG" "$COMMIT" >> "$GITHUB_STEP_SUMMARY"
env:
GH_TOKEN: ${{ github.token }}
COMMIT: ${{ steps.target.outputs.commit }}
RELEASE_TAG: ${{ inputs.tag }}
TAG: ${{ github.event.release.tag_name }}
- run: npm ci
- run: npm run check
- name: Check existing publication and tag identity
id: publication
run: |
git fetch --no-tags origin "refs/tags/$RELEASE_TAG"
test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "$COMMIT"
node scripts/release.ts notes "$VERSION" > "$RUNNER_TEMP/notes.md"
name=$(node -p 'require("./package.json").name')
published=$(node scripts/release.ts published "$name" "$VERSION" "$COMMIT")
released=$(gh api --paginate "repos/$GITHUB_REPOSITORY/releases" --jq ".[] | select(.tag_name == \"$RELEASE_TAG\" and .draft == false) | .id")
{
echo "published=$published"
echo "released=$released"
} >> "$GITHUB_OUTPUT"
env:
GH_TOKEN: ${{ github.token }}
RELEASE_TAG: ${{ inputs.tag }}
VERSION: ${{ steps.target.outputs.version }}
COMMIT: ${{ steps.target.outputs.commit }}
- name: Publish to npm
if: steps.publication.outputs.published == 'false'
run: npm publish
- name: Create the GitHub release
if: steps.publication.outputs.released == ''
run: gh release create "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --verify-tag --title "$RELEASE_TAG" --notes-file "$RUNNER_TEMP/notes.md"
run: |
npm version "${TAG#v}" --no-git-tag-version --allow-same-version
npm publish
env:
GH_TOKEN: ${{ github.token }}
RELEASE_TAG: ${{ inputs.tag }}
TAG: ${{ github.event.release.tag_name }}
6 changes: 6 additions & 0 deletions .github/zizmor.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
rules:
adhoc-packages:
ignore:
# Testing against the oldest supported and the latest published Pi is the purpose of these steps.
- ci.yml:47
- ci.yml:53
31 changes: 0 additions & 31 deletions CHANGELOG.md

This file was deleted.

25 changes: 16 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ npm ci
npm run check
```

`npm run check` validates package and lockfile metadata, release notes, TypeScript, and the offline tests. The tests use Pi's faux provider, not a real model.
`npm run check` validates TypeScript and the offline tests. The tests use Pi's faux provider, not a real model.

CI also installs the latest published Pi packages on Node 24 and reruns these checks. It runs weekly, even without repository changes.
CI also installs Pi `1.0.3`, the oldest supported version, and the latest published Pi packages on Node 24, and reruns these checks. It runs weekly, even without repository changes.
Keep the lockfile baseline reproducible; do not replace it with an unbounded dependency tree. Host-provided peer dependencies stay `*`.

For an optional manual test in Pi:
Expand All @@ -31,7 +31,7 @@ Do not load another copy of this extension in the same session.
- Prefer existing Pi APIs and small changes over new dependencies or abstractions.
- Add a regression test for a bug and check that it fails before the fix.
- Do not weaken tests or input validation to pass checks.
- Describe user-visible changes under `Unreleased` in `CHANGELOG.md`.
- Give the pull request a title that describes the user-visible change. Release notes are generated from these titles.
- Never include credentials, account data, or private conversation content in commits, screenshots, or logs.

## Pull requests
Expand All @@ -45,16 +45,23 @@ No third-party approval is required, so a solo maintainer can merge after CI suc

## Releases

Release preparation requires Node 24 or later, npm publish permission through the configured workflow, and an authenticated GitHub CLI.
Only the repository owner can publish. A GitHub release triggers **Publish release**, and the owner must approve the `npm` environment deployment.

Follow the [release procedure](README.md#contributing-and-releases). Do not bump the package version in ordinary contribution pull requests.
Do not bump the package version in pull requests. The release tag sets the published version.

Merging a release PR only prepares the version. The PR must update both manifests and include nonempty versioned release notes. CI rejects version rollback.
### Release procedure

Only the repository owner can launch **Publish release** from an explicit `vX.Y.Z` tag whose commit belongs to `main`. The owner must also approve the `npm` environment deployment. Pushes and tag creation do not publish.
1. Wait for CI to succeed on the `main` commit you want to publish.
2. On GitHub, open **Releases > Draft a new release**.
3. Create the tag `vX.Y.Z` on `main`. Choose `patch` for fixes, `minor` for compatible features, or `major` for breaking changes.
4. Select **Generate release notes**, then **Publish release**.
5. Approve the `npm` environment deployment in the Actions run.

Retry a failed release from its original Actions run and tag. Do not move any release tag or reuse its version for different code.
If the code needs a fix, open another release PR with a new version instead.
The workflow rejects a release that is not from the owner, a prerelease, a tag that is not `vX.Y.Z`, a commit outside `main`, or a commit without successful CI. It runs `npm run check`, sets the package version from the tag and publishes with npm provenance. A new npm publication updates the `latest` dist-tag.

Releases and `v*` tags are immutable. If publication fails for an external cause, use **Re-run failed jobs** on the original run. If the code needs a fix, publish a new version.

The workflow uses npm trusted publishing, so the repository stores no npm token. Configure the npm trusted publisher for this repository, `release.yml`, and the GitHub environment `npm`. Restrict that environment to tags `v*`, with the owner as its required reviewer and self-review allowed.

## Security

Expand Down
Loading
Loading