world-building-framework 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,11 @@
+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 "./start-page.js";
+export * from "./build.js";
+export * from "./write.js";
+export * from "./sync.js";

package/dist/render-pipeline/index.js

@@ -0,0 +1,11 @@
+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 "./start-page.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,8 @@
+/**
+ * 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. No page gets a slug
+ * in `reserved` (e.g. the start page's "index").
+ */
+export declare function assignSlugs(titles: Map<string, string>, reserved?: string[]): Map<string, string>;

package/dist/render-pipeline/slugs.js

@@ -0,0 +1,31 @@
+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. No page gets a slug
+ * in `reserved` (e.g. the start page's "index").
+ */
+export function assignSlugs(titles, reserved = []) {
+    const used = new Set(reserved);
+    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/start-page.d.ts

@@ -0,0 +1,9 @@
+import type { RenderedPage } from "./types.js";
+/** Quartz builds a site's root page from `content/index.md`; without it, the wiki's own address is a 404. */
+export declare const START_PAGE_SLUG = "index";
+/**
+ * The wiki's start page: every included entity, grouped by entityType and sorted
+ * by title, then every included event in causal order. `events` must already be
+ * in that order; only pages of this build go in, so nothing filtered out shows up.
+ */
+export declare function buildStartPage(title: string, entities: RenderedPage[], events: RenderedPage[]): RenderedPage;

package/dist/render-pipeline/start-page.js

@@ -0,0 +1,44 @@
+/** Quartz builds a site's root page from `content/index.md`; without it, the wiki's own address is a 404. */
+export const START_PAGE_SLUG = "index";
+function titleOf(page) {
+    return typeof page.frontmatter.title === "string" ? page.frontmatter.title : page.slug;
+}
+function linkTo(page) {
+    return `[[${page.slug}|${titleOf(page)}]]`;
+}
+function describeDate(page) {
+    const date = page.frontmatter.worldDate;
+    if (typeof date?.year !== "number")
+        return "";
+    return typeof date.day === "number" ? ` (year ${date.year}, day ${date.day})` : ` (year ${date.year})`;
+}
+function heading(entityType) {
+    return entityType.charAt(0).toUpperCase() + entityType.slice(1);
+}
+/**
+ * The wiki's start page: every included entity, grouped by entityType and sorted
+ * by title, then every included event in causal order. `events` must already be
+ * in that order; only pages of this build go in, so nothing filtered out shows up.
+ */
+export function buildStartPage(title, entities, events) {
+    const groups = new Map();
+    for (const page of entities) {
+        const entityType = typeof page.frontmatter.entityType === "string" ? page.frontmatter.entityType : "";
+        groups.set(entityType, [...(groups.get(entityType) ?? []), page]);
+    }
+    // Typed groups alphabetically, untyped entities last.
+    const groupKeys = [...groups.keys()].sort((a, b) => (a === "" ? 1 : b === "" ? -1 : a.localeCompare(b)));
+    const sections = groupKeys.map((key) => {
+        const pages = groups.get(key).sort((a, b) => titleOf(a).localeCompare(titleOf(b)));
+        return `## ${key === "" ? "Other" : heading(key)}\n\n${pages.map((page) => `- ${linkTo(page)}`).join("\n")}`;
+    });
+    if (events.length > 0) {
+        sections.push(`## Events\n\n${events.map((page) => `- ${linkTo(page)}${describeDate(page)}`).join("\n")}`);
+    }
+    return {
+        id: START_PAGE_SLUG,
+        slug: START_PAGE_SLUG,
+        frontmatter: { title },
+        body: sections.length > 0 ? `${sections.join("\n\n")}\n` : "Nothing here yet.\n",
+    };
+}

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.1",
+  "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": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^22.20.1",
+    "glob": "^13.0.6",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.4"
+  }
+}

package/skills/world-vault/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: world-vault
+description: Search, create, correct, and validate entity/event files in a World Building Framework world via the `wbf` CLI. Use whenever the user wants to look up, add, or change world-building content (characters, locations, events, factions, ...) in this repo.
+---
+
+# World Vault authoring
+
+This repo is a world built with the World Building Framework. Its content is a vault of entity/event Markdown files, named by UUID, next to a `world.config.json`. You read and write it through the `wbf` command-line tool, which prints JSON.
+
+**Never hand-write or hand-edit a vault file.** Only `wbf create` and `wbf update` validate content before it touches disk, and only `create` generates the required UUID filename.
+
+Run every command from the repo root as `npx wbf <command>`. That runs the framework version installed in this repo. If it reports "No vault specified", you're not in the folder that holds `world.config.json`: change into it, or pass `--vault <path>`.
+
+Commands that take JSON input read it from stdin, or from a file with `--input <file>`. Use a file when piping is awkward in your shell.
+
+## 1. Check the current schema before writing anything
+
+```
+npx wbf schema
+```
+
+This prints the framework's fixed fields, plus this world's own `entityType` list from `world.config.json`, if it declares one. Run it whenever you're unsure which fields are valid, especially before creating an entity with an `entityType` you haven't seen used here yet.
+
+## 2. Search before creating
+
+Search for what already exists before adding anything. That avoids duplicating an entity, and gives you the UUIDs you need to link to things:
+
+```
+npx wbf search <query terms...>
+```
+
+Each result has an `id` (the UUID you link with), `title` and `score`, and for entities `entityType` and `tags`. Add `--tags a,b` to require specific tags, and `--limit N` to cap the results.
+
+## 3. Writing links
+
+Every relation, in frontmatter or in body text, uses this link form: the target's UUID before the pipe, and its current title after it.
+
+```
+[[3af2c9d1-8b4e-4c6a-91f0-2d5e7a9b1c33|Port Kavas]]
+```
+
+Get the UUID from a search result's `id`, or from the `id` a `create` call just returned. Never write a bare `[[Display Name]]`. The vault only resolves links by UUID.
+
+## 4. Propose before writing
+
+No tool here enforces an approval step, so that's your job. Before calling `create` or `update`, show the user the frontmatter and body you're about to write, and wait for their go-ahead, the way you'd show a diff before editing code.
+
+## 5. Validate before (or instead of) creating
+
+To check a candidate without writing it:
+
+```
+echo '{"frontmatter": {"type": "entity", "title": "Alea Vantorr", "entityType": "character"}}' | npx wbf validate --input -
+```
+
+Each issue has a `severity`:
+- Fix every `"error"` (schema problems, dangling links, wrong link targets) before calling `create`.
+- A `"warning"` (e.g. an event with no `entities` yet) doesn't block anything. Mention it to the user, but it's fine to proceed.
+
+`create` runs these same checks, so `valid: true` here means `create` will succeed.
+
+## 6. Creating a file
+
+```
+echo '{"frontmatter": {...}, "body": "..."}' | npx wbf create
+```
+
+- **Required fields:** `type` and `title`. Everything else depends on whether it's an entity or an event; see `npx wbf schema`.
+- **On success** it prints `{"written": true, "id": "...", "path": "..."}`, plus an `issues` list if there were warnings. Tell the user the new `id`, since anything that links to this file needs that UUID.
+- **If any link points at an id that doesn't exist**, nothing is written, and the error is reported instead.
+
+## 7. Correcting an existing file
+
+For a **correction** (a typo, a wrong tag, a missing link, badly written text), replace the file in place:
+
+```
+echo '{"frontmatter": {...}, "body": "..."}' | npx wbf update --id <uuid>
+```
+
+- **Send the complete content.** The input is the file's whole new content, not just the changed fields. Read the current file (`<uuid>.md`) first, change what needs changing, and send all of it. Any field you leave out is removed.
+- **Same checks as `create`**, and `type` can't change.
+- **Show the user what you're changing** before calling it, as with `create`.
+
+Changing a `title` also changes **other files**:
+- Every link elsewhere written as `[[<uuid>|<old title>]]` is rewritten to show the new title.
+- Links with different display text, like `[[<uuid>|the old harbour]]`, are left alone.
+- When proposing a rename, tell the user other files will be updated too. Search the vault for `[[<uuid>|<old title>]]` to say which ones.
+- The result lists them under `relinked`. Any file under `relinkFailed` is already invalid on its own and kept the old name; report it to the user.
+
+`update` is only for things that were wrong. If something changed **in the story**, use section 8 instead.
+
+## 8. Recording a change to an existing entity: never edit it in place
+
+When an event changes something about an entity (it looks different, its status changed, and so on), that's **not** an edit to the existing file. Create a **new** entity file with these two fields:
+- `supersedes`: a link to the entity's current file. That's its **latest** version, not the anchor, unless the anchor is the only version so far. A "Fork in the version chain" warning almost always means you pointed at an older version. Tell the user and fix it with `update`, unless they deliberately want a story branch.
+- `causedBy`: a link to the event that caused the change.
+
+Both fields are required together. The vault keeps every version, and the published wiki shows the whole history. Never overwrite an entity file's body to reflect an in-world change; that erases history the vault is designed to keep.
+
+Other files always link to an entity's **original, first-ever** file (its anchor), never to a later version. If you're not sure which id is the anchor, follow the file's `supersedes` chain back. Or reuse whatever id you already have for that entity: that's always the anchor once created.

package/templates/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent instructions
+
+This repo is a world built with the World Building Framework (version __WBF_VERSION__). Its content is a vault of UUID-named Markdown files next to `world.config.json`.
+
+- Read and write the vault only through the `wbf` command-line tool: run `npx wbf <command>` from this folder. It prints JSON.
+- Run `npx wbf schema` before writing anything, `npx wbf search <terms>` before creating something, and `npx wbf --help` for every command.
+- Never hand-write or hand-edit a vault `.md` file. Only `wbf create` and `wbf update` validate content, and only `create` generates the required UUID filename.
+- Show the user what you're about to write, and wait for their go-ahead, before `create` or `update`.
+- If skills were installed for your agent (`npx wbf init --agent <name>`), the `world-vault` skill has the full workflow.
+
+Generated by `wbf init`. `npx wbf refresh` keeps it current while it's unedited.

package/templates/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+# Quartz's working copy, fetched by wbf on demand
+.wbf/quartz/
+# Local publish output
+site/

package/templates/publish.yml

@@ -0,0 +1,54 @@
+# Generated by world-building-framework __WBF_VERSION__ (`wbf init`).
+# `npx wbf refresh` updates this file to the installed framework version, but
+# only while you haven't edited it. Once you change it, it's yours to maintain.
+name: Publish wiki
+
+on:
+  push:
+    branches: [__BRANCH__]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install the framework (version pinned in package.json)
+        run: npm ci
+
+      # Runs before publish so its base_url output (the Pages site's real
+      # address) can be handed to Quartz.
+      - uses: actions/configure-pages@v5
+        id: pages
+
+      - name: Publish every build variant
+        run: npx wbf publish --output ./site --base-url "${{ steps.pages.outputs.base_url }}"
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment