spec-up-t 1.6.10 → 1.6.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.6.10",
+  "version": "1.6.11",
   "description": "Technical specification drafting tool that generates rich specification documents from markdown. Forked from https://github.com/decentralized-identity/spec-up by Daniel Buchner (https://github.com/csuwildcat)",
   "main": "./index",
   "repository": {

package/src/install-from-boilerplate/boilerplate/.github/workflows/menu.yml

@@ -33,7 +33,8 @@ jobs:
   build-and-deploy-spec:
     runs-on: ubuntu-latest
     permissions:
-      contents: write  # Needed for pushing changes and deploying to Pages
+      contents: write   # Needed for pushing changes
+      actions: write    # Needed to dispatch render-and-deploy.yml
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v4
@@ -68,7 +69,14 @@ jobs:
         run: |
           case "${{ github.event.inputs.action_type }}" in
             render)
-              npm run render
+              # Rendering is handled by render-and-deploy.yml.
+              # Dispatch that workflow to render and deploy to GitHub Pages.
+              curl -s -X POST \
+                -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+                -H "Accept: application/vnd.github+json" \
+                "https://api.github.com/repos/${{ github.repository }}/actions/workflows/render-and-deploy.yml/dispatches" \
+                -d "{\"ref\":\"${{ github.ref_name }}\"}"
+              echo "render-and-deploy.yml dispatched"
               ;;
             topdf)
               npm run topdf
@@ -105,7 +113,8 @@ jobs:
           # Commit with appropriate message
           case "${{ github.event.inputs.action_type }}" in
             render)
-              git commit -m "Render specification: Update files" || echo "No changes to commit"
+              # render-and-deploy.yml already handles the commit/deploy; nothing to commit here.
+              echo "Render dispatched to render-and-deploy.yml — no direct commit needed"
               ;;
             topdf)
               git commit -m "Export to PDF" || echo "No changes to commit"
@@ -128,16 +137,7 @@ jobs:
           esac
           
           # Push changes
-          git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
-
-      - name: Commit output files
-        if: success()
-        run: |
-          git config --global user.email "actions@github.com"
-          git config --global user.name "GitHub Actions"
-          git add "$OUTPUT_PATH"
-          git commit -m "Update output files in $OUTPUT_PATH" || echo "No changes to commit in output directory"
-          git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
+          git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:${{ github.ref_name }}
 
       - name: Clean up
         if: always()

package/src/install-from-boilerplate/boilerplate/.github/workflows/render-and-deploy.yml

@@ -0,0 +1,109 @@
+name: Render and Deploy to GitHub Pages
+
+# Triggered automatically on every push to main or master, or manually via
+# the Actions tab (or when dispatched by menu.yml for a render action).
+# Renders the specification and pushes the output to the gh-pages branch.
+# docs/ is NEVER committed to main/master.
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    # Do not trigger on workflow file changes (.github/). Each workflow file
+    # is uploaded as a separate commit during repo creation, which would cause
+    # multiple competing runs in the same concurrency group. Real spec content
+    # changes (spec/, specs.json, package.json, etc.) still trigger a render.
+    # The initial render after repo creation is handled by an explicit dispatch.
+    # The trigger matrix is now:
+    #
+    # Event --> Triggers render?
+    #
+    # Push spec content (spec, specs.json, etc.) --> ✅ yes
+    # Push `.github/workflows/*.yml` (repo creation) --> ❌ no
+    # `workflow_dispatch` (GitHubUi "render" button, or menu.yml) --> ✅ yes
+    # PR into main/master --> ❌ not triggered (no `pull_request:` event)
+
+    paths-ignore:
+      - '.github/**'
+  workflow_dispatch:
+
+# Only allow one deployment at a time; do not cancel in-progress runs so that
+# a completed deploy is never replaced by a stale one.
+# NOTE: do NOT use 'pages' as the group name — that conflicts with GitHub's own
+# internal Pages deployment concurrency group and causes spurious cancellations.
+concurrency:
+  group: render-and-deploy-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ── Build & Deploy ────────────────────────────────────────────────────────────
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    # GitHub automatically generates a GITHUB_TOKEN for each workflow run.
+    # This ephemeral token is scoped only to the current repository and expires
+    # after the run completes. The 'permissions' block declares what this token
+    # is allowed to do — GitHub denies operations outside these scopes.
+    permissions:
+      contents: write # Required by peaceiris/actions-gh-pages to push to gh-pages
+      pages: write    # Required to configure GitHub Pages source via API
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies 🔧
+        run: npm install
+
+      # Collect external references — this also renders the specification and
+      # writes output to the path defined in specs.json (output_path, typically ./docs/).
+      - name: Collect external references and render
+        run: npm run collectExternalReferences
+
+      # Push the rendered ./docs output to the gh-pages branch.
+      # peaceiris/actions-gh-pages creates the branch on first run when it
+      # does not yet exist — no manual branch setup is required.
+      # Uses GITHUB_TOKEN (automatically injected by GitHub) with 'contents: write'
+      # permission to push to this repository.
+      - name: Deploy to GitHub Pages 🚀
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages
+
+      # Configure GitHub Pages to serve from the gh-pages branch (root /).
+      # This uses the GitHub REST API with GITHUB_TOKEN (permission: 'pages: write').
+      # It is idempotent — safe to run on every render (201=create, 409/422=exists, update).
+      # GITHUB_TOKEN is ephemeral (created per-run, expires at run end), scoped only to
+      # this repository, and never logged. GitHub accepts it because the token is issued
+      # by GitHub itself and this workflow declares 'pages: write' permission.
+      # continue-on-error: the API call may return a conflict on the very first run while
+      # GitHub is still processing the new gh-pages branch — this is non-fatal.
+      - name: Configure GitHub Pages source
+        continue-on-error: true
+        run: |
+          TOKEN="${{ secrets.GITHUB_TOKEN }}"
+          REPO="${{ github.repository }}"
+
+          HTTP_CODE=$(curl -s -o response.json -w "%{http_code}" \
+            -X POST \
+            -H "Authorization: token $TOKEN" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/$REPO/pages" \
+            -d '{"source":{"branch":"gh-pages","path":"/"}}')
+
+          # 201 = created; 409/422 = already exists, update instead
+          if [ "$HTTP_CODE" -eq 409 ] || [ "$HTTP_CODE" -eq 422 ]; then
+            curl -s -o /dev/null \
+              -X PUT \
+              -H "Authorization: token $TOKEN" \
+              -H "Accept: application/vnd.github+json" \
+              "https://api.github.com/repos/$REPO/pages" \
+              -d '{"source":{"branch":"gh-pages","path":"/"}}'
+          fi
+          echo "GitHub Pages source set to gh-pages branch"

package/src/install-from-boilerplate/boilerplate/.github/workflows/set-gh-pages.yml

@@ -1,5 +1,10 @@
 name: Set GitHub Pages and Homepage
 
+# One-time setup workflow: run this AFTER the first successful
+# render-and-deploy run, which creates the gh-pages branch.
+# It configures GitHub Pages to serve from the gh-pages branch (root /)
+# and sets the repository homepage URL.
+
 on:
   workflow_dispatch:
 
@@ -7,93 +12,90 @@ jobs:
   configure-pages-and-homepage:
     runs-on: ubuntu-latest
     permissions:
-      contents: read  # To check branches
-      pages: write   # To configure Pages settings
+      contents: read
     steps:
-      - name: Check if gh-pages branch exists
-        id: check-branch
-        run: |
-          RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
-            -H "Authorization: token ${{ secrets.MY_PAT }}" \
-            -H "Accept: application/vnd.github+json" \
-            https://api.github.com/repos/${{ github.repository }}/branches/gh-pages)
-          if [ "$RESPONSE" -eq 200 ]; then
-            echo "gh-pages branch exists"
-            echo "BRANCH_EXISTS=true" >> $GITHUB_ENV
-          elif [ "$RESPONSE" -eq 404 ]; then
-            echo "Error: gh-pages branch does not exist in ${{ github.repository }}"
-            exit 1
-          else
-            echo "Unexpected response code: $RESPONSE"
-            exit 1
-          fi
-
-      - name: Set GitHub Pages to gh-pages
-        if: env.BRANCH_EXISTS == 'true'
+      # Configure Pages to serve from the gh-pages branch (root /).
+      # POST creates the resource; a 409 means it already exists, so we PUT
+      # to update the source to the gh-pages branch.
+      - name: Enable GitHub Pages (gh-pages branch source)
         env:
           PAT: ${{ secrets.MY_PAT }}
         run: |
-          RESPONSE=$(curl -s -L \
+          HTTP_CODE=$(curl -s -L \
             -X POST \
             -H "Authorization: token $PAT" \
             -H "Accept: application/vnd.github+json" \
             https://api.github.com/repos/${{ github.repository }}/pages \
             -d '{"source":{"branch":"gh-pages","path":"/"}}' \
-            -w "%{http_code}" -o response.json)
-          if [ "$RESPONSE" -eq 201 ] || [ "$RESPONSE" -eq 200 ]; then
-            echo "GitHub Pages set to gh-pages branch for ${{ github.repository }}"
+            -w "%{http_code}" -o response.json | tail -n1)
+
+          if [ "$HTTP_CODE" -eq 201 ] || [ "$HTTP_CODE" -eq 200 ]; then
+            echo "GitHub Pages enabled with gh-pages branch as source"
+          elif [ "$HTTP_CODE" -eq 409 ]; then
+            echo "Pages already exists — updating source to gh-pages branch..."
+            HTTP_CODE2=$(curl -s -L \
+              -X PUT \
+              -H "Authorization: token $PAT" \
+              -H "Accept: application/vnd.github+json" \
+              https://api.github.com/repos/${{ github.repository }}/pages \
+              -d '{"source":{"branch":"gh-pages","path":"/"}}' \
+              -w "%{http_code}" -o response2.json | tail -n1)
+            if [ "$HTTP_CODE2" -eq 200 ] || [ "$HTTP_CODE2" -eq 204 ]; then
+              echo "GitHub Pages source updated to gh-pages branch"
+            else
+              echo "Failed to update Pages: $HTTP_CODE2"
+              cat response2.json
+              exit 1
+            fi
           else
-            echo "Failed to set GitHub Pages: $RESPONSE"
+            echo "Failed to configure Pages: $HTTP_CODE"
             cat response.json
             exit 1
           fi
 
+      # Set the repository homepage field to the expected GitHub Pages URL so
+      # it appears prominently on the repository landing page.
       - name: Set repository homepage to GitHub Pages URL
-        if: env.BRANCH_EXISTS == 'true'
         env:
           PAT: ${{ secrets.MY_PAT }}
         run: |
-          # Construct the expected GitHub Pages URL
           REPO_NAME=$(echo "${{ github.repository }}" | cut -d'/' -f2)
           OWNER=$(echo "${{ github.repository }}" | cut -d'/' -f1)
           PAGES_URL="https://${OWNER}.github.io/${REPO_NAME}"
 
-          # Set the homepage via API
-          RESPONSE=$(curl -s -L \
+          HTTP_CODE=$(curl -s -L \
             -X PATCH \
             -H "Authorization: token $PAT" \
             -H "Accept: application/vnd.github+json" \
             https://api.github.com/repos/${{ github.repository }} \
             -d "{\"homepage\":\"${PAGES_URL}\"}" \
-            -w "%{http_code}" -o response.json)
+            -w "%{http_code}" -o response.json | tail -n1)
 
-          if [ "$RESPONSE" -eq 200 ]; then
-            echo "Repository homepage set to $PAGES_URL for ${{ github.repository }}"
+          if [ "$HTTP_CODE" -eq 200 ]; then
+            echo "Repository homepage set to $PAGES_URL"
           else
-            echo "Failed to set homepage: $RESPONSE"
+            echo "Failed to set homepage: $HTTP_CODE"
             cat response.json
             exit 1
           fi
 
+      # Verify the homepage was written correctly.
       - name: Verify homepage matches GitHub Pages URL
-        if: env.BRANCH_EXISTS == 'true'
         env:
           PAT: ${{ secrets.MY_PAT }}
         run: |
-          # Construct the expected GitHub Pages URL
           REPO_NAME=$(echo "${{ github.repository }}" | cut -d'/' -f2)
           OWNER=$(echo "${{ github.repository }}" | cut -d'/' -f1)
           EXPECTED_URL="https://${OWNER}.github.io/${REPO_NAME}"
 
-          # Fetch the current homepage from the repo
           CURRENT_HOMEPAGE=$(curl -s -L \
             -H "Authorization: token $PAT" \
             -H "Accept: application/vnd.github+json" \
             https://api.github.com/repos/${{ github.repository }} | jq -r '.homepage')
 
           if [ "$CURRENT_HOMEPAGE" = "$EXPECTED_URL" ]; then
-            echo "Verified: Homepage is set to GitHub Pages URL ($EXPECTED_URL)"
+            echo "Verified: homepage is $EXPECTED_URL"
           else
-            echo "Error: Homepage ($CURRENT_HOMEPAGE) does not match expected GitHub Pages URL ($EXPECTED_URL)"
+            echo "Error: homepage ($CURRENT_HOMEPAGE) does not match $EXPECTED_URL"
             exit 1
           fi

package/src/install-from-boilerplate/boilerplate/gitignore

@@ -10,6 +10,9 @@
 # `.git/info/exclude` file instead of modifying the shared .gitignore.
 # Entries in `.git/info/exclude` stay completely local.
 
+# Generated by render-and-deploy.yml — do not commit build output
+docs/
+
 # Dependencies
 node_modules/
 

package/src/install-from-boilerplate/config-gitignore-entries.js

@@ -12,7 +12,9 @@ const gitIgnoreEntries = {
         '.env',
         'coverage',
         'build',
-        '.history'
+        '.history',
+        // Generated by render-and-deploy.yml — do not commit build output
+        'docs'
 ],
 };
 

package/src/install-from-boilerplate/config-system-files.js

@@ -3,6 +3,7 @@ const systemFiles = [
     '.env.example',
     'menu-wrapper.sh',
     '.github/workflows/menu.yml',
+    '.github/workflows/render-and-deploy.yml',
     '.github/workflows/set-gh-pages.yml',
     'assets/test.json',
     'assets/test.text',