@stll/folio-cli 0.0.1-placeholder.0 → 0.1.0

package/dist/serve.js

@@ -0,0 +1,234 @@
+import { readDocumentFile } from "./document.js";
+import { journalPathFor } from "./journal.js";
+import { buildDisplayList, displayListHtml } from "./render.js";
+import { SIDECAR_DIRECTORY, inspectPath, readSidecarFile } from "./sidecar.js";
+import { Result } from "better-result";
+import { randomBytes } from "node:crypto";
+import { watch } from "node:fs";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { escapeHtmlText } from "@stll/folio-core/display-list/html/renderDisplayListToHtml";
+import { createServer } from "node:http";
+//#region src/serve.ts
+/**
+* `folio serve`: a read-only live preview of one document on 127.0.0.1.
+*
+* The page is the DOM backend's rendering of the document's display list,
+* the same pages `folio render` writes. The server watches the file (and the
+* `.folio/journal.jsonl` a folio write appends to) and tells the page over
+* server-sent events when the file's version changes, so an edit made by the
+* CLI, the MCP server or any other program shows up without a reload.
+*
+* It never writes: not the document, not a lock, not the journal. It binds
+* to 127.0.0.1 only, every URL carries a random token, requests whose `Host`
+* is not the loopback address it bound are refused (so a web page cannot reach
+* it through a rebound name), and only GET and HEAD are answered.
+*/
+const PREVIEW_HOST = "127.0.0.1";
+/** How often the file is re-checked when a watch event may have been missed. */
+const POLL_INTERVAL_MS = 1e3;
+/** The latest `toVersion` the journal committed for this document, if any. */
+const journalToVersion = async (documentPath) => {
+	const journalPath = journalPathFor(documentPath, void 0);
+	const parent = await inspectPath(path.dirname(journalPath));
+	if (parent.isErr() || parent.value.type !== "directory") return null;
+	const bytes = await readSidecarFile(journalPath);
+	if (bytes.isErr()) return null;
+	const lines = new TextDecoder().decode(bytes.value).split("\n");
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const parsed = Result.try(() => JSON.parse(lines[index] ?? ""));
+		if (!parsed.isOk() || typeof parsed.value !== "object" || parsed.value === null) continue;
+		const entry = { ...parsed.value };
+		if (entry["type"] === "commit" && entry["path"] === documentPath) return typeof entry["toVersion"] === "string" ? entry["toVersion"] : null;
+	}
+	return null;
+};
+const SHELL_STYLE = "html, body { margin: 0; height: 100%; background: #e8e8e8; } iframe { border: 0; width: 100%; height: 100%; display: block; }";
+const shellHtml = (title, nonce) => [
+	"<!doctype html>",
+	`<html><head><meta charset="utf-8"><title>${escapeHtmlText(title)}</title>`,
+	`<style nonce="${nonce}">${SHELL_STYLE}</style></head><body>`,
+	"<iframe id=\"document\" sandbox src=\"document.html\" title=\"document\"></iframe>",
+	`<script nonce="${nonce}">`,
+	"const frame = document.getElementById('document');",
+	"let version = null;",
+	"const events = new EventSource('events');",
+	"events.onmessage = (event) => {",
+	"  const next = JSON.parse(event.data).fileVersion;",
+	"  if (version !== null && next !== version) frame.src = 'document.html?v=' + next;",
+	"  version = next;",
+	"};",
+	"<\/script></body></html>"
+].join("\n");
+const errorHtml = (message) => `<!doctype html><html><head><meta charset="utf-8"><title>folio</title></head><body><pre>${escapeHtmlText(message)}</pre></body></html>`;
+const SECURITY_HEADERS = {
+	"Cache-Control": "no-store",
+	"Referrer-Policy": "no-referrer",
+	"X-Content-Type-Options": "nosniff",
+	"Cross-Origin-Resource-Policy": "same-origin"
+};
+/** The rendered document may contain inline styles and data URLs, and nothing that runs. */
+const DOCUMENT_CSP = "default-src 'none'; img-src data:; font-src data:; style-src 'unsafe-inline'";
+/** Serve the preview until {@link PreviewServer.close}. */
+const startPreviewServer = async ({ documentPath, port }) => {
+	const initial = await readDocumentFile(documentPath);
+	if (initial.isErr()) return Result.err(new Error(initial.error.message));
+	const realPath = initial.value.path;
+	const title = path.basename(realPath);
+	const prefix = `/${randomBytes(24).toString("base64url")}/`;
+	let stamp = null;
+	let rendered = null;
+	let rendering = null;
+	const listeners = /* @__PURE__ */ new Set();
+	/** Render when the file changed since the last render; one render at a time. */
+	const current = async () => {
+		const info = await Result.tryPromise(() => stat(realPath));
+		const next = info.isOk() ? {
+			size: info.value.size,
+			modifiedMs: info.value.mtimeMs,
+			ino: info.value.ino
+		} : null;
+		if (rendered !== null && next !== null && stamp !== null && next.size === stamp.size && next.modifiedMs === stamp.modifiedMs && next.ino === stamp.ino && rendered !== null) return rendered;
+		rendering ??= (async () => {
+			const file = await readDocumentFile(realPath);
+			if (file.isErr()) return {
+				type: "error",
+				fileVersion: null,
+				message: file.error.message
+			};
+			if (rendered !== null && rendered.fileVersion === file.value.fileVersion) return rendered;
+			const list = await buildDisplayList(file.value);
+			if (list.isErr()) return {
+				type: "error",
+				fileVersion: file.value.fileVersion,
+				message: list.error.message
+			};
+			return {
+				type: "page",
+				fileVersion: file.value.fileVersion,
+				html: displayListHtml(list.value, title),
+				pageCount: list.value.pages.length
+			};
+		})();
+		const result = await rendering;
+		rendering = null;
+		const changed = rendered === null || rendered.fileVersion !== result.fileVersion;
+		rendered = result;
+		stamp = next;
+		if (changed) {
+			const message = `data: ${JSON.stringify({ fileVersion: result.fileVersion })}\n\n`;
+			for (const listener of listeners) listener.write(message);
+		}
+		return result;
+	};
+	const check = () => {
+		current();
+	};
+	let boundPort = port;
+	const allowedHosts = () => /* @__PURE__ */ new Set([`${PREVIEW_HOST}:${String(boundPort)}`, `localhost:${String(boundPort)}`]);
+	const respond = (response, status, body, headers = {}) => {
+		response.writeHead(status, {
+			...SECURITY_HEADERS,
+			...headers
+		});
+		response.end(body);
+	};
+	const handle = async (request, response) => {
+		if (!allowedHosts().has(request.headers.host ?? "")) {
+			respond(response, 403, "forbidden", { "Content-Type": "text/plain" });
+			return;
+		}
+		if (request.method !== "GET" && request.method !== "HEAD") {
+			respond(response, 405, "method not allowed", {
+				"Content-Type": "text/plain",
+				Allow: "GET, HEAD"
+			});
+			return;
+		}
+		const url = new URL(request.url ?? "/", `http://${PREVIEW_HOST}`);
+		if (!url.pathname.startsWith(prefix)) {
+			respond(response, 404, "not found", { "Content-Type": "text/plain" });
+			return;
+		}
+		const route = url.pathname.slice(prefix.length);
+		if (route === "") {
+			const nonce = randomBytes(16).toString("base64");
+			respond(response, 200, shellHtml(title, nonce), {
+				"Content-Type": "text/html; charset=utf-8",
+				"Content-Security-Policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; frame-src 'self'; connect-src 'self'`
+			});
+			return;
+		}
+		if (route === "document.html") {
+			const page = await current();
+			respond(response, 200, page.type === "page" ? page.html : errorHtml(page.message), {
+				"Content-Type": "text/html; charset=utf-8",
+				"Content-Security-Policy": DOCUMENT_CSP
+			});
+			return;
+		}
+		if (route === "version") {
+			const page = await current();
+			respond(response, 200, JSON.stringify({
+				path: realPath,
+				fileVersion: page.fileVersion,
+				journalToVersion: await journalToVersion(realPath),
+				...page.type === "page" ? { pageCount: page.pageCount } : { error: page.message }
+			}), { "Content-Type": "application/json" });
+			return;
+		}
+		if (route === "events") {
+			response.writeHead(200, {
+				...SECURITY_HEADERS,
+				"Content-Type": "text/event-stream",
+				Connection: "keep-alive"
+			});
+			listeners.add(response);
+			request.on("close", () => listeners.delete(response));
+			const page = await current();
+			response.write(`data: ${JSON.stringify({ fileVersion: page.fileVersion })}\n\n`);
+			return;
+		}
+		respond(response, 404, "not found", { "Content-Type": "text/plain" });
+	};
+	const server = createServer((request, response) => {
+		handle(request, response).catch((error) => {
+			respond(response, 500, error instanceof Error ? error.message : "error", { "Content-Type": "text/plain" });
+		});
+	});
+	if ((await Result.tryPromise(() => new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, "127.0.0.1", () => resolve());
+	}))).isErr()) return Result.err(/* @__PURE__ */ new Error(`Cannot listen on ${PREVIEW_HOST}:${String(port)}.`));
+	const address = server.address();
+	boundPort = typeof address === "object" && address !== null ? address.port : port;
+	const watchers = [];
+	const directory = path.dirname(realPath);
+	const watched = /* @__PURE__ */ new Set([
+		path.basename(realPath),
+		SIDECAR_DIRECTORY,
+		"journal.jsonl"
+	]);
+	for (const target of [directory, path.join(directory, SIDECAR_DIRECTORY)]) {
+		const watcher = Result.try(() => watch(target, (_event, name) => {
+			if (name === null || watched.has(String(name))) check();
+		}));
+		if (watcher.isOk()) watchers.push(watcher.value);
+	}
+	const poll = setInterval(check, POLL_INTERVAL_MS);
+	check();
+	return Result.ok({
+		url: `http://${PREVIEW_HOST}:${String(boundPort)}${prefix}`,
+		close: async () => {
+			clearInterval(poll);
+			for (const watcher of watchers) watcher.close();
+			for (const listener of listeners) listener.end();
+			await new Promise((resolve) => {
+				server.close(() => resolve());
+				server.closeAllConnections();
+			});
+		}
+	});
+};
+//#endregion
+export { PREVIEW_HOST, startPreviewServer };

package/dist/sidecar.d.ts

@@ -0,0 +1,52 @@
+import { FolioCliError } from "./errors.js";
+import { FileIdentity } from "./document.js";
+import { Result } from "better-result";
+import { FileHandle } from "node:fs/promises";
+//#region src/sidecar.d.ts
+declare const SIDECAR_DIRECTORY = ".folio";
+declare const unsafePath: (message: string, hint?: string) => FolioCliError;
+/** What a path names, without following a final symlink. */
+type PathEntry = {
+  type: "missing";
+} | {
+  type: "file";
+  identity: FileIdentity;
+  links: number;
+  modifiedMs: number;
+} | {
+  type: "directory";
+  identity: FileIdentity;
+} | {
+  type: "other";
+};
+declare const inspectPath: (filePath: string) => Promise<Result<PathEntry, FolioCliError>>;
+/**
+ * `<document directory>/.folio/<segments...>`, each level checked or created
+ * private. The document's own directory is the caller's choice and is not
+ * inspected.
+ */
+declare const sidecarDirectory: (documentPath: string, ...segments: readonly string[]) => Promise<Result<string, FolioCliError>>;
+/** Check the directory a sidecar file lives in; create it only when it is `.folio` itself. */
+declare const ensureSidecarParent: (filePath: string) => Promise<Result<void, FolioCliError>>;
+type OpenedSidecar = {
+  handle: FileHandle;
+  identity: FileIdentity;
+  size: number;
+};
+/**
+ * Open a sidecar file without following a final symlink, and refuse it
+ * unless it is a regular file with exactly one link.
+ */
+declare const openSidecarFile: (filePath: string, flags: number) => Promise<Result<OpenedSidecar, FolioCliError>>;
+/** Read a whole sidecar file through {@link openSidecarFile}. */
+declare const readSidecarFile: (filePath: string) => Promise<Result<Uint8Array<ArrayBuffer>, FolioCliError>>;
+/** Create a new sidecar file (never an existing one), write it, and flush it to disk. */
+declare const writeNewSidecarFile: (filePath: string, bytes: Uint8Array) => Promise<Result<FileIdentity, FolioCliError>>;
+/**
+ * Flush a directory's entries (a create or rename) to disk. Platforms that
+ * cannot open a directory for syncing report nothing; every other failure
+ * is returned.
+ */
+declare const syncDirectory: (directory: string) => Promise<Result<void, FolioCliError>>;
+//#endregion
+export { PathEntry, SIDECAR_DIRECTORY, ensureSidecarParent, inspectPath, openSidecarFile, readSidecarFile, sidecarDirectory, syncDirectory, unsafePath, writeNewSidecarFile };

package/dist/sidecar.js

@@ -0,0 +1,156 @@
+import { NO_FOLLOW, errnoCode } from "./document.js";
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { Result } from "better-result";
+import { constants } from "node:fs";
+import { lstat, mkdir, open } from "node:fs/promises";
+import path from "node:path";
+//#region src/sidecar.ts
+/**
+* The one boundary every file folio keeps beside a document goes through:
+* the lock, the stage, the journal, and backups. None of them follows a
+* symlink or writes through a hard link. The `.folio` directory and its
+* subdirectories are created private (0700), and an existing one that is a
+* symlink or not a directory is refused rather than followed.
+*/
+const SIDECAR_DIRECTORY = ".folio";
+const PRIVATE_DIRECTORY_MODE = 448;
+const PRIVATE_FILE_MODE = 384;
+const describe = (error) => error instanceof Error ? error.message : String(error);
+const unsafePath = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.unsafePath,
+	message,
+	hint
+});
+const fileSystemError = (message, error) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.internal,
+	message: `${message}: ${describe(error)}`
+});
+const inspectPath = async (filePath) => {
+	const info = await Result.tryPromise(() => lstat(filePath));
+	if (info.isErr()) return errnoCode(info.error.cause) === "ENOENT" ? Result.ok({ type: "missing" }) : Result.err(fileSystemError(`Cannot inspect ${filePath}`, info.error.cause));
+	const stats = info.value;
+	const identity = {
+		dev: stats.dev,
+		ino: stats.ino
+	};
+	if (stats.isFile()) return Result.ok({
+		type: "file",
+		identity,
+		links: stats.nlink,
+		modifiedMs: stats.mtimeMs
+	});
+	if (stats.isDirectory()) return Result.ok({
+		type: "directory",
+		identity
+	});
+	return Result.ok({ type: "other" });
+};
+/**
+* Create `directory` private when missing; refuse it when it exists as a
+* symlink or anything but a directory. Its parent must already exist.
+*/
+const ensurePrivateDirectory = async (directory) => {
+	for (let attempt = 0; attempt < 2; attempt++) {
+		const entry = await inspectPath(directory);
+		if (entry.isErr()) return Result.err(entry.error);
+		if (entry.value.type === "directory") return Result.ok();
+		if (entry.value.type !== "missing") return Result.err(unsafePath(`${directory} is not a plain directory; folio does not write through it.`, "Remove or rename it (it may be a symlink), then retry."));
+		const made = await Result.tryPromise(() => mkdir(directory, { mode: PRIVATE_DIRECTORY_MODE }));
+		if (made.isOk()) return Result.ok();
+		if (errnoCode(made.error.cause) !== "EEXIST") return Result.err(fileSystemError(`Cannot create ${directory}`, made.error.cause));
+	}
+	return Result.err(unsafePath(`${directory} changed while it was being created.`));
+};
+/**
+* `<document directory>/.folio/<segments...>`, each level checked or created
+* private. The document's own directory is the caller's choice and is not
+* inspected.
+*/
+const sidecarDirectory = async (documentPath, ...segments) => {
+	let directory = path.join(path.dirname(documentPath), SIDECAR_DIRECTORY);
+	const top = await ensurePrivateDirectory(directory);
+	if (top.isErr()) return Result.err(top.error);
+	for (const segment of segments) {
+		if (segment === "" || segment === "." || segment === ".." || segment.includes(path.sep)) return Result.err(unsafePath(`${JSON.stringify(segment)} is not a plain name.`));
+		directory = path.join(directory, segment);
+		const level = await ensurePrivateDirectory(directory);
+		if (level.isErr()) return Result.err(level.error);
+	}
+	return Result.ok(directory);
+};
+/** Check the directory a sidecar file lives in; create it only when it is `.folio` itself. */
+const ensureSidecarParent = async (filePath) => {
+	const parent = path.dirname(filePath);
+	if (path.basename(parent) === ".folio") return await ensurePrivateDirectory(parent);
+	const entry = await inspectPath(parent);
+	if (entry.isErr()) return Result.err(entry.error);
+	return entry.value.type === "directory" ? Result.ok() : Result.err(unsafePath(`${parent} is not a plain directory.`));
+};
+/**
+* Open a sidecar file without following a final symlink, and refuse it
+* unless it is a regular file with exactly one link.
+*/
+const openSidecarFile = async (filePath, flags) => {
+	const opened = await Result.tryPromise(() => open(filePath, flags | NO_FOLLOW, PRIVATE_FILE_MODE));
+	if (opened.isErr()) {
+		const code = errnoCode(opened.error.cause);
+		return code === "ELOOP" || code === "EMLINK" ? Result.err(unsafePath(`${filePath} is a symlink; folio does not follow it.`)) : Result.err(fileSystemError(`Cannot open ${filePath}`, opened.error.cause));
+	}
+	const handle = opened.value;
+	const info = await Result.tryPromise(() => handle.stat());
+	if (info.isErr() || !info.value.isFile() || info.value.nlink !== 1) {
+		await handle.close();
+		return Result.err(unsafePath(`${filePath} is not a regular file with a single link; folio does not use it.`));
+	}
+	return Result.ok({
+		handle,
+		identity: {
+			dev: info.value.dev,
+			ino: info.value.ino
+		},
+		size: info.value.size
+	});
+};
+/** Read a whole sidecar file through {@link openSidecarFile}. */
+const readSidecarFile = async (filePath) => {
+	const opened = await openSidecarFile(filePath, constants.O_RDONLY);
+	if (opened.isErr()) return Result.err(opened.error);
+	const { handle } = opened.value;
+	const read = await Result.tryPromise(async () => new Uint8Array(await handle.readFile()));
+	await handle.close();
+	return read.isOk() ? Result.ok(read.value) : Result.err(fileSystemError(`Cannot read ${filePath}`, read.error.cause));
+};
+/** Create a new sidecar file (never an existing one), write it, and flush it to disk. */
+const writeNewSidecarFile = async (filePath, bytes) => {
+	const opened = await openSidecarFile(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+	if (opened.isErr()) return Result.err(opened.error);
+	const { handle, identity } = opened.value;
+	const written = await Result.tryPromise(async () => {
+		try {
+			await handle.writeFile(bytes);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	});
+	return written.isOk() ? Result.ok(identity) : Result.err(fileSystemError(`Cannot write ${filePath}`, written.error.cause));
+};
+/**
+* Flush a directory's entries (a create or rename) to disk. Platforms that
+* cannot open a directory for syncing report nothing; every other failure
+* is returned.
+*/
+const syncDirectory = async (directory) => {
+	if (process.platform === "win32") return Result.ok();
+	const synced = await Result.tryPromise(async () => {
+		const handle = await open(directory, constants.O_RDONLY);
+		try {
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	});
+	return synced.isOk() ? Result.ok() : Result.err(fileSystemError(`Cannot flush ${directory}`, synced.error.cause));
+};
+//#endregion
+export { SIDECAR_DIRECTORY, ensureSidecarParent, inspectPath, openSidecarFile, readSidecarFile, sidecarDirectory, syncDirectory, unsafePath, writeNewSidecarFile };

package/dist/transaction.d.ts

@@ -0,0 +1,55 @@
+import { FolioCliError } from "./errors.js";
+import { FileIdentity } from "./document.js";
+import { JournalCommit } from "./journal.js";
+import { ChangedPart } from "./package-parts.js";
+import { Result } from "better-result";
+//#region src/transaction.d.ts
+/** Backups kept per document. */
+declare const MAX_BACKUPS = 20;
+type WriteDestination = {
+  type: "inPlace";
+} | {
+  type: "file";
+  path: string;
+  /** Allow replacing an existing file; its version must then be `expectedVersion`. */
+  overwrite: boolean;
+  expectedVersion: string | undefined;
+};
+/** `.folio/backups/<document name>`, created private and never through a symlink. */
+declare const backupDirectoryFor: (documentPath: string) => Promise<Result<string, FolioCliError>>;
+/**
+ * Keep the newest `keep` backups in one document's backup directory. Only
+ * regular files named `<version>.docx` count; nothing else is touched.
+ */
+declare const pruneBackups: (directory: string, keep: number) => Promise<Result<void, FolioCliError>>;
+type CommitRequest = {
+  txId: string;
+  destinationPath: string;
+  destination: WriteDestination;
+  /** The file the transaction read; re-read under the lease before anything is written. */
+  sourcePath: string;
+  sourceIdentity: FileIdentity;
+  fromVersion: string;
+  bytes: Uint8Array<ArrayBuffer>;
+  changedParts: readonly ChangedPart[];
+  journalPath: string;
+  /** Refuses unless the transaction still holds the destination's lease. */
+  verifyLease: () => Promise<Result<void, FolioCliError>>;
+  /** The journal line, completed with the stage, versions, and backup here. */
+  entry: Omit<JournalCommit, "type" | "path" | "toVersion" | "destinationVersionBefore" | "stage" | "receipt">;
+  /** The receipt returned to the caller; completed with `toVersion` and `backup`. */
+  receipt: Readonly<Record<string, unknown>>;
+};
+type CommitResult = {
+  toVersion: string;
+  backup: string | undefined;
+  receipt: Readonly<Record<string, unknown>>;
+};
+/**
+ * Commit under a lease the caller already holds. Refuses when the source
+ * changed since it was read, when a new destination already exists, or when
+ * an existing destination is not the version the caller named.
+ */
+declare const commitTransaction: (request: CommitRequest) => Promise<Result<CommitResult, FolioCliError>>;
+//#endregion
+export { CommitRequest, CommitResult, MAX_BACKUPS, WriteDestination, backupDirectoryFor, commitTransaction, pruneBackups };