# Contributing and releasing

## Development

Use Node.js 22.19+ (Node 24 recommended):

```sh
npm ci
npm run check
npm test
npm pack --dry-run
```

The test suite uses the public Pi SDK and an isolated temporary session. It must not request a model. Keep the Pi host package in `peerDependencies` with `"*"`, and in `devDependencies` at the version used for tests. Do not bundle it or add it to runtime dependencies.

CI checks Node 22 and 24 on pushes to `main` and pull requests. The npm tarball includes the extension, bilingual documentation, license, changelog, and package manifest only.

## First publication

The unscoped npm name `pi-edit-last` must be available and the publishing account must have access. Authenticate interactively; do not commit registry credentials:

```sh
gh auth login
npm login
```

Create and push the public repository if it does not exist:

```sh
gh repo create tong233/pi-edit-last --public --source=. --remote=origin --push
```

Publish the initial version locally (npm may request a one-time password):

```sh
npm publish --access public
```

`prepublishOnly` runs type checking and the full test suite before publishing. Confirm the registry version before retrying any interrupted publication:

```sh
npm view pi-edit-last version
```

After publication, configure the package's **Trusted publisher** in its npm settings:

- Provider: GitHub Actions
- Organization or user: `tong233`
- Repository: `pi-edit-last`
- Workflow filename: `publish.yml`
- Environment: leave empty (the workflow does not use a GitHub environment)

The tag workflow uses npm trusted publishing through GitHub OIDC, with provenance and no stored npm token. It requires npm 11.5.1+; the workflow uses Node 24's bundled npm. Trusted publisher setup is an npm account configuration step and is not created by committing the workflow.

Record the initial release after publication:

```sh
git tag v0.1.0
git push origin v0.1.0
gh release create v0.1.0 --title v0.1.0 --notes-file CHANGELOG.md
```

Pushing the initial tag also runs the publishing workflow. Since that version was already published locally, it will be validated and skipped rather than published twice.

## Subsequent releases

1. Update `CHANGELOG.md` and ensure CI is green.
2. Run `npm version patch` (or `minor` / `major`); npm commits the version and creates its `v` tag. Include any changelog changes in a commit first.
3. Run `git push origin main` and `git push origin --tags`.
4. Check the **Publish** workflow and `npm view pi-edit-last version`.
5. Create a GitHub release with notes for that version, for example `gh release create v0.1.1 --title v0.1.1 --generate-notes`.

The workflow checks that the tag matches `package.json`, installs the locked dependencies, type-checks, tests, inspects the package, and publishes with provenance. If publication fails, inspect the registry and workflow logs before retrying; a published npm version cannot be reused.

## Pi packages

There is no separate Pi registry upload. npm publication plus the `pi-package` keyword and `pi.extensions` manifest makes the package installable with:

```sh
pi install npm:pi-edit-last
```

The Pi gallery at https://pi.dev/packages manages discovery and indexing independently. For a smoke test, use an isolated Pi agent directory to avoid loading a second copy alongside your local extension:

```sh
PI_CODING_AGENT_DIR="$(mktemp -d)" pi -e npm:pi-edit-last
```

Run `/last` in that temporary session after sending a text message and waiting for Pi to become idle.