pi-extension-release-tool

Release tooling, shared CI/CD and the project template for the FloezWerk pi extensions. Everything that used to be copied into each extension repository lives here once.

Table of contents

• What is in here
• Tooling
• Prompt template: new extension
• New extension repository
• Releasing an extension
• Updating this toolkit
• Optional: Gitea as source
• Changelog

What is in here

• tooling/ - the published npm package @floez-werk/pi-extension-release-tool (command pi-release): scaffolding, generated README blocks (badges, release notes) and the GitHub release body. Used by every extension repository via npx -y …@^0.1 ….
• template/ - the skeleton a new extension repository starts from (extension stub, README with badges and the changelog block, CHANGELOG.md, package.json, AGENTS.md, LICENSE, .gitignore/.gitattributes, thin CI/release callers, and a .gitea/workflows/ placeholder for the optional Gitea setup, see Gitea as source).
• .github/workflows/reusable-*.yml - the shared CI and release pipelines. Extension repositories call them with uses: …/reusable-release.yml@v0.1, so a fix here reaches all of them without touching their files.
• prompts/ - the interactive prompt template shipped with the package (/new-pi-extension): it collects the scaffold parameters, then follows the "New extension repository" flow below. Install the package as a pi package to get it.

Nothing in here is specific to a single extension; extension-specific code stays in the extension repository.

Tooling

# scaffold a new extension repository (see below for the full flow)
npx -y @floez-werk/pi-extension-release-tool@^0.1 init /srv/projects/piagent-my-ext \
  --name @floez-werk/piagent-my-ext \
  --desc "Pi extension: one-line description"

# regenerate the generated README blocks (badges, release notes) / verify them
npx -y @floez-werk/pi-extension-release-tool@^0.1 sync-readme
npx -y @floez-werk/pi-extension-release-tool@^0.1 sync-readme --check

# GitHub release body (the CHANGELOG section of the current version)
npx -y @floez-werk/pi-extension-release-tool@^0.1 release-notes --out /tmp/notes.md

# move the moving "v<major>.<minor>" tag (run after a release, from the repo)
npx -y @floez-werk/pi-extension-release-tool@^0.1 tag-major --push

The README and release-notes subcommands read package.json and CHANGELOG.md from the current directory, so they work in any repository. Two blocks in README.md are generated instead of maintained by hand (both guarded by --check in CI):

• the badges block (badges:start / badges:end) - npm version, license, CI and changelog badges built from package.json (skipped in repositories without the markers)
• the release-notes block (changelog:start / changelog:end) - the notes of the current version from CHANGELOG.md

Write those marker names in prose and in CHANGELOG.md without the comment syntax; a literal marker would look like a second block to the check.

Prompt template: new extension

The package is also a pi package and ships one prompt template. Install it once and the wizard is available as a slash command:

pi install npm:@floez-werk/pi-extension-release-tool

Run /new-pi-extension (no arguments needed). It asks for the package name, the brief and the optional init flags, then scaffolds the repository and implements the extension as described under New extension repository. After a package update, /reload picks up the new version of the template.

New extension repository

<repo> below is the repository name, e.g. piagent-my-ext.

1. GitHub: create the repository (empty, public). GitHub runs the CI and release workflows. Working through Gitea first is optional, see Gitea as source.

2. Scaffold the repository (the tooling comes from npm, no clone needed):

   npx -y @floez-werk/pi-extension-release-tool@^0.1 init /srv/projects/<repo> \
     --name @floez-werk/<repo> \
     --desc "Pi extension: one-line description"
   cd /srv/projects/<repo> && npm run check
   

   The scaffolder replaces all placeholders, generates the README release-notes block, runs git init -b main and creates the initial commit. Useful flags: --ext <file.ts> (extension file, default <repo>.ts), --cmd <name> (command without slash), --owner, --no-git.

3. Push to GitHub:

   git remote add origin git@github.com:FloezWerk/<repo>.git
   git push -u origin main
   

4. First npm publish (manual, once per package): the package does not exist on npm yet, so an automation token cannot be scoped to it. Run locally:

   npm login
   npm publish --access public
   

   Do not push the tag of this version (v0.1.0): the release workflow rejects versions that are already published, so the first tag-driven release is the next patch (v0.1.1). Keep the 0.1.0 heading link in CHANGELOG.md pointing at npm.

5. npmjs.com: add a Trusted Publisher (package → Settings → Trusted Publisher): owner and repository of the GitHub repo, workflow filename release.yml, no environment. No NPM_TOKEN secret is needed - permissions and the workflow call are already in the scaffolded files. Optional: enable "Require two-factor authentication and disallow tokens" for the package.

6. Optional, after the first tag-driven release: point the [Unreleased] link in CHANGELOG.md at compare/v0.1.1...HEAD instead of commits/main.

7. Verify the pipeline with the next change: bump the patch version, move the [Unreleased] bullets into a heading X.Y.Z - YYYY-MM-DD (version linked to its GitHub release), npm run readme, commit, then

   git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z
   

   GitHub Actions then publishes to npm (with provenance), creates the GitHub release from the CHANGELOG section and attaches the tarball. pi.dev/packages lists the package automatically (pi-package keyword).

Releasing an extension

1. Move the [Unreleased] bullets into a heading X.Y.Z - YYYY-MM-DD (the version links its GitHub release) in CHANGELOG.md.
2. Bump "version" in package.json, run npm run readme, commit both.
3. git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z.

The rest is the shared pipeline (see reusable-release.yml).

Updating this toolkit

• Versioning is 0.y.z; every change to tooling/ or template/ must end in a release, otherwise the pinned npx version in the extensions does not see it.
• Release: CHANGELOG.md ([Unreleased] → heading X.Y.Z - YYYY-MM-DD), npm run readme, version bump, commit, tag vX.Y.Z, push. The release workflow then publishes to npm and creates the GitHub release.
• Afterwards move the moving tag locally: npm run tag-major sets vX.Y to this release and pushes it to origin. Tags are never created in a workflow. With Gitea as source, see Gitea as source for the mirror details.
• Extension repositories pin two refs: the npm package (@^X.Y in their package.json scripts) and the reusable workflows (@vX.Y in their ci.yml/release.yml). A patch release reaches them after the tag move; a minor release is a deliberate update - after a 0.2.0 release, update the pins in the affected repositories.
• Workflows can be changed without touching the extensions: the tag move is what delivers the change. Watch the first run after a change (publish job of the tag build).
• Changes that require new placeholders in template/ must also update tooling/scaffold.mjs; npm run check (self-test) fails otherwise.

Changelog

Notable changes per version are documented in CHANGELOG.md.

0.1.7 - 2026-10-13

Changed

• New extensions are set up for npm trusted publishing: no NPM_TOKEN secret, a Trusted Publisher on npmjs.com instead. Existing token setups keep working.

Full history and all versions: CHANGELOG.md