@topik/cli 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/cli.d.mts

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

package/dist/cli.mjs

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 import { boolean, command, positional, run, string } from "@drizzle-team/brocli";
-import { CompileError, compile, isErrorDiagnostic, lint, validateResources, watch } from "@topik/core";
-import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { extname, isAbsolute, join, relative, resolve } from "node:path";
-import { existsSync, realpathSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync } from "node:fs";
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { ManifestSourceError, PublicCompileError, TOPIK_PREVIEW_PROTOCOL, compile, isErrorDiagnostic, lint, parseStrictTopikJson, publicCompileErrorMessage, serializeTopikJson, validateResources, validateTopikMaterializationRecord, watch } from "@topik/core";
+import { sanitizeTopikContentDiagnostic } from "@topik/content";
 import { createServer } from "node:http";
 import { parseAllDocuments } from "yaml";
 //#region src/diagnostics.ts
 function formatDiagnostic(diagnostic) {
-	return `${diagnostic.file ?? "content"}${diagnostic.lines.length > 0 ? `:${diagnostic.lines.join(",")}` : ""} ${diagnostic.level} ${diagnostic.id}: ${diagnostic.message}`;
+	const sanitized = sanitizeTopikContentDiagnostic(diagnostic);
+	return `${sanitized.file ?? "content"}${sanitized.lines.length > 0 ? `:${sanitized.lines.join(",")}` : ""} ${sanitized.level} ${sanitized.id}: ${sanitized.message}`;
 }
 function printDiagnostics(diagnostics) {
 	for (const diagnostic of diagnostics) {
@@ -25,6 +28,39 @@ var CliError = class extends Error {
 		this.name = "CliError";
 	}
 };
+const PUBLIC_CLI_ERROR_MESSAGES = Object.freeze({
+	"browser-origin-invalid": "Browser origin configuration is invalid",
+	"compilation-publication-failed": "Compilation output publication failed after moving the existing output aside. For manual recovery, first stop concurrent writers, then inspect .topik-compilation-prior-* directories beside the output path. Verify the backup contents and do not overwrite an existing output path.",
+	"resource-access-failed": "Resource input could not be accessed.",
+	"resource-format-unsupported": "Resource input format is unsupported.",
+	"resource-json-invalid": "JSON resource input could not be parsed.",
+	"resource-jsonl-invalid": "JSONL resource input could not be parsed.",
+	"resource-read-failed": "Resource input could not be read.",
+	"resource-validation-failed": "Resource validation failed.",
+	"resource-yaml-invalid": "YAML resource input could not be parsed."
+});
+/** CLI failure admitted to presentation only through fixed catalog wording. */
+var PublicCliError = class extends CliError {
+	id;
+	constructor(id, options) {
+		super(publicCliErrorMessage(id) ?? "Topik command failed.", options);
+		this.name = "PublicCliError";
+		this.id = id;
+	}
+};
+function publicCliErrorMessage(id) {
+	return typeof id === "string" && Object.hasOwn(PUBLIC_CLI_ERROR_MESSAGES, id) ? PUBLIC_CLI_ERROR_MESSAGES[id] : void 0;
+}
+function formatPublicCliError(error) {
+	if (error instanceof PublicCliError) return publicCliErrorMessage(error.id) ?? "Topik command failed.";
+	if (error instanceof ManifestSourceError) {
+		const message = publicCompileErrorMessage(error.id) ?? "Topik command failed.";
+		const location = new PublicCompileError(error.id, error.location).location;
+		return `.topik.yaml ${Number.isSafeInteger(error.sourceIndex) && error.sourceIndex >= 0 ? `sources[${error.sourceIndex}]` : "source"}${error.kind === "wiki" || error.kind === "collection" || error.kind === "course" ? ` (${error.kind})` : ""}${location ? ` ${location}` : ""}: ${message}`;
+	}
+	if (error instanceof PublicCompileError) return publicCompileErrorMessage(error.id) ?? "Topik command failed.";
+	return "Topik command failed.";
+}
 //#endregion
 //#region src/validation-output.ts
 function formatValidationFailure(errors, resourceCount, context) {
@@ -35,40 +71,28 @@ function formatValidationFailure(errors, resourceCount, context) {
 }
 //#endregion
 //#region src/compile/index.ts
-const formatExtensions = {
-	json: ".json",
-	jsonl: ".jsonl",
-	yaml: ".yaml"
-};
-async function toYaml(value) {
-	if (process.versions.bun) return Bun.YAML.stringify(value);
-	const { stringify } = await import("yaml");
-	return stringify(value);
-}
-function serialize(resource, format) {
-	switch (format) {
-		case "json": return Promise.resolve(JSON.stringify(resource, null, 2) + "\n");
-		case "jsonl": return Promise.resolve(JSON.stringify(resource) + "\n");
-		case "yaml": return toYaml(resource);
-	}
-}
+const COMPILATION_GENERATION_PREFIX = ".topik-compilation-generation-";
+const COMPILATION_PRIOR_PREFIX = ".topik-compilation-prior-";
+const COMPILATION_DIRECTORIES = ["blobs", "resources"];
+const ownedDescriptorDecoder = new TextDecoder("utf-8", { fatal: true });
+const ownedDescriptorEncoder = new TextEncoder();
 const compile$1 = command({
 	name: "compile",
-	desc: "Compile wiki content into Topik resource files",
+	desc: "Compile project content into Topik resource files",
 	options: {
-		dir: positional("dir").desc("Path to the content directory").default("."),
+		dir: positional("dir").desc("Project directory containing .topik.yaml").default("."),
 		outDir: string("out-dir").alias("o").desc("Output directory for compiled resources"),
-		format: string("format").alias("f").desc("Output format").enum("json", "jsonl", "yaml").default("json"),
+		format: string("format").alias("f").desc("Output format (canonical JSON only)").enum("json").default("json"),
 		dryRun: boolean("dry-run").desc("Show what would be compiled without writing files").default(false),
-		clean: boolean("clean").desc("Remove existing output before compiling").default(false),
 		validate: boolean("validate").desc("Validate compiled resources against schemas").default(false),
 		links: string("links").desc("How unresolved wiki links and local guide fragments are handled").enum("error", "warning", "off").default("error")
 	},
 	handler: async (options) => {
 		const dir = resolve(options.dir);
-		const format = options.format;
 		const links = options.links;
-		const { diagnostics, resources } = await compile({
+		const outDir = options.outDir ? resolve(options.outDir) : join(dir, ".topik");
+		await assertCompilationOutputScope(dir, outDir);
+		const { diagnostics, materialization, payloads, resources, semantic } = await compile({
 			dir,
 			validation: { links }
 		});
@@ -77,55 +101,478 @@ const compile$1 = command({
 			const { valid, errors } = validateResources(resources);
 			if (!valid) throw new CliError(formatValidationFailure(errors, resources.length, "validating compiled output"));
 		}
-		const ext = formatExtensions[format];
 		if (options.dryRun) {
-			for (const resource of resources) console.log(`${resource.type}/${resource.name}${ext}`);
-			console.log(`\n${resources.length} resources (dry run)`);
+			const paths = [
+				...resources.map((resource) => `resources/${resource.type}/${resource.name}.json`),
+				...payloads.map((payload) => payload.path),
+				"materialization.json",
+				"semantic.json"
+			].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+			for (const path of paths) console.log(path);
+			console.log(`\n${resources.length} resources and ${payloads.length} payloads (dry run)`);
 			return;
 		}
-		const outDir = options.outDir ? resolve(options.outDir) : join(dir, ".topik", "resources");
-		if (options.clean) await rm(outDir, {
-			recursive: true,
-			force: true
+		const materializedResources = new Map(materialization.resources.map((resource) => [resource.resource, resource]));
+		const files = resources.map((resource) => {
+			const materialized = materializedResources.get(`${resource.type}/${resource.name}`);
+			if (materialized === void 0) throw new CliError("Compiled materialization omits a resource descriptor");
+			return {
+				path: materialized.path,
+				bytes: serializeTopikJson(resource)
+			};
 		});
-		const types = new Set(resources.map((r) => r.type));
-		await Promise.all([...types].map((type) => mkdir(join(outDir, type), { recursive: true })));
-		await Promise.all(resources.map(async (resource) => writeFile(join(outDir, resource.type, `${resource.name}${ext}`), await serialize(resource, format))));
-		console.log(`Compiled ${resources.length} resources to ${outDir}`);
+		files.push(...payloads.map((payload) => ({
+			path: payload.path,
+			bytes: payload.bytes
+		})), {
+			path: "materialization.json",
+			bytes: serializeTopikJson(materialization)
+		}, {
+			path: "semantic.json",
+			bytes: serializeTopikJson(semantic)
+		});
+		await replaceCompilationTree(outDir, files);
+		console.log(`Compiled ${resources.length} resources and ${payloads.length} payloads to ${outDir}`);
 	}
 });
+async function replaceCompilationTree(absolutePath, files) {
+	const stagedFiles = snapshotCompilationFiles(files);
+	const target = basename(absolutePath);
+	if (target.length === 0 || target === "." || target === "..") throw new CliError("Compilation output root is invalid");
+	const anchoredParent = await openAnchoredOutputDirectory(dirname(absolutePath), true);
+	if (anchoredParent === void 0) throw new CliError("Compilation output parent could not be created");
+	const parent = anchoredParent.handle;
+	let existing;
+	let generation;
+	let published = false;
+	let existingRemoved = false;
+	let operationError;
+	try {
+		const targetPath = procFdChild(parent.fd, target);
+		existing = await openOwnedCompilationOutput(parent, target);
+		generation = await createOwnedTemporaryDirectory(parent, COMPILATION_GENERATION_PREFIX);
+		for (const directory of COMPILATION_DIRECTORIES) {
+			const handle = await openAnchoredChildDirectory(generation.handle, directory, true);
+			if (handle === void 0) throw new CliError("Compilation output directory is unavailable");
+			await handle.close();
+		}
+		for (const file of stagedFiles) await writeAnchoredFile(generation.handle, file.path, file.bytes);
+		generation.tree = bindCompleteCompilationTreeSync(generation.handle);
+		assertExpectedStagedTree(generation.tree, stagedFiles);
+		if (existing !== void 0) {
+			const priorName = `${COMPILATION_PRIOR_PREFIX}${randomUUID()}`;
+			assertOutputPathAbsent(procFdChild(parent.fd, priorName));
+			renameSync(targetPath, procFdChild(parent.fd, priorName));
+			existing.name = priorName;
+		}
+		renameSync(generation.path, targetPath);
+		generation.path = targetPath;
+		generation.name = target;
+		published = true;
+		if (existing !== void 0) {
+			cleanupCompilationDirectory(parent, existing);
+			existingRemoved = true;
+		}
+	} catch (error) {
+		operationError = error;
+	}
+	if (!published && existing !== void 0 && existing.name !== target) operationError = new PublicCliError("compilation-publication-failed", { cause: operationError });
+	if (generation !== void 0 && !published) try {
+		generation.tree = bindCompleteCompilationTreeSync(generation.handle);
+		cleanupCompilationDirectory(parent, generation);
+	} catch (error) {
+		operationError ??= error;
+	}
+	if (published && existing !== void 0 && !existingRemoved && existing.name !== target) try {
+		cleanupCompilationDirectory(parent, existing);
+	} catch (error) {
+		operationError ??= error;
+	}
+	await generation?.handle.close().catch(() => void 0);
+	await existing?.handle.close().catch(() => void 0);
+	await parent.close().catch(() => void 0);
+	if (operationError !== void 0) throw operationError;
+}
+async function createOwnedTemporaryDirectory(parent, prefix) {
+	const path = await mkdtemp(procFdChild(parent.fd, prefix));
+	let handle;
+	try {
+		handle = await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+		if (!(await handle.stat({ bigint: true })).isDirectory()) throw new CliError("Compilation staging identity is invalid");
+		return {
+			name: basename(path),
+			path,
+			handle,
+			tree: { entries: [] }
+		};
+	} catch (error) {
+		await handle?.close().catch(() => void 0);
+		try {
+			rmdirSync(procFdChild(parent.fd, basename(path)));
+		} catch {}
+		if (error instanceof CliError) throw error;
+		throw new CliError("Compilation staging directory could not be opened safely");
+	}
+}
+async function openOwnedCompilationOutput(parent, target) {
+	const targetPath = procFdChild(parent.fd, target);
+	let stat;
+	try {
+		stat = await lstat(targetPath);
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw new CliError("Compilation output target could not be inspected safely");
+	}
+	if (!stat.isDirectory()) throw new CliError("Compilation output contains a link or non-directory collision");
+	const directory = await openAnchoredChildDirectory(parent, target, false);
+	if (directory === void 0) throw new CliError("Compilation output directory could not be opened safely");
+	try {
+		const tree = bindCompleteCompilationTreeSync(directory);
+		assertOwnedCompilationTree(directory, tree);
+		return {
+			handle: directory,
+			name: target,
+			path: targetPath,
+			tree
+		};
+	} catch (error) {
+		await directory.close().catch(() => void 0);
+		throw error;
+	}
+}
+function cleanupCompilationDirectory(parent, directory) {
+	for (const entry of [...directory.tree.entries].reverse()) {
+		if (entry.path.length === 0) continue;
+		const path = `${procFd(directory.handle.fd)}/${entry.path}`;
+		if (entry.kind === "file") unlinkSync(path);
+		else rmdirSync(path);
+	}
+	rmdirSync(procFdChild(parent.fd, directory.name));
+}
+function assertOutputPathAbsent(path) {
+	try {
+		lstatSync(path);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw new CliError("Compilation replacement storage could not be inspected safely");
+	}
+	throw new CliError("Compilation replacement storage is already occupied");
+}
+async function assertCompilationOutputScope(sourceDir, outDir) {
+	let canonicalOutput = outDir;
+	try {
+		canonicalOutput = await realpath(outDir);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw new CliError("Compilation output scope could not be proven safely");
+	}
+	let canonicalSource;
+	try {
+		canonicalSource = await realpath(sourceDir);
+	} catch {
+		throw new CliError("Compilation source scope could not be proven safely");
+	}
+	const relation = relative(canonicalOutput, canonicalSource);
+	if (relation === "" || !relation.startsWith("..") && !isAbsolute(relation)) throw new CliError("Compilation output cannot equal or contain the source directory");
+}
+function assertOwnedCompilationTree(directory, tree) {
+	try {
+		const materialization = parseBoundCanonicalJson(directory, tree, "materialization.json");
+		const semantic = parseBoundCanonicalJson(directory, tree, "semantic.json");
+		if (!isRecord(materialization) || !Array.isArray(materialization.resources)) throw new TypeError("Materialization resource inventory is unavailable");
+		const resources = materialization.resources.map((entry) => {
+			if (!isRecord(entry) || typeof entry.path !== "string") throw new TypeError("Materialization resource inventory is malformed");
+			return parseBoundCanonicalJson(directory, tree, entry.path);
+		});
+		if (!isValidResourceSet(resources)) throw new TypeError("Compiled resource inventory is invalid");
+		const closure = validateTopikMaterializationRecord(materialization, resources, semantic);
+		if (!closure.ok) throw new TypeError("Compilation identity records do not close");
+		assertBoundTreeMatchesInventory(tree, closure.value);
+	} catch {
+		throw new CliError("Existing compilation output is populated but is not recognized as owned");
+	}
+}
+function parseBoundCanonicalJson(root, tree, path) {
+	const bytes = readBoundCompilationFileSync(root, tree, path);
+	const text = ownedDescriptorDecoder.decode(bytes);
+	const value = parseStrictTopikJson(text, Number.POSITIVE_INFINITY);
+	const canonicalBytes = ownedDescriptorEncoder.encode(serializeTopikJson(value));
+	if (!Buffer.from(bytes).equals(canonicalBytes)) throw new TypeError("Compilation descriptor is not canonical");
+	return value;
+}
+function readBoundCompilationFileSync(root, tree, path) {
+	safeOutputComponents(path);
+	const expected = tree.entries.find((entry) => entry.kind === "file" && entry.path === path);
+	if (expected === void 0) throw new TypeError("Compilation descriptor is unavailable");
+	let fileFd;
+	try {
+		const anchoredPath = `${procFd(root.fd)}/${path}`;
+		fileFd = openSync(anchoredPath, constants.O_RDONLY | constants.O_NOFOLLOW | (typeof constants.O_NONBLOCK === "number" ? constants.O_NONBLOCK : 0));
+		const before = fstatSync(fileFd, { bigint: true });
+		if (!before.isFile() || !sameStoredOutputIdentity(toBoundOutputIdentity(before), expected.identity)) throw new TypeError("Compilation descriptor identity changed");
+		const bytes = readFileSync(fileFd);
+		const after = fstatSync(fileFd, { bigint: true });
+		if (!sameBoundOutputIdentity(before, after) || sha256OutputBytes(bytes) !== expected.digest) throw new TypeError("Compilation descriptor bytes changed");
+		assertPathStillBindsIdentitySync(anchoredPath, after, "file");
+		return Uint8Array.from(bytes);
+	} finally {
+		if (fileFd !== void 0) closeSync(fileFd);
+	}
+}
+function assertBoundTreeMatchesInventory(tree, materialization) {
+	const expectedDirectories = /* @__PURE__ */ new Set(["", ...COMPILATION_DIRECTORIES]);
+	const expectedFiles = /* @__PURE__ */ new Map([["materialization.json", {}], ["semantic.json", {}]]);
+	for (const entry of [...materialization.resources, ...materialization.payloads]) {
+		safeOutputComponents(entry.path);
+		if (expectedFiles.has(entry.path)) throw new TypeError("Compilation inventory repeats a path");
+		expectedFiles.set(entry.path, {
+			sha256: entry.sha256,
+			size: entry.size
+		});
+		const components = entry.path.split("/");
+		for (let index = 1; index < components.length; index++) expectedDirectories.add(components.slice(0, index).join("/"));
+	}
+	if (tree.entries.length !== expectedDirectories.size + expectedFiles.size) throw new TypeError("Compilation tree contains an unexpected path");
+	for (const entry of tree.entries) {
+		if (entry.kind === "directory") {
+			if (!expectedDirectories.has(entry.path)) throw new TypeError("Compilation tree contains an unexpected directory");
+			continue;
+		}
+		const expected = expectedFiles.get(entry.path);
+		if (expected === void 0 || expected.size !== void 0 && entry.identity.size !== BigInt(expected.size) || expected.sha256 !== void 0 && entry.digest !== expected.sha256) throw new TypeError("Compilation tree does not match its inventory");
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isValidResourceSet(resources) {
+	return validateResources(resources).valid;
+}
+async function openAnchoredOutputDirectory(absolutePath, create) {
+	if (process.platform !== "linux" || typeof constants.O_NOFOLLOW !== "number" || typeof constants.O_DIRECTORY !== "number") throw new CliError("This platform cannot prove descriptor-anchored output containment");
+	const normalized = resolve(absolutePath);
+	if (normalized === "/") throw new CliError("Compilation output root cannot be the filesystem root");
+	const components = normalized.split("/").filter(Boolean);
+	let current = await open("/", constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+	try {
+		for (const component of components) {
+			const child = await openAnchoredChildDirectory(current, component, create);
+			if (child === void 0) {
+				await current.close();
+				return;
+			}
+			await current.close();
+			current = child;
+		}
+		return { handle: current };
+	} catch (error) {
+		await current.close().catch(() => void 0);
+		if (error instanceof CliError) throw error;
+		throw new CliError("Compilation output has an unsafe or unresolvable ancestor");
+	}
+}
+function snapshotCompilationFiles(files) {
+	const paths = /* @__PURE__ */ new Set();
+	const snapshots = files.map((file) => {
+		safeOutputComponents(file.path);
+		if (paths.has(file.path)) throw new CliError("Compilation output repeats a staged file path");
+		paths.add(file.path);
+		const bytes = typeof file.bytes === "string" ? Uint8Array.from(Buffer.from(file.bytes, "utf8")) : Uint8Array.from(file.bytes);
+		return {
+			path: file.path,
+			bytes,
+			digest: sha256OutputBytes(bytes)
+		};
+	});
+	for (const path of paths) {
+		const components = safeOutputComponents(path);
+		for (let index = 1; index < components.length; index++) if (paths.has(components.slice(0, index).join("/"))) throw new CliError("Compilation output has a parent/file collision");
+	}
+	return snapshots;
+}
+function bindCompleteCompilationTreeSync(root) {
+	const entries = [];
+	try {
+		inspectBoundDirectorySync(root.fd, "", entries);
+	} catch (error) {
+		if (error instanceof CliError) throw error;
+		throw new CliError("Compilation generation contents could not be inspected safely");
+	}
+	entries.sort((left, right) => Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8")));
+	return { entries };
+}
+function inspectBoundDirectorySync(directoryFd, prefix, entries) {
+	const before = fstatSync(directoryFd, { bigint: true });
+	if (!before.isDirectory()) throw new CliError("Compilation generation contains an unsafe directory entry");
+	const children = readdirSync(procFd(directoryFd), { withFileTypes: true }).sort((left, right) => Buffer.compare(Buffer.from(left.name, "utf8"), Buffer.from(right.name, "utf8")));
+	for (const child of children) {
+		const path = prefix.length === 0 ? child.name : `${prefix}/${child.name}`;
+		const anchoredPath = procFdChild(directoryFd, child.name);
+		if (child.isDirectory()) {
+			let childFd;
+			try {
+				childFd = openSync(anchoredPath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+				inspectBoundDirectorySync(childFd, path, entries);
+				assertPathStillBindsIdentitySync(anchoredPath, fstatSync(childFd, { bigint: true }), "directory");
+			} finally {
+				if (childFd !== void 0) closeSync(childFd);
+			}
+			continue;
+		}
+		if (!child.isFile()) throw new CliError("Compilation generation contains a link or special-node entry");
+		let fileFd;
+		try {
+			fileFd = openSync(anchoredPath, constants.O_RDONLY | constants.O_NOFOLLOW | (typeof constants.O_NONBLOCK === "number" ? constants.O_NONBLOCK : 0));
+			const fileBefore = fstatSync(fileFd, { bigint: true });
+			if (!fileBefore.isFile() || fileBefore.nlink !== 1n) throw new CliError("Compilation generation contains a hard link or unsafe file entry");
+			const bytes = readFileSync(fileFd);
+			const fileAfter = fstatSync(fileFd, { bigint: true });
+			if (!sameBoundOutputIdentity(fileBefore, fileAfter)) throw new CliError("Compilation generation file changed while it was inspected");
+			assertPathStillBindsIdentitySync(anchoredPath, fileAfter, "file");
+			entries.push({
+				path,
+				kind: "file",
+				identity: toBoundOutputIdentity(fileAfter),
+				digest: sha256OutputBytes(bytes)
+			});
+		} finally {
+			if (fileFd !== void 0) closeSync(fileFd);
+		}
+	}
+	const after = fstatSync(directoryFd, { bigint: true });
+	if (!sameBoundOutputIdentity(before, after)) throw new CliError("Compilation generation directory changed while it was inspected");
+	entries.push({
+		path: prefix,
+		kind: "directory",
+		identity: toBoundOutputIdentity(after)
+	});
+}
+function assertPathStillBindsIdentitySync(path, expected, kind) {
+	const actual = lstatSync(path, { bigint: true });
+	if ((kind === "directory" ? !actual.isDirectory() : !actual.isFile()) || !sameBoundOutputIdentity(actual, expected)) throw new CliError("Compilation generation path binding changed while it was inspected");
+}
+function assertExpectedStagedTree(tree, files) {
+	const expectedDirectories = /* @__PURE__ */ new Set([""]);
+	for (const directory of COMPILATION_DIRECTORIES) expectedDirectories.add(directory);
+	const expectedFiles = new Map(files.map((file) => [file.path, file]));
+	for (const file of files) {
+		const components = safeOutputComponents(file.path);
+		for (let index = 1; index < components.length; index++) expectedDirectories.add(components.slice(0, index).join("/"));
+	}
+	if (tree.entries.length !== expectedDirectories.size + expectedFiles.size) throw new CliError("Compilation staged generation contains an unexpected path");
+	for (const entry of tree.entries) {
+		if (entry.kind === "directory") {
+			if (!expectedDirectories.has(entry.path)) throw new CliError("Compilation staged generation contains an unexpected directory");
+			continue;
+		}
+		const expected = expectedFiles.get(entry.path);
+		if (expected === void 0 || entry.identity.size !== BigInt(expected.bytes.byteLength) || entry.digest !== expected.digest) throw new CliError("Compilation staged generation bytes do not match expected output");
+	}
+}
+function sameBoundOutputIdentity(left, right) {
+	return sameStoredOutputIdentity(toBoundOutputIdentity(left), toBoundOutputIdentity(right));
+}
+function sameStoredOutputIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode && left.nlink === right.nlink && left.size === right.size && left.ctimeNs === right.ctimeNs && left.mtimeNs === right.mtimeNs;
+}
+function toBoundOutputIdentity(stat) {
+	return {
+		dev: stat.dev,
+		ino: stat.ino,
+		mode: stat.mode,
+		nlink: stat.nlink,
+		size: stat.size,
+		ctimeNs: stat.ctimeNs,
+		mtimeNs: stat.mtimeNs
+	};
+}
+function sha256OutputBytes(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+async function openAnchoredChildDirectory(parent, component, create) {
+	if (component.length === 0 || component === "." || component === ".." || component.includes("/")) throw new CliError("Compilation output path is invalid");
+	const path = procFdChild(parent.fd, component);
+	try {
+		return await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+	} catch (error) {
+		if (error.code !== "ENOENT" || !create) {
+			if (error.code === "ENOENT") return void 0;
+			throw new CliError("Compilation output contains a link or non-directory collision");
+		}
+		await mkdir(path, { mode: 448 }).catch((mkdirError) => {
+			if (mkdirError.code !== "EEXIST") throw mkdirError;
+		});
+		try {
+			return await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+		} catch {
+			throw new CliError("Compilation output directory identity could not be proven");
+		}
+	}
+}
+async function writeAnchoredFile(root, relativePath, bytes) {
+	const components = safeOutputComponents(relativePath);
+	const directories = [];
+	let parent = root;
+	let output;
+	try {
+		for (const component of components.slice(0, -1)) {
+			const child = await openAnchoredChildDirectory(parent, component, true);
+			if (child === void 0) throw new CliError("Compilation output directory is unavailable");
+			directories.push(child);
+			parent = child;
+		}
+		const path = procFdChild(parent.fd, components.at(-1) ?? "");
+		output = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384);
+		await output.writeFile(bytes);
+		await output.chmod(420);
+	} finally {
+		await output?.close().catch(() => void 0);
+		await Promise.all(directories.map((handle) => handle.close().catch(() => void 0)));
+	}
+}
+function safeOutputComponents(relativePath) {
+	const components = relativePath.split("/");
+	if (relativePath.startsWith("/") || components.some((component) => component.length === 0 || component === "." || component === ".." || component.includes("\\"))) throw new CliError("Compilation output path is not safely relative");
+	return components;
+}
+function procFd(fd) {
+	return `/proc/self/fd/${fd}`;
+}
+function procFdChild(fd, component) {
+	return `${procFd(fd)}/${component}`;
+}
+//#endregion
+//#region package.json
+var version = "0.1.0-alpha.6";
 //#endregion
 //#region src/dev/index.ts
-const ASSET_EXTENSIONS = {
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".svg": "image/svg+xml",
-	".webp": "image/webp",
-	".avif": "image/avif",
-	".ico": "image/x-icon",
-	".mp4": "video/mp4",
-	".webm": "video/webm"
-};
+const DEV_HOST = "127.0.0.1";
+const DEFAULT_ALLOWED_ORIGIN = "https://write.subtopik.com";
+const REQUEST_VARY_HEADERS = "Origin, Sec-Fetch-Site";
 function sendSSE(res, event, data) {
 	res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
 }
-function handleResources(watcher, _req, res) {
+function handleResources(watcher, res, corsHeaders) {
 	res.writeHead(200, {
 		"Content-Type": "application/json",
-		"Access-Control-Allow-Origin": "*"
+		"Cache-Control": "no-store",
+		...corsHeaders
 	});
-	res.end(JSON.stringify({ resources: [...watcher.resources.values()] }));
+	res.end(JSON.stringify(watcher.state));
 }
-function handleEvents(watcher, _req, res) {
+function handleEvents(watcher, res, corsHeaders) {
 	res.writeHead(200, {
 		"Content-Type": "text/event-stream",
 		"Cache-Control": "no-cache",
 		Connection: "keep-alive",
-		"Access-Control-Allow-Origin": "*"
+		...corsHeaders
+	});
+	sendSSE(res, "preview-state", watcher.state);
+	const onState = (state) => sendSSE(res, "preview-state", state);
+	watcher.on("preview-state", onState);
+	sendSSE(res, "sync", {
+		resources: Object.fromEntries(watcher.resources),
+		payloads: Object.fromEntries([...watcher.payloads].map(([path, { bytes: _bytes, ...payload }]) => [path, payload]))
 	});
-	sendSSE(res, "sync", { resources: Object.fromEntries(watcher.resources) });
 	const onUpdate = (key, resource) => {
 		sendSSE(res, "update", {
 			key,
@@ -135,123 +582,234 @@ function handleEvents(watcher, _req, res) {
 	watcher.on("update", onUpdate);
 	res.on("close", () => {
 		watcher.off("update", onUpdate);
+		watcher.off("preview-state", onState);
 	});
 }
-function getAsset(watcher, name) {
-	const resource = watcher.resources.get(`Asset/${name}`);
-	return resource?.type === "Asset" ? resource : null;
-}
-function handleAsset(watcher, dir, url, res) {
-	if (!url.pathname.startsWith("/assets/")) return false;
-	let name;
-	try {
-		name = decodeURIComponent(url.pathname.slice(8));
-	} catch {
-		res.writeHead(404, { "Access-Control-Allow-Origin": "*" });
-		res.end();
-		return true;
-	}
-	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
-		res.writeHead(404, { "Access-Control-Allow-Origin": "*" });
+function handleAssetPayload(watcher, rawPathname, method, res, corsHeaders) {
+	if (!rawPathname.startsWith("/blobs/")) return false;
+	const relativePath = rawPathname.slice(1);
+	if (!/^blobs\/[0-9a-f]{64}$/u.test(relativePath)) {
+		res.writeHead(404, corsHeaders);
 		res.end();
 		return true;
 	}
-	const asset = getAsset(watcher, name);
-	if (!asset) {
-		res.writeHead(404, { "Access-Control-Allow-Origin": "*" });
+	const payload = watcher.payloads.get(relativePath);
+	if (payload === void 0) {
+		res.writeHead(404, corsHeaders);
 		res.end();
 		return true;
 	}
-	let filePath;
-	let realDir;
-	let realFilePath;
+	const contentType = payload.mediaType;
+	res.writeHead(200, {
+		"Content-Type": contentType,
+		"Content-Length": String(payload.size),
+		...corsHeaders,
+		"Cache-Control": "no-cache",
+		"X-Content-Type-Options": "nosniff",
+		...isDownloadMediaType(contentType) ? { "Content-Disposition": "attachment" } : {}
+	});
+	res.end(method === "HEAD" ? void 0 : payload.bytes);
+	return true;
+}
+function isDownloadMediaType(mediaType) {
+	return [
+		"application/octet-stream",
+		"text/html",
+		"image/svg+xml",
+		"application/javascript",
+		"text/javascript",
+		"application/x-executable",
+		"application/wasm",
+		"application/x-topik-active-content"
+	].includes(mediaType);
+}
+function normalizeAllowedOrigin(value) {
+	let url;
 	try {
-		filePath = resolve(join(dir, asset.spec.uri));
-		realDir = realpathSync(dir);
-		realFilePath = realpathSync(filePath);
+		url = new URL(value);
 	} catch {
-		res.writeHead(404, { "Access-Control-Allow-Origin": "*" });
-		res.end();
-		return true;
-	}
-	const relativeAssetPath = relative(realDir, realFilePath);
-	if (relativeAssetPath !== "" && (relativeAssetPath.startsWith("..") || isAbsolute(relativeAssetPath)) || !existsSync(realFilePath)) {
-		res.writeHead(404, { "Access-Control-Allow-Origin": "*" });
-		res.end();
-		return true;
+		throw new PublicCliError("browser-origin-invalid");
 	}
-	readFile(filePath).then((data) => {
-		res.writeHead(200, {
-			"Content-Type": asset.spec.mediaType ?? ASSET_EXTENSIONS[extname(filePath)] ?? "application/octet-stream",
-			"Access-Control-Allow-Origin": "*",
-			"Cache-Control": "no-cache"
+	if (url.protocol !== "http:" && url.protocol !== "https:" || url.origin === "null" || url.username !== "" || url.password !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "") throw new PublicCliError("browser-origin-invalid");
+	return url.origin;
+}
+function isAllowedHost(host, port) {
+	if (!host) return false;
+	const normalizedHost = host.toLowerCase();
+	if (normalizedHost === `localhost:${port}` || normalizedHost === `127.0.0.1:${port}` || normalizedHost === `[::1]:${port}`) return true;
+	return port === 80 && (normalizedHost === "localhost" || normalizedHost === "127.0.0.1" || normalizedHost === "[::1]");
+}
+function isLoopbackAddress(address) {
+	return address === "127.0.0.1" || address === "::1";
+}
+function getCorsHeaders(origin, allowedOrigin) {
+	return origin === allowedOrigin ? {
+		"Access-Control-Allow-Origin": allowedOrigin,
+		Vary: REQUEST_VARY_HEADERS
+	} : { Vary: REQUEST_VARY_HEADERS };
+}
+function rejectRequest(res) {
+	res.writeHead(403, {
+		"Content-Type": "text/plain",
+		Vary: REQUEST_VARY_HEADERS
+	});
+	res.end("Forbidden");
+}
+function createRequestHandler(watcher, getPort, allowedOrigin) {
+	return (req, res) => {
+		if (!isAllowedHost(req.headers.host, getPort())) {
+			rejectRequest(res);
+			return;
+		}
+		const origin = req.headers.origin;
+		const fetchSite = req.headers["sec-fetch-site"];
+		if (origin !== void 0 && origin !== allowedOrigin || origin === void 0 && fetchSite !== void 0 && fetchSite !== "same-origin" && fetchSite !== "none") {
+			rejectRequest(res);
+			return;
+		}
+		const corsHeaders = getCorsHeaders(origin, allowedOrigin);
+		if (req.method === "OPTIONS") {
+			res.writeHead(204, {
+				...corsHeaders,
+				"Access-Control-Allow-Methods": "GET, HEAD, OPTIONS",
+				"Access-Control-Allow-Headers": "Content-Type"
+			});
+			res.end();
+			return;
+		}
+		const requestTarget = req.url ?? "/";
+		let url;
+		try {
+			url = new URL(requestTarget, `http://localhost:${getPort()}`);
+		} catch {
+			res.writeHead(400, {
+				"Content-Type": "text/plain",
+				...corsHeaders
+			});
+			res.end("Bad Request");
+			return;
+		}
+		if (req.method === "GET" && url.pathname === "/health") {
+			res.writeHead(200, {
+				"Content-Type": "application/json",
+				"Cache-Control": "no-store",
+				...corsHeaders
+			});
+			res.end(JSON.stringify({
+				status: "ok",
+				version,
+				capabilities: [TOPIK_PREVIEW_PROTOCOL],
+				sessionId: watcher.state.sessionId
+			}));
+			return;
+		}
+		if (req.method === "GET" && url.pathname === "/resources") {
+			handleResources(watcher, res, corsHeaders);
+			return;
+		}
+		if (req.method === "GET" && url.pathname === "/events") {
+			handleEvents(watcher, res, corsHeaders);
+			return;
+		}
+		if (url.pathname.startsWith("/blobs/") && (url.searchParams.has("sessionId") || url.searchParams.has("generation"))) {
+			if (url.searchParams.getAll("sessionId").length !== 1 || url.searchParams.getAll("generation").length !== 1 || url.searchParams.get("sessionId") !== watcher.state.sessionId || url.searchParams.get("generation") !== String(watcher.state.generation)) {
+				res.writeHead(409, {
+					...corsHeaders,
+					"Cache-Control": "no-store"
+				});
+				res.end();
+				return;
+			}
+		}
+		const queryOffset = requestTarget.indexOf("?");
+		const rawPathname = queryOffset === -1 ? requestTarget : requestTarget.slice(0, queryOffset);
+		if ((req.method === "GET" || req.method === "HEAD") && handleAssetPayload(watcher, rawPathname, req.method, res, corsHeaders)) return;
+		res.writeHead(404, {
+			"Content-Type": "text/plain",
+			...corsHeaders
 		});
-		res.end(data);
-	}).catch(() => {
-		res.writeHead(500, { "Access-Control-Allow-Origin": "*" });
-		res.end();
+		res.end("Not Found");
+	};
+}
+/** @internal */
+async function startDevServer(options) {
+	const dir = resolve(options.dir);
+	const allowedOrigin = normalizeAllowedOrigin(options.allowOrigin ?? DEFAULT_ALLOWED_ORIGIN);
+	console.log("Watching content for changes...");
+	const watcher = await watch({ dir });
+	if (watcher.state.status === "error") console.error("Compile error:", watcher.state.diagnostics.map((diagnostic) => diagnostic.message).join(" "));
+	else console.log(`Compiled ${watcher.resources.size} resources`);
+	watcher.on("error", (error) => {
+		console.error("Compile error:", formatPublicCliError(error));
 	});
-	return true;
+	watcher.on("update", (key) => {
+		console.log(`Updated ${key}`);
+	});
+	let activePort = options.port;
+	const server = createServer(createRequestHandler(watcher, () => activePort, allowedOrigin));
+	try {
+		await new Promise((resolveListening, rejectListening) => {
+			const onError = (error) => {
+				server.off("listening", onListening);
+				rejectListening(error);
+			};
+			const onListening = () => {
+				server.off("error", onError);
+				const address = server.address();
+				if (!address || typeof address === "string" || !isLoopbackAddress(address.address)) {
+					server.close(() => {
+						rejectListening(/* @__PURE__ */ new Error("Dev server did not bind to a loopback address"));
+					});
+					return;
+				}
+				activePort = address.port;
+				resolveListening();
+			};
+			server.once("error", onError);
+			server.once("listening", onListening);
+			server.listen(options.port, DEV_HOST);
+		});
+	} catch (error) {
+		await watcher.close();
+		throw error;
+	}
+	let closePromise;
+	return {
+		port: activePort,
+		server,
+		watcher,
+		close: () => {
+			closePromise ??= (async () => {
+				const serverClosed = server.listening ? new Promise((resolveClosed, rejectClosed) => {
+					server.close((error) => {
+						if (error) rejectClosed(error);
+						else resolveClosed();
+					});
+					server.closeAllConnections();
+				}) : Promise.resolve();
+				await Promise.all([serverClosed, watcher.close()]);
+			})();
+			return closePromise;
+		}
+	};
 }
 const dev = command({
 	name: "dev",
 	desc: "Start a development server that watches for content changes",
 	options: {
-		dir: positional("dir").desc("Path to the content directory").default("."),
-		port: string("port").alias("p").desc("Port to listen on").default("50001")
+		dir: positional("dir").desc("Project directory containing .topik.yaml").default("."),
+		port: string("port").alias("p").desc("Port to listen on").default("50001"),
+		allowOrigin: string("allow-origin").desc(`Browser origin allowed to connect (default: ${DEFAULT_ALLOWED_ORIGIN})`)
 	},
 	handler: async (options) => {
-		const dir = resolve(options.dir);
-		const port = parseInt(options.port, 10);
-		console.log(`Watching ${dir} for changes...`);
-		const watcher = await watch({ dir });
-		console.log(`Compiled ${watcher.resources.size} resources`);
-		watcher.on("error", (error) => {
-			console.error("Compile error:", error.message);
-		});
-		watcher.on("update", (key) => {
-			console.log(`Updated ${key}`);
-		});
-		const server = createServer((req, res) => {
-			if (req.method === "OPTIONS") {
-				res.writeHead(204, {
-					"Access-Control-Allow-Origin": "*",
-					"Access-Control-Allow-Methods": "GET, OPTIONS",
-					"Access-Control-Allow-Headers": "Content-Type"
-				});
-				res.end();
-				return;
-			}
-			const url = new URL(req.url ?? "/", `http://localhost:${port}`);
-			if (req.method === "GET" && url.pathname === "/health") {
-				res.writeHead(200, {
-					"Content-Type": "application/json",
-					"Access-Control-Allow-Origin": "*"
-				});
-				res.end(JSON.stringify({ status: "ok" }));
-				return;
-			}
-			if (req.method === "GET" && url.pathname === "/resources") {
-				handleResources(watcher, req, res);
-				return;
-			}
-			if (req.method === "GET" && url.pathname === "/events") {
-				handleEvents(watcher, req, res);
-				return;
-			}
-			if (req.method === "GET" && handleAsset(watcher, dir, url, res)) return;
-			res.writeHead(404, {
-				"Content-Type": "text/plain",
-				"Access-Control-Allow-Origin": "*"
-			});
-			res.end("Not Found");
-		});
-		server.listen(port, () => {
-			console.log(`Dev server listening on http://localhost:${port}`);
+		const runningServer = await startDevServer({
+			dir: resolve(options.dir),
+			port: parseInt(options.port, 10),
+			allowOrigin: options.allowOrigin
 		});
-		process.on("SIGINT", async () => {
-			server.close();
-			await watcher.close();
+		console.log(`Dev server listening on http://localhost:${runningServer.port}`);
+		process.once("SIGINT", async () => {
+			await runningServer.close();
 			process.exit(0);
 		});
 	}
@@ -262,7 +820,7 @@ const lint$1 = command({
 	name: "lint",
 	desc: "Lint Topik source content without writing compiled resources",
 	options: {
-		dir: positional("dir").desc("Path to the content directory").default("."),
+		dir: positional("dir").desc("Project directory containing .topik.yaml").default("."),
 		links: string("links").desc("How unresolved wiki links and local guide fragments are handled").enum("error", "warning", "off").default("error")
 	},
 	handler: async (options) => {
@@ -280,52 +838,53 @@ const lint$1 = command({
 });
 //#endregion
 //#region src/validate/index.ts
-function parseJson(path, content) {
+function parseJson(content) {
 	try {
 		return JSON.parse(content);
-	} catch (error) {
-		throw new CliError(`Failed to parse JSON resource file ${path}`, { cause: error });
+	} catch {
+		throw new PublicCliError("resource-json-invalid");
 	}
 }
-function parseJsonl(path, content) {
-	return content.split("\n").map((line, index) => ({
-		line,
-		index: index + 1
-	})).filter(({ line }) => line.trim().length > 0).map(({ line, index }) => {
+function parseJsonl(content) {
+	return content.split("\n").filter((line) => line.trim().length > 0).map((line) => {
 		try {
 			return JSON.parse(line);
-		} catch (error) {
-			throw new CliError(`Failed to parse JSONL resource file ${path} at line ${index}`, { cause: error });
+		} catch {
+			throw new PublicCliError("resource-jsonl-invalid");
 		}
 	});
 }
-function parseYaml(path, content) {
+function parseYaml(content) {
 	try {
 		return parseAllDocuments(content).filter((document) => document.contents !== null).map((document) => {
 			if (document.errors.length > 0) throw document.errors[0];
 			return document.toJS();
 		});
-	} catch (error) {
-		throw new CliError(`Failed to parse YAML resource file ${path}`, { cause: error });
+	} catch {
+		throw new PublicCliError("resource-yaml-invalid");
 	}
 }
 async function readResourceFile(path) {
-	const content = await readFile(path, "utf-8");
+	const content = await readFile(path, "utf-8").catch(() => {
+		throw new PublicCliError("resource-read-failed");
+	});
 	switch (extname(path).toLowerCase()) {
-		case ".json": return [parseJson(path, content)];
-		case ".jsonl": return parseJsonl(path, content);
+		case ".json": return [parseJson(content)];
+		case ".jsonl": return parseJsonl(content);
 		case ".yaml":
-		case ".yml": return parseYaml(path, content);
-		default: throw new CliError(`Unsupported resource file format for ${path}`);
+		case ".yml": return parseYaml(content);
+		default: throw new PublicCliError("resource-format-unsupported");
 	}
 }
 async function loadResources(path) {
-	if ((await stat(path).catch((error) => {
-		throw new CliError(`Failed to access ${path}`, { cause: error });
+	if ((await stat(path).catch(() => {
+		throw new PublicCliError("resource-access-failed");
 	})).isFile()) return readResourceFile(path);
 	const resourceFiles = (await readdir(path, {
 		withFileTypes: true,
 		recursive: true
+	}).catch(() => {
+		throw new PublicCliError("resource-read-failed");
 	})).filter((entry) => {
 		if (!entry.isFile()) return false;
 		const extension = extname(entry.name).toLowerCase();
@@ -343,9 +902,9 @@ const validate = command({
 			console.log("No resource files found.");
 			return;
 		}
-		const { valid, errors } = validateResources(resources);
+		const { valid } = validateResources(resources);
 		if (valid) console.log(`Validated ${resources.length} resources`);
-		else throw new CliError(formatValidationFailure(errors, resources.length, "validating resources"));
+		else throw new PublicCliError("resource-validation-failed");
 	}
 });
 //#endregion
@@ -361,11 +920,8 @@ try {
 		description: "Topik CLI"
 	});
 } catch (error) {
-	if (error instanceof CliError || error instanceof CompileError) {
-		console.error(error.message);
-		process.exit(1);
-	}
-	throw error;
+	console.error(formatPublicCliError(error));
+	process.exitCode = 1;
 }
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topik/cli",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "description": "Topik CLI",
   "license": "MIT",
   "repository": {
@@ -24,16 +24,16 @@
   },
   "dependencies": {
     "@drizzle-team/brocli": "^0.12.0",
-    "yaml": "^2.9.0",
-    "@topik/content-schema": "0.1.0-alpha.4",
-    "@topik/core": "0.1.0-alpha.4"
+    "yaml": "^2.9.1",
+    "@topik/content": "0.1.0-alpha.6",
+    "@topik/core": "0.1.0-alpha.6"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
-    "@types/node": "22.20.1",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "typescript": "^6.0.3",
-    "vite-plus": "0.2.4"
+    "@types/bun": "^1.4.3",
+    "@types/node": "22.20.4",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.2.0",
+    "vite-plus": "1.2.0"
   },
   "scripts": {
     "build": "vp pack",