@marver-design/marver 0.21.0 → 0.22.1

package/dist/boards-BwiDAmPf.mjs

@@ -1,337 +0,0 @@
-import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { join, sep } from "node:path";
-import { createHash } from "node:crypto";
-//#region src/server/hash.ts
-/** sha256 hex of a string - the CAS token for board files, the registry, the manifest. */
-const hash = (s) => createHash("sha256").update(s).digest("hex");
-//#endregion
-//#region src/shared/board-tree.ts
-/**
-* Board folders - the pure tree shared by the sidebar, the dev API, the build and the
-* tests. Files are the truth: a board says which folder it sits in (`folder` on the
-* board file - one slug, the folder it sits in directly), ranked among its siblings by
-* `order`, and `design/boards/_folders.json` says which folders exist, where they rank, and
-* which folder holds which (`parent`). Two levels: a folder holds boards and folders, a
-* folder inside a folder (a sub-folder) holds boards only. `all-scenes` never enters the
-* tree - callers pin it last.
-*/
-/** The on-disk name grammar shared by boards and folders (a board name is a filename). */
-const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
-const isBoardName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
-/** The folder registry beside the boards - underscore = infrastructure, never a board. */
-const FOLDERS_FILE = "_folders.json";
-/** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
-*  off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
-const isBoardFile = (f) => f.endsWith(".json") && isBoardName(f.slice(0, -5));
-const readDescription = (v) => {
-	if (typeof v !== "string") return void 0;
-	return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
-};
-const readTitle = (v) => {
-	if (typeof v !== "string") return void 0;
-	return Array.from(v.replace(/[\u0000-\u001f\u007f]/g, " ").trim().replace(/\s+/g, " ")).slice(0, 120).join("").trim() || void 0;
-};
-const rank = (o) => typeof o === "number" && Number.isFinite(o) ? o : Infinity;
-/** A folder's title and description, present only when set. */
-const folderExtras = (it) => ({
-	...it.title ? { title: it.title } : {},
-	...it.description ? { description: it.description } : {}
-});
-/** The registry file's shape. Returns the rows, or a string naming what is wrong - a
-*  malformed registry is an ERROR the human must fix (silently reading it as empty, or
-*  flattening a broken nesting, would let the next drag overwrite their folders), while a
-*  missing file is simply no folders. */
-function parseFolders(raw) {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "expected an object";
-	const { version, folders } = raw;
-	if (version !== void 0 && version !== 1 && version !== 2) return `unsupported version ${String(version)}`;
-	if (!Array.isArray(folders)) return "expected a \"folders\" array";
-	const out = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const f of folders) {
-		const name = f?.name;
-		if (!isBoardName(name)) return "a folder needs a name - lowercase letters, numbers and dashes";
-		if (seen.has(name)) return `folder "${name}" is listed twice`;
-		seen.add(name);
-		const o = f.order;
-		const p = f.parent;
-		if (p !== void 0 && !isBoardName(p)) return `folder "${name}" has an invalid parent - a folder name`;
-		const t = readTitle(f.title);
-		const d = readDescription(f.description);
-		out.push({
-			name,
-			...typeof o === "number" && Number.isFinite(o) ? { order: o } : {},
-			...p !== void 0 ? { parent: p } : {},
-			...t ? { title: t } : {},
-			...d ? { description: d } : {}
-		});
-	}
-	const byName = new Map(out.map((f) => [f.name, f]));
-	for (const f of out) {
-		if (f.parent === void 0) continue;
-		if (version !== 2) return `folder "${f.name}" names a parent - nested folders need "version": 2`;
-		if (f.parent === f.name) return `folder "${f.name}" cannot be its own parent`;
-		const p = byName.get(f.parent);
-		if (!p) return `folder "${f.name}" names an unknown parent "${f.parent}"`;
-		if (p.parent !== void 0) return `folder "${f.name}" would sit three levels deep - folders nest one level only`;
-	}
-	return out;
-}
-/** Sidebar order from the files. At every level the boards and folders there share one
-*  sequence, ranked by `order`, then kind (board before folder), then name; unranked sorts
-*  after ranked. The root holds root boards and top-level folders (registered without a
-*  parent, or implied by a board that names an unregistered folder); a top-level folder holds
-*  its boards and its sub-folders; a sub-folder holds its boards. A folder's title and
-*  description ride on its item (they live in the registry a tree write rewrites); a board's
-*  title stays with its row - it lives in the board's own file. */
-function buildTree(boards, folders) {
-	const reg = /* @__PURE__ */ new Map();
-	for (const f of folders) if (isBoardName(f.name) && !reg.has(f.name)) reg.set(f.name, f);
-	const parentOf = (n) => {
-		const p = reg.get(n)?.parent;
-		return p !== void 0 && p !== n && reg.has(p) && reg.get(p).parent === void 0 ? p : void 0;
-	};
-	const members = /* @__PURE__ */ new Map();
-	const implied = [];
-	const rootBoards = [];
-	for (const b of boards) {
-		if (!isBoardName(b.name) || b.name === "all-scenes") continue;
-		const folder = isBoardName(b.folder) ? b.folder : void 0;
-		if (!folder) {
-			rootBoards.push(b);
-			continue;
-		}
-		if (!reg.has(folder) && !implied.includes(folder)) implied.push(folder);
-		const list = members.get(folder) ?? [];
-		list.push(b);
-		members.set(folder, list);
-	}
-	const sorted = (xs) => xs.sort((a, b) => rank(a.order) - rank(b.order) || (a.item.kind === b.item.kind ? 0 : a.item.kind === "board" ? -1 : 1) || a.item.name.localeCompare(b.item.name)).map((r) => r.item);
-	const boardsHere = (name) => (name === null ? rootBoards : members.get(name) ?? []).map((b) => ({
-		item: {
-			kind: "board",
-			name: b.name
-		},
-		order: b.order
-	}));
-	const folder = (name, kids) => ({
-		item: {
-			kind: "folder",
-			name,
-			items: sorted(kids),
-			...folderExtras(reg.get(name) ?? {})
-		},
-		order: reg.get(name)?.order
-	});
-	const subsOf = (top) => [...reg.keys()].filter((n) => parentOf(n) === top);
-	const tops = [...[...reg.keys()].filter((n) => !parentOf(n)), ...implied];
-	return sorted([...boardsHere(null), ...tops.map((t) => folder(t, [...boardsHere(t), ...subsOf(t).map((s) => folder(s, boardsHere(s)))]))]);
-}
-/** Every board in reading order, depth-first - the order the switchers and the landing pick use. */
-function flatten(tree) {
-	const out = [];
-	const walk = (items) => {
-		for (const it of items) if (it.kind === "board") out.push(it.name);
-		else walk(it.items);
-	};
-	walk(tree);
-	return out;
-}
-const wireKids = (w) => w.items ?? w.boards ?? [];
-function validateWire(wire) {
-	if (!Array.isArray(wire)) return "invalid tree";
-	const boards = /* @__PURE__ */ new Set(), folders = /* @__PURE__ */ new Set();
-	const board = (n) => {
-		if (!isBoardName(n) || n === "all-scenes") return "invalid board name in tree";
-		if (boards.has(n)) return `board "${n}" appears twice`;
-		boards.add(n);
-		return null;
-	};
-	const walk = (list, depth) => {
-		for (const w of list) {
-			if (typeof w === "string") {
-				const e = board(w);
-				if (e) return e;
-				continue;
-			}
-			if (!w || typeof w !== "object" || Array.isArray(w)) return "invalid tree item";
-			if (depth >= 2) return "folders nest one level only";
-			const { folder, items, boards: legacy, title, description } = w;
-			if (!isBoardName(folder)) return "invalid folder name in tree";
-			if (title !== void 0 && (typeof title !== "string" || Array.from(title).length > 120)) return "invalid folder title";
-			if (description !== void 0 && (typeof description !== "string" || description.length > 300)) return "invalid folder description";
-			if (folders.has(folder)) return `folder "${folder}" appears twice`;
-			folders.add(folder);
-			const kids = items ?? legacy;
-			if (!Array.isArray(kids)) return "invalid folder in tree";
-			if (items === void 0 && kids.some((k) => typeof k !== "string")) return "invalid folder in tree";
-			const e = walk(kids, depth + 1);
-			if (e) return e;
-		}
-		return null;
-	};
-	const e = walk(wire, 0);
-	if (e) return e;
-	if (boards.size > 200 || folders.size > 50) return "tree too large";
-	return null;
-}
-/** Every folder with the folder it sits in (null = the root), top-level folders first in
-*  reading order, each followed by its sub-folders. */
-function folderEntries(t) {
-	const out = [];
-	for (const it of t) {
-		if (it.kind !== "folder") continue;
-		out.push({
-			folder: it,
-			parent: null
-		});
-		for (const k of it.items) if (k.kind === "folder") out.push({
-			folder: k,
-			parent: it.name
-		});
-	}
-	return out;
-}
-//#endregion
-//#region src/server/boards.ts
-/**
-* Reading design/boards/ safely - the one enumerator the dev API, the build and the tests
-* share. Only REGULAR files on the board-name grammar count as boards (a symlink, dangling or
-* live, could read or publish JSON from outside the project - it is skipped, and reported so
-* the build can fail closed). The folder registry is read the same way: absent = no folders,
-* malformed = an error the human must fix, never a silently empty registry.
-*/
-/** Does realpath(dir) stay inside realpath(root)? A symlinked design/boards can't escape. */
-function underRoot(root, dir) {
-	try {
-		const rr = realpathSync(root);
-		const rd = realpathSync(dir);
-		return rd === rr || rd.startsWith(rr + sep);
-	} catch {
-		return false;
-	}
-}
-/** Is design/boards a directory we may read and write? It must not be a symlink at all (a
-*  link to the repo root would list package.json as a board and let a tree write rewrite
-*  it; a link outside would publish foreign JSON) and must resolve inside the root. Absent
-*  is fine (no boards yet). Returns the error, or null. */
-function checkBoardsDir(root, boardsDir) {
-	return checkRealDirs(root, [[join(boardsDir, ".."), "design"], [boardsDir, "design/boards"]]);
-}
-/** Every EXISTING path in `dirs` (root-down order) must be a real directory inside the root -
-*  a symlinked `design` with no boards dir yet would otherwise be followed by the mkdir that
-*  creates it; a symlinked `design/scenes` would let a brief write land outside the project.
-*  An absent one ends the walk (nothing beneath it exists either). Returns the error, or null. */
-function checkRealDirs(root, dirs) {
-	for (const [p, label] of dirs) {
-		try {
-			if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
-		} catch {
-			return null;
-		}
-		if (!underRoot(root, p)) return `${label} escapes the project`;
-	}
-	return null;
-}
-/** A regular file (lstat: a symlink is never followed, a dangling one is not "absent"). */
-const isRegularFile = (p) => {
-	try {
-		return lstatSync(p).isFile();
-	} catch {
-		return false;
-	}
-};
-/** Is there ANY node at p (a dangling symlink counts)? */
-const nodeExists = (p) => {
-	try {
-		lstatSync(p);
-		return true;
-	} catch {
-		return false;
-	}
-};
-/** Every board file: name, raw content, hash, and its JSON (null when malformed). `skipped`
-*  names the entries that looked like boards but were not regular files. */
-function listBoardFiles(boardsDir) {
-	const boards = [], skipped = [];
-	if (!existsSync(boardsDir)) return {
-		boards,
-		skipped
-	};
-	for (const f of readdirSync(boardsDir)) {
-		if (!isBoardFile(f)) continue;
-		const file = join(boardsDir, f);
-		if (!isRegularFile(file)) {
-			skipped.push(f);
-			continue;
-		}
-		const content = readFileSync(file, "utf8");
-		let json = null;
-		try {
-			json = JSON.parse(content);
-		} catch {}
-		boards.push({
-			name: f.slice(0, -5),
-			file,
-			content,
-			sha256: hash(content),
-			json
-		});
-	}
-	return {
-		boards,
-		skipped
-	};
-}
-/** The author-owned sidebar fields off a board's JSON, leniently: rank, folder, the title
-*  humans see, the sentence agents read. */
-function boardFields(json, validName) {
-	const o = json;
-	const title = readTitle(o?.title);
-	const description = readDescription(o?.description);
-	return {
-		...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
-		...validName(o?.folder) ? { folder: o.folder } : {},
-		...title ? { title } : {},
-		...description ? { description } : {}
-	};
-}
-/** The folder registry. `sha256` is the CAS token a tree write must echo (null = "there was
-*  no file"), so a write can never silently replace a registry it never saw. */
-function readRegistry(boardsDir) {
-	const p = join(boardsDir, FOLDERS_FILE);
-	if (!nodeExists(p)) return {
-		state: "absent",
-		folders: [],
-		sha256: null
-	};
-	if (!isRegularFile(p)) return {
-		state: "malformed",
-		error: `design/boards/${FOLDERS_FILE} must be a regular file, not a symlink`,
-		sha256: null
-	};
-	const content = readFileSync(p, "utf8");
-	let raw;
-	try {
-		raw = JSON.parse(content);
-	} catch {
-		return {
-			state: "malformed",
-			error: `design/boards/${FOLDERS_FILE} is not valid JSON - fix the file`,
-			sha256: hash(content)
-		};
-	}
-	const parsed = parseFolders(raw);
-	if (typeof parsed === "string") return {
-		state: "malformed",
-		error: `design/boards/${FOLDERS_FILE}: ${parsed}`,
-		sha256: hash(content)
-	};
-	return {
-		state: "ok",
-		folders: parsed,
-		sha256: hash(content)
-	};
-}
-//#endregion
-export { wireKids as _, listBoardFiles as a, BOARD_NAME as c, flatten as d, folderEntries as f, validateWire as g, readTitle as h, isRegularFile as i, FOLDERS_FILE as l, readDescription as m, checkBoardsDir as n, nodeExists as o, isBoardName as p, checkRealDirs as r, readRegistry as s, boardFields as t, buildTree as u, hash as v };

package/dist/boards-DnLewfj8.mjs

@@ -1,71 +0,0 @@
-import { a as listBoardFiles, d as flatten, n as checkBoardsDir, p as isBoardName, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BwiDAmPf.mjs";
-import { join } from "node:path";
-//#region src/cli/boards.ts
-/**
-* `marver boards` - the sidebar as the agent sees it: every folder and board in reading
-* order - sub-folders indented under their parent - from the files (no dev server needed). One
-* call answers "what folders exist, what is in them, what ranks where" before the agent writes `folder` on a board or edits
-* `design/boards/_folders.json`. `--json` gives the tree shape the shell uses.
-*/
-function boardsCommand(root, opts) {
-	const dir = join(root, "design", "boards");
-	const de = checkBoardsDir(root, dir);
-	if (de) throw new Error(de);
-	const { boards, skipped } = listBoardFiles(dir);
-	const reg = readRegistry(dir);
-	if (reg.state === "malformed") throw new Error(reg.error);
-	const rows = boards.map((b) => ({
-		name: b.name,
-		...boardFields(b.json, isBoardName)
-	}));
-	const tree = buildTree(rows, reg.folders);
-	const hasAll = boards.some((b) => b.name === "all-scenes");
-	if (opts.json) {
-		console.log(JSON.stringify({
-			tree,
-			boards: rows.filter((r) => r.name !== "all-scenes"),
-			landing: flatten(tree)[0] ?? (hasAll ? "all-scenes" : null),
-			registry: reg.state === "ok" ? "design/boards/_folders.json" : null
-		}, null, 2));
-		return;
-	}
-	if (!tree.length && !hasAll) {
-		console.log("no boards yet - design/boards/ is empty");
-		return;
-	}
-	const order = (n) => {
-		const o = rows.find((r) => r.name === n)?.order;
-		return o === void 0 ? "" : `  order ${o}`;
-	};
-	const title = (t) => t ? `  "${t}"` : "";
-	const desc = (d) => d ? `  - ${d}` : "";
-	const boardLine = (n) => {
-		const r = rows.find((x) => x.name === n);
-		return `${n}${title(r?.title)}${order(n)}${desc(r?.description)}`;
-	};
-	const count = (f) => {
-		const boards = f.items.filter((k) => k.kind === "board").length, subs = f.items.length - boards;
-		return `${boards} board${boards === 1 ? "" : "s"}${subs ? `, ${subs} folder${subs === 1 ? "" : "s"}` : ""}`;
-	};
-	const print = (items, pad, parent) => {
-		for (const it of items) {
-			if (it.kind === "board") {
-				console.log(`${pad}${boardLine(it.name)}`);
-				continue;
-			}
-			const where = parent ? `sub-folder of ${parent}` : "folder";
-			const implied = reg.folders.some((f) => f.name === it.name) ? "" : ", implied by its boards - not in _folders.json";
-			console.log(`${pad}${it.name}/${title(it.title)}  (${where}, ${count(it)}${implied})${desc(it.description)}`);
-			print(it.items, `${pad}  `, it.name);
-			if (!it.items.length) console.log(`${pad}  (empty)`);
-		}
-	};
-	print(tree, "", null);
-	if (hasAll) console.log("all-scenes  (auto, always last)");
-	const landing = flatten(tree)[0];
-	if (landing) console.log(`\nlanding board: ${landing}`);
-	console.log(`registry: ${reg.state === "ok" ? "design/boards/_folders.json" : "none (no empty or ranked folders yet)"}`);
-	if (skipped.length) console.log(`skipped (not regular files): ${skipped.join(", ")}`);
-}
-//#endregion
-export { boardsCommand };