npm - @kenjura/ursa - Versions diffs - 0.87.1 → 0.89.1 - Mend

@kenjura/ursa 0.87.1 → 0.89.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/CHANGELOG.md +796 -737
package/bin/ursa.js +7 -1
package/meta/templates/default-template/index.html +1 -0
package/package.json +1 -1
package/src/dev.js +8 -4
package/src/helper/__test__/hiddenPaths.test.js +106 -0
package/src/helper/__test__/portUtils.test.js +100 -0
package/src/helper/__test__/staticAssets.test.js +47 -0
package/src/helper/automenu.js +43 -3
package/src/helper/build/autoIndex.js +10 -5
package/src/helper/contentHash.js +19 -0
package/src/helper/hiddenPaths.js +62 -0
package/src/helper/portUtils.js +71 -22
package/src/helper/staticAssets.js +31 -0
package/src/jobs/generate.js +1771 -1714
package/src/serve.js +907 -906

package/bin/ursa.js CHANGED Viewed

@@ -123,6 +123,11 @@ yargs(hideBin(process.argv))
           describe: 'Port to serve on',
           type: 'number'
         })
+        .option('strict-port', {
+          describe: 'Fail if the port is taken instead of falling back to another',
+          type: 'boolean',
+          default: false
+        })
         .option('whitelist', {
           alias: 'w',
           describe: 'Path to whitelist file containing patterns for files to include',
@@ -177,7 +182,8 @@ yargs(hideBin(process.argv))
           port: port,
           _whitelist: whitelist,
           _exclude: exclude,
-          _clean: clean
+          _clean: clean,
+          strictPort: argv['strict-port']
         });
       } catch (error) {
         console.error('Error starting development server:', error.message);

package/meta/templates/default-template/index.html CHANGED Viewed

@@ -1,3 +1,4 @@
+<!DOCTYPE html>
 <html>
 <head>

package/package.json CHANGED Viewed

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.87.1",
+  "version": "0.89.1",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/dev.js CHANGED Viewed

@@ -33,6 +33,7 @@ import { generateBreadcrumbs } from "./helper/breadcrumbs.js";
 import { extractImageReferences } from "./helper/imageExtractor.js";
 import { recurse } from "./helper/recursive-readdir.js";
 import { isFolderHidden, clearConfigCache } from "./helper/folderConfig.js";
+import { isHiddenOrSystemPath, HIDDEN_OR_SYSTEM_DIRS_DEV } from "./helper/hiddenPaths.js";
 import { extractSections } from "./helper/sectionExtractor.js";
 import { getTemplates, getMenu, findAllCustomMenus, getCustomMenuForFile, getTransformedMetadata, getFooter, getUrsaMetadata, toTitleCase, addTrailingSlash, generateAutoIndexHtmlFromSource, copyMetaAssets } from "./helper/build/index.js";
 import { findCustomMenu, extractMenuFrontmatter, parseCustomMenu, combineAutoAndManualMenu } from "./helper/customMenu.js";
@@ -597,11 +598,14 @@ async function buildBackgroundCaches() {
     const allSourceFiles = await recurse(source, [() => false]);
     // Filter hidden folders
-    const hiddenOrSystemDirs = /[\/\\]\.(?!\.)|[\/\\]node_modules[\/\\]/;
+    // Judged RELATIVE to the docroot — see helper/hiddenPaths.js for why
+    // testing the absolute path silently yields an empty site.
+    const isHiddenOrSystem = (f) =>
+      isHiddenOrSystemPath(f, source, HIDDEN_OR_SYSTEM_DIRS_DEV);
     const articleExtensions = /\.(md|mdx|txt|yml)/;
     const allArticles = allSourceFiles.filter(f =>
-      f.match(articleExtensions) && !f.match(hiddenOrSystemDirs) && !isFolderHidden(dirname(f), source)
+      f.match(articleExtensions) && !isHiddenOrSystem(f) && !isFolderHidden(dirname(f), source)
     );
     const allDirectories = [];
@@ -609,7 +613,7 @@ async function buildBackgroundCaches() {
     for (const f of allSourceFiles) {
       try {
         const s = await stat(f);
-        if (s.isDirectory() && !f.match(hiddenOrSystemDirs) && !isFolderHidden(f, source)) {
+        if (s.isDirectory() && !isHiddenOrSystem(f) && !isFolderHidden(f, source)) {
           if (!seenDirs.has(f)) {
             seenDirs.add(f);
             allDirectories.push(f);
@@ -623,7 +627,7 @@ async function buildBackgroundCaches() {
       let dir = dirname(article);
       while (dir.startsWith(source) && !seenDirs.has(dir)) {
         seenDirs.add(dir);
-        if (!dir.match(hiddenOrSystemDirs)) {
+        if (!isHiddenOrSystem(dir)) {
           allDirectories.push(dir);
         }
         dir = dirname(dir);

package/src/helper/__test__/hiddenPaths.test.js ADDED Viewed

@@ -0,0 +1,106 @@
+import {
+  HIDDEN_OR_SYSTEM_DIRS,
+  HIDDEN_OR_SYSTEM_DIRS_DEV,
+  isHiddenOrSystemPath,
+  toSourceRelative,
+} from "../hiddenPaths.js";
+describe("toSourceRelative", () => {
+  it("strips the docroot and keeps a leading separator", () => {
+    expect(toSourceRelative("/srv/site/a/b.md", "/srv/site")).toBe("/a/b.md");
+  });
+  it("does not care whether the docroot has a trailing slash", () => {
+    expect(toSourceRelative("/srv/site/a.md", "/srv/site/")).toBe("/a.md");
+    expect(toSourceRelative("/srv/site/a.md", "/srv/site")).toBe("/a.md");
+  });
+  it("returns '/' for the docroot itself", () => {
+    expect(toSourceRelative("/srv/site", "/srv/site")).toBe("/");
+    expect(toSourceRelative("/srv/site/", "/srv/site")).toBe("/");
+  });
+  it("passes through a path outside the docroot unchanged", () => {
+    expect(toSourceRelative("/elsewhere/a.md", "/srv/site")).toBe(
+      "/elsewhere/a.md"
+    );
+  });
+});
+describe("isHiddenOrSystemPath", () => {
+  it("hides a dot-folder inside the docroot", () => {
+    expect(isHiddenOrSystemPath("/srv/site/.drafts/a.md", "/srv/site")).toBe(
+      true
+    );
+  });
+  it("hides a dot-folder nested inside the docroot", () => {
+    expect(isHiddenOrSystemPath("/srv/site/a/.x/b.md", "/srv/site")).toBe(true);
+  });
+  it("hides node_modules and _templates inside the docroot", () => {
+    expect(
+      isHiddenOrSystemPath("/srv/site/node_modules/p/a.md", "/srv/site")
+    ).toBe(true);
+    expect(isHiddenOrSystemPath("/srv/site/_templates/a.md", "/srv/site")).toBe(
+      true
+    );
+  });
+  it("does not hide an ordinary article", () => {
+    expect(isHiddenOrSystemPath("/srv/site/a/b.md", "/srv/site")).toBe(false);
+  });
+  /*
+   * The regression this module exists for.
+   *
+   * Every one of these docroots is perfectly ordinary; only its ANCESTRY
+   * contains a dot-directory. Testing the absolute path marked all of them
+   * hidden, so `generate` classified zero articles, reported success, and wrote
+   * an empty site.
+   */
+  it.each([
+    ["a git worktree", "/Users/x/repo/.claude/worktrees/wt/docs/help"],
+    ["a dotfile config dir", "/Users/x/.config/site"],
+    ["~/.local", "/Users/x/.local/share/site"],
+  ])("does not hide the docroot because of %s", (_label, root) => {
+    expect(isHiddenOrSystemPath(`${root}/index.md`, root)).toBe(false);
+    expect(isHiddenOrSystemPath(`${root}/api/action-api.md`, root)).toBe(false);
+  });
+  it("still hides a dot-folder inside a docroot that is itself under one", () => {
+    const root = "/Users/x/repo/.claude/worktrees/wt/docs/help";
+    expect(isHiddenOrSystemPath(`${root}/.drafts/a.md`, root)).toBe(true);
+  });
+  it("does not treat '..' as a hidden folder", () => {
+    expect(isHiddenOrSystemPath("/srv/site/a/../b.md", "/srv/site")).toBe(false);
+  });
+  it("accepts an alternative pattern for the dev server", () => {
+    const root = "/srv/site";
+    // The dev pattern omits _templates, which dev mode does not process.
+    expect(
+      isHiddenOrSystemPath(
+        `${root}/_templates/a.md`,
+        root,
+        HIDDEN_OR_SYSTEM_DIRS_DEV
+      )
+    ).toBe(false);
+    expect(
+      isHiddenOrSystemPath(`${root}/.x/a.md`, root, HIDDEN_OR_SYSTEM_DIRS_DEV)
+    ).toBe(true);
+  });
+  it("exports patterns that are not sticky or global", () => {
+    // A /g or /y regex would carry lastIndex between calls and answer
+    // differently on alternate invocations.
+    for (const re of [HIDDEN_OR_SYSTEM_DIRS, HIDDEN_OR_SYSTEM_DIRS_DEV]) {
+      expect(re.global).toBe(false);
+      expect(re.sticky).toBe(false);
+    }
+    const p = "/srv/site/.x/a.md";
+    expect(isHiddenOrSystemPath(p, "/srv/site")).toBe(true);
+    expect(isHiddenOrSystemPath(p, "/srv/site")).toBe(true);
+  });
+});

package/src/helper/__test__/portUtils.test.js ADDED Viewed

@@ -0,0 +1,100 @@
+import net from "net";
+import { jest } from "@jest/globals";
+import { isPortAvailable, resolvePort } from "../portUtils.js";
+/** Hold a port for the duration of `fn`. */
+async function withPortHeld(port, fn) {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, resolve);
+  });
+  try {
+    return await fn();
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+}
+/** A port pair (n, n+1) that is currently free, so tests do not fight the machine. */
+async function findFreePair(start = 39000) {
+  for (let p = start; p < start + 400; p += 2) {
+    if ((await isPortAvailable(p)) && (await isPortAvailable(p + 1))) return p;
+  }
+  throw new Error("no free port pair for test");
+}
+describe("resolvePort", () => {
+  let logSpy;
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+  afterEach(() => logSpy.mockRestore());
+  it("returns the requested port when it and its ws port are free", async () => {
+    const port = await findFreePair();
+    await expect(resolvePort(port, { strict: true })).resolves.toBe(port);
+  });
+  describe("strict", () => {
+    it("throws rather than moving when the HTTP port is taken", async () => {
+      const port = await findFreePair();
+      await withPortHeld(port, async () => {
+        await expect(resolvePort(port, { strict: true })).rejects.toThrow(
+          /already in use[\s\S]*--strict-port/
+        );
+      });
+    });
+    /*
+     * The WS port is the trap: ursa serves hot-reload on port+1, so a port pair
+     * is only usable if BOTH halves are free. A caller that checked only the
+     * HTTP port would call this fine and then die with EADDRINUSE later.
+     */
+    it("throws when only the WEBSOCKET port is taken", async () => {
+      const port = await findFreePair();
+      await withPortHeld(port + 1, async () => {
+        await expect(resolvePort(port, { strict: true })).rejects.toThrow(
+          /WebSocket port/
+        );
+      });
+    });
+  });
+  describe("non-interactive", () => {
+    /*
+     * The regression that motivated this: `ursa serve` running as one process
+     * of a parallel `pnpm dev`. Prompting there hangs the whole dev command,
+     * because sibling processes share stdin and nobody is reading this one.
+     */
+    it("falls back without prompting when stdin is not a TTY", async () => {
+      const port = await findFreePair();
+      const resolved = await withPortHeld(port, () =>
+        resolvePort(port, { interactive: false })
+      );
+      expect(resolved).not.toBe(port);
+      expect(typeof resolved).toBe("number");
+    });
+    it("says loudly which port it moved to", async () => {
+      const port = await findFreePair();
+      const resolved = await withPortHeld(port, () =>
+        resolvePort(port, { interactive: false })
+      );
+      const said = logSpy.mock.calls.flat().join("\n");
+      expect(said).toContain(String(resolved));
+      expect(said).toMatch(/not a TTY/);
+      // The whole point of being loud: whoever pointed at the old port must act.
+      expect(said).toMatch(/must be updated|--strict-port/);
+    });
+    it("prefers strict over falling back when both are in play", async () => {
+      const port = await findFreePair();
+      await withPortHeld(port, async () => {
+        await expect(
+          resolvePort(port, { strict: true, interactive: false })
+        ).rejects.toThrow(/--strict-port/);
+      });
+    });
+  });
+});

package/src/helper/__test__/staticAssets.test.js ADDED Viewed

@@ -0,0 +1,47 @@
+import {
+  isImage,
+  isMedia,
+  isStaticAsset,
+} from "../staticAssets.js";
+describe("staticAssets", () => {
+  it("treats the image formats as images", () => {
+    for (const f of ["a.jpg", "a.jpeg", "a.PNG", "a.gif", "a.webp", "a.svg", "a.ico"]) {
+      expect(isImage(f)).toBe(true);
+      expect(isMedia(f)).toBe(false);
+    }
+  });
+  // The regression this module exists for: generate() copied images and HTML
+  // and nothing else, so every one of these 404'd in a built site.
+  it("treats fonts, audio, video and documents as media", () => {
+    for (const f of ["a.woff", "a.woff2", "a.ttf", "a.eot", "a.otf", "a.pdf",
+      "a.mp3", "a.m4a", "a.wav", "a.flac", "a.mp4", "a.m4v", "a.webm", "a.ogv", "a.ogg", "a.zip"]) {
+      expect(isMedia(f)).toBe(true);
+      expect(isImage(f)).toBe(false);
+    }
+  });
+  it("counts both as static assets", () => {
+    expect(isStaticAsset("clip.mp4")).toBe(true);
+    expect(isStaticAsset("Herculanum Regular.ttf")).toBe(true);
+    expect(isStaticAsset("photo.jpg")).toBe(true);
+  });
+  it("leaves the processed formats alone", () => {
+    for (const f of ["page.md", "page.mdx", "page.html", "style.css", "script.js", "data.json"]) {
+      expect(isStaticAsset(f)).toBe(false);
+    }
+  });
+  it("matches on the extension, not on a name that merely contains one", () => {
+    expect(isStaticAsset("mp4")).toBe(false);
+    expect(isStaticAsset("notes-about-mp4-encoding.md")).toBe(false);
+    expect(isStaticAsset("my.mp4.md")).toBe(false);
+  });
+  it("is case insensitive, as filesystems are not", () => {
+    expect(isStaticAsset("CLIP.MP4")).toBe(true);
+    expect(isStaticAsset("Font.TTF")).toBe(true);
+  });
+});

package/src/helper/automenu.js CHANGED Viewed

@@ -1,4 +1,5 @@
 import dirTree from "directory-tree";
+import { isHiddenOrSystemPath } from "./hiddenPaths.js";
 import { extname, basename, join, dirname } from "path";
 import { existsSync, readFileSync } from "fs";
 import { getFolderConfig, isFolderHidden, getRootConfig } from "./folderConfig.js";
@@ -447,10 +448,49 @@ function collapseSingleDocFolders(items) {
   });
 }
+/**
+ * Drop hidden/system nodes from a directory-tree, judging each node's path
+ * RELATIVE to the docroot. See helper/hiddenPaths.js for why relative.
+ *
+ * Returns a new tree; the input is not mutated.
+ *
+ * @param {object} node - A directory-tree node
+ * @param {string} source - Absolute path of the docroot
+ * @returns {object} The pruned node
+ */
+export function pruneHiddenNodes(node, source) {
+  if (!node.children) return node;
+  return {
+    ...node,
+    children: node.children
+      .filter((child) => !isHiddenOrSystemPath(child.path, source))
+      .map((child) => pruneHiddenNodes(child, source)),
+  };
+}
 export async function getAutomenu(source, validPaths) {
-  const tree = dirTree(source, {
-    exclude: /[\/\\]\.|node_modules|_templates/,  // Exclude hidden folders (starting with .), node_modules, and _templates
-  });
+  /*
+   * Walk first, prune second.
+   *
+   * `dirTree`'s `exclude` is tested against each item's ABSOLUTE path,
+   * including the root's. A docroot that merely lives under a dot-directory —
+   * a git worktree under `.claude/worktrees/…`, anything in `~/.config` —
+   * therefore excluded ITSELF, and `dirTree` returned null, which reached
+   * `buildMenuData` as `Cannot read properties of null (reading 'children')`.
+   *
+   * Pruning afterwards judges each node relative to the docroot instead, which
+   * is what "hidden folder" was always meant to mean. The cost is that a
+   * `node_modules` sitting inside a docroot is now walked before being
+   * discarded; docroots do not normally contain one, and correctness on every
+   * ordinary path is worth more than speed on a pathological one.
+   */
+  const fullTree = dirTree(source);
+  if (!fullTree) {
+    throw new Error(
+      `Cannot read docroot for menu generation: ${source} (does it exist and is it a directory?)`
+    );
+  }
+  const tree = pruneHiddenNodes(fullTree, source);
   // Build menu data WITHOUT debug fields for smaller JSON
   let menuData = buildMenuData(tree, source, validPaths, '', false);

package/src/helper/build/autoIndex.js CHANGED Viewed

@@ -273,11 +273,16 @@ export async function generateAutoIndices(output, directories, source, templates
       continue; // Don't overwrite existing source HTML
     }
-    // Skip if index.html already exists in output (e.g., created by previous run or current run)
-    if (existsSync(indexPath)) {
-      continue;
-    }
+    // NOTE: an existing index.html in output is deliberately NOT a reason to
+    // skip. This listing describes the folder's contents, so it goes stale the
+    // moment a document or subfolder is added or removed, and warm builds kept
+    // whatever was written the first time — indefinitely. Everything that has a
+    // rightful claim on index.html is already excluded above: folders with a
+    // source index document (dirsWithSourceIndex, built from every source
+    // article rather than only the regenerated ones) and hand-written source
+    // HTML (existingHtmlFiles). Alternates are re-promoted below, so those stay
+    // authoritative too.
     // Get folder name for (foldername).html check
     const folderName = basename(dir);
     const folderNameAlternate = `${folderName}.html`;

package/src/helper/contentHash.js CHANGED Viewed

@@ -61,6 +61,25 @@ export function needsRegeneration(filePath, content, hashCache) {
   return newHash !== oldHash;
 }
+/**
+ * Check whether every expected output file for a source document exists.
+ *
+ * A matching content hash only proves the *source* is unchanged — it says
+ * nothing about whether the output was ever written to this particular output
+ * directory. The hash cache lives in the source tree (`<source>/.ursa/`) and is
+ * shared by every output directory built from that source, so a hash written
+ * during a build to one output dir will hash-skip the same file during a build
+ * to another. Deleting (or partially losing) an output dir has the same effect.
+ * Callers must combine this with needsRegeneration() so a missing output always
+ * forces a rebuild.
+ *
+ * @param {string[]} outputPaths - Absolute paths to every file the build emits for this document
+ * @returns {boolean} True only if all of them are present
+ */
+export function outputsExist(outputPaths) {
+  return outputPaths.every((p) => existsSync(p));
+}
 /**
  * Update the hash for a file in the cache
  */

package/src/helper/hiddenPaths.js ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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);

package/src/helper/staticAssets.js ADDED Viewed

@@ -0,0 +1,31 @@
+/**
+ * What counts as a static asset.
+ *
+ * This list used to be written out separately in serve.js and in
+ * dependencyTracker.js and — fatally — not at all in generate.js, which knew
+ * only about *image* extensions. `ursa serve` therefore served fonts, audio and
+ * video quite happily while `ursa generate` left them out of the build
+ * entirely, so they worked all the way through development and 404'd in
+ * production. One list, in one place, used by both.
+ */
+/** Extensions that get preview generation and image transformation. */
+export const IMAGE_EXTENSIONS = /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i;
+/**
+ * Everything else copied through untouched: fonts, documents, audio, video.
+ * Deliberately not images, which take a different path, and deliberately not
+ * .css, .js, .html or the document formats, all of which are processed rather
+ * than copied.
+ */
+export const MEDIA_EXTENSIONS = /\.(woff2?|ttf|eot|otf|pdf|mp3|m4a|wav|flac|mp4|m4v|webm|ogv|ogg|zip)$/i;
+/** Any file the build should place in the output as-is. */
+export const STATIC_ASSET_EXTENSIONS = new RegExp(
+  `(?:${IMAGE_EXTENSIONS.source})|(?:${MEDIA_EXTENSIONS.source})`,
+  'i'
+);
+export const isImage = (filename) => IMAGE_EXTENSIONS.test(filename);
+export const isMedia = (filename) => MEDIA_EXTENSIONS.test(filename);
+export const isStaticAsset = (filename) => STATIC_ASSET_EXTENSIONS.test(filename);