@kenjura/ursa 0.86.0 → 0.88.0

package/src/helper/dependencyTracker.js

@@ -17,6 +17,16 @@
  */
 
 import { dirname, join, relative, resolve } from "path";
+import { existsSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { getUrsaDir } from "./contentHash.js";
+
+const DEP_GRAPH_FILE = "dependency-graph.json";
+const DEP_GRAPH_VERSION = 1;
+
+// Static assets in meta (copied verbatim to output/public by copyMetaAssets);
+// these are never embedded in document HTML, so no regeneration is needed.
+const META_STATIC_EXTENSIONS = /\.(jpg|jpeg|png|gif|webp|svg|ico|woff|woff2|ttf|eot|pdf|mp3|mp4|webm|ogg)$/i;
 
 export class DependencyTracker {
   constructor() {
@@ -216,7 +226,13 @@ export class DependencyTracker {
 
     // Template file changed → regenerate all documents using that template
     if (fileName.endsWith(".html")) {
-      const templateName = fileName.replace(".html", "");
+      // New structure: templates/{templateName}/index.html → name is the folder;
+      // legacy flat structure: {templateName}.html at the meta root
+      const parts = relativePath.split("/");
+      const templateName =
+        parts[0] === "templates" && parts.length >= 3
+          ? parts[1]
+          : fileName.replace(".html", "");
       const affected = this.getDocumentsUsingTemplate(templateName);
       if (affected.size > 0) {
         return {
@@ -244,6 +260,17 @@ export class DependencyTracker {
       };
     }
 
+    // Static asset in meta (image, font, PDF, media) → copyMetaAssets already
+    // re-copied it to output/public; documents reference it by URL, so no
+    // document regeneration (and no full rebuild) is needed.
+    if (META_STATIC_EXTENSIONS.test(fileName)) {
+      return {
+        affectedDocuments: [],
+        reason: `Meta static asset copied: ${relativePath}`,
+        requiresFullRebuild: false,
+      };
+    }
+
     // Other meta file → full rebuild to be safe
     return {
       affectedDocuments: [],
@@ -263,7 +290,95 @@ export class DependencyTracker {
       uniqueFiles: this.fileToDocuments.size,
     };
   }
+
+  /**
+   * Serialize the tracker for persistence to .ursa/dependency-graph.json.
+   * @returns {{ version: number, sourceDir: string, documents: Object<string, string[]> }}
+   */
+  serialize() {
+    return {
+      version: DEP_GRAPH_VERSION,
+      sourceDir: this.sourceDir,
+      documents: Object.fromEntries(
+        [...this.documentToFiles.entries()].map(([doc, deps]) => [doc, [...deps]])
+      ),
+    };
+  }
+
+  /**
+   * Load persisted registrations, merging with the current run: documents
+   * already registered in this run keep their (fresher) edges; persisted
+   * edges only fill in documents not yet registered (e.g. hash-skipped docs).
+   * Rejects data from a different source directory or schema version.
+   * @param {object} data - Previously serialized tracker
+   * @returns {boolean} Whether the data was loaded
+   */
+  load(data) {
+    if (!data || data.version !== DEP_GRAPH_VERSION) return false;
+    if (data.sourceDir && this.sourceDir && data.sourceDir !== this.sourceDir) return false;
+    for (const [doc, deps] of Object.entries(data.documents || {})) {
+      if (this.documentToFiles.has(doc)) continue; // live registrations win
+      if (!Array.isArray(deps)) continue;
+      for (const dep of deps) {
+        this.addDependency(doc, dep);
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Drop registrations for documents not in the given set (e.g. deleted or
+   * excluded files), so persisted state doesn't accumulate stale entries.
+   * @param {Set<string>} keepDocuments - Document paths that should survive
+   */
+  prune(keepDocuments) {
+    for (const doc of [...this.documentToFiles.keys()]) {
+      if (!keepDocuments.has(doc)) this.clearDocument(doc);
+    }
+  }
 }
 
 // Singleton instance
 export const dependencyTracker = new DependencyTracker();
+
+/** Path to the persisted dependency graph for a source directory. */
+export function getDependencyGraphPath(sourceDir) {
+  return join(getUrsaDir(sourceDir), DEP_GRAPH_FILE);
+}
+
+/**
+ * Load the persisted dependency tracker state from .ursa/dependency-graph.json
+ * and merge it into the tracker (current-run registrations win).
+ * @param {string} sourceDir - Source directory root
+ * @param {DependencyTracker} [tracker] - Defaults to the singleton
+ * @returns {Promise<boolean>} Whether a valid graph was loaded
+ */
+export async function loadDependencyTracker(sourceDir, tracker = dependencyTracker) {
+  const path = getDependencyGraphPath(sourceDir);
+  try {
+    if (!existsSync(path)) return false;
+    const data = JSON.parse(await readFile(path, "utf8"));
+    return tracker.load(data);
+  } catch (e) {
+    console.warn(`Could not load dependency graph: ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * Persist the dependency tracker to .ursa/dependency-graph.json so that
+ * hash-skipped documents keep their edges across warm starts.
+ * @param {string} sourceDir - Source directory root
+ * @param {DependencyTracker} [tracker] - Defaults to the singleton
+ * @returns {Promise<boolean>} Whether the graph was saved
+ */
+export async function saveDependencyTracker(sourceDir, tracker = dependencyTracker) {
+  try {
+    await mkdir(getUrsaDir(sourceDir), { recursive: true });
+    await writeFile(getDependencyGraphPath(sourceDir), JSON.stringify(tracker.serialize()));
+    return true;
+  } catch (e) {
+    console.warn(`Could not save dependency graph: ${e.message}`);
+    return false;
+  }
+}

package/src/helper/hiddenPaths.js

@@ -0,0 +1,62 @@
+import { resolve } from "path";
+
+/**
+ * Hidden / system folder detection.
+ *
+ * The pattern matches a path segment that starts with a dot (but not `..`),
+ * `node_modules`, or `_templates`. A leading separator is required, which is
+ * why {@link toSourceRelative} always returns a path that begins with one.
+ */
+export const HIDDEN_OR_SYSTEM_DIRS =
+  /[\/\\]\.(?!\.)|[\/\\]node_modules[\/\\]|[\/\\]_templates[\/\\]|[\/\\]_templates$/;
+
+/** The dev server's narrower pattern — no `_templates`, which it does not process. */
+export const HIDDEN_OR_SYSTEM_DIRS_DEV = /[\/\\]\.(?!\.)|[\/\\]node_modules[\/\\]/;
+
+/**
+ * A file's path relative to the site source root, always separator-prefixed.
+ *
+ * **This is the whole point of this module.** These patterns must be tested
+ * against the path *relative to `source`*, never against the absolute path. A
+ * docroot that happens to live under a dot-directory — `~/.config/site`, a git
+ * worktree under `.claude/worktrees/…`, anything inside `.local` — is not a
+ * site full of hidden folders, but an absolute-path test reads it as one and
+ * classifies **every** article as hidden. The failure is silent and
+ * particularly nasty: generation reports success, and writes a site with zero
+ * pages, so the first symptom is an empty deploy.
+ *
+ * The separator prefix preserves detection of a genuinely hidden folder at the
+ * top of the docroot (`<source>/.drafts/x.md` → `/.drafts/x.md`, still a match).
+ *
+ * @param {string} filePath - Absolute path to a file or directory
+ * @param {string} source - Absolute path of the source root (trailing slash optional)
+ * @returns {string} The relative path, beginning with `/`
+ */
+export function toSourceRelative(filePath, source) {
+  if (!source) return filePath;
+
+  // Normalize both sides so a trailing slash on either cannot change the result.
+  const root = resolve(source);
+  const full = resolve(filePath);
+
+  if (full === root) return "/";
+  if (!full.startsWith(root)) return full; // outside the docroot; test it as-is
+
+  const rel = full.slice(root.length);
+  return rel.startsWith("/") || rel.startsWith("\\") ? rel : `/${rel}`;
+}
+
+/**
+ * True when a path lies inside a hidden or system folder *within the docroot*.
+ *
+ * @param {string} filePath - Absolute path to a file or directory
+ * @param {string} source - Absolute path of the source root
+ * @param {RegExp} [pattern] - Defaults to {@link HIDDEN_OR_SYSTEM_DIRS}
+ */
+export function isHiddenOrSystemPath(
+  filePath,
+  source,
+  pattern = HIDDEN_OR_SYSTEM_DIRS
+) {
+  return pattern.test(toSourceRelative(filePath, source));
+}

package/src/helper/portUtils.js

@@ -47,6 +47,35 @@ export async function findClosestAvailablePort(preferred, maxDistance = 100) {
   return null;
 }
 
+/**
+ * Find the closest port P such that both P (HTTP) and P+1 (WebSocket) are
+ * available. Searches both upward and downward from the preferred port.
+ * @param {number} preferred - The preferred port number
+ * @param {number} [maxDistance=100] - Maximum distance to search from preferred port
+ * @returns {Promise<number|null>} The closest available port pair base, or null if none found
+ */
+export async function findClosestAvailablePortPair(preferred, maxDistance = 100) {
+  for (let offset = 1; offset <= maxDistance; offset++) {
+    const candidates = [];
+    if (preferred + offset <= 65534) candidates.push(preferred + offset);
+    if (preferred - offset >= 1024) candidates.push(preferred - offset);
+
+    // Check both candidates (up and down) in parallel
+    const results = await Promise.all(
+      candidates.map(async (port) => ({
+        port,
+        available: (await isPortAvailable(port)) && (await isPortAvailable(port + 1)),
+      }))
+    );
+
+    // Return the first available candidate (lower offset = closer)
+    // Since we push +offset first, it's preferred over -offset at the same distance
+    const found = results.find((r) => r.available);
+    if (found) return found.port;
+  }
+  return null;
+}
+
 /**
  * Prompt the user via stdin to confirm using an alternative port.
  * @param {number} originalPort
@@ -77,11 +106,30 @@ function promptUser(originalPort, alternativePort) {
  *
  * Also checks wsPort (port + 1) availability since the WebSocket server needs it.
  *
+ * ## Why `strict` and the TTY check exist
+ *
+ * `ursa serve` is increasingly run as one process among several — a `pnpm dev`
+ * that starts an app, an API and this wiki in parallel. Two things go wrong
+ * there that do not go wrong at an interactive terminal:
+ *
+ * 1. **The prompt has nobody to answer it.** Sibling processes share stdin, so
+ *    the question either hangs the whole dev command or eats a keystroke meant
+ *    for another process. Hence: never prompt when stdin is not a TTY.
+ * 2. **A different port is not automatically a good outcome.** Whatever embeds
+ *    the wiki — an iframe, a proxy, a link — was configured with the port that
+ *    was asked for. Silently serving on another one produces a broken embed
+ *    with no error anywhere. Hence `strict`: fail loudly instead.
+ *
  * @param {number} port - The desired port
- * @returns {Promise<number>} The port to use (original or user-accepted alternative)
- * @throws {Error} If no available port is found or user declines the alternative
+ * @param {object} [options]
+ * @param {boolean} [options.strict=false] - Fail rather than use another port
+ * @param {boolean} [options.interactive] - Defaults to whether stdin is a TTY
+ * @returns {Promise<number>} The port to use
+ * @throws {Error} If no port is available, or `strict` and the port is taken
  */
-export async function resolvePort(port) {
+export async function resolvePort(port, options = {}) {
+  const { strict = false, interactive = Boolean(process.stdin.isTTY) } = options;
+
   const httpAvailable = await isPortAvailable(port);
   const wsAvailable = await isPortAvailable(port + 1);
 
@@ -91,35 +139,36 @@ export async function resolvePort(port) {
 
   const reason = !httpAvailable
     ? `Port ${port} is already in use`
-    : `WebSocket port ${port + 1} is already in use`;
+    : `WebSocket port ${port + 1} is already in use (ursa serves hot-reload there)`;
+
+  if (strict) {
+    throw new Error(
+      `${reason}. Refusing to use a different port because --strict-port was ` +
+        `given. Free the port, or pass --port <n> to choose another deliberately.`
+    );
+  }
 
   console.log(`\n⚠️  ${reason}.`);
   console.log(`🔍 Searching for an available port...`);
 
-  const alternative = await findClosestAvailablePort(port);
+  // The alternative must have both its HTTP port and its WebSocket port (port + 1) free
+  const alternative = await findClosestAvailablePortPair(port);
 
   if (!alternative) {
     throw new Error(
-      `Could not find an available port near ${port}. Please free up a port and try again.`
+      `Could not find an available port pair (HTTP + WebSocket) near ${port}. Please free up a port and try again.`
     );
   }
 
-  // Also verify the ws port for the alternative
-  const altWsAvailable = await isPortAvailable(alternative + 1);
-  if (!altWsAvailable) {
-    // Try again, skipping this one
-    const secondTry = await findClosestAvailablePort(alternative + 1);
-    if (!secondTry) {
-      throw new Error(
-        `Could not find an available port pair (HTTP + WebSocket) near ${port}.`
-      );
-    }
-    const accepted = await promptUser(port, secondTry);
-    if (!accepted) {
-      console.log('👋 Server startup cancelled.');
-      process.exit(0);
-    }
-    return secondTry;
+  if (!interactive) {
+    // Nobody can answer the prompt; asking would hang. Be loud instead, since
+    // anything pointed at the original port is now pointed at nothing.
+    console.log(
+      `⚠️  stdin is not a TTY, so using port ${alternative} without asking.\n` +
+        `   Anything configured for port ${port} must be updated, or pass ` +
+        `--strict-port to fail instead.`
+    );
+    return alternative;
   }
 
   const accepted = await promptUser(port, alternative);