infra: add sync:ii-spec script and port 16 upstream spec commits

.github/workflows/sync-ii-spec.yml

@@ -0,0 +1,148 @@
+name: Sync II spec
+
+on:
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub App Token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        id: app-token
+        with:
+          client-id: ${{ vars.PR_AUTOMATION_BOT_PUBLIC_CLIENT_ID }}
+          private-key: ${{ secrets.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY }}
+
+      - name: Initialize internetidentity submodule at current pin
+        run: |
+          git config --global url."https://github.com/".insteadOf "git@github.com:"
+          git submodule update --init --depth 1 .sources/internetidentity
+
+      - name: Get current pinned hash
+        id: current
+        run: |
+          HASH=$(git -C .sources/internetidentity rev-parse HEAD)
+          echo "hash=$HASH" >> $GITHUB_OUTPUT
+          echo "short=$(git -C .sources/internetidentity rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Fetch latest main
+        run: git -C .sources/internetidentity fetch --depth 100 origin main
+
+      - name: Get latest main hash
+        id: latest
+        run: |
+          HASH=$(git -C .sources/internetidentity rev-parse FETCH_HEAD)
+          echo "hash=$HASH" >> $GITHUB_OUTPUT
+          echo "short=$(git -C .sources/internetidentity rev-parse --short FETCH_HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Check if relevant files changed
+        id: check
+        run: |
+          CURRENT="${{ steps.current.outputs.hash }}"
+          LATEST="${{ steps.latest.outputs.hash }}"
+          BRANCH="infra/sync-ii-spec-${{ steps.latest.outputs.short }}"
+
+          if [ "$CURRENT" = "$LATEST" ]; then
+            echo "Already at latest main. No update needed."
+            echo "needed=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          if git ls-remote --exit-code origin "refs/heads/${BRANCH}" > /dev/null 2>&1; then
+            echo "Branch $BRANCH already exists — PR likely open, skipping."
+            echo "needed=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Only proceed if the spec files themselves changed
+          CHANGED=$(git -C .sources/internetidentity diff --name-only "${CURRENT}..${LATEST}" -- \
+            docs/ii-spec.mdx \
+            src/internet_identity/internet_identity.did)
+
+          if [ -z "$CHANGED" ]; then
+            echo "No changes to ii-spec.mdx or internet_identity.did. Skipping."
+            echo "needed=false" >> $GITHUB_OUTPUT
+          else
+            echo "Spec files changed:"
+            echo "$CHANGED"
+            echo "needed=true" >> $GITHUB_OUTPUT
+            echo "changed_files<<EOF" >> $GITHUB_OUTPUT
+            echo "$CHANGED" >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Bump submodule to latest main
+        if: steps.check.outputs.needed == 'true'
+        run: git -C .sources/internetidentity checkout ${{ steps.latest.outputs.hash }}
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        if: steps.check.outputs.needed == 'true'
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        if: steps.check.outputs.needed == 'true'
+        run: npm ci
+
+      - name: Initialize examples submodule (required for build)
+        if: steps.check.outputs.needed == 'true'
+        run: git submodule update --init --depth 1 .sources/examples
+
+      - name: Run II spec sync
+        if: steps.check.outputs.needed == 'true'
+        run: npm run sync:ii-spec
+
+      - name: Build check
+        if: steps.check.outputs.needed == 'true'
+        run: npm run build
+
+      - name: Create PR
+        if: steps.check.outputs.needed == 'true'
+        run: |
+          git config user.name "pr-automation-bot-public[bot]"
+          git config user.email "pr-automation-bot-public[bot]@users.noreply.github.com"
+
+          BRANCH="infra/sync-ii-spec-${{ steps.latest.outputs.short }}"
+          git checkout -b "$BRANCH"
+          git add .sources/internetidentity docs/references/internet-identity-spec.md public/references/internet-identity.did
+          git commit -m "chore: sync II spec from dfinity/internet-identity@${{ steps.latest.outputs.short }}"
+          git push -u origin "$BRANCH"
+
+          CHANGED="${{ steps.check.outputs.changed_files }}"
+          {
+            echo "## Summary"
+            echo ""
+            echo "Automated sync of the Internet Identity specification from \`dfinity/internet-identity\` main."
+            echo ""
+            echo "**Pin:** \`${{ steps.current.outputs.short }}\` → \`${{ steps.latest.outputs.short }}\`"
+            echo ""
+            echo "**Changed upstream files:**"
+            while IFS= read -r f; do
+              [ -n "$f" ] && echo "- \`$f\`"
+            done <<< "$CHANGED"
+            echo ""
+            echo "- Ran \`npm run sync:ii-spec\` — regenerated \`docs/references/internet-identity-spec.md\`"
+            echo "- Build passed ✓"
+            echo ""
+            echo "## Checklist"
+            echo ""
+            echo "- [ ] Review the diff to \`docs/references/internet-identity-spec.md\` for content changes"
+            echo "- [ ] Check for new absolute \`internetcomputer.org\` link patterns (script exits non-zero if any were missed)"
+            echo "- [ ] Verify any renamed or restructured sections are reflected correctly"
+            echo ""
+            echo "## Sync recommendation"
+            echo ""
+            echo "\`sync from dfinity/internet-identity — docs/ii-spec.mdx, src/internet_identity/internet_identity.did\`"
+          } > /tmp/pr-body.md
+
+          gh pr create \
+            --title "chore: sync II spec from dfinity/internet-identity@${{ steps.latest.outputs.short }}" \
+            --body-file /tmp/pr-body.md
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}

AGENTS.md

@@ -292,7 +292,7 @@ EOF
 | `candid` | Check for spec changes affecting the Candid reference or type-mapping examples |
 | `response-verification` | Check for API changes affecting certified variables patterns |
 | `dotskills` | Check if the `technical-documentation` skill changed in ways that affect review criteria |
-| `internetidentity` | Check for spec changes in `docs/ii-spec.mdx`; re-sync `internet-identity-spec.md` (see link adaptation note below). Re-copy Candid interface from `src/internet_identity/internet_identity.did` if changed |
+| `internetidentity` | Run `npm run sync:ii-spec` — the script handles all link rewrites, Candid inlining, and frontmatter. If the script exits with a warning about unhandled links, add the new pattern to `linkMap` in `scripts/sync-ii-spec.mjs`. The **Sync II spec** workflow (`.github/workflows/sync-ii-spec.yml`) can be triggered manually from GitHub Actions; it only opens a PR when `docs/ii-spec.mdx` or `internet_identity.did` actually changed. |
 | `chain-fusion-signer` | Check for changed canister IDs, API methods, or key derivation patterns |
 | `papi` | Check for changed payment interface or cycle cost model |
 | `ic-pub-key` | Check for changed CLI flags or commands |
@@ -317,14 +317,7 @@ EOF
    ```
 4. Run `npm run build` to confirm no broken links.
 
-**Link adaptation for `internet-identity-spec.md`:** The upstream source (`docs/ii-spec.mdx`) uses absolute `internetcomputer.org` URLs pointing to the IC interface spec. Our file uses relative paths into the split `ic-interface-spec/` directory. After every re-sync, run:
-```bash
-grep -n "ic-interface-spec" docs/references/internet-identity-spec.md
-```
-Any link of the form `internetcomputer.org/.../ic-interface-spec#<anchor>` or `./ic-interface-spec.md#<anchor>` must be converted. Use the anchor-to-file mapping at the bottom of `docs/references/internet-identity-spec.md` as the authoritative guide. If a new anchor appears that is not in the comment, find its file with:
-```bash
-grep -r "{#<anchor>}" docs/references/ic-interface-spec/
-```
+**Link adaptation for `internet-identity-spec.md`:** Handled automatically by `npm run sync:ii-spec`. The script rewrites all absolute `internetcomputer.org` links to relative paths using `linkMap` in `scripts/sync-ii-spec.mjs`. If a new link pattern appears in the upstream source, the script exits with a warning listing the unhandled URL — add it to `linkMap` with the correct relative path (use `grep -r "{#<anchor>}" docs/references/ic-interface-spec/` to find which file owns the anchor), then re-run.
 
 ### Synced files from submodules