@armadra/agent 0.0.0-stage → 0.3.0

package/dist/tools/file-mutex.js

@@ -0,0 +1,29 @@
+/**
+ * 按路径串行化读 - 改 - 写（设计 §1.2）。[B3]
+ *
+ * 同一绝对路径上的 write / edit 排队执行；不同路径互不阻塞。前一个失败不影响后一个。
+ */
+import { resolve } from "node:path";
+const tails = new Map();
+function keyOf(path) {
+    const abs = resolve(path);
+    return process.platform === "win32" || process.platform === "darwin" ? abs.toLowerCase() : abs;
+}
+export async function withFileMutex(path, fn) {
+    const key = keyOf(path);
+    const previous = tails.get(key) ?? Promise.resolve();
+    const run = previous.then(fn, fn);
+    const tail = run.then(() => undefined, () => undefined);
+    tails.set(key, tail);
+    try {
+        return await run;
+    }
+    finally {
+        if (tails.get(key) === tail)
+            tails.delete(key);
+    }
+}
+/** 当前持有队列的路径数（测试用）。 */
+export function pendingMutexCount() {
+    return tails.size;
+}

package/dist/tools/glob.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 内置 glob（设计 §5.2 glob）。[B3]
+ *
+ * 语法：`*`（不跨 `/`）、`?`、`**`（零或多段）、`[abc]` / `[a-z]` / `[!x]`、`{a,b}`（可嵌套）、`\` 转义；
+ * 以 `!` 开头的模式是排除。不含 `/` 的模式匹配**文件名**（任意深度），含 `/` 的匹配相对搜索根的
+ * 路径。点文件同样参与匹配（`.git` 由遍历层排除）。Windows 上大小写不敏感。
+ *
+ * 工具：遍历尊重 `.gitignore` / `.ignore`，按 mtime 倒序，缺省上限 1000。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export interface GlobBodyOptions {
+    /** 是否识别 `{a,b}`（gitignore 不识别）。 */
+    braces?: boolean;
+}
+/** 把 glob 翻译成不带锚点的正则源。 */
+export declare function globBody(pattern: string, options?: GlobBodyOptions): string;
+export interface GlobMatchOptions {
+    nocase?: boolean;
+}
+export declare function globToRegExp(pattern: string, options?: GlobMatchOptions): RegExp;
+/** 多模式匹配器：正模式取并集，`!` 模式排除；只有排除模式时视为全集减排除。 */
+export declare class GlobMatcher {
+    private readonly include;
+    private readonly exclude;
+    constructor(patterns: string | readonly string[], options?: GlobMatchOptions);
+    private static hit;
+    /** `rel` 为相对搜索根的 `/` 分隔路径。 */
+    matches(rel: string): boolean;
+}
+export interface GlobInput {
+    pattern: string;
+    path?: string;
+    limit?: number;
+}
+export declare const DEFAULT_GLOB_LIMIT = 1000;
+export interface GlobMatchFile {
+    abs: string;
+    rel: string;
+    mtimeMs: number;
+}
+/** 收集匹配文件并按 mtime 倒序（同 mtime 按路径）。 */
+export declare function globFiles(root: string, pattern: string | readonly string[], signal?: AbortSignal): Promise<GlobMatchFile[]>;
+export declare function executeGlob(input: GlobInput, ctx: ToolContext): Promise<ToolResult>;
+export declare function createGlobTool(): ToolDefinition<GlobInput>;

package/dist/tools/glob.js

@@ -0,0 +1,217 @@
+/**
+ * 内置 glob（设计 §5.2 glob）。[B3]
+ *
+ * 语法：`*`（不跨 `/`）、`?`、`**`（零或多段）、`[abc]` / `[a-z]` / `[!x]`、`{a,b}`（可嵌套）、`\` 转义；
+ * 以 `!` 开头的模式是排除。不含 `/` 的模式匹配**文件名**（任意深度），含 `/` 的匹配相对搜索根的
+ * 路径。点文件同样参与匹配（`.git` 由遍历层排除）。Windows 上大小写不敏感。
+ *
+ * 工具：遍历尊重 `.gitignore` / `.ignore`，按 mtime 倒序，缺省上限 1000。
+ */
+import { stat } from "node:fs/promises";
+import { displayPath, resolvePath } from "./paths.js";
+import { walk } from "./ignore.js";
+const REGEX_SPECIAL = /[.+^${}()|[\]\\*?]/;
+function escapeChar(ch) {
+    return REGEX_SPECIAL.test(ch) || ch === "/" ? `\\${ch}` : ch;
+}
+/** 从 `start`（指向 `[`）解析字符类，返回 [正则片段, 结束下标]；不闭合返回 undefined。 */
+function parseClass(p, start) {
+    let i = start + 1;
+    let negate = false;
+    if (p[i] === "!" || p[i] === "^") {
+        negate = true;
+        i++;
+    }
+    let body = "";
+    let first = true;
+    while (i < p.length) {
+        const ch = p[i];
+        if (ch === "]" && !first) {
+            return [`[${negate ? "^" : ""}${body}${negate ? "/" : ""}]`, i];
+        }
+        if (ch === "\\" && i + 1 < p.length) {
+            body += `\\${p[i + 1]}`;
+            i += 2;
+        }
+        else {
+            body += ch === "\\" || ch === "]" || ch === "[" || ch === "^" ? `\\${ch}` : ch;
+            i++;
+        }
+        first = false;
+    }
+    return undefined;
+}
+/** 与 `{` 配对的 `}` 下标；无则 -1。 */
+function matchingBrace(p, start) {
+    let depth = 0;
+    for (let i = start; i < p.length; i++) {
+        const ch = p[i];
+        if (ch === "\\")
+            i++;
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** 把 glob 翻译成不带锚点的正则源。 */
+export function globBody(pattern, options = {}) {
+    const braces = options.braces ?? true;
+    let out = "";
+    const closers = [];
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\" && i + 1 < pattern.length) {
+            out += escapeChar(pattern[++i]);
+        }
+        else if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                const atStart = i === 0 || pattern[i - 1] === "/";
+                const next = pattern[i + 2];
+                if (atStart && next === "/") {
+                    out += "(?:[^/]*/)*";
+                    i += 2;
+                }
+                else if (atStart && next === undefined) {
+                    out += ".*";
+                    i += 1;
+                }
+                else {
+                    out += "[^/]*";
+                    i += 1;
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            out += "[^/]";
+        }
+        else if (ch === "[") {
+            const cls = parseClass(pattern, i);
+            if (cls) {
+                out += cls[0];
+                i = cls[1];
+            }
+            else
+                out += "\\[";
+        }
+        else if (braces && ch === "{" && matchingBrace(pattern, i) > 0) {
+            closers.push(matchingBrace(pattern, i));
+            out += "(?:";
+        }
+        else if (braces && ch === "," && closers.length > 0) {
+            out += "|";
+        }
+        else if (braces && ch === "}" && closers[closers.length - 1] === i) {
+            closers.pop();
+            out += ")";
+        }
+        else {
+            out += escapeChar(ch);
+        }
+    }
+    return out;
+}
+export function globToRegExp(pattern, options = {}) {
+    return new RegExp(`^${globBody(pattern)}$`, options.nocase ? "i" : "");
+}
+/** 多模式匹配器：正模式取并集，`!` 模式排除；只有排除模式时视为全集减排除。 */
+export class GlobMatcher {
+    include = [];
+    exclude = [];
+    constructor(patterns, options = {}) {
+        const nocase = options.nocase ?? process.platform === "win32";
+        for (const raw of typeof patterns === "string" ? [patterns] : patterns) {
+            const negate = raw.startsWith("!");
+            let p = negate ? raw.slice(1) : raw;
+            if (p.startsWith("./"))
+                p = p.slice(2);
+            if (p === "")
+                continue;
+            const compiled = { regex: globToRegExp(p, { nocase }), basename: !p.includes("/") };
+            (negate ? this.exclude : this.include).push(compiled);
+        }
+    }
+    static hit(g, rel) {
+        const target = g.basename ? (rel.split("/").pop() ?? rel) : rel;
+        return g.regex.test(target);
+    }
+    /** `rel` 为相对搜索根的 `/` 分隔路径。 */
+    matches(rel) {
+        const included = this.include.length === 0 || this.include.some((g) => GlobMatcher.hit(g, rel));
+        return included && !this.exclude.some((g) => GlobMatcher.hit(g, rel));
+    }
+}
+export const DEFAULT_GLOB_LIMIT = 1000;
+/** 收集匹配文件并按 mtime 倒序（同 mtime 按路径）。 */
+export async function globFiles(root, pattern, signal) {
+    const matcher = new GlobMatcher(pattern);
+    const found = [];
+    for await (const entry of walk(root, signal ? { signal } : {})) {
+        if (entry.isDir || !matcher.matches(entry.rel))
+            continue;
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (await stat(entry.abs)).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        found.push({ abs: entry.abs, rel: entry.rel, mtimeMs });
+    }
+    found.sort((a, b) => b.mtimeMs - a.mtimeMs || a.rel.localeCompare(b.rel));
+    return found;
+}
+export async function executeGlob(input, ctx) {
+    if (typeof input.pattern !== "string" || input.pattern === "") {
+        return { content: "pattern must be a non-empty string", isError: true };
+    }
+    const limit = input.limit ?? DEFAULT_GLOB_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1) {
+        return { content: "limit must be an integer ≥ 1", isError: true };
+    }
+    const root = resolvePath(input.path ?? ".", ctx.cwd);
+    try {
+        if (!(await stat(root)).isDirectory()) {
+            return { content: `${displayPath(root, ctx.cwd)} is not a directory`, isError: true };
+        }
+    }
+    catch {
+        return { content: `Directory not found: ${displayPath(root, ctx.cwd)}`, isError: true };
+    }
+    const files = await globFiles(root, input.pattern, ctx.signal);
+    if (files.length === 0)
+        return { content: "No files found", details: { count: 0 } };
+    const shown = files.slice(0, limit).map((f) => displayPath(f.abs, ctx.cwd));
+    let content = shown.join("\n");
+    if (files.length > limit) {
+        content += `\n\n[${files.length} files matched; showing the ${limit} most recently modified. Narrow the pattern or raise limit.]`;
+    }
+    return { content, details: { count: files.length, truncated: files.length > limit } };
+}
+export function createGlobTool() {
+    return {
+        name: "glob",
+        label: "Glob",
+        description: "Find files by glob (`**`, `*`, `?`, `[...]`, `{a,b}`, leading `!` excludes). " +
+            "Patterns without `/` match names at any depth. Respects .gitignore/.ignore; newest first.",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: { type: "string", description: "e.g. **/*.ts" },
+                path: { type: "string", description: "Directory (default: cwd)" },
+                limit: { type: "integer", description: `Default ${DEFAULT_GLOB_LIMIT}` },
+            },
+            required: ["pattern"],
+            additionalProperties: false,
+        },
+        permission: "read",
+        executionMode: "parallel",
+        annotations: { readOnly: true },
+        promptSnippet: "glob: find files by name pattern",
+        execute: executeGlob,
+    };
+}

package/dist/tools/grep.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 内置正则搜索（设计 §5.2 grep）。[B3]
+ *
+ * - 遍历尊重 `.gitignore` / `.ignore`；跳过二进制（NUL 嗅探）与 > 2 MB 文件；每批并发 16 个文件；
+ * - 文件按路径排序处理，输出确定；匹配行 `path:line: text`，上下文行 `path-line- text`，
+ *   不相邻的组之间 `--`；匹配行截 500 字符；
+ * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export interface GrepInput {
+    pattern: string;
+    path?: string;
+    glob?: string;
+    ignoreCase?: boolean;
+    literal?: boolean;
+    context?: number;
+    limit?: number;
+}
+export declare const DEFAULT_GREP_LIMIT = 100;
+export declare const GREP_MAX_FILE_BYTES: number;
+export declare const GREP_CONCURRENCY = 16;
+export interface GrepMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+export declare function compilePattern(input: Pick<GrepInput, "pattern" | "ignoreCase" | "literal">): RegExp;
+interface FileHits {
+    lines: string[];
+    hits: number[];
+}
+/** 一个文件的输出块；`budget` 是还允许输出的匹配数。 */
+export declare function formatFileHits(shown: string, file: FileHits, context: number, budget: number): {
+    text: string[];
+    used: number;
+};
+export declare function executeGrep(input: GrepInput, ctx: ToolContext): Promise<ToolResult>;
+export declare function createGrepTool(): ToolDefinition<GrepInput>;
+export {};

package/dist/tools/grep.js

@@ -0,0 +1,179 @@
+/**
+ * 内置正则搜索（设计 §5.2 grep）。[B3]
+ *
+ * - 遍历尊重 `.gitignore` / `.ignore`；跳过二进制（NUL 嗅探）与 > 2 MB 文件；每批并发 16 个文件；
+ * - 文件按路径排序处理，输出确定；匹配行 `path:line: text`，上下文行 `path-line- text`，
+ *   不相邻的组之间 `--`；匹配行截 500 字符；
+ * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { displayPath, resolvePath } from "./paths.js";
+import { walk } from "./ignore.js";
+import { GlobMatcher } from "./glob.js";
+import { isBinary } from "./read.js";
+import { DEFAULT_MAX_BYTES, truncateHead, truncateLine } from "./truncate.js";
+export const DEFAULT_GREP_LIMIT = 100;
+export const GREP_MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const GREP_CONCURRENCY = 16;
+const MAX_CONTEXT = 5;
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function compilePattern(input) {
+    const source = input.literal ? escapeRegExp(input.pattern) : input.pattern;
+    return new RegExp(source, input.ignoreCase ? "i" : "");
+}
+async function searchFile(abs, regex) {
+    try {
+        const info = await stat(abs);
+        if (!info.isFile() || info.size > GREP_MAX_FILE_BYTES)
+            return undefined;
+        const buf = await readFile(abs);
+        if (isBinary(buf))
+            return undefined;
+        const lines = buf.toString("utf8").replace(/\r\n/g, "\n").split("\n");
+        if (lines[lines.length - 1] === "")
+            lines.pop();
+        const hits = [];
+        lines.forEach((line, i) => {
+            if (regex.test(line))
+                hits.push(i);
+        });
+        return hits.length > 0 ? { lines, hits } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 一个文件的输出块；`budget` 是还允许输出的匹配数。 */
+export function formatFileHits(shown, file, context, budget) {
+    const hits = file.hits.slice(0, budget);
+    const out = [];
+    let lastPrinted = -1;
+    const hitSet = new Set(hits);
+    for (const hit of hits) {
+        const from = Math.max(0, hit - context);
+        const to = Math.min(file.lines.length - 1, hit + context);
+        if (context > 0 && lastPrinted >= 0 && from > lastPrinted + 1)
+            out.push("--");
+        for (let i = Math.max(from, lastPrinted + 1); i <= to; i++) {
+            const sep = hitSet.has(i) ? ":" : "-";
+            out.push(`${shown}${sep}${i + 1}${sep} ${truncateLine(file.lines[i] ?? "")}`);
+        }
+        lastPrinted = Math.max(lastPrinted, to);
+    }
+    return { text: out, used: hits.length };
+}
+async function candidateFiles(root, isFile, glob, signal) {
+    if (isFile)
+        return [root];
+    const matcher = glob ? new GlobMatcher(glob) : undefined;
+    const files = [];
+    for await (const entry of walk(root, { signal })) {
+        if (entry.isDir)
+            continue;
+        if (matcher && !matcher.matches(entry.rel))
+            continue;
+        files.push(entry.abs);
+    }
+    return files;
+}
+export async function executeGrep(input, ctx) {
+    if (typeof input.pattern !== "string" || input.pattern === "") {
+        return { content: "pattern must be a non-empty string", isError: true };
+    }
+    let regex;
+    try {
+        regex = compilePattern(input);
+    }
+    catch (err) {
+        return { content: `Invalid regular expression: ${err.message}`, isError: true };
+    }
+    const context = Math.min(MAX_CONTEXT, Math.max(0, Math.floor(input.context ?? 0)));
+    const limit = input.limit ?? DEFAULT_GREP_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1) {
+        return { content: "limit must be an integer ≥ 1", isError: true };
+    }
+    const root = resolvePath(input.path ?? ".", ctx.cwd);
+    let rootIsFile;
+    try {
+        rootIsFile = (await stat(root)).isFile();
+    }
+    catch {
+        return { content: `Path not found: ${displayPath(root, ctx.cwd)}`, isError: true };
+    }
+    const files = await candidateFiles(root, rootIsFile, input.glob, ctx.signal);
+    const blocks = [];
+    let matches = 0;
+    let matchedFiles = 0;
+    let limited = false;
+    outer: for (let i = 0; i < files.length; i += GREP_CONCURRENCY) {
+        if (ctx.signal.aborted)
+            return { content: "aborted by user", isError: true };
+        const batch = files.slice(i, i + GREP_CONCURRENCY);
+        const results = await Promise.all(batch.map((f) => searchFile(f, regex)));
+        for (let j = 0; j < batch.length; j++) {
+            const hits = results[j];
+            if (!hits)
+                continue;
+            if (matches >= limit) {
+                limited = true;
+                break outer;
+            }
+            const shown = displayPath(batch[j], ctx.cwd);
+            const block = formatFileHits(shown, hits, context, limit - matches);
+            blocks.push(block.text.join("\n"));
+            matches += block.used;
+            matchedFiles++;
+            if (block.used < hits.hits.length) {
+                limited = true;
+                break outer;
+            }
+        }
+    }
+    if (matches === 0)
+        return { content: "No matches found", details: { matches: 0, files: 0 } };
+    const joined = blocks.join(context > 0 ? "\n--\n" : "\n");
+    const cut = truncateHead(joined, {
+        maxLines: Number.MAX_SAFE_INTEGER,
+        maxBytes: DEFAULT_MAX_BYTES,
+    });
+    let content = cut.content;
+    if (limited) {
+        content += `\n\n[Stopped at ${limit} matches. Narrow the search or raise limit.]`;
+    }
+    else if (cut.truncated) {
+        content += "\n\n[Output truncated at 50 KB. Narrow the search.]";
+    }
+    return {
+        content,
+        details: { matches, files: matchedFiles, limited, truncated: cut.truncated },
+    };
+}
+export function createGrepTool() {
+    return {
+        name: "grep",
+        label: "Grep",
+        description: "Search file contents by JS regex. Respects .gitignore/.ignore; skips binary and >2 MB " +
+            "files. Output: `path:line: text`.",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: { type: "string" },
+                path: { type: "string", description: "File or dir (default: cwd)" },
+                glob: { type: "string", description: "File filter, e.g. *.ts" },
+                ignoreCase: { type: "boolean" },
+                literal: { type: "boolean" },
+                context: { type: "integer", description: "0-5 lines" },
+                limit: { type: "integer", description: `Default ${DEFAULT_GREP_LIMIT}` },
+            },
+            required: ["pattern"],
+            additionalProperties: false,
+        },
+        permission: "read",
+        executionMode: "parallel",
+        annotations: { readOnly: true },
+        promptSnippet: "grep: search file contents",
+        execute: executeGrep,
+    };
+}

package/dist/tools/ignore.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `.gitignore` / `.ignore` 解析与匹配，以及尊重它们的目录遍历（设计 §5.2 grep / glob）。[B3]
+ *
+ * 规则语义（gitignore 子集）：空行与 `#` 注释；`\#`、`\!`、`\ ` 转义；`!` 取反；末尾 `/` 只匹配目录；
+ * 中间或开头含 `/` 的模式锚定在 ignore 文件所在目录，否则匹配任意深度的名字；`**` 的三种位置；
+ * 同一路径**最后**命中的规则生效；被忽略的目录不再下钻（其下的取反规则无效，与 git 一致）。
+ * 嵌套：每个目录的 `.gitignore` 先、`.ignore` 后（后者优先）；从搜索根向上到仓库根（含 `.git` 的
+ * 目录）的祖先 ignore 文件也生效。`.git` 目录永远跳过；目录符号链接不跟随。
+ */
+export interface IgnoreRule {
+    negate: boolean;
+    dirOnly: boolean;
+    regex: RegExp;
+    /** ignore 文件所在目录（绝对路径，`/` 分隔，无尾斜杠）。 */
+    base: string;
+    source: string;
+}
+export declare const IGNORE_FILES: readonly [".gitignore", ".ignore"];
+/** 解析一行；空 / 注释返回 undefined。 */
+export declare function parseIgnoreLine(rawLine: string, base: string, nocase?: boolean): IgnoreRule | undefined;
+export declare function parseIgnoreFile(content: string, base: string, nocase?: boolean): IgnoreRule[];
+/** 按规则顺序求值，最后命中者生效。 */
+export declare function isIgnoredBy(rules: readonly IgnoreRule[], absPath: string, isDir: boolean): boolean;
+/** 搜索根之上、直到仓库根（含 `.git` 的目录）的祖先 ignore 规则，外层在前。 */
+export declare function ancestorRules(root: string, nocase?: boolean): Promise<IgnoreRule[]>;
+export interface WalkEntry {
+    abs: string;
+    /** 相对遍历根，`/` 分隔。 */
+    rel: string;
+    isDir: boolean;
+}
+export interface WalkOptions {
+    /** 缺省 true。 */
+    respectIgnore?: boolean;
+    signal?: AbortSignal;
+    /** 只在 Windows 上缺省大小写不敏感。 */
+    nocase?: boolean;
+}
+/** 深度优先、目录内按名字排序的遍历；产出文件与目录（目录先于其内容）。 */
+export declare function walk(root: string, options?: WalkOptions): AsyncGenerator<WalkEntry>;