yakmesh 2.8.2 → 3.0.0

package/scripts/update-docs-nav.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * update-docs-nav.js - Update documentation navigation links
+ * 
+ * Reads docs/nav-order.json and updates prev/next links in all doc pages.
+ * Handles two navigation formats:
+ * 1. Journey Navigation cards (with icons and descriptions)
+ * 2. Simple nav-footer links
+ * 
+ * Usage: node scripts/update-docs-nav.js [--dry-run] [--verbose]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DOCS_DIR = path.join(__dirname, '..', 'docs');
+const NAV_ORDER_FILE = path.join(DOCS_DIR, 'nav-order.json');
+
+// Parse args
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes('--dry-run');
+const VERBOSE = args.includes('--verbose');
+
+function log(...msg) {
+  if (VERBOSE) console.log(...msg);
+}
+
+function loadNavOrder() {
+  const content = fs.readFileSync(NAV_ORDER_FILE, 'utf8');
+  return JSON.parse(content).pages;
+}
+
+/**
+ * Generate Journey Navigation card HTML
+ */
+function generateJourneyCard(page, direction) {
+  if (!page) return '';
+  
+  const borderClass = direction === 'prev' 
+    ? 'border-mountain-700' 
+    : 'border-theme-primary';
+  const label = direction === 'prev' ? '← Previous' : 'Next →';
+  
+  return [
+    '          <a href="' + page.file + '" class="flex-1 block bg-mountain-800 border ' + borderClass + ' rounded-xl p-4 hover:border-theme-accent transition group">',
+    '            <div class="text-xs text-mountain-400 mb-1">' + label + '</div>',
+    '            <div class="flex items-center gap-2">',
+    '              <span class="text-xl">' + page.icon + '</span>',
+    '              <span class="font-semibold group-hover:text-theme-accent">' + page.title + '</span>',
+    '            </div>',
+    '            <p class="text-mountain-400 text-sm mt-1">' + page.description + '</p>',
+    '          </a>'
+  ].join('\n');
+}
+
+/**
+ * Generate Journey Navigation section
+ */
+function generateJourneyNav(prevPage, nextPage) {
+  const cards = [];
+  if (prevPage) cards.push(generateJourneyCard(prevPage, 'prev'));
+  if (nextPage) cards.push(generateJourneyCard(nextPage, 'next'));
+  
+  return [
+    '      <!-- Journey Navigation -->',
+    '      <div class="border-t border-mountain-700 mt-12 pt-8">',
+    '        <h2 class="text-xl font-bold mb-6">Continue the Journey</h2>',
+    '        <div class="flex flex-col sm:flex-row gap-4">',
+    cards.join('\n'),
+    '        </div>',
+    '      </div>'
+  ].join('\n');
+}
+
+/**
+ * Generate simple nav-footer HTML
+ */
+function generateNavFooter(prevPage, nextPage) {
+  const links = [];
+  if (prevPage) {
+    links.push('        <a href="' + prevPage.file + '">← ' + prevPage.title + '</a>');
+  }
+  if (nextPage) {
+    const mlAuto = prevPage ? ' class="ml-auto"' : '';
+    links.push('        <a href="' + nextPage.file + '"' + mlAuto + '>' + nextPage.title + ' →</a>');
+  }
+  
+  return [
+    '      <!-- Navigation -->',
+    '      <nav class="docs-nav-footer">',
+    links.join('\n'),
+    '      </nav>'
+  ].join('\n');
+}
+
+/**
+ * Update navigation in a single file
+ */
+function updateFileNav(filePath, prevPage, nextPage) {
+  let content = fs.readFileSync(filePath, 'utf8');
+  const fileName = path.basename(filePath);
+  let modified = false;
+  
+  // Pattern 1: Journey Navigation cards
+  const journeyPattern = /<!-- Journey Navigation -->.*?<\/div>\s*<\/div>\s*<\/div>/s;
+  if (journeyPattern.test(content)) {
+    const newNav = generateJourneyNav(prevPage, nextPage);
+    content = content.replace(journeyPattern, newNav);
+    modified = true;
+    log('  Updated Journey Navigation in', fileName);
+  }
+  
+  // Pattern 2: Simple nav-footer (if no Journey Navigation)
+  const navFooterPattern = /<!-- Navigation -->\s*<nav class="docs-nav-footer">.*?<\/nav>/s;
+  if (!modified && navFooterPattern.test(content)) {
+    const newNav = generateNavFooter(prevPage, nextPage);
+    content = content.replace(navFooterPattern, newNav);
+    modified = true;
+    log('  Updated nav-footer in', fileName);
+  }
+  
+  // Pattern 3: Alternative Journey Navigation format (closing with </div></div>)
+  const altJourneyPattern = /<div class="border-t border-mountain-700 mt-12 pt-8">\s*<h2 class="text-xl font-bold mb-6">Continue the Journey<\/h2>.*?<\/div>\s*<\/div>/s;
+  if (!modified && altJourneyPattern.test(content)) {
+    const newNav = generateJourneyNav(prevPage, nextPage);
+    content = content.replace(altJourneyPattern, newNav.replace('      <!-- Journey Navigation -->\n', ''));
+    modified = true;
+    log('  Updated alt Journey Navigation in', fileName);
+  }
+  
+  if (modified) {
+    if (!DRY_RUN) {
+      fs.writeFileSync(filePath, content, 'utf8');
+    }
+    return true;
+  }
+  
+  log('  No navigation section found in', fileName);
+  return false;
+}
+
+/**
+ * Main update function
+ */
+function updateAllNavigation() {
+  console.log('📚 Updating documentation navigation links...');
+  if (DRY_RUN) console.log('   (DRY RUN - no files will be modified)');
+  console.log('');
+  
+  const pages = loadNavOrder();
+  console.log('Found', pages.length, 'pages in nav-order.json');
+  console.log('');
+  
+  let updated = 0;
+  let skipped = 0;
+  let notFound = 0;
+  
+  for (let i = 0; i < pages.length; i++) {
+    const current = pages[i];
+    const prev = i > 0 ? pages[i - 1] : null;
+    const next = i < pages.length - 1 ? pages[i + 1] : null;
+    
+    const filePath = path.join(DOCS_DIR, current.file);
+    
+    if (!fs.existsSync(filePath)) {
+      console.log('⚠️  File not found:', current.file);
+      notFound++;
+      continue;
+    }
+    
+    if (updateFileNav(filePath, prev, next)) {
+      console.log('✅', current.file, '→', 
+        prev ? '← ' + prev.file : '(no prev)',
+        next ? '→ ' + next.file : '(no next)');
+      updated++;
+    } else {
+      skipped++;
+    }
+  }
+  
+  console.log('');
+  console.log('Summary:');
+  console.log('  Updated:', updated);
+  console.log('  Skipped:', skipped, '(no nav section)');
+  console.log('  Not found:', notFound);
+  
+  if (DRY_RUN) {
+    console.log('');
+    console.log('Run without --dry-run to apply changes.');
+  }
+}
+
+// Run
+updateAllNavigation();

package/scripts/update-docs-sidebar.cjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * update-docs-sidebar.cjs - Update sidebar navigation in all doc pages
+ * 
+ * Reads docs/nav-order.json and updates the <ul class="sidebar-nav"> section
+ * in all HTML files to match the canonical navigation order.
+ * 
+ * Usage: node scripts/update-docs-sidebar.cjs [--dry-run] [--verbose]
+ * 
+ * This ensures all pages have consistent sidebar navigation without manual updates.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Support both /docs and /website/docs
+const SCRIPTS_DIR = __dirname;
+const ROOT_DIR = path.join(SCRIPTS_DIR, '..');
+const NAV_ORDER_FILE = path.join(ROOT_DIR, 'docs', 'nav-order.json');
+
+// Target directories to scan
+const DOCS_DIRS = [
+  path.join(ROOT_DIR, 'docs'),
+  path.join(ROOT_DIR, 'website', 'docs'),
+  path.join(ROOT_DIR, 'website', 'docs', 'tutorials')
+];
+
+// Parse args
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes('--dry-run');
+const VERBOSE = args.includes('--verbose');
+
+function log(...msg) {
+  if (VERBOSE) console.log(...msg);
+}
+
+function loadNavOrder() {
+  const content = fs.readFileSync(NAV_ORDER_FILE, 'utf8');
+  return JSON.parse(content).pages;
+}
+
+/**
+ * Generate sidebar nav list items from nav-order.json
+ * @param {string} currentFile - The current file name (for "active" class)
+ * @param {string} prefix - Path prefix (e.g., "../" for subdirectory pages)
+ */
+function generateSidebarNavItems(currentFile, prefix = '') {
+  const pages = loadNavOrder();
+  
+  const items = pages.map(page => {
+    const isActive = page.file === currentFile;
+    const activeClass = isActive ? ' class="active"' : '';
+    const href = prefix + page.file;
+    
+    // Icon handling - some use classes like yak-icon
+    let iconHtml;
+    if (page.title === 'YAK://') {
+      iconHtml = '<span class="yak-icon"></span>';
+    } else {
+      iconHtml = `<span>${page.icon}</span>`;
+    }
+    
+    return `      <li><a href="${href}"${activeClass}>${iconHtml} <span>${page.title}</span></a></li>`;
+  });
+  
+  return items.join('\n');
+}
+
+/**
+ * Update sidebar in a single file
+ */
+function updateFileSidebar(filePath) {
+  let content = fs.readFileSync(filePath, 'utf8');
+  const fileName = path.basename(filePath);
+  
+  // Determine prefix for subdirectory pages (tutorials/)
+  const inSubdir = filePath.includes(path.sep + 'tutorials' + path.sep);
+  const prefix = inSubdir ? '../' : '';
+  
+  // Match the sidebar-nav ul section
+  const sidebarPattern = /<ul class="sidebar-nav">\s*(?:<li>.*?<\/li>\s*)+<\/ul>/s;
+  
+  if (!sidebarPattern.test(content)) {
+    log('  No sidebar-nav found in', fileName);
+    return false;
+  }
+  
+  const newNavItems = generateSidebarNavItems(fileName, prefix);
+  const newSidebar = `<ul class="sidebar-nav">\n${newNavItems}\n    </ul>`;
+  
+  const newContent = content.replace(sidebarPattern, newSidebar);
+  
+  if (newContent === content) {
+    log('  No changes needed in', fileName);
+    return false;
+  }
+  
+  if (!DRY_RUN) {
+    fs.writeFileSync(filePath, newContent, 'utf8');
+  }
+  
+  return true;
+}
+
+/**
+ * Get all HTML files in a directory
+ */
+function getHtmlFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.html'))
+    .map(f => path.join(dir, f));
+}
+
+/**
+ * Main update function
+ */
+function updateAllSidebars() {
+  console.log('🧭 Updating documentation sidebars...');
+  if (DRY_RUN) console.log('   (DRY RUN - no files will be modified)');
+  console.log('');
+  
+  const pages = loadNavOrder();
+  console.log(`Loaded ${pages.length} pages from nav-order.json`);
+  console.log('');
+  
+  let updated = 0;
+  let skipped = 0;
+  
+  // Collect all HTML files from all directories
+  const allFiles = [];
+  for (const dir of DOCS_DIRS) {
+    allFiles.push(...getHtmlFiles(dir));
+  }
+  
+  console.log(`Found ${allFiles.length} HTML files to process`);
+  console.log('');
+  
+  for (const filePath of allFiles) {
+    const relativePath = path.relative(ROOT_DIR, filePath);
+    
+    if (updateFileSidebar(filePath)) {
+      console.log('✅', relativePath);
+      updated++;
+    } else {
+      log('⏭️ ', relativePath);
+      skipped++;
+    }
+  }
+  
+  console.log('');
+  console.log('Summary:');
+  console.log('  Updated:', updated);
+  console.log('  Skipped:', skipped);
+  
+  if (DRY_RUN) {
+    console.log('');
+    console.log('Run without --dry-run to apply changes.');
+  }
+}
+
+// Run
+updateAllSidebars();

package/security/crypto-config.js

@@ -276,12 +276,13 @@ export function getBackupSignatureName(level = activeLevel) {
 /**
  * Generate a backup (SLH-DSA) keypair using the current security level
  * Note: SLH-DSA keys are much smaller than ML-DSA, but signatures are larger
+ * @param {Uint8Array} [seed] - Optional seed for deterministic generation
  * @param {number} [level] - Optional security level
  * @returns {Object} { publicKey, secretKey }
  */
-export function generateBackupSignatureKeyPair(level = activeLevel) {
+export function generateBackupSignatureKeyPair(seed = null, level = activeLevel) {
   const algo = CRYPTO_PROFILES[level].backupSignature.algorithm;
-  return algo.keygen();
+  return seed ? algo.keygen(seed) : algo.keygen();
 }
 
 /**
@@ -324,7 +325,7 @@ export function verifyBackup(signature, message, publicKey, level = activeLevel)
 export function generateDualSignatureKeyPairs(seed, level = activeLevel) {
   return {
     primary: generateSignatureKeyPair(seed, level),
-    backup: generateBackupSignatureKeyPair(level),
+    backup: generateBackupSignatureKeyPair(null, level),
   };
 }