world-building-framework 0.0.0-stage → 0.2.0

package/dist/core/vault/read.js

@@ -0,0 +1,62 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { isUuid } from "../id.js";
+import { parseVaultFile } from "./parse.js";
+function idFromFilename(fileName) {
+    const base = path.basename(fileName, ".md");
+    return isUuid(base) ? base : undefined;
+}
+/**
+ * Folders that never hold world content: dependencies, and anything starting
+ * with "." (.git, .wbf with Quartz's working copy, .obsidian, agent folders
+ * like .claude). A world repo is the vault (claude-dev/DISTRIBUTION_PLAN.md),
+ * so these sit right next to the world's files.
+ */
+function isToolingFolder(name) {
+    return name === "node_modules" || name.startsWith(".");
+}
+/** Every UUID-named `.md` file under vaultDir, as absolute paths. Never descends into tooling folders. */
+async function findVaultFilePaths(vaultDir) {
+    const found = new Map();
+    const pending = [vaultDir];
+    while (pending.length > 0) {
+        const dir = pending.pop();
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!isToolingFolder(entry.name))
+                    pending.push(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                const id = idFromFilename(entry.name);
+                if (id)
+                    found.set(id, fullPath);
+            }
+        }
+    }
+    return found;
+}
+/** Where an existing vault file actually lives — possibly in a local subfolder (see readVault). */
+export async function findVaultFilePath(vaultDir, id) {
+    return (await findVaultFilePaths(vaultDir)).get(id);
+}
+/** Reads and parses one vault file by id. Never validates — see write.ts. */
+export async function readVaultFile(vaultDir, id) {
+    const raw = await readFile(path.join(vaultDir, `${id}.md`), "utf8");
+    return parseVaultFile(id, raw);
+}
+/**
+ * Reads every vault file: UUID-named `.md` files anywhere under vaultDir.
+ * SCHEMA.md's flat pool needs no folders, but a project may still use them
+ * locally (rule 5), so this looks recursively rather than assuming a flat layout.
+ * Anything not UUID-named (README, config, etc.) is silently skipped, and
+ * tooling folders (node_modules, dot-folders) aren't searched at all.
+ */
+export async function readVault(vaultDir) {
+    const files = [];
+    for (const [id, filePath] of await findVaultFilePaths(vaultDir)) {
+        const raw = await readFile(filePath, "utf8");
+        files.push(parseVaultFile(id, raw));
+    }
+    return files;
+}

package/dist/core/vault/relink.d.ts

@@ -0,0 +1,10 @@
+import type { VaultFile } from "./types.js";
+/**
+ * Rewrites every link to `targetId` whose display text is exactly `from` so it
+ * shows `to` instead — in frontmatter values and body alike. Used when a file's
+ * title is corrected, so links written with the old title follow the rename.
+ * Links with any other display text (e.g. "the old castle" in prose) are left
+ * alone: that wording was chosen on purpose. Returns the new content, or
+ * undefined if nothing in the file changed.
+ */
+export declare function replaceLinkDisplay(file: Pick<VaultFile, "frontmatter" | "body">, targetId: string, from: string, to: string): Pick<VaultFile, "frontmatter" | "body"> | undefined;

package/dist/core/vault/relink.js

@@ -0,0 +1,33 @@
+import { formatWikilink } from "../schema/wikilink.js";
+/**
+ * Rewrites every link to `targetId` whose display text is exactly `from` so it
+ * shows `to` instead — in frontmatter values and body alike. Used when a file's
+ * title is corrected, so links written with the old title follow the rename.
+ * Links with any other display text (e.g. "the old castle" in prose) are left
+ * alone: that wording was chosen on purpose. Returns the new content, or
+ * undefined if nothing in the file changed.
+ */
+export function replaceLinkDisplay(file, targetId, from, to) {
+    const oldLink = formatWikilink(targetId, from);
+    const newLink = formatWikilink(targetId, to);
+    let changed = false;
+    const replaceIn = (text) => {
+        if (!text.includes(oldLink))
+            return text;
+        changed = true;
+        return text.split(oldLink).join(newLink);
+    };
+    const replaceValue = (value) => {
+        if (typeof value === "string")
+            return replaceIn(value);
+        if (Array.isArray(value))
+            return value.map(replaceValue);
+        if (value !== null && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, replaceValue(inner)]));
+        }
+        return value;
+    };
+    const frontmatter = replaceValue(file.frontmatter);
+    const body = replaceIn(file.body);
+    return changed ? { frontmatter, body } : undefined;
+}

package/dist/core/vault/serialize.d.ts

@@ -0,0 +1,4 @@
+export declare function serializeVaultFile(file: {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}): string;

package/dist/core/vault/serialize.js

@@ -0,0 +1,4 @@
+import matter from "gray-matter";
+export function serializeVaultFile(file) {
+    return matter.stringify(file.body, file.frontmatter);
+}

package/dist/core/vault/types.d.ts

@@ -0,0 +1,5 @@
+export interface VaultFile {
+    id: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}

package/dist/core/vault/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/vault/write.d.ts

@@ -0,0 +1,18 @@
+import { type ValidateOptions, type ValidationIssue } from "../schema/validate.js";
+export type WriteResult = {
+    written: true;
+    id: string;
+    path: string;
+} | {
+    written: false;
+    issues: ValidationIssue[];
+};
+/** Creates a new vault file with a freshly generated id (SCHEMA.md rule 1). */
+export declare function createVaultFile(vaultDir: string, frontmatter: Record<string, unknown>, body: string, options?: ValidateOptions): Promise<WriteResult>;
+/**
+ * Overwrites an existing vault file's own content (e.g. fixing a typo, editing prose),
+ * in place — including when it lives in a local subfolder. Throws if no file has this id.
+ * To record a change to an entity over time, prefer createVaultFile with
+ * `supersedes`/`causedBy` instead (SCHEMA.md) — this does not create a new version.
+ */
+export declare function writeVaultFile(vaultDir: string, id: string, frontmatter: Record<string, unknown>, body: string, options?: ValidateOptions): Promise<WriteResult>;

package/dist/core/vault/write.js

@@ -0,0 +1,37 @@
+import { mkdir, writeFile as writeFileFs } from "node:fs/promises";
+import path from "node:path";
+import { generateId } from "../id.js";
+import { validateFrontmatter } from "../schema/validate.js";
+import { serializeVaultFile } from "./serialize.js";
+import { findVaultFilePath } from "./read.js";
+/**
+ * Validates before writing, and only then — this is the one place non-conforming
+ * frontmatter actually gets rejected (reading a vault file never validates, see read.ts).
+ */
+async function writeValidated(filePath, id, frontmatter, body, options) {
+    const result = validateFrontmatter(frontmatter, options);
+    if (!result.valid) {
+        return { written: false, issues: result.issues };
+    }
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFileFs(filePath, serializeVaultFile({ frontmatter, body }), "utf8");
+    return { written: true, id, path: filePath };
+}
+/** Creates a new vault file with a freshly generated id (SCHEMA.md rule 1). */
+export function createVaultFile(vaultDir, frontmatter, body, options) {
+    const id = generateId();
+    return writeValidated(path.join(vaultDir, `${id}.md`), id, frontmatter, body, options);
+}
+/**
+ * Overwrites an existing vault file's own content (e.g. fixing a typo, editing prose),
+ * in place — including when it lives in a local subfolder. Throws if no file has this id.
+ * To record a change to an entity over time, prefer createVaultFile with
+ * `supersedes`/`causedBy` instead (SCHEMA.md) — this does not create a new version.
+ */
+export async function writeVaultFile(vaultDir, id, frontmatter, body, options) {
+    const filePath = await findVaultFilePath(vaultDir, id);
+    if (!filePath) {
+        throw new Error(`No file with id "${id}" in this vault — use createVaultFile for a new file.`);
+    }
+    return writeValidated(filePath, id, frontmatter, body, options);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./core/schema/index.js";
+export * from "./core/vault/index.js";
+export * from "./core/config/index.js";
+export * from "./core/query/index.js";
+export * from "./core/graph/index.js";
+export * from "./core/search/index.js";
+export * from "./core/lint/index.js";
+export { generateId, isUuid } from "./core/id.js";
+export { buildDerivedTree } from "./render-pipeline/index.js";
+export type { RenderedPage } from "./render-pipeline/index.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+// Library entry point: the shared core engine (AUTHORING_STACK.md's "one
+// algorithm"), for tools built on top of a vault without going through the CLI.
+export * from "./core/schema/index.js";
+export * from "./core/vault/index.js";
+export * from "./core/config/index.js";
+export * from "./core/query/index.js";
+export * from "./core/graph/index.js";
+export * from "./core/search/index.js";
+export * from "./core/lint/index.js";
+export { generateId, isUuid } from "./core/id.js";
+export { buildDerivedTree } from "./render-pipeline/index.js";

package/dist/render-pipeline/build.d.ts

@@ -0,0 +1,9 @@
+import type { VaultFile } from "../core/vault/types.js";
+import type { BuildVariantQuery, RenderedPage } from "./types.js";
+/**
+ * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
+ * by the build variant's query, merges each included entity's version history
+ * into one page, and rewrites every link to a slug (or strips it if the target
+ * isn't included).
+ */
+export declare function buildDerivedTree(files: VaultFile[], query: BuildVariantQuery): RenderedPage[];

package/dist/render-pipeline/build.js

@@ -0,0 +1,45 @@
+import { buildGraph } from "../core/graph/index.js";
+import { filterEvents, filterEntityAnchors } from "./filter.js";
+import { mergeEntityBody } from "./merge.js";
+import { assignSlugs } from "./slugs.js";
+import { rewriteLinks, rewriteFrontmatterLinks } from "./rewrite.js";
+import { renameQuartzReservedFields } from "./quartz-compat.js";
+function titleOf(file) {
+    return typeof file.frontmatter.title === "string" ? file.frontmatter.title : file.id;
+}
+/**
+ * Stage 1: vault -> derived, Quartz-ready page set (RENDER_PIPELINE.md). Filters
+ * by the build variant's query, merges each included entity's version history
+ * into one page, and rewrites every link to a slug (or strips it if the target
+ * isn't included).
+ */
+export function buildDerivedTree(files, query) {
+    const graph = buildGraph(files);
+    const includedEventIds = filterEvents(graph, files, query);
+    const includedAnchorIds = filterEntityAnchors(graph, files, query);
+    // Sorted for a deterministic slug assignment, independent of vault read order.
+    const includedIds = [...includedEventIds, ...includedAnchorIds].sort();
+    const titles = new Map(includedIds.map((id) => [id, titleOf(graph.nodes.get(id))]));
+    const slugsById = assignSlugs(titles);
+    const pages = [];
+    for (const id of includedEventIds) {
+        const file = graph.nodes.get(id);
+        pages.push({
+            id,
+            slug: slugsById.get(id),
+            frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(file.frontmatter, slugsById)),
+            body: rewriteLinks(file.body, slugsById),
+        });
+    }
+    for (const anchorId of includedAnchorIds) {
+        const anchor = graph.nodes.get(anchorId);
+        const mergedBody = mergeEntityBody(graph, anchorId, includedEventIds);
+        pages.push({
+            id: anchorId,
+            slug: slugsById.get(anchorId),
+            frontmatter: renameQuartzReservedFields(rewriteFrontmatterLinks(anchor.frontmatter, slugsById)),
+            body: rewriteLinks(mergedBody, slugsById),
+        });
+    }
+    return pages;
+}

package/dist/render-pipeline/filter.d.ts

@@ -0,0 +1,21 @@
+import type { VaultFile } from "../core/vault/types.js";
+import type { KnowledgeGraph } from "../core/graph/index.js";
+import type { BuildVariantQuery } from "./types.js";
+/**
+ * Events included in this build. A dated event is checked against the date
+ * range directly. An undated event is placed by its causal neighbours
+ * (undatedEventWindow) and included only if that places it inside the range
+ * for certain — one with no dated events on the relevant side is left out of
+ * a date-limited build. Date one to pin it.
+ */
+export declare function filterEvents(graph: KnowledgeGraph, files: VaultFile[], query: BuildVariantQuery): Set<string>;
+/**
+ * Entity anchors included in this build. Only the upper date bound gates
+ * inclusion (REQUIREMENTS.md); tags are checked against the anchor file only,
+ * never later versions. The entity's first event must be at or before the
+ * upper bound for certain — if that event is undated, the latest date its
+ * causal neighbours allow is used, same rule as filterEvents. An entity with no
+ * tied events at all is always included: it has no place on the timeline
+ * (background lore, most locations), so there's nothing to be unsure about.
+ */
+export declare function filterEntityAnchors(graph: KnowledgeGraph, files: VaultFile[], query: BuildVariantQuery): Set<string>;

package/dist/render-pipeline/filter.js

@@ -0,0 +1,80 @@
+import { entityFirstEventId, eventDate, undatedEventWindow } from "../core/graph/index.js";
+import { isDateWithinRange, isAtOrBeforeUpperBound, isAtOrAfterLowerBound, } from "../core/query/index.js";
+function isEntityAnchor(file) {
+    return file.frontmatter.type === "entity" && file.frontmatter.supersedes === undefined;
+}
+function isEvent(file) {
+    return file.frontmatter.type === "event";
+}
+function hasAllTags(frontmatter, tags) {
+    const fileTags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+    return tags.every((tag) => fileTags.includes(tag));
+}
+/**
+ * True only if the window lies entirely inside the range: an undated event is
+ * excluded whenever it *could* fall outside, so a date-limited build never
+ * leaks a later event (spoiler-safe "exclude when in doubt"). A side of the
+ * window with no dated neighbour is unbounded, so it fails any bound on that side.
+ */
+function windowWithinRange(window, range) {
+    if (range.from && !(window.earliest && isAtOrAfterLowerBound(window.earliest, range)))
+        return false;
+    if (range.to && !(window.latest && isAtOrBeforeUpperBound(window.latest, range)))
+        return false;
+    return true;
+}
+/**
+ * Events included in this build. A dated event is checked against the date
+ * range directly. An undated event is placed by its causal neighbours
+ * (undatedEventWindow) and included only if that places it inside the range
+ * for certain — one with no dated events on the relevant side is left out of
+ * a date-limited build. Date one to pin it.
+ */
+export function filterEvents(graph, files, query) {
+    const included = new Set();
+    for (const file of files) {
+        if (!isEvent(file))
+            continue;
+        if (query.tags && query.tags.length > 0 && !hasAllTags(file.frontmatter, query.tags))
+            continue;
+        if (query.dateRange) {
+            const date = eventDate(file);
+            const inRange = date
+                ? isDateWithinRange(date, query.dateRange)
+                : windowWithinRange(undatedEventWindow(graph, file.id), query.dateRange);
+            if (!inRange)
+                continue;
+        }
+        included.add(file.id);
+    }
+    return included;
+}
+/**
+ * Entity anchors included in this build. Only the upper date bound gates
+ * inclusion (REQUIREMENTS.md); tags are checked against the anchor file only,
+ * never later versions. The entity's first event must be at or before the
+ * upper bound for certain — if that event is undated, the latest date its
+ * causal neighbours allow is used, same rule as filterEvents. An entity with no
+ * tied events at all is always included: it has no place on the timeline
+ * (background lore, most locations), so there's nothing to be unsure about.
+ */
+export function filterEntityAnchors(graph, files, query) {
+    const included = new Set();
+    for (const file of files) {
+        if (!isEntityAnchor(file))
+            continue;
+        if (query.tags && query.tags.length > 0 && !hasAllTags(file.frontmatter, query.tags))
+            continue;
+        if (query.dateRange?.to) {
+            const firstEventId = entityFirstEventId(graph, file.id);
+            if (firstEventId) {
+                const date = eventDate(graph.nodes.get(firstEventId));
+                const latest = date ?? undatedEventWindow(graph, firstEventId).latest;
+                if (!latest || !isAtOrBeforeUpperBound(latest, query.dateRange))
+                    continue;
+            }
+        }
+        included.add(file.id);
+    }
+    return included;
+}

package/dist/render-pipeline/index.d.ts

@@ -0,0 +1,10 @@
+export * from "../core/query/index.js";
+export * from "./types.js";
+export * from "./filter.js";
+export * from "./merge.js";
+export * from "./slugs.js";
+export * from "./rewrite.js";
+export * from "./quartz-compat.js";
+export * from "./build.js";
+export * from "./write.js";
+export * from "./sync.js";

package/dist/render-pipeline/index.js

@@ -0,0 +1,10 @@
+export * from "../core/query/index.js";
+export * from "./types.js";
+export * from "./filter.js";
+export * from "./merge.js";
+export * from "./slugs.js";
+export * from "./rewrite.js";
+export * from "./quartz-compat.js";
+export * from "./build.js";
+export * from "./write.js";
+export * from "./sync.js";

package/dist/render-pipeline/merge.d.ts

@@ -0,0 +1,11 @@
+import type { KnowledgeGraph } from "../core/graph/index.js";
+/**
+ * The full body for an included entity: its anchor text, followed by each later
+ * version whose causing event is itself included in this build. Using the
+ * events-included set (rather than re-checking dates here) means one mechanism
+ * handles both date-range truncation and tag-based hiding — a version caused by
+ * a hidden event never shows up as an unexplained state change. Each version's
+ * body is a full rewrite (SCHEMA.md), not a diff, so skipping a hidden version
+ * and keeping a later one still reads coherently.
+ */
+export declare function mergeEntityBody(graph: KnowledgeGraph, anchorId: string, includedEventIds: Set<string>): string;

package/dist/render-pipeline/merge.js

@@ -0,0 +1,21 @@
+import { versionHistory, outgoing } from "../core/graph/index.js";
+/**
+ * The full body for an included entity: its anchor text, followed by each later
+ * version whose causing event is itself included in this build. Using the
+ * events-included set (rather than re-checking dates here) means one mechanism
+ * handles both date-range truncation and tag-based hiding — a version caused by
+ * a hidden event never shows up as an unexplained state change. Each version's
+ * body is a full rewrite (SCHEMA.md), not a diff, so skipping a hidden version
+ * and keeping a later one still reads coherently.
+ */
+export function mergeEntityBody(graph, anchorId, includedEventIds) {
+    const history = versionHistory(graph, anchorId);
+    const sections = [history[0]?.body ?? ""];
+    for (const version of history.slice(1)) {
+        const causedByEdge = outgoing(graph, version.id, "causedBy")[0];
+        if (!causedByEdge || !includedEventIds.has(causedByEdge.to))
+            continue;
+        sections.push(`## After: ${causedByEdge.display}\n\n${version.body}`);
+    }
+    return sections.join("\n\n");
+}

package/dist/render-pipeline/quartz-compat.d.ts

@@ -0,0 +1 @@
+export declare function renameQuartzReservedFields(frontmatter: Record<string, unknown>): Record<string, unknown>;

package/dist/render-pipeline/quartz-compat.js

@@ -0,0 +1,18 @@
+/**
+ * Quartz reserves the `date` frontmatter key for its own created/modified
+ * handling — verified hands-on: a real Quartz build logged "invalid date
+ * [object Object]" warnings for our event `date: {year, day}` objects, and
+ * renaming the key made them disappear. This only affects Stage 1's output —
+ * the vault's own schema keeps `date` (SCHEMA.md); this rewrite is purely
+ * cosmetic for what Quartz sees.
+ */
+const QUARTZ_RESERVED_FIELD_RENAMES = {
+    date: "worldDate",
+};
+export function renameQuartzReservedFields(frontmatter) {
+    const renamed = {};
+    for (const [key, value] of Object.entries(frontmatter)) {
+        renamed[QUARTZ_RESERVED_FIELD_RENAMES[key] ?? key] = value;
+    }
+    return renamed;
+}

package/dist/render-pipeline/rewrite.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Rewrites every `[[uuid|Display]]` link (SCHEMA.md rule 7): to `[[slug|Display]]`
+ * — a Quartz-compatible wikilink — if the target is included in this build, or
+ * strips it to plain `Display` text otherwise (the resolved link-integrity rule,
+ * RENDER_PIPELINE.md).
+ */
+export declare function rewriteLinks(text: string, slugsById: Map<string, string>): string;
+export declare function rewriteFrontmatterLinks(frontmatter: Record<string, unknown>, slugsById: Map<string, string>): Record<string, unknown>;

package/dist/render-pipeline/rewrite.js

@@ -0,0 +1,23 @@
+const WIKILINK_RE = /\[\[([0-9a-f-]{36})\|([^\]]*)\]\]/gi;
+/**
+ * Rewrites every `[[uuid|Display]]` link (SCHEMA.md rule 7): to `[[slug|Display]]`
+ * — a Quartz-compatible wikilink — if the target is included in this build, or
+ * strips it to plain `Display` text otherwise (the resolved link-integrity rule,
+ * RENDER_PIPELINE.md).
+ */
+export function rewriteLinks(text, slugsById) {
+    return text.replace(WIKILINK_RE, (_match, targetId, display) => {
+        const slug = slugsById.get(targetId);
+        return slug ? `[[${slug}|${display}]]` : display;
+    });
+}
+function rewriteValue(value, slugsById) {
+    if (typeof value === "string")
+        return rewriteLinks(value, slugsById);
+    if (Array.isArray(value))
+        return value.map((entry) => rewriteValue(entry, slugsById));
+    return value;
+}
+export function rewriteFrontmatterLinks(frontmatter, slugsById) {
+    return Object.fromEntries(Object.entries(frontmatter).map(([key, value]) => [key, rewriteValue(value, slugsById)]));
+}

package/dist/render-pipeline/slugs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Assigns a unique, readable slug per id — vault files are UUID-named (SCHEMA.md),
+ * meaningless as a published URL; this is what Stage 1 uses instead for the
+ * derived tree. Iterates `titles` in whatever order the caller provides, so pass
+ * ids in a deterministic order for reproducible builds.
+ */
+export declare function assignSlugs(titles: Map<string, string>): Map<string, string>;

package/dist/render-pipeline/slugs.js

@@ -0,0 +1,30 @@
+function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "untitled";
+}
+/**
+ * Assigns a unique, readable slug per id — vault files are UUID-named (SCHEMA.md),
+ * meaningless as a published URL; this is what Stage 1 uses instead for the
+ * derived tree. Iterates `titles` in whatever order the caller provides, so pass
+ * ids in a deterministic order for reproducible builds.
+ */
+export function assignSlugs(titles) {
+    const used = new Set();
+    const slugs = new Map();
+    for (const [id, title] of titles) {
+        const base = slugify(title);
+        let slug = base;
+        let suffix = 2;
+        while (used.has(slug)) {
+            slug = `${base}-${suffix}`;
+            suffix += 1;
+        }
+        used.add(slug);
+        slugs.set(id, slug);
+    }
+    return slugs;
+}

package/dist/render-pipeline/sync.d.ts

@@ -0,0 +1,9 @@
+import type { RenderedPage } from "./types.js";
+/**
+ * Writes the derived tree into a Quartz content folder, first clearing any
+ * `.md` files already there. Plain writeDerivedTree alone isn't enough here —
+ * without clearing first, a page removed/renamed by a later build (e.g. a
+ * build-variant query change, or an entity dropping out of range) would leave
+ * a stale, orphaned page behind in Quartz's content folder.
+ */
+export declare function syncDerivedTreeToQuartz(quartzContentDir: string, pages: RenderedPage[]): Promise<void>;

package/dist/render-pipeline/sync.js

@@ -0,0 +1,18 @@
+import { mkdir, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { writeDerivedTree } from "./write.js";
+/**
+ * Writes the derived tree into a Quartz content folder, first clearing any
+ * `.md` files already there. Plain writeDerivedTree alone isn't enough here —
+ * without clearing first, a page removed/renamed by a later build (e.g. a
+ * build-variant query change, or an entity dropping out of range) would leave
+ * a stale, orphaned page behind in Quartz's content folder.
+ */
+export async function syncDerivedTreeToQuartz(quartzContentDir, pages) {
+    await mkdir(quartzContentDir, { recursive: true });
+    const existing = await readdir(quartzContentDir);
+    await Promise.all(existing
+        .filter((name) => name.endsWith(".md"))
+        .map((name) => rm(path.join(quartzContentDir, name))));
+    await writeDerivedTree(quartzContentDir, pages);
+}

package/dist/render-pipeline/types.d.ts

@@ -0,0 +1,8 @@
+export type { BuildVariantQuery } from "../core/query/index.js";
+export interface RenderedPage {
+    /** The original vault id (an event id, or an entity's anchor id). */
+    id: string;
+    slug: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}

package/dist/render-pipeline/types.js

@@ -0,0 +1 @@
+export {};

package/dist/render-pipeline/write.d.ts

@@ -0,0 +1,3 @@
+import type { RenderedPage } from "./types.js";
+/** Writes the derived tree to disk as plain markdown, ready for Stage 2 (Quartz) to build from later. */
+export declare function writeDerivedTree(outputDir: string, pages: RenderedPage[]): Promise<void>;

package/dist/render-pipeline/write.js

@@ -0,0 +1,12 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { writeFile } from "node:fs/promises";
+import { serializeVaultFile } from "../core/vault/index.js";
+/** Writes the derived tree to disk as plain markdown, ready for Stage 2 (Quartz) to build from later. */
+export async function writeDerivedTree(outputDir, pages) {
+    await mkdir(outputDir, { recursive: true });
+    for (const page of pages) {
+        const content = serializeVaultFile({ frontmatter: page.frontmatter, body: page.body });
+        await writeFile(path.join(outputDir, `${page.slug}.md`), content, "utf8");
+    }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "world-building-framework",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Build, search and publish fictional worlds from a vault of Markdown files: the wbf CLI and its core engine.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "wbf": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node scripts/run-tests.mjs",
+    "cli": "tsx src/cli/index.ts",
+    "setup:quartz": "tsx src/cli/index.ts setup-quartz",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "better-sqlite3": "^13.0.3",
+    "commander": "^15.0.0",
+    "gray-matter": "^4.0.3",
+    "uuid": "^14.0.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^22.20.1",
+    "glob": "^13.0.6",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.4"
+  }
+}