@sidebase/base-config 0.2.0 → 0.2.2

package/docs/migration.md

@@ -334,10 +334,10 @@ the managed file and is reverted on the next sync.
 warns you. `streamctl check` stays green, the file looks deliberate, and a package whose
 install scripts are blocked still installs.
 
-Be precise about the consequence, because it is narrower than it first appears. The usual
-suspects (`sharp`, `@tailwindcss/oxide`, `unrs-resolver`, `@parcel/watcher`) ship their
-native binary as a prebuilt optional dependency, so on a platform with a prebuild they keep
-working whether or not they are approved, cold install included. Verified across pnpm
+The consequence is narrower than it first appears. The usual suspects (`sharp`,
+`@tailwindcss/oxide`, `unrs-resolver`, `@parcel/watcher`) ship their native binary as a
+prebuilt optional dependency, so on a platform with a prebuild they keep working whether or
+not they are approved, cold install included. Verified across pnpm
 10.28.1, 10.29.1 and 10.29.3. Where the loss is real:
 
 - architectures with no prebuild, where the binary genuinely has to be compiled
@@ -546,13 +546,12 @@ too, so on first sync the payload appends its block to whatever your repository
 Your existing lines stay above it. Nothing is overwritten and nothing is reported.
 
 Most of the leftovers are harmless. Ignore patterns are additive, so a duplicated `node_modules`
-or `.env` above the block is genuinely inert -- it changes nothing about what the build context
-carries. Delete them anyway, for a reason that is not tidiness: the detector below is the only
-thing that will ever tell you a payload entry has started shadowing something of yours, and it
-is not a one-shot check. A future payload version can add an entry that collides with a line you
-kept above the block, and a file with leftover duplicates reads `AFFECTED` forever, so it can no
-longer distinguish that from the noise. Clearing them is what keeps the check able to answer next
-time.
+or `.env` above the block is inert; it changes nothing about what the build context carries.
+Delete them anyway, and not for tidiness. The detector below is the only thing that will ever
+tell you a payload entry has started shadowing something of yours, and it is not a one-shot
+check. A future payload version can add an entry that collides with a line you kept above the
+block. A file with leftover duplicates reads `AFFECTED` forever, so it can no longer distinguish
+that from the noise. Clearing them keeps the check able to answer next time.
 
 **The case that bites is a negation.** `.dockerignore` is last-match-wins, and the managed block
 is appended at the BOTTOM, so every payload entry beats anything you wrote above it. A repository
@@ -822,5 +821,5 @@ keeps its own command this way.
 
 Nothing here is destructive if you work on a branch. `sync` rewrites tracked files, so
 `git diff` shows everything it did and `git restore` undoes it. Keep the migration on its
-own branch and its own commit so that if the sync diff turns out to be larger than
-expected, reverting it is one operation rather than an archaeology exercise.
+own branch and its own commit, so that if the sync diff turns out to be larger than
+expected, reverting it is one operation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidebase/base-config",
-  "version": "0.2.0",
+  "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/AGENTS.md

@@ -10,6 +10,15 @@ follow. They are the same across every repo in the fleet.
 - Never commit secrets, credentials, or generated build artifacts.
 - Keep all code, comments and identifiers in English.
 
+## Comments & wording
+
+- Keep comments short. Say WHY the code is the way it is, not what it plainly does.
+- ASCII only: no em dash, en dash, arrow, ellipsis, curly quote, or emoji.
+- One idea per sentence. Cut filler openers ("It is worth noting") and inflated words
+  ("leverage", "utilize", "robust", "seamless").
+- Do not leave a comment describing an alternative you rejected, or internal ticket
+  shorthand a reader cannot resolve.
+
 ## Types & correctness
 
 - Use precise types; avoid `any` and unchecked casts. Parse and validate external input at the boundary instead of trusting it downstream.

package/presets/base/dockerignore

@@ -12,16 +12,15 @@ tests
 .env
 .env.*
 !.env.example
-# The build-stage COPY globs `.npmrc*`; keep token-bearing backups
-# (`.npmrc.local`, `.npmrc.bak`, ...) out of the build context. `.npmrc` itself
-# is intentionally allowed through.
+# The build stage globs `.npmrc*`, so keep token-bearing backups like
+# `.npmrc.local` out of the build context. `.npmrc` itself is allowed through.
 .npmrc.*
 .DS_Store
-# Local dev state written by `pnpm db` / `docker compose up`. `prisma/pglite-data`
-# is tens of MB; `prisma/local.postgres_data` is root-owned, which fails a rootless
-# `docker build` outright. Patterns are anchored to the context root here (unlike
-# .gitignore), so `**/local.*` is required to reach the nested paths.
+# Local dev state from `pnpm db` or `docker compose up`. `prisma/pglite-data` is
+# tens of MB, and root-owned `prisma/local.postgres_data` fails a rootless build.
+# Root-anchored so `src/path/local.ts` still reaches the build context.
 prisma/client
 prisma/pglite-data
 pgliteHealthz
-**/local.*
+local.*
+prisma/local.*

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

@@ -1,49 +1,30 @@
-# Managed by streamctl (full-own, render: automation-upgrade). OFF BY DEFAULT: this
-# file only lands when a repo sets `automation: { upgradePr: true }` in
-# streamctl.config.ts. See the payload README "Upgrade-PR workflow" for enabling.
-#
-# TOKEN: the PR is opened with `secrets.STREAMCTL_PR_TOKEN` (a GitHub App
-# installation token or a machine-account PAT), NOT the default `GITHUB_TOKEN`.
-# A PR created with `GITHUB_TOKEN` does NOT trigger `pull_request` workflows, so
-# this repo's own `check` gate would never run on the bot's PR. The bot identity
-# for the fleet is still being decided; treat this file as inert and provide the
-# secret before enabling. No registry token is needed: the payload is public npm.
-# A repo with OTHER private dependencies must opt this file out
-# (`files: { ".github/workflows/streamctl-upgrade.yml": "off" }`) and wire its own auth.
-#
-# Actions are pinned by full commit SHA (this workflow handles a token); the version
-# tag is in the trailing comment.
+# 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:
 
-# Least privilege: every PR/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:
-      # A bot identity is REQUIRED for the PR (see the header). To mint an App token
-      # in-workflow instead of storing a PAT, uncomment and wire the App credentials,
-      # then use `${{ steps.bot.outputs.token }}` in place of STREAMCTL_PR_TOKEN below:
-      #
-      # - 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
@@ -59,72 +40,362 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      # Exit codes drive the branch: 4 = an update is available (proceed); 0 = up to
-      # date (stop, no PR); 3 = the repo already has drift (open an issue, not a PR).
+      - 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 = the chained sync hit conflicts and ROLLED BACK. Re-run bumping only the
-      # pin + devDependency (no sync) so the PR carries a reviewable diff a human then
-      # reconciles with `streamctl sync --interactive`.
-      - 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

@@ -11,9 +11,7 @@ pglite-debug.log
 prisma/*.db
 prisma/migrations/dev
 .DS_Store
-# streamctl local scratch dirs/files (e.g. local.concept) stay untracked.
-local.*
-local.*/
-# CLAUDE.md is managed by streamctl; a user-global gitignore that ignores the
-# filename everywhere would silently untrack it. Force-allow it here.
-!CLAUDE.md
+# streamctl scratch. Root-anchored so `src/path/local.ts` stays tracked.
+/local.*
+/local.*/
+prisma/local.*

package/presets/base/oxlintrc.json

@@ -3,8 +3,9 @@
     "browser": true
   },
   "ignorePatterns": [
-    "local.*",
-    "local.*/"
+    "/local.*",
+    "/local.*/",
+    "prisma/local.*"
   ],
   "plugins": [
     "unicorn",

package/presets/base/pnpm-workspace.yaml

@@ -1,22 +1,15 @@
-# Managed by streamctl (full-own, render: security). pnpm's own settings file.
+# Managed by streamctl. pnpm's own settings file.
 #
-# SUPPLY-CHAIN COOLDOWN: a version must have been published for ${MIN_RELEASE_AGE}
-# minutes before pnpm will resolve it, so a compromised release has time to be caught
-# and yanked before the fleet installs it. Requires pnpm >= 10.16 (baseline: 10.28.1);
-# it gates fresh resolution only, so `--frozen-lockfile` installs are unaffected.
-# `@sidebase/*` is exempt: the first-party scope (this payload + the streamctl CLI),
-# published by the org itself, so a payload release reaches the fleet the same day.
+# Cooldown: a version must be ${MIN_RELEASE_AGE} minutes old before pnpm resolves it,
+# giving a compromised release time to be yanked. Needs pnpm >= 10.16. Gates fresh
+# resolution only, so `--frozen-lockfile` is unaffected. `@sidebase/*` is exempt.
 #
-# `packages: []` is REQUIRED, not decorative: pnpm defaults it to `**` whenever a
-# pnpm-workspace.yaml exists, which would silently promote every nested package.json
-# (test fixtures, examples) to a workspace project and break `--frozen-lockfile`.
-# A real monorepo owns this key itself, so opt the file out with
-# `files: { "pnpm-workspace.yaml": "off" }` in .streamctl/config.ts.
+# `packages: []` is required: pnpm otherwise defaults it to `**`, promoting every nested
+# package.json to a workspace project and breaking `--frozen-lockfile`. A monorepo should
+# opt out with `files: { "pnpm-workspace.yaml": "off" }`.
 #
-# `onlyBuiltDependencies` is the postinstall-script allowlist: everything else installs
-# with its lifecycle scripts blocked. The baseline covers what the fleet universally
-# needs; add extras via `pnpm: { onlyBuiltDependencies: [...] }` rather than running
-# `pnpm approve-builds` (which writes here and would be reverted on the next sync).
+# `onlyBuiltDependencies` allowlists postinstall scripts. Add extras through the `pnpm`
+# knob, not `pnpm approve-builds`, which writes here and is reverted on the next sync.
 packages: []
 minimumReleaseAge: ${MIN_RELEASE_AGE}
 minimumReleaseAgeExclude:

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",