@first-tree-ai/context-tree 0.1.7-alpha.202609010710 → 0.1.7

package/dist/index.mjs

@@ -1,1449 +0,0 @@
-import { A as treeNameSchema, C as credentialFreeRepositoryUrlSchema, F as isRecord, O as parseContextTreeRootNode, P as parseMarkdownFrontmatter, T as githubRepositoryIdentitySchema, b as contextTreeStateSchema, f as contextTreeConnectionSchema, i as VALIDATION_CODES, t as CLI_ERROR_CODES } from "./schemas-DKHE1sWt.mjs";
-import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
-import { z } from "zod";
-import { spawnSync } from "node:child_process";
-import { fromMarkdown } from "mdast-util-from-markdown";
-import { fileURLToPath } from "node:url";
-//#region src/core/internal/errors.ts
-/**
-* A failure the CLI reports with a specific machine-readable code. Anything
-* thrown as a plain Error is reported as CONTEXT_TREE_FAILED instead.
-*/
-var ContextTreeError = class extends Error {
-	code;
-	constructor(code, message) {
-		super(message);
-		this.name = "ContextTreeError";
-		this.code = code;
-	}
-};
-//#endregion
-//#region src/core/internal/git.ts
-function defaultRunner(command, args) {
-	const result = spawnSync(command, args, {
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		]
-	});
-	return {
-		status: result.status,
-		stderr: typeof result.stderr === "string" ? result.stderr : "",
-		stdout: typeof result.stdout === "string" ? result.stdout : ""
-	};
-}
-/** A failed Git or `gh` operation. Messages never include the argv. */
-var CommandError = class extends Error {
-	command;
-	status;
-	stderr;
-	constructor(command, status, stderr, message) {
-		const detail = sanitizeCommandOutput(stderr).trim();
-		super(detail.length > 0 ? `${message}: ${detail}` : message);
-		this.name = "CommandError";
-		this.command = command;
-		this.status = status;
-		this.stderr = detail;
-	}
-};
-/** Remove credentials and common access-token shapes before surfacing subprocess output. */
-function sanitizeCommandOutput(value) {
-	return value.replace(/((?:https?|ssh):\/\/)[^\s/@]+@/giu, "$1<redacted>@").replace(/\b(?:gh[opsu]_[A-Za-z\d_]{20,}|github_pat_[A-Za-z\d_]{20,})\b/gu, "<redacted>").replace(/(authorization\s*:\s*(?:bearer|token)\s+)[^\s]+/giu, "$1<redacted>");
-}
-function trimOutput(value) {
-	return value.trim();
-}
-function execute(runner, command, args, message) {
-	const result = runner(command, args);
-	if (result.status !== 0) throw new CommandError(command, result.status, result.stderr, message);
-	return trimOutput(result.stdout);
-}
-/** Run a Git command that is not scoped by `-C`, such as `git init <path>`. */
-function gitCommand(args, options = {}) {
-	return execute(options.runner ?? defaultRunner, "git", args, options.message ?? "A Git operation failed.");
-}
-/** Run `git -C <root> <args>` and return trimmed stdout, throwing on failure. */
-function git(root, args, options = {}) {
-	return execute(options.runner ?? defaultRunner, "git", [
-		"-C",
-		root,
-		...args
-	], options.message ?? "A Git operation failed.");
-}
-/** Run `git -C <root> <args>` and return trimmed stdout, or undefined on failure. */
-function optionalGit(root, args, runner = defaultRunner) {
-	const result = runner("git", [
-		"-C",
-		root,
-		...args
-	]);
-	if (result.status !== 0) return void 0;
-	return trimOutput(result.stdout);
-}
-/** Run `gh <args>` and return trimmed stdout, throwing on failure. */
-function gh(args, options = {}) {
-	return execute(options.runner ?? defaultRunner, "gh", args, options.message ?? "A GitHub CLI operation failed.");
-}
-//#endregion
-//#region src/core/internal/github-repository.ts
-const ORIGIN_MESSAGE = "Context Tree origin must identify a credential-free GitHub OWNER/REPO repository.";
-function canonicalGitHubRepositoryUrl(repository) {
-	githubRepositoryIdentitySchema.parse(repository);
-	return `https://github.com/${repository}.git`;
-}
-/** Derive OWNER/REPO from a github.com origin, rejecting anything else. */
-function gitHubRepositoryFromOriginUrl(origin) {
-	if (!credentialFreeRepositoryUrlSchema.safeParse(origin).success) throw new Error(ORIGIN_MESSAGE);
-	let owner;
-	let name;
-	const scp = /^(?:git@)?github\.com:([^/]+)\/(.+)$/iu.exec(origin);
-	if (scp !== null) [, owner, name] = scp;
-	else {
-		const url = URL.parse(origin);
-		if (url === null || url.hostname.toLowerCase() !== "github.com") throw new Error(ORIGIN_MESSAGE);
-		[owner, name] = url.pathname.replace(/^\/+|\/+$/gu, "").split("/");
-	}
-	const repository = `${owner ?? ""}/${(name ?? "").replace(/\.git$/iu, "")}`;
-	if (!githubRepositoryIdentitySchema.safeParse(repository).success) throw new Error(ORIGIN_MESSAGE);
-	return repository;
-}
-//#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);
-}
-/** Resolve a directory while rejecting symlinks in user-controlled path components. */
-function realDirectoryWithoutSymlinks(path, label) {
-	const absolute = resolve(path);
-	const parsed = parse(absolute);
-	const parts = absolute.slice(parsed.root.length).split(sep).filter(Boolean);
-	let current = parsed.root;
-	for (const [index, part] of parts.entries()) {
-		current = resolve(current, part);
-		if (lstatSync(current).isSymbolicLink()) if (index === 0) current = realpathSync(current);
-		else throw new Error(`${label} must contain no symlink component.`);
-	}
-	if (!lstatSync(current).isDirectory()) throw new Error(`${label} must be a directory.`);
-	return realpathSync(current);
-}
-function toPosixPath(path) {
-	return path.replace(/\\/gu, "/");
-}
-//#endregion
-//#region src/core/internal/project.ts
-/**
-* Projects are identified solely by their canonical local root. A Git
-* repository without an origin, a non-Git directory, a Git worktree, and a
-* separate clone are all independent checkouts with their own canonical root.
-*/
-function canonicalProjectRoot(path, runner) {
-	const directory = realDirectoryWithoutSymlinks(path, "Project path");
-	const toplevel = optionalGit(directory, ["rev-parse", "--show-toplevel"], runner);
-	if (toplevel === void 0 || toplevel.length === 0) return directory;
-	return realpathSync(toplevel);
-}
-//#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/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/internal/tree-state.ts
-/**
-* The one tree-state resolver shared by create, connect, sync, publish, and
-* writes. It validates a checkout exactly once and reports the discriminated
-* tree state: a local-only tree, or a published tree with its GitHub
-* OWNER/REPO identity. Resolution never backfills or mutates stored state.
-*/
-/** Require a real directory with no symlink component that is an exact Git root. */
-function exactGitRoot(treePath, runner) {
-	const root = realDirectoryWithoutSymlinks(treePath, "Context Tree path");
-	const toplevel = optionalGit(root, ["rev-parse", "--show-toplevel"], runner);
-	if (toplevel === void 0 || toplevel.length === 0) throw new Error("Context Tree path must be a Git repository.");
-	if (realpathSync(toplevel) !== root) throw new Error("Context Tree path must be the real Git root.");
-	return root;
-}
-/** Parse the root NODE.md, refusing symlinked or irregular files. */
-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));
-}
-/**
-* Validate a clean checkout without inferring state from mutable Git remotes.
-* Uncommitted changes and invalid content each get their own code so callers
-* can tell "commit your edits" apart from "this path is gone".
-*/
-function validateTreeCheckout(treePath, runner) {
-	const root = exactGitRoot(treePath, runner);
-	if (git(root, [
-		"status",
-		"--porcelain",
-		"--untracked-files=all"
-	], {
-		message: "Failed to inspect Context Tree cleanliness.",
-		runner
-	}).trim().length !== 0) throw new ContextTreeError(CLI_ERROR_CODES.dirtyTree, `The Context Tree at ${root} has uncommitted changes; commit or discard them.`);
-	if (!verifyTree(root).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `The Context Tree at ${root} is invalid; run context-tree verify --tree-path ${root}.`);
-	return root;
-}
-/** Validate a stored state without reclassifying it from mutable Git remotes. */
-function validateStoredTreeState(state, runner) {
-	const path = validateTreeCheckout(state.path, runner);
-	return state.kind === "local" ? {
-		kind: "local",
-		path
-	} : {
-		kind: "github",
-		path,
-		repository: state.repository
-	};
-}
-//#endregion
-//#region src/core/connections.ts
-const connectionsFileSchema = z.object({
-	connections: z.array(contextTreeConnectionSchema),
-	schemaVersion: z.literal(1)
-}).strict();
-const DUPLICATE_MESSAGE = "Duplicate Context Tree connection records exist for this project.";
-const NO_CONNECTION_MESSAGE = "No Context Tree connection exists for this project; run context-tree create or connect.";
-function realHome() {
-	try {
-		return realpathSync(homedir());
-	} catch {
-		return homedir();
-	}
-}
-/** Create a managed application directory below the home directory, failing closed on symlinks. */
-function ensureManagedDirectory(...segments) {
-	let current = realHome();
-	for (const segment of segments) {
-		current = join(current, segment);
-		const entry = lstatSync(current, { throwIfNoEntry: false });
-		if (entry === void 0) {
-			mkdirSync(current, { mode: 448 });
-			continue;
-		}
-		if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Context Tree managed directory must be a real directory: ${current}`);
-	}
-	return current;
-}
-/** The managed namespace without creating it; listing must not create an absent directory. */
-function managedTreesPath() {
-	return join(realHome(), ".context-tree", "trees");
-}
-function connectionsPath() {
-	return join(realHome(), ".context-tree", "connections.json");
-}
-function managedTreesRoot() {
-	return ensureManagedDirectory(".context-tree", "trees");
-}
-function loadConnections(required) {
-	const path = connectionsPath();
-	if (!existsSync(path)) {
-		if (required) throw new ContextTreeError(CLI_ERROR_CODES.noConnection, NO_CONNECTION_MESSAGE);
-		return {
-			connections: [],
-			schemaVersion: 1
-		};
-	}
-	try {
-		const entry = lstatSync(path);
-		if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("not a regular file");
-		return connectionsFileSchema.parse(JSON.parse(readFileSync(path, "utf8")));
-	} catch {
-		throw new ContextTreeError(CLI_ERROR_CODES.corruptConnection, "Context Tree connections are corrupt; remove connections.json and run context-tree connect again.");
-	}
-}
-function saveConnections(value) {
-	const directory = ensureManagedDirectory(".context-tree");
-	const path = join(directory, "connections.json");
-	const temporary = join(directory, `.connections-${process.pid}-${Date.now()}.tmp`);
-	writeFileSync(temporary, `${JSON.stringify(connectionsFileSchema.parse(value), null, 2)}\n`, {
-		encoding: "utf8",
-		flag: "wx",
-		mode: 384
-	});
-	try {
-		renameSync(temporary, path);
-		chmodSync(path, 384);
-	} finally {
-		rmSync(temporary, { force: true });
-	}
-}
-/** Exactly one record may exist per project; more than one is corruption. */
-function singleConnection(stored, canonical) {
-	const matches = stored.connections.filter((connection) => connection.projectPath === canonical);
-	if (matches.length > 1) throw new ContextTreeError(CLI_ERROR_CODES.corruptConnection, DUPLICATE_MESSAGE);
-	return matches[0];
-}
-function isManagedName(value) {
-	return treeNameSchema.safeParse(value).success && value === value.toLowerCase();
-}
-function managedName(value) {
-	if (!isManagedName(value)) throw new Error(`Managed Context Tree names must be safe lowercase path segments: ${value}`);
-	return value;
-}
-/** List valid, clean managed trees, excluding unsafe or invalid candidates without failing the listing. */
-function listManagedTrees(runner) {
-	const root = managedTreesPath();
-	if (!existsSync(root)) return {
-		schemaVersion: 1,
-		trees: []
-	};
-	const rootEntry = lstatSync(root);
-	if (rootEntry.isSymbolicLink() || !rootEntry.isDirectory()) throw new Error("Context Tree managed directory must be a real directory.");
-	const trees = [];
-	for (const candidate of readdirSync(root, { withFileTypes: true })) {
-		if (!candidate.isDirectory() || !isManagedName(candidate.name)) continue;
-		try {
-			trees.push({
-				name: candidate.name,
-				tree: classifyCheckout(join(root, candidate.name), runner)
-			});
-		} catch {}
-	}
-	trees.sort((left, right) => left.name.localeCompare(right.name));
-	return {
-		schemaVersion: 1,
-		trees
-	};
-}
-function findConnectionRecord(projectPath, runner) {
-	return singleConnection(loadConnections(false), canonicalProjectRoot(projectPath, runner));
-}
-function validateManagedTreeState(tree, runner) {
-	const validated = validateStoredTreeState(tree, runner);
-	if (dirname(validated.path) === managedTreesPath() && !isManagedName(basename(validated.path))) throw new Error(`Managed Context Tree names must be safe lowercase path segments: ${basename(validated.path)}`);
-	return validated;
-}
-function resolveConnectionRecord(projectPath, runner) {
-	const canonical = canonicalProjectRoot(projectPath, runner);
-	const connection = singleConnection(loadConnections(true), canonical);
-	if (connection === void 0) throw new ContextTreeError(CLI_ERROR_CODES.noConnection, NO_CONNECTION_MESSAGE);
-	try {
-		return {
-			projectPath: connection.projectPath,
-			tree: validateManagedTreeState(connection.tree, runner)
-		};
-	} catch (error) {
-		if (error instanceof ContextTreeError) throw error;
-		const detail = error instanceof Error ? error.message : "unknown failure";
-		throw new ContextTreeError(CLI_ERROR_CODES.staleConnection, `The connected Context Tree is no longer usable at ${connection.tree.path}; run context-tree connect to point this project at its current location. ${detail}`);
-	}
-}
-function resolveConnection(projectPath, runner) {
-	return {
-		schemaVersion: 1,
-		tree: resolveConnectionRecord(projectPath, runner).tree
-	};
-}
-function upsertConnection(connection, runner) {
-	const canonical = canonicalProjectRoot(connection.projectPath, runner);
-	const record = {
-		projectPath: canonical,
-		tree: validateManagedTreeState(contextTreeStateSchema.parse(connection.tree), runner)
-	};
-	const stored = loadConnections(false);
-	const previous = singleConnection(stored, canonical);
-	if (previous !== void 0 && JSON.stringify(previous.tree) === JSON.stringify(record.tree)) return {
-		schemaVersion: 1,
-		tree: record.tree
-	};
-	saveConnections({
-		connections: [...stored.connections.filter((candidate) => candidate.projectPath !== canonical), record],
-		schemaVersion: 1
-	});
-	return {
-		schemaVersion: 1,
-		tree: record.tree
-	};
-}
-function updateConnectionTree(projectPath, tree, runner) {
-	const canonical = canonicalProjectRoot(projectPath, runner);
-	const stored = loadConnections(true);
-	if (singleConnection(stored, canonical) === void 0) throw new ContextTreeError(CLI_ERROR_CODES.noConnection, NO_CONNECTION_MESSAGE);
-	const validatedTree = validateManagedTreeState(contextTreeStateSchema.parse(tree), runner);
-	saveConnections({
-		connections: stored.connections.map((connection) => connection.projectPath === canonical ? {
-			...connection,
-			tree: validatedTree
-		} : connection),
-		schemaVersion: 1
-	});
-}
-/**
-* Validate an exact checkout and classify it from a safe origin: no origin
-* is local state, a credential-free GitHub origin is GitHub state, and any
-* other origin is rejected as unsafe or unsupported.
-*/
-function classifyCheckout(path, runner) {
-	const root = validateTreeCheckout(path, runner);
-	const origin = optionalGit(root, [
-		"remote",
-		"get-url",
-		"origin"
-	], runner);
-	if (origin === void 0) return {
-		kind: "local",
-		path: root
-	};
-	return {
-		kind: "github",
-		path: root,
-		repository: gitHubRepositoryFromOriginUrl(origin)
-	};
-}
-function sameRepository(left, right) {
-	return left.toLowerCase() === right.toLowerCase();
-}
-/** An existing managed directory that must be a real directory, not a symlinked alias. */
-function realManagedDirectory(name, destination) {
-	const entry = lstatSync(destination);
-	if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Managed Context Tree name ${name} is occupied by an unsafe destination.`);
-}
-/**
-* Connect by exact managed name or GitHub OWNER/REPO, or attach an exact,
-* clean, fully valid Git checkout at an explicit disk path in place.
-*/
-function connectProject(options, runner) {
-	if ("treePath" in options) {
-		const tree = classifyCheckout(options.treePath, runner);
-		return upsertConnection({
-			projectPath: options.projectPath,
-			tree
-		}, runner);
-	}
-	const treesRoot = managedTreesRoot();
-	if (!options.target.includes("/")) {
-		const name = managedName(options.target);
-		const destination = join(treesRoot, name);
-		if (!existsSync(destination)) throw new Error(`No managed Context Tree named ${name} exists.`);
-		realManagedDirectory(name, destination);
-		const tree = classifyCheckout(destination, runner);
-		return upsertConnection({
-			projectPath: options.projectPath,
-			tree
-		}, runner);
-	}
-	const repository = githubRepositoryIdentitySchema.parse(options.target);
-	const repositoryName = repository.split("/")[1];
-	if (repositoryName === void 0) throw new Error("Repository must be OWNER/REPO.");
-	const name = managedName(repositoryName.toLowerCase());
-	const destination = join(treesRoot, name);
-	if (existsSync(destination)) {
-		realManagedDirectory(name, destination);
-		const tree = classifyCheckout(destination, runner);
-		if (tree.kind !== "github" || !sameRepository(tree.repository, repository)) throw new Error(`Managed Context Tree name ${name} is already used by a different tree.`);
-		return upsertConnection({
-			projectPath: options.projectPath,
-			tree
-		}, runner);
-	}
-	mkdirSync(destination, { mode: 448 });
-	try {
-		git(treesRoot, [
-			"clone",
-			"--quiet",
-			"--origin",
-			"origin",
-			"--",
-			canonicalGitHubRepositoryUrl(repository),
-			destination
-		], {
-			message: "Cloning the Context Tree repository failed.",
-			runner
-		});
-		const tree = classifyCheckout(destination, runner);
-		if (tree.kind !== "github" || !sameRepository(tree.repository, repository)) throw new Error("The cloned Context Tree origin does not match the requested repository.");
-		return upsertConnection({
-			projectPath: options.projectPath,
-			tree
-		}, runner);
-	} catch (error) {
-		rmSync(destination, {
-			force: true,
-			recursive: true
-		});
-		throw error;
-	}
-}
-//#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/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;
-}
-/** Templated regular files, written before the CLAUDE.md -> AGENTS.md symlink. */
-const TEMPLATED_FILES = [
-	["NODE.md", "root-node.md"],
-	["AGENTS.md", "AGENTS.md"],
-	[".github/workflows/validate-context-tree.yml", "validate-context-tree.yml"]
-];
-const SCAFFOLD_FILES = [
-	"NODE.md",
-	"AGENTS.md",
-	"CLAUDE.md",
-	".github/workflows/validate-context-tree.yml"
-];
-function initializeGitRepository(root, runner) {
-	gitCommand([
-		"init",
-		"--quiet",
-		"--",
-		root
-	], {
-		message: "Failed to initialize Git repository.",
-		runner
-	});
-	return git(root, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the initial Git branch during repository initialization.",
-		runner
-	});
-}
-function commitScaffold(root, runner) {
-	for (const file of SCAFFOLD_FILES) git(root, [
-		"add",
-		"--",
-		file
-	], {
-		message: "Failed to stage the scaffold files.",
-		runner
-	});
-	git(root, [
-		"-c",
-		"user.name=Context Tree",
-		"-c",
-		"user.email=context-tree@localhost",
-		"-c",
-		"commit.gpgsign=false",
-		"commit",
-		"--quiet",
-		"-m",
-		"Initialize Context Tree"
-	], {
-		message: "Failed to commit the scaffold.",
-		runner
-	});
-	return git(root, ["rev-parse", "HEAD"], {
-		message: "Failed to resolve the scaffold commit.",
-		runner
-	});
-}
-function scaffoldTree(options) {
-	const name = treeNameSchema.parse(options.name);
-	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.runner);
-	const values = {
-		branchJson: JSON.stringify(initialBranch),
-		packageVersion: readPackageVersion(),
-		title: name,
-		titleJson: JSON.stringify(name)
-	};
-	for (const [relativePath, source] of TEMPLATED_FILES) {
-		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");
-	if (!verifyTree(root).ok) throw new Error("Refusing to commit an invalid Context Tree scaffold.");
-	return {
-		branch: initialBranch,
-		commit: commitScaffold(root, options.runner),
-		root
-	};
-}
-//#endregion
-//#region src/core/create.ts
-function projectName(canonicalRoot) {
-	const normalized = basename(canonicalRoot).toLowerCase().replace(/[^a-z\d._-]+/gu, "-").replace(/-{2,}/gu, "-").replace(/^[-.]+/u, "").replace(/[-.]+$/u, "").slice(0, 40);
-	return /^[a-z\d]/u.test(normalized) ? normalized : "project";
-}
-function existingCreateResult(destination, runner) {
-	return {
-		branch: git(destination, [
-			"symbolic-ref",
-			"--short",
-			"HEAD"
-		], {
-			message: "Failed to resolve the managed tree branch.",
-			runner
-		}),
-		commitSha: git(destination, ["rev-parse", "HEAD"], {
-			message: "Failed to resolve the managed tree commit.",
-			runner
-		}),
-		created: false,
-		schemaVersion: 1,
-		title: parseRootNode(destination).frontmatter.title,
-		treePath: destination
-	};
-}
-/** Create and connect the project's uniquely named managed local Context Tree. */
-function createProject(projectPath, runner) {
-	const canonical = canonicalProjectRoot(projectPath, runner);
-	const name = treeNameSchema.parse(`${projectName(canonical)}-context-tree`);
-	const destination = join(managedTreesRoot(), name);
-	const current = findConnectionRecord(canonical, runner);
-	if (current !== void 0 && current.tree.path !== destination) throw new Error(`This project is already connected to a Context Tree at ${current.tree.path}; run context-tree connect ${name} to switch.`);
-	if (existsSync(destination)) {
-		const entry = lstatSync(destination);
-		if (entry.isSymbolicLink() || !entry.isDirectory() || current === void 0) throw new Error(`Managed Context Tree name ${name} is occupied; run context-tree connect ${name}.`);
-		return existingCreateResult(destination, runner);
-	}
-	mkdirSync(destination, { mode: 448 });
-	try {
-		const scaffold = scaffoldTree({
-			name,
-			path: destination,
-			runner
-		});
-		upsertConnection({
-			projectPath: canonical,
-			tree: {
-				kind: "local",
-				path: scaffold.root
-			}
-		}, runner);
-		return {
-			branch: scaffold.branch,
-			commitSha: scaffold.commit,
-			created: true,
-			schemaVersion: 1,
-			title: name,
-			treePath: scaffold.root
-		};
-	} catch (error) {
-		rmSync(destination, {
-			force: true,
-			recursive: true
-		});
-		throw error;
-	}
-}
-//#endregion
-//#region src/core/policy.ts
-function readContextTreePolicy() {
-	return {
-		content: readFileSync(resolvePackagedResource("policy", "context-tree-policy.md"), "utf8"),
-		schemaVersion: 1
-	};
-}
-//#endregion
-//#region src/core/publish.ts
-function authenticatedAccount(runner) {
-	let login;
-	try {
-		login = gh([
-			"api",
-			"user",
-			"--jq",
-			".login"
-		], {
-			message: "GitHub account lookup failed.",
-			runner
-		});
-	} catch (error) {
-		if (error instanceof CommandError && /gh auth login|not logged|authentication failed|http 401|bad credentials/iu.test(error.stderr)) throw new ContextTreeError(CLI_ERROR_CODES.githubAuth, "GitHub authentication failed; run gh auth login before publishing.");
-		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub account lookup failed; publication did not start and must not be retried automatically.");
-	}
-	if (login.trim().length === 0) throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub account lookup returned no repository owner.");
-	return login.trim();
-}
-function classifyCreationFailure(stderr) {
-	if (/already exists/iu.test(stderr)) return new ContextTreeError(CLI_ERROR_CODES.repositoryExists, "A GitHub repository with this name already exists; choose an explicit OWNER/REPO override.");
-	return new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub repository creation has an uncertain or partial result; do not retry automatically.");
-}
-/**
-* Publish a clean, valid local tree as a private GitHub repository. The
-* default repository name derives from the authenticated account and managed
-* tree name; OWNER/REPO is accepted only as an explicit override. The initial
-* publication is one gh repo create operation, and the stored connection is
-* updated atomically to the published tree state.
-*/
-function publishProject(projectPath, options = {}, runner) {
-	const connection = resolveConnectionRecord(projectPath, runner);
-	const root = connection.tree.path;
-	if (connection.tree.kind === "github") throw new ContextTreeError(CLI_ERROR_CODES.failed, `The Context Tree is already published as ${connection.tree.repository}; writes publish new commits automatically.`);
-	if (optionalGit(root, [
-		"remote",
-		"get-url",
-		"origin"
-	], runner) !== void 0) throw new ContextTreeError(CLI_ERROR_CODES.failed, "A local Context Tree must not already have an origin before publication.");
-	const branch = git(root, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the checked-out branch.",
-		runner
-	});
-	const sha = git(root, ["rev-parse", "HEAD"], {
-		message: "Failed to resolve the Context Tree commit.",
-		runner
-	});
-	const repository = options.repository === void 0 ? `${authenticatedAccount(runner)}/${basename(root)}` : githubRepositoryIdentitySchema.parse(options.repository);
-	const url = canonicalGitHubRepositoryUrl(repository);
-	try {
-		gh([
-			"repo",
-			"create",
-			repository,
-			"--private",
-			"--source",
-			root,
-			"--remote",
-			"origin",
-			"--push"
-		], {
-			message: "GitHub repository creation failed.",
-			runner
-		});
-	} catch (error) {
-		if (error instanceof CommandError) throw classifyCreationFailure(error.stderr);
-		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub publication ended with an uncertain result.");
-	}
-	try {
-		updateConnectionTree(connection.projectPath, {
-			kind: "github",
-			path: root,
-			repository
-		}, runner);
-	} catch {
-		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "The private repository was created, but updating the local connection failed.");
-	}
-	return {
-		branch,
-		repository,
-		schemaVersion: 1,
-		sha,
-		url
-	};
-}
-//#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/sync.ts
-/**
-* Local trees report their checked-out state without network access. GitHub
-* trees fast-forward the exact checked-out branch once, then revalidate.
-*/
-function syncProject(projectPath, runner) {
-	const connection = resolveConnectionRecord(projectPath, runner);
-	const root = connection.tree.path;
-	const branch = git(root, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the checked-out branch.",
-		runner
-	});
-	if (connection.tree.kind === "github") {
-		git(root, [
-			"pull",
-			"--ff-only",
-			"origin",
-			branch
-		], {
-			message: "Fast-forwarding the Context Tree failed.",
-			runner
-		});
-		validateStoredTreeState(connection.tree, runner);
-	}
-	return {
-		branch,
-		schemaVersion: 1,
-		sha: git(root, ["rev-parse", "HEAD"], {
-			message: "Failed to resolve the Context Tree commit.",
-			runner
-		}),
-		tree: connection.tree
-	};
-}
-//#endregion
-//#region src/core/write.ts
-const TASK_BRANCH_PREFIX = "context-tree/write/";
-/** Synchronize first, then create an isolated task worktree at the exact HEAD. */
-function prepareContextWrite(projectPath, runner) {
-	const synchronized = syncProject(projectPath, runner);
-	const root = synchronized.tree.path;
-	const destination = mkdtempSync(join(tmpdir(), "context-tree-write-"));
-	const taskBranch = `${TASK_BRANCH_PREFIX}${basename(destination)}`;
-	try {
-		git(root, [
-			"worktree",
-			"add",
-			"--quiet",
-			"-b",
-			taskBranch,
-			destination,
-			synchronized.sha
-		], {
-			message: "Creating the isolated write worktree failed.",
-			runner
-		});
-		return {
-			schemaVersion: 1,
-			worktreePath: realDirectoryWithoutSymlinks(destination, "Write worktree")
-		};
-	} catch (error) {
-		rmSync(destination, {
-			force: true,
-			recursive: true
-		});
-		throw error;
-	}
-}
-/** Commit every pending change, then fast-forward locally or push once. */
-function finishContextWrite(options, runner) {
-	const connection = resolveConnectionRecord(options.projectPath, runner);
-	const root = connection.tree.path;
-	const { taskBranch, worktreePath } = validatePreparedWorktree(root, options.worktreePath, runner);
-	const branch = git(root, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the connected checkout branch.",
-		runner
-	});
-	if (git(worktreePath, [
-		"status",
-		"--porcelain",
-		"--untracked-files=all"
-	], {
-		message: "Failed to inspect the prepared worktree.",
-		runner
-	}).length === 0) throw new Error("The prepared worktree has no pending changes.");
-	if (!verifyTree(worktreePath).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `Refusing to commit an invalid Context Tree; run context-tree verify --tree-path ${worktreePath}.`);
-	git(worktreePath, ["add", "--all"], {
-		message: "Staging the Context Tree changes failed.",
-		runner
-	});
-	git(worktreePath, [
-		"-c",
-		"commit.gpgsign=false",
-		"commit",
-		"--quiet",
-		"-m",
-		options.message
-	], {
-		message: "Committing the Context Tree changes failed.",
-		runner
-	});
-	const sha = git(worktreePath, ["rev-parse", "HEAD"], {
-		message: "Failed to resolve the write commit.",
-		runner
-	});
-	try {
-		if (connection.tree.kind === "local") git(root, [
-			"merge",
-			"--ff-only",
-			taskBranch
-		], {
-			message: "Fast-forwarding the local Context Tree failed.",
-			runner
-		});
-		else git(worktreePath, [
-			"push",
-			"origin",
-			`HEAD:refs/heads/${branch}`
-		], {
-			message: "Publishing the Context Tree write failed.",
-			runner
-		});
-	} catch (error) {
-		if (isNonFastForward(error)) throw new ContextTreeError(CLI_ERROR_CODES.writeOutdated, `The Context Tree advanced; the prepared worktree is preserved at ${worktreePath}.`);
-		throw error;
-	}
-	removeWorktree(root, worktreePath, taskBranch, runner);
-	return {
-		branch,
-		schemaVersion: 1,
-		sha
-	};
-}
-function gitCommonDirectory(root, runner) {
-	const value = git(root, ["rev-parse", "--git-common-dir"], {
-		message: "Failed to resolve the Git common directory.",
-		runner
-	});
-	return realDirectoryWithoutSymlinks(isAbsolute(value) ? value : resolve(root, value), "Git common directory");
-}
-function validatePreparedWorktree(root, suppliedPath, runner) {
-	const worktreePath = realDirectoryWithoutSymlinks(suppliedPath, "Prepared worktree");
-	if (gitCommonDirectory(worktreePath, runner) !== gitCommonDirectory(root, runner)) throw new Error("The prepared worktree does not belong to the connected Context Tree.");
-	const taskBranch = git(worktreePath, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	], {
-		message: "Failed to resolve the worktree branch.",
-		runner
-	});
-	if (!taskBranch.startsWith(TASK_BRANCH_PREFIX)) throw new Error("The prepared worktree is not on a reserved Context Tree write branch.");
-	return {
-		taskBranch,
-		worktreePath
-	};
-}
-function isNonFastForward(error) {
-	return error instanceof CommandError && /non-fast-forward|fetch first|tip of your current branch is behind|not possible to fast-forward|diverg/i.test(error.stderr);
-}
-function removeWorktree(root, worktreePath, taskBranch, runner) {
-	git(root, [
-		"worktree",
-		"remove",
-		worktreePath
-	], {
-		message: "Removing the write worktree failed.",
-		runner
-	});
-	git(root, [
-		"branch",
-		"-D",
-		taskBranch
-	], {
-		message: "Deleting the write branch failed.",
-		runner
-	});
-}
-//#endregion
-export { connectProject, createProject, finishContextWrite, listManagedTrees, prepareContextWrite, publishProject, readContextTreePolicy, readTree, resolveConnection, syncProject, verifyTree };