Release: timeout queue fix, pnpm and rman

.claude/settings.json

@@ -0,0 +1,38 @@
+{
+  "extraKnownMarketplaces": {
+    "panates": {
+      "source": {
+        "source": "github",
+        "repo": "panates/ai-harness"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "panates@panates": true
+  },
+  "attribution": {
+    "commit": ""
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/ehanoglu/.local/bin/graphify hook-guard search"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/ehanoglu/.local/bin/graphify hook-guard read"
+          }
+        ]
+      }
+    ]
+  }
+}

.github/workflows/main-from-dev.yml

@@ -0,0 +1,28 @@
+name: Main from dev
+on:
+  # main takes pull requests from dev only
+  pull_request:
+    branches:
+      - main
+
+# This workflow reads nothing; the branch names come from the event
+permissions: {}
+
+jobs:
+  main-from-dev:
+    name: main-from-dev
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # The branch names go through env, never into the script text: a branch name is set by
+      # whoever opens the pull request.
+      - name: Check the source branch
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [ "$HEAD_REF" != "dev" ] || [ "$HEAD_REPO" != "$REPO" ]; then
+            echo "::error::main takes pull requests from dev only, not from $HEAD_REPO:$HEAD_REF"
+            exit 1
+          fi

.github/workflows/release.yml

@@ -8,7 +8,7 @@ on:
         type: boolean
         default: false
 
-  # on git push
+  # A push to main releases
   push:
     branches:
       - main
@@ -19,52 +19,41 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  # Tells whether the commit came through a pull request, and from which branch
+  source:
+    uses: panates/github-actions/.github/workflows/pr-source.yaml@v3
+    permissions:
+      contents: read
+      pull-requests: read
+
+  # A commit merged from dev was tested on dev and is not tested again
   test:
+    needs: source
     if: >
       !contains(github.event.head_commit.message, 'no-release') &&
       (
         (github.event_name == 'workflow_dispatch' && github.event.inputs.skip-tests != 'true') ||
         (
           github.event_name == 'push' &&
-          !(
-            contains(github.event.head_commit.message, 'no-test') ||
-            ( 
-              startsWith(github.event.head_commit.message, 'Merge pull request') &&
-              contains(github.event.head_commit.message, '/dev')
-            )
-          )
+          !contains(github.event.head_commit.message, 'no-test') &&
+          needs.source.outputs.head-ref != 'dev'
         )
       )
+    permissions:
+      contents: read
     uses: ./.github/workflows/test.yml
-    secrets:
-      PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-
-
-  release_after_test:
-    # Wait for "test" job
-    needs: test
-    uses: panates/github-actions/.github/workflows/node-release.yaml@v1
-    secrets:
-      PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   release:
+    needs: [source, test]
+    # always(): a skipped test job (merged from dev, or no-test) still releases
     if: >
-      !contains(github.event.head_commit.message, 'no-release') &&
-      !(
-        (github.event_name == 'workflow_dispatch' && github.event.inputs.skip-tests != 'true') ||
-        (
-          github.event_name == 'push' &&
-          !(
-            contains(github.event.head_commit.message, 'no-test') ||
-            ( 
-              startsWith(github.event.head_commit.message, 'Merge pull request') &&
-              contains(github.event.head_commit.message, '/dev')
-            )
-          )
-        )
-      )
-    uses: panates/github-actions/.github/workflows/node-release.yaml@v1
-    secrets:
-      PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      always() && !cancelled() &&
+      needs.source.result == 'success' &&
+      (needs.test.result == 'success' || needs.test.result == 'skipped') &&
+      !contains(github.event.head_commit.message, 'no-release')
+    uses: panates/github-actions/.github/workflows/node-release.yaml@v3
+    # The version bump, the tag, the GitHub Release and the merge back into dev write to the repository
+    permissions:
+      contents: write
+      # node-release.yaml asks for it in every repository; npm Trusted Publishing (OIDC) uses it, no NPM_TOKEN
+      id-token: write

.github/workflows/test.yml

@@ -1,63 +1,61 @@
 name: Test
 on:
+  # release.yml runs the tests before a release
   workflow_call:
-    secrets:
-      PERSONAL_ACCESS_TOKEN:
 
   # Can be run manually
   workflow_dispatch:
 
-  # on git push
+  # Every push but to main, which gets its tests from release.yml
   push:
-    branches:
-      - dev
+    branches-ignore:
+      - main
+
+# This workflow only reads the repository
+permissions:
+  contents: read
 
 # Only one run per branch at a time
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  # ***********************************
-  # Job: Test
-  # ***********************************
   test:
-    name: 'Tests'
-    if: >
-      github.event_name == 'workflow_dispatch' ||
-      (
-        github.event_name == 'push' &&
-        !(
-          contains(github.event.head_commit.message, 'no-test') ||
-          ( 
-            startsWith(github.event.head_commit.message, 'Merge pull request') &&
-            contains(github.event.head_commit.message, '/dev')
-          )
-        )
-      )
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
+    name: Node v${{ matrix.node }}
+    # Every Node.js release line from the engines.node floor (>=22) up
     strategy:
       fail-fast: false
       matrix:
-        node: [ '18', '20', '22', '23' ]
-
+        node: ['22', '24', '26']
+    # A push whose commit message says no-test skips the tests
+    if: >
+      github.event_name != 'push' ||
+      !contains(github.event.head_commit.message, 'no-test')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
+      # Checks the repository out, installs what the lockfile pins and puts rman on the PATH
       - name: Setup Environment
-        uses: panates/gh-setup-node@v1
+        uses: panates/gh-setup-node@v2
         with:
-          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          node-version: ${{ matrix.node }}
+          rman-version: '2'
+          install: 'ci'
+
+      - name: Run linter test
+        run: rman lint
+
+      - name: Run circular dependency test
+        run: rman check
 
-      - name: Apply tests
-        run: |
-          npm run qc
-          npm run citest
-        env:
-          NODE_OPTIONS: "--max_old_space_size=4096"
+      - name: Run unit tests
+        run: pnpm run citest
 
+      # The coverage badge reads Coveralls
       - name: Send coverage to Coveralls
         uses: coverallsapp/github-action@v2
-        # Run only once
-        if: ${{ matrix.node == '22' }}
+        # Once per run
+        if: ${{ matrix.node == '24' }}
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,26 +1,21 @@
-# compiled output
-/node_modules
-/build
+# Dependencies
 node_modules
-coverage
+
+# Build output
+build/
 *.tsbuildinfo
-graphify-out
-.claude
 
-# benchmark raw results (regenerate with `npm run bench`)
+# Benchmark raw results (regenerate with `pnpm run bench`)
 /benchmark/results
 
-# environment variables
+# Environment variables: only an example file is committed
 .env
-.development.env
+.env.*
+!.env.example
 
 # Logs
 logs
 *.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
 
 # OS
 .DS_Store
@@ -29,6 +24,11 @@ lerna-debug.log*
 /coverage
 /.nyc_output
 
+# Claude Code: .claude/settings.json is shared and committed, these are local
+.claude/settings.local.json
+.claude/worktrees/
+graphify-out
+
 # IDEs and editors
 /.idea
 .project

.prettierignore

@@ -2,13 +2,16 @@
 /build
 /coverage
 /.idea
-/.circleci
-/.husky
 /.DS_Store
 /.nyc_output
 /.github
+/.claude
+/graphify-out
 **/*.md
 
+# pnpm writes the lockfile in its own layout, which prettier would rewrite on every format
+pnpm-lock.yaml
+
 # IDEs and editors
 .project
 .classpath

.rmanrc.yml

@@ -0,0 +1,5 @@
+extends: '@panates/rman-preset'
+
+# Install, sync the lockfile and publish with pnpm.
+packageManager:
+  node: pnpm

CHANGELOG.md

@@ -1,6 +1,17 @@
 ## Changelog
 
-### [v4.14.0](https://github.com/panates/lightning-pool/compare/v4.13.0...v4.14.0) - 
+### [v4.14.1](https://github.com/panates/lightning-pool/compare/v4.14.0...v4.14.1) - 
+
+#### 🪲 Fixes
+
+- fix: point coverage badge at dev instead of the stale master record @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: Add TSDoc coverage across src/ @Eray Hanoğlu 
+- docs: Add a doc-sync-marker convention for hand-written reference docs @Eray Hanoğlu 
+
+### [v4.14.0](https://github.com/panates/lightning-pool/compare/v4.13.0...v4.14.0) -  8 September 2026 
 
 #### 🚀 New Features