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
14 changes: 14 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ on:

permissions:
contents: write
id-token: write

concurrency:
group: release-main
Expand Down Expand Up @@ -34,6 +35,7 @@ jobs:
with:
node-version-file: .nvmrc
cache: npm
registry-url: https://registry.npmjs.org
- run: npm ci
- run: npm run check
- name: Configure release author
Expand All @@ -44,3 +46,15 @@ jobs:
run: node scripts/release.mjs --publish
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Publish npm package
run: |
npm -v
name="$(jq -r .name package.json)"
version="$(jq -r .version package.json)"
if [ "$(npm view "$name@$version" version 2>/dev/null)" = "$version" ]; then
echo "npm already has $name@$version"
else
npm publish
fi
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,10 +65,12 @@ All images are 1920×1080. They come from the Paseo 0.11.0-beta.3 web app in lig
Requires Paseo 0.9.0 or newer (tested against the 0.10.2 plugin SDK) and be-concise 0.7.0 or newer on the daemon machine. The adapter uses the configuration, monitoring, and preview APIs shipped with be-concise 0.7.0. Paseo supplies all runtime dependencies.

```sh
paseo plugin add yannelli/paseo-plugin-concise
paseo plugin add npm:@yannelli/paseo-be-concise
paseo plugin ls
```

To install from GitHub instead, run `paseo plugin add yannelli/paseo-plugin-concise`.

For local development:

```sh
Expand Down Expand Up @@ -108,11 +110,11 @@ Tests use Node.js 24 and temporary home/project directories. They cover activity

Paseo API reference: [v0.9 plugins](https://paseo.sh/docs/plugins/v0.9/reference).

See the [documentation index](docs/INDEX.md) for the current composer button contract, screenshot capture details, and the be-concise installer commands. Consult it when you change pill labels, update screenshots, or change install behavior.
See the [documentation index](docs/INDEX.md) for the current composer button contract, screenshot capture details, the be-concise installer commands, and npm publishing. Consult it when you change pill labels, update screenshots, change install behavior, or change the release workflow.

## Releases

GitHub Actions runs the checks and publishes a GitHub release on qualifying pushes to `main`. The first release is `v0.1.0`. The workflow updates `package.json` and `package-lock.json`, pushes an annotated tag, and publishes release notes. It uses the repository's `GITHUB_TOKEN`; no extra secrets or npm publication are required.
GitHub Actions runs the checks and publishes a GitHub release on qualifying pushes to `main`. The first release is `v0.1.0`. The workflow updates `package.json` and `package-lock.json`, pushes an annotated tag, and publishes release notes with the repository's `GITHUB_TOKEN`. It then publishes [`@yannelli/paseo-be-concise`](https://www.npmjs.com/package/@yannelli/paseo-be-concise) to npm through trusted publishing, or with the `NPM_TOKEN` secret when no trusted publisher is set. See [npm publishing](docs/npm-publishing.md) for the package contents and the trusted publisher setup.

Use Conventional Commits in commits and squash-merge titles:

Expand All @@ -125,6 +127,6 @@ Use Conventional Commits in commits and squash-merge titles:

The highest change since the last release determines the next version. For example, `fix: repair the badge` changes `0.1.0` to `0.1.1`; `feat: add a filter` changes it to `0.2.0`.

Run `npm run release:dry-run` from a clean `main` checkout with all tags fetched to preview the next release. Rerun the **Release** workflow to complete a publication interrupted after its tag was pushed.
Run `npm run release:dry-run` from a clean `main` checkout with all tags fetched to preview the next release. Rerun the **Release** workflow to complete a GitHub or npm publication interrupted after its tag was pushed.

Questions or feedback? Please reach out to me at [Ryan Yannelli](https://ryanyannelli.com) or open an issue/PR.
1 change: 1 addition & 0 deletions docs/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ Created: 2026-10-04. Last updated: 2026-10-05.

- [Composer pill and screenshots](composer-pill.md): compact status labels, the Paseo button contract, and screenshot capture details. Read this before changing labels or refreshing images.
- [be-concise installer](plugin-installer.md): GitHub release handling, the Claude Code and Codex CLI commands, storage, and adapter discovery order. Read this before you change the Plugin tab or install commands.
- [npm publishing](npm-publishing.md): the npm package contents, the release workflow publish step, the `NPM_TOKEN` secret, and the trusted publisher setup. Read this before you change `files` in `package.json` or the release authentication.
31 changes: 31 additions & 0 deletions docs/npm-publishing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# npm publishing

Created: 2026-10-05. Last updated: 2026-10-05.

The **Release** workflow publishes `@yannelli/paseo-be-concise` to [npm](https://www.npmjs.com/package/@yannelli/paseo-be-concise) after the GitHub release step. Paseo installs it with:

```sh
paseo plugin add npm:@yannelli/paseo-be-concise
```

Paseo runs `npm install --omit=dev --ignore-scripts` on the daemon host and compiles `index.client.tsx` and `index.server.ts` itself. The tarball holds TypeScript source only, listed in `files` in `package.json`. Paseo resolves plugin modules only under `client/`, `server/`, and `shared/`. Run `npm pack --dry-run` to check the file list after you add a top-level file.

## Workflow step

The **Publish npm package** step reads the name and version from `package.json`. It runs `npm publish` when npm does not have that version yet. A rerun after a failed publish completes it. A push with no release-triggering commits skips it because npm already has the version.

`publishConfig` sets public access and provenance. The job grants `id-token: write` for the provenance statement and for trusted publishing.

## Authentication

npm CLI 11.5.1 or newer on Node.js 22.14.0 or newer tries [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) first. Without a trusted publisher on the package, it uses `NODE_AUTH_TOKEN`, which the step reads from the `NPM_TOKEN` repository secret. The current token is a granular token scoped to `@yannelli` that expires on 2027-01-03.

`npm trust` rejects tokens that bypass 2FA, and the package must exist on npm. To add the trusted publisher, sign in with 2FA and run:

```sh
npm login
npm trust github @yannelli/paseo-be-concise --repo yannelli/paseo-plugin-concise --file release.yml --allow-publish
npm trust list @yannelli/paseo-be-concise
```

Or open the package on npmjs.com, then **Settings → Trusted publishing**, and add GitHub Actions, with owner `yannelli`, repository `paseo-plugin-concise`, and workflow `release.yml`. After the next release publishes through OIDC, delete the `NPM_TOKEN` secret and set **Publishing access** to require 2FA and disallow tokens.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

15 changes: 13 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
{
"name": "paseo-be-concise",
"private": true,
"name": "@yannelli/paseo-be-concise",
"version": "2.2.0",
"description": "Live be-concise activity, configuration, and hook previews inside Paseo",
"license": "MIT",
Expand All @@ -12,6 +11,18 @@
"type": "git",
"url": "git+https://github.com/yannelli/paseo-plugin-concise.git"
},
"files": [
"paseo-plugin.json",
"index.client.tsx",
"index.server.ts",
"client/",
"server/",
"shared/"
],
"publishConfig": {
"access": "public",
"provenance": true
},
"scripts": {
"typecheck": "tsc --noEmit",
"test": "node --experimental-strip-types --test backend.test.mts test/*.test.mjs test/*.test.mts",
Expand Down
Loading