@ankhorage/devtools 1.15.6 → 1.15.8

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.15.6](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v1.15.8](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects
 
@@ -363,6 +363,8 @@ A repository participates in Changesets synchronization when `.changeset/config.
 
 CI and Release render their `bun-version` from the same managed Bun runtime policy used for `package.json`. They also render Changesets status, version, and publish commands from the same policy that owns the synchronized package scripts. The CI workflow installs that Bun version with the frozen lockfile, builds before repository-provider validation, runs `bunx @ankhorage/ankh doctor validate .`, and conditionally runs lint, formatting, Knip, tests, typecheck, and the strict `changeset:status --since=origin/main` guard for pull requests. After a green change reaches `main`, Release uses the scoped Ankhorage Renovate Sync App token to apply Changesets versioning directly to `main` in a `chore(release)` `[skip ci]` commit and publishes without creating a second Version Packages pull request. Release publishing calls the Devtools-owned runner through the synchronized package script; it never resolves an ambient or mutable Changesets executable. Changesets v3 creates the local release tags; the managed workflow pushes those exact tags and creates any missing GitHub Releases directly, without parsing Changesets’ human-readable publish output.
 
+For the **first npm publication** of a new `@ankhorage/*` package, the organization publishing credential must be able to create/publish packages in the `@ankhorage` scope. With a granular npm token, grant package permission **Read and write (publish and stage)** to the `@ankhorage` scope or **All Packages**. If initial publication fails after Changesets has already pushed the release commit, correct the npm credential and rerun Release; the current unpublished version is reused and must not be bumped again. The managed workflow diagnoses this first-publish state separately from registry/network failures.
+
 The Renovate workflow accepts only same-repository branches created by `renovate[bot]`. It calls the SHA-pinned `ankhorage/renovate` workflow to add a release Changeset for runtime Ankhorage dependency updates or an empty Changeset for dev-only updates. The trusted workflow scopes the Ankhorage Renovate Sync GitHub App token to the current repository and uses it only for the validated commit, allowing every normal pull-request CI workflow to start without manual approval. It never checks out or executes pull-request code in the privileged `pull_request_target` context.
 
 ## Managed VS Code configuration

package/dist/tools/workflows/files/release.yml

@@ -16,10 +16,16 @@ concurrency:
 jobs:
   release:
     runs-on: ubuntu-latest
+    outputs:
+      versioned: ${{ steps.release.outputs.versioned }}
+      package_name: ${{ steps.release.outputs.package_name }}
+      package_version: ${{ steps.release.outputs.package_version }}
+      release_sha: ${{ steps.release.outputs.release_sha }}
 
     steps:
       - name: Create the scoped release token
         id: release-token
+        continue-on-error: true
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
           client-id: ${{ vars.ANKHORAGE_RENOVATE_SYNC_CLIENT_ID }}
@@ -28,6 +34,12 @@ jobs:
           repositories: ${{ github.event.repository.name }}
           permission-contents: write
 
+      - name: Diagnose unavailable scoped release token
+        if: steps.release-token.outcome == 'failure'
+        run: |
+          echo "::error title=Renovate Sync App repository access required::Could not create the scoped Ankhorage release token for ${GITHUB_REPOSITORY}. Ensure the ankhorage-renovate-sync GitHub App is installed and authorized for this repository, then rerun Release. Bootstrap policy: https://github.com/ankhorage/renovate/issues/115"
+          exit 1
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
@@ -67,7 +79,16 @@ jobs:
           git checkout -B main origin/main
 
           if [ -z "$(find .changeset -maxdepth 1 -type f -name '*.md' ! -name README.md -print -quit)" ]; then
-            echo "versioned=false" >> "$GITHUB_OUTPUT"
+            current_subject="$(git log -1 --pretty=%s)"
+            if [ "$current_subject" = "chore(release): version packages [skip ci]" ]; then
+              echo "Recovering the canonical versioned release commit without another version bump."
+              echo "versioned=true" >> "$GITHUB_OUTPUT"
+              echo "package_name=$(node -p "require('./package.json').name")" >> "$GITHUB_OUTPUT"
+              echo "package_version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+              echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+            else
+              echo "versioned=false" >> "$GITHUB_OUTPUT"
+            fi
             exit 0
           fi
 
@@ -107,13 +128,33 @@ jobs:
             echo "versioned=true" >> "$GITHUB_OUTPUT"
             echo "package_name=$(node -p "require('./package.json').name")" >> "$GITHUB_OUTPUT"
             echo "package_version=$after_version" >> "$GITHUB_OUTPUT"
+            echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Publish unpublished packages
         if: hashFiles('.changeset/config.json') != ''
         run: |
           if ! node -e "const p=require('./package.json'); process.exit(p.ankh?.apm === undefined ? 1 : 0)"; then
-            __ANKH_CHANGESETS_PUBLISH_COMMAND__
+            package_name="$(node -p "require('./package.json').name")"
+            package_version="$(node -p "require('./package.json').version")"
+            registry_evidence="${RUNNER_TEMP}/npm-package-preflight.json"
+            package_absent=false
+
+            if npm view "$package_name" version --json > "$registry_evidence"; then
+              :
+            elif node -e "const p=require(process.argv[1]); if(p.error?.code !== 'E404') process.exit(1)" "$registry_evidence"; then
+              package_absent=true
+            else
+              echo "::error title=npm registry preflight failed::Could not determine whether $package_name already exists in npm. Refusing to treat an authentication or network failure as first-publish bootstrap."
+              exit 1
+            fi
+
+            if ! __ANKH_CHANGESETS_PUBLISH_COMMAND__; then
+              if [ "$package_absent" = true ]; then
+                echo "::error title=npm scope publish access required::Initial publish of ${package_name}@${package_version} failed while the package is absent from npm. Verify that the configured npm publishing credential has Read and write (publish and stage) access to the @ankhorage scope or All Packages, then rerun Release. The already-versioned release commit on main is reusable; do not create another version bump. Bootstrap guidance: https://github.com/ankhorage/devtools/issues/225"
+              fi
+              exit 1
+            fi
             exit 0
           fi
 
@@ -132,15 +173,29 @@ jobs:
             __ANKH_APM_RELEASE_COMMAND__ validate . --allow-owner-code --artifact "$artifact"
             npm publish "$artifact" --ignore-scripts
           fi
-          if ! git rev-parse -q --verify "refs/tags/v${package_version}" >/dev/null; then
-            git tag "v${package_version}"
-          fi
+      - name: Skip release tooling
+        if: hashFiles('.changeset/config.json') == ''
+        run: echo "No Changesets config found; skipping versioning and publishing."
+
+  verify-publication:
+    needs: release
+    if: needs.release.outputs.versioned == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Setup Node for npm verification
+        uses: actions/setup-node@v4
+        with:
+          node-version: '__ANKH_NODE_VERSION__'
+          registry-url: https://registry.npmjs.org
 
-      - name: Verify published npm artifact
-        if: steps.release.outputs.versioned == 'true'
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Verify published npm artifact from a fresh runner
         env:
-          PUBLISHED_PACKAGE_NAME: ${{ steps.release.outputs.package_name }}
-          PUBLISHED_PACKAGE_VERSION: ${{ steps.release.outputs.package_version }}
+          PUBLISHED_PACKAGE_NAME: ${{ needs.release.outputs.package_name }}
+          PUBLISHED_PACKAGE_VERSION: ${{ needs.release.outputs.package_version }}
         run: |
           set -euo pipefail
           package_spec="${PUBLISHED_PACKAGE_NAME}@${PUBLISHED_PACKAGE_VERSION}"
@@ -157,9 +212,9 @@ jobs:
             last_stage="registry-metadata"
 
             if npm view "$package_spec" version dist.tarball dist.integrity --json > "$registry_evidence"; then
-              resolved_version="$(node -e "const p=require(process.argv[1]); process.stdout.write(p.version ?? '')" "$registry_evidence")"
-              tarball="$(node -e "const p=require(process.argv[1]); process.stdout.write(p['dist.tarball'] ?? '')" "$registry_evidence")"
-              integrity="$(node -e "const p=require(process.argv[1]); process.stdout.write(p['dist.integrity'] ?? '')" "$registry_evidence")"
+              resolved_version="$(node -e "const raw=require(process.argv[1]); const p=Array.isArray(raw)&&raw.length===1?raw[0]:raw; process.stdout.write(typeof p?.version==='string'?p.version:'')" "$registry_evidence")"
+              tarball="$(node -e "const raw=require(process.argv[1]); const p=Array.isArray(raw)&&raw.length===1?raw[0]:raw; process.stdout.write(typeof p?.['dist.tarball']==='string'?p['dist.tarball']:'')" "$registry_evidence")"
+              integrity="$(node -e "const raw=require(process.argv[1]); const p=Array.isArray(raw)&&raw.length===1?raw[0]:raw; process.stdout.write(typeof p?.['dist.integrity']==='string'?p['dist.integrity']:'')" "$registry_evidence")"
 
               if [ "$resolved_version" = "$PUBLISHED_PACKAGE_VERSION" ] && [ -n "$tarball" ] && [ -n "$integrity" ]; then
                 last_stage="tarball-download"
@@ -188,24 +243,58 @@ jobs:
           cat "$registry_evidence" 2>/dev/null || true
           exit 1
 
-      - name: Finalize Changesets v3 tags and GitHub releases
-        if: hashFiles('.changeset/config.json') != ''
+  finalize:
+    needs:
+      - release
+      - verify-publication
+    if: needs.release.outputs.versioned == 'true' && needs.verify-publication.result == 'success'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Create the scoped release token
+        id: release-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ vars.ANKHORAGE_RENOVATE_SYNC_CLIENT_ID }}
+          private-key: ${{ secrets.ANKHORAGE_RENOVATE_SYNC_PRIVATE_KEY }}
+          owner: ankhorage
+          repositories: ${{ github.event.repository.name }}
+          permission-contents: write
+
+      - name: Checkout exact release commit
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.release.outputs.release_sha }}
+          token: ${{ steps.release-token.outputs.token }}
+
+      - name: Finalize Changesets v3 tag and GitHub release
         env:
-          GH_TOKEN: ${{ github.token }}
+          GH_TOKEN: ${{ steps.release-token.outputs.token }}
+          PUBLISHED_PACKAGE_VERSION: ${{ needs.release.outputs.package_version }}
+          RELEASE_SHA: ${{ needs.release.outputs.release_sha }}
         run: |
-          git tag --points-at HEAD | while IFS= read -r tag; do
-            if [ -z "$tag" ]; then
-              continue
+          set -euo pipefail
+          tag="v${PUBLISHED_PACKAGE_VERSION}"
+          remote_sha="$(git ls-remote --tags origin "refs/tags/$tag" | cut -f1)"
+
+          if [ -n "$remote_sha" ]; then
+            if [ "$remote_sha" != "$RELEASE_SHA" ]; then
+              echo "Existing tag $tag points to $remote_sha, expected $RELEASE_SHA."
+              exit 1
             fi
+          else
+            git tag "$tag" "$RELEASE_SHA"
             git push origin "refs/tags/$tag"
-            if ! gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
-              gh release create "$tag" --repo "$GITHUB_REPOSITORY" --generate-notes
-            fi
-          done
+          fi
+
+          if ! gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release create "$tag" --repo "$GITHUB_REPOSITORY" --generate-notes --target "$RELEASE_SHA"
+          fi
 
       - name: Create the scoped rollout token
         id: rollout-token
-        if: steps.release.outputs.versioned == 'true' && steps.release.outputs.package_name == '@ankhorage/devtools'
+        if: needs.release.outputs.package_name == '@ankhorage/devtools'
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
           client-id: ${{ vars.ANKHORAGE_RENOVATE_SYNC_CLIENT_ID }}
@@ -215,11 +304,11 @@ jobs:
           permission-contents: write
 
       - name: Trigger the Devtools consumer rollout
-        if: steps.release.outputs.versioned == 'true' && steps.release.outputs.package_name == '@ankhorage/devtools'
+        if: needs.release.outputs.package_name == '@ankhorage/devtools'
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         env:
-          PUBLISHED_PACKAGE_NAME: ${{ steps.release.outputs.package_name }}
-          PUBLISHED_PACKAGE_VERSION: ${{ steps.release.outputs.package_version }}
+          PUBLISHED_PACKAGE_NAME: ${{ needs.release.outputs.package_name }}
+          PUBLISHED_PACKAGE_VERSION: ${{ needs.release.outputs.package_version }}
         with:
           github-token: ${{ steps.rollout-token.outputs.token }}
           script: |
@@ -240,7 +329,3 @@ jobs:
               event_type: 'devtools-release',
               client_payload: { version: release.version },
             });
-
-      - name: Skip release tooling
-        if: hashFiles('.changeset/config.json') == ''
-        run: echo "No Changesets config found; skipping versioning and publishing."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.15.6",
+  "version": "1.15.8",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",