@first-tree-ai/context-tree 0.1.1 → 0.1.2

package/dist/index.mjs

@@ -1,2 +1,1087 @@
-import { a as readContextTreePolicy, i as readTree, n as verifyTree, t as scaffoldTree } from "./src-DJZoQVCF.mjs";
-export { readContextTreePolicy, readTree, scaffoldTree, verifyTree };
+import { A as isRecord, C as githubRepositoryIdentitySchema, S as credentialFreeRepositoryUrlSchema, f as contextTreeLinkSchema, i as VALIDATION_CODES, k as parseMarkdownFrontmatter, t as CLI_ERROR_CODES, w as parseContextTreeRootNode } from "./schemas-BWM6Q6iz.mjs";
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve } from "node:path";
+import { z } from "zod";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { fileURLToPath } from "node:url";
+//#region src/core/internal/filesystem.ts
+function readUtf8File(path) {
+	return new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path));
+}
+//#endregion
+//#region src/core/internal/github-repository.ts
+function parseGitHubRepositoryIdentity(repository) {
+	githubRepositoryIdentitySchema.parse(repository);
+	return repository.split("/")[1] ?? "";
+}
+function repositoryIdentityFromGitHubUrl(repositoryUrl) {
+	try {
+		credentialFreeRepositoryUrlSchema.parse(repositoryUrl);
+	} catch {
+		throw new Error("Context Tree origin must be a safe credential-free github.com repository URL.");
+	}
+	let host;
+	let path;
+	const scp = /^(?:git@)?([^:]+):(.+)$/u.exec(repositoryUrl);
+	if (scp !== null && !repositoryUrl.includes("://")) {
+		host = scp[1] ?? "";
+		path = scp[2] ?? "";
+	} else {
+		let parsed;
+		try {
+			parsed = new URL(repositoryUrl);
+		} catch {
+			throw new Error("Context Tree origin must be a safe credential-free github.com repository URL.");
+		}
+		if (parsed.password || (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.username) throw new Error("Context Tree origin must be a safe credential-free github.com repository URL.");
+		host = parsed.hostname;
+		path = parsed.pathname;
+	}
+	if (host.toLowerCase() !== "github.com") throw new Error("Context Tree origin must use github.com.");
+	const identity = path.replace(/^\/+|\/+$/gu, "").replace(/\.git$/iu, "");
+	try {
+		parseGitHubRepositoryIdentity(identity);
+	} catch {
+		throw new Error("Context Tree origin must identify a safe GitHub OWNER/REPO repository.");
+	}
+	return identity;
+}
+function canonicalGitHubRepositoryUrl(repository) {
+	parseGitHubRepositoryIdentity(repository);
+	return `https://github.com/${repository}.git`;
+}
+//#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.some((part) => part.startsWith(".") || GENERATED_DIRECTORY_NAMES.has(part)) || parts[0] === "scripts" || REPO_INFRA_MARKDOWN_FILES.has(parts.at(-1) ?? "")) return "repo-infra";
+	if (parts[0] === "members") return "member";
+	return "normal";
+}
+function emptyContentClassCounts() {
+	return {
+		normal: 0,
+		member: 0,
+		"repo-infra": 0
+	};
+}
+function readDirectoryEntries(path) {
+	try {
+		return readdirSync(path, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+	} catch {
+		return [];
+	}
+}
+function canonicalTarget$1(realTreeRoot, path) {
+	try {
+		const realTarget = realpathSync(path);
+		if (!isPathInside(realTreeRoot, realTarget)) return { kind: "escaped" };
+		return {
+			kind: "resolved",
+			relativePath: toTreeRelativePosixPath(realTreeRoot, realTarget)
+		};
+	} catch {
+		return { kind: "unresolved" };
+	}
+}
+function inspectMarkdownSymlink(realTreeRoot, absolutePath, contentClass) {
+	let targetStat;
+	try {
+		targetStat = statSync(absolutePath);
+	} catch {
+		return { kind: "unresolved" };
+	}
+	const target = canonicalTarget$1(realTreeRoot, absolutePath);
+	if (target.kind !== "resolved") return target;
+	if (!targetStat.isFile()) return { kind: "unsupported" };
+	if (classifyContextContent(target.relativePath) !== contentClass) return {
+		kind: "content-class-mismatch",
+		canonicalRelativePath: target.relativePath
+	};
+	return { kind: "regular" };
+}
+function collectContextMarkdownContent(treeRoot) {
+	const directories = [];
+	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") {
+					directories.push(relativePath);
+					walk(absolutePath);
+				}
+				continue;
+			}
+			const symbolicLink = entry.isSymbolicLink();
+			if (symbolicLink) try {
+				if (statSync(absolutePath).isDirectory()) {
+					if (contentClass !== "repo-infra" || entry.name.endsWith(".md")) {
+						const target = canonicalTarget$1(realTreeRoot, absolutePath);
+						directorySymlinks.push({
+							escaped: target.kind === "escaped",
+							relativePath
+						});
+					}
+					continue;
+				}
+			} catch {
+				if (MANAGED_SYMLINK_PATHS.has(relativePath)) continue;
+				if (entry.name.endsWith(".md")) files.push({
+					absolutePath,
+					contentClass,
+					inspection: { kind: "unresolved" },
+					relativePath
+				});
+				continue;
+			}
+			if (!entry.isFile() && !symbolicLink || !entry.name.endsWith(".md")) continue;
+			if (symbolicLink && MANAGED_SYMLINK_PATHS.has(relativePath)) continue;
+			files.push({
+				absolutePath,
+				contentClass,
+				inspection: symbolicLink ? inspectMarkdownSymlink(realTreeRoot, absolutePath, contentClass) : { kind: "regular" },
+				relativePath
+			});
+		}
+	}
+	walk(treeRoot);
+	return {
+		directories,
+		directorySymlinks,
+		files
+	};
+}
+//#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 readNodeDocument(path) {
+	const document = readContextDocument(path);
+	if (document.frontmatter !== "valid") return null;
+	const title = readNonEmptyStringField(document.data, "title");
+	const description = readNonEmptyStringField(document.data, "description");
+	if (!title.valid || description.present && !description.valid) return null;
+	return {
+		body: document.body,
+		frontmatter: document.data,
+		title: title.value,
+		...description.valid ? { description: description.value } : {}
+	};
+}
+//#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 "escaped-missing";
+	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);
+	if (!isPathInside(absoluteRoot, absoluteTarget)) return "escaped-missing";
+	if (!targetExists(absoluteTarget, options.softLink)) return "missing";
+	try {
+		if (!isPathInside(realpathSync(absoluteRoot), realpathSync(absoluteTarget))) return "escaped-existing";
+	} catch {
+		return "missing";
+	}
+	return "valid";
+}
+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
+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") {
+		addFinding(findings, VALIDATION_CODES.frontmatterParse, path, `frontmatter could not be parsed: ${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 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 validateRootOnlyFields(document, path, findings) {
+	if (path === "NODE.md" || document.frontmatter !== "valid") return;
+	const fields = ["schemaVersion"].filter((field) => field in document.data);
+	if (fields.length > 0) addFinding(findings, VALIDATION_CODES.rootOnlyFields, path, `root-only frontmatter field${fields.length === 1 ? "" : "s"} must appear only in root NODE.md: ${fields.join(", ")}`);
+}
+function readSoftLinks(document, path, findings) {
+	if (document.frontmatter !== "valid") 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 === "missing" || resolved === "escaped-missing") addFinding(options.findings, VALIDATION_CODES.softLinkBroken, options.path, "broken soft_links target", target);
+		if (resolved === null) continue;
+		if (resolved === "escaped-existing" || resolved === "escaped-missing") 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 === "escaped-existing" || resolved === "escaped-missing") 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.directories) {
+		const nodePath = `${directory}/NODE.md`;
+		let hasRegularNode = false;
+		try {
+			const entry = lstatSync(join(treeRoot, nodePath));
+			hasRegularNode = entry.isFile() && !entry.isSymbolicLink();
+		} catch {}
+		if (!hasRegularNode) addFinding(findings, VALIDATION_CODES.directoryNodeMissing, directory, "Context Tree directory is missing NODE.md");
+	}
+	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) {
+		scannedByContentClass[file.contentClass] += 1;
+		if (file.inspection.kind === "unresolved") {
+			addFinding(findings, VALIDATION_CODES.markdownFileSymlinkBroken, file.relativePath, "Markdown file symlink target cannot be resolved");
+			continue;
+		}
+		if (file.inspection.kind === "escaped") {
+			addFinding(findings, VALIDATION_CODES.markdownFilePathEscape, file.relativePath, "Markdown file resolves outside the Context Tree root");
+			continue;
+		}
+		if (file.inspection.kind === "unsupported") {
+			addFinding(findings, VALIDATION_CODES.markdownFileSymlinkUnsupported, file.relativePath, "Markdown file symlink must resolve to a regular file");
+			continue;
+		}
+		if (file.inspection.kind === "content-class-mismatch") {
+			const canonicalContentClass = classifyContextContent(file.inspection.canonicalRelativePath);
+			addFinding(findings, VALIDATION_CODES.markdownFileContentClassMismatch, file.relativePath, `Markdown file symlink crosses content-class boundary from ${file.contentClass} to ${canonicalContentClass}`, file.inspection.canonicalRelativePath);
+			continue;
+		}
+		if (file.contentClass === "repo-infra") continue;
+		const document = readContextDocument(file.absolutePath);
+		validateRootOnlyFields(document, file.relativePath, findings);
+		if (file.relativePath !== "NODE.md" || document.frontmatter === "valid") validateRequiredNodeMetadata(document, file.relativePath, findings);
+		validateSoftLinks({
+			document,
+			findings,
+			path: file.relativePath,
+			treeRoot
+		});
+		validateMarkdownLinks(document, file.relativePath, treeRoot, findings);
+	}
+	return {
+		findings,
+		scannedByContentClass
+	};
+}
+//#endregion
+//#region src/core/verify.ts
+function rootNodeFindings(root) {
+	const path = join(root, "NODE.md");
+	if (!existsSync(path)) return [{
+		code: VALIDATION_CODES.rootMissing,
+		message: "root NODE.md is missing",
+		path: "NODE.md"
+	}];
+	try {
+		const entry = lstatSync(path);
+		if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("Root NODE.md must be a regular file and must not be a symlink.");
+		parseContextTreeRootNode(readUtf8File(path));
+		return [];
+	} catch (error) {
+		return [{
+			code: VALIDATION_CODES.rootNodeInvalid,
+			message: error instanceof Error ? error.message : String(error),
+			path: "NODE.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 findings = deduplicate([...rootNodeFindings(root), ...nodeResult.findings]);
+	return {
+		findings,
+		ok: findings.length === 0,
+		root,
+		scannedByContentClass: nodeResult.scannedByContentClass,
+		schemaVersion: 1
+	};
+}
+//#endregion
+//#region src/core/links.ts
+const contextTreeLinksFileSchema = z.object({
+	links: z.array(contextTreeLinkSchema),
+	schemaVersion: z.literal(1)
+}).strict();
+var LinkError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "LinkError";
+		this.code = code;
+	}
+};
+function git$1(path, args) {
+	const result = spawnSync("git", [
+		"-C",
+		path,
+		...args
+	], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		]
+	});
+	if (result.error !== void 0 || result.status !== 0) return void 0;
+	return result.stdout.replace(/\r?\n$/u, "");
+}
+function requireGit$1(path, args, message, allowEmpty = false) {
+	const value = git$1(path, args);
+	if (value === void 0 || !allowEmpty && value.length === 0) throw new Error(message);
+	return value;
+}
+function normalizeRepositoryUrl(repositoryUrl) {
+	try {
+		credentialFreeRepositoryUrlSchema.parse(repositoryUrl);
+	} catch {
+		throw new Error("Git origin must be a canonical credential-free repository URL.");
+	}
+	try {
+		return canonicalGitHubRepositoryUrl(repositoryIdentityFromGitHubUrl(repositoryUrl).toLowerCase());
+	} catch {}
+	const scp = /^(?:([^@]+)@)?([^:]+):(.+)$/u.exec(repositoryUrl);
+	if (scp !== null && !repositoryUrl.includes("://")) return `${scp[1] === void 0 ? "" : `${scp[1].toLowerCase()}@`}${(scp[2] ?? "").toLowerCase()}:${(scp[3] ?? "").replace(/\/+$/gu, "").replace(/\.git$/iu, "")}.git`;
+	const parsed = new URL(repositoryUrl);
+	parsed.hostname = parsed.hostname.toLowerCase();
+	parsed.pathname = `${parsed.pathname.replace(/\/+$/gu, "").replace(/\.git$/iu, "")}.git`;
+	return parsed.toString();
+}
+function realDirectory(path) {
+	const absolute = resolve(path);
+	if (!lstatSync(absolute).isDirectory()) throw new Error("Project path must be a directory.");
+	return realpathSync(absolute);
+}
+function identifyProject(projectPath) {
+	const path = realDirectory(projectPath);
+	const gitRoot = git$1(path, ["rev-parse", "--show-toplevel"]);
+	if (gitRoot === void 0) return {
+		kind: "directory",
+		path
+	};
+	return {
+		kind: "git",
+		origin: normalizeRepositoryUrl(requireGit$1(realpathSync(gitRoot), [
+			"remote",
+			"get-url",
+			"origin"
+		], "Git project must have an origin remote."))
+	};
+}
+function linksPath() {
+	return join(homedir(), ".context-tree", "connections.json");
+}
+function emptyLinks() {
+	return {
+		links: [],
+		schemaVersion: 1
+	};
+}
+function loadLinks(required) {
+	const path = linksPath();
+	if (!existsSync(path)) {
+		if (required) throw new LinkError(CLI_ERROR_CODES.noLink, "No Context Tree link exists for this project.");
+		return emptyLinks();
+	}
+	try {
+		const entry = lstatSync(path);
+		if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("not a regular file");
+		return contextTreeLinksFileSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		throw new LinkError(CLI_ERROR_CODES.corruptLink, "Context Tree links are corrupt; run link after repairing or removing the internal links file.");
+	}
+}
+function saveLinks(value) {
+	const path = linksPath();
+	const directory = dirname(path);
+	mkdirSync(directory, {
+		recursive: true,
+		mode: 448
+	});
+	const directoryEntry = lstatSync(directory);
+	if (directoryEntry.isSymbolicLink() || !directoryEntry.isDirectory()) throw new Error("Context Tree links directory must be a real directory.");
+	const temporary = join(directory, `.links-${process.pid}-${Date.now()}.tmp`);
+	writeFileSync(temporary, `${JSON.stringify(contextTreeLinksFileSchema.parse(value), null, 2)}\n`, {
+		encoding: "utf8",
+		flag: "wx",
+		mode: 384
+	});
+	renameSync(temporary, path);
+	chmodSync(path, 384);
+}
+function exactCheckoutRoot(treePath) {
+	const absolute = resolve(treePath);
+	const entry = lstatSync(absolute);
+	const root = realpathSync(absolute);
+	if (!entry.isDirectory() || entry.isSymbolicLink() || absolute !== root) throw new Error("Context Tree checkout path must be a real directory with no symlink component.");
+	if (realpathSync(requireGit$1(root, ["rev-parse", "--show-toplevel"], "Context Tree checkout must be a Git repository.")) !== root) throw new Error("Context Tree checkout must be the real Git root.");
+	return root;
+}
+function checkoutRepository(root) {
+	return repositoryIdentityFromGitHubUrl(requireGit$1(root, [
+		"remote",
+		"get-url",
+		"origin"
+	], "Context Tree checkout must have an origin remote."));
+}
+function requireCheckoutClean(root, mode) {
+	const status = requireGit$1(root, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	], "Failed to inspect Context Tree cleanliness.", true);
+	if (status.length === 0) return;
+	if (mode === "scaffold") {
+		const lines = status.split("\n").sort();
+		if (git$1(root, [
+			"rev-parse",
+			"--verify",
+			"HEAD"
+		]) === void 0 && JSON.stringify(lines) === JSON.stringify([
+			"?? .github/workflows/validate-context-tree.yml",
+			"?? AGENTS.md",
+			"?? CLAUDE.md",
+			"?? NODE.md"
+		])) return;
+	}
+	throw new Error("Context Tree checkout must be clean.");
+}
+function parseRootNode(root) {
+	const path = join(root, "NODE.md");
+	const entry = lstatSync(path);
+	if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("Context Tree root NODE.md must be a regular file.");
+	return parseContextTreeRootNode(readUtf8File(path));
+}
+function verifyCheckout(treePath, mode) {
+	const root = exactCheckoutRoot(treePath);
+	requireCheckoutClean(root, mode);
+	const repository = checkoutRepository(root);
+	if (!verifyTree(root).ok) throw new Error("Context Tree checkout is invalid; run context-tree verify.");
+	return {
+		path: root,
+		repository
+	};
+}
+function sameProject(left, right) {
+	return left.kind === "git" && right.kind === "git" ? left.origin === right.origin : left.kind === "directory" && right.kind === "directory" && left.path === right.path;
+}
+function projectMatches(candidate, current) {
+	if (candidate.kind === "git" && current.kind === "git") return candidate.origin === current.origin;
+	if (candidate.kind === "directory" && current.kind === "directory") return isPathInside(candidate.path, current.path);
+	return false;
+}
+function liveStoredCheckout(link) {
+	try {
+		const path = exactCheckoutRoot(link.tree.path);
+		return {
+			path,
+			repository: checkoutRepository(path)
+		};
+	} catch {
+		return;
+	}
+}
+function linkWithMode(projectPath, treePath, mode) {
+	const project = identifyProject(projectPath);
+	const tree = verifyCheckout(treePath, mode);
+	const stored = loadLinks(false);
+	const existing = stored.links.filter((link) => sameProject(link.project, project));
+	if (existing.length > 1) throw new LinkError(CLI_ERROR_CODES.ambiguousLink, "Multiple Context Tree links match this project.");
+	const previous = existing[0];
+	if (previous !== void 0) {
+		if (previous.tree.repository.toLowerCase() !== tree.repository.toLowerCase()) throw new Error("A project cannot link to a different Context Tree repository.");
+		if (previous.tree.path !== tree.path) {
+			const live = liveStoredCheckout(previous);
+			if (live !== void 0 && live.repository.toLowerCase() === previous.tree.repository.toLowerCase()) throw new Error("The existing Context Tree checkout is still live; replacement is allowed only when it is stale.");
+		}
+	}
+	const link = {
+		project,
+		tree
+	};
+	saveLinks({
+		links: [...stored.links.filter((candidate) => !sameProject(candidate.project, project)), link],
+		schemaVersion: 1
+	});
+	return {
+		link,
+		schemaVersion: 1
+	};
+}
+function linkProject(projectPath, treePath) {
+	return linkWithMode(projectPath, treePath, "link");
+}
+function resolveLink(projectPath) {
+	const project = identifyProject(projectPath);
+	const matches = loadLinks(true).links.filter((link) => projectMatches(link.project, project));
+	if (matches.length === 0) throw new LinkError(CLI_ERROR_CODES.noLink, "No Context Tree link exists for this project.");
+	if (matches.length > 1) throw new LinkError(CLI_ERROR_CODES.ambiguousLink, "Multiple Context Tree links match this project.");
+	const link = matches[0];
+	if (link === void 0) throw new Error("Link lookup failed.");
+	try {
+		const root = exactCheckoutRoot(link.tree.path);
+		requireCheckoutClean(root, "link");
+		const repository = checkoutRepository(root);
+		if (repository.toLowerCase() !== link.tree.repository.toLowerCase()) throw new Error("The linked path now contains a different Context Tree repository.");
+		parseRootNode(root);
+		return {
+			link: {
+				project: link.project,
+				tree: {
+					path: root,
+					repository
+				}
+			},
+			schemaVersion: 1
+		};
+	} catch (error) {
+		const message = error instanceof Error && error.message === "The linked path now contains a different Context Tree repository." ? error.message : "The linked Context Tree checkout is no longer a valid clean candidate; run link when its stored path is stale.";
+		throw new LinkError(CLI_ERROR_CODES.staleLink, message);
+	}
+}
+//#endregion
+//#region src/core/live.ts
+function git(root, args) {
+	const result = spawnSync("git", [
+		"-C",
+		root,
+		...args
+	], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		]
+	});
+	if (result.error !== void 0 || result.status !== 0) throw new Error("A Git operation failed while preparing the Context Tree.");
+	return typeof result.stdout === "string" ? result.stdout : "";
+}
+function requireGit(root, args, allowEmpty = false) {
+	const output = git(root, args).trim();
+	if (output.length === 0 && !allowEmpty) throw new Error("Unexpected empty Git output.");
+	return output;
+}
+function discoverDefaultBranch(root) {
+	const refs = git(root, [
+		"ls-remote",
+		"--symref",
+		"origin",
+		"HEAD"
+	]).split("\n").map((line) => /^ref: refs\/heads\/([^\s\t]+)\tHEAD$/u.exec(line)?.[1]).filter((value) => value !== void 0 && value.length > 0);
+	if (refs.length !== 1) throw new Error("The Context Tree origin must report exactly one live default branch.");
+	return refs[0] ?? "";
+}
+function refreshProject(projectPath) {
+	const result = resolveLink(projectPath);
+	const root = result.link.tree.path;
+	const defaultBranch = discoverDefaultBranch(root);
+	if (requireGit(root, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	]) !== defaultBranch) throw new Error(`The Context Tree checkout must be on the live default branch "${defaultBranch}".`);
+	const before = requireGit(root, ["rev-parse", "HEAD"]);
+	requireGit(root, [
+		"pull",
+		"--ff-only",
+		"origin",
+		defaultBranch
+	]);
+	const after = requireGit(root, ["rev-parse", "HEAD"]);
+	return {
+		link: {
+			...result.link,
+			tree: {
+				...result.link.tree,
+				path: realpathSync(root)
+			}
+		},
+		defaultBranch,
+		refreshed: before !== after,
+		schemaVersion: 1,
+		sha: after
+	};
+}
+function createIsolatedWorktree(treePath, baseSha) {
+	const destination = mkdtempSync(join(tmpdir(), "context-tree-stage-"));
+	const taskBranch = `context-tree/write/${basename(destination)}`;
+	git(treePath, [
+		"worktree",
+		"add",
+		"-b",
+		taskBranch,
+		destination,
+		baseSha
+	]);
+	return {
+		taskBranch,
+		worktreePath: realpathSync(destination)
+	};
+}
+function stageContextWrite(projectPath) {
+	const result = resolveLink(projectPath);
+	const treePath = result.link.tree.path;
+	const ownerRepository = result.link.tree.repository;
+	const defaultBranch = discoverDefaultBranch(treePath);
+	if (requireGit(treePath, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	]) !== defaultBranch) throw new Error(`The Context Tree checkout must be on the live default branch "${defaultBranch}".`);
+	requireGit(treePath, [
+		"fetch",
+		"origin",
+		defaultBranch
+	], true);
+	const baseSha = requireGit(treePath, ["rev-parse", `origin/${defaultBranch}`]);
+	const { taskBranch, worktreePath } = createIsolatedWorktree(treePath, baseSha);
+	return {
+		baseSha,
+		link: {
+			project: result.link.project,
+			tree: {
+				path: treePath,
+				repository: ownerRepository
+			}
+		},
+		defaultBranch,
+		schemaVersion: 1,
+		taskBranch,
+		worktreePath
+	};
+}
+const DIFF_STATUS = {
+	A: "added",
+	D: "deleted",
+	M: "modified",
+	R: "renamed"
+};
+function changedFiles(root, base) {
+	const output = git(root, [
+		"diff",
+		"--name-status",
+		base
+	]);
+	const files = [];
+	for (const line of output.split("\n")) {
+		const match = /^([ADMR])\s+(.+)$/u.exec(line);
+		if (match === null) continue;
+		const status = DIFF_STATUS[match[1]];
+		if (status === void 0) continue;
+		files.push({
+			path: match[2] ?? "",
+			status
+		});
+	}
+	const porcelain = git(root, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	]);
+	for (const line of porcelain.split("\n")) {
+		const path = /^\?\?\s+(.+)$/u.exec(line)?.[1];
+		if (path !== void 0 && path.length > 0) files.push({
+			path,
+			status: "added"
+		});
+	}
+	return files;
+}
+function inspectContextTreeDiff(treePath, base) {
+	const root = realpathSync(treePath);
+	const reference = base ?? "HEAD";
+	return {
+		base: reference,
+		files: changedFiles(root, reference),
+		patch: git(root, ["diff", reference]),
+		schemaVersion: 1,
+		treePath: root
+	};
+}
+//#endregion
+//#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 isRecord(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;
+}
+function readPackageVersion() {
+	const manifest = readPackageManifest();
+	if (typeof manifest.version !== "string") throw new Error("Package version is missing or invalid.");
+	return manifest.version;
+}
+//#endregion
+//#region src/core/policy.ts
+function readContextTreePolicy() {
+	return {
+		content: readFileSync(resolvePackagedResource("policy", "context-tree-policy.md"), "utf8"),
+		schemaVersion: 1
+	};
+}
+//#endregion
+//#region src/core/read.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 canonicalTarget(root, path) {
+	const requested = normalizeTreeTarget(path);
+	const semanticPath = requested === "NODE.md" ? "" : requested.endsWith("/NODE.md") ? dirname(requested) : requested;
+	if (classifyContextContent(semanticPath) === "repo-infra") throw new Error(`Read target is repository infrastructure: ${requested || "."}`);
+	const absolutePath = resolve(root, semanticPath);
+	if (!isPathInside(root, absolutePath)) throw new Error("Read target escapes the Context Tree root.");
+	const entry = lstatSync(absolutePath);
+	if (entry.isSymbolicLink() || !entry.isDirectory() && !entry.isFile()) throw new Error(`Read target must be a real file or directory: ${requested || "."}`);
+	if (realpathSync(absolutePath) !== absolutePath) throw new Error(`Read target must not traverse a symlink: ${requested || "."}`);
+	const relativePath = toPosixPath(relative(root, absolutePath));
+	if (entry.isFile() && !absolutePath.endsWith(".md")) throw new Error(`Read target must be a Markdown file or indexed directory: ${requested || "."}`);
+	return {
+		absolutePath,
+		kind: entry.isDirectory() ? "directory" : "file",
+		relativePath
+	};
+}
+function readNode(path, relativePath, kind) {
+	const documentPath = kind === "directory" ? join(path, "NODE.md") : path;
+	const entry = lstatSync(documentPath);
+	if (entry.isSymbolicLink() || !entry.isFile()) throw new Error(`Context Tree document must be a regular file: ${relativePath || "NODE.md"}`);
+	const document = readNodeDocument(documentPath);
+	if (document === null) throw new Error(`Context Tree document has invalid or missing metadata: ${relativePath || "."}`);
+	return {
+		body: document.body,
+		contentClass: classifyContextContent(relativePath),
+		frontmatter: document.frontmatter,
+		kind,
+		path: relativePath || "."
+	};
+}
+function childSummary(root, parentPath, name) {
+	const absolutePath = join(parentPath, name);
+	const relativePath = toPosixPath(relative(root, absolutePath));
+	const contentClass = classifyContextContent(relativePath);
+	if (contentClass === "repo-infra") return null;
+	const entry = lstatSync(absolutePath);
+	if (entry.isSymbolicLink()) return null;
+	const kind = entry.isDirectory() ? "directory" : entry.isFile() && name.endsWith(".md") && name !== "NODE.md" ? "file" : null;
+	if (kind === null) return null;
+	const document = readNodeDocument(kind === "directory" ? join(absolutePath, "NODE.md") : absolutePath);
+	if (document === null) throw new Error(`Context Tree child has invalid or missing metadata: ${relativePath}`);
+	return {
+		contentClass,
+		...document.description === void 0 ? {} : { description: document.description },
+		kind,
+		path: relativePath,
+		title: document.title
+	};
+}
+function readTree(treePath, path) {
+	const root = resolveTreeRoot(treePath);
+	const target = canonicalTarget(root, path);
+	const node = readNode(target.absolutePath, target.relativePath, target.kind);
+	return {
+		children: target.kind === "file" ? [] : readdirSync(target.absolutePath).map((name) => childSummary(root, target.absolutePath, name)).filter((child) => child !== null).sort((left, right) => left.path.localeCompare(right.path)),
+		node,
+		root,
+		schemaVersion: 1,
+		target: target.relativePath || "."
+	};
+}
+//#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 initializeGitRepository(root, repository) {
+	const initialized = spawnSync("git", [
+		"init",
+		"--quiet",
+		root
+	], { stdio: "ignore" });
+	if (initialized.error !== void 0 || initialized.status !== 0) throw new Error("Failed to initialize Git repository.");
+	const branch = spawnSync("git", [
+		"-C",
+		root,
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		]
+	});
+	const name = branch.stdout.replace(/\r?\n$/u, "");
+	if (branch.error !== void 0 || branch.status !== 0 || name.length === 0) throw new Error("Failed to resolve the initial Git branch during repository initialization.");
+	const remote = spawnSync("git", [
+		"-C",
+		root,
+		"remote",
+		"add",
+		"origin",
+		canonicalGitHubRepositoryUrl(repository)
+	], { stdio: "ignore" });
+	if (remote.error !== void 0 || remote.status !== 0) throw new Error("Failed to configure the credential-free Context Tree origin.");
+	return name;
+}
+function scaffoldTree(options) {
+	const title = parseGitHubRepositoryIdentity(options.repository);
+	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 initialBranch = initializeGitRepository(root, options.repository);
+	const values = {
+		branchJson: JSON.stringify(initialBranch),
+		packageVersion: readPackageVersion(),
+		title,
+		titleJson: JSON.stringify(title)
+	};
+	const regularFiles = [
+		["NODE.md", "root-node.md"],
+		["AGENTS.md", "AGENTS.md"],
+		[".github/workflows/validate-context-tree.yml", "validate-context-tree.yml"]
+	];
+	const files = [
+		"NODE.md",
+		"AGENTS.md",
+		"CLAUDE.md",
+		".github/workflows/validate-context-tree.yml"
+	];
+	for (const [relativePath, source] of regularFiles.slice(0, 2)) {
+		const path = join(root, relativePath);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, template(source, values), {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 420
+		});
+	}
+	symlinkSync("AGENTS.md", join(root, "CLAUDE.md"), "file");
+	for (const [relativePath, source] of regularFiles.slice(2)) {
+		const path = join(root, relativePath);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, template(source, values), {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 420
+		});
+	}
+	return {
+		files,
+		root,
+		schemaVersion: 1,
+		verification: verifyTree(root)
+	};
+}
+//#endregion
+export { inspectContextTreeDiff, linkProject, readContextTreePolicy, readTree, refreshProject, resolveLink, scaffoldTree, stageContextWrite, verifyTree };