@crossdelta/platform-sdk 0.26.3 → 0.26.4

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.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/package.json

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