spec-up-t 1.6.12 → 1.6.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.6.12",
+  "version": "1.6.13",
   "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

@@ -16,7 +16,11 @@ const config = fs.readJsonSync('specs.json');
 const outputPath = config.specs[0].output_path;
 
 const sourceFile = path.join(outputPath, 'index.html');
-const destDir = path.join(outputPath, 'versions');
+
+// spec-versions/ lives at the repo root and is committed to the main branch.
+// This is the source of truth — it survives gh-pages resets and fresh CI checkouts.
+// docs/versions/ is the derived, deployed copy and is always rebuilt from here.
+const destDir = 'spec-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.
@@ -117,7 +121,11 @@ async function run() {
 
     Logger.success(`Created a freezed specification version in ${destFile}`);
 
-    // Update the versions index.html to include the newly created version
+    // Sync spec-versions/ → docs/versions/ so the local preview reflects the
+    // new snapshot immediately, then regenerate the versions index page.
+    const syncSpecVersions = require('./pipeline/configuration/sync-spec-versions.js');
+    syncSpecVersions(outputPath);
+
     const createVersionsIndex = require('./pipeline/configuration/create-versions-index.js');
     createVersionsIndex(outputPath);
 }

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

@@ -85,8 +85,13 @@ jobs:
               npm run todocx
               ;;
             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.
+              # A fresh CI checkout has no docs/ (gitignored), so we must render
+              # first to give freeze-spec-data.js the docs/index.html it needs.
+              # freeze-spec-data.js then writes the snapshot to spec-versions/,
+              # which is tracked in git. The commit+push step below commits
+              # spec-versions/ to the main branch, which triggers
+              # render-and-deploy.yml to deploy the full spec (including versions).
+              npm run collectExternalReferences
               FREEZE_LABEL="${{ github.event.inputs.freeze_label }}" npm run freeze
               ;;
             custom-update)
@@ -126,6 +131,8 @@ jobs:
               git commit -m "Collect external references" || echo "No changes to commit"
               ;;
             freeze)
+              # spec-versions/ is tracked in git — committing it triggers
+              # render-and-deploy.yml, which deploys the full spec with versions.
               git commit -m "Freeze specification" || echo "No changes to commit"
               ;;
             custom-update)

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

@@ -61,9 +61,27 @@ jobs:
 
       # Collect external references — this also renders the specification and
       # writes output to the path defined in specs.json (output_path, typically ./docs/).
+      # The render pipeline (prepare-spec-configuration.js) automatically copies
+      # spec-versions/ → docs/versions/ so frozen snapshots are always included.
       - name: Collect external references and render
         run: npm run collectExternalReferences
 
+      # Preserve the CNAME file from gh-pages before deploying.
+      # peaceiris/actions-gh-pages replaces the entire gh-pages branch with the
+      # contents of ./docs. A fresh CI checkout of main never contains docs/CNAME
+      # (docs/ is gitignored), so without this step any previously committed CNAME
+      # would be silently deleted on every render.
+      - name: Preserve CNAME from gh-pages
+        run: |
+          git fetch origin gh-pages 2>/dev/null || true
+          CNAME_CONTENT=$(git show origin/gh-pages:CNAME 2>/dev/null || echo "")
+          if [ -n "$CNAME_CONTENT" ]; then
+            echo "$CNAME_CONTENT" > docs/CNAME
+            echo "CNAME preserved: $CNAME_CONTENT"
+          else
+            echo "No CNAME found on gh-pages — nothing to preserve"
+          fi
+
       # 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.

package/src/install-from-boilerplate/custom-update.js

@@ -1,3 +1,4 @@
+const fs = require('fs-extra');
 const { configScriptsKeys } = require('./config-scripts-keys');
 const { configOverwriteScriptsKeys } = require('./config-scripts-keys');
 const addScriptsKeys = require('./add-scripts-keys');
@@ -5,6 +6,7 @@ const copySystemFiles = require('./copy-system-files');
 const { gitIgnoreEntries } = require('./config-gitignore-entries');
 const { updateGitignore } = require('./add-gitignore-entries');
 const updateDependencies = require('./update-dependencies');
+const migrateVersionsToSpecVersions = require('./migrate-versions-to-spec-versions');
 const Logger = require('../utils/logger');
 
 
@@ -17,8 +19,18 @@ const customUpdate = () => {
     // Update dependencies based on package.spec-up-t.json
     updateDependencies();
 
-    // Custom logic here
-    // ...
+    // One-time migration: repos that stored snapshots in docs/versions/ (the old
+    // "commit docs/" regime) need their snapshots moved to spec-versions/ so they
+    // survive after docs/ is removed from git tracking. Safe to run on every
+    // custom-update — already-migrated versions are not overwritten.
+    try {
+        const config = fs.readJsonSync('specs.json');
+        const outputPath = config.specs[0].output_path;
+        migrateVersionsToSpecVersions(outputPath);
+    } catch (error) {
+        // specs.json missing or malformed — skip migration silently.
+        Logger.info('Skipping versions migration: could not read specs.json');
+    }
 }
 
 // Call custom update

package/src/install-from-boilerplate/migrate-versions-to-spec-versions.js

@@ -0,0 +1,85 @@
+/**
+ * @file migrate-versions-to-spec-versions.js
+ * @description One-time migration helper for repositories that were created under the
+ * old "commit docs/" regime. Those repos store frozen snapshots inside docs/versions/.
+ *
+ * Starting with the issue270 changes, snapshots are stored in spec-versions/ (tracked,
+ * at the repo root) instead of docs/versions/ (gitignored, ephemeral). This migration
+ * copies any snapshots found in docs/versions/ into spec-versions/ so they are not
+ * lost when the user eventually removes docs/ from git tracking.
+ *
+ * - Safe to run more than once: already-migrated versions are not overwritten.
+ * - Does nothing when docs/versions/ does not exist (new repos or repos that never froze).
+ * - Does not delete docs/versions/ — git history is preserved; the user decides when
+ *   to run `git rm -r --cached docs/`.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const Logger = require('../utils/logger');
+
+/**
+ * Migrates frozen snapshots from docs/versions/ to spec-versions/.
+ * @param {string} outputPath - The output directory defined in specs.json (e.g. './docs').
+ */
+function migrateVersionsToSpecVersions(outputPath) {
+    const src = path.join(outputPath, 'versions');
+    const dest = 'spec-versions';
+
+    if (!fs.existsSync(src)) {
+        // No old snapshots to migrate — nothing to do.
+        return;
+    }
+
+    // Check whether there are any version subdirectories (v1, v2, …) to migrate.
+    // We skip labels.json and index.html — those are regenerated automatically.
+    const versionDirs = fs.readdirSync(src).filter(entry =>
+        fs.statSync(path.join(src, entry)).isDirectory()
+    );
+
+    if (versionDirs.length === 0) {
+        return;
+    }
+
+    fs.ensureDirSync(dest);
+
+    let migratedCount = 0;
+
+    // Copy each version directory that does not already exist in spec-versions/.
+    versionDirs.forEach(dir => {
+        const srcDir = path.join(src, dir);
+        const destDir = path.join(dest, dir);
+
+        if (!fs.existsSync(destDir)) {
+            fs.copySync(srcDir, destDir);
+            migratedCount++;
+        }
+    });
+
+    // Always keep labels.json up to date in spec-versions/.
+    const srcLabels = path.join(src, 'labels.json');
+    const destLabels = path.join(dest, 'labels.json');
+
+    if (fs.existsSync(srcLabels)) {
+        if (!fs.existsSync(destLabels)) {
+            // No labels.json in spec-versions/ yet — copy the whole file.
+            fs.copySync(srcLabels, destLabels);
+        } else {
+            // Merge: preserve any entries already in spec-versions/labels.json
+            // and add any entries from docs/versions/labels.json that are missing.
+            const existing = fs.readJsonSync(destLabels);
+            const legacy = fs.readJsonSync(srcLabels);
+            const merged = { ...legacy, ...existing }; // spec-versions wins on conflict
+            fs.writeJsonSync(destLabels, merged, { spaces: 2 });
+        }
+    }
+
+    if (migratedCount > 0) {
+        Logger.success(
+            `Migrated ${migratedCount} snapshot(s) from ${src} to ${dest}/. ` +
+            `You can now safely run: git rm -r --cached ${outputPath}`
+        );
+    }
+}
+
+module.exports = migrateVersionsToSpecVersions;

package/src/pipeline/configuration/prepare-spec-configuration.js

@@ -34,6 +34,12 @@ async function initializeConfig(options = {}) {
     const createExternalSpecsList = require('./create-external-specs-list.js');
     const externalSpecsList = createExternalSpecsList(config);
 
+    // Copy any frozen snapshots from the tracked spec-versions/ directory into
+    // the output path before regenerating the versions index. This is what makes
+    // locally-created or CI-created freezes survive a fresh checkout and redeploy.
+    const syncSpecVersions = require('./sync-spec-versions.js');
+    syncSpecVersions(config.specs[0].output_path);
+
     const createVersionsIndex = require('./create-versions-index.js');
     createVersionsIndex(config.specs[0].output_path);
 

package/src/pipeline/configuration/sync-spec-versions.js

@@ -0,0 +1,38 @@
+/**
+ * @file sync-spec-versions.js
+ * @description Copies the tracked spec-versions/ directory (at the consuming repo's
+ * root) into the output path's versions/ folder before the spec is rendered and
+ * deployed. This ensures that snapshots committed to the main branch are always
+ * included in the deployed specification, even after a completely fresh CI checkout
+ * where docs/ does not yet exist.
+ *
+ * spec-versions/ is the source of truth for frozen snapshots.
+ * docs/versions/   is the derived, deployable copy (gitignored, rebuilt every render).
+ *
+ * Does nothing when spec-versions/ does not exist — so repositories that have
+ * never run `npm run freeze` are not affected.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const Logger = require('../../utils/logger.js');
+
+/**
+ * Copies all contents of spec-versions/ into outputPath/versions/.
+ * The destination is created if it does not already exist.
+ * @param {string} outputPath - The output directory defined in specs.json (e.g. './docs').
+ */
+function syncSpecVersions(outputPath) {
+    const src = 'spec-versions';
+    const dest = path.join(outputPath, 'versions');
+
+    if (!fs.existsSync(src)) {
+        // No snapshots have been created yet — nothing to sync.
+        return;
+    }
+
+    fs.copySync(src, dest);
+    Logger.info(`Synced spec-versions/ → ${dest}`);
+}
+
+module.exports = syncSpecVersions;

package/src/pipeline/rendering/render-spec-document.js

@@ -40,6 +40,12 @@ async function render(spec, assets, sharedVars, config, template, assetsGlobal,
     // Get the branch name from which the index.html was generated
     const buildBranch = getCurrentBranch();
 
+    // Read spec-up-t version from its own package.json for build info display
+    const specUpTVersion = require('../../../package.json').version;
+
+    // Capture Node.js runtime version for build info display
+    const nodeVersion = process.version;
+
     // Read all markdown files into an array
     const docs = await Promise.all(
       (spec.markdown_paths || ['spec.md']).map(_path =>
@@ -166,6 +172,8 @@ async function render(spec, assets, sharedVars, config, template, assetsGlobal,
       currentDate: currentDate,
       universalTimestamp: universalTimestamp,
       buildBranch: buildBranch,
+      specUpTVersion: specUpTVersion,
+      nodeVersion: nodeVersion,
       githubRepoInfo: getGithubRepoInfo(spec)
     });
 

package/templates/template.html

@@ -325,6 +325,14 @@
                         <i class="bi bi-signpost-split me-2"></i>
                         <span>Source branch: <strong>${buildBranch}</strong></span>
                     </div>
+                    <div class="d-flex align-items-center mb-1">
+                        <i class="bi bi-box me-2"></i>
+                        <span>spec-up-t: <strong>v${specUpTVersion}</strong></span>
+                    </div>
+                    <div class="d-flex align-items-center mb-1">
+                        <i class="bi bi-cpu me-2"></i>
+                        <span>Node.js: <strong>${nodeVersion}</strong></span>
+                    </div>
                 </div>
             </div>
             <hr>