attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/file/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Public filesystem surface: tree nodes, reads/writes, outlines and module
+ * graphs. Every export is read-only except `writeFile`/`ensureDirectory`;
+ * mutation authority is granted by a `SessionRoot` and enforced by
+ * `PathSandbox`.
+ */
+export * from "./types.js";
+export { FilesystemError, fail, isFilesystemError } from "./errors.js";
+export { detectCharset, decodeText, encodeText, countLines, LineIndex } from "../syntax/charset.js";
+export type { DetectedCharset } from "../syntax/charset.js";
+export { ByteLineIndex } from "../syntax/byteIndex.js";
+export { formatNodeTime, formatIsoTime, parseNodeTime, creationTime } from "./time.js";
+export { PathSandbox } from "./path.js";
+export type { PathSandboxOptions } from "./path.js";
+export { buildFileNode, wireNode, wireTree, verifyFingerprint } from "./file.js";
+export { buildDirectoryNode, listDirectory, compareTreeNodes } from "./directory.js";
+export { buildTree, WorkspaceTree } from "./tree.js";
+export { readPage, ReadCache, byteRangeFingerprint, locateLineSpan, useByte as useByteRead, useLine as useLineRead } from "./read.js";
+export type { ReadOptions, ByteUse, ByteUseRequest, LineEnding, LineSpan, LineUse, LineUseRequest } from "./read.js";
+export { writeFile, ensureDirectory, WriteLocks, useByte as useByteWrite, useLine as useLineWrite } from "./write.js";
+export type { BytePatchRequest, LinePatchRequest, PatchJournalEntry, WriteOptions, WritePatchOptions, WritePatchResult, } from "./write.js";
+export { SessionRuntime } from "./runtime.js";
+export type { AnnotationMap, ResolvedNode, SessionRuntimeOptions } from "./runtime.js";
+export { FilesystemService, FilesystemSession, filesystemSessionSummary } from "./service.js";
+export type { AstRequest, DependencyQuery, ExportRequest, FilesystemServiceLimits, FilesystemServiceOptions, ImportRequest, OutlineRequest, } from "./service.js";
+export { buildOutline, OutlineRegistry, DefaultOutlineRegistry, OutlineStrategies, OutlineMaxFileBytes, OutlineMaxScanLines, OutlineDefaultMaxNodes, OutlineHardMaxNodes, OutlineDefaultMaxDepth, OutlineHardMaxDepth, createOutlineRegistry, outlineLanguage, outlineNodeFingerprint, } from "../outline/outline.js";
+export type { FingerprintedOutlineNode, OutlineAnchor, OutlineMatchInput, OutlineOptions, OutlineParseInput, OutlineStrategy } from "../outline/outline.js";
+export { DefaultOutlineKeywords, OutlineKeywordRegistry, createOutlineKeywordRegistry } from "../outline/outlineKeywords.js";
+export type { OutlineKeywordCategory } from "../outline/outlineKeywords.js";
+export { buildSyntaxTree } from "./syntaxTree.js";
+export { DefaultSyntaxRegistry, SyntaxRegistry, buildSyntaxTreeFromText, createSyntaxRegistry, disposeSyntaxNode, syntaxLanguageOf, wireSyntaxTree, } from "../syntax/syntaxTree.js";
+export type { SyntaxLanguage, SyntaxLanguageDefinition, SyntaxNode, SyntaxNodeKind, SyntaxNodeKindDefinition, SyntaxToken, SyntaxTokenKind, SyntaxTokenKindDefinition, SyntaxTree, SyntaxTreeOptions, WireSyntaxNode, WireSyntaxToken, WireSyntaxTree, } from "../syntax/syntaxTree.js";
+export { OutlineIndex, buildOutlineIndex, filterOutline, hasLabelPrefix, wireOutline, wireOutlineNode, wireOutlineRange, outlineFromWire } from "../outline/outlineIndex.js";
+export type { OutlinePayload } from "../outline/outlineIndex.js";
+export { extractImports, importedBy, isParseableSource, readSourceFile, resolveImportSpecifier, tokenizeSource } from "./importGraph.js";
+export type { ResolvedSpecifier, SourceFileSnapshot, SourceToken } from "./importGraph.js";
+export { extractExports } from "./exportGraph.js";
+export { DependencyGraph, buildDependencyReport, graphFromImports } from "./dependency.js";
+export { isOfficeFile, parseOffice, officeImports, officeExports, officeReferences, officeOutlineParser, installOfficeOutlineParser } from "../outline/office.js";
+export type { OfficeDocument, OfficeFormat, OfficeKind, OfficeReference, OfficeSection, OfficeSectionKind } from "../outline/office.js";
+export { readCfb } from "./cfb.js";
+export type { CfbEntry } from "./cfb.js";
+export { readZipEntries, zipText } from "./zip.js";
+export type { ZipEntry } from "./zip.js";
+export type { DependencyClosure, DependencyRequest, DependencySubgraph, TopologicalResult } from "./dependency.js";

package/lib/file/index.js

@@ -0,0 +1,30 @@
+/**
+ * Public filesystem surface: tree nodes, reads/writes, outlines and module
+ * graphs. Every export is read-only except `writeFile`/`ensureDirectory`;
+ * mutation authority is granted by a `SessionRoot` and enforced by
+ * `PathSandbox`.
+ */
+export * from "./types.js";
+export { FilesystemError, fail, isFilesystemError } from "./errors.js";
+export { detectCharset, decodeText, encodeText, countLines, LineIndex } from "../syntax/charset.js";
+export { ByteLineIndex } from "../syntax/byteIndex.js";
+export { formatNodeTime, formatIsoTime, parseNodeTime, creationTime } from "./time.js";
+export { PathSandbox } from "./path.js";
+export { buildFileNode, wireNode, wireTree, verifyFingerprint } from "./file.js";
+export { buildDirectoryNode, listDirectory, compareTreeNodes } from "./directory.js";
+export { buildTree, WorkspaceTree } from "./tree.js";
+export { readPage, ReadCache, byteRangeFingerprint, locateLineSpan, useByte as useByteRead, useLine as useLineRead } from "./read.js";
+export { writeFile, ensureDirectory, WriteLocks, useByte as useByteWrite, useLine as useLineWrite } from "./write.js";
+export { SessionRuntime } from "./runtime.js";
+export { FilesystemService, FilesystemSession, filesystemSessionSummary } from "./service.js";
+export { buildOutline, OutlineRegistry, DefaultOutlineRegistry, OutlineStrategies, OutlineMaxFileBytes, OutlineMaxScanLines, OutlineDefaultMaxNodes, OutlineHardMaxNodes, OutlineDefaultMaxDepth, OutlineHardMaxDepth, createOutlineRegistry, outlineLanguage, outlineNodeFingerprint, } from "../outline/outline.js";
+export { DefaultOutlineKeywords, OutlineKeywordRegistry, createOutlineKeywordRegistry } from "../outline/outlineKeywords.js";
+export { buildSyntaxTree } from "./syntaxTree.js";
+export { DefaultSyntaxRegistry, SyntaxRegistry, buildSyntaxTreeFromText, createSyntaxRegistry, disposeSyntaxNode, syntaxLanguageOf, wireSyntaxTree, } from "../syntax/syntaxTree.js";
+export { OutlineIndex, buildOutlineIndex, filterOutline, hasLabelPrefix, wireOutline, wireOutlineNode, wireOutlineRange, outlineFromWire } from "../outline/outlineIndex.js";
+export { extractImports, importedBy, isParseableSource, readSourceFile, resolveImportSpecifier, tokenizeSource } from "./importGraph.js";
+export { extractExports } from "./exportGraph.js";
+export { DependencyGraph, buildDependencyReport, graphFromImports } from "./dependency.js";
+export { isOfficeFile, parseOffice, officeImports, officeExports, officeReferences, officeOutlineParser, installOfficeOutlineParser } from "../outline/office.js";
+export { readCfb } from "./cfb.js";
+export { readZipEntries, zipText } from "./zip.js";

package/lib/file/metadata.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Deterministic, bounded metadata extraction for tree nodes.
+ *
+ * Descriptions are derived only from bytes the caller already has: a leading
+ * JSDoc or line comment, a Markdown heading and paragraph, front matter, a
+ * package manifest or the first paragraph of plain text. Extraction never
+ * touches the filesystem, never executes code and never inspects more than the
+ * first 64 KiB of a file, so building a tree stays cheap and side-effect free.
+ *
+ * The three fields have different jobs. `description` is a short identity line,
+ * `summary` adds detail for retrieval and `purpose` records what the host or the
+ * document explicitly says the node is for. Host annotations override all three,
+ * but they are descriptive only: they never change a fingerprint.
+ */
+import type { Charset } from "../syntax/types.js";
+import type { NodeAnnotation, TreeNode } from "./types.js";
+/**
+ * Descriptive fields derived for one node.
+ */
+export interface NodeDescription {
+    readonly description: string;
+    readonly summary: string;
+    readonly purpose: string;
+}
+/**
+ * Last path segment, accepting both POSIX and host separators so an absolute
+ * path is usable as a name fallback. The root path normalizes to `.`.
+ */
+export declare const nameOfPath: (value: string) => string;
+/**
+ * Last lowercase extension without the dot; the empty string when the name has
+ * no extension. A leading dot is a hidden-file marker, not an extension.
+ */
+export declare const extensionOfPath: (value: string) => string;
+/**
+ * Derive description/summary/purpose for one file from its detected charset and
+ * a bounded head of its bytes.
+ *
+ * @param absolute - Absolute host path, used only as a name fallback.
+ * @param relative - Root-relative POSIX path.
+ * @param charset - Detected charset; `binary`/`none` disable text extraction.
+ * @param head - First bytes of the file; at most 64 KiB are inspected.
+ * @param annotation - Optional host override.
+ * @returns The three descriptive fields.
+ */
+export declare const describeFile: (absolute: string, relative: string, charset: Charset, head: Uint8Array, annotation?: NodeAnnotation) => NodeDescription;
+/**
+ * Derive description/summary/purpose for one directory from its direct
+ * children.
+ *
+ * @param relative - Root-relative POSIX path.
+ * @param children - Direct children in tree order.
+ * @param annotation - Optional host override.
+ * @param readme - Optional README text used for the purpose.
+ * @returns The three descriptive fields.
+ */
+export declare const describeDirectory: (relative: string, children: readonly TreeNode[], annotation?: NodeAnnotation, readme?: string) => NodeDescription;
+/**
+ * Look up an annotation by exact root-relative path. Parent-directory
+ * annotations are not inherited: an override names exactly one node.
+ *
+ * @param annotations - Path-keyed override map.
+ * @param relative - Exact root-relative path.
+ * @returns The annotation when present.
+ */
+export declare const annotationFor: (annotations: Readonly<Record<string, NodeAnnotation>> | undefined, relative: string) => NodeAnnotation | undefined;

package/lib/file/metadata.js

@@ -0,0 +1,470 @@
+import { decodeText } from "../syntax/charset.js";
+const MaxHeadBytes = 64 * 1024;
+const MaxDescriptionLength = 160;
+const MaxSummaryLength = 400;
+const MaxPurposeLength = 200;
+const MaxSummaryChildren = 6;
+const ScriptExtensions = new Set([
+    "js",
+    "jsx",
+    "mjs",
+    "cjs",
+    "ts",
+    "tsx",
+    "mts",
+    "cts",
+    "java",
+    "kt",
+    "kts",
+    "c",
+    "h",
+    "cc",
+    "cpp",
+    "hpp",
+    "cs",
+    "go",
+    "rs",
+    "swift",
+]);
+const MarkdownExtensions = new Set(["md", "markdown", "mdx"]);
+const collapse = (value) => value.replace(/\s+/gu, " ").trim();
+const safeSliceEnd = (value, end) => {
+    let cut = Math.min(end, value.length);
+    if (cut > 0 && cut < value.length) {
+        const code = value.charCodeAt(cut - 1);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            cut -= 1;
+        }
+    }
+    return cut;
+};
+const clip = (value, maximum) => {
+    if (value.length <= maximum) {
+        return value;
+    }
+    const cut = safeSliceEnd(value, Math.max(0, maximum - 3));
+    return `${value.slice(0, cut)}...`;
+};
+const normalizeField = (value, maximum) => clip(collapse(value), maximum);
+/**
+ * Last path segment, accepting both POSIX and host separators so an absolute
+ * path is usable as a name fallback. The root path normalizes to `.`.
+ */
+export const nameOfPath = (value) => {
+    const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (normalized.length === 0 || normalized === ".") {
+        return ".";
+    }
+    const slash = normalized.lastIndexOf("/");
+    return slash === -1 ? normalized : normalized.slice(slash + 1);
+};
+/**
+ * Last lowercase extension without the dot; the empty string when the name has
+ * no extension. A leading dot is a hidden-file marker, not an extension.
+ */
+export const extensionOfPath = (value) => {
+    const name = nameOfPath(value);
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0 || dot === name.length - 1) {
+        return "";
+    }
+    return name.slice(dot + 1).toLowerCase();
+};
+const decodePreview = (head, charset) => {
+    if (charset === "binary" || charset === "none") {
+        return undefined;
+    }
+    const bounded = head.length > MaxHeadBytes ? head.subarray(0, MaxHeadBytes) : head;
+    const even = charset === "utf-16le" || charset === "utf-16be" ? bounded.subarray(0, bounded.length - (bounded.length % 2)) : bounded;
+    for (let trim = 0; trim <= 3; trim += 1) {
+        const candidate = trim === 0 ? even : even.subarray(0, Math.max(0, even.length - trim));
+        try {
+            return decodeText(candidate, charset);
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+};
+const stripQuotes = (value) => {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2) {
+        const first = trimmed[0];
+        const last = trimmed[trimmed.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return trimmed.slice(1, -1).trim();
+        }
+    }
+    return trimmed;
+};
+const parseFrontMatter = (text) => {
+    const normalized = text.replace(/\r\n?/g, "\n").replace(/^\uFEFF/, "");
+    const lines = normalized.split("\n");
+    if (lines.length === 0 || lines[0].trim() !== "---") {
+        return { body: normalized };
+    }
+    let closing = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        const marker = lines[index].trim();
+        if (marker === "---" || marker === "...") {
+            closing = index;
+            break;
+        }
+    }
+    if (closing === -1) {
+        return { body: normalized };
+    }
+    const fields = {};
+    for (let index = 1; index < closing; index += 1) {
+        const match = /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[index]);
+        if (match === null) {
+            continue;
+        }
+        const key = match[1].toLowerCase();
+        const value = stripQuotes(match[2]);
+        if (value.length === 0) {
+            continue;
+        }
+        if (key === "title" && fields.title === (void 0)) {
+            fields.title = value;
+        }
+        else if (key === "description" && fields.description === (void 0)) {
+            fields.description = value;
+        }
+        else if (key === "purpose" && fields.purpose === (void 0)) {
+            fields.purpose = value;
+        }
+    }
+    return {
+        title: fields.title,
+        description: fields.description,
+        purpose: fields.purpose,
+        body: lines.slice(closing + 1).join("\n"),
+    };
+};
+const firstNonEmptyLine = (text) => {
+    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const trimmed = lines[index].trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    return undefined;
+};
+const firstParagraph = (text) => {
+    const raw = text.replace(/\r\n?/g, "\n").split("\n");
+    const lines = [];
+    for (let index = 0; index < raw.length; index += 1) {
+        const line = raw[index].trim();
+        const next = index + 1 < raw.length ? raw[index + 1].trim() : "";
+        if (line.length > 0 && !line.startsWith("#") && /^=+\s*$/.test(next)) {
+            lines.push("");
+            index += 1;
+            continue;
+        }
+        lines.push(line);
+    }
+    const collected = [];
+    let started = false;
+    let fence = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        const fenceLine = line.startsWith("```") || line.startsWith("~~~");
+        if (fenceLine) {
+            if (started) {
+                break;
+            }
+            fence = !fence;
+            continue;
+        }
+        if (fence) {
+            continue;
+        }
+        if (!started) {
+            if (line.length === 0 || line.startsWith("#")) {
+                continue;
+            }
+            started = true;
+        }
+        else if (line.length === 0 || line.startsWith("#")) {
+            break;
+        }
+        collected.push(line);
+    }
+    return collected.length === 0 ? undefined : collected.join(" ");
+};
+const firstMarkdownHeading = (text) => {
+    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    let fence = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        if (line.startsWith("```") || line.startsWith("~~~")) {
+            fence = !fence;
+            continue;
+        }
+        if (fence) {
+            continue;
+        }
+        const match = /^#\s+(.+?)\s*#*\s*$/.exec(line);
+        if (match !== null) {
+            return match[1].trim();
+        }
+        const next = index + 1 < lines.length ? lines[index + 1].trim() : "";
+        if (line.length > 0 && !line.startsWith("#") && /^=+\s*$/.test(next)) {
+            return line;
+        }
+    }
+    return undefined;
+};
+const cleanComment = (lines) => {
+    const cleaned = [];
+    let purpose;
+    for (let index = 0; index < lines.length; index += 1) {
+        let value = lines[index].trim();
+        if (value.startsWith("*")) {
+            value = value.replace(/^\*+\s?/, "").trim();
+        }
+        if (value.length === 0) {
+            cleaned.push("");
+            continue;
+        }
+        const tag = /^@([A-Za-z][A-Za-z0-9_-]*)\s*(.*)$/.exec(value);
+        if (tag !== null) {
+            if (tag[1].toLowerCase() === "purpose") {
+                purpose = tag[2].trim();
+            }
+            continue;
+        }
+        cleaned.push(value);
+    }
+    return { text: cleaned.join("\n").trim(), purpose };
+};
+const extractLeadingComment = (text) => {
+    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    let index = 0;
+    while (index < lines.length && lines[index].trim().length === 0) {
+        index += 1;
+    }
+    if (index < lines.length && lines[index].trimStart().startsWith("#!")) {
+        index += 1;
+    }
+    while (index < lines.length && lines[index].trim().length === 0) {
+        index += 1;
+    }
+    if (index >= lines.length) {
+        return undefined;
+    }
+    const first = lines[index].trimStart();
+    if (first.startsWith("/*")) {
+        const raw = [];
+        let closed = false;
+        for (; index < lines.length; index += 1) {
+            const line = lines[index];
+            const open = line.indexOf("/*");
+            const content = line.slice(open === -1 ? 0 : open + 2);
+            const close = content.indexOf("*/");
+            raw.push(close === -1 ? content : content.slice(0, close));
+            if (close !== -1) {
+                closed = true;
+                break;
+            }
+        }
+        return closed ? cleanComment(raw) : undefined;
+    }
+    if (first.startsWith("//")) {
+        const raw = [];
+        for (; index < lines.length; index += 1) {
+            const trimmed = lines[index].trim();
+            if (trimmed.startsWith("//")) {
+                raw.push(trimmed.slice(2));
+                continue;
+            }
+            if (trimmed.length === 0) {
+                raw.push("");
+                continue;
+            }
+            break;
+        }
+        return raw.length === 0 ? undefined : cleanComment(raw);
+    }
+    return undefined;
+};
+const describePackage = (text, relative) => {
+    if (nameOfPath(relative).toLowerCase() !== "package.json") {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof (parsed) !== "object" || parsed === null) {
+        return undefined;
+    }
+    const record = parsed;
+    const packageName = typeof (record.name) === "string" ? collapse(record.name) : "";
+    const declared = typeof (record.description) === "string" ? collapse(record.description) : "";
+    const description = packageName.length > 0 ? `Package ${packageName}.` : "File package.json.";
+    const summary = declared.length > 0 ? declared : description;
+    return {
+        description: normalizeField(description, MaxDescriptionLength),
+        summary: normalizeField(summary, MaxSummaryLength),
+        purpose: "not declared",
+    };
+};
+const withAnnotation = (base, annotation) => {
+    if (annotation === (void 0)) {
+        return base;
+    }
+    const description = annotation.description === (void 0) ? base.description : normalizeField(annotation.description, MaxDescriptionLength);
+    const summary = annotation.summary === (void 0) ? base.summary : normalizeField(annotation.summary, MaxSummaryLength);
+    const purpose = annotation.purpose === (void 0) ? base.purpose : normalizeField(annotation.purpose, MaxPurposeLength);
+    return { description, summary, purpose };
+};
+/**
+ * Derive description/summary/purpose for one file from its detected charset and
+ * a bounded head of its bytes.
+ *
+ * @param absolute - Absolute host path, used only as a name fallback.
+ * @param relative - Root-relative POSIX path.
+ * @param charset - Detected charset; `binary`/`none` disable text extraction.
+ * @param head - First bytes of the file; at most 64 KiB are inspected.
+ * @param annotation - Optional host override.
+ * @returns The three descriptive fields.
+ */
+export const describeFile = (absolute, relative, charset, head, annotation) => {
+    const nameFromPath = relative === "." || relative.length === 0 ? absolute : relative;
+    const name = nameOfPath(nameFromPath);
+    const fallback = {
+        description: normalizeField(`File ${name}.`, MaxDescriptionLength),
+        summary: normalizeField(`File ${name}.`, MaxSummaryLength),
+        purpose: "not declared",
+    };
+    const text = decodePreview(head, charset);
+    let description;
+    let summary;
+    let purpose;
+    if (text !== (void 0)) {
+        const front = parseFrontMatter(text);
+        const body = front.body;
+        const extension = extensionOfPath(relative);
+        const isPackage = nameOfPath(relative).toLowerCase() === "package.json";
+        const packageDescription = describePackage(text, relative);
+        if (packageDescription !== (void 0)) {
+            description = packageDescription.description;
+            summary = packageDescription.summary;
+            purpose = packageDescription.purpose;
+        }
+        else if (isPackage) {
+            description = "File package.json.";
+            summary = description;
+        }
+        else if (MarkdownExtensions.has(extension)) {
+            description = firstMarkdownHeading(body) ?? firstNonEmptyLine(body);
+            summary = firstParagraph(body) ?? description;
+        }
+        else if (ScriptExtensions.has(extension)) {
+            const comment = extractLeadingComment(body);
+            if (comment !== (void 0)) {
+                purpose = comment.purpose;
+            }
+            if (comment !== (void 0) && comment.text.length > 0) {
+                description = firstNonEmptyLine(comment.text);
+                summary = collapse(comment.text);
+            }
+            else {
+                description = firstNonEmptyLine(body);
+                summary = firstParagraph(body);
+            }
+        }
+        else {
+            description = firstNonEmptyLine(body);
+            summary = firstParagraph(body);
+        }
+        if (front.title !== (void 0)) {
+            description = front.title;
+        }
+        if (front.description !== (void 0)) {
+            summary = front.description;
+        }
+        if (front.purpose !== (void 0)) {
+            purpose = front.purpose;
+        }
+    }
+    const resolvedDescription = normalizeField(description ?? "", MaxDescriptionLength);
+    const resolvedSummary = normalizeField(summary ?? description ?? "", MaxSummaryLength);
+    const resolvedPurpose = normalizeField(purpose ?? "", MaxPurposeLength);
+    const base = {
+        description: resolvedDescription.length > 0 ? resolvedDescription : fallback.description,
+        summary: resolvedSummary.length > 0 ? resolvedSummary : resolvedDescription.length > 0 ? resolvedDescription : fallback.summary,
+        purpose: resolvedPurpose.length > 0 ? resolvedPurpose : fallback.purpose,
+    };
+    return withAnnotation(base, annotation);
+};
+/**
+ * Derive description/summary/purpose for one directory from its direct
+ * children.
+ *
+ * @param relative - Root-relative POSIX path.
+ * @param children - Direct children in tree order.
+ * @param annotation - Optional host override.
+ * @param readme - Optional README text used for the purpose.
+ * @returns The three descriptive fields.
+ */
+export const describeDirectory = (relative, children, annotation, readme) => {
+    const name = nameOfPath(relative);
+    let files = 0;
+    let directories = 0;
+    const names = [];
+    for (let index = 0; index < children.length; index += 1) {
+        const child = children[index];
+        if (child.type === "File") {
+            files += 1;
+            names.push(child.name);
+        }
+        else {
+            directories += 1;
+            names.push(`${child.name}/`);
+        }
+    }
+    names.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    const fileWord = files === 1 ? "file" : "files";
+    const directoryWord = directories === 1 ? "directory" : "directories";
+    const description = `Directory ${name} with ${files} ${fileWord} and ${directories} ${directoryWord}.`;
+    const visible = names.slice(0, MaxSummaryChildren);
+    const hidden = names.length - visible.length;
+    const summary = names.length === 0 ? "Empty directory." : `Children: ${visible.join(", ")}${hidden > 0 ? ` (+${hidden} more)` : ""}.`;
+    let purpose = "not declared";
+    if (readme !== (void 0)) {
+        const bounded = readme.length > MaxHeadBytes ? readme.slice(0, MaxHeadBytes) : readme;
+        const front = parseFrontMatter(bounded);
+        purpose = front.purpose ?? firstParagraph(front.body) ?? firstMarkdownHeading(front.body) ?? "not declared";
+    }
+    const base = {
+        description: normalizeField(description, MaxDescriptionLength),
+        summary: normalizeField(summary, MaxSummaryLength),
+        purpose: normalizeField(purpose, MaxPurposeLength),
+    };
+    return withAnnotation(base, annotation);
+};
+/**
+ * Look up an annotation by exact root-relative path. Parent-directory
+ * annotations are not inherited: an override names exactly one node.
+ *
+ * @param annotations - Path-keyed override map.
+ * @param relative - Exact root-relative path.
+ * @returns The annotation when present.
+ */
+export const annotationFor = (annotations, relative) => {
+    if (annotations === (void 0) || annotations === null) {
+        return undefined;
+    }
+    if (!Object.prototype.hasOwnProperty.call(annotations, relative)) {
+        return undefined;
+    }
+    return annotations[relative];
+};

package/lib/file/path.d.ts

@@ -0,0 +1,60 @@
+import type { SessionOperation, SessionRoot } from "../session/types.js";
+import type { RootedPath } from "./types.js";
+/**
+ * Sandbox options. Symlink following is off by default because a link is a
+ * capability the session was not granted.
+ */
+export interface PathSandboxOptions {
+    readonly followSymlinks?: boolean;
+}
+export declare class PathSandbox {
+    private readonly roots;
+    private readonly byId;
+    private readonly followSymlinks;
+    private readonly defaultRootId;
+    constructor(roots: readonly SessionRoot[], options?: PathSandboxOptions);
+    /**
+     * All roots, in the order the session declared them.
+     */
+    listRoots(): readonly SessionRoot[];
+    /**
+     * The root used when a path does not name one explicitly.
+     */
+    defaultRoot(): SessionRoot;
+    /**
+     * Look up a root by id.
+     */
+    root(id: string): SessionRoot;
+    /**
+     * Resolve a caller path to a root, a normalized relative path and an
+     * absolute host path. The method does not require the target to exist; a
+     * write may create it. Symlink checks stop at the first missing component.
+     *
+     * @param input - Root-relative POSIX path, optionally prefixed by `rootId/`.
+     * @param operation - Operation used for writability checks.
+     * @returns Resolved path.
+     */
+    resolve(input: unknown, operation: SessionOperation): RootedPath;
+    /**
+     * Whether an absolute path is inside a root, using the platform's case
+     * sensitivity.
+     */
+    contains(rootPath: string, absolute: string): boolean;
+    /**
+     * Prefix/name exclusion. A bare name excludes a segment at any depth; a
+     * value containing `/` is a root-relative prefix.
+     */
+    isExcluded(root: SessionRoot, relative: string): boolean;
+    /**
+     * The root-relative POSIX path for an absolute path already known to be in
+     * the root.
+     */
+    relative(root: SessionRoot, absolute: string): string;
+    /**
+     * Re-check that a path still resolves inside its root. Used after a write
+     * rename and before a read, so a component swapped for a symlink between
+     * resolution and I/O is rejected.
+     */
+    revalidate(rooted: RootedPath): void;
+    private assertNoSymlinkEscape;
+}