@crossdelta/platform-sdk 0.26.3 → 0.26.5

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to `@crossdelta/platform-sdk` will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.5] - 2026-10-23
+
+### Changed
+- **The workspace template's `publish-packages.yml` queues its runs and skips a version npm already
+  holds.** A `concurrency` group (`publish-packages`, no cancelling) stops two merges in a row from
+  publishing the same version at once, and the publish step reads `npm view "<name>@<version>"`
+  right before `npm publish`: a hit ends the step with a skip line, any other failure of `npm view`
+  publishes as before (the read ignores setup-node's placeholder token). On a push the matrix now
+  checks every public package against npm instead of only the changed ones: a queued run can be
+  replaced by a newer one, and the replaced push's version bump would otherwise never publish.
+
+## [0.26.4] - 2026-10-21
+
+### Changed
+- **The workspace template's PR checks skip drafts and docs-only pull requests.** `lint-and-tests.yml`
+  runs `lint` and `test` only when the PR is not a draft and also starts on `ready_for_review`; on a
+  draft they are skipped as `lint (draft)` and `test (draft)`, so a late draft run cannot hide the
+  real check of the same commit. A new
+  action `pr-docs-only` lists the PR's files from the GitHub API (renames by their old name too); when
+  every file matches `docs/**/*.md`, both jobs skip every later step and still end as a success, so a
+  required check never waits. Any error runs the checks as before. The `test` job also runs the tests
+  under `.github/actions`, which no workspace covers.
+
 ## [0.26.3] - 2026-10-21
 
 ### Changed

package/bin/templates/workspace/.github/actions/pr-docs-only/action.yml

@@ -0,0 +1,15 @@
+name: PR docs only
+description: Whether a pull_request event's pull request changes only files matching the patterns
+inputs:
+  patterns:
+    description: Globs, one per line, that count as documentation (e.g. docs/**/*.md)
+    required: true
+  github-token:
+    description: Token with pull-requests read access to list the pull request's files
+    required: true
+outputs:
+  docs_only:
+    description: "'true' if every changed file matches a pattern; 'false' otherwise and on any error"
+runs:
+  using: node24
+  main: index.js

package/bin/templates/workspace/.github/actions/pr-docs-only/docs-only.js

@@ -0,0 +1,81 @@
+/**
+ * Whether a pull request changes nothing but documentation, so lint, tests and the review can skip
+ * their work and still end green. Every doubt answers false: a check that runs for nothing costs
+ * minutes, a check skipped for code costs a broken main.
+ *
+ * `parseFileEntries` and `isPlainPath` mirror jackherd's merge guard
+ * (`packages/jackherd/kit/hooks/hooks/merge-guard/check-free.ts`, `plain-path.ts`): an action cannot
+ * import a workspace package. A change to one belongs in both.
+ */
+
+const { posix } = require('node:path')
+
+/** GitHub lists at most this many files of a pull request and says nothing when it stops there. */
+const MAX_LISTED_FILES = 3000
+
+/** What `gh api …/pulls/<n>/files --jq` prints per file: the name, and the old name of a rename. */
+const FILE_ENTRY_QUERY = '.[] | [.filename, .previous_filename] | @json'
+
+/**
+ * The action's `patterns` input, one glob per line.
+ * @param {string} input
+ * @returns {string[]}
+ */
+const parsePatterns = (input) =>
+  input
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '')
+
+const isNameOrNull = (value) => value === null || typeof value === 'string'
+
+/**
+ * The names a listing carries, the old name of a rename too, from one `[filename, previous]` JSON
+ * pair per line. The pairs must be exactly as many as the pull request changes files, and fewer
+ * than GitHub's cap: a list cut short would hide the files missing from it. Anything else answers
+ * undefined.
+ * @param {string} stdout
+ * @param {number} changedFiles - `pull_request.changed_files` from the event
+ * @returns {string[] | undefined}
+ */
+const parseFileEntries = (stdout, changedFiles) => {
+  if (!Number.isInteger(changedFiles) || changedFiles >= MAX_LISTED_FILES) return undefined
+  try {
+    const entries = stdout
+      .split('\n')
+      .filter((line) => line !== '')
+      .map((line) => JSON.parse(line))
+    const pairs = entries.filter(
+      (entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === 'string' && isNameOrNull(entry[1]),
+    )
+    if (pairs.length !== entries.length || pairs.length !== changedFiles) return undefined
+    return pairs.flatMap(([filename, previous]) => (previous === null ? [filename] : [filename, previous]))
+  } catch {
+    return undefined
+  }
+}
+
+const isControlCharacter = (character) => {
+  const code = character.charCodeAt(0)
+  return code < 0x20 || code === 0x7f
+}
+
+/** A repository path as GitHub lists it: relative, no empty, `.` or `..` segment, no backslash, no control character. */
+const isPlainPath = (file) =>
+  !file.includes('\\') &&
+  ![...file].some(isControlCharacter) &&
+  file.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
+
+/**
+ * True only for a known, non-empty file list, at least one pattern, and every file a plain path
+ * matching a pattern.
+ * @param {string[] | undefined} files
+ * @param {string[]} patterns
+ * @returns {boolean}
+ */
+const isDocsOnly = (files, patterns) => {
+  if (!files || files.length === 0 || patterns.length === 0) return false
+  return files.every((file) => isPlainPath(file) && patterns.some((pattern) => posix.matchesGlob(file, pattern)))
+}
+
+module.exports = { FILE_ENTRY_QUERY, MAX_LISTED_FILES, isDocsOnly, parseFileEntries, parsePatterns }

package/bin/templates/workspace/.github/actions/pr-docs-only/index.js

@@ -0,0 +1,69 @@
+/**
+ * PR Docs Only Action
+ *
+ * Sets `docs_only=true` when every file of the pull request, renames by their old name too, matches
+ * one of the `patterns`. Reads the file list from the GitHub API, never from the checkout. Any
+ * failure sets `false` and leaves the job green, so the checks run as before.
+ *
+ * @example
+ * - uses: ./.github/actions/pr-docs-only
+ *   id: docs-only
+ *   with:
+ *     patterns: docs/**\/*.md
+ *     github-token: ${{ github.token }}
+ *
+ * @outputs docs_only - 'true' if the pull request changes only matching files, 'false' otherwise
+ */
+
+const { spawnSync } = require('node:child_process')
+const { appendFileSync, readFileSync } = require('node:fs')
+const { FILE_ENTRY_QUERY, isDocsOnly, parseFileEntries, parsePatterns } = require('./docs-only.js')
+
+const input = (name) => (process.env[`INPUT_${name.toUpperCase()}`] ?? '').trim()
+
+const setOutput = (name, value) => {
+  const outputFile = process.env.GITHUB_OUTPUT
+  if (outputFile) appendFileSync(outputFile, `${name}=${value}\n`)
+  else console.log(`${name}=${value}`)
+}
+
+const readPullRequest = () => {
+  try {
+    return JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH ?? '', 'utf-8')).pull_request
+  } catch {
+    return undefined
+  }
+}
+
+const listFiles = (pullRequest) => {
+  const repository = pullRequest.base?.repo?.full_name
+  const result = spawnSync(
+    'gh',
+    ['api', `repos/${repository}/pulls/${pullRequest.number}/files?per_page=100`, '--paginate', '--jq', FILE_ENTRY_QUERY],
+    { encoding: 'utf-8', env: { ...process.env, GH_TOKEN: input('github-token') } },
+  )
+  if (result.status !== 0) {
+    console.log(`::warning::Could not list the pull request's files: ${result.stderr || result.error}`)
+    return undefined
+  }
+  return parseFileEntries(result.stdout, pullRequest.changed_files)
+}
+
+const classify = () => {
+  const pullRequest = readPullRequest()
+  const files = pullRequest ? listFiles(pullRequest) : undefined
+  const docsOnly = isDocsOnly(files, parsePatterns(input('patterns')))
+  if (docsOnly) console.log(`::notice::Only documentation changed (${pullRequest.changed_files} files): skipping the checks.`)
+  return docsOnly
+}
+
+const run = () => {
+  try {
+    setOutput('docs_only', String(classify()))
+  } catch (error) {
+    console.log(`::warning::Could not classify the pull request, running the checks: ${error}`)
+    setOutput('docs_only', 'false')
+  }
+}
+
+run()

package/bin/templates/workspace/.github/workflows/lint-and-tests.yml.hbs

@@ -4,20 +4,43 @@ on:
   pull_request:
     branches:
       - main
+    # ready_for_review starts the checks a draft skipped.
+    types: [opened, synchronize, reopened, ready_for_review]
 
+# Draft runs get their own group, so a late draft event cannot cancel the run that marking the PR
+# ready started.
 concurrency:
-  group: $\{{ github.workflow }}-$\{{ github.ref }}
+  group: $\{{ github.workflow }}-$\{{ github.ref }}-$\{{ github.event.pull_request.draft }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+  pull-requests: read
+
+# A draft skips lint and test under their own check names: GitHub shows the newest check run per
+# name, and a draft push followed at once by `gh pr ready` leaves two runs on one commit, so a
+# skipped "lint" could land after, and hide, the real one. A docs-only PR runs them but skips every
+# step after the file check, so both end as a success and a required check never waits for a run
+# that never comes.
 jobs:
   lint:
+    name: $\{{ github.event.pull_request.draft && 'lint (draft)' || 'lint' }}
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
 
+      - name: Check for docs-only changes
+        id: docs-only
+        uses: ./.github/actions/pr-docs-only
+        with:
+          patterns: docs/**/*.md
+          github-token: $\{{ github.token }}
+
       - name: Setup Bun and install dependencies
+        if: steps.docs-only.outputs.docs_only != 'true'
         uses: ./.github/actions/setup-bun-install
         with:
           enable-cache: 'true'
@@ -25,17 +48,22 @@ jobs:
           cache-restore-keys: bun-v4-$\{{ runner.os }}-
 
       - name: Run Linter
+        if: steps.docs-only.outputs.docs_only != 'true'
         run: bun run --if-present lint
 
       - name: Component manifest
+        if: steps.docs-only.outputs.docs_only != 'true'
         run: |
           git fetch --depth=1 origin main
           bun run --if-present manifest:check
 
       - name: Pattern manifest
+        if: steps.docs-only.outputs.docs_only != 'true'
         run: bun run --if-present patterns:check
 
   test:
+    name: $\{{ github.event.pull_request.draft && 'test (draft)' || 'test' }}
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     timeout-minutes: 20
     env:
@@ -47,7 +75,15 @@ jobs:
         with:
           fetch-depth: 2
 
+      - name: Check for docs-only changes
+        id: docs-only
+        uses: ./.github/actions/pr-docs-only
+        with:
+          patterns: docs/**/*.md
+          github-token: $\{{ github.token }}
+
       - name: Setup Bun and install dependencies
+        if: steps.docs-only.outputs.docs_only != 'true'
         uses: ./.github/actions/setup-bun-install
         with:
           enable-cache: 'true'
@@ -60,6 +96,7 @@ jobs:
       # Those paths test every package. A PR that touches no package runs no task and passes.
       - name: Decide test scope
         id: test-scope
+        if: steps.docs-only.outputs.docs_only != 'true'
         env:
           GLOBAL_PATHS: package.json bunfig.toml tsconfig.json .npmrc .bun-version patches/ .github/workflows/lint-and-tests.yml .github/actions/setup-bun-install/
         run: |
@@ -72,7 +109,15 @@ jobs:
             echo "affected_only=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # The local actions are no workspace, so turbo never runs their tests; pr-docs-only decides
+      # whether this job tests anything at all. Runs from the directory to keep Bun's file scan small.
+      - name: Run action tests
+        if: steps.docs-only.outputs.docs_only != 'true'
+        working-directory: .github/actions
+        run: bun test --pass-with-no-tests
+
       - name: Run Tests
+        if: steps.docs-only.outputs.docs_only != 'true'
         env:
           AFFECTED_ONLY: $\{{ steps.test-scope.outputs.affected_only }}
           TURBO_SCM_BASE: HEAD^1

package/bin/templates/workspace/.github/workflows/publish-packages.yml

@@ -16,6 +16,11 @@ on:
         default: all
         required: true
 
+# Runs queue one behind the other: two merges in a row must not publish the same version at once.
+concurrency:
+  group: publish-packages
+  cancel-in-progress: false
+
 # id-token: write only where it is used: the publish job sets it itself.
 permissions:
   contents: read
@@ -32,38 +37,18 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Detect changed packages
-        id: changed
-        uses: tj-actions/changed-files@v47
-        with:
-          json: true
-          safe_output: false
-          files: packages/*/**
-
       - name: Build package matrix
         id: set-matrix
         env:
           INPUT_PACKAGE: ${{ github.event.inputs.package || '' }}
-          CHANGED_FILES: ${{ steps.changed.outputs.all_changed_files }}
         run: |
           declare -a packages=()
-          declare -A changed_packages
 
           # Compare semver: true if $1 > $2
           version_gt() {
             [ "$(printf '%s\n' "$1" "$2" | sort -V | tail -1)" = "$1" ] && [ "$1" != "$2" ]
           }
 
-          # Extract package names from changed file paths (e.g. packages/platform-sdk/src/foo.ts → platform-sdk)
-          if [ "${{ github.event_name }}" == "push" ] && [ -n "$CHANGED_FILES" ]; then
-            CLEAN_FILES=$(echo "$CHANGED_FILES" | sed 's/\\"/"/g')
-            for file in $(echo "$CLEAN_FILES" | jq -r '.[]' 2>/dev/null); do
-              if [[ $file =~ ^packages/([^/]+)/ ]]; then
-                changed_packages["${BASH_REMATCH[1]}"]=1
-              fi
-            done
-          fi
-          
           # Iterate all packages
           for dir in packages/*/; do
             [ ! -f "$dir/package.json" ] && continue
@@ -76,17 +61,13 @@ jobs:
             [ "$is_private" = "true" ] && continue
             [ -z "$name" ] && continue
             
-            # Include package?
-            should_include=false
-            if [ -n "$INPUT_PACKAGE" ]; then
-              [ "$INPUT_PACKAGE" = "all" ] || [ "$INPUT_PACKAGE" = "$slug" ] && should_include=true
-            else
-              [ -n "${changed_packages[$slug]}" ] && should_include=true
+            # A dispatch may name one package; a push checks every public package. A queued run can be
+            # replaced by a newer one, so a changed-files delta would lose the bump of the replaced push.
+            if [ -n "$INPUT_PACKAGE" ] && [ "$INPUT_PACKAGE" != "all" ] && [ "$INPUT_PACKAGE" != "$slug" ]; then
+              continue
             fi
-            
-            [ "$should_include" = true ] || continue
 
-            # Skip if local version <= npm version
+            # Skip if local version <= npm version (this check, not a changed-files filter, selects what publishes)
             local_ver=$(jq -r '.version' "$dir/package.json")
             npm_ver=$(npm view "$name" version 2>/dev/null || echo "0.0.0")
             if ! version_gt "$local_ver" "$npm_ver"; then
@@ -214,7 +195,7 @@ jobs:
       # The kit is published for other people's repositories: nothing of this one may ride along. The check packs
       # the package as npm receives it and scans every text file against the kit's built-in patterns.
       - name: Setup Bun for the leak check
-        if: matrix.package.name == 'jackherd' || matrix.package.name == '@crossdelta/agent-kit'
+        if: matrix.package.name == 'jackherd'
         # Pinned to a commit: this job holds id-token: write, which npm Trusted Publishing accepts.
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
@@ -225,11 +206,6 @@ jobs:
         working-directory: ${{ matrix.package.dir }}
         run: bun scripts/check-package-leaks.ts
 
-      - name: Leak check on the agent-kit shell tarball
-        if: matrix.package.name == '@crossdelta/agent-kit'
-        working-directory: ${{ matrix.package.dir }}
-        run: bun ../jackherd/scripts/check-package-leaks.ts .
-
       - name: Publish to npm
         working-directory: ${{ matrix.package.dir }}
         run: |
@@ -242,6 +218,13 @@ jobs:
               (if .peerDependencies[$n] then .peerDependencies[$n] = $v else . end)
             ' package.json > "$tmp" && mv "$tmp" package.json
           done
+          NAME=$(jq -r '.name' package.json)
           VERSION=$(jq -r '.version' package.json)
-          echo "📦 Publishing ${{ matrix.package.name }}@$VERSION"
+          # Only a hit skips; any other npm view failure (network) falls through to the publish.
+          # Empty NODE_AUTH_TOKEN: setup-node's placeholder token must not turn a public read into a 401.
+          if [ "$(NODE_AUTH_TOKEN= npm view --registry=https://registry.npmjs.org "$NAME@$VERSION" version 2>/dev/null)" = "$VERSION" ]; then
+            echo "⏭️ $NAME@$VERSION is on npm already — skipping"
+            exit 0
+          fi
+          echo "📦 Publishing $NAME@$VERSION"
           npm publish --access=public --ignore-scripts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/platform-sdk",
-  "version": "0.26.3",
+  "version": "0.26.5",
   "description": "Platform toolkit for event-driven microservices — keeping code and infrastructure in lockstep.",
   "keywords": [
     "cli",