diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9a92479..8009246 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -7,6 +7,7 @@ on: permissions: contents: write + id-token: write concurrency: group: release-main @@ -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 @@ -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 }} diff --git a/README.md b/README.md index 8babe99..629b066 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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: @@ -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. diff --git a/docs/INDEX.md b/docs/INDEX.md index 12bf82e..05c13f4 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -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. diff --git a/docs/npm-publishing.md b/docs/npm-publishing.md new file mode 100644 index 0000000..b5aaba2 --- /dev/null +++ b/docs/npm-publishing.md @@ -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. diff --git a/package-lock.json b/package-lock.json index edd8e19..e0fb9bf 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "paseo-be-concise", + "name": "@yannelli/paseo-be-concise", "version": "2.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "paseo-be-concise", + "name": "@yannelli/paseo-be-concise", "version": "2.2.0", "license": "MIT", "devDependencies": { diff --git a/package.json b/package.json index bca138c..0ace2c7 100644 --- a/package.json +++ b/package.json @@ -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", @@ -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",