@armadra/agent 0.0.0-stage → 0.3.0

package/dist/tools/ignore.js

@@ -0,0 +1,174 @@
+/**
+ * `.gitignore` / `.ignore` 解析与匹配，以及尊重它们的目录遍历（设计 §5.2 grep / glob）。[B3]
+ *
+ * 规则语义（gitignore 子集）：空行与 `#` 注释；`\#`、`\!`、`\ ` 转义；`!` 取反；末尾 `/` 只匹配目录；
+ * 中间或开头含 `/` 的模式锚定在 ignore 文件所在目录，否则匹配任意深度的名字；`**` 的三种位置；
+ * 同一路径**最后**命中的规则生效；被忽略的目录不再下钻（其下的取反规则无效，与 git 一致）。
+ * 嵌套：每个目录的 `.gitignore` 先、`.ignore` 后（后者优先）；从搜索根向上到仓库根（含 `.git` 的
+ * 目录）的祖先 ignore 文件也生效。`.git` 目录永远跳过；目录符号链接不跟随。
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { toPosix } from "./paths.js";
+import { globBody } from "./glob.js";
+export const IGNORE_FILES = [".gitignore", ".ignore"];
+function trimTrailingSpaces(line) {
+    let end = line.length;
+    while (end > 0 && line[end - 1] === " " && line[end - 2] !== "\\")
+        end--;
+    return line.slice(0, end);
+}
+/** 解析一行；空 / 注释返回 undefined。 */
+export function parseIgnoreLine(rawLine, base, nocase = false) {
+    let line = trimTrailingSpaces(rawLine.replace(/\r$/, ""));
+    if (line === "" || line.startsWith("#"))
+        return undefined;
+    let negate = false;
+    if (line.startsWith("!")) {
+        negate = true;
+        line = line.slice(1);
+    }
+    else if (line.startsWith("\\!") || line.startsWith("\\#")) {
+        line = line.slice(1);
+    }
+    let dirOnly = false;
+    if (line.endsWith("/") && !line.endsWith("\\/")) {
+        dirOnly = true;
+        line = line.replace(/\/+$/, "");
+    }
+    if (line === "")
+        return undefined;
+    const anchored = line.includes("/");
+    if (line.startsWith("/"))
+        line = line.slice(1);
+    const body = globBody(line, { braces: false });
+    const prefix = anchored || line.startsWith("**/") ? "" : "(?:[^/]*/)*";
+    return {
+        negate,
+        dirOnly,
+        regex: new RegExp(`^${prefix}${body}$`, nocase ? "i" : ""),
+        base: base.replace(/\/+$/, ""),
+        source: rawLine,
+    };
+}
+export function parseIgnoreFile(content, base, nocase = false) {
+    const rules = [];
+    for (const line of content.split("\n")) {
+        const rule = parseIgnoreLine(line, base, nocase);
+        if (rule)
+            rules.push(rule);
+    }
+    return rules;
+}
+/** `absPosix` 相对 `base` 的路径；不在其下返回 undefined。 */
+function relativeTo(base, absPosix) {
+    if (base === "")
+        return absPosix.replace(/^\/+/, "");
+    if (absPosix === base)
+        return "";
+    const prefix = base.endsWith("/") ? base : `${base}/`;
+    return absPosix.startsWith(prefix) ? absPosix.slice(prefix.length) : undefined;
+}
+/** 按规则顺序求值，最后命中者生效。 */
+export function isIgnoredBy(rules, absPath, isDir) {
+    const absPosix = toPosix(absPath);
+    let ignored = false;
+    for (const rule of rules) {
+        if (rule.dirOnly && !isDir)
+            continue;
+        const rel = relativeTo(rule.base, absPosix);
+        if (rel === undefined || rel === "")
+            continue;
+        if (rule.regex.test(rel))
+            ignored = !rule.negate;
+    }
+    return ignored;
+}
+async function readRules(dir, nocase) {
+    const rules = [];
+    for (const name of IGNORE_FILES) {
+        try {
+            const text = await readFile(join(dir, name), "utf8");
+            rules.push(...parseIgnoreFile(text, toPosix(dir), nocase));
+        }
+        catch {
+            // 不存在
+        }
+    }
+    return rules;
+}
+/** 搜索根之上、直到仓库根（含 `.git` 的目录）的祖先 ignore 规则，外层在前。 */
+export async function ancestorRules(root, nocase = false) {
+    const chain = [];
+    let dir = root;
+    let foundRepo = await exists(join(root, ".git"));
+    while (!foundRepo) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            return [];
+        dir = parent;
+        chain.unshift(dir);
+        foundRepo = await exists(join(dir, ".git"));
+    }
+    const rules = [];
+    for (const d of chain)
+        rules.push(...(await readRules(d, nocase)));
+    return rules;
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 深度优先、目录内按名字排序的遍历；产出文件与目录（目录先于其内容）。 */
+export async function* walk(root, options = {}) {
+    const respect = options.respectIgnore ?? true;
+    const nocase = options.nocase ?? process.platform === "win32";
+    const base = respect ? await ancestorRules(root, nocase) : [];
+    yield* walkDir(root, "", base, respect, nocase, options.signal);
+}
+async function* walkDir(dir, rel, inherited, respect, nocase, signal) {
+    if (signal?.aborted)
+        return;
+    const rules = respect ? [...inherited, ...(await readRules(dir, nocase))] : inherited;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        if (signal?.aborted)
+            return;
+        if (entry.name === ".git")
+            continue;
+        const abs = join(dir, entry.name);
+        const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+        let isDir = entry.isDirectory();
+        if (entry.isSymbolicLink()) {
+            // 链接到文件的照常产出；链接到目录的不跟随（避免环），作为普通条目跳过。
+            try {
+                if ((await stat(abs)).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            isDir = false;
+        }
+        else if (!isDir && !entry.isFile()) {
+            continue;
+        }
+        if (respect && isIgnoredBy(rules, abs, isDir))
+            continue;
+        yield { abs, rel: childRel, isDir };
+        if (isDir)
+            yield* walkDir(abs, childRel, rules, respect, nocase, signal);
+    }
+}

package/dist/tools/image-file.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 图片文件（`read` 工具、`ama -p --image`、界面里的 `@图片路径` 共用）：MIME 检测、尺寸、大小上限。
+ *
+ * - MIME 以文件头为准（PNG / JPEG / GIF / WebP），文件头认不出时退回扩展名；
+ * - 单张上限 5 MB（各家图片上限里最小的 Anthropic）；
+ * - 不解码像素，只读文件头取尺寸。
+ */
+import type { ImageBlock } from "../ai/types.js";
+export declare const MAX_IMAGE_BYTES: number;
+export declare const IMAGE_EXTENSIONS: Readonly<Record<string, string>>;
+/** 按扩展名（不分大小写）；不是图片返回 undefined。 */
+export declare function imageMimeFromPath(path: string): string | undefined;
+/** 按文件头识别；认不出返回 undefined。 */
+export declare function sniffImageMime(buf: Buffer): string | undefined;
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/** 只读文件头取尺寸；不认识返回 undefined。 */
+export declare function imageSize(buf: Buffer, mimeType: string): ImageSize | undefined;
+export interface LoadedImage {
+    block: ImageBlock;
+    path: string;
+    mimeType: string;
+    bytes: number;
+    size?: ImageSize;
+}
+/**
+ * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
+ */
+export declare function loadImageFile(path: string): Promise<LoadedImage>;

package/dist/tools/image-file.js

@@ -0,0 +1,114 @@
+/**
+ * 图片文件（`read` 工具、`ama -p --image`、界面里的 `@图片路径` 共用）：MIME 检测、尺寸、大小上限。
+ *
+ * - MIME 以文件头为准（PNG / JPEG / GIF / WebP），文件头认不出时退回扩展名；
+ * - 单张上限 5 MB（各家图片上限里最小的 Anthropic）；
+ * - 不解码像素，只读文件头取尺寸。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { extname } from "node:path";
+import { AmaError } from "../errors.js";
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+export const IMAGE_EXTENSIONS = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+/** 按扩展名（不分大小写）；不是图片返回 undefined。 */
+export function imageMimeFromPath(path) {
+    return IMAGE_EXTENSIONS[extname(path).toLowerCase()];
+}
+/** 按文件头识别；认不出返回 undefined。 */
+export function sniffImageMime(buf) {
+    if (buf.length >= 8 && buf.readUInt32BE(0) === 0x89504e47 && buf.readUInt32BE(4) === 0x0d0a1a0a)
+        return "image/png";
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return "image/jpeg";
+    if (buf.length >= 6 && /^GIF8[79]a$/.test(buf.toString("ascii", 0, 6)))
+        return "image/gif";
+    if (buf.length >= 12 &&
+        buf.toString("ascii", 0, 4) === "RIFF" &&
+        buf.toString("ascii", 8, 12) === "WEBP")
+        return "image/webp";
+    return undefined;
+}
+/** 只读文件头取尺寸；不认识返回 undefined。 */
+export function imageSize(buf, mimeType) {
+    try {
+        if (mimeType === "image/png" && buf.length >= 24) {
+            return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+        }
+        if (mimeType === "image/gif" && buf.length >= 10) {
+            return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+        }
+        if (mimeType === "image/jpeg")
+            return jpegSize(buf);
+        if (mimeType === "image/webp")
+            return webpSize(buf);
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function jpegSize(buf) {
+    let i = 2;
+    while (i + 9 < buf.length) {
+        if (buf[i] !== 0xff) {
+            i++;
+            continue;
+        }
+        const marker = buf[i + 1] ?? 0;
+        const isSof = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (isSof)
+            return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) };
+        i += 2 + buf.readUInt16BE(i + 2);
+    }
+    return undefined;
+}
+function webpSize(buf) {
+    if (buf.length < 30 || buf.toString("ascii", 0, 4) !== "RIFF")
+        return undefined;
+    const chunk = buf.toString("ascii", 12, 16);
+    if (chunk === "VP8 ") {
+        return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+    }
+    if (chunk === "VP8L") {
+        const b = buf.readUInt32LE(21);
+        return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1 };
+    }
+    if (chunk === "VP8X") {
+        return { width: buf.readUIntLE(24, 3) + 1, height: buf.readUIntLE(27, 3) + 1 };
+    }
+    return undefined;
+}
+/**
+ * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
+ */
+export async function loadImageFile(path) {
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch {
+        throw new AmaError("invalid_arguments", `图片不存在：${path}`);
+    }
+    if (!info.isFile())
+        throw new AmaError("invalid_arguments", `不是文件：${path}`);
+    if (info.size > MAX_IMAGE_BYTES)
+        throw new AmaError("invalid_arguments", `图片超过 ${MAX_IMAGE_BYTES / 1024 / 1024} MB 上限：${path}（${(info.size / 1024 / 1024).toFixed(1)} MB）`);
+    const buf = await readFile(path);
+    const mimeType = sniffImageMime(buf) ?? imageMimeFromPath(path);
+    if (mimeType === undefined)
+        throw new AmaError("invalid_arguments", `不是支持的图片（PNG / JPEG / GIF / WebP）：${path}`);
+    const size = imageSize(buf, mimeType);
+    return {
+        block: { type: "image", data: buf.toString("base64"), mimeType },
+        path,
+        mimeType,
+        bytes: buf.length,
+        ...(size ? { size } : {}),
+    };
+}

package/dist/tools/ls.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `ls` 工具（设计 §5.2）。[B3]
+ *
+ * 目录项按名字排序（目录与文件混排，与 `ls` 一致）；目录写 `name/`，文件附大小，符号链接写
+ * `name -> target`；含点文件，不过滤 ignore；缺省上限 500。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export interface LsInput {
+    path?: string;
+    limit?: number;
+}
+export declare const DEFAULT_LS_LIMIT = 500;
+export interface LsEntry {
+    name: string;
+    type: "file" | "dir" | "symlink" | "other";
+    size?: number;
+    target?: string;
+}
+export declare function formatEntry(entry: LsEntry): string;
+export declare function executeLs(input: LsInput, ctx: ToolContext): Promise<ToolResult>;
+export declare function createLsTool(): ToolDefinition<LsInput>;

package/dist/tools/ls.js

@@ -0,0 +1,96 @@
+/**
+ * `ls` 工具（设计 §5.2）。[B3]
+ *
+ * 目录项按名字排序（目录与文件混排，与 `ls` 一致）；目录写 `name/`，文件附大小，符号链接写
+ * `name -> target`；含点文件，不过滤 ignore；缺省上限 500。
+ */
+import { lstat, readdir, readlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { displayPath, resolvePath } from "./paths.js";
+import { formatSize } from "./truncate.js";
+export const DEFAULT_LS_LIMIT = 500;
+async function describe(dir, name) {
+    const abs = join(dir, name);
+    try {
+        const info = await lstat(abs);
+        if (info.isSymbolicLink()) {
+            let target = "?";
+            try {
+                target = await readlink(abs);
+            }
+            catch {
+                // 保留 ?
+            }
+            let pointsToDir = false;
+            try {
+                pointsToDir = (await stat(abs)).isDirectory();
+            }
+            catch {
+                // 悬空链接
+            }
+            return { name: pointsToDir ? `${name}/` : name, type: "symlink", target };
+        }
+        if (info.isDirectory())
+            return { name: `${name}/`, type: "dir" };
+        if (info.isFile())
+            return { name, type: "file", size: info.size };
+        return { name, type: "other" };
+    }
+    catch {
+        return { name, type: "other" };
+    }
+}
+export function formatEntry(entry) {
+    if (entry.type === "symlink")
+        return `${entry.name} -> ${entry.target ?? "?"}`;
+    if (entry.type === "file")
+        return `${entry.name}  (${formatSize(entry.size ?? 0)})`;
+    return entry.name;
+}
+export async function executeLs(input, ctx) {
+    const limit = input.limit ?? DEFAULT_LS_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1) {
+        return { content: "limit must be an integer ≥ 1", isError: true };
+    }
+    const dir = resolvePath(input.path ?? ".", ctx.cwd);
+    const shown = displayPath(dir, ctx.cwd);
+    let names;
+    try {
+        if (!(await stat(dir)).isDirectory())
+            return { content: `${shown} is not a directory`, isError: true };
+        names = await readdir(dir);
+    }
+    catch {
+        return { content: `Directory not found: ${shown}`, isError: true };
+    }
+    names.sort((a, b) => a.localeCompare(b, "en"));
+    if (names.length === 0)
+        return { content: `(${shown} is empty)`, details: { count: 0 } };
+    const entries = await Promise.all(names.slice(0, limit).map((n) => describe(dir, n)));
+    let content = entries.map(formatEntry).join("\n");
+    if (names.length > limit) {
+        content += `\n\n[${names.length} entries; showing the first ${limit}. Raise limit to see more.]`;
+    }
+    return { content, details: { count: names.length, entries } };
+}
+export function createLsTool() {
+    return {
+        name: "ls",
+        label: "List",
+        description: "List a directory: subdirectories end with `/`, files show their size, symlinks show their " +
+            `target. Includes dotfiles. Default limit ${DEFAULT_LS_LIMIT}.`,
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Directory (default: cwd)" },
+                limit: { type: "integer", description: `Maximum entries (default ${DEFAULT_LS_LIMIT})` },
+            },
+            additionalProperties: false,
+        },
+        permission: "read",
+        executionMode: "parallel",
+        annotations: { readOnly: true },
+        promptSnippet: "ls: list directory contents",
+        execute: executeLs,
+    };
+}

package/dist/tools/output-accumulator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 进程输出累积（设计 §5.2 bash）。[B3]
+ *
+ * - 保留滚动尾部（约 2 × maxBytes）用于流式 `onUpdate` 与最终尾截断；
+ * - 内存里最多攒 `memoryLimitBytes`，超出即把已有内容落文件，之后增量追加，内存只留尾部；
+ * - `finish()` 做尾截断（行数 + 字节）；发生截断而尚未落盘时补写全文，给出 `fullOutputPath`；
+ * - 输出清洗：去 ANSI 转义与除 `\t\n` 外的控制字符，`\r\n` → `\n`。
+ */
+export interface OutputAccumulatorOptions {
+    maxLines?: number;
+    maxBytes?: number;
+    /** 内存上限，缺省 1 MB。 */
+    memoryLimitBytes?: number;
+    /** 全文落盘路径（懒求值，只在需要时调用一次）。 */
+    spillPath(): string;
+}
+export interface AccumulatedOutput {
+    /** 尾截断后的输出。 */
+    output: string;
+    truncated: boolean;
+    fullOutputPath?: string;
+    totalBytes: number;
+    totalLines: number;
+    outputLines: number;
+}
+export declare function sanitizeOutput(text: string): string;
+export declare class OutputAccumulator {
+    private readonly options;
+    private readonly maxLines;
+    private readonly maxBytes;
+    private readonly memoryLimit;
+    private readonly decoder;
+    private chunks;
+    private memoryBytes;
+    private tailText;
+    private spilledTo;
+    private bytes;
+    private newlines;
+    private lastChar;
+    constructor(options: OutputAccumulatorOptions);
+    get totalBytes(): number;
+    append(chunk: Buffer | string): void;
+    private pushText;
+    private spill;
+    /** 当前滚动尾部（已清洗、尾截断），给流式 onUpdate。 */
+    tail(maxLines?: number): string;
+    finish(): AccumulatedOutput;
+}

package/dist/tools/output-accumulator.js

@@ -0,0 +1,106 @@
+/**
+ * 进程输出累积（设计 §5.2 bash）。[B3]
+ *
+ * - 保留滚动尾部（约 2 × maxBytes）用于流式 `onUpdate` 与最终尾截断；
+ * - 内存里最多攒 `memoryLimitBytes`，超出即把已有内容落文件，之后增量追加，内存只留尾部；
+ * - `finish()` 做尾截断（行数 + 字节）；发生截断而尚未落盘时补写全文，给出 `fullOutputPath`；
+ * - 输出清洗：去 ANSI 转义与除 `\t\n` 外的控制字符，`\r\n` → `\n`。
+ */
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, sliceTailBytes, truncateTail } from "./truncate.js";
+const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+const CONTROL = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+export function sanitizeOutput(text) {
+    return text.replace(/\r\n/g, "\n").replace(ANSI, "").replace(/\r/g, "\n").replace(CONTROL, "");
+}
+export class OutputAccumulator {
+    options;
+    maxLines;
+    maxBytes;
+    memoryLimit;
+    decoder = new StringDecoder("utf8");
+    chunks = [];
+    memoryBytes = 0;
+    tailText = "";
+    spilledTo;
+    bytes = 0;
+    newlines = 0;
+    lastChar = "";
+    constructor(options) {
+        this.options = options;
+        this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.memoryLimit = options.memoryLimitBytes ?? 1024 * 1024;
+    }
+    get totalBytes() {
+        return this.bytes;
+    }
+    append(chunk) {
+        const raw = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+        this.bytes += raw.length;
+        this.pushText(this.decoder.write(raw));
+    }
+    pushText(text) {
+        if (text === "")
+            return;
+        for (let i = 0; i < text.length; i++)
+            if (text.charCodeAt(i) === 10)
+                this.newlines++;
+        this.lastChar = text[text.length - 1] ?? this.lastChar;
+        this.tailText += text;
+        if (this.tailText.length > this.maxBytes * 4) {
+            this.tailText = sliceTailBytes(this.tailText, this.maxBytes * 2);
+        }
+        if (this.spilledTo !== undefined) {
+            appendFileSync(this.spilledTo, text);
+            return;
+        }
+        this.chunks.push(text);
+        this.memoryBytes += Buffer.byteLength(text, "utf8");
+        if (this.memoryBytes > this.memoryLimit)
+            this.spill();
+    }
+    spill() {
+        const target = this.options.spillPath();
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, this.chunks.join(""));
+        this.spilledTo = target;
+        this.chunks = [];
+        this.memoryBytes = 0;
+    }
+    /** 当前滚动尾部（已清洗、尾截断），给流式 onUpdate。 */
+    tail(maxLines = 50) {
+        return truncateTail(sanitizeOutput(this.tailText), { maxLines, maxBytes: this.maxBytes })
+            .content;
+    }
+    finish() {
+        this.pushText(this.decoder.end());
+        const totalLines = this.newlines + (this.bytes > 0 && this.lastChar !== "\n" ? 1 : 0);
+        let source;
+        if (this.spilledTo !== undefined) {
+            // 尾部可能从半行开始：去掉第一行残片。
+            const cut = this.tailText.indexOf("\n");
+            source = cut >= 0 ? this.tailText.slice(cut + 1) : this.tailText;
+        }
+        else {
+            source = this.chunks.join("");
+        }
+        const result = truncateTail(sanitizeOutput(source), {
+            maxLines: this.maxLines,
+            maxBytes: this.maxBytes,
+        });
+        const truncated = result.truncated || this.spilledTo !== undefined;
+        if (truncated && this.spilledTo === undefined)
+            this.spill();
+        return {
+            output: result.content,
+            truncated,
+            ...(truncated && this.spilledTo !== undefined ? { fullOutputPath: this.spilledTo } : {}),
+            totalBytes: this.bytes,
+            totalLines,
+            outputLines: result.outputLines,
+        };
+    }
+}

package/dist/tools/paths.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 路径解析（设计 §5.2「通用安全」）。[B3]
+ *
+ * - 展开 `~` / `~/…`（`~user` 不展开）；相对路径按 cwd 解析；结果是规范化绝对路径。
+ * - 含 NUL 的路径一律拒绝（AmaError invalid_arguments）。
+ * - 符号链接策略：**跟随**，不做沙箱（信任边界是容器 / VM）。规则匹配用词法路径，
+ *   `realPathOrSelf()` 给需要真实路径的调用方（如 ls 标注链接目标）。
+ * - `toPosix()` 把路径统一成 `/` 分隔，供 glob / ignore / 权限规则匹配。
+ */
+export declare function assertNoNul(path: string): void;
+/** 展开 `~` 与 `~/…`、`~\…`。 */
+export declare function expandHome(path: string, home?: string): string;
+/** 解析为绝对路径；空串视为 cwd。 */
+export declare function resolvePath(path: string, cwd: string, home?: string): string;
+export declare function toPosix(path: string): string;
+/** cwd 内给相对路径，cwd 外给绝对路径；统一 `/`。 */
+export declare function displayPath(absolutePath: string, cwd: string): string;
+/** 是否在 dir 之内（含 dir 本身）。 */
+export declare function isWithin(dir: string, target: string): boolean;
+export declare function realPathOrSelf(path: string): string;

package/dist/tools/paths.js

@@ -0,0 +1,58 @@
+/**
+ * 路径解析（设计 §5.2「通用安全」）。[B3]
+ *
+ * - 展开 `~` / `~/…`（`~user` 不展开）；相对路径按 cwd 解析；结果是规范化绝对路径。
+ * - 含 NUL 的路径一律拒绝（AmaError invalid_arguments）。
+ * - 符号链接策略：**跟随**，不做沙箱（信任边界是容器 / VM）。规则匹配用词法路径，
+ *   `realPathOrSelf()` 给需要真实路径的调用方（如 ls 标注链接目标）。
+ * - `toPosix()` 把路径统一成 `/` 分隔，供 glob / ignore / 权限规则匹配。
+ */
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { AmaError } from "../errors.js";
+export function assertNoNul(path) {
+    if (path.includes("\0")) {
+        throw new AmaError("invalid_arguments", "Path must not contain NUL characters");
+    }
+}
+/** 展开 `~` 与 `~/…`、`~\…`。 */
+export function expandHome(path, home = homedir()) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(home, path.slice(2));
+    return path;
+}
+/** 解析为绝对路径；空串视为 cwd。 */
+export function resolvePath(path, cwd, home) {
+    assertNoNul(path);
+    const trimmed = path.trim() === "" ? "." : path;
+    const expanded = expandHome(trimmed, home);
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+}
+export function toPosix(path) {
+    return sep === "\\" ? path.replace(/\\/g, "/") : path;
+}
+/** cwd 内给相对路径，cwd 外给绝对路径；统一 `/`。 */
+export function displayPath(absolutePath, cwd) {
+    const rel = relative(cwd, absolutePath);
+    if (rel === "")
+        return ".";
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return toPosix(absolutePath);
+    return toPosix(rel);
+}
+/** 是否在 dir 之内（含 dir 本身）。 */
+export function isWithin(dir, target) {
+    const rel = relative(dir, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function realPathOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}