spec-up-t 1.6.9 → 1.6.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.6.9",
+  "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/freeze-spec-data.js

@@ -2,10 +2,13 @@
  * @file freeze-spec-data.js
  * @description Reads the output path from specs.json, finds the highest versioned directory
  * in the destination path, and copies index.html to a new directory with an incremented version.
+ * The user is prompted for a human-readable label for the snapshot; the label is persisted in
+ * versions/labels.json so that create-versions-index.js can use it as link text.
  */
 
 const fs = require('fs-extra');
 const path = require('path');
+const readline = require('node:readline');
 const Logger = require('./utils/logger');
 const { versions } = require('./utils/regex-patterns');
 
@@ -15,6 +18,16 @@ const outputPath = config.specs[0].output_path;
 const sourceFile = path.join(outputPath, 'index.html');
 const destDir = path.join(outputPath, 'versions');
 
+// A snapshot can only be created when the specification has been built at least once.
+// If index.html is missing, the user must run `npm run menu 1` (or `npm run menu 4`) first.
+if (!fs.existsSync(sourceFile)) {
+    Logger.error(
+        `Cannot create a snapshot: "${sourceFile}" does not exist.\n` +
+        `Please build the specification first (e.g. npm run menu 1 or npm run menu 9) and try again.`
+    );
+    process.exit(0);
+}
+
 if (!fs.existsSync(destDir)) {
     fs.mkdirSync(destDir, { recursive: true });
 }
@@ -35,16 +48,78 @@ dirs.forEach(dir => {
 
 const newVersion = highestVersion + 1;
 const newVersionDir = path.join(destDir, `v${newVersion}`);
+const defaultLabel = `v${newVersion}`;
 
-if (!fs.existsSync(newVersionDir)) {
-    fs.mkdirSync(newVersionDir, { recursive: true });
+/**
+ * Prompts the user for a single line of input, showing a default value.
+ * Pressing Enter without typing accepts the default.
+ * @param {string} question - The question text shown to the user.
+ * @param {string} defaultValue - The value used when the user presses Enter without typing.
+ * @returns {Promise<string>}
+ */
+function prompt(question, defaultValue) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(`${question} [${defaultValue}]: `, answer => {
+            rl.close();
+            resolve(answer.trim() || defaultValue);
+        });
+    });
 }
 
-const destFile = path.join(newVersionDir, 'index.html');
-fs.copyFileSync(sourceFile, destFile);
+/**
+ * Persists the label for the given directory name in versions/labels.json.
+ * Existing entries are preserved; only the new key is added or updated.
+ * @param {string} labelsFile - Absolute path to labels.json.
+ * @param {string} dirName - The version directory name (e.g. "v3").
+ * @param {string} label - The human-readable label to store.
+ */
+function saveLabel(labelsFile, dirName, label) {
+    const existing = fs.existsSync(labelsFile) ? fs.readJsonSync(labelsFile) : {};
+    existing[dirName] = label;
+    fs.writeJsonSync(labelsFile, existing, { spaces: 2 });
+}
+
+/**
+ * Main flow: resolve the label, create the version directory, copy the snapshot,
+ * save the label, and regenerate the versions index.
+ *
+ * Label resolution order:
+ *  1. FREEZE_LABEL environment variable — set by the menu.yml GitHub Actions workflow
+ *     so that GitHubUi (or any non-interactive caller) can supply a custom label.
+ *  2. Interactive readline prompt — only used when stdin is a real TTY (local CLI).
+ *  3. Default label (e.g. "v3") — fallback for non-interactive environments without
+ *     an explicit FREEZE_LABEL (e.g. running freeze directly inside a CI script).
+ */
+async function run() {
+    let label;
+
+    if (process.env.FREEZE_LABEL) {
+        // Non-interactive path: label supplied by caller via environment variable
+        label = process.env.FREEZE_LABEL;
+    } else if (process.stdin.isTTY) {
+        // Interactive path: prompt the user, defaulting to the auto-generated name
+        label = await prompt('Enter a label for this snapshot', defaultLabel);
+    } else {
+        // Non-interactive path without an explicit label: use the auto-generated default
+        label = defaultLabel;
+    }
+
+    if (!fs.existsSync(newVersionDir)) {
+        fs.mkdirSync(newVersionDir, { recursive: true });
+    }
 
-Logger.success(`Created a freezed specification version in ${destFile}`);
+    const destFile = path.join(newVersionDir, 'index.html');
+    fs.copyFileSync(sourceFile, destFile);
+
+    const labelsFile = path.join(destDir, 'labels.json');
+    saveLabel(labelsFile, `v${newVersion}`, label);
+
+    Logger.success(`Created a freezed specification version in ${destFile}`);
+
+    // Update the versions index.html to include the newly created version
+    const createVersionsIndex = require('./pipeline/configuration/create-versions-index.js');
+    createVersionsIndex(outputPath);
+}
 
-// Update the versions index.html to include the newly created version
-const createVersionsIndex = require('./pipeline/configuration/create-versions-index.js');
-createVersionsIndex(outputPath);
+run();

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

@@ -24,12 +24,17 @@ on:
       triggered_by:
         description: 'Triggered by'
         required: false
+      freeze_label:
+        description: 'Label for the snapshot (freeze action only). Leave empty to use the auto-generated version number.'
+        required: false
+        default: ''
 
 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
@@ -64,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
@@ -73,7 +85,9 @@ jobs:
               npm run todocx
               ;;
             freeze)
-              npm run freeze
+              # Pass the label to freeze-spec-data.js via environment variable.
+              # If freeze_label is empty the script falls back to the auto-generated default.
+              FREEZE_LABEL="${{ github.event.inputs.freeze_label }}" npm run freeze
               ;;
             custom-update)
               npm run custom-update
@@ -99,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"
@@ -122,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

@@ -1,11 +1,61 @@
+#######################
+#
+# BEGIN SPEC-UP-T rules
+#
+#######################
+
+# This file represents the recommended .gitignore for Spec-Up-T projects.
+# If you only need to ignore something locally and don’t want to
+# commit the rule, you can add the pattern to your repository’s
+# `.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/
+
+# Logs
 *.log
-dist
+
+# Editor / OS temporaries & backups
 *.bak
 *.tmp
-.DS_Store
-.env
-coverage
-build
+.idea
+.vscode/
+
+# Environment / secrets
+.env*
+
+# Test coverage
+coverage/
+
+# Various caches & history
 .history/
-/.cache/
+.cache/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon\r          # (the \r is intentional — it's a hidden carriage-return file)
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+*.lnk           # Windows shortcuts (optional, but very common noise)
+
+# Linux / Ubuntu / general Unix-like
+*~              # Editor backup files (Vim, Nano, etc.)
+.*.swp          # Vim swap files
+.*.swo
+.fuse_hidden*   # Sometimes appears with fuse mounts
+
+#######################
+#
+# END SPEC-UP-T rules
+#
+#######################

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

package/src/pipeline/configuration/create-versions-index.js

@@ -29,6 +29,11 @@ function createVersionsIndex(outputPath) {
     // Get all directories in the destination directory
     const dirs = fs.readdirSync(versionsDir).filter(file => fs.statSync(path.join(versionsDir, file)).isDirectory());
 
+    // Load persisted labels written by freeze-spec-data.js.
+    // Falls back to an empty object when no labels file exists yet.
+    const labelsFile = path.join(versionsDir, 'labels.json');
+    const labels = fs.existsSync(labelsFile) ? fs.readJsonSync(labelsFile) : {};
+
     // Generate HTML content
     let htmlContent = `
 <!DOCTYPE html>
@@ -58,7 +63,9 @@ function createVersionsIndex(outputPath) {
         htmlContent += `    <li class="list-group-item">No versions available</li>\n`;
     } else {
         dirs.forEach(dir => {
-            htmlContent += `    <li class="list-group-item"><a href="${dir}/">Version ${dir}</a></li>\n`;
+            // Use the stored label when available; fall back to the directory name
+            const linkText = labels[dir] || `Version ${dir}`;
+            htmlContent += `    <li class="list-group-item"><a href="${dir}/">${linkText}</a></li>\n`;
         });
     }