@first-tree-ai/context-tree 0.0.1 → 0.1.0

package/dist/src-Ce9BtETD.mjs

@@ -0,0 +1,794 @@
+import { S as isRecord, g as parseContextTreeScope, i as VALIDATION_CODES, x as parseMarkdownFrontmatter } from "./schemas-D0Qt1bWc.mjs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { fromMarkdown } from "mdast-util-from-markdown";
+//#region src/core/internal/packaged-resource.ts
+const PACKAGE_NAME = "@first-tree-ai/context-tree";
+function isPackageRoot(path) {
+	const manifestPath = join(path, "package.json");
+	if (!existsSync(manifestPath)) return false;
+	try {
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+		return typeof manifest === "object" && manifest !== null && "name" in manifest && manifest.name === PACKAGE_NAME;
+	} catch {
+		return false;
+	}
+}
+function resolvePackagedResource(...segments) {
+	let candidate = dirname(fileURLToPath(import.meta.url));
+	const filesystemRoot = parse(candidate).root;
+	while (true) {
+		if (isPackageRoot(candidate)) {
+			const resource = resolve(candidate, ...segments);
+			if (existsSync(resource)) return resource;
+			throw new Error(`Packaged resource is missing: ${segments.join("/")}`);
+		}
+		if (candidate === filesystemRoot) break;
+		candidate = dirname(candidate);
+	}
+	throw new Error(`Package root is missing while resolving: ${segments.join("/")}`);
+}
+function readPackageManifest() {
+	const parsed = JSON.parse(readFileSync(resolvePackagedResource("package.json"), "utf8"));
+	if (!isRecord(parsed)) throw new Error("Package metadata is invalid.");
+	return parsed;
+}
+//#endregion
+//#region src/core/policy.ts
+function readContextTreePolicy() {
+	return {
+		content: readFileSync(resolvePackagedResource("policy", "context-tree-policy.md"), "utf8"),
+		schemaVersion: 1
+	};
+}
+//#endregion
+//#region src/core/path.ts
+function isPathInside(root, target) {
+	const path = relative(root, target);
+	return path === "" || !path.startsWith("..") && !isAbsolute(path);
+}
+function resolveTreeRoot(path) {
+	const absolute = resolve(path);
+	const entry = lstatSync(absolute);
+	if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Context Tree root must be a real directory: ${path}`);
+	return realpathSync(absolute);
+}
+function toPosixPath(path) {
+	return path.replace(/\\/gu, "/");
+}
+//#endregion
+//#region src/core/internal/content-class.ts
+const GENERATED_DIRECTORY_NAMES = new Set([
+	"node_modules",
+	"__pycache__",
+	"dist",
+	"build",
+	".next",
+	".turbo"
+]);
+const REPO_INFRA_MARKDOWN_FILES = new Set(["AGENTS.md", "CLAUDE.md"]);
+const MANAGED_SYMLINK_PATHS = new Set(["WHITEPAPER.md"]);
+function toTreeRelativePosixPath(treeRoot, targetPath) {
+	return relative(treeRoot, targetPath).replace(/\\/gu, "/");
+}
+function classifyContextContent(relativePath) {
+	const parts = relativePath.replace(/\\/gu, "/").replace(/^\.\//u, "").split("/").filter((part) => part.length > 0);
+	if (parts.length === 0 || parts.some((part) => part.startsWith(".") || GENERATED_DIRECTORY_NAMES.has(part)) || REPO_INFRA_MARKDOWN_FILES.has(parts.at(-1) ?? "")) return "repo-infra";
+	if (parts[0] === "raw-context") return "archive-supporting";
+	if (parts[0] === "members") return "member";
+	return "normal";
+}
+function emptyContentClassCounts() {
+	return {
+		normal: 0,
+		"archive-supporting": 0,
+		member: 0,
+		"repo-infra": 0
+	};
+}
+function isSafeCanonicalMarkdown(file) {
+	return file.contentClass !== "repo-infra" && !file.escaped && !file.unresolved && !file.unsupported && file.canonicalContentClass === file.contentClass;
+}
+function readDirectoryEntries(path) {
+	try {
+		return readdirSync(path, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+	} catch {
+		return [];
+	}
+}
+function collectContextMarkdownContent(treeRoot) {
+	const directorySymlinks = [];
+	const files = [];
+	const realTreeRoot = realpathSync(treeRoot);
+	function walk(directoryPath) {
+		for (const entry of readDirectoryEntries(directoryPath)) {
+			const absolutePath = join(directoryPath, entry.name);
+			const relativePath = toTreeRelativePosixPath(treeRoot, absolutePath);
+			const contentClass = classifyContextContent(relativePath);
+			if (entry.isDirectory()) {
+				if (contentClass !== "repo-infra") walk(absolutePath);
+				continue;
+			}
+			const symbolicLink = entry.isSymbolicLink();
+			if (symbolicLink) try {
+				const targetStat = statSync(absolutePath);
+				if (targetStat.isDirectory()) {
+					if (contentClass !== "repo-infra" || entry.name.endsWith(".md")) directorySymlinks.push({
+						contentClass,
+						escaped: !isPathInside(realTreeRoot, realpathSync(absolutePath)),
+						relativePath
+					});
+					continue;
+				}
+				if (!targetStat.isFile() && entry.name.endsWith(".md")) {
+					let escaped = false;
+					let canonicalContentClass = contentClass;
+					let canonicalRelativePath = relativePath;
+					try {
+						const realTarget = realpathSync(absolutePath);
+						escaped = !isPathInside(realTreeRoot, realTarget);
+						canonicalRelativePath = toTreeRelativePosixPath(realTreeRoot, realTarget);
+						if (!escaped) canonicalContentClass = classifyContextContent(canonicalRelativePath);
+					} catch {
+						files.push({
+							absolutePath,
+							canonicalContentClass,
+							canonicalRelativePath,
+							contentClass,
+							escaped: false,
+							relativePath,
+							unsupported: false,
+							unresolved: true
+						});
+						continue;
+					}
+					files.push({
+						absolutePath,
+						canonicalContentClass,
+						canonicalRelativePath,
+						contentClass,
+						escaped,
+						relativePath,
+						unsupported: true,
+						unresolved: false
+					});
+					continue;
+				}
+			} catch {
+				if (MANAGED_SYMLINK_PATHS.has(relativePath)) continue;
+				if (entry.name.endsWith(".md")) files.push({
+					absolutePath,
+					canonicalContentClass: contentClass,
+					canonicalRelativePath: relativePath,
+					contentClass,
+					escaped: false,
+					relativePath,
+					unsupported: false,
+					unresolved: true
+				});
+				continue;
+			}
+			if (!entry.isFile() && !symbolicLink || !entry.name.endsWith(".md")) continue;
+			if (symbolicLink && MANAGED_SYMLINK_PATHS.has(relativePath)) continue;
+			try {
+				if (!statSync(absolutePath).isFile()) continue;
+			} catch {
+				continue;
+			}
+			let escaped = false;
+			let canonicalContentClass = contentClass;
+			let canonicalRelativePath = relativePath;
+			if (symbolicLink) try {
+				const realTarget = realpathSync(absolutePath);
+				escaped = !isPathInside(realTreeRoot, realTarget);
+				canonicalRelativePath = toTreeRelativePosixPath(realTreeRoot, realTarget);
+				if (!escaped) canonicalContentClass = classifyContextContent(canonicalRelativePath);
+			} catch {
+				continue;
+			}
+			files.push({
+				absolutePath,
+				canonicalContentClass,
+				canonicalRelativePath,
+				contentClass,
+				escaped,
+				relativePath,
+				unsupported: false,
+				unresolved: false
+			});
+		}
+	}
+	walk(treeRoot);
+	return {
+		directorySymlinks,
+		files
+	};
+}
+//#endregion
+//#region src/core/internal/filesystem.ts
+function readUtf8File(path) {
+	return new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path));
+}
+//#endregion
+//#region src/core/internal/context-document.ts
+function readContextDocument(path) {
+	try {
+		return parseMarkdownFrontmatter(readUtf8File(path));
+	} catch (error) {
+		return {
+			body: "",
+			data: null,
+			error: error instanceof Error ? error.message : String(error),
+			frontmatter: "invalid"
+		};
+	}
+}
+function readNonEmptyStringField(data, key) {
+	if (!(key in data)) return {
+		present: false,
+		valid: false
+	};
+	const value = data[key];
+	if (typeof value !== "string" || value.trim().length === 0) return {
+		present: true,
+		valid: false
+	};
+	return {
+		present: true,
+		valid: true,
+		value: value.trim()
+	};
+}
+function readNonEmptyStringArrayField(data, key) {
+	if (!(key in data)) return {
+		present: false,
+		valid: false
+	};
+	const value = data[key];
+	if (!Array.isArray(value) || value.length === 0) return {
+		present: true,
+		valid: false
+	};
+	const items = [];
+	for (const item of value) {
+		if (typeof item !== "string" || item.trim().length === 0) return {
+			present: true,
+			valid: false
+		};
+		items.push(item.trim());
+	}
+	return {
+		present: true,
+		valid: true,
+		value: items
+	};
+}
+function readNodeMetadata(path) {
+	const document = readContextDocument(path);
+	if (document.frontmatter !== "valid" || document.data === null) return null;
+	const title = readNonEmptyStringField(document.data, "title");
+	const owners = readNonEmptyStringArrayField(document.data, "owners");
+	const description = readNonEmptyStringField(document.data, "description");
+	if (!title.valid || !owners.valid || description.present && !description.valid) return null;
+	return {
+		title: title.value,
+		owners: owners.value,
+		...description.valid ? { description: description.value } : {}
+	};
+}
+//#endregion
+//#region src/core/internal/tree-selection.ts
+function normalizeTreeTarget(value) {
+	if (!value || value === ".") return "";
+	const normalized = posix.normalize(toPosixPath(value).replace(/^\.\//u, ""));
+	if (normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) throw new Error(`Read target is outside the Context Tree: ${value}`);
+	return normalized.replace(/\/$/u, "");
+}
+function compileSegmentLocalGlob(pattern) {
+	let source = "^";
+	for (const character of pattern) if (character === "*") source += "[^/]*";
+	else if (character === "?") source += "[^/]";
+	else source += character.replace(/[|\\{}()[\]^$+?.]/gu, "\\$&");
+	return new RegExp(`${source}$`, "u");
+}
+function entryDepth(path) {
+	if (path === "." || path.length === 0) return 0;
+	return path.split("/").length;
+}
+function relativeTreeDepth(path, target) {
+	return Math.max(0, entryDepth(path) - entryDepth(target));
+}
+function isTreeEntryWithinTarget(path, sourcePath, target) {
+	return target.length === 0 || path === target || path.startsWith(`${target}/`) || sourcePath === target || sourcePath.startsWith(`${target}/`);
+}
+function displayTitle(relativePath) {
+	return basename(relativePath, ".md").split(/[-_]/u).filter(Boolean).map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" ");
+}
+function deriveTreeEntry(relativePath, metadataTitle) {
+	const isNode = basename(relativePath) === "NODE.md";
+	const entryPath = isNode ? dirname(relativePath).replace(/^\.$/u, ".") : relativePath;
+	const normalizedPath = entryPath === "." ? "" : toPosixPath(entryPath);
+	return {
+		kind: isNode ? "directory" : "file",
+		path: normalizedPath,
+		title: metadataTitle ?? (relativePath === "SCOPE.md" ? "Scope" : displayTitle(relativePath))
+	};
+}
+function compareTreeEntries(left, right) {
+	const leftParts = left.path === "." ? [] : left.path.split("/");
+	const rightParts = right.path === "." ? [] : right.path.split("/");
+	const sharedLength = Math.min(leftParts.length, rightParts.length);
+	for (let index = 0; index < sharedLength; index += 1) {
+		const comparison = (leftParts[index] ?? "").localeCompare(rightParts[index] ?? "");
+		if (comparison !== 0) return comparison;
+	}
+	return leftParts.length - rightParts.length || left.kind.localeCompare(right.kind);
+}
+//#endregion
+//#region src/core/read.ts
+function allSafeMarkdown(root) {
+	return collectContextMarkdownContent(root).files.filter(isSafeCanonicalMarkdown).map((file) => ({
+		absolutePath: file.absolutePath,
+		contentClass: file.contentClass,
+		relativePath: file.relativePath
+	})).sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function readTree(treePath, options = {}) {
+	const root = resolveTreeRoot(treePath);
+	const target = normalizeTreeTarget(options.path);
+	const absoluteTarget = resolve(root, target);
+	if (!isPathInside(root, absoluteTarget)) throw new Error("Read target escapes the Context Tree root.");
+	const targetEntry = lstatSync(absoluteTarget);
+	if (targetEntry.isSymbolicLink() || !targetEntry.isDirectory() && !targetEntry.isFile()) throw new Error(`Read target must be a real file or directory: ${target || "."}`);
+	const classes = options.classes ?? ["normal"];
+	const pattern = options.pattern ? compileSegmentLocalGlob(options.pattern) : null;
+	const entries = [];
+	for (const file of allSafeMarkdown(root)) {
+		if (classes !== "all" && !classes.includes(file.contentClass)) continue;
+		const metadata = file.relativePath === "SCOPE.md" ? null : readNodeMetadata(file.absolutePath);
+		const entry = deriveTreeEntry(file.relativePath, metadata?.title);
+		if (!isTreeEntryWithinTarget(entry.path, file.relativePath, target)) continue;
+		const depth = relativeTreeDepth(entry.path, target);
+		if (options.depth !== void 0 && depth > options.depth) continue;
+		const candidates = [
+			entry.path,
+			file.relativePath,
+			entry.title,
+			metadata?.description ?? ""
+		];
+		if (pattern && !candidates.some((candidate) => pattern.test(candidate))) continue;
+		const source = readUtf8File(file.absolutePath);
+		entries.push({
+			contentClass: file.contentClass,
+			depth,
+			kind: entry.kind,
+			owners: metadata?.owners ?? [],
+			path: entry.path || ".",
+			title: entry.title,
+			...metadata?.description ? { description: metadata.description } : {},
+			...options.content ? { content: source } : {}
+		});
+	}
+	return {
+		entries: entries.sort(compareTreeEntries),
+		root,
+		schemaVersion: 1,
+		target: target || "."
+	};
+}
+function classifyTreePath(path) {
+	return classifyContextContent(path);
+}
+//#endregion
+//#region src/core/internal/validate-members.ts
+const VALID_TYPES = new Set(["human", "agent"]);
+const VALID_STATUSES = new Set(["invited"]);
+function addFinding$1(findings, code, path, message) {
+	findings.push({
+		code,
+		message,
+		path
+	});
+}
+function validateMember(nodePath, treeRoot) {
+	const findings = [];
+	const location = toTreeRelativePosixPath(treeRoot, nodePath);
+	const document = readContextDocument(nodePath);
+	if (document.frontmatter === "missing") {
+		addFinding$1(findings, VALIDATION_CODES.memberFrontmatterMissing, location, "no frontmatter found");
+		return findings;
+	}
+	if (document.frontmatter === "invalid" || document.data === null) {
+		addFinding$1(findings, VALIDATION_CODES.memberFrontmatterParse, location, `frontmatter could not be parsed${document.error === void 0 ? "" : `: ${document.error}`}`);
+		return findings;
+	}
+	if (!readNonEmptyStringField(document.data, "title").valid) addFinding$1(findings, VALIDATION_CODES.memberTitleInvalid, location, "missing or invalid 'title' field");
+	const owners = readNonEmptyStringArrayField(document.data, "owners");
+	if (!owners.present) addFinding$1(findings, VALIDATION_CODES.memberOwnersMissing, location, "missing 'owners' field");
+	else if (!owners.valid) addFinding$1(findings, VALIDATION_CODES.memberOwnersInvalid, location, "'owners' must be a non-empty string array");
+	const memberType = readNonEmptyStringField(document.data, "type");
+	if (!memberType.present) addFinding$1(findings, VALIDATION_CODES.memberTypeMissing, location, "missing 'type' field");
+	else if (!memberType.valid) addFinding$1(findings, VALIDATION_CODES.memberTypeShape, location, "'type' must be a non-empty string");
+	else if (!VALID_TYPES.has(memberType.value)) addFinding$1(findings, VALIDATION_CODES.memberTypeInvalid, location, `invalid type '${memberType.value}' — must be one of: ${[...VALID_TYPES].sort().join(", ")}`);
+	const status = readNonEmptyStringField(document.data, "status");
+	if (status.present && !status.valid) addFinding$1(findings, VALIDATION_CODES.memberStatusShape, location, "'status' must be a non-empty string when present");
+	else if (status.valid && !VALID_STATUSES.has(status.value)) addFinding$1(findings, VALIDATION_CODES.memberStatusInvalid, location, `invalid status '${status.value}' — must be one of: ${[...VALID_STATUSES].sort().join(", ")}`);
+	const role = readNonEmptyStringField(document.data, "role");
+	if (!role.present) addFinding$1(findings, VALIDATION_CODES.memberRoleInvalid, location, "missing 'role' field");
+	else if (!role.valid) addFinding$1(findings, VALIDATION_CODES.memberRoleShape, location, "'role' must be a non-empty string");
+	const domains = readNonEmptyStringArrayField(document.data, "domains");
+	if (!domains.present) addFinding$1(findings, VALIDATION_CODES.memberDomainsInvalid, location, "missing 'domains' field");
+	else if (!domains.valid) {
+		const value = document.data.domains;
+		addFinding$1(findings, Array.isArray(value) && value.length === 0 ? VALIDATION_CODES.memberDomainsInvalid : VALIDATION_CODES.memberDomainsShape, location, Array.isArray(value) && value.length === 0 ? "'domains' must contain at least one entry" : "'domains' must be a non-empty string array");
+	}
+	return findings;
+}
+function collectMemberValidationFindings(treeRoot) {
+	const membersDir = join(treeRoot, "members");
+	const findings = [];
+	if (!existsSync(membersDir)) {
+		addFinding$1(findings, VALIDATION_CODES.membersDirectoryMissing, "members/", `Members directory not found: ${membersDir}`);
+		return findings;
+	}
+	try {
+		const membersStat = lstatSync(membersDir);
+		if (membersStat.isSymbolicLink()) return findings;
+		if (!membersStat.isDirectory()) {
+			addFinding$1(findings, VALIDATION_CODES.membersDirectoryMissing, "members/", `Members directory not found: ${membersDir}`);
+			return findings;
+		}
+	} catch {
+		addFinding$1(findings, VALIDATION_CODES.membersDirectoryMissing, "members/", `Members directory not found: ${membersDir}`);
+		return findings;
+	}
+	let memberCount = 0;
+	function walk(dir, requireNode) {
+		const entries = readdirSync(dir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+		for (const entry of entries) {
+			if (entry.isSymbolicLink() || !entry.isDirectory()) continue;
+			const childPath = join(dir, entry.name);
+			const nodePath = join(childPath, "NODE.md");
+			if (!existsSync(nodePath)) {
+				if (requireNode) {
+					const path = `${toTreeRelativePosixPath(treeRoot, childPath)}/`;
+					addFinding$1(findings, VALIDATION_CODES.memberNodeMissing, path, "directory exists but is missing NODE.md");
+					walk(childPath, false);
+				}
+				continue;
+			}
+			memberCount += 1;
+			findings.push(...validateMember(nodePath, treeRoot));
+			walk(childPath, false);
+		}
+	}
+	walk(membersDir, true);
+	if (memberCount === 0) addFinding$1(findings, VALIDATION_CODES.memberNodesEmpty, "members/", "no member nodes were found");
+	return findings;
+}
+//#endregion
+//#region src/core/internal/context-links.ts
+function stripQueryAndFragment(target) {
+	const indexes = [target.indexOf("?"), target.indexOf("#")].filter((index) => index >= 0);
+	const end = indexes.length === 0 ? target.length : Math.min(...indexes);
+	return target.slice(0, end);
+}
+function decodeTarget(target) {
+	try {
+		return decodeURIComponent(target);
+	} catch {
+		return target;
+	}
+}
+function isWindowsAbsoluteTarget(target) {
+	return /^[a-z]:[\\/]/iu.test(target) || /^\\/u.test(target);
+}
+function isTreeLocalTarget(target) {
+	const trimmed = target.trim();
+	if (isWindowsAbsoluteTarget(decodeTarget(stripQueryAndFragment(trimmed)))) return true;
+	return trimmed.length > 0 && !trimmed.startsWith("#") && !trimmed.startsWith("//") && !/^[a-z][a-z\d+.-]*:/iu.test(trimmed);
+}
+function targetExists(path, softLink) {
+	try {
+		const stat = statSync(path);
+		if (stat.isFile()) return !softLink || path.endsWith(".md");
+		return stat.isDirectory() && (!softLink || existsSync(resolve(path, "NODE.md")));
+	} catch {
+		return false;
+	}
+}
+function resolveLocalTreeTarget(options) {
+	if (!isTreeLocalTarget(options.target)) return null;
+	const decodedTarget = decodeTarget(stripQueryAndFragment(options.target.trim()));
+	const withoutSuffix = decodedTarget.replace(/\\/gu, "/");
+	if (withoutSuffix.length === 0) return null;
+	if (isWindowsAbsoluteTarget(decodedTarget)) return {
+		contentClass: classifyContextContent(withoutSuffix),
+		escaped: true,
+		exists: false,
+		relativePath: withoutSuffix
+	};
+	const sourceDirectory = posix.dirname(options.sourcePath);
+	const relativePath = posix.normalize(options.softLink || withoutSuffix.startsWith("/") ? withoutSuffix.replace(/^\/+/, "") : posix.join(sourceDirectory, withoutSuffix));
+	const absoluteRoot = resolve(options.treeRoot);
+	const absoluteTarget = resolve(absoluteRoot, relativePath);
+	const lexicalEscape = !isPathInside(absoluteRoot, absoluteTarget);
+	let contentClass = classifyContextContent(relativePath);
+	if (lexicalEscape) return {
+		contentClass,
+		escaped: true,
+		exists: false,
+		relativePath
+	};
+	if (!targetExists(absoluteTarget, options.softLink)) return {
+		contentClass,
+		escaped: false,
+		exists: false,
+		relativePath
+	};
+	try {
+		const realRoot = realpathSync(absoluteRoot);
+		const realTarget = realpathSync(absoluteTarget);
+		if (!isPathInside(realRoot, realTarget)) return {
+			contentClass,
+			escaped: true,
+			exists: true,
+			relativePath
+		};
+		contentClass = classifyContextContent(relative(realRoot, realTarget).replace(/\\/gu, "/"));
+	} catch {
+		return {
+			contentClass,
+			escaped: false,
+			exists: false,
+			relativePath
+		};
+	}
+	return {
+		contentClass,
+		escaped: false,
+		exists: true,
+		relativePath
+	};
+}
+function readMarkdownLinkTargets(markdown) {
+	const root = fromMarkdown(markdown);
+	const targets = [];
+	function visit(node) {
+		if (!isRecord(node)) return;
+		if ((node.type === "link" || node.type === "image" || node.type === "definition") && typeof node.url === "string") targets.push(node.url);
+		if (Array.isArray(node.children)) for (const child of node.children) visit(child);
+	}
+	visit(root);
+	return targets;
+}
+//#endregion
+//#region src/core/internal/validate-nodes.ts
+const MEMBERS_INDEX_PATH = "members/NODE.md";
+function addFinding(findings, code, path, message, target) {
+	findings.push({
+		code,
+		message,
+		path,
+		...target === void 0 ? {} : { target }
+	});
+}
+function validateRequiredNodeMetadata(document, path, findings) {
+	if (document.frontmatter === "missing") {
+		addFinding(findings, VALIDATION_CODES.frontmatterMissing, path, "missing frontmatter");
+		return;
+	}
+	if (document.frontmatter === "invalid" || document.data === null) {
+		addFinding(findings, VALIDATION_CODES.frontmatterParse, path, `frontmatter could not be parsed${document.error === void 0 ? "" : `: ${document.error}`}`);
+		return;
+	}
+	const title = readNonEmptyStringField(document.data, "title");
+	if (!title.present) addFinding(findings, VALIDATION_CODES.titleMissing, path, "missing 'title' field in frontmatter");
+	else if (!title.valid) addFinding(findings, VALIDATION_CODES.titleInvalid, path, "'title' must be a non-empty string");
+	const owners = readNonEmptyStringArrayField(document.data, "owners");
+	if (!owners.present) addFinding(findings, VALIDATION_CODES.ownersMissing, path, "missing 'owners' field in frontmatter");
+	else if (!owners.valid) addFinding(findings, VALIDATION_CODES.ownersInvalid, path, "'owners' must be a non-empty string array");
+	const description = readNonEmptyStringField(document.data, "description");
+	if (description.present && !description.valid) addFinding(findings, VALIDATION_CODES.descriptionInvalid, path, "'description' must be a non-empty string when present");
+}
+function readSoftLinks(document, path, findings) {
+	if (document.data === null) return [];
+	const softLinks = readNonEmptyStringArrayField(document.data, "soft_links");
+	if (!softLinks.present) return [];
+	if (!softLinks.valid) {
+		addFinding(findings, VALIDATION_CODES.softLinksInvalid, path, "'soft_links' must be a non-empty string array when present");
+		return [];
+	}
+	return softLinks.value;
+}
+function validateSoftLinks(options) {
+	for (const target of readSoftLinks(options.document, options.path, options.findings)) {
+		const resolved = resolveLocalTreeTarget({
+			sourcePath: options.path,
+			target,
+			treeRoot: options.treeRoot,
+			softLink: true
+		});
+		if (resolved === null || !resolved.exists) addFinding(options.findings, VALIDATION_CODES.softLinkBroken, options.path, "broken soft_links target", target);
+		if (resolved === null) continue;
+		if (!options.allowArchive && resolved.contentClass === "archive-supporting") addFinding(options.findings, VALIDATION_CODES.softLinkArchiveDependency, options.path, "normal content must not link to archive/supporting content", target);
+		if (resolved.escaped) addFinding(options.findings, VALIDATION_CODES.softLinkPathEscape, options.path, "soft_links target resolves outside the Context Tree root", target);
+	}
+}
+function validateMarkdownLinks(document, path, treeRoot, findings) {
+	for (const target of readMarkdownLinkTargets(document.body)) {
+		const resolved = resolveLocalTreeTarget({
+			sourcePath: path,
+			target,
+			treeRoot,
+			softLink: false
+		});
+		if (resolved === null) continue;
+		if (resolved.contentClass === "archive-supporting") addFinding(findings, VALIDATION_CODES.markdownArchiveDependency, path, "normal content must not link to archive/supporting content", target);
+		if (resolved.escaped) addFinding(findings, VALIDATION_CODES.markdownPathEscape, path, "Markdown link resolves outside the Context Tree root", target);
+	}
+}
+function collectNodeValidationFindings(treeRoot) {
+	const findings = [];
+	const scannedByContentClass = emptyContentClassCounts();
+	const content = collectContextMarkdownContent(treeRoot);
+	for (const directory of content.directorySymlinks) addFinding(findings, directory.escaped ? VALIDATION_CODES.directorySymlinkPathEscape : VALIDATION_CODES.directorySymlinkUnsupported, directory.relativePath, directory.escaped ? "directory symlink resolves outside the Context Tree root" : "Context Tree domain directories must not be symlinks");
+	for (const file of content.files) {
+		if (file.relativePath === "SCOPE.md") continue;
+		scannedByContentClass[file.contentClass] += 1;
+		if (file.unresolved) {
+			addFinding(findings, VALIDATION_CODES.markdownFileSymlinkBroken, file.relativePath, "Markdown file symlink target cannot be resolved");
+			continue;
+		}
+		if (file.escaped) {
+			addFinding(findings, VALIDATION_CODES.markdownFilePathEscape, file.relativePath, "Markdown file resolves outside the Context Tree root");
+			continue;
+		}
+		if (file.unsupported) {
+			addFinding(findings, VALIDATION_CODES.markdownFileSymlinkUnsupported, file.relativePath, "Markdown file symlink must resolve to a regular file");
+			continue;
+		}
+		if (file.canonicalContentClass !== file.contentClass) {
+			addFinding(findings, VALIDATION_CODES.markdownFileContentClassMismatch, file.relativePath, `Markdown file symlink crosses content-class boundary from ${file.contentClass} to ${file.canonicalContentClass}`, file.canonicalRelativePath);
+			continue;
+		}
+		if (file.contentClass === "repo-infra" || file.contentClass === "archive-supporting") continue;
+		const document = readContextDocument(file.absolutePath);
+		if (file.contentClass === "member" && file.relativePath !== MEMBERS_INDEX_PATH) {
+			if (document.frontmatter === "missing") continue;
+			if (document.frontmatter === "invalid") continue;
+			validateSoftLinks({
+				allowArchive: true,
+				document,
+				findings,
+				path: file.relativePath,
+				treeRoot
+			});
+			continue;
+		}
+		validateRequiredNodeMetadata(document, file.relativePath, findings);
+		validateSoftLinks({
+			allowArchive: file.contentClass === "member",
+			document,
+			findings,
+			path: file.relativePath,
+			treeRoot
+		});
+		if (file.contentClass === "normal") validateMarkdownLinks(document, file.relativePath, treeRoot, findings);
+	}
+	return {
+		findings,
+		scannedByContentClass
+	};
+}
+//#endregion
+//#region src/core/verify.ts
+function scopeFindings(root) {
+	const path = join(root, "SCOPE.md");
+	if (!existsSync(path)) return [];
+	try {
+		const entry = lstatSync(path);
+		if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("SCOPE.md must be a regular root file and must not be a symlink.");
+		parseContextTreeScope(readUtf8File(path));
+		return [];
+	} catch (error) {
+		return [{
+			code: VALIDATION_CODES.scopeInvalid,
+			message: error instanceof Error ? error.message : String(error),
+			path: "SCOPE.md"
+		}];
+	}
+}
+function deduplicate(findings) {
+	const seen = /* @__PURE__ */ new Set();
+	return findings.filter((finding) => {
+		const key = `${finding.code}\0${finding.path}\0${finding.target ?? ""}`;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+function verifyTree(treePath) {
+	const root = resolveTreeRoot(treePath);
+	const nodeResult = collectNodeValidationFindings(root);
+	const memberFindings = collectMemberValidationFindings(root);
+	const findings = deduplicate([
+		...existsSync(join(root, "NODE.md")) ? [] : [{
+			code: VALIDATION_CODES.rootMissing,
+			message: "root NODE.md is missing",
+			path: "NODE.md"
+		}],
+		...scopeFindings(root),
+		...nodeResult.findings,
+		...memberFindings
+	]);
+	return {
+		findings,
+		ok: findings.length === 0,
+		root,
+		scannedByContentClass: nodeResult.scannedByContentClass,
+		schemaVersion: 1
+	};
+}
+//#endregion
+//#region src/core/scaffold.ts
+function template(name, values) {
+	let result = readFileSync(resolvePackagedResource("templates", name), "utf8");
+	for (const [key, value] of Object.entries(values)) result = result.replaceAll(`{{${key}}}`, value);
+	return result;
+}
+function scaffoldTree(options) {
+	const root = resolve(options.path);
+	const destination = lstatSync(root, { throwIfNoEntry: false });
+	if (destination !== void 0) {
+		if (destination.isSymbolicLink() || !destination.isDirectory()) throw new Error(`Refusing to scaffold into a symlink or non-directory destination: ${root}`);
+		if (readdirSync(root).length > 0) throw new Error(`Refusing to scaffold into a non-empty directory: ${root}`);
+	}
+	const owner = options.owner.trim();
+	const repository = options.repository.trim();
+	const title = options.title.trim();
+	if (!/^[a-z\d][a-z\d._-]{0,127}$/iu.test(owner)) throw new Error("Owner must be a portable identifier containing only letters, digits, dot, underscore, or hyphen.");
+	const unsafeTitle = [...title].some((character) => {
+		const code = character.codePointAt(0);
+		return code !== void 0 && (code <= 31 || code === 127);
+	});
+	if (!title || title.length > 200 || unsafeTitle) throw new Error("Tree title must be a non-empty single line of at most 200 characters.");
+	const repositoryParts = repository.split("/");
+	const [repositoryOwner, repositoryName] = repositoryParts;
+	if (options.repository !== repository || repositoryParts.length !== 2 || repositoryOwner === void 0 || repositoryName === void 0 || !/^[A-Za-z\d](?:[A-Za-z\d-]{0,37}[A-Za-z\d])?$/u.test(repositoryOwner) || !/^[A-Za-z\d._-]{1,100}$/u.test(repositoryName) || repositoryName === "." || repositoryName === ".." || /\.git$/iu.test(repositoryName)) throw new Error("Repository must be an explicit GitHub OWNER/REPO identity.");
+	const manifest = readPackageManifest();
+	if (!("version" in manifest) || typeof manifest.version !== "string") throw new Error("Package version is missing or invalid.");
+	const values = {
+		owner,
+		ownerJson: JSON.stringify(owner),
+		packageVersion: manifest.version,
+		title,
+		titleJson: JSON.stringify(title)
+	};
+	mkdirSync(root, { recursive: true });
+	const files = [
+		["NODE.md", "root-node.md"],
+		["SCOPE.md", "scope.md"],
+		["members/NODE.md", "members-index.md"],
+		[`members/${values.owner}/NODE.md`, "member-node.md"],
+		[".github/workflows/validate-context-tree.yml", "validate-context-tree.yml"]
+	];
+	for (const [relativePath, source] of files) {
+		const path = join(root, relativePath);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, template(source, values), {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 420
+		});
+	}
+	return {
+		files: files.map(([path]) => path),
+		root,
+		schemaVersion: 1,
+		verification: verifyTree(root)
+	};
+}
+//#endregion
+export { readContextTreePolicy as a, readTree as i, verifyTree as n, readPackageManifest as o, classifyTreePath as r, scaffoldTree as t };