@sidebase/base-config 0.2.1 → 0.2.2

package/README.md

@@ -590,15 +590,18 @@ sync. A repo that genuinely needs a different layout should opt the file out
 
 The base preset ships `.github/workflows/streamctl-upgrade.yml`, a scheduled workflow
 that opens a PR when a payload update is available. It is an `enabledBy`-gated managed
-file, off by default: it only lands once a repo opts in, and it is inert until the
-required token exists.
+file, off by default. It only lands once a repo opts in.
 
 Enable it in `streamctl.config.ts`, then `streamctl sync`:
 
 ```ts
 export default {
   // ...
-  automation: { upgradePr: true },
+  automation: {
+    upgradePr: true,
+    // allowWorkflowUpdates: true,
+    // prTokenSecret: "STREAMCTL_PR_TOKEN",
+  },
   // optional: version pins, default to the payload's baseline. `node` feeds
   // ci.yml + the Dockerfile; `pnpm` feeds the Dockerfile only (CI pins pnpm
   // via package.json#packageManager):
@@ -606,24 +609,50 @@ export default {
 };
 ```
 
-Required secrets:
-
-| Secret | Purpose |
-| ------ | ------- |
-| `STREAMCTL_PR_TOKEN` | A GitHub App installation token or machine-account PAT used to open the PR. **Not** the default `GITHUB_TOKEN`: a PR opened with `GITHUB_TOKEN` does not trigger `pull_request` workflows, so the repo's own `check` gate would never run on the bot PR. |
-
-That is the only one, because the payload is public npm, so the install step needs no registry
-token. A repo whose *other* dependencies are private must opt this full-owned workflow
-out and wire its own auth.
+By default, the workflow uses `GITHUB_TOKEN` and omits changes under
+`.github/workflows/**`. If an update contains workflow changes, it opens a draft PR
+with every other safe change and lists the omitted files and completion commands.
 
-The workflow branches on the CLI exit codes: `check` exit 4 opens a PR; exit 0 stops;
-exit 3 (pre-existing drift) opens a drift issue instead. A clean `upgrade` (exit 0)
-produces a reconcile PR; a conflicted `upgrade` (exit 2, rolled back) produces a
-plan-only PR labelled `needs-interactive-upgrade` for a human to finish with
-`streamctl sync --interactive`.
+Set `automation.allowWorkflowUpdates` to `true` to include workflow changes. Add a
+`STREAMCTL_PR_TOKEN` repository secret with `Contents`, `Pull requests`, and
+`Workflows` write access. Change `automation.prTokenSecret` when the secret has another
+name. A fine-grained PAT or GitHub App token works. The built-in `GITHUB_TOKEN` cannot
+receive `Workflows` permission.
 
-> The org bot identity is still being decided. Until the runbook lands, leave the
-> workflow disabled. Design only; nothing is enabled anywhere.
+| Knob | Default | Effect |
+| ---- | ------- | ------ |
+| `automation.upgradePr` | `false` | Sync the scheduled upgrade workflow |
+| `automation.allowWorkflowUpdates` | `false` | Include `.github/workflows/**` changes in upgrade PRs |
+| `automation.prTokenSecret` | `"STREAMCTL_PR_TOKEN"` | Secret used when workflow updates are enabled |
+
+The upgrade job runs `streamctl check` and every available lint, typecheck, test, and
+build script before opening a ready PR. PRs created with `GITHUB_TOKEN` do not trigger
+their own `pull_request` workflows, so these inline checks are required. The external
+token allows the new PR to trigger them normally.
+
+The workflow handles CLI results as follows:
+
+- `check` exit 0: stop without a PR.
+- `check` exit 3: open or update one drift issue.
+- `check` exit 4: attempt the upgrade.
+- `upgrade` exit 0: validate and open a ready PR, or a draft when workflow files were omitted.
+- `upgrade` exit 2: inspect conflicts using the pre-upgrade status.
+- Any other exit: fail the workflow.
+
+A conflict is safe to apply when the same path was previously `full` managed and
+`in-sync`. The workflow retries those generated replacements with `--force`. Any new,
+modified, malformed, or structurally conflicting path produces a draft PR instead.
+Workflow changes also produce a draft unless explicitly allowed. Drafts contain every
+safe change, keep conflicting and omitted workflow files at their current content, list
+what remains, and give the commands needed to finish the upgrade. When a malformed or
+structurally invalid file blocks `--force`, the draft only updates the payload version
+and lockfile.
+
+Diagnostic JSON stays under the runner's temporary directory. Upgrade branches include
+the target version, so a later release does not overwrite an older open PR.
+
+The payload is public npm. A repo with other private dependencies must opt this workflow
+out and provide its own install authentication.
 
 ### Action pinning policy
 

package/dist/config.d.mts

@@ -99,6 +99,10 @@ interface NuxtBaseDockerConfig {
 interface NuxtBaseAutomationConfig {
     /** Sync the weekly streamctl upgrade-PR workflow (default: off, no workflow lands). */
     upgradePr?: boolean;
+    /** Let upgrade PRs change GitHub Actions workflows (default: false). */
+    allowWorkflowUpdates?: boolean;
+    /** Repository secret used when workflow updates are allowed. */
+    prTokenSecret?: string;
 }
 /**
  * Supply-chain knobs (`config.security.*`): the pnpm install cooldown rendered into

package/dist/config.d.ts

@@ -99,6 +99,10 @@ interface NuxtBaseDockerConfig {
 interface NuxtBaseAutomationConfig {
     /** Sync the weekly streamctl upgrade-PR workflow (default: off, no workflow lands). */
     upgradePr?: boolean;
+    /** Let upgrade PRs change GitHub Actions workflows (default: false). */
+    allowWorkflowUpdates?: boolean;
+    /** Repository secret used when workflow updates are allowed. */
+    prTokenSecret?: string;
 }
 /**
  * Supply-chain knobs (`config.security.*`): the pnpm install cooldown rendered into

package/dist/config.mjs

@@ -24,7 +24,9 @@ const NUXT_BASE_DOCKER_KEYS = knobKeys({
   startCommand: 0
 });
 const NUXT_BASE_AUTOMATION_KEYS = knobKeys({
-  upgradePr: 0
+  upgradePr: 0,
+  allowWorkflowUpdates: 0,
+  prTokenSecret: 0
 });
 const NUXT_BASE_SECURITY_KEYS = knobKeys({
   minimumReleaseAge: 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidebase/base-config",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Shared @sidebase base configuration for Nuxt repos: ESLint / Prisma / tsconfig factories on npm, plus the streamctl file-sync preset payload",
   "keywords": [
     "sidebase",

package/presets/base/github/workflows/streamctl-upgrade.yml

@@ -1,41 +1,30 @@
-# Managed by streamctl. Off by default; lands only when a repo sets
-# `automation: { upgradePr: true }`. See the README section "Upgrade-PR workflow".
-#
-# Needs `secrets.STREAMCTL_PR_TOKEN`: a PR opened with `GITHUB_TOKEN` does not trigger
-# `pull_request` workflows, so the repo's own `check` gate would never run on it.
-#
-# A repo with private dependencies must opt this file out and wire its own auth:
-# `files: { ".github/workflows/streamctl-upgrade.yml": "off" }`.
+# Managed by streamctl. Enabled by `automation.upgradePr`.
+# Repos with private dependencies should own this workflow.
+# Workflow updates need the configured token with Contents, Pull requests, and Workflows write.
 name: streamctl upgrade
 
 on:
   schedule:
-    - cron: "0 6 * * 1" # Mondays 06:00 UTC
+    - cron: "0 6 * * 1"
   workflow_dispatch:
 
-# Every PR and issue write below uses STREAMCTL_PR_TOKEN, so the default token
-# only needs to read the repo for checkout.
 permissions:
-  contents: read
+  contents: write
+  issues: write
+  pull-requests: write
 
 env:
+  ALLOW_WORKFLOW_UPDATES: "${ALLOW_WORKFLOW_UPDATES}"
   NODE_VERSION: "${NODE_VERSION}"
 
 jobs:
   upgrade:
     runs-on: ubuntu-latest
     steps:
-      # To mint an App token in-workflow instead of storing a PAT, uncomment this
-      # and use `${{ steps.bot.outputs.token }}` in place of STREAMCTL_PR_TOKEN:
-      #
-      # - id: bot
-      #   uses: actions/create-github-app-token@5d869da34e18e7287c1daad50e0b8ea0f506ce69 # v1.11.0
-      #   with:
-      #     app-id: ${{ secrets.STREAMCTL_APP_ID }}
-      #     private-key: ${{ secrets.STREAMCTL_APP_PRIVATE_KEY }}
-
       - name: Checkout
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
 
       - name: Set up pnpm
         uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
@@ -51,70 +40,362 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      # Exit codes: 4 = update available, 0 = up to date, 3 = repo already drifted.
+      - name: Capture managed-file state
+        run: pnpm streamctl status --json > "$RUNNER_TEMP/streamctl-status.json"
+
       - id: check
         name: Check for a payload update
         run: |
           set +e
-          pnpm streamctl check --fail-on outdated --json > streamctl-check.json
-          echo "code=$?" >> "$GITHUB_OUTPUT"
+          pnpm streamctl check --fail-on any --json > "$RUNNER_TEMP/streamctl-check.json"
+          code=$?
           set -e
-          cat streamctl-check.json
+          echo "code=$code" >> "$GITHUB_OUTPUT"
+          echo "target=$(jq -r '.error.details.updateAvailable.latest // empty' "$RUNNER_TEMP/streamctl-check.json")" >> "$GITHUB_OUTPUT"
+          cat "$RUNNER_TEMP/streamctl-check.json"
+
+      - name: Fail on an unexpected check result
+        if: ${{ steps.check.outputs.code != '0' && steps.check.outputs.code != '3' && steps.check.outputs.code != '4' }}
+        run: exit 1
 
-      - name: Open a drift issue (repo already diverged)
+      - name: Require an update target
+        if: ${{ steps.check.outputs.code == '4' }}
+        env:
+          TARGET: ${{ steps.check.outputs.target }}
+        run: test -n "$TARGET"
+
+      - name: Ensure workflow labels
+        if: ${{ steps.check.outputs.code == '3' || steps.check.outputs.code == '4' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh label create streamctl --color 0E8A16 --description "Managed by streamctl" --force
+          gh label create needs-interactive-upgrade --color D93F0B --description "Manual upgrade work required" --force
+
+      - name: Require the PR token
+        if: ${{ steps.check.outputs.code == '4' && env.ALLOW_WORKFLOW_UPDATES == 'true' }}
+        env:
+          PR_TOKEN: ${{ secrets.${PR_TOKEN_SECRET} }}
+        run: test -n "$PR_TOKEN"
+
+      - name: Open or update the drift issue
         if: ${{ steps.check.outputs.code == '3' }}
         env:
-          GH_TOKEN: ${{ secrets.STREAMCTL_PR_TOKEN }}
+          GH_TOKEN: ${{ github.token }}
         run: |
-          gh issue create \
-            --title "streamctl: managed files have drifted" \
-            --label streamctl \
-            --body "\`streamctl check\` reports pre-existing drift, so the automated upgrade was skipped. Run \`pnpm streamctl sync\` locally, commit the result, then re-run this workflow."
+          title="streamctl: managed files have drifted"
+          body="The automated upgrade was skipped because managed files already differ. Run \`pnpm streamctl sync\` locally, commit the result, then rerun this workflow. Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          issue_number=$(gh issue list --state open --label streamctl --search "\"$title\" in:title" --json number --jq '.[0].number // empty')
+          if [[ -n "$issue_number" ]]; then
+            gh issue edit "$issue_number" --body "$body"
+          else
+            gh issue create --title "$title" --label streamctl --body "$body"
+          fi
 
-      # Only upgrade when an update is actually available (check exit 4).
       - id: upgrade
         name: Upgrade the payload
         if: ${{ steps.check.outputs.code == '4' }}
+        env:
+          CI: "false"
+          TARGET: ${{ steps.check.outputs.target }}
         run: |
           set +e
-          pnpm streamctl upgrade --json > streamctl-upgrade.json
-          echo "code=$?" >> "$GITHUB_OUTPUT"
+          pnpm streamctl upgrade --to "$TARGET" --yes --json > "$RUNNER_TEMP/streamctl-upgrade.raw"
+          code=$?
           set -e
-          cat streamctl-upgrade.json
+          tail -n 1 "$RUNNER_TEMP/streamctl-upgrade.raw" > "$RUNNER_TEMP/streamctl-upgrade.json"
+          echo "code=$code" >> "$GITHUB_OUTPUT"
+          cat "$RUNNER_TEMP/streamctl-upgrade.raw"
+
+      - name: Fail on an unexpected upgrade result
+        if: ${{ steps.upgrade.outputs.code != '' && steps.upgrade.outputs.code != '0' && steps.upgrade.outputs.code != '2' }}
+        run: exit 1
 
-      # Exit 2 means the sync hit conflicts and rolled back. Bump only the pin and
-      # devDependency so the PR carries a diff a human reconciles interactively.
-      - name: Prepare a plan-only bump (interactive sync required)
+      - id: conflicts
+        name: Classify upgrade conflicts
         if: ${{ steps.upgrade.outputs.code == '2' }}
-        run: pnpm streamctl upgrade --no-install --json > streamctl-upgrade.json
+        run: |
+          jq -r --slurpfile status "$RUNNER_TEMP/streamctl-status.json" '
+            (.error.details.conflicted // [])[]
+            | select((
+                (.kind == "edit" or .kind == "adoption")
+                and (.path as $path | any($status[0].data.files[];
+                  .path == $path and .strategy == "full" and .state == "in-sync"
+                ))
+              ) | not)
+            | .path
+          ' "$RUNNER_TEMP/streamctl-upgrade.json" | sort -u > "$RUNNER_TEMP/streamctl-unsafe.txt"
+          if [[ ! -s "$RUNNER_TEMP/streamctl-unsafe.txt" ]] && jq -e '
+            .error.code == "CONFLICTS_PENDING"
+            and .error.details.rolledBack == true
+            and (.error.details.conflicted | length > 0)
+          ' "$RUNNER_TEMP/streamctl-upgrade.json" > /dev/null; then
+            echo "safe=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "safe=false" >> "$GITHUB_OUTPUT"
+          fi
 
-      - name: Open the upgrade PR (clean reconcile)
-        if: ${{ steps.upgrade.outputs.code == '0' }}
+      - id: force
+        name: Apply safe generated replacements
+        if: ${{ steps.conflicts.outputs.safe == 'true' }}
+        env:
+          CI: "false"
+          TARGET: ${{ steps.check.outputs.target }}
+        run: |
+          set +e
+          pnpm streamctl upgrade --to "$TARGET" --force --json > "$RUNNER_TEMP/streamctl-force.raw"
+          code=$?
+          set -e
+          tail -n 1 "$RUNNER_TEMP/streamctl-force.raw" > "$RUNNER_TEMP/streamctl-force.json"
+          echo "code=$code" >> "$GITHUB_OUTPUT"
+          cat "$RUNNER_TEMP/streamctl-force.raw"
+
+      - name: Fail when safe replacement fails
+        if: ${{ steps.conflicts.outputs.safe == 'true' && steps.force.outputs.code != '0' }}
+        run: exit 1
+
+      - id: outcome
+        name: Record the upgrade outcome
+        if: ${{ steps.check.outputs.code == '4' }}
+        env:
+          FORCE_CODE: ${{ steps.force.outputs.code }}
+          UPGRADE_CODE: ${{ steps.upgrade.outputs.code }}
+        run: |
+          if [[ "$UPGRADE_CODE" == "0" || "$FORCE_CODE" == "0" ]]; then
+            echo "completed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "completed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - id: workflow_changes
+        name: Exclude workflow changes by default
+        if: ${{ steps.outcome.outputs.completed == 'true' }}
+        run: |
+          jq -r '
+            (.data.plan // .error.details.plan // [])[]
+            | .path
+            | select(startswith(".github/workflows/"))
+          ' "$RUNNER_TEMP/streamctl-upgrade.json" | sort -u > "$RUNNER_TEMP/streamctl-workflows.txt"
+          echo "blocked=false" >> "$GITHUB_OUTPUT"
+          if [[ "$ALLOW_WORKFLOW_UPDATES" == "true" || ! -s "$RUNNER_TEMP/streamctl-workflows.txt" ]]; then
+            exit 0
+          fi
+          while IFS= read -r path; do
+            if git cat-file -e "HEAD:$path" 2>/dev/null; then
+              git restore --source=HEAD --worktree -- "$path"
+            else
+              rm -f -- "$path"
+            fi
+          done < "$RUNNER_TEMP/streamctl-workflows.txt"
+          echo "blocked=true" >> "$GITHUB_OUTPUT"
+
+      - id: manual
+        name: Prepare the manual upgrade
+        if: ${{ steps.upgrade.outputs.code == '2' && steps.conflicts.outputs.safe == 'false' }}
+        env:
+          CI: "false"
+          TARGET: ${{ steps.check.outputs.target }}
+        run: |
+          set +e
+          pnpm streamctl upgrade --to "$TARGET" --force --json
+          code=$?
+          set -e
+          # Faults and malformed files cannot be forced; fall back to the pin bump.
+          if [[ "$code" != "0" ]]; then
+            pnpm streamctl upgrade --to "$TARGET" --no-install --json
+            pnpm install --lockfile-only --ignore-scripts
+            echo "applied=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          : > "$RUNNER_TEMP/streamctl-workflows.txt"
+          if [[ "$ALLOW_WORKFLOW_UPDATES" != "true" ]]; then
+            jq -r '
+              (.data.plan // .error.details.plan // [])[]
+              | .path
+              | select(startswith(".github/workflows/"))
+            ' "$RUNNER_TEMP/streamctl-upgrade.json" | sort -u > "$RUNNER_TEMP/streamctl-workflows.txt"
+          fi
+          sort -u "$RUNNER_TEMP/streamctl-unsafe.txt" "$RUNNER_TEMP/streamctl-workflows.txt" > "$RUNNER_TEMP/streamctl-held.txt"
+          while IFS= read -r path; do
+            if git cat-file -e "HEAD:$path" 2>/dev/null; then
+              git restore --source=HEAD --worktree -- "$path"
+            else
+              rm -f -- "$path"
+            fi
+          done < "$RUNNER_TEMP/streamctl-held.txt"
+          echo "applied=true" >> "$GITHUB_OUTPUT"
+
+      - name: Validate the completed upgrade
+        if: ${{ steps.outcome.outputs.completed == 'true' && steps.workflow_changes.outputs.blocked == 'false' }}
+        run: |
+          pnpm streamctl check
+          pnpm run --if-present lint
+          pnpm run --if-present typecheck
+          pnpm run --if-present test
+          pnpm run --if-present build
+
+      - name: Validate the partial upgrade
+        if: ${{ steps.workflow_changes.outputs.blocked == 'true' }}
+        run: |
+          set +e
+          pnpm streamctl check --fail-on drift --json > "$RUNNER_TEMP/streamctl-partial-check.raw"
+          code=$?
+          set -e
+          tail -n 1 "$RUNNER_TEMP/streamctl-partial-check.raw" > "$RUNNER_TEMP/streamctl-partial-check.json"
+          test "$code" -eq 3
+          jq -Rsc 'split("\n") | map(select(length > 0)) | sort' \
+            "$RUNNER_TEMP/streamctl-workflows.txt" > "$RUNNER_TEMP/streamctl-workflows.json"
+          jq -e --slurpfile expected "$RUNNER_TEMP/streamctl-workflows.json" '
+            .error.code == "DRIFT_DETECTED"
+            and (.error.details.structuralFaults | length == 0)
+            and (.error.details.versionSkew | length == 0)
+            and (([.error.details.drift[].path] | sort) == $expected[0])
+          ' "$RUNNER_TEMP/streamctl-partial-check.json" > /dev/null
+          pnpm run --if-present lint
+          pnpm run --if-present typecheck
+          pnpm run --if-present test
+          pnpm run --if-present build
+
+      - name: Prepare the completed-upgrade description
+        if: ${{ steps.outcome.outputs.completed == 'true' && steps.workflow_changes.outputs.blocked == 'false' }}
+        env:
+          TARGET: ${{ steps.check.outputs.target }}
+        run: |
+          from=$(jq -r '.data.payload.pinned' "$RUNNER_TEMP/streamctl-status.json")
+          {
+            echo "## Summary"
+            echo
+            printf -- '- Updated the streamctl payload from `%s` to `%s`.\n' "$from" "$TARGET"
+            echo "- Reconciled all managed files."
+            echo "- Updated dependencies and the lockfile."
+            echo
+            echo "## Validation"
+            echo
+            echo '- `pnpm streamctl check`'
+            echo "- Available lint, typecheck, test, and build scripts"
+          } > "$RUNNER_TEMP/streamctl-pr.md"
+
+      - name: Open the completed upgrade PR
+        if: ${{ steps.outcome.outputs.completed == 'true' && steps.workflow_changes.outputs.blocked == 'false' }}
         uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
         with:
-          token: ${{ secrets.STREAMCTL_PR_TOKEN }}
-          branch: chore/streamctl-upgrade
-          commit-message: "chore: upgrade the streamctl payload"
-          title: "chore: upgrade the streamctl payload"
-          body: |
-            Automated payload upgrade: the managed files were reconciled cleanly by
-            `streamctl upgrade`. Review the diff; `streamctl-upgrade.json` (in the run
-            logs) has the full sync summary and dependency bumps.
+          token: ${{ env.ALLOW_WORKFLOW_UPDATES == 'true' && secrets.${PR_TOKEN_SECRET} || github.token }}
+          branch: chore/streamctl-upgrade-${{ steps.check.outputs.target }}
+          commit-message: "chore: upgrade streamctl payload to ${{ steps.check.outputs.target }}"
+          title: "chore: upgrade streamctl payload to ${{ steps.check.outputs.target }}"
+          body-path: ${{ runner.temp }}/streamctl-pr.md
           labels: streamctl
 
-      - name: Open a plan-only PR (conflicts need interactive sync)
-        if: ${{ steps.upgrade.outputs.code == '2' }}
+      - name: Prepare the resolve instructions
+        if: ${{ steps.workflow_changes.outputs.blocked == 'true' || steps.manual.outputs.applied != '' }}
+        env:
+          TARGET: ${{ steps.check.outputs.target }}
+        run: |
+          branch="chore/streamctl-upgrade-$TARGET"
+          {
+            echo "## Resolve"
+            echo
+            echo '```sh'
+            printf 'git fetch origin %s\n' "$branch"
+            printf 'git switch --create %s --track origin/%s\n' "$branch" "$branch"
+            echo 'pnpm install --frozen-lockfile'
+            echo 'pnpm streamctl sync --interactive'
+            echo 'pnpm streamctl check'
+            echo 'pnpm run --if-present lint'
+            echo 'pnpm run --if-present typecheck'
+            echo 'pnpm run --if-present test'
+            echo 'pnpm run --if-present build'
+            echo 'git add .'
+            echo 'git commit -m "chore: finish streamctl upgrade"'
+            echo 'git push'
+            echo '```'
+          } > "$RUNNER_TEMP/streamctl-resolve.md"
+
+      - name: Prepare the workflow-update description
+        if: ${{ steps.workflow_changes.outputs.blocked == 'true' }}
+        env:
+          TARGET: ${{ steps.check.outputs.target }}
+        run: |
+          from=$(jq -r '.data.payload.pinned' "$RUNNER_TEMP/streamctl-status.json")
+          {
+            echo "## Status"
+            echo
+            echo "This update omits GitHub Actions workflow changes. Do not merge this pull request yet."
+            echo
+            printf -- '- Updated the streamctl payload from `%s` to `%s`.\n' "$from" "$TARGET"
+            echo "- Applied every other safe managed-file change."
+            echo "- Updated dependencies and the lockfile."
+            echo
+            echo "## Omitted workflow files"
+            echo
+            sed 's|^|- `|; s|$|`|' "$RUNNER_TEMP/streamctl-workflows.txt"
+            echo
+            cat "$RUNNER_TEMP/streamctl-resolve.md"
+          } > "$RUNNER_TEMP/streamctl-workflow-pr.md"
+
+      - name: Open the workflow-update PR
+        if: ${{ steps.workflow_changes.outputs.blocked == 'true' }}
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
+        with:
+          token: ${{ env.ALLOW_WORKFLOW_UPDATES == 'true' && secrets.${PR_TOKEN_SECRET} || github.token }}
+          branch: chore/streamctl-upgrade-${{ steps.check.outputs.target }}
+          commit-message: "chore: prepare streamctl payload ${{ steps.check.outputs.target }}"
+          title: "chore: upgrade streamctl payload to ${{ steps.check.outputs.target }}"
+          body-path: ${{ runner.temp }}/streamctl-workflow-pr.md
+          draft: true
+          labels: |
+            streamctl
+            needs-interactive-upgrade
+
+      - name: Prepare the manual-upgrade description
+        if: ${{ steps.upgrade.outputs.code == '2' && steps.conflicts.outputs.safe == 'false' }}
+        env:
+          APPLIED: ${{ steps.manual.outputs.applied }}
+          TARGET: ${{ steps.check.outputs.target }}
+        run: |
+          from=$(jq -r '.data.payload.pinned' "$RUNNER_TEMP/streamctl-status.json")
+          {
+            echo "## Status"
+            echo
+            echo "This update needs manual conflict resolution. Do not merge this pull request yet."
+            echo
+            printf -- '- Updated the streamctl payload from `%s` to `%s`.\n' "$from" "$TARGET"
+            if [[ "$APPLIED" == "true" ]]; then
+              echo "- Applied every safe managed-file change."
+              echo "- Left conflicting managed files unchanged."
+            else
+              echo "- Did not update managed files because \`streamctl upgrade --force\` failed. See the workflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+            fi
+            echo "- Updated dependencies and the lockfile."
+            echo
+            echo "## Conflicts"
+            echo
+            jq -r --arg applied "$APPLIED" --rawfile unsafe "$RUNNER_TEMP/streamctl-unsafe.txt" '
+              ($unsafe | split("\n")) as $held
+              | .error.details.conflicted[]
+              | select($applied != "true" or (.path | IN($held[])))
+              | "- `\(.path)` (`\(.kind)`): \(.reason)"
+            ' "$RUNNER_TEMP/streamctl-upgrade.json"
+            echo
+            if [[ -s "$RUNNER_TEMP/streamctl-workflows.txt" ]]; then
+              echo "## Omitted workflow files"
+              echo
+              sed 's|^|- `|; s|$|`|' "$RUNNER_TEMP/streamctl-workflows.txt"
+              echo
+            fi
+            cat "$RUNNER_TEMP/streamctl-resolve.md"
+          } > "$RUNNER_TEMP/streamctl-conflict-pr.md"
+
+      - name: Open the manual upgrade PR
+        if: ${{ steps.upgrade.outputs.code == '2' && steps.conflicts.outputs.safe == 'false' }}
         uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
         with:
-          token: ${{ secrets.STREAMCTL_PR_TOKEN }}
-          branch: chore/streamctl-upgrade
-          commit-message: "chore: bump the streamctl payload pin (interactive sync required)"
-          title: "chore: streamctl payload upgrade needs interactive sync"
-          body: |
-            The automated `streamctl upgrade` hit conflicts and rolled the sync back, so
-            only the payload pin + devDependency were bumped here. Finish the upgrade by
-            hand: check out this branch, run `pnpm streamctl sync --interactive`, resolve
-            each conflict, and push.
+          token: ${{ env.ALLOW_WORKFLOW_UPDATES == 'true' && secrets.${PR_TOKEN_SECRET} || github.token }}
+          branch: chore/streamctl-upgrade-${{ steps.check.outputs.target }}
+          commit-message: "chore: prepare streamctl payload ${{ steps.check.outputs.target }}"
+          title: "chore: upgrade streamctl payload to ${{ steps.check.outputs.target }}"
+          body-path: ${{ runner.temp }}/streamctl-conflict-pr.md
+          draft: true
           labels: |
             streamctl
             needs-interactive-upgrade

package/presets/base/gitignore

@@ -15,6 +15,3 @@ prisma/migrations/dev
 /local.*
 /local.*/
 prisma/local.*
-# CLAUDE.md is managed by streamctl. A user-global gitignore matching the name
-# everywhere would silently untrack it, so force-allow it.
-!CLAUDE.md

package/presets/base/preset.json

@@ -10,13 +10,14 @@
     { "path": ".vscode/settings.json", "strategy": "merge", "source": "base/vscode/settings.json", "render": "editor", "projectFields": ["editor.fontSize", "editor.rulers", "editor.formatOnSave", "files.exclude", "search.exclude", "files.watcherExclude"] },
     { "path": ".vscode/extensions.json", "strategy": "merge", "source": "base/vscode/extensions.json", "projectFields": ["unwantedRecommendations"] },
     { "path": "AGENTS.md", "strategy": "full", "source": "base/AGENTS.md", "adoption": "expected" },
-    { "path": "CLAUDE.md", "strategy": "scaffold", "source": "base/CLAUDE.md", "adoption": "expected" },
     { "path": ".github/workflows/streamctl-upgrade.yml", "strategy": "full", "source": "base/github/workflows/streamctl-upgrade.yml", "render": "automation-upgrade", "enabledBy": "automation.upgradePr", "adoption": "unexpected" }
   ],
   "renders": {
     "automation-upgrade": {
       "placeholders": {
-        "NODE_VERSION": { "configPath": "versions.node", "default": "24.13.0", "pattern": "^[\\w.+-]+$" }
+        "ALLOW_WORKFLOW_UPDATES": { "configPath": "automation.allowWorkflowUpdates", "default": "false", "pattern": "^(?:true|false)$" },
+        "NODE_VERSION": { "configPath": "versions.node", "default": "24.13.0", "pattern": "^[\\w.+-]+$" },
+        "PR_TOKEN_SECRET": { "configPath": "automation.prTokenSecret", "default": "STREAMCTL_PR_TOKEN", "pattern": "^(?![Gg][Ii][Tt][Hh][Uu][Bb]_)[A-Za-z_][A-Za-z0-9_]*$" }
       }
     },
     "editor": {
@@ -34,6 +35,8 @@
     }
   },
   "configKeys": {
+    "automation.allowWorkflowUpdates": "boolean",
+    "automation.prTokenSecret": "string",
     "automation.upgradePr": "boolean",
     "editor.i18nSourceLanguage": "string",
     "security.minimumReleaseAge": "string",

package/presets/base/CLAUDE.md

@@ -1,3 +0,0 @@
-# CLAUDE.md
-
-@AGENTS.md