@llblab/pi-kit 0.35.4 → 0.35.5

package/AGENTS.md

@@ -27,6 +27,7 @@
 - Do not copy extension source, Skills, or documentation into this repository.
 - Preserve package independence: a kit release may advance any subset of included extensions without forcing lockstep extension releases.
 - Adding packages or newly exposed capabilities requires a kit minor bump. For updates to the existing composition, derive the kit version bump from the highest dependency bump in the synchronized release cohort: dependency patch-only updates require a kit patch bump, while any dependency minor update requires a kit minor bump. Do not let lower-level dependency bumps force a larger kit bump.
+- Automated dependency updates must remain reviewable PRs with a visible kit version bump; never auto-merge. Keep unreviewed preparation read-only and secret-free, isolate PR writes on a fresh runner, and accept only declared data artifacts without executing them. Publish only the reviewed main commit after clean validation, and never overwrite release tags.
 - Use English for public and repository-facing text.
 - Do not commit, publish, tag, create a remote repository, or mutate Pi settings without explicit authorization.
 

package/BACKLOG.md

@@ -2,6 +2,11 @@
 
 Package pins, resource order and bundled runtime ownership remain authoritative in `package.json`. Release outcomes belong in [CHANGELOG.md](./CHANGELOG.md).
 
+## Automation activation (administrator-owned)
+
+- Before relying on automated updates/publication, configure the repository settings described in [Update automation](./README.md#repository-setup-and-secrets): required human Code Owner approval, stale-approval dismissal, the `validate` PR check, no bypass/auto-merge and Actions PR creation permission. Add an automation-account `PI_KIT_PAT` only if downstream checks must trigger automatically. Local validation does not establish these remote settings.
+- **First OIDC publication:** The operator created the `publish-pi-kit.yml` npm trusted publisher on October 21, 2026. Confirm direct `npm publish` is permitted and complete the first successful workflow publication before **October 23, 2026 at 18:13 UTC** to validate that binding; otherwise recreate it. Keep the existing `release.yml` connection until success. No `NPM_TOKEN` is required.
+
 ## Carried checks
 
 - **Installed 0.35.4 Telegram smoke (operator-owned):** After separately authorized kit installation/reload of every Pi process together, run `/telegram-new` in one follower instance and confirm the same Thread is reused with a new letter slot and title, with no second tab and no orphan left behind. Then restart that instance, open a new session in the same folder, and confirm it adopts the retained Thread instead of provisioning another. Do not erase accepted work or replay uncertain input. Packed validation does not certify installed clients.

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.35.5: Reviewed Updates and OIDC Releases
+
+- `Update preparation`: Adds daily/manual npm discovery and one human-reviewed update PR containing exact pins, both bundle aliases, regenerated lockfile, README inventory, kit version and changelog. Preparation is read-only without secrets or dependency hooks/bin links; a fresh write runner accepts only four checked data files. Major/prerelease updates and resource changes remain manual; failed validation prevents PR creation, and no auto-merge is enabled.
+- `Publication`: Replaces tag-triggered publication with a main-only npm Trusted Publisher using short-lived OIDC, without a persistent npm token. It reads the reviewed version, skips an unchanged latest tag, validates before a non-forced tag push, and publishes npm before the GitHub Release. Existing-version recovery requires matching tag/npm commit identity; public packed inventory remains verified. Stage-only permission is rejected, not silently substituted.
+- `Review and evidence`: Adds automation regression tests, executable lock/bundle/tarball coherence checks, CODEOWNERS and maintainer setup/recovery guidance. The npm trust binding and enforced main-branch review protection remain administrator-owned activation steps.
+- `Compatibility`: Keeps all eight dependency pins, bundled resource order and runtime entrypoints unchanged. This patch changes update/release tooling and documentation; it does not install or reload Pi clients.
+
 ## 0.35.4: Telegram Session Thread Continuity
 
 - `Telegram pin`: Advances only the exact Telegram pin from `0.57.2` to `0.57.3`. A session replaced inside one Pi process now reuses its preserved Thread on every registration path instead of provisioning a second tab, and a new session registering in a folder whose previous session is provably gone adopts that binding's exact target and slot while the predecessor binding is re-keyed. A live predecessor or an ambiguous candidate set keeps ordinary provisioning.

package/README.md

@@ -58,6 +58,53 @@ npm run validate
 
 The repository-local `.npmrc` keeps Pi-provided peer packages out of the kit's lockfile; Pi supplies those peers at runtime. To advance an included package, update its exact version in `dependencies`, run `npm install`, synchronize bundled dependencies, each declared extension pointer and its target, declared Skill paths, tests, the table above, and the changelog, then validate the packed artifact. Keep every pointer target identical to the entrypoint its pin declares. A bundled package must resolve auxiliary files, workers and sibling packages from its own module URL rather than from the declared entry path, because a pointer redirects only that entry. Expose only resources declared by the published owning package; do not use version ranges or unpublished local paths.
 
+## Update automation
+
+Two independent workflows prepare updates and publish **human-reviewed** kit versions. Automation reduces synchronization work; it does not decide whether an extension is safe and never enables auto-merge.
+
+### Prepare an update PR
+
+[Update pi-kit dependencies](./.github/workflows/update-pi-kit-deps.yml) runs daily at **03:00 UTC** and supports `workflow_dispatch` on `main`. Manual dispatch defaults to `dry_run: true`: it prepares and validates the complete working-tree diff and prints it in the run log/summary, but does not push a branch or create/update a PR. Select `false` to open or refresh the single `chore/pi-kit-deps` PR, labelled `dependencies` and `automated`.
+
+The dependency-free [updater](./scripts/check-updates.mjs) reads npm's `latest` metadata for the existing direct dependencies. A custom updater is used instead of Dependabot because one coherent PR must synchronize kit-owned artifacts, not just npm pins:
+
+- Exact dependency versions, both `bundledDependencies`/`bundleDependencies` aliases, and `package-lock.json` regenerated by `npm install --ignore-scripts --bin-links=false`.
+- The README package/version inventory and versioned upstream documentation links.
+- The kit version and [changelog](./CHANGELOG.md): patch-only direct updates produce a kit patch; any direct minor update produces a kit minor. Transitive bumps do not determine the kit bump; pending `Unreleased` outcomes are carried into the new release within the changelog budget.
+- Existing package membership, extension pointers and resource order are preserved. Tests reject changed upstream resource declarations; prepare those composition changes manually rather than guessing new entrypoints.
+
+Major updates and non-stable `latest` versions are reported for manual preparation, never silently accepted. Pre-1.0 minor releases can still break compatibility and require particular care. After synchronization, the updater runs **`npm ci --ignore-scripts --bin-links=false` and `npm run validate`**. Failure stops the run before any PR write; inspect the failed run's log. Both installs disable dependency lifecycle hooks and executable links, so a dependency-provided `node`/`npm` bin cannot shadow validation commands. This is not a security verdict about the bundled code. For a read-only local discovery plan, run `node scripts/check-updates.mjs --plan`; `npm run deps:check` instead prepares and validates changes locally and should be used on a disposable working branch.
+
+Preparation runs in a **read-only job without repository secrets**. A separate fresh runner receives only `package.json`, `package-lock.json`, `README.md` and `CHANGELOG.md` from that run's artifact. Before any PR write, the trusted updater rejects extra paths, symlinks, package-set/resource/script changes, incorrect version bumps and unexpected prose edits; it regenerates the PR report itself. The write job never installs dependencies or executes artifact-provided scripts. Read-only preparation cannot poison the later write runner's command path.
+
+### Maintainer review
+
+For every bot PR, use the [Security](#security) guidance and its generated checklist:
+
+1. Read the linked upstream releases, changelogs and source comparisons. Investigate breaking changes and compatibility with the supported Pi/Node versions.
+2. Review new transitive dependencies, registry integrity changes, executable hooks and auxiliary workers/scripts. Confirm pointer-loaded extensions resolve auxiliary files from their own `import.meta.url`, not the redirected entry path.
+3. Inspect the entire diff: exact pins with no ranges, both bundle aliases matching the package set, lockfile, README inventory, kit version and changelog. No new package, capability or resource should enter through an automatic pin-only update.
+4. Inspect successful `validate` output, including the dry-run tarball's bundled manifests, extension targets and Skills. Run necessary isolated runtime/client smoke checks; package checks and a clean audit do not establish extension safety.
+5. Obtain human approval, then **merge manually**. Do not enable auto-merge. If the updater refreshes the PR, review the new diff again before approval.
+
+The existing [Release / validate](./.github/workflows/release.yml) PR check is retained, without a tag-triggered publisher. PRs created with `GITHUB_TOKEN` normally do **not** trigger another workflow. The updater already validates before creating them; to obtain the separate PR check, a maintainer can close/reopen the PR or push a reviewed change with their own credentials. `workflow_dispatch` on the PR branch can also provide separate validation evidence, but it does not replace a required PR check. Use an automation-account `PI_KIT_PAT` when automatic downstream PR checks are needed; do not use the sole reviewer's PAT, since authors cannot approve their own PRs.
+
+### Publish after merge
+
+[Publish pi-kit](./.github/workflows/publish-pi-kit.yml) runs on `main` pushes changing `package.json`, or by manual dispatch on `main`. It **reads**, never bumps, the reviewed kit version. If `v<version>` equals the latest `v*` tag in version-sort order, the run exits successfully without publishing. Older versions and existing non-latest tags are rejected, not overwritten.
+
+For a new version the order is: verify the hosted main-workflow OIDC environment and npm >= 11.5.1 → clean `npm ci --ignore-scripts --bin-links=false` → `npm run validate` → create and push `vX.Y.Z` → `npm publish --access public` through Trusted Publishing → verify public npm identity and packed inventory → `gh release create --generate-notes`. Validation must succeed before a tag is created. The tag push is non-forced, concurrent publications are serialized, and an npm version-conflict error is accepted only when the tag and npm `gitHead` both match the current HEAD. Authentication, registry failures and contradictory identities remain errors. The workflow never commits to `main`.
+
+A tag may remain if npm or GitHub fails **after** successful validation and tag push. An ordinary rerun intentionally no-ops once that version is the latest tag; it does not republish. Recovery requires a separate maintainer decision: verify the existing remote tag and npm state, preserve the exact tagged commit, and rerun `npm ci --ignore-scripts --bin-links=false` and `npm run validate` before any missing publication. Use an explicitly reviewed OIDC recovery or an interactive maintainer publication with 2FA; never silently fall back to a persistent token or staging. Run `node scripts/publish-pi-kit.mjs verify` before creating a missing GitHub Release with `gh release create vX.Y.Z --verify-tag --generate-notes`. Never move/delete a published tag or reuse a version for different content.
+
+### Repository setup and secrets
+
+- **npm Trusted Publishing (required; no `NPM_TOKEN`):** In the npm settings for `@llblab/pi-kit`, add a GitHub Actions trusted publisher for user/organization `llblab`, repository `pi-kit`, workflow filename `publish-pi-kit.yml` (without `.github/workflows/`), and no environment name. Explicitly allow **`npm publish`**, not only `npm stage publish`. Keep an existing `release.yml` trust connection until the new publisher succeeds. A new configuration must complete its first successful publication within two days or be recreated. The preflight verifies runtime prerequisites, not npm authorization; only the successful publish validates the binding. See [npm's Trusted Publishing documentation](https://docs.npmjs.com/trusted-publishers/).
+- **`PI_KIT_PAT` (optional):** A repository-scoped automation-account token with contents and pull-request write access. Without it, PR writes and tag pushes use `GITHUB_TOKEN`; those events do not trigger downstream workflows. Use the PAT only if those downstream events are required. No token is stored in source or committed git configuration.
+- **Actions permissions:** Permit Actions to create pull requests in the repository settings. Only the updater's fresh PR-write job requests `contents: write` and `pull-requests: write`; dependency preparation and PR validation are read-only. The publisher requests `contents: write` for the validated tag/GitHub Release and `id-token: write` for short-lived npm OIDC authentication on a GitHub-hosted runner. No long-lived npm credential is needed.
+- **Do not substitute stage-only tokens:** npm is removing granular-token direct publication in January 2027. A stage-only token returns `E_STAGE_REQUIRED` for `npm publish` and requires separate maintainer approval with 2FA after `npm stage publish`. That is a different release process; this workflow keeps automatic post-merge publication through explicitly permitted OIDC and never silently stages instead.
+- **Required human review:** [CODEOWNERS](./.github/CODEOWNERS) assigns `@llblab` to workflows, manifests and automation scripts. An administrator must separately protect `main` with a pull-request requirement, required Code Owner approval, stale-approval dismissal after new commits, and the `validate` status check; disallow bypasses and auto-merge. CODEOWNERS alone does **not** enforce approval. Configure these settings before relying on the pipeline as a mandatory review gate.
+
 ## Security
 
-Pi extensions execute with the user's system permissions, and Skills can guide executable actions. Review each included package and release before advancing its pin. Private Knowledge, credentials, and personal Pi configuration are not bundled.
+Pi extensions execute with the user's system permissions, and Skills can guide executable actions. Review each included package and release before advancing its pin; the [maintainer checklist](#maintainer-review) makes that review explicit for automated PRs. Automated validation and npm audit are packaging signals, not approval to trust an update. Private Knowledge, credentials, and personal Pi configuration are not bundled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.35.4",
+  "version": "0.35.5",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -29,8 +29,10 @@
   "scripts": {
     "test": "node --test test/*.test.mjs",
     "audit": "npm audit --omit=dev",
-    "pack:check": "npm pack --dry-run",
-    "validate": "npm test && npm run audit && npm run pack:check"
+    "deps:check": "node scripts/check-updates.mjs",
+    "check:coherence": "node scripts/validate.mjs",
+    "pack:check": "node scripts/validate.mjs --pack",
+    "validate": "npm run check:coherence && npm test && npm run audit && npm run pack:check"
   },
   "files": [
     "extensions/",