attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/file/syntaxTree.js

@@ -0,0 +1,38 @@
+/** Read-only syntax-tree construction through a session's filesystem sandbox. */
+import { readFileSync, statSync } from "node:fs";
+import { rawDigest } from "../fingerprint/raw.js";
+import { detectCharset, decodeText } from "../syntax/charset.js";
+import { buildSyntaxTreeFromText, DefaultSyntaxRegistry } from "../syntax/syntaxTree.js";
+import { fail, isFilesystemError } from "./errors.js";
+const DefaultMaxBytes = 4 * 1024 * 1024;
+/**
+ * Read and parse one file through the session sandbox. The parser is read-only:
+ * it never evaluates the file, resolves an import or launches a subprocess.
+ */
+export const buildSyntaxTree = (sandbox, path, options = {}) => {
+    const rooted = sandbox.resolve(path, "read");
+    sandbox.revalidate(rooted);
+    const stat = statSync(rooted.absolute);
+    if (!stat.isFile()) {
+        return fail("not_file");
+    }
+    const maxBytes = Math.min(options.maxBytes ?? DefaultMaxBytes, DefaultMaxBytes);
+    if (stat.size > maxBytes) {
+        return fail("quota_exceeded");
+    }
+    const bytes = readFileSync(rooted.absolute);
+    const detected = detectCharset(bytes);
+    if (detected.binary) {
+        return fail("binary_file");
+    }
+    let text;
+    try {
+        text = decodeText(bytes, detected.charset);
+    }
+    catch (error) {
+        return isFilesystemError(error) ? fail(error.code) : fail("charset_unsupported");
+    }
+    const registry = options.registry ?? DefaultSyntaxRegistry;
+    const built = buildSyntaxTreeFromText(rooted.relative, text, registry.languageOf(rooted.relative), options);
+    return { ...built, fingerprint: rawDigest(bytes), charset: detected.charset };
+};

package/lib/file/time.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Timestamp formatting shared by tree nodes, journal rows and protocol
+ * envelopes.
+ *
+ * Node metadata uses the wire shape `yyyy-MM-ddTHH:mm:ss` with no zone suffix.
+ * The default is host-local wall time because that is what a person sees in an
+ * explorer; `timeZone: "utc"` provides a reproducible snapshot for tests and
+ * cross-host comparison.
+ */
+import type { NodeTime } from "./types.js";
+/**
+ * Format a date as `yyyy-MM-ddTHH:mm:ss`.
+ *
+ * @param date - Date to format.
+ * @param timeZone - `local` (default) or `utc`.
+ * @returns The truncated timestamp.
+ */
+export declare const formatNodeTime: (date: Date, timeZone?: "local" | "utc") => NodeTime;
+/**
+ * Format an audit/envelope timestamp with milliseconds and a `Z` suffix.
+ */
+export declare const formatIsoTime: (date: Date) => string;
+/**
+ * Parse either a `yyyy-MM-ddTHH:mm:ss` node time or an ISO timestamp.
+ *
+ * @param value - Timestamp text.
+ * @returns The parsed date, or `undefined` when invalid.
+ */
+export declare const parseNodeTime: (value: string) => Date | undefined;
+/**
+ * Pick the useful creation time. Some filesystems report a zero birth time;
+ * the caller then falls back to change time, and finally to modification time.
+ */
+export declare const creationTime: (stat: {
+    birthtimeMs: number;
+    ctimeMs: number;
+    mtimeMs: number;
+}) => Date;

package/lib/file/time.js

@@ -0,0 +1,44 @@
+const pad = (value, width = 2) => String(value).padStart(width, "0");
+/**
+ * Format a date as `yyyy-MM-ddTHH:mm:ss`.
+ *
+ * @param date - Date to format.
+ * @param timeZone - `local` (default) or `utc`.
+ * @returns The truncated timestamp.
+ */
+export const formatNodeTime = (date, timeZone = "local") => {
+    const year = timeZone === "utc" ? date.getUTCFullYear() : date.getFullYear();
+    const month = timeZone === "utc" ? date.getUTCMonth() + 1 : date.getMonth() + 1;
+    const day = timeZone === "utc" ? date.getUTCDate() : date.getDate();
+    const hour = timeZone === "utc" ? date.getUTCHours() : date.getHours();
+    const minute = timeZone === "utc" ? date.getUTCMinutes() : date.getMinutes();
+    const second = timeZone === "utc" ? date.getUTCSeconds() : date.getSeconds();
+    return `${year}-${pad(month)}-${pad(day)}T${pad(hour)}:${pad(minute)}:${pad(second)}`;
+};
+/**
+ * Format an audit/envelope timestamp with milliseconds and a `Z` suffix.
+ */
+export const formatIsoTime = (date) => date.toISOString();
+/**
+ * Parse either a `yyyy-MM-ddTHH:mm:ss` node time or an ISO timestamp.
+ *
+ * @param value - Timestamp text.
+ * @returns The parsed date, or `undefined` when invalid.
+ */
+export const parseNodeTime = (value) => {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) ? parsed : undefined;
+};
+/**
+ * Pick the useful creation time. Some filesystems report a zero birth time;
+ * the caller then falls back to change time, and finally to modification time.
+ */
+export const creationTime = (stat) => {
+    if (Number.isFinite(stat.birthtimeMs) && stat.birthtimeMs > 0) {
+        return new Date(stat.birthtimeMs);
+    }
+    if (Number.isFinite(stat.ctimeMs) && stat.ctimeMs > 0) {
+        return new Date(stat.ctimeMs);
+    }
+    return new Date(stat.mtimeMs);
+};

package/lib/file/tree.d.ts

@@ -0,0 +1,53 @@
+import type { SessionRoot } from "../session/types.js";
+import type { TreeNode, TreeOptions, TreeSnapshot, TreeStats } from "./types.js";
+/**
+ * Build one immutable snapshot of a session root.
+ *
+ * The walk skips hidden entries unless `includeHidden`, skips excluded paths,
+ * refuses symbolic links unless `followSymlinks`, and records read failures in
+ * `stats.truncated` rather than throwing mid-tree.
+ *
+ * @param root - Session root to scan.
+ * @param options - Bounds and metadata options.
+ * @returns A snapshot whose root is the session root directory.
+ */
+export declare const buildTree: (root: SessionRoot, options?: TreeOptions) => TreeSnapshot;
+/**
+ * Cached, immutable view of one session root.
+ */
+export declare class WorkspaceTree {
+    readonly root: SessionRoot;
+    readonly options: TreeOptions;
+    private cached;
+    private index;
+    constructor(root: SessionRoot, options?: TreeOptions);
+    /**
+     * Return the cached snapshot, building it on first use.
+     */
+    snapshot(): TreeSnapshot;
+    /**
+     * Look up one node by root-relative POSIX path.
+     */
+    node(relative: string): TreeNode | undefined;
+    /**
+     * Direct children of a directory; an empty array for a file or missing path.
+     */
+    children(relative: string): readonly TreeNode[];
+    /**
+     * Current tree revision.
+     */
+    revision(): string;
+    /**
+     * Discard the cache and rebuild the whole tree.
+     *
+     * @param relative - Subtree hint accepted for future targeted rebuilds.
+     * @returns The fresh snapshot.
+     */
+    refresh(relative?: string): TreeSnapshot;
+    /**
+     * Aggregate statistics for the current snapshot.
+     */
+    stats(): TreeStats;
+    private ensure;
+    private rebuild;
+}

package/lib/file/tree.js

@@ -0,0 +1,417 @@
+/**
+ * Bounded workspace tree construction, indexing and revisioning.
+ *
+ * The tree is the read side of the filesystem domain: every file and directory
+ * becomes one immutable node, directories aggregate their descendants' bytes and
+ * lines, and a bounded walk stops with `truncated: true` instead of exhausting
+ * memory. Exclusions come from `PathSandbox` so the tree service and the tool
+ * resolver cannot disagree about what a root excludes.
+ *
+ * A snapshot is cached per `WorkspaceTree`. `refresh()` rebuilds it (a targeted
+ * subtree rebuild is an optimisation this implementation does not need yet) and
+ * the revision covers structure, annotations and the truncated flag, not
+ * timestamps or raw bytes.
+ */
+import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { digestOf } from "../semantic/canonical.js";
+import { buildDirectoryNode } from "./directory.js";
+import { fail } from "./errors.js";
+import { buildFileNode } from "./file.js";
+import { annotationFor, describeDirectory } from "./metadata.js";
+import { PathSandbox } from "./path.js";
+import { creationTime } from "./time.js";
+const DefaultMaxNodes = 20000;
+const DefaultMaxBytes = 268435456n;
+const ControlCharacters = /[\u0000-\u001f\u007f]/;
+const DriveLetter = /^[A-Za-z]:/;
+const ReadmeName = /^readme(?:\.(?:md|markdown|mdx|txt|rst))?$/i;
+const compareNames = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+const compareCandidates = (left, right) => {
+    if (left.directory !== right.directory) {
+        return left.directory ? -1 : 1;
+    }
+    return compareNames(left.name, right.name);
+};
+const errnoCode = (error) => {
+    if (typeof (error) === "object" && error !== null) {
+        const candidate = error;
+        if (typeof (candidate.code) === "string") {
+            return candidate.code;
+        }
+    }
+    return "";
+};
+const rootStat = (path) => {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        const code = errnoCode(error);
+        if (code === "ENOENT") {
+            return fail("not_found");
+        }
+        if (code === "EACCES" || code === "EPERM") {
+            return fail("permission_denied");
+        }
+        return fail("internal_error");
+    }
+};
+const normalizeMaxNodes = (value) => {
+    if (value === (void 0) || !Number.isFinite(value)) {
+        return DefaultMaxNodes;
+    }
+    return Math.max(1, Math.floor(value));
+};
+const normalizeMaxBytes = (value) => {
+    if (value === (void 0)) {
+        return DefaultMaxBytes;
+    }
+    return value < 0n ? 0n : value;
+};
+const normalizeTreePath = (input) => {
+    if (typeof (input) !== "string" || ControlCharacters.test(input)) {
+        return undefined;
+    }
+    const text = input.trim();
+    if (text.length === 0 || text === ".") {
+        return ".";
+    }
+    if (text.includes("\\") || DriveLetter.test(text) || text.startsWith("/")) {
+        return undefined;
+    }
+    const segments = [];
+    const parts = text.split("/");
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        if (part === "" || part === ".") {
+            continue;
+        }
+        if (part === "..") {
+            return undefined;
+        }
+        segments.push(part);
+    }
+    return segments.length === 0 ? "." : segments.join("/");
+};
+const freezeNode = (node) => {
+    if (node.type === "Directory") {
+        for (let index = 0; index < node.children.length; index += 1) {
+            freezeNode(node.children[index]);
+        }
+    }
+    Object.freeze(node.children);
+    return Object.freeze(node);
+};
+const indexNode = (node, index) => {
+    index.set(node.path, node);
+    if (node.type === "Directory") {
+        for (let child = 0; child < node.children.length; child += 1) {
+            indexNode(node.children[child], index);
+        }
+    }
+};
+/**
+ * Apply a directory's direct README paragraph as its purpose. The README file
+ * node already carries the deterministic first-paragraph summary, so this needs
+ * no second read. An explicit annotation always wins.
+ */
+const withReadmePurpose = (node, relative, children, options) => {
+    const annotation = annotationFor(options.annotations, relative);
+    if (annotation !== (void 0) && annotation.purpose !== (void 0)) {
+        return node;
+    }
+    let readme;
+    for (let index = 0; index < children.length; index += 1) {
+        const child = children[index];
+        if (child.type === "File" && ReadmeName.test(child.name) && child.charset !== "binary") {
+            readme = child;
+            break;
+        }
+    }
+    if (readme === (void 0) || readme.type !== "File") {
+        return node;
+    }
+    const fallback = `File ${readme.name}.`;
+    const source = readme.purpose !== "not declared" ? readme.purpose : readme.summary;
+    if (source.length === 0 || source === fallback) {
+        return node;
+    }
+    const described = describeDirectory(relative, children, annotation, source);
+    if (described.purpose === "not declared" || described.purpose === node.purpose) {
+        return node;
+    }
+    return { ...node, purpose: described.purpose };
+};
+const revisionOf = (root, options, truncated) => {
+    const annotations = [];
+    const configured = options.annotations;
+    if (configured !== (void 0)) {
+        const paths = Object.keys(configured).sort(compareNames);
+        for (let index = 0; index < paths.length; index += 1) {
+            const path = paths[index];
+            const annotation = configured[path];
+            annotations.push({
+                path,
+                description: annotation.description === (void 0) ? null : annotation.description,
+                summary: annotation.summary === (void 0) ? null : annotation.summary,
+                purpose: annotation.purpose === (void 0) ? null : annotation.purpose,
+            });
+        }
+    }
+    return digestOf({
+        version: "amp.fs.rev/1",
+        tree: root.fingerprint,
+        annotations,
+        truncated,
+    });
+};
+/**
+ * Build one immutable snapshot of a session root.
+ *
+ * The walk skips hidden entries unless `includeHidden`, skips excluded paths,
+ * refuses symbolic links unless `followSymlinks`, and records read failures in
+ * `stats.truncated` rather than throwing mid-tree.
+ *
+ * @param root - Session root to scan.
+ * @param options - Bounds and metadata options.
+ * @returns A snapshot whose root is the session root directory.
+ */
+export const buildTree = (root, options = {}) => {
+    const maxNodes = normalizeMaxNodes(options.maxNodes);
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const includeHidden = options.includeHidden === true;
+    const rootExclude = Array.isArray(root.exclude) ? root.exclude : [];
+    const scopedRoot = {
+        ...root,
+        exclude: [...rootExclude, ...(Array.isArray(options.exclude) ? options.exclude : [])],
+    };
+    const sandbox = new PathSandbox([scopedRoot], { followSymlinks: options.followSymlinks === true });
+    const state = {
+        nodes: 1,
+        files: 0n,
+        directories: 1n,
+        lines: 0n,
+        bytes: 0n,
+        truncated: false,
+    };
+    const walkDirectory = (relative, absolute, stat, ancestry) => {
+        let names;
+        try {
+            names = readdirSync(absolute);
+        }
+        catch {
+            state.truncated = true;
+            return undefined;
+        }
+        const candidates = [];
+        for (let index = 0; index < names.length; index += 1) {
+            const name = names[index];
+            if (!includeHidden && name.startsWith(".")) {
+                continue;
+            }
+            const childRelative = relative === "." ? name : `${relative}/${name}`;
+            if (sandbox.isExcluded(scopedRoot, childRelative)) {
+                continue;
+            }
+            const childAbsolute = join(absolute, name);
+            let linkStat;
+            try {
+                linkStat = lstatSync(childAbsolute);
+            }
+            catch {
+                state.truncated = true;
+                continue;
+            }
+            let entryStat = linkStat;
+            let realPath;
+            const symbolic = linkStat.isSymbolicLink();
+            if (symbolic) {
+                if (options.followSymlinks !== true) {
+                    continue;
+                }
+                try {
+                    entryStat = statSync(childAbsolute);
+                    realPath = realpathSync(childAbsolute);
+                }
+                catch {
+                    state.truncated = true;
+                    continue;
+                }
+                if (!sandbox.contains(root.path, realPath)) {
+                    continue;
+                }
+            }
+            if (!entryStat.isDirectory() && !entryStat.isFile()) {
+                continue;
+            }
+            if (entryStat.isDirectory() && options.followSymlinks === true) {
+                let directoryReal;
+                if (realPath === (void 0)) {
+                    try {
+                        directoryReal = realpathSync(childAbsolute);
+                    }
+                    catch {
+                        state.truncated = true;
+                        continue;
+                    }
+                }
+                else {
+                    directoryReal = realPath;
+                }
+                if (!sandbox.contains(root.path, directoryReal)) {
+                    continue;
+                }
+                realPath = directoryReal;
+            }
+            candidates.push({ name, relative: childRelative, absolute: childAbsolute, stat: entryStat, directory: entryStat.isDirectory(), real: realPath });
+        }
+        candidates.sort(compareCandidates);
+        const children = [];
+        for (let index = 0; index < candidates.length; index += 1) {
+            const candidate = candidates[index];
+            if (state.nodes + 1 > maxNodes) {
+                state.truncated = true;
+                break;
+            }
+            if (candidate.directory) {
+                if (candidate.real !== (void 0) && ancestry.has(candidate.real)) {
+                    continue;
+                }
+                state.nodes += 1;
+                state.directories += 1n;
+                const childAncestry = candidate.real === (void 0) ? ancestry : new Set([...ancestry, candidate.real]);
+                const child = walkDirectory(candidate.relative, candidate.absolute, candidate.stat, childAncestry);
+                if (child === (void 0)) {
+                    state.nodes -= 1;
+                    state.directories -= 1n;
+                    continue;
+                }
+                children.push(child);
+                continue;
+            }
+            const size = BigInt(candidate.stat.size);
+            if (state.bytes + size > maxBytes) {
+                state.truncated = true;
+                continue;
+            }
+            try {
+                const child = buildFileNode(root, candidate.relative, options);
+                state.nodes += 1;
+                state.files += 1n;
+                state.bytes += child.bytes;
+                state.lines += child.lines;
+                children.push(child);
+            }
+            catch {
+                state.truncated = true;
+            }
+        }
+        const built = buildDirectoryNode(relative, children, options, creationTime(stat), new Date(stat.mtimeMs));
+        return withReadmePurpose(built, relative, children, options);
+    };
+    const stat = rootStat(root.path);
+    if (!stat.isDirectory()) {
+        return fail("not_directory");
+    }
+    let rootReal = root.path;
+    try {
+        rootReal = realpathSync(root.path);
+    }
+    catch {
+        rootReal = root.path;
+    }
+    const rootNode = walkDirectory(".", root.path, stat, new Set([rootReal])) ??
+        buildDirectoryNode(".", [], options, creationTime(stat), new Date(stat.mtimeMs));
+    const frozen = freezeNode(rootNode);
+    const stats = Object.freeze({
+        files: state.files,
+        directories: state.directories,
+        lines: state.lines,
+        bytes: state.bytes,
+        truncated: state.truncated,
+    });
+    return Object.freeze({
+        root: frozen,
+        revision: revisionOf(frozen, options, state.truncated),
+        stats,
+    });
+};
+/**
+ * Cached, immutable view of one session root.
+ */
+export class WorkspaceTree {
+    root;
+    options;
+    cached;
+    index;
+    constructor(root, options = {}) {
+        this.root = { ...root, exclude: Array.isArray(root.exclude) ? [...root.exclude] : [] };
+        this.options = { ...options };
+    }
+    /**
+     * Return the cached snapshot, building it on first use.
+     */
+    snapshot() {
+        return this.ensure();
+    }
+    /**
+     * Look up one node by root-relative POSIX path.
+     */
+    node(relative) {
+        this.ensure();
+        const normalized = normalizeTreePath(relative);
+        if (normalized === (void 0)) {
+            return undefined;
+        }
+        const index = this.index;
+        return index === (void 0) ? undefined : index.get(normalized);
+    }
+    /**
+     * Direct children of a directory; an empty array for a file or missing path.
+     */
+    children(relative) {
+        const found = this.node(relative);
+        if (found === (void 0) || found.type === "File") {
+            return [];
+        }
+        return found.children;
+    }
+    /**
+     * Current tree revision.
+     */
+    revision() {
+        return this.ensure().revision;
+    }
+    /**
+     * Discard the cache and rebuild the whole tree.
+     *
+     * @param relative - Subtree hint accepted for future targeted rebuilds.
+     * @returns The fresh snapshot.
+     */
+    refresh(relative) {
+        void relative;
+        return this.rebuild();
+    }
+    /**
+     * Aggregate statistics for the current snapshot.
+     */
+    stats() {
+        return this.ensure().stats;
+    }
+    ensure() {
+        const cached = this.cached;
+        if (cached !== (void 0)) {
+            return cached;
+        }
+        return this.rebuild();
+    }
+    rebuild() {
+        const snapshot = buildTree(this.root, this.options);
+        this.cached = snapshot;
+        const index = new Map();
+        indexNode(snapshot.root, index);
+        this.index = index;
+        return snapshot;
+    }
+}