spec-up-t 1.6.15 → 1.6.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.6.15",
+  "version": "1.6.17",
   "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/add-gitignore-entries.js

@@ -30,10 +30,17 @@ async function updateGitignore(gitignorePath, filesToAdd) {
         // Split the content into lines and remove empty lines
         const gitignoreLines = gitignoreContent.split('\n').filter(line => line.trim() !== '');
 
-        // Add files to .gitignore if they are not already present
+        // Add files to .gitignore if they are not already present.
+        // Strip inline comments from existing lines before comparing, so that
+        // entries like "*.lnk  # some comment" are not duplicated.
         filesToAdd.forEach(file => {
-            if (!gitignoreLines.some(line => line.trim() === file.trim())) {
-                gitignoreLines.push(file.trim());
+            const pattern = file.trim();
+            const alreadyPresent = gitignoreLines.some(line => {
+                const linePattern = line.trim().split('#')[0].trim();
+                return linePattern === pattern;
+            });
+            if (!alreadyPresent) {
+                gitignoreLines.push(pattern);
             }
         });
 

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

@@ -3,19 +3,41 @@ const path = require('path');
 // Configuration
 const gitIgnoreEntries = {
     gitignorePath: path.join(process.cwd(), '.gitignore'),
-    filesToAdd: ['node_modules',
+    filesToAdd: [
+        // Generated by render-and-deploy.yml — do not commit build output
+        'docs/',
+        // Dependencies
+        'node_modules/',
+        // Logs
         '*.log',
-        'dist',
+        // Editor / OS temporaries & backups
         '*.bak',
         '*.tmp',
+        '.idea',
+        '.vscode/',
+        // Environment / secrets
+        '.env*',
+        // Test coverage
+        'coverage/',
+        // Various caches & history
+        '.history/',
+        '.cache/',
+        // macOS
         '.DS_Store',
-        '.env',
-        'coverage',
-        'build',
-        '.history',
-        // Generated by render-and-deploy.yml — do not commit build output
-        'docs'
-],
+        '.AppleDouble',
+        '.LSOverride',
+        // Windows
+        'Thumbs.db',
+        'ehthumbs.db',
+        'Desktop.ini',
+        '$RECYCLE.BIN/',
+        '*.lnk',
+        // Linux / Ubuntu / general Unix-like
+        '*~',
+        '.*.swp',
+        '.*.swo',
+        '.fuse_hidden*',
+    ],
 };
 
 module.exports = { gitIgnoreEntries };

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

@@ -18,6 +18,34 @@ const fs = require('fs-extra');
 const path = require('path');
 const Logger = require('../utils/logger');
 
+/**
+ * Extracts snapshot labels from a hand-edited docs/versions/index.html.
+ * Parses every anchor whose href points to a version directory (e.g. "v1/")
+ * and maps the directory name to the visible link text.
+ *
+ * Example input:  <a href="v1/">KERI Release 1.0</a>
+ * Example output: { "v1": "KERI Release 1.0" }
+ *
+ * The "Latest version" link (href="../") is intentionally ignored.
+ *
+ * @param {string} indexHtmlPath - Absolute path to docs/versions/index.html.
+ * @returns {Object} Map of version directory names to label strings.
+ */
+function extractLabelsFromIndexHtml(indexHtmlPath) {
+    const labels = {};
+    const html = fs.readFileSync(indexHtmlPath, 'utf8');
+    // Match: href="v1/" or href="v1" (with or without trailing slash)
+    const linkPattern = /href="(v\d+)\/?">([^<]+)<\/a>/g;
+    let match = linkPattern.exec(html);
+    while (match !== null) {
+        const dirName = match[1];
+        const linkText = match[2].trim();
+        labels[dirName] = linkText;
+        match = linkPattern.exec(html);
+    }
+    return labels;
+}
+
 /**
  * Migrates frozen snapshots from docs/versions/ to snapshots/.
  * @param {string} outputPath - The output directory defined in specs.json (e.g. './docs').
@@ -57,27 +85,38 @@ function migrateVersionsToSnapshots(outputPath) {
     });
 
     // Always keep labels.json up to date in snapshots/.
+    // Priority order (highest wins):
+    //   1. Labels already in snapshots/labels.json (from previous migrations or freezes)
+    //   2. Labels extracted from hand-edited docs/versions/index.html
+    //   3. Labels from docs/versions/labels.json (auto-generated source)
     const srcLabels = path.join(src, 'labels.json');
+    const srcIndexHtml = path.join(src, 'index.html');
     const destLabels = path.join(dest, 'labels.json');
 
-    if (fs.existsSync(srcLabels)) {
-        if (!fs.existsSync(destLabels)) {
-            // No labels.json in snapshots/ yet — copy the whole file.
-            fs.copySync(srcLabels, destLabels);
-        } else {
-            // Merge: preserve any entries already in snapshots/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 }; // snapshots wins on conflict
-            fs.writeJsonSync(destLabels, merged, { spaces: 2 });
-        }
+    // Start from labels.json if it exists
+    const legacyLabels = fs.existsSync(srcLabels) ? fs.readJsonSync(srcLabels) : {};
+
+    // Overlay with labels parsed from index.html — these may be hand-edited
+    const htmlLabels = fs.existsSync(srcIndexHtml)
+        ? extractLabelsFromIndexHtml(srcIndexHtml)
+        : {};
+
+    // Existing snapshots/labels.json wins on any conflict
+    const existingDestLabels = fs.existsSync(destLabels) ? fs.readJsonSync(destLabels) : {};
+
+    const merged = { ...legacyLabels, ...htmlLabels, ...existingDestLabels };
+
+    if (Object.keys(merged).length > 0) {
+        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}`
+        Logger.action(
+            `Migrated ${migratedCount} snapshot(s) from ${src} to ${dest}/.`,
+            {
+                hint: `git rm -r --cached ${outputPath}`,
+                context: 'Remove old docs from git tracking'
+            }
         );
     }
 }

package/src/utils/logger.js

@@ -131,6 +131,66 @@ class Logger {
         console.log(); // Extra newline for readability
     }
 
+    /**
+     * Action required messages - red with pointing hand icon
+     * 
+     * Indicates that the user must take action to proceed.
+     * More urgent than a warning, used when user intervention is required.
+     * 
+     * @param {string} message - The main action required message
+     * @param {...any} args - Additional arguments. Can include:
+     *   - Regular values (strings, numbers, objects) for message formatting
+     *   - An options object (if last arg is object with 'hint', 'context', or 'details' keys):
+     *     - hint: Clear instruction on what action to take
+     *     - context: Additional context about why action is needed
+     *     - details: Technical details or related information
+     * 
+     * @example
+     * Logger.action('Configuration required before proceeding', { 
+     *   context: 'specs.json is incomplete',
+     *   hint: 'Add the "title" and "github_url" fields to specs.json',
+     *   details: 'See https://example.com/docs' 
+     * });
+     */
+    static action(message, ...args) {
+        // Extract options object if present (last arg with special keys)
+        const lastArg = args[args.length - 1];
+        const isOptionsObject = lastArg && typeof lastArg === 'object' &&
+            (lastArg.hint || lastArg.context || lastArg.details);
+
+        const options = isOptionsObject ? args.pop() : {};
+        const regularArgs = args;
+
+        // Display main action required message - red to signal urgency
+        console.log(chalk.red('👉'), chalk.red(message), ...regularArgs);
+
+        // Display context if provided - explains why action is needed
+        if (options.context) {
+            console.log(chalk.red('   Context:'), chalk.gray(options.context));
+        }
+
+        // Display technical details if provided - helps understand the situation
+        if (options.details) {
+            const detailsStr = typeof options.details === 'object'
+                ? JSON.stringify(options.details, null, 2)
+                : String(options.details);
+            console.log(chalk.red('   Details:'), chalk.gray(detailsStr));
+        }
+
+        // Display hint if provided - critical instruction on what to do
+        if (options.hint) {
+            console.log(chalk.red('   👉 Action:'), chalk.red(options.hint));
+        }
+
+        // Collect message with all context for healthcheck/JSON output
+        messageCollector.addMessage('action', message, [...regularArgs, options]);
+
+        console.log(); // Extra newline for readability
+    }
+
+    /**
+     * Information messages - blue
+     */
     static info(message, ...args) {
         console.log(chalk.blue('📋'), chalk.blue(message), ...args);
         messageCollector.addMessage('info', message, args);