rea-agents 0.3.0 → 0.5.0

package/dist/native/parsers/otool.js

@@ -0,0 +1,193 @@
+/** Parse stable fields from `otool -l`, preserving unknown command fields. */
+export const parseOtoolLoadCommands = (output) => {
+    const headerTokens = parseHeaderTokens(output);
+    const state = createLoadCommandState(headerTokens);
+    for (const block of output.split(/(?=Load command \d+)/u))
+        parseLoadCommand(block, state);
+    return {
+        fileType: headerTokens?.[4] ?? null,
+        flags: [...state.flags].sort(),
+        uuid: state.uuid,
+        commands: state.commands,
+        segments: state.segments,
+        dependencies: state.dependencies,
+        entrypoints: state.entrypoints,
+        builds: state.builds,
+    };
+};
+const parseHeaderTokens = (output) => output
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .find((line) => /^0x[a-fA-F0-9]+\s/u.test(line))
+    ?.split(/\s+/u);
+const createLoadCommandState = (headerTokens) => ({
+    commands: [],
+    segments: [],
+    dependencies: [],
+    entrypoints: [],
+    builds: [],
+    uuid: null,
+    flags: new Set(headerTokens?.slice(7) ?? []),
+});
+const parseLoadCommand = (block, state) => {
+    const indexText = /^Load command (\d+)/u.exec(block)?.[1];
+    if (indexText === undefined)
+        return;
+    const header = block.split(/\n\s*Section\n/u)[0] ?? block;
+    const fields = parseFields(header);
+    const kind = stringField(fields, "cmd") ?? "unknown";
+    state.commands.push({
+        index: Number.parseInt(indexText, 10),
+        kind,
+        file_offset: null,
+        fields,
+    });
+    collectUuid(kind, fields, state);
+    collectEntrypoint(kind, fields, state);
+    collectBuild(kind, block, fields, state);
+    collectDependency(kind, fields, state);
+    collectSegment(kind, block, fields, state);
+    collectFlags(fields, state.flags);
+};
+const collectUuid = (kind, fields, state) => {
+    if (kind === "LC_UUID")
+        state.uuid = stringField(fields, "uuid") ?? state.uuid;
+};
+const collectEntrypoint = (kind, fields, state) => {
+    if (kind !== "LC_MAIN")
+        return;
+    const entry = numberField(fields, "entryoff");
+    if (entry !== null)
+        state.entrypoints.push({ file_offset: entry });
+};
+const collectBuild = (kind, block, fields, state) => {
+    if (kind !== "LC_BUILD_VERSION")
+        return;
+    state.builds.push({
+        platform: stringField(fields, "platform"),
+        minimum_os: stringField(fields, "minos"),
+        sdk: stringField(fields, "sdk"),
+        tools: parseBuildTools(block),
+    });
+};
+const collectDependency = (kind, fields, state) => {
+    if (!kind.startsWith("LC_LOAD_") && kind !== "LC_ID_DYLIB")
+        return;
+    state.dependencies.push({
+        path: stripOffsetSuffix(stringField(fields, "name")),
+        kind,
+        current_version: stringField(fields, "current version"),
+        compatibility_version: stringField(fields, "compatibility version"),
+    });
+};
+const collectSegment = (kind, block, fields, state) => {
+    if (kind === "LC_SEGMENT" || kind === "LC_SEGMENT_64")
+        state.segments.push(parseSegment(block, fields));
+};
+const collectFlags = (fields, flags) => {
+    const rawFlags = stringField(fields, "flags");
+    if (rawFlags === null)
+        return;
+    for (const flag of rawFlags.split(/\s+/u))
+        if (flag.length > 0)
+            flags.add(flag);
+};
+const parseFields = (block) => {
+    const fields = {};
+    for (const rawLine of block.split(/\r?\n/u).slice(1)) {
+        const line = rawLine.trim();
+        const match = /^(\S+(?:\s+version)?)\s+(.+)$/u.exec(line);
+        if (match?.[1] === undefined || match[2] === undefined)
+            continue;
+        const value = match[2].trim();
+        fields[match[1]] = numeric(value) ?? value;
+    }
+    return fields;
+};
+const parseSegment = (block, fields) => ({
+    name: stringField(fields, "segname") ?? "unknown",
+    vm_address: hexField(fields, "vmaddr"),
+    vm_size: numberField(fields, "vmsize"),
+    file_offset: numberField(fields, "fileoff"),
+    file_size: numberField(fields, "filesize"),
+    maximum_permissions: permissions(stringField(fields, "maxprot")),
+    initial_permissions: permissions(stringField(fields, "initprot")),
+    sections: parseSections(block),
+});
+const parseSections = (block) => block
+    .split(/(?=\n\s*Section\n)/u)
+    .slice(1)
+    .map((sectionBlock) => {
+    const fields = parseFields(`Section${sectionBlock}`);
+    return {
+        segment: stringField(fields, "segname") ?? "unknown",
+        name: stringField(fields, "sectname") ?? "unknown",
+        address: hexField(fields, "addr"),
+        size: numberField(fields, "size"),
+        file_offset: numberField(fields, "offset"),
+        alignment: sectionAlignment(numberField(fields, "align")),
+        flags: (stringField(fields, "flags") ?? "")
+            .split(/\s+/u)
+            .filter((flag) => flag.length > 0),
+    };
+});
+const parseBuildTools = (block) => {
+    const tools = [];
+    const lines = block.split(/\r?\n/u).map((line) => line.trim());
+    for (let index = 0; index < lines.length - 1; index += 1) {
+        const tool = /^tool\s+(.+)$/u.exec(lines[index] ?? "")?.[1];
+        const version = /^version\s+(.+)$/u.exec(lines[index + 1] ?? "")?.[1];
+        if (tool !== undefined && version !== undefined)
+            tools.push({ name: tool, version });
+    }
+    return tools;
+};
+const permissions = (raw) => {
+    if (raw === null)
+        return { read: null, write: null, execute: null, raw: null };
+    const numericValue = numeric(raw);
+    if (numericValue !== null)
+        return {
+            read: (numericValue & 4) !== 0,
+            write: (numericValue & 2) !== 0,
+            execute: (numericValue & 1) !== 0,
+            raw,
+        };
+    if (/^[r-][w-][x-]$/u.test(raw))
+        return {
+            read: raw[0] === "r",
+            write: raw[1] === "w",
+            execute: raw[2] === "x",
+            raw,
+        };
+    return { read: null, write: null, execute: null, raw };
+};
+const numeric = (value) => {
+    const token = value.split(/\s+/u)[0];
+    if (token === undefined || !/^(?:0x[a-fA-F0-9]+|\d+)$/u.test(token))
+        return null;
+    const parsed = Number.parseInt(token, token.startsWith("0x") ? 16 : 10);
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+};
+const stringField = (fields, name) => {
+    const value = fields[name];
+    return typeof value === "string"
+        ? value
+        : value === undefined || value === null
+            ? null
+            : String(value);
+};
+const numberField = (fields, name) => {
+    const value = fields[name];
+    return typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? numeric(value)
+            : null;
+};
+const hexField = (fields, name) => {
+    const value = numberField(fields, name);
+    return value === null ? null : `0x${value.toString(16)}`;
+};
+const stripOffsetSuffix = (value) => value?.replace(/\s+\(offset\s+\d+\)$/u, "") ?? "unknown";
+const sectionAlignment = (exponent) => exponent === null || exponent > 52 ? null : 2 ** exponent;

package/dist/native/parsers/plist.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+const plistObject = z.record(z.string(), z.unknown());
+/** Parse plutil JSON output and project stable bundle metadata. */
+export const parsePlistJson = (output) => {
+    const value = JSON.parse(output);
+    const object = plistObject.safeParse(value);
+    const field = (name) => {
+        if (!object.success)
+            return null;
+        const candidate = object.data[name];
+        return typeof candidate === "string" ? candidate : null;
+    };
+    return {
+        value,
+        bundle: {
+            identifier: field("CFBundleIdentifier"),
+            executable: field("CFBundleExecutable"),
+            name: field("CFBundleName"),
+            version: field("CFBundleVersion"),
+            short_version: field("CFBundleShortVersionString"),
+        },
+    };
+};

package/dist/reference/ReferenceSourceReader.js

@@ -0,0 +1,73 @@
+import { err, ok } from "../domain/result.js";
+import { traverseDirectory } from "./ReferenceSourceReaderEntries.js";
+import { compareNames } from "./ReferenceSourceReaderPaths.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+import { isAborted, noFollowOpenSupported, prepareRoot, } from "./ReferenceSourceReaderValidate.js";
+const DEFAULT_LIMITS = {
+    maxBytes: 16 * 1024 * 1024,
+    maxEntries: 10_000,
+    maxDepth: 32,
+    maxPathBytes: 4_096,
+};
+const PATH_RACE_LIMITATION = "Path identity is revalidated around operations; Node lacks portable descriptor-relative openat traversal, so a syscall-boundary pathname race remains.";
+/** Read a bounded source tree without intentionally following symbolic links. */
+export const readReferenceSource = async (root, limits = DEFAULT_LIMITS, options = {}) => {
+    if (!noFollowOpenSupported())
+        return err({
+            tag: "reference-source-reader",
+            code: "unsupported",
+            message: "Safe no-follow file opens are unavailable",
+        });
+    const prepared = await prepareRoot(root, limits, options.signal);
+    if (!prepared.ok)
+        return prepared;
+    const { canonicalRoot, rootIdentity } = prepared.value;
+    const state = {
+        root: canonicalRoot,
+        rootIdentity,
+        limits,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.shouldExclude === undefined
+            ? {}
+            : { shouldExclude: options.shouldExclude }),
+        entries: [],
+        pending: [{ path: canonicalRoot, depth: 0 }],
+        bytesRead: 0,
+        filesSeen: 0,
+        truncated: false,
+        stopped: false,
+    };
+    const traversal = await traverse(state);
+    if (!traversal.ok)
+        return traversal;
+    state.entries.sort((left, right) => compareNames(left.path, right.path));
+    return ok({
+        root: canonicalRoot,
+        entries: state.entries,
+        bytesRead: state.bytesRead,
+        truncated: state.truncated,
+        limitations: [
+            PATH_RACE_LIMITATION,
+            ...(state.stopped
+                ? ["Traversal stopped because the entry limit was reached."]
+                : []),
+        ],
+    });
+};
+const traverse = async (state) => {
+    while (state.pending.length > 0 && !state.stopped) {
+        if (isAborted(state.signal))
+            return err({
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            });
+        const current = state.pending.pop();
+        if (current === undefined)
+            break;
+        const result = await traverseDirectory(state, current);
+        if (!result.ok)
+            return result;
+    }
+    return ok(undefined);
+};

package/dist/reference/ReferenceSourceReaderEntries.js

@@ -0,0 +1,206 @@
+import { readdir, readlink, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { entryFailure, safeSize } from "./ReferenceSourceReaderErrors.js";
+import { compareNames, pathFromRoot, withinRoot, } from "./ReferenceSourceReaderPaths.js";
+import { readStableFile } from "./ReferenceSourceReaderFile.js";
+import { isAborted, sameFile, validateDirectory, bigLstat, } from "./ReferenceSourceReaderValidate.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+export const traverseDirectory = async (state, current) => {
+    const before = await validateDirectory(state.root, state.rootIdentity, current.path);
+    if (!before.ok) {
+        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", before.code, before.message));
+        return { ok: true, value: undefined };
+    }
+    const names = await readDirectoryNames(current.path);
+    if (!names.ok) {
+        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "io", names.message));
+        return { ok: true, value: undefined };
+    }
+    if (isAborted(state.signal))
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            },
+        };
+    const after = await validateDirectory(state.root, state.rootIdentity, current.path);
+    if (!after.ok || !sameFile(before.stats, after.stats)) {
+        state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "changed", "Directory changed while it was read"));
+        return { ok: true, value: undefined };
+    }
+    const directories = [];
+    for (const name of names.value) {
+        const result = await processEntry(state, current, name, directories);
+        if (!result.ok)
+            return result;
+        if (state.stopped)
+            break;
+    }
+    directories.reverse();
+    state.pending.push(...directories);
+    return { ok: true, value: undefined };
+};
+const readDirectoryNames = async (path) => {
+    try {
+        return { ok: true, value: (await readdir(path)).sort(compareNames) };
+    }
+    catch {
+        return { ok: false, message: "Directory could not be read" };
+    }
+};
+const readMetadata = async (path) => {
+    try {
+        return { ok: true, value: await bigLstat(path) };
+    }
+    catch {
+        return { ok: false, message: "Entry metadata could not be read" };
+    }
+};
+const processEntry = async (state, current, name, directories) => {
+    if (isAborted(state.signal))
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            },
+        };
+    const absolute = join(current.path, name);
+    const path = pathFromRoot(state.root, absolute);
+    const excluded = applyExclusion(state.shouldExclude, path);
+    if (!excluded.ok)
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "io",
+                message: "Reference source exclusion check failed",
+            },
+        };
+    if (excluded.value)
+        return { ok: true, value: undefined };
+    if (!reserveEntry(state))
+        return { ok: true, value: undefined };
+    if (Buffer.byteLength(path) > state.limits.maxPathBytes) {
+        state.entries.push(entryFailure(path, "unknown", "limit", "Path exceeds maxPathBytes"));
+        state.truncated = true;
+        return { ok: true, value: undefined };
+    }
+    const metadata = await readMetadata(absolute);
+    if (!metadata.ok) {
+        state.entries.push(entryFailure(path, "unknown", "io", metadata.message));
+        return { ok: true, value: undefined };
+    }
+    if (isAborted(state.signal))
+        return {
+            ok: false,
+            error: {
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            },
+        };
+    if (metadata.value.isSymbolicLink())
+        state.entries.push(await describeSymlink(state.root, absolute, path));
+    else if (metadata.value.isDirectory()) {
+        if (current.depth < state.limits.maxDepth) {
+            state.entries.push({ status: "read", kind: "directory", path });
+            directories.push({ path: absolute, depth: current.depth + 1 });
+        }
+        else {
+            state.entries.push(entryFailure(path, "directory", "limit", "Directory exceeds maxDepth"));
+            state.truncated = true;
+        }
+    }
+    else if (!metadata.value.isFile())
+        state.entries.push(entryFailure(path, "other", "unsupported", "Entry is not a regular file", safeSize(metadata.value.size)));
+    else
+        await processFileEntry(state, absolute, path, metadata.value);
+    return { ok: true, value: undefined };
+};
+const processFileEntry = async (state, absolute, path, metadata) => {
+    const remaining = state.limits.maxBytes - state.bytesRead;
+    if (metadata.size > BigInt(remaining)) {
+        state.entries.push(entryFailure(path, "file", "limit", "File exceeds remaining maxBytes", safeSize(metadata.size)));
+        state.truncated = true;
+        return;
+    }
+    const result = await readStableFile({
+        root: state.root,
+        rootIdentity: state.rootIdentity,
+        absolute,
+        path,
+        expected: metadata,
+        remaining,
+        ...(state.signal === undefined ? {} : { signal: state.signal }),
+    });
+    if (result.status === "read" && result.kind === "file")
+        state.bytesRead += result.bytes.byteLength;
+    else if (result.status === "failed" && result.code === "limit")
+        state.truncated = true;
+    state.entries.push(result);
+};
+const describeSymlink = async (root, absolute, path) => {
+    try {
+        const rawTarget = await readlink(absolute);
+        const lexicalTarget = resolve(dirname(absolute), rawTarget);
+        if (!withinRoot(root, lexicalTarget))
+            return {
+                status: "read",
+                kind: "symlink",
+                path,
+                target: "<outside-root>",
+                targetState: "external",
+            };
+        try {
+            const canonicalTarget = await realpath(lexicalTarget);
+            return withinRoot(root, canonicalTarget)
+                ? {
+                    status: "read",
+                    kind: "symlink",
+                    path,
+                    target: pathFromRoot(root, canonicalTarget),
+                    targetState: "internal",
+                }
+                : {
+                    status: "read",
+                    kind: "symlink",
+                    path,
+                    target: "<outside-root>",
+                    targetState: "external",
+                };
+        }
+        catch {
+            return {
+                status: "read",
+                kind: "symlink",
+                path,
+                target: pathFromRoot(root, lexicalTarget),
+                targetState: "missing",
+            };
+        }
+    }
+    catch {
+        return entryFailure(path, "symlink", "io", "Symbolic link target could not be read");
+    }
+};
+const applyExclusion = (shouldExclude, path) => {
+    try {
+        return { ok: true, value: shouldExclude?.(path) === true };
+    }
+    catch {
+        return { ok: false };
+    }
+};
+const reserveEntry = (state) => {
+    if (state.filesSeen < state.limits.maxEntries) {
+        state.filesSeen += 1;
+        return true;
+    }
+    state.truncated = true;
+    state.stopped = true;
+    return false;
+};

package/dist/reference/ReferenceSourceReaderErrors.js

@@ -0,0 +1,19 @@
+import {} from "./ReferenceSourceReaderTypes.js";
+export const failure = (code, message) => ({
+    tag: "reference-source-reader",
+    code,
+    message,
+});
+export const cancelled = () => failure("cancelled", "Reference source traversal cancelled");
+export const safeSize = (size) => {
+    const value = Number(size);
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+};
+export const entryFailure = (...[path, kind, code, message, size]) => ({
+    status: "failed",
+    kind,
+    path,
+    code,
+    message,
+    ...(size === undefined ? {} : { size }),
+});

package/dist/reference/ReferenceSourceReaderFile.js

@@ -0,0 +1,119 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { dirname } from "node:path";
+import { entryFailure, safeSize } from "./ReferenceSourceReaderErrors.js";
+import { isAborted, sameFile, validateDirectory, } from "./ReferenceSourceReaderValidate.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+const READ_CHUNK_BYTES = 64 * 1024;
+const prepareFileRead = async (request) => {
+    const { root, rootIdentity, absolute, path, expected, signal } = request;
+    const parentBefore = await validateDirectory(root, rootIdentity, dirname(absolute));
+    if (!parentBefore.ok)
+        return {
+            status: "failed",
+            entry: entryFailure(path, "file", parentBefore.code, parentBefore.message, safeSize(expected.size)),
+        };
+    const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    if (isAborted(signal)) {
+        await handle.close().catch(() => undefined);
+        return {
+            status: "failed",
+            entry: entryFailure(path, "file", "cancelled", "File read cancelled", safeSize(expected.size)),
+        };
+    }
+    const before = await handle.stat({ bigint: true });
+    if (!sameFile(expected, before)) {
+        await handle.close().catch(() => undefined);
+        return {
+            status: "failed",
+            entry: entryFailure(path, "file", "changed", "File changed before it was read", safeSize(before.size)),
+        };
+    }
+    return { status: "ready", handle, before, parentBefore };
+};
+const readFileContents = async (request) => {
+    const { handle, path, remaining, signal } = request;
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        if (isAborted(signal))
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "cancelled", "File read cancelled", total),
+            };
+        const capacity = Math.min(READ_CHUNK_BYTES, remaining + 1 - total);
+        if (capacity <= 0)
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "limit", "File exceeds remaining maxBytes", total),
+            };
+        const chunk = Buffer.allocUnsafe(capacity);
+        const read = await handle.read(chunk, 0, capacity, null);
+        if (isAborted(signal))
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "cancelled", "File read cancelled", total),
+            };
+        if (read.bytesRead === 0)
+            break;
+        total += read.bytesRead;
+        if (total > remaining)
+            return {
+                status: "failed",
+                entry: entryFailure(path, "file", "limit", "File exceeds remaining maxBytes", total),
+            };
+        chunks.push(chunk.subarray(0, read.bytesRead));
+    }
+    return { status: "ok", chunks, total };
+};
+const finalizeFileRead = async (request) => {
+    const { root, rootIdentity, absolute, path, handle, before, parentBefore, chunks, total, } = request;
+    const after = await handle.stat({ bigint: true });
+    const parentAfter = await validateDirectory(root, rootIdentity, dirname(absolute));
+    if (!parentAfter.ok || !sameFile(parentBefore.stats, parentAfter.stats))
+        return entryFailure(path, "file", "changed", "Parent directory changed while file was read", total);
+    if (!sameFile(before, after) || BigInt(total) !== after.size)
+        return entryFailure(path, "file", "changed", "File changed while it was read", total);
+    return {
+        status: "read",
+        kind: "file",
+        path,
+        bytes: Buffer.concat(chunks, total),
+        size: total,
+    };
+};
+export const readStableFile = async (request) => {
+    const { root, rootIdentity, absolute, path, expected, remaining, signal } = request;
+    let handle;
+    try {
+        const prepared = await prepareFileRead(request);
+        if (prepared.status === "failed")
+            return prepared.entry;
+        handle = prepared.handle;
+        const contents = await readFileContents({
+            handle,
+            path,
+            remaining,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (contents.status === "failed")
+            return contents.entry;
+        return await finalizeFileRead({
+            root,
+            rootIdentity,
+            absolute,
+            path,
+            handle,
+            before: prepared.before,
+            parentBefore: prepared.parentBefore,
+            chunks: contents.chunks,
+            total: contents.total,
+        });
+    }
+    catch {
+        return entryFailure(path, "file", isAborted(signal) ? "cancelled" : "io", "File could not be read safely", safeSize(expected.size));
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};

package/dist/reference/ReferenceSourceReaderPaths.js

@@ -0,0 +1,23 @@
+import { isAbsolute, relative, sep } from "node:path";
+export const withinRoot = (root, path) => {
+    const value = relative(root, path);
+    return (value === "" ||
+        (value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value)));
+};
+export const pathFromRoot = (root, path) => {
+    const value = relative(root, path);
+    return withinRoot(root, path)
+        ? value.split(sep).join("/") || "."
+        : "<outside-root>";
+};
+export const compareNames = (left, right) => {
+    const leftPoints = [...left].map((value) => value.codePointAt(0) ?? 0);
+    const rightPoints = [...right].map((value) => value.codePointAt(0) ?? 0);
+    const length = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = (leftPoints[index] ?? 0) - (rightPoints[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return leftPoints.length - rightPoints.length;
+};

package/dist/reference/ReferenceSourceReaderTypes.js

@@ -0,0 +1,2 @@
+import {} from "node:fs";
+import {} from "../domain/result.js";