@kenjura/ursa 0.85.0 → 0.87.1

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+# 0.87.1
+2026-06-15
+
+- nothing
+
+# 0.87.0
+2026-06-11
+
+- Added support for definition lists in Markdown/MDX documents, allowing for structured term-definition pairs to be rendered as HTML definition lists (<dl>, <dt>, <dd>).
+- Added response headers for json files with the ursa and doc repo version numbers, so consumers can invalidate caches when a new version is deployed.
+
+
+## Serve Revamp (Phases 0–1)
+
+`ursa serve` could miss cascading updates — stylesheet edits, static files in `meta/`, template changes, and any change saved while a rebuild was already running — forcing a restart with `--clean`. This release ships the first two phases of the rework; design, root-cause analysis, and remaining TODOs: [docs/changes/serve-logic.md](docs/changes/serve-logic.md).
+
+- **Serve-mode reliability fixes (Phase 0):**
+  - Static assets in `meta/` (images, fonts, PDFs, media) are now watched; replacing one re-copies it to output and reloads clients, without a full rebuild. Previously these changes were invisible until restart.
+  - Changes saved while a regeneration is in flight are queued and processed when the current pass finishes, instead of being dropped with "changes lost".
+  - Every full-rebuild path now deletes `content-hashes.json` and `nav-cache.json` first, so a rebuild after a template/meta change actually regenerates unchanged articles instead of hash-skipping them and leaving stale HTML.
+  - The dependency tracker is persisted to `.ursa/dependency-graph.json` and reloaded on warm start, so hash-skipped documents keep their invalidation edges. Single-file regeneration now registers dependencies too, and template edits are recognized under the `templates/{name}/index.html` folder structure — a template edit on a warm start is now a selective rebuild of just the documents using that template.
+- **New incremental build engine (Phase 1):** `src/helper/build/graph.js` — a fingerprinted dependency graph (Make/Shake-style) with dynamic dependency discovery (`ctx.read`/`ctx.exists`/`ctx.get`), lookup nodes so file *creation* invalidates, size+mtime fast-path fingerprinting with content-hash confirmation, early cutoff, topological demand-driven scheduling, failure isolation with retry, and versioned persistence to `.ursa/graph.json`. Fully unit-tested; the build/serve pipelines will be ported onto it in the next phases (2–4).
+
+# 0.86.0
+2026-05-18
+
+- small CSS fix
+
+# 0.85.0
+2026-05-15
+
+- deflists in MDX
+
+
 # 0.84.0
 2026-05-08
 

package/bin/ursa.js

@@ -6,6 +6,7 @@ import { generate } from '../src/jobs/generate.js';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { stagePromotedChangelog, registerCleanupOnExit } from '../src/helper/promoteChangelog.js';
+import { instantiateTemplate } from '../src/helper/documentTemplates.js';
 
 // Get the directory where ursa is installed
 const __filename = fileURLToPath(import.meta.url);
@@ -14,7 +15,7 @@ const PACKAGE_META = join(__dirname, '..', 'meta');
 
 yargs(hideBin(process.argv))
   .command(
-    'generate <source>',
+    ['generate <source>', '$0 <source>'],
     'Generate a static site from source files',
     (yargs) => {
       return yargs
@@ -235,54 +236,40 @@ yargs(hideBin(process.argv))
     }
   )
   .command(
-    '$0 <source>',
-    'Generate a static site from source files (default command)',
+    'template <source> <templatePath> <destination>',
+    'Create a new document from a document template',
     (yargs) => {
       return yargs
         .positional('source', {
-          describe: 'Source directory containing markdown/wikitext files',
+          describe: 'Source directory (docroot) of the Ursa site',
           type: 'string',
           demandOption: true
         })
-        .option('meta', {
-          alias: 'm',
-          default: 'meta',
-          describe: 'Meta directory containing templates and styles',
-          type: 'string'
-        })
-        .option('output', {
-          alias: 'o', 
-          default: 'output',
-          describe: 'Output directory for generated site',
-          type: 'string'
+        .positional('templatePath', {
+          describe: 'Path to the template file (relative to source, e.g. _templates/city.md)',
+          type: 'string',
+          demandOption: true
         })
-        .option('whitelist', {
-          alias: 'w',
-          describe: 'Path to whitelist file containing patterns for files to include',
-          type: 'string'
+        .positional('destination', {
+          describe: 'Path for the new document (relative to source, e.g. places/springfield.md)',
+          type: 'string',
+          demandOption: true
         });
     },
     async (argv) => {
       const source = resolve(argv.source);
-      const meta = resolve(argv.meta);
-      const output = resolve(argv.output);
-      const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
-      
-      console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
-      if (whitelist) {
-        console.log(`Using whitelist: ${whitelist}`);
-      }
-      
+      const templateAbsPath = resolve(source, argv.templatePath);
+      const destAbsPath = resolve(source, argv.destination);
+
       try {
-        await generate({
-          _source: source,
-          _meta: meta,
-          _output: output,
-          _whitelist: whitelist
-        });
-        console.log('Site generation completed successfully!');
+        const { templateRelPath, destRelPath } = await instantiateTemplate(
+          templateAbsPath,
+          destAbsPath,
+          source
+        );
+        console.log(`✅ Created ${destRelPath} from template ${templateRelPath}`);
       } catch (error) {
-        console.error('Error generating site:', error.message);
+        console.error(`Error creating template instance: ${error.message}`);
         process.exit(1);
       }
     }

package/meta/templates/default-template/default.css

@@ -50,11 +50,16 @@ h1 {
   text-overflow: ellipsis;
 }
 
+h1,h2,h3 {
+  clear: both;
+}
+
 figure {
   margin: 0.5rem 0;
   padding: 0;
   max-width: 300px;
   float: left;
+  clear: both;
   margin-right: 1.5rem;
   margin-bottom: 0.5rem;
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.85.0",
+  "version": "0.87.1",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -35,6 +35,7 @@
     "markdown-it-front-matter": "^0.2.3",
     "markdown-it-sup": "^1.0.0",
     "mdx-bundler": "^10.1.1",
+    "node-diff3": "^3.2.0",
     "node-watch": "^0.7.3",
     "object-to-xml": "^2.0.0",
     "react": "^19.2.4",

package/src/dev.js

@@ -34,7 +34,7 @@ import { extractImageReferences } from "./helper/imageExtractor.js";
 import { recurse } from "./helper/recursive-readdir.js";
 import { isFolderHidden, clearConfigCache } from "./helper/folderConfig.js";
 import { extractSections } from "./helper/sectionExtractor.js";
-import { getTemplates, getMenu, findAllCustomMenus, getCustomMenuForFile, getTransformedMetadata, getFooter, toTitleCase, addTrailingSlash, generateAutoIndexHtmlFromSource, copyMetaAssets } from "./helper/build/index.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";
 import { getAndIncrementBuildId } from "./helper/ursaConfig.js";
 import { resolvePort } from "./helper/portUtils.js";
@@ -47,6 +47,9 @@ const devState = {
   source: null,
   meta: null,
   output: null,
+
+  // Ursa + doc repo versions, embedded in JSON response headers
+  ursaMetadata: null,
   
   // Background cache status
   cacheReady: false,
@@ -766,6 +769,7 @@ export async function dev({
   devState.source = sourceDir + '/';
   devState.meta = metaDir;
   devState.output = outputDir + '/';
+  devState.ursaMetadata = await getUrsaMetadata(_source);
   
   console.log('🚀 Ursa Dev Mode');
   console.log('━'.repeat(50));
@@ -810,6 +814,17 @@ export async function dev({
     threshold: 1024,
     level: 6
   }));
+
+  // Add ursa-version and doc-version headers to all JSON responses
+  // (per-document JSON, directory index arrays, and public/*.json index files)
+  app.use((req, res, next) => {
+    if (req.path.endsWith('.json')) {
+      const meta = devState.ursaMetadata || {};
+      res.setHeader('X-ursa-version', meta.ursaVersion || 'unknown');
+      res.setHeader('X-doc-version', meta.docVersion || 'unknown');
+    }
+    next();
+  });
   
   // Dev mode document handler
   app.use(async (req, res, next) => {

package/src/helper/__test__/dependencyTracker.test.js

@@ -0,0 +1,157 @@
+import { join } from "path";
+import { mkdtemp, rm, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { tmpdir } from "os";
+import {
+  DependencyTracker,
+  loadDependencyTracker,
+  saveDependencyTracker,
+  getDependencyGraphPath,
+} from "../dependencyTracker.js";
+
+let tempDir;
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "ursa-deptracker-"));
+});
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeTracker(sourceDir) {
+  const tracker = new DependencyTracker();
+  tracker.init(sourceDir);
+  return tracker;
+}
+
+describe("serialize / load", () => {
+  it("round-trips registrations through serialize + load", () => {
+    const t1 = makeTracker("/site/docs");
+    t1.registerDocument("/site/docs/a.md", {
+      templateName: "default-template",
+      cssPaths: ["/site/docs/style.css"],
+      scriptPaths: ["/site/docs/script.js"],
+    });
+    t1.registerDocument("/site/docs/sub/b.md", {
+      templateName: "wiki",
+      cssPaths: ["/site/docs/style.css", "/site/docs/sub/style.css"],
+    });
+
+    const data = JSON.parse(JSON.stringify(t1.serialize()));
+    const t2 = makeTracker("/site/docs");
+    expect(t2.load(data)).toBe(true);
+
+    expect([...t2.getAffectedDocuments("/site/docs/style.css")].sort()).toEqual([
+      "/site/docs/a.md",
+      "/site/docs/sub/b.md",
+    ]);
+    expect([...t2.getDocumentsUsingTemplate("wiki")]).toEqual(["/site/docs/sub/b.md"]);
+    expect(t2.getStats()).toEqual(t1.getStats());
+  });
+
+  it("merges with current-run registrations, which take precedence", () => {
+    const t1 = makeTracker("/site/docs");
+    t1.registerDocument("/site/docs/a.md", { templateName: "old-template" });
+    t1.registerDocument("/site/docs/b.md", { templateName: "default-template" });
+    const persisted = t1.serialize();
+
+    // New run: a.md was re-rendered with a different template before load
+    const t2 = makeTracker("/site/docs");
+    t2.registerDocument("/site/docs/a.md", { templateName: "new-template" });
+    expect(t2.load(persisted)).toBe(true);
+
+    // Live registration wins; persisted fills in the hash-skipped doc
+    expect([...t2.getDocumentsUsingTemplate("new-template")]).toEqual(["/site/docs/a.md"]);
+    expect([...t2.getDocumentsUsingTemplate("old-template")]).toEqual([]);
+    expect([...t2.getDocumentsUsingTemplate("default-template")]).toEqual(["/site/docs/b.md"]);
+  });
+
+  it("rejects mismatched schema versions and source dirs", () => {
+    const t = makeTracker("/site/docs");
+    expect(t.load(null)).toBe(false);
+    expect(t.load({ version: 99, documents: {} })).toBe(false);
+    const other = makeTracker("/different/source").serialize();
+    other.documents["/different/source/a.md"] = ["template:default-template"];
+    expect(t.load(other)).toBe(false);
+    expect(t.getStats().totalDocuments).toBe(0);
+  });
+});
+
+describe("prune", () => {
+  it("drops registrations for documents not in the keep set", () => {
+    const t = makeTracker("/site/docs");
+    t.registerDocument("/site/docs/keep.md", { cssPaths: ["/site/docs/style.css"] });
+    t.registerDocument("/site/docs/deleted.md", { cssPaths: ["/site/docs/style.css"] });
+
+    t.prune(new Set(["/site/docs/keep.md"]));
+
+    expect([...t.getAffectedDocuments("/site/docs/style.css")]).toEqual(["/site/docs/keep.md"]);
+    expect(t.getStats().totalDocuments).toBe(1);
+  });
+});
+
+describe("file persistence helpers", () => {
+  it("saves to and loads from .ursa/dependency-graph.json", async () => {
+    const t1 = makeTracker(tempDir);
+    t1.registerDocument(join(tempDir, "a.md"), {
+      templateName: "default-template",
+      cssPaths: [join(tempDir, "style.css")],
+    });
+    expect(await saveDependencyTracker(tempDir, t1)).toBe(true);
+    expect(existsSync(getDependencyGraphPath(tempDir))).toBe(true);
+    const onDisk = JSON.parse(await readFile(getDependencyGraphPath(tempDir), "utf8"));
+    expect(onDisk.version).toBe(1);
+
+    const t2 = makeTracker(tempDir);
+    expect(await loadDependencyTracker(tempDir, t2)).toBe(true);
+    expect([...t2.getAffectedDocuments(join(tempDir, "style.css"))]).toEqual([
+      join(tempDir, "a.md"),
+    ]);
+  });
+
+  it("returns false when no persisted graph exists", async () => {
+    const t = makeTracker(tempDir);
+    expect(await loadDependencyTracker(tempDir, t)).toBe(false);
+  });
+});
+
+describe("getMetaInvalidationPlan", () => {
+  it("does not force a full rebuild for static assets in meta", () => {
+    const t = makeTracker("/site/docs");
+    t.registerDocument("/site/docs/a.md", { templateName: "default-template" });
+
+    for (const file of ["logo.png", "font.woff2", "manual.pdf", "icon.SVG"]) {
+      const plan = t.getMetaInvalidationPlan(`/site/meta/shared/${file}`, "/site/meta");
+      expect(plan.requiresFullRebuild).toBe(false);
+      expect(plan.affectedDocuments).toEqual([]);
+    }
+  });
+
+  it("still regenerates documents for template and css/js meta changes", () => {
+    const t = makeTracker("/site/docs");
+    t.registerDocument("/site/docs/a.md", { templateName: "default-template" });
+
+    // New folder structure: templates/{name}/index.html → name from the folder
+    const tplPlan = t.getMetaInvalidationPlan(
+      "/site/meta/templates/default-template/index.html",
+      "/site/meta"
+    );
+    expect(tplPlan.requiresFullRebuild).toBe(false);
+    expect(tplPlan.affectedDocuments).toEqual(["/site/docs/a.md"]);
+
+    // Legacy flat structure: {name}.html at the meta root
+    const legacyPlan = t.getMetaInvalidationPlan(
+      "/site/meta/default-template.html",
+      "/site/meta"
+    );
+    expect(legacyPlan.requiresFullRebuild).toBe(false);
+    expect(legacyPlan.affectedDocuments).toEqual(["/site/docs/a.md"]);
+
+    const cssPlan = t.getMetaInvalidationPlan("/site/meta/shared/theme.css", "/site/meta");
+    expect(cssPlan.requiresFullRebuild).toBe(false);
+    expect(cssPlan.affectedDocuments).toEqual(["/site/docs/a.md"]);
+
+    // Unknown meta file types still fall back to a full rebuild
+    const unknownPlan = t.getMetaInvalidationPlan("/site/meta/shared/data.json", "/site/meta");
+    expect(unknownPlan.requiresFullRebuild).toBe(true);
+  });
+});