@topik/cli 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/cli.mjs

@@ -3,14 +3,12 @@ import { boolean, command, positional, run, string } from "@drizzle-team/brocli"
 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, posix, relative, resolve, sep } from "node:path";
-import { AssetCompilationError, PublicCompileError, compile, isErrorDiagnostic, lint, parseStrictTopikJson, publicCompileErrorMessage, serializeTopikJson, validateResources, validateStableSourceNamespace, validateTopikMaterializationRecord, watch } from "@topik/core";
-import { sanitizeTopikContentDiagnostic } from "@topik/content-schema";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+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
+// src/diagnostics.ts
 function formatDiagnostic(diagnostic) {
 	const sanitized = sanitizeTopikContentDiagnostic(diagnostic);
 	return `${sanitized.file ?? "content"}${sanitized.lines.length > 0 ? `:${sanitized.lines.join(",")}` : ""} ${sanitized.level} ${sanitized.id}: ${sanitized.message}`;
@@ -22,8 +20,7 @@ function printDiagnostics(diagnostics) {
 		else console.warn(output);
 	}
 }
-//#endregion
-//#region src/errors.ts
+// src/errors.ts
 var CliError = class extends Error {
 	constructor(message, options) {
 		super(message, options);
@@ -32,6 +29,7 @@ var CliError = class extends Error {
 };
 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.",
@@ -43,8 +41,8 @@ const PUBLIC_CLI_ERROR_MESSAGES = Object.freeze({
 /** CLI failure admitted to presentation only through fixed catalog wording. */
 var PublicCliError = class extends CliError {
 	id;
-	constructor(id) {
-		super(publicCliErrorMessage(id) ?? "Topik command failed.");
+	constructor(id, options) {
+		super(publicCliErrorMessage(id) ?? "Topik command failed.", options);
 		this.name = "PublicCliError";
 		this.id = id;
 	}
@@ -54,93 +52,22 @@ function publicCliErrorMessage(id) {
 }
 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
+// src/validation-output.ts
 function formatValidationFailure(errors, resourceCount, context) {
 	const lines = errors.map((error) => `${error.resource}: ${error.path} ${error.message}`);
 	lines.push("");
 	lines.push(`${errors.length} validation error(s) in ${resourceCount} resources while ${context}`);
 	return lines.join("\n");
 }
-//#endregion
-//#region src/source-namespace.ts
-const execFileAsync = promisify(execFile);
-function requiresSourceNamespace(error) {
-	return error instanceof AssetCompilationError && error.diagnostics.some((diagnostic) => diagnostic.id === "TOPIK_ASSET_SOURCE_NAMESPACE_REQUIRED");
-}
-function sourceNamespaceOptions(value) {
-	if (value === void 0) return void 0;
-	const validation = validateStableSourceNamespace(value);
-	if (!validation.ok) throw new CliError("--source-namespace must be normalized portable text");
-	return { sourceNamespace: validation.value };
-}
-/** Derive only after automatic discovery proves that an Asset needs a namespace. */
-async function deriveGitSourceNamespace(dir) {
-	let worktree;
-	let remotes;
-	try {
-		worktree = (await git(dir, ["rev-parse", "--show-toplevel"])).trim();
-		remotes = (await git(dir, ["remote"])).split(/\r?\n/u).filter(Boolean).sort();
-	} catch {
-		throw namespaceRequired();
-	}
-	const remoteName = remotes.includes("origin") ? "origin" : remotes.length === 1 ? remotes[0] : void 0;
-	if (remoteName === void 0) throw namespaceRequired();
-	let remote;
-	try {
-		remote = (await git(dir, [
-			"remote",
-			"get-url",
-			remoteName
-		])).trim();
-	} catch {
-		throw namespaceRequired();
-	}
-	const identity = normalizeRemote(remote);
-	if (identity === void 0) throw namespaceRequired();
-	const rootRelative = relative(resolve(worktree), resolve(dir)).split(sep).join(posix.sep);
-	if (rootRelative.startsWith("../") || rootRelative === "..") throw namespaceRequired();
-	const namespace = `topik-git-v1:${identity}#${rootRelative || "."}`;
-	const validation = validateStableSourceNamespace(namespace);
-	if (!validation.ok) throw namespaceRequired();
-	return validation.value;
-}
-function normalizeRemote(value) {
-	const scp = value.includes("://") ? null : /^(?:[^@/:]+@)?([^/:]+):(.+)$/u.exec(value);
-	const candidate = scp !== null ? `ssh://${scp[1]}/${scp[2]}` : value;
-	let url;
-	try {
-		url = new URL(candidate);
-	} catch {
-		return;
-	}
-	if (url.protocol !== "https:" && url.protocol !== "ssh:" && url.protocol !== "git:") return void 0;
-	if (url.hostname.length === 0 || url.password !== "" || url.protocol === "https:" && url.username !== "" || url.search || url.hash) return;
-	const path = url.pathname.replace(/^\/+|\/+$/gu, "").replace(/\.git$/u, "");
-	if (path.length === 0 || path.split("/").some((part) => part.length === 0 || part === "." || part === "..")) return;
-	const port = url.port && !(url.protocol === "https:" && url.port === "443" || url.protocol === "ssh:" && url.port === "22") ? `:${url.port}` : "";
-	return `${url.hostname.toLowerCase()}${port}/${path}`;
-}
-async function git(dir, args) {
-	const { stdout } = await execFileAsync("git", [
-		"-C",
-		dir,
-		...args
-	], {
-		encoding: "utf8",
-		timeout: 1e4,
-		windowsHide: true
-	});
-	return stdout;
-}
-function namespaceRequired() {
-	return new CliError("Automatic local Assets require --source-namespace because no stable Git remote identity could be derived");
-}
-//#endregion
-//#region src/compile/index.ts
+// src/compile/index.ts
 const COMPILATION_GENERATION_PREFIX = ".topik-compilation-generation-";
 const COMPILATION_PRIOR_PREFIX = ".topik-compilation-prior-";
 const COMPILATION_DIRECTORIES = ["blobs", "resources"];
@@ -148,38 +75,24 @@ 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 (canonical JSON only)").enum("json").default("json"),
 		dryRun: boolean("dry-run").desc("Show what would be compiled without writing files").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"),
-		sourceNamespace: string("source-namespace").desc("Stable source namespace for automatically discovered local Assets (derived from Git when omitted)")
+		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 links = options.links;
 		const outDir = options.outDir ? resolve(options.outDir) : join(dir, ".topik");
 		await assertCompilationOutputScope(dir, outDir);
-		const assetOptions = sourceNamespaceOptions(options.sourceNamespace);
-		let result;
-		try {
-			result = await compile({
-				dir,
-				validation: { links },
-				assets: assetOptions
-			});
-		} catch (error) {
-			if (assetOptions !== void 0 || !requiresSourceNamespace(error)) throw error;
-			result = await compile({
-				dir,
-				validation: { links },
-				assets: { sourceNamespace: await deriveGitSourceNamespace(dir) }
-			});
-		}
-		const { diagnostics, materialization, payloads, resources, semantic } = result;
+		const { diagnostics, materialization, payloads, resources, semantic } = await compile({
+			dir,
+			validation: { links }
+		});
 		printDiagnostics(diagnostics);
 		if (options.validate) {
 			const { valid, errors } = validateResources(resources);
@@ -260,13 +173,14 @@ async function replaceCompilationTree(absolutePath, files) {
 	} 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 (existing !== void 0 && !existingRemoved && existing.name !== target) try {
+	if (published && existing !== void 0 && !existingRemoved && existing.name !== target) try {
 		cleanupCompilationDirectory(parent, existing);
 	} catch (error) {
 		operationError ??= error;
@@ -623,8 +537,9 @@ function procFd(fd) {
 function procFdChild(fd, component) {
 	return `${procFd(fd)}/${component}`;
 }
-//#endregion
-//#region src/dev/index.ts
+// package.json
+var version = "0.1.0-alpha.7";
+// src/dev/index.ts
 const DEV_HOST = "127.0.0.1";
 const DEFAULT_ALLOWED_ORIGIN = "https://write.subtopik.com";
 const REQUEST_VARY_HEADERS = "Origin, Sec-Fetch-Site";
@@ -634,12 +549,10 @@ function sendSSE(res, event, data) {
 function handleResources(watcher, res, corsHeaders) {
 	res.writeHead(200, {
 		"Content-Type": "application/json",
+		"Cache-Control": "no-store",
 		...corsHeaders
 	});
-	res.end(JSON.stringify({
-		resources: [...watcher.resources.values()],
-		payloads: [...watcher.payloads.values()].map(({ bytes: _bytes, ...payload }) => payload)
-	}));
+	res.end(JSON.stringify(watcher.state));
 }
 function handleEvents(watcher, res, corsHeaders) {
 	res.writeHead(200, {
@@ -648,6 +561,9 @@ function handleEvents(watcher, res, corsHeaders) {
 		Connection: "keep-alive",
 		...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]))
@@ -661,6 +577,7 @@ function handleEvents(watcher, res, corsHeaders) {
 	watcher.on("update", onUpdate);
 	res.on("close", () => {
 		watcher.off("update", onUpdate);
+		watcher.off("preview-state", onState);
 	});
 }
 function handleAssetPayload(watcher, rawPathname, method, res, corsHeaders) {
@@ -770,9 +687,15 @@ function createRequestHandler(watcher, getPort, allowedOrigin) {
 		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" }));
+			res.end(JSON.stringify({
+				status: "ok",
+				version,
+				capabilities: [TOPIK_PREVIEW_PROTOCOL],
+				sessionId: watcher.state.sessionId
+			}));
 			return;
 		}
 		if (req.method === "GET" && url.pathname === "/resources") {
@@ -783,6 +706,16 @@ function createRequestHandler(watcher, getPort, allowedOrigin) {
 			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;
@@ -798,21 +731,9 @@ async function startDevServer(options) {
 	const dir = resolve(options.dir);
 	const allowedOrigin = normalizeAllowedOrigin(options.allowOrigin ?? DEFAULT_ALLOWED_ORIGIN);
 	console.log("Watching content for changes...");
-	const assetOptions = sourceNamespaceOptions(options.sourceNamespace);
-	let watcher;
-	try {
-		watcher = await watch({
-			dir,
-			assets: assetOptions
-		});
-	} catch (error) {
-		if (assetOptions !== void 0 || !requiresSourceNamespace(error)) throw error;
-		watcher = await watch({
-			dir,
-			assets: { sourceNamespace: await deriveGitSourceNamespace(dir) }
-		});
-	}
-	console.log(`Compiled ${watcher.resources.size} resources`);
+	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));
 	});
@@ -871,17 +792,15 @@ 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("."),
+		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})`),
-		sourceNamespace: string("source-namespace").desc("Stable source namespace for automatically discovered local Assets (derived from Git when omitted)")
+		allowOrigin: string("allow-origin").desc(`Browser origin allowed to connect (default: ${DEFAULT_ALLOWED_ORIGIN})`)
 	},
 	handler: async (options) => {
 		const runningServer = await startDevServer({
 			dir: resolve(options.dir),
 			port: parseInt(options.port, 10),
-			allowOrigin: options.allowOrigin,
-			sourceNamespace: options.sourceNamespace
+			allowOrigin: options.allowOrigin
 		});
 		console.log(`Dev server listening on http://localhost:${runningServer.port}`);
 		process.once("SIGINT", async () => {
@@ -890,13 +809,12 @@ const dev = command({
 		});
 	}
 });
-//#endregion
-//#region src/lint/index.ts
+// src/lint/index.ts
 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) => {
@@ -912,8 +830,7 @@ const lint$1 = command({
 		console.log(`Lint passed${warnings > 0 ? ` with ${warnings} warning(s)` : ""}`);
 	}
 });
-//#endregion
-//#region src/validate/index.ts
+// src/validate/index.ts
 function parseJson(content) {
 	try {
 		return JSON.parse(content);
@@ -983,8 +900,7 @@ const validate = command({
 		else throw new PublicCliError("resource-validation-failed");
 	}
 });
-//#endregion
-//#region src/cli.ts
+// src/cli.ts
 try {
 	await run([
 		compile$1,
@@ -999,5 +915,4 @@ try {
 	console.error(formatPublicCliError(error));
 	process.exitCode = 1;
 }
-//#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topik/cli",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "description": "Topik CLI",
   "license": "MIT",
   "repository": {
@@ -23,17 +23,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@drizzle-team/brocli": "^0.12.0",
-    "yaml": "^2.9.0",
-    "@topik/content-schema": "0.1.0-alpha.5",
-    "@topik/core": "0.1.0-alpha.5"
+    "@drizzle-team/brocli": "^0.12.1",
+    "@topik/content": "0.1.0-alpha.7",
+    "@topik/core": "0.1.0-alpha.7",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
-    "@types/node": "22.20.1",
+    "@types/bun": "^1.4.4",
+    "@types/node": "22.20.5",
     "typescript": "^7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
-    "vite-plus": "0.2.9"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plus": "1.4.0"
   },
   "scripts": {
     "build": "vp pack",