world-building-framework 0.0.0-stage → 0.2.1

package/dist/cli/commands/update.d.ts

@@ -0,0 +1,23 @@
+import { type ValidationIssue } from "../../core/schema/index.js";
+import { type CreateOutcome } from "./create.js";
+export interface UpdateOutcome extends CreateOutcome {
+    /** Other files whose links were rewritten to show the new title. */
+    relinked?: string[];
+    /** Other files whose links couldn't be rewritten, because the file itself fails validation. */
+    relinkFailed?: {
+        id: string;
+        issues: ValidationIssue[];
+    }[];
+}
+/**
+ * Replaces an existing file's frontmatter and body in place — for corrections
+ * (typos, a wrong tag, a missing link), not in-world changes, which are a new
+ * version file instead (SCHEMA.md rule 8). The input is the complete new
+ * content, not a patch. Same checks as create, plus `type` may not change:
+ * turning an entity into an event (or back) would break every file linking to it.
+ *
+ * If the title changes, every link elsewhere whose display text is exactly the
+ * old title is rewritten to the new one (see replaceLinkDisplay), so a
+ * corrected typo doesn't live on in other files' link text.
+ */
+export declare function runUpdate(vaultOption: string | undefined, id: string, rawInput: unknown): Promise<UpdateOutcome>;

package/dist/cli/commands/update.js

@@ -0,0 +1,69 @@
+import { readVault, writeVaultFile, replaceLinkDisplay } from "../../core/vault/index.js";
+import { hasErrors } from "../../core/schema/index.js";
+import { loadWorldConfig, validateOptionsFromConfig } from "../../core/config/index.js";
+import { resolveVaultDir } from "../vault-path.js";
+import { createLintContext } from "../../core/lint/index.js";
+import { checkFile } from "../check.js";
+import { fileInputSchema } from "./create.js";
+/**
+ * Replaces an existing file's frontmatter and body in place — for corrections
+ * (typos, a wrong tag, a missing link), not in-world changes, which are a new
+ * version file instead (SCHEMA.md rule 8). The input is the complete new
+ * content, not a patch. Same checks as create, plus `type` may not change:
+ * turning an entity into an event (or back) would break every file linking to it.
+ *
+ * If the title changes, every link elsewhere whose display text is exactly the
+ * old title is rewritten to the new one (see replaceLinkDisplay), so a
+ * corrected typo doesn't live on in other files' link text.
+ */
+export async function runUpdate(vaultOption, id, rawInput) {
+    const vaultDir = resolveVaultDir(vaultOption);
+    const input = fileInputSchema.parse(rawInput);
+    const config = await loadWorldConfig(vaultDir);
+    const options = validateOptionsFromConfig(config);
+    const files = await readVault(vaultDir);
+    const existing = files.find((file) => file.id === id);
+    if (!existing)
+        throw new Error(`No file with id "${id}" in this vault.`);
+    const issues = checkFile({ id, ...input }, options, createLintContext(files));
+    if (input.frontmatter.type !== existing.frontmatter.type) {
+        issues.unshift({
+            path: "type",
+            message: `"type" can't change (was ${JSON.stringify(existing.frontmatter.type)}) — create a new file instead`,
+            severity: "error",
+        });
+    }
+    if (hasErrors(issues)) {
+        return { written: false, issues };
+    }
+    const result = await writeVaultFile(vaultDir, id, input.frontmatter, input.body, options);
+    if (!result.written) {
+        return { written: false, issues: result.issues };
+    }
+    const outcome = { written: true, id: result.id, path: result.path };
+    if (issues.length > 0)
+        outcome.issues = issues;
+    const oldTitle = existing.frontmatter.title;
+    const newTitle = input.frontmatter.title;
+    if (typeof oldTitle === "string" && typeof newTitle === "string" && oldTitle !== newTitle) {
+        const relinked = [];
+        const relinkFailed = [];
+        for (const file of files) {
+            if (file.id === id)
+                continue;
+            const replaced = replaceLinkDisplay(file, id, oldTitle, newTitle);
+            if (!replaced)
+                continue;
+            const written = await writeVaultFile(vaultDir, file.id, replaced.frontmatter, replaced.body, options);
+            if (written.written)
+                relinked.push(file.id);
+            else
+                relinkFailed.push({ id: file.id, issues: written.issues });
+        }
+        if (relinked.length > 0)
+            outcome.relinked = relinked;
+        if (relinkFailed.length > 0)
+            outcome.relinkFailed = relinkFailed;
+    }
+    return outcome;
+}

package/dist/cli/commands/validate.d.ts

@@ -0,0 +1,21 @@
+import { type ValidationIssue } from "../../core/schema/index.js";
+export interface ValidateOutcome {
+    id?: string;
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+export interface ValidateRequest {
+    /** Validate one existing vault file by id. */
+    id?: string;
+    /** Validate a not-yet-written candidate ({"frontmatter": {...}, "body": "..."}) instead of vault files. */
+    candidate?: unknown;
+}
+/**
+ * Three modes: validate a candidate that hasn't been written yet (candidate),
+ * validate one existing file (id), or validate the whole vault (neither) — an
+ * explicit lint pass, distinct from readVault which never validates. All three
+ * run both core/schema's structural validation and core/lint's checks
+ * (dangling links, events without entities) — the vault is always read in
+ * full since dangling-link checking needs every known id as context.
+ */
+export declare function runValidate(vaultOption: string | undefined, request: ValidateRequest): Promise<ValidateOutcome | ValidateOutcome[]>;

package/dist/cli/commands/validate.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { readVault } from "../../core/vault/index.js";
+import { hasErrors } from "../../core/schema/index.js";
+import { createLintContext } from "../../core/lint/index.js";
+import { checkFile } from "../check.js";
+import { loadWorldConfig, validateOptionsFromConfig } from "../../core/config/index.js";
+import { resolveVaultDir } from "../vault-path.js";
+const candidateInputSchema = z.object({
+    frontmatter: z.record(z.string(), z.unknown()),
+    body: z.string().optional(),
+});
+/**
+ * Three modes: validate a candidate that hasn't been written yet (candidate),
+ * validate one existing file (id), or validate the whole vault (neither) — an
+ * explicit lint pass, distinct from readVault which never validates. All three
+ * run both core/schema's structural validation and core/lint's checks
+ * (dangling links, events without entities) — the vault is always read in
+ * full since dangling-link checking needs every known id as context.
+ */
+export async function runValidate(vaultOption, request) {
+    const vaultDir = resolveVaultDir(vaultOption);
+    const config = await loadWorldConfig(vaultDir);
+    const options = validateOptionsFromConfig(config);
+    const files = await readVault(vaultDir);
+    const context = createLintContext(files);
+    // Warnings (e.g. an event with no entities) are reported but never make a file invalid.
+    const check = (file) => checkFile(file, options, context);
+    if (request.candidate !== undefined) {
+        const { frontmatter, body } = candidateInputSchema.parse(request.candidate);
+        const issues = check({ frontmatter, body: body ?? "" });
+        return { valid: !hasErrors(issues), issues };
+    }
+    if (request.id) {
+        const file = files.find((f) => f.id === request.id);
+        if (!file)
+            throw new Error(`No file with id "${request.id}" in this vault.`);
+        const issues = check(file);
+        return { id: file.id, valid: !hasErrors(issues), issues };
+    }
+    return files.map((file) => {
+        const issues = check(file);
+        return { id: file.id, valid: !hasErrors(issues), issues };
+    });
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { runSchema } from "./commands/schema.js";
+import { runInit } from "./commands/init.js";
+import { runRefresh } from "./commands/refresh.js";
+import { runCreate } from "./commands/create.js";
+import { runUpdate } from "./commands/update.js";
+import { runValidate } from "./commands/validate.js";
+import { runSearch } from "./commands/search.js";
+import { runRender } from "./commands/render.js";
+import { runListVariants } from "./commands/list-variants.js";
+import { runPublish } from "./commands/publish.js";
+import { readJsonInput } from "./io.js";
+import { resolveQuartzDir } from "./quartz-runner.js";
+import { setupQuartz, isQuartzReady, QUARTZ_VERSION } from "./quartz-setup.js";
+function handle(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            console.error(JSON.stringify({ error: err.message }, null, 2));
+            process.exitCode = 1;
+        }
+    };
+}
+const program = new Command();
+// ../../package.json from both src/cli (dev) and dist/cli (installed package).
+const { version } = createRequire(import.meta.url)("../../package.json");
+program.name("wbf").description("World Building Framework CLI").version(version);
+program
+    .command("init")
+    .description("Set up the current folder as a world repo: config, publish workflow, AGENTS.md, and agent skills. Never overwrites existing files")
+    .option("--dir <path>", "folder to set up (default: current folder)")
+    .option("--title <title>", "the world's display title (default: derived from the folder name)")
+    .option("--agent <name>", "install skills for this AI agent; repeat for several", (value, previous) => [...previous, value], [])
+    .option("--branch <name>", "branch the publish workflow runs on (default: the repo's current branch, else main)")
+    .action(handle(async (opts) => {
+    const outcome = await runInit({ dir: opts.dir, title: opts.title, agents: opts.agent, branch: opts.branch });
+    console.log(JSON.stringify(outcome, null, 2));
+}));
+program
+    .command("refresh")
+    .description("Update the files wbf init generated (workflow, AGENTS.md, skills) to the installed framework version. Keeps files you edited")
+    .option("--dir <path>", "world repo root (default: current folder)")
+    .option("--force", "also overwrite files that were edited, deleted, or not generated by wbf", false)
+    .action(handle(async (opts) => {
+    console.log(JSON.stringify(await runRefresh({ dir: opts.dir, force: opts.force }), null, 2));
+}));
+program
+    .command("schema")
+    .description("Print the current, authoritative vault schema")
+    .option("-v, --vault <path>", "vault directory")
+    .action(handle(async (opts) => {
+    console.log(await runSchema(opts.vault));
+}));
+program
+    .command("create")
+    .description("Create a new vault file")
+    .option("-v, --vault <path>", "vault directory")
+    .option("-i, --input <path>", 'JSON input ({"frontmatter": {...}, "body": "..."}); omit or "-" for stdin')
+    .action(handle(async (opts) => {
+    const input = await readJsonInput(opts.input);
+    const outcome = await runCreate(opts.vault, input);
+    console.log(JSON.stringify(outcome, null, 2));
+    if (!outcome.written)
+        process.exitCode = 1;
+}));
+program
+    .command("update")
+    .description("Replace an existing vault file's content (corrections only — in-world changes are a new version)")
+    .option("-v, --vault <path>", "vault directory")
+    .requiredOption("--id <id>", "id of the file to replace")
+    .option("-i, --input <path>", 'complete new content as JSON ({"frontmatter": {...}, "body": "..."}); omit or "-" for stdin')
+    .action(handle(async (opts) => {
+    const input = await readJsonInput(opts.input);
+    const outcome = await runUpdate(opts.vault, opts.id, input);
+    console.log(JSON.stringify(outcome, null, 2));
+    if (!outcome.written)
+        process.exitCode = 1;
+}));
+program
+    .command("validate")
+    .description("Validate vault file(s), or a candidate that hasn't been written yet")
+    .option("-v, --vault <path>", "vault directory")
+    .option("--id <id>", "validate one existing file by id")
+    .option("-i, --input <path>", 'validate a candidate JSON payload ({"frontmatter": {...}, "body": "..."}) instead of vault files')
+    .action(handle(async (opts) => {
+    const candidate = opts.input !== undefined ? await readJsonInput(opts.input) : undefined;
+    const outcome = await runValidate(opts.vault, { id: opts.id, candidate });
+    console.log(JSON.stringify(outcome, null, 2));
+    const allValid = Array.isArray(outcome) ? outcome.every((o) => o.valid) : outcome.valid;
+    if (!allValid)
+        process.exitCode = 1;
+}));
+program
+    .command("search")
+    .description("Keyword search over the vault")
+    .argument("<query...>", "search terms")
+    .option("-v, --vault <path>", "vault directory")
+    .option("-t, --tags <tags>", "comma-separated tags, all required")
+    .option("-l, --limit <n>", "max results", (value) => parseInt(value, 10))
+    .action(handle(async (queryParts, opts) => {
+    const tags = opts.tags ? opts.tags.split(",").map((tag) => tag.trim()) : undefined;
+    const results = await runSearch(opts.vault, queryParts.join(" "), { tags, limit: opts.limit });
+    console.log(JSON.stringify(results, null, 2));
+}));
+program
+    .command("render")
+    .description("Build a named build variant's derived tree and sync it into Quartz's content folder")
+    .option("-v, --vault <path>", "vault directory")
+    .requiredOption("--variant <name>", "named build variant from this vault's world.config.json")
+    .option("--quartz-dir <path>", "Quartz project directory (default: ./.wbf/quartz, or WBF_QUARTZ_DIR)")
+    .option("--build", "also run `quartz build` after syncing", false)
+    .option("--output <dir>", "output directory for the Quartz build (only used with --build)")
+    .action(handle(async (opts) => {
+    const outcome = await runRender(opts.vault, {
+        variant: opts.variant,
+        quartzDir: opts.quartzDir,
+        build: opts.build,
+        outputDir: opts.output,
+    });
+    console.log(JSON.stringify(outcome, null, 2));
+}));
+program
+    .command("setup-quartz")
+    .description("Fetch, install and initialize Quartz at the pinned version (default location: ./.wbf/quartz). Safe to re-run")
+    .option("--quartz-dir <path>", "Quartz project directory (default: ./.wbf/quartz, or WBF_QUARTZ_DIR)")
+    .action(handle(async (opts) => {
+    const quartzDir = resolveQuartzDir(opts.quartzDir);
+    await setupQuartz(quartzDir);
+    console.log(JSON.stringify({ quartzDir, version: QUARTZ_VERSION, ready: isQuartzReady(quartzDir) }, null, 2));
+}));
+program
+    .command("list-variants")
+    .description("List this vault's declared build variants (world.config.json)")
+    .option("-v, --vault <path>", "vault directory")
+    .action(handle(async (opts) => {
+    console.log(JSON.stringify(await runListVariants(opts.vault), null, 2));
+}));
+program
+    .command("publish")
+    .description("Build every declared build variant into its own subpath of one combined output tree, plus a landing page")
+    .option("-v, --vault <path>", "vault directory")
+    .option("--quartz-dir <path>", "Quartz project directory (default: ./.wbf/quartz, or WBF_QUARTZ_DIR)")
+    .requiredOption("--output <dir>", "combined output directory (each variant gets a subfolder here)")
+    .option("--base-url <url>", "public URL of the combined site; each variant is built with <url>/<variant> as Quartz's baseUrl")
+    .action(handle(async (opts) => {
+    const outcome = await runPublish(opts.vault, {
+        quartzDir: opts.quartzDir,
+        outputDir: opts.output,
+        baseUrl: opts.baseUrl,
+    });
+    console.log(JSON.stringify(outcome, null, 2));
+}));
+await program.parseAsync(process.argv);

package/dist/cli/io.d.ts

@@ -0,0 +1,4 @@
+/** Reads text from a file path, or from stdin when path is omitted or "-". */
+export declare function readTextInput(path: string | undefined): Promise<string>;
+/** Reads and parses a JSON payload from a file path, or from stdin when path is omitted or "-". */
+export declare function readJsonInput(path: string | undefined): Promise<unknown>;

package/dist/cli/io.js

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** Reads text from a file path, or from stdin when path is omitted or "-". */
+export async function readTextInput(path) {
+    if (!path || path === "-") {
+        return readStdin();
+    }
+    return readFile(path, "utf8");
+}
+/** Reads and parses a JSON payload from a file path, or from stdin when path is omitted or "-". */
+export async function readJsonInput(path) {
+    const raw = await readTextInput(path);
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Input is not valid JSON: ${err.message}`);
+    }
+}

package/dist/cli/managed-files.d.ts

@@ -0,0 +1,35 @@
+/** The installed package's root: ../.. from both src/cli (dev) and dist/cli (installed package). */
+export declare const PACKAGE_ROOT: string;
+/**
+ * Where each supported agent looks for project skills (open SKILL.md format).
+ * Only folders confirmed in the agent's own docs belong here
+ * (claude-dev/DISTRIBUTION_PLAN.md, component 6).
+ */
+export declare const AGENT_SKILL_DIRS: Record<string, string>;
+/** Settings that decide how managed files render; stored so `refresh` renders them the same way. */
+export interface ManagedSettings {
+    branch: string;
+    agents: string[];
+}
+/** The record of generated files, kept in the world repo (committed) at MANIFEST_PATH. */
+export interface Manifest extends ManagedSettings {
+    frameworkVersion: string;
+    /** Repo-relative path (forward slashes) -> content hash of what wbf last wrote there. */
+    files: Record<string, string>;
+}
+export declare const MANIFEST_PATH = ".wbf/managed.json";
+/**
+ * Content hash, ignoring line endings: git may check a file out with CRLF on
+ * Windows, and that must not look like the user edited it.
+ */
+export declare function contentHash(content: string): string;
+export declare function readFrameworkVersion(): Promise<string>;
+/**
+ * The files wbf owns in a world repo, rendered for this framework version:
+ * the publish workflow, AGENTS.md, and the package's skills copied into each
+ * chosen agent's skill folder. Keyed by repo-relative path.
+ */
+export declare function renderManagedFiles(version: string, settings: ManagedSettings): Promise<Map<string, string>>;
+export declare function readManifest(rootDir: string): Promise<Manifest | undefined>;
+export declare function writeManifest(rootDir: string, manifest: Manifest): Promise<void>;
+export declare function writeRepoFile(rootDir: string, relPath: string, content: string): Promise<void>;

package/dist/cli/managed-files.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** The installed package's root: ../.. from both src/cli (dev) and dist/cli (installed package). */
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+/**
+ * Where each supported agent looks for project skills (open SKILL.md format).
+ * Only folders confirmed in the agent's own docs belong here
+ * (claude-dev/DISTRIBUTION_PLAN.md, component 6).
+ */
+export const AGENT_SKILL_DIRS = {
+    claude: ".claude/skills",
+};
+export const MANIFEST_PATH = ".wbf/managed.json";
+/**
+ * Content hash, ignoring line endings: git may check a file out with CRLF on
+ * Windows, and that must not look like the user edited it.
+ */
+export function contentHash(content) {
+    return createHash("sha256").update(content.replace(/\r\n/g, "\n")).digest("hex");
+}
+export async function readFrameworkVersion() {
+    const raw = await readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8");
+    return JSON.parse(raw).version;
+}
+async function template(name, version, branch) {
+    const raw = await readFile(path.join(PACKAGE_ROOT, "templates", name), "utf8");
+    return raw.replaceAll("__WBF_VERSION__", version).replaceAll("__BRANCH__", branch);
+}
+/** Every file under `dir`, as paths relative to it (forward slashes). */
+async function listFiles(dir, prefix = "") {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...(await listFiles(path.join(dir, entry.name), rel)));
+        else if (entry.isFile())
+            out.push(rel);
+    }
+    return out;
+}
+/**
+ * The files wbf owns in a world repo, rendered for this framework version:
+ * the publish workflow, AGENTS.md, and the package's skills copied into each
+ * chosen agent's skill folder. Keyed by repo-relative path.
+ */
+export async function renderManagedFiles(version, settings) {
+    const files = new Map();
+    files.set(".github/workflows/publish.yml", await template("publish.yml", version, settings.branch));
+    files.set("AGENTS.md", await template("AGENTS.md", version, settings.branch));
+    const skillsDir = path.join(PACKAGE_ROOT, "skills");
+    const skillFiles = await listFiles(skillsDir);
+    for (const agent of settings.agents) {
+        const target = AGENT_SKILL_DIRS[agent];
+        if (!target)
+            throw new Error(`Unknown agent "${agent}". Supported: ${Object.keys(AGENT_SKILL_DIRS).join(", ")}`);
+        for (const rel of skillFiles) {
+            files.set(`${target}/${rel}`, await readFile(path.join(skillsDir, rel), "utf8"));
+        }
+    }
+    return files;
+}
+export async function readManifest(rootDir) {
+    const manifestFile = path.join(rootDir, MANIFEST_PATH);
+    if (!existsSync(manifestFile))
+        return undefined;
+    return JSON.parse(await readFile(manifestFile, "utf8"));
+}
+export async function writeManifest(rootDir, manifest) {
+    const manifestFile = path.join(rootDir, MANIFEST_PATH);
+    await mkdir(path.dirname(manifestFile), { recursive: true });
+    await writeFile(manifestFile, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+export async function writeRepoFile(rootDir, relPath, content) {
+    const target = path.join(rootDir, ...relPath.split("/"));
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, content, "utf8");
+}

package/dist/cli/quartz-runner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where Quartz's working copy lives: --quartz-dir, then WBF_QUARTZ_DIR, then
+ * `.wbf/quartz` in the current folder — in a world repo, that's the world's
+ * own root (claude-dev/DISTRIBUTION_PLAN.md, component 3).
+ */
+export declare function resolveQuartzDir(cliOption: string | undefined): string;
+/** Quartz's own baseUrl form: no protocol, no trailing slash (matches what `quartz create -b` stores). */
+export declare function normalizeBaseUrl(url: string): string;
+/**
+ * Sets `baseUrl`. It must be right per variant: Quartz uses its path part for
+ * absolute asset URLs (e.g. the 404 page), so a variant served at /<variant>/
+ * needs that subpath in its own baseUrl.
+ */
+export declare function setQuartzBaseUrl(quartzDir: string, baseUrl: string): Promise<void>;
+/** Sets `pageTitle`, the site name shown in every page's header. Quoted, so `:` or `"` in a title can't break the YAML. */
+export declare function setQuartzPageTitle(quartzDir: string, title: string): Promise<void>;
+/**
+ * Runs a Quartz build. `outputDir`, if given, must be absolute — it's passed
+ * straight through to Quartz's own `-o` flag, which resolves relative paths
+ * against its cwd (quartzDir), not the caller's.
+ */
+export declare function runQuartzBuild(quartzDir: string, outputDir?: string): Promise<void>;

package/dist/cli/quartz-runner.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+/**
+ * Where Quartz's working copy lives: --quartz-dir, then WBF_QUARTZ_DIR, then
+ * `.wbf/quartz` in the current folder — in a world repo, that's the world's
+ * own root (claude-dev/DISTRIBUTION_PLAN.md, component 3).
+ */
+export function resolveQuartzDir(cliOption) {
+    return cliOption ?? process.env.WBF_QUARTZ_DIR ?? path.join(process.cwd(), ".wbf", "quartz");
+}
+/** Quartz's own baseUrl form: no protocol, no trailing slash (matches what `quartz create -b` stores). */
+export function normalizeBaseUrl(url) {
+    return url.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+/**
+ * Replaces one `key: value` line in Quartz's quartz.config.yaml. `quartz build`
+ * has no flags for these settings — it only ever reads them from config — and
+ * quartz/ is fetched fresh in CI, so anything that must survive a build has to
+ * be written here right before it. `yamlValue` is written as-is.
+ */
+async function setQuartzConfigLine(quartzDir, key, yamlValue) {
+    const configPath = path.join(quartzDir, "quartz.config.yaml");
+    const lineRe = new RegExp(`^(\\s*${key}:).*$`, "m");
+    const raw = await readFile(configPath, "utf8");
+    if (!lineRe.test(raw)) {
+        throw new Error(`No ${key} line found in ${configPath} — has Quartz been initialized (wbf setup-quartz)?`);
+    }
+    await writeFile(configPath, raw.replace(lineRe, (_line, prefix) => `${prefix} ${yamlValue}`), "utf8");
+}
+/**
+ * Sets `baseUrl`. It must be right per variant: Quartz uses its path part for
+ * absolute asset URLs (e.g. the 404 page), so a variant served at /<variant>/
+ * needs that subpath in its own baseUrl.
+ */
+export function setQuartzBaseUrl(quartzDir, baseUrl) {
+    return setQuartzConfigLine(quartzDir, "baseUrl", normalizeBaseUrl(baseUrl));
+}
+/** Sets `pageTitle`, the site name shown in every page's header. Quoted, so `:` or `"` in a title can't break the YAML. */
+export function setQuartzPageTitle(quartzDir, title) {
+    return setQuartzConfigLine(quartzDir, "pageTitle", JSON.stringify(title));
+}
+/**
+ * Runs one Quartz step. Its output goes to our stderr, never stdout: the CLI's
+ * own JSON result is the only thing on stdout, so scripts and agents can parse it.
+ */
+function spawnStep(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", process.stderr, process.stderr], ...options });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+        });
+    });
+}
+/**
+ * Runs a Quartz build. `outputDir`, if given, must be absolute — it's passed
+ * straight through to Quartz's own `-o` flag, which resolves relative paths
+ * against its cwd (quartzDir), not the caller's.
+ */
+export async function runQuartzBuild(quartzDir, outputDir) {
+    // Quartz's package.json wires plugin installation as a "prebuild" npm lifecycle
+    // hook, which never fires when bootstrap-cli.mjs is invoked directly (as we do
+    // here) instead of via `npm run build` — verified hands-on: skipping this step
+    // left `.quartz/plugins` missing and the build failed. Replicate that hook
+    // explicitly rather than relying on invoking it the one specific way it happens
+    // to fire.
+    await spawnStep("npm", ["run", "install-plugins"], { cwd: quartzDir, shell: true });
+    const buildArgs = ["./quartz/bootstrap-cli.mjs", "build"];
+    if (outputDir)
+        buildArgs.push("-o", outputDir);
+    await spawnStep("node", buildArgs, { cwd: quartzDir });
+}

package/dist/cli/quartz-setup.d.ts

@@ -0,0 +1,10 @@
+export declare const QUARTZ_VERSION = "f1fba3fc55cbf60a60a5d09c95a49c042cdab63a";
+/** A Quartz working copy is usable once it's cloned, installed and initialized. */
+export declare function isQuartzReady(quartzDir: string): boolean;
+/**
+ * Fetches Quartz at the pinned commit into quartzDir, installs its dependencies
+ * and initializes it. Each step is skipped if already done, so it's safe to re-run.
+ */
+export declare function setupQuartz(quartzDir: string): Promise<void>;
+/** Sets Quartz up first if it isn't ready yet — so render --build and publish work on a fresh checkout. */
+export declare function ensureQuartz(quartzDir: string): Promise<void>;

package/dist/cli/quartz-setup.js

@@ -0,0 +1,59 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+// Pinned to a specific commit (not a moving branch, and deliberately NOT the
+// "v5.0.0" tag) for reproducible builds. The v5.0.0 tag itself has at least two
+// real bugs found hands-on — a missing .quartz/plugins folder (its own
+// package.json's plugin-install step never runs outside `npm run build`) and a
+// crash importing a raw .scss file — both absent on this later commit, which is
+// the exact state we validated end-to-end (see render-pipeline's
+// quartz-compat.ts for the one real fix that *was* needed against it).
+export const QUARTZ_VERSION = "f1fba3fc55cbf60a60a5d09c95a49c042cdab63a";
+const QUARTZ_REPO = "https://github.com/jackyzha0/quartz.git";
+/** A Quartz working copy is usable once it's cloned, installed and initialized. */
+export function isQuartzReady(quartzDir) {
+    return (existsSync(path.join(quartzDir, "quartz", "bootstrap-cli.mjs")) &&
+        existsSync(path.join(quartzDir, "node_modules")) &&
+        existsSync(path.join(quartzDir, "quartz.config.yaml")));
+}
+// shell:true is only needed to resolve npm's .cmd shim on Windows — using it for
+// plain executables (git, node) breaks argument quoting for paths containing
+// spaces, since the args array gets flattened into a shell command line.
+// Child output goes to stderr, so a command's own JSON result on stdout stays parseable.
+function run(command, args, cwd) {
+    const result = spawnSync(command, args, { cwd, stdio: ["ignore", 2, 2], shell: command === "npm" });
+    if (result.status !== 0) {
+        throw new Error(`Quartz setup failed: ${command} ${args.join(" ")} exited with code ${result.status ?? "unknown"}`);
+    }
+}
+/**
+ * Fetches Quartz at the pinned commit into quartzDir, installs its dependencies
+ * and initializes it. Each step is skipped if already done, so it's safe to re-run.
+ */
+export async function setupQuartz(quartzDir) {
+    if (!existsSync(path.join(quartzDir, "quartz", "bootstrap-cli.mjs"))) {
+        // git clone --branch only accepts a branch/tag name, not an arbitrary commit —
+        // this is the standard init/fetch/checkout pattern for shallow-cloning one
+        // specific commit (GitHub supports fetching a bare SHA for public repos).
+        console.error(`Cloning Quartz @ ${QUARTZ_VERSION} into ${quartzDir} ...`);
+        await mkdir(quartzDir, { recursive: true });
+        run("git", ["init", quartzDir]);
+        run("git", ["remote", "add", "origin", QUARTZ_REPO], quartzDir);
+        run("git", ["fetch", "--depth", "1", "origin", QUARTZ_VERSION], quartzDir);
+        run("git", ["checkout", "FETCH_HEAD"], quartzDir);
+    }
+    if (!existsSync(path.join(quartzDir, "node_modules"))) {
+        console.error("Installing Quartz's own dependencies ...");
+        run("npm", ["install"], quartzDir);
+    }
+    if (!existsSync(path.join(quartzDir, "quartz.config.yaml"))) {
+        console.error("Initializing Quartz (empty content folder, non-interactive) ...");
+        run("node", ["./quartz/bootstrap-cli.mjs", "create", "-X", "new", "-l", "shortest", "-t", "default", "-b", "localhost"], quartzDir);
+    }
+}
+/** Sets Quartz up first if it isn't ready yet — so render --build and publish work on a fresh checkout. */
+export async function ensureQuartz(quartzDir) {
+    if (!isQuartzReady(quartzDir))
+        await setupQuartz(quartzDir);
+}

package/dist/cli/vault-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Like resolveVaultDir, but returns undefined instead of throwing — for commands
+ * that are useful without a vault (e.g. `schema`).
+ */
+export declare function findVaultDir(cliOption: string | undefined): string | undefined;
+/** Resolves which vault to operate on: explicit flag, then WBF_VAULT_DIR, then the current folder if it has a world.config.json, then a single directory under ./vaults/. */
+export declare function resolveVaultDir(cliOption: string | undefined): string;