@kenjura/ursa 0.75.0 → 0.77.0

package/src/helper/build/templates.js

@@ -1,30 +1,187 @@
 // Template helpers for build
-import { readFile } from "fs/promises";
-import { parse } from "path";
-import { recurse } from "../recursive-readdir.js";
+import { readFile, readdir } from "fs/promises";
+import { join, basename } from "path";
+import { existsSync } from "fs";
 
 /**
  * Get all templates from meta directory
+ * Templates are now organized in meta/templates/{templateName}/index.html
+ * Falls back to legacy flat structure if templates folder doesn't exist
  * @param {string} meta - Full path to meta files directory
- * @returns {Promise<Object>} Map of templateName to templateBody
+ * @returns {Promise<Object>} Map of templateName to { html, dir }
  */
 export async function getTemplates(meta) {
-  const allMetaFilenames = await recurse(meta);
-  const allHtmlFilenames = allMetaFilenames.filter((filename) =>
-    filename.match(/\.html/)
-  );
-
+  const templatesDir = join(meta, "templates");
   let templates = {};
-  const templatesArray = await Promise.all(
-    allHtmlFilenames.map(async (filename) => {
-      const { name } = parse(filename);
-      const fileContent = await readFile(filename, "utf8");
-      return [name, fileContent];
-    })
-  );
-  templatesArray.forEach(
-    ([templateName, templateText]) => (templates[templateName] = templateText)
-  );
+
+  // Check if new templates folder structure exists
+  if (existsSync(templatesDir)) {
+    const entries = await readdir(templatesDir, { withFileTypes: true });
+    const templateFolders = entries.filter(e => e.isDirectory());
+
+    const templatesArray = await Promise.all(
+      templateFolders.map(async (folder) => {
+        const templateName = folder.name;
+        const templateDir = join(templatesDir, templateName);
+        const indexPath = join(templateDir, "index.html");
+
+        if (existsSync(indexPath)) {
+          const fileContent = await readFile(indexPath, "utf8");
+          return [templateName, { html: fileContent, dir: templateDir }];
+        }
+        return null;
+      })
+    );
+
+    templatesArray
+      .filter(Boolean)
+      .forEach(([name, data]) => (templates[name] = data));
+  }
+
+  // Legacy fallback: check for *-template.html files in meta root
+  // This allows backward compatibility during migration
+  if (Object.keys(templates).length === 0) {
+    const { recurse } = await import("../recursive-readdir.js");
+    const allMetaFilenames = await recurse(meta);
+    const legacyTemplates = allMetaFilenames.filter((filename) =>
+      filename.match(/-template\.html$/)
+    );
+
+    const templatesArray = await Promise.all(
+      legacyTemplates.map(async (filename) => {
+        const name = basename(filename).replace("-template.html", "");
+        const fileContent = await readFile(filename, "utf8");
+        // For legacy templates, the dir is the meta folder itself
+        return [name, { html: fileContent, dir: meta }];
+      })
+    );
+    templatesArray.forEach(
+      ([templateName, data]) => (templates[templateName] = data)
+    );
+  }
 
   return templates;
 }
+
+/**
+ * Get template HTML content (backward compatible)
+ * @param {Object} templates - Templates map from getTemplates()
+ * @param {string} name - Template name
+ * @returns {string|null} Template HTML or null
+ */
+export function getTemplateHtml(templates, name) {
+  const template = templates[name];
+  if (!template) return null;
+  // Support both new { html, dir } format and legacy string format
+  return typeof template === 'string' ? template : template.html;
+}
+
+/**
+ * Get template directory (for resolving assets)
+ * @param {Object} templates - Templates map from getTemplates()
+ * @param {string} name - Template name
+ * @returns {string|null} Template directory path or null
+ */
+export function getTemplateDir(templates, name) {
+  const template = templates[name];
+  if (!template) return null;
+  return typeof template === 'string' ? null : template.dir;
+}
+
+/**
+ * Copy meta assets to output/public directory.
+ * Handles the new template folder structure:
+ * - meta/shared/* → output/public/*
+ * - meta/templates/{name}/* (except index.html) → output/public/*
+ * 
+ * Also handles legacy flat structure for backward compatibility.
+ * 
+ * @param {string} metaDir - Path to meta directory
+ * @param {string} outputPublicDir - Path to output/public directory
+ * @returns {Promise<{ copiedFiles: string[], orphanedFiles: string[] }>}
+ */
+export async function copyMetaAssets(metaDir, outputPublicDir) {
+  const { copy } = await import('fs-extra');
+  const { readdir, stat } = await import('fs/promises');
+  const { relative } = await import('path');
+  
+  const copiedFiles = [];
+  const orphanedFiles = [];
+  const templatesDir = join(metaDir, 'templates');
+  const sharedDir = join(metaDir, 'shared');
+  
+  // Helper to copy a file
+  const copyFile = async (src, dest) => {
+    await copy(src, dest, { overwrite: true });
+    copiedFiles.push(relative(metaDir, src));
+  };
+  
+  // Helper to recursively copy directory contents (not the directory itself)
+  const copyDirContents = async (srcDir, destDir, excludeFiles = []) => {
+    if (!existsSync(srcDir)) return;
+    
+    const entries = await readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue; // Skip hidden files
+      if (excludeFiles.includes(entry.name)) continue;
+      
+      const srcPath = join(srcDir, entry.name);
+      const destPath = join(destDir, entry.name);
+      
+      if (entry.isDirectory()) {
+        await copyDirContents(srcPath, destPath, excludeFiles);
+      } else {
+        await copyFile(srcPath, destPath);
+      }
+    }
+  };
+  
+  // Check if new structure exists
+  if (existsSync(templatesDir)) {
+    // Copy shared assets
+    await copyDirContents(sharedDir, outputPublicDir);
+    
+    // Copy each template's assets (except index.html)
+    const templateFolders = await readdir(templatesDir, { withFileTypes: true });
+    for (const folder of templateFolders) {
+      if (!folder.isDirectory()) continue;
+      const templateDir = join(templatesDir, folder.name);
+      await copyDirContents(templateDir, outputPublicDir, ['index.html']);
+    }
+    
+    // Check for orphaned files in meta root (excluding templates and shared folders)
+    const rootEntries = await readdir(metaDir, { withFileTypes: true });
+    for (const entry of rootEntries) {
+      if (entry.name.startsWith('.')) continue;
+      if (entry.name === 'templates' || entry.name === 'shared') continue;
+      
+      // This is an orphaned file/folder in meta root
+      const fullPath = join(metaDir, entry.name);
+      if (entry.isDirectory()) {
+        // Recursively find all orphaned files
+        const findOrphans = async (dir) => {
+          const entries = await readdir(dir, { withFileTypes: true });
+          for (const e of entries) {
+            if (e.name.startsWith('.')) continue;
+            const p = join(dir, e.name);
+            if (e.isDirectory()) {
+              await findOrphans(p);
+            } else {
+              orphanedFiles.push(relative(metaDir, p));
+            }
+          }
+        };
+        await findOrphans(fullPath);
+      } else {
+        orphanedFiles.push(entry.name);
+      }
+    }
+  } else {
+    // Legacy: copy entire meta folder to public (old behavior)
+    await copy(metaDir, outputPublicDir, {
+      filter: (src) => !basename(src).startsWith('.') && !src.endsWith('.html')
+    });
+  }
+  
+  return { copiedFiles, orphanedFiles };
+}

package/src/helper/build/watchCache.js

@@ -1,5 +1,7 @@
 // Watch mode cache and clear function for build
 
+import { dependencyTracker } from "../dependencyTracker.js";
+
 export const watchModeCache = {
   templates: null,
   menu: null,
@@ -10,6 +12,8 @@ export const watchModeCache = {
   output: null,
   hashCache: null,
   cacheBustTimestamp: null,
+  cacheBustHashes: null,   // CacheBustHashMap instance for per-file cache-busting
+  allArticlePaths: null,   // Array of all article paths (for full rebuild tracking)
   lastFullBuild: 0,
   isInitialized: false,
 };
@@ -20,7 +24,10 @@ export function clearWatchCache(cssPathCache) {
   watchModeCache.footer = null;
   watchModeCache.validPaths = null;
   watchModeCache.hashCache = null;
+  watchModeCache.cacheBustHashes = null;
+  watchModeCache.allArticlePaths = null;
   watchModeCache.isInitialized = false;
+  dependencyTracker.init("");
   if (cssPathCache) cssPathCache.clear();
   console.log('Watch cache cleared');
 }

package/src/helper/customMenu.js

@@ -267,11 +267,13 @@ export function autoGenerateMenuFromFolder(folderPath, sourceRoot, depth = 10, i
     const topLevelFolders = processedItems.filter(item => item.hasChildren);
     const topLevelFiles = processedItems.filter(item => !item.hasChildren);
     
-    const relativePath = '/' + relative(sourceRoot, folderPath).replace(/\\/g, '/');
+    const relPath = relative(sourceRoot, folderPath).replace(/\\/g, '/');
+    // Avoid double slash: if relPath is empty (root), href is '/index.html', otherwise '/relPath/index.html'
+    const homeHref = relPath ? `/${relPath}/index.html` : '/index.html';
     const homeItem = {
       label: 'Home',
       path: 'home',
-      href: relativePath + '/index.html',
+      href: homeHref,
       hasChildren: topLevelFiles.length > 0,
       icon: `<span class="menu-icon">${HOME_ICON}</span>`,
       children: topLevelFiles,

package/src/helper/dependencyTracker.js

@@ -0,0 +1,269 @@
+/**
+ * Dependency tracker for Ursa's regeneration system.
+ *
+ * Tracks which documents depend on which files so that when a file changes,
+ * we can determine exactly which documents need regeneration.
+ *
+ * Dependency types:
+ * - template: document uses a specific meta template
+ * - style: document inherits a specific style.css
+ * - script: document inherits a specific script.js
+ * - static: document references a static asset (image, font, etc.)
+ * - meta-asset: document depends on a meta CSS/JS file (via template bundling)
+ *
+ * The tracker maintains two indexes:
+ * 1. fileToDocuments: Map<dependencyPath, Set<documentPath>> — given a changed file, which documents need regeneration?
+ * 2. documentToFiles: Map<documentPath, Set<dependencyPath>> — given a document, what are its dependencies? (for cleanup)
+ */
+
+import { dirname, join, relative, resolve } from "path";
+
+export class DependencyTracker {
+  constructor() {
+    /** @type {Map<string, Set<string>>} dependency file path → set of document paths */
+    this.fileToDocuments = new Map();
+    /** @type {Map<string, Set<string>>} document path → set of dependency file paths */
+    this.documentToFiles = new Map();
+    /** @type {string} source directory root (absolute, with trailing slash) */
+    this.sourceDir = "";
+  }
+
+  /**
+   * Initialize with the source directory.
+   * @param {string} sourceDir - Absolute path to source directory (with or without trailing slash)
+   */
+  init(sourceDir) {
+    this.sourceDir = resolve(sourceDir) + "/";
+    this.fileToDocuments.clear();
+    this.documentToFiles.clear();
+  }
+
+  /**
+   * Register that a document depends on a file.
+   * @param {string} documentPath - Absolute path to the document
+   * @param {string} dependencyPath - Absolute path to the dependency file
+   */
+  addDependency(documentPath, dependencyPath) {
+    // file → documents
+    if (!this.fileToDocuments.has(dependencyPath)) {
+      this.fileToDocuments.set(dependencyPath, new Set());
+    }
+    this.fileToDocuments.get(dependencyPath).add(documentPath);
+
+    // document → files
+    if (!this.documentToFiles.has(documentPath)) {
+      this.documentToFiles.set(documentPath, new Set());
+    }
+    this.documentToFiles.get(documentPath).add(dependencyPath);
+  }
+
+  /**
+   * Register dependencies for a document: template, style.css files, script.js files.
+   * @param {string} documentPath - Absolute path to the document
+   * @param {{ templateName: string, cssPaths: string[], scriptPaths: string[], metaAssets: string[] }} deps
+   */
+  registerDocument(documentPath, { templateName, cssPaths = [], scriptPaths = [], metaAssets = [] } = {}) {
+    // Clear old dependencies for this document
+    this.clearDocument(documentPath);
+
+    // Template dependency (use a virtual path so template changes can be looked up)
+    if (templateName) {
+      this.addDependency(documentPath, `template:${templateName}`);
+    }
+
+    // Style.css dependencies
+    for (const cssPath of cssPaths) {
+      this.addDependency(documentPath, cssPath);
+    }
+
+    // Script.js dependencies
+    for (const scriptPath of scriptPaths) {
+      this.addDependency(documentPath, scriptPath);
+    }
+
+    // Meta template assets (CSS/JS referenced by the template)
+    for (const metaAsset of metaAssets) {
+      this.addDependency(documentPath, metaAsset);
+    }
+  }
+
+  /**
+   * Clear all dependencies for a document.
+   * @param {string} documentPath
+   */
+  clearDocument(documentPath) {
+    const deps = this.documentToFiles.get(documentPath);
+    if (deps) {
+      for (const dep of deps) {
+        const docSet = this.fileToDocuments.get(dep);
+        if (docSet) {
+          docSet.delete(documentPath);
+          if (docSet.size === 0) this.fileToDocuments.delete(dep);
+        }
+      }
+      this.documentToFiles.delete(documentPath);
+    }
+  }
+
+  /**
+   * Get all documents that depend on a given file.
+   * @param {string} filePath - Absolute path to the changed file
+   * @returns {Set<string>} Set of document paths that need regeneration
+   */
+  getAffectedDocuments(filePath) {
+    return this.fileToDocuments.get(filePath) || new Set();
+  }
+
+  /**
+   * Get all documents that use a specific template.
+   * @param {string} templateName - Template name (e.g., "default-template")
+   * @returns {Set<string>} Set of document paths
+   */
+  getDocumentsUsingTemplate(templateName) {
+    return this.getAffectedDocuments(`template:${templateName}`);
+  }
+
+  /**
+   * Determine which documents are affected by a changed file.
+   * This is the main entry point for the invalidation logic.
+   *
+   * @param {string} changedFile - Absolute path to the changed file
+   * @param {string} sourceDir - Absolute path to source directory
+   * @returns {{ affectedDocuments: string[], reason: string, requiresFullRebuild: boolean }}
+   */
+  getInvalidationPlan(changedFile, sourceDir) {
+    const normalizedSource = resolve(sourceDir) + "/";
+    const relativePath = changedFile.replace(normalizedSource, "");
+    const fileName = relativePath.split("/").pop();
+
+    // 1. Menu/config changes → full rebuild (affects navigation structure)
+    if (
+      fileName === "menu.md" || fileName === "menu.txt" || fileName === "_menu" ||
+      fileName === "config.json" || fileName === "_config"
+    ) {
+      return {
+        affectedDocuments: [],
+        reason: `Menu/config change: ${relativePath}`,
+        requiresFullRebuild: true,
+      };
+    }
+
+    // 2. style.css or script.js → affects current folder + all subfolders
+    //    These are "inherited" files — documents in the folder and all subfolders include them.
+    if (
+      fileName === "style.css" || fileName === "_style.css" || fileName === "style-ursa.css" ||
+      fileName === "script.js" || fileName === "_script.js"
+    ) {
+      // Get all documents directly registered as depending on this file
+      const directDeps = this.getAffectedDocuments(changedFile);
+
+      if (directDeps.size > 0) {
+        return {
+          affectedDocuments: [...directDeps],
+          reason: `Inherited ${fileName} changed: ${relativePath} (${directDeps.size} documents)`,
+          requiresFullRebuild: false,
+        };
+      }
+
+      // Fallback: if dependency tracker wasn't populated, scope by directory
+      const changedDir = dirname(changedFile);
+      const allDocs = [...this.documentToFiles.keys()];
+      const affected = allDocs.filter((doc) => doc.startsWith(changedDir));
+      return {
+        affectedDocuments: affected,
+        reason: `Inherited ${fileName} changed: ${relativePath} (${affected.length} documents in subtree, fallback)`,
+        requiresFullRebuild: false,
+      };
+    }
+
+    // 3. Article file changes → just that document
+    if (/\.(md|mdx|txt|yml|yaml)$/.test(fileName)) {
+      return {
+        affectedDocuments: [changedFile],
+        reason: `Article changed: ${relativePath}`,
+        requiresFullRebuild: false,
+      };
+    }
+
+    // 4. Other static files (images, fonts, etc.) → find documents that reference them
+    const directDeps = this.getAffectedDocuments(changedFile);
+    if (directDeps.size > 0) {
+      return {
+        affectedDocuments: [...directDeps],
+        reason: `Static asset changed: ${relativePath} (${directDeps.size} referencing documents)`,
+        requiresFullRebuild: false,
+      };
+    }
+
+    // If we don't track this file, it's safe to just broadcast reload (dev mode only)
+    return {
+      affectedDocuments: [],
+      reason: `Unknown file changed: ${relativePath} (no registered dependents)`,
+      requiresFullRebuild: false,
+    };
+  }
+
+  /**
+   * Determine which documents are affected by a meta file change.
+   * @param {string} changedFile - Absolute path to the changed meta file
+   * @param {string} metaDir - Absolute path to meta directory
+   * @returns {{ affectedDocuments: string[], reason: string, requiresFullRebuild: boolean }}
+   */
+  getMetaInvalidationPlan(changedFile, metaDir) {
+    const normalizedMeta = resolve(metaDir) + "/";
+    const relativePath = changedFile.replace(normalizedMeta, "");
+    const fileName = relativePath.split("/").pop();
+
+    // Template file changed → regenerate all documents using that template
+    if (fileName.endsWith(".html")) {
+      const templateName = fileName.replace(".html", "");
+      const affected = this.getDocumentsUsingTemplate(templateName);
+      if (affected.size > 0) {
+        return {
+          affectedDocuments: [...affected],
+          reason: `Template changed: ${templateName} (${affected.size} documents)`,
+          requiresFullRebuild: false,
+        };
+      }
+      // If no documents tracked, fall back to full rebuild (safe default)
+      return {
+        affectedDocuments: [],
+        reason: `Template changed: ${templateName} (no tracked documents, full rebuild)`,
+        requiresFullRebuild: true,
+      };
+    }
+
+    // Meta CSS or JS file changed → all documents are affected
+    // (meta assets are bundled into every template)
+    if (fileName.endsWith(".css") || fileName.endsWith(".js")) {
+      const allDocs = [...this.documentToFiles.keys()];
+      return {
+        affectedDocuments: allDocs,
+        reason: `Meta asset changed: ${relativePath} (affects all ${allDocs.length} documents)`,
+        requiresFullRebuild: false,
+      };
+    }
+
+    // Other meta file → full rebuild to be safe
+    return {
+      affectedDocuments: [],
+      reason: `Meta file changed: ${relativePath}`,
+      requiresFullRebuild: true,
+    };
+  }
+
+  /**
+   * Get stats about the dependency graph.
+   * @returns {{ totalDocuments: number, totalDependencies: number, uniqueFiles: number }}
+   */
+  getStats() {
+    return {
+      totalDocuments: this.documentToFiles.size,
+      totalDependencies: [...this.documentToFiles.values()].reduce((sum, s) => sum + s.size, 0),
+      uniqueFiles: this.fileToDocuments.size,
+    };
+  }
+}
+
+// Singleton instance
+export const dependencyTracker = new DependencyTracker();

package/src/helper/findScriptJs.js

@@ -24,3 +24,32 @@ export async function findScriptJs(startDir, names = ["script.js", "_script.js"]
   }
   return null;
 }
+
+/**
+ * Find ALL script.js or _script.js files from the docroot down to startDir.
+ * Walks up from startDir to docroot collecting all matches, then returns them
+ * sorted from shortest path (closest to docroot) to longest (closest to startDir).
+ * @param {string} startDir - Directory to start searching from (deepest)
+ * @param {string} docroot - The root directory to stop at (shallowest)
+ * @param {string[]} [names=["script.js", "_script.js"]] - Filenames to look for
+ * @returns {Promise<string[]>} Array of script file paths, ordered from shallowest to deepest
+ */
+export async function findAllScriptJs(startDir, docroot, names = ["script.js", "_script.js"]) {
+  const found = [];
+  let dir = resolve(startDir);
+  const base = resolve(docroot);
+  while (true) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) {
+        found.push(candidate);
+        break; // Only one match per directory (prefer script.js over _script.js)
+      }
+    }
+    if (dir === base || dir === dirname(dir)) break;
+    dir = dirname(dir);
+  }
+  // Sort from shortest path (docroot) to longest (startDir)
+  found.sort((a, b) => a.length - b.length);
+  return found;
+}

package/src/helper/findStyleCss.js

@@ -24,3 +24,32 @@ export async function findStyleCss(startDir, names = ["style-ursa.css", "style.c
   }
   return null;
 }
+
+/**
+ * Find ALL style.css or _style.css files from the docroot down to startDir.
+ * Walks up from startDir to docroot collecting all matches, then returns them
+ * sorted from shortest path (closest to docroot) to longest (closest to startDir).
+ * @param {string} startDir - Directory to start searching from (deepest)
+ * @param {string} docroot - The root directory to stop at (shallowest)
+ * @param {string[]} [names=["style-ursa.css", "style.css", "_style.css"]] - Filenames to look for
+ * @returns {Promise<string[]>} Array of CSS file paths, ordered from shallowest to deepest
+ */
+export async function findAllStyleCss(startDir, docroot, names = ["style-ursa.css", "style.css", "_style.css"]) {
+  const found = [];
+  let dir = resolve(startDir);
+  const base = resolve(docroot);
+  while (true) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) {
+        found.push(candidate);
+        break; // Only one match per directory (prefer style-ursa.css > style.css > _style.css)
+      }
+    }
+    if (dir === base || dir === dirname(dir)) break;
+    dir = dirname(dir);
+  }
+  // Sort from shortest path (docroot) to longest (startDir)
+  found.sort((a, b) => a.length - b.length);
+  return found;
+}