@armadra/agent 0.0.0-stage → 0.3.0

package/dist/permissions/preview.js

@@ -0,0 +1,463 @@
+/**
+ * 执行前预览（第三波 §2.2）：审批时列出「这一步会碰到什么」。[W3-B9a-2]
+ *
+ * - 只读：只用 `statSync / lstatSync / readdirSync / readFileSync`，不起子进程、不写盘；
+ * - 有上限：目录递归计数每个目标最多 `maxEntries`（缺省 2000）项，整次预览共用一个时间预算
+ *   （缺省 200 ms，预算循环里逐项检查），超出只给提示；超时 / 超限不降低严重度；
+ * - bash：按段（含 `sh -c` / `eval` / `xargs` / `find -exec` 的嵌套命令）识别 `rm / rmdir / unlink`、
+ *   `mv`、`git clean`、`git checkout -- <路径>`、`git reset --hard` 与 `>` / `>>` 重定向目标；
+ *   通配符、变量与 `{}` 不展开，原样显示并提示范围可能更大；段首的 `cd <路径>` 改变后续段的基准；
+ * - write：目标是否存在、现有行数 / 大小 → 新内容；覆盖本会话未 read 过的文件标 warn；
+ * - edit：读原文用 `planEdits` 干跑，成功给每处 −n/+m 行与总变化，失败提前说明原因；
+ *   超过 2 MiB 的文件只报大小，不读内容；
+ * - 其它工具：一行参数摘要。
+ *
+ * `lines` 不含颜色；`affected[].path` 与行里的路径一样是显示路径（cwd 内相对、`/` 分隔）。
+ */
+import { lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { EditError, planEdits } from "../tools/edit.js";
+import { normalizeToLF, splitBom } from "../tools/edit-fuzzy.js";
+import { displayPath, resolvePath } from "../tools/paths.js";
+import { collectNestedCommands, commandWords, matchDangerous, shellWords } from "./dangerous.js";
+import { splitShellSegments } from "./rules.js";
+export const PREVIEW_MAX_ENTRIES = 2000;
+export const PREVIEW_BUDGET_MS = 200;
+/** 超过它的文件不读内容，只报大小。 */
+export const PREVIEW_MAX_READ_BYTES = 2 * 1024 * 1024;
+/** 一次预览最多列出的目标数。 */
+export const PREVIEW_MAX_TARGETS = 20;
+const RANK = { info: 0, warn: 1, danger: 2 };
+const NULL_DEVICES = new Set(["/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty", "nul"]);
+const UNEXPANDED = /[*?[\]{}$`]/;
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+function countLines(text) {
+    if (text === "")
+        return 0;
+    const n = normalizeToLF(text).split("\n").length;
+    return text.endsWith("\n") ? n - 1 : n;
+}
+class Collector {
+    options;
+    lines = [];
+    affected = [];
+    severity = "info";
+    timedOut = false;
+    hidden = 0;
+    deadline;
+    maxEntries;
+    now;
+    /** 显示路径的基准（会话 cwd）。 */
+    root;
+    /** 解析基准：随段首的 `cd` 与 `git -C` 变化。 */
+    cwd;
+    constructor(options) {
+        this.options = options;
+        this.root = options.cwd;
+        this.cwd = options.cwd;
+        this.now = options.now ?? Date.now;
+        this.deadline = this.now() + (options.budgetMs ?? PREVIEW_BUDGET_MS);
+        this.maxEntries = options.maxEntries ?? PREVIEW_MAX_ENTRIES;
+    }
+    raise(severity) {
+        if (RANK[severity] > RANK[this.severity])
+            this.severity = severity;
+    }
+    expired() {
+        if (!this.timedOut && this.now() > this.deadline)
+            this.timedOut = true;
+        return this.timedOut;
+    }
+    /** 一个目标的一行；超出 {@link PREVIEW_MAX_TARGETS} 只计数。 */
+    target(line, target) {
+        if (this.affected.length + this.hidden >= PREVIEW_MAX_TARGETS) {
+            this.hidden++;
+            return;
+        }
+        this.lines.push(line);
+        if (target !== undefined)
+            this.affected.push(target);
+    }
+    finish(kind) {
+        if (this.hidden > 0)
+            this.lines.push(`… 另 ${this.hidden} 处未列出`);
+        if (this.timedOut) {
+            this.lines.push(`统计超时（> ${this.options.budgetMs ?? PREVIEW_BUDGET_MS} ms），实际范围可能更大`);
+            this.raise("warn");
+        }
+        const preview = { kind, lines: this.lines, severity: this.severity };
+        if (this.affected.length > 0)
+            preview.affected = this.affected;
+        return preview;
+    }
+}
+function tryStat(path, follow = false) {
+    try {
+        return (follow ? statSync : lstatSync)(path, { throwIfNoEntry: false });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 目录递归计数（不跟随符号链接）：文件数、字节数；超限 / 超时提前返回。 */
+function tally(root, c) {
+    const out = { files: 0, bytes: 0, capped: false };
+    const stack = [root];
+    let entries = 0;
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let list;
+        try {
+            list = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of list) {
+            if (c.expired())
+                return out;
+            if (++entries > c.maxEntries)
+                return { ...out, capped: true };
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else {
+                out.files++;
+                out.bytes += tryStat(full)?.size ?? 0;
+            }
+        }
+    }
+    return out;
+}
+/** 统计一个路径：返回目标与「：」之后的说明。 */
+function inspect(abs, c) {
+    const shown = displayPath(abs, c.root);
+    const info = tryStat(abs);
+    if (info === undefined)
+        return { target: { path: shown, exists: false }, text: "不存在" };
+    if (info.isSymbolicLink())
+        return { target: { path: shown, exists: true }, text: "符号链接" };
+    if (!info.isDirectory()) {
+        return {
+            target: { path: shown, exists: true, bytes: info.size },
+            text: `文件，${formatBytes(info.size)}`,
+        };
+    }
+    const t = tally(abs, c);
+    const target = { path: `${shown}/`, exists: true, files: t.files };
+    if (t.capped)
+        return { target, text: `目录，> ${c.maxEntries} 项` };
+    target.bytes = t.bytes;
+    const partial = c.timedOut ? "（统计未完成）" : "";
+    return { target, text: `目录，${t.files} 个文件，${formatBytes(t.bytes)}${partial}` };
+}
+/** 一个路径参数一行；含通配 / 变量的原样显示不展开。 */
+function pathLine(verb, word, c, note = "") {
+    if (UNEXPANDED.test(word)) {
+        c.target(`${verb} ${word}：含通配符或变量，未展开，实际范围可能更大`);
+        c.raise("warn");
+        return;
+    }
+    const { target, text } = inspect(resolvePath(word, c.cwd), c);
+    if (target.exists)
+        c.raise("warn");
+    c.target(`${verb} ${target.path}：${text}${note}`, target);
+}
+/** 段里的 `>` / `>>` 重定向：返回目标与去掉重定向后的文本。 */
+export function splitRedirects(segment) {
+    const targets = [];
+    let rest = "";
+    let quote;
+    for (let i = 0; i < segment.length; i++) {
+        const ch = segment[i];
+        if (quote !== undefined) {
+            rest += ch;
+            if (ch === "\\" && quote === '"' && i + 1 < segment.length)
+                rest += segment[++i];
+            else if (ch === quote)
+                quote = undefined;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+            rest += ch;
+        }
+        else if (ch === "\\" && i + 1 < segment.length) {
+            rest += ch + segment[++i];
+        }
+        else if (ch !== ">" || segment[i + 1] === "(") {
+            rest += ch;
+        }
+        else {
+            rest = rest.replace(/(^|\s)(\d+|&)$/, "$1");
+            let j = i + 1;
+            const append = segment[j] === ">";
+            if (append || segment[j] === "|")
+                j++;
+            const dup = segment[j] === "&";
+            if (dup)
+                j++;
+            while (segment[j] === " " || segment[j] === "\t")
+                j++;
+            let end = j;
+            let q;
+            for (; end < segment.length; end++) {
+                const e = segment[end];
+                if (q !== undefined) {
+                    if (e === q)
+                        q = undefined;
+                }
+                else if (e === "'" || e === '"')
+                    q = e;
+                else if (/[\s;|&<>()]/.test(e))
+                    break;
+            }
+            const word = shellWords(segment.slice(j, end))[0] ?? "";
+            if (word !== "" && !(dup && /^(\d+|-)$/.test(word)))
+                targets.push({ word, append });
+            rest += " ";
+            i = end - 1;
+        }
+    }
+    return { rest, targets };
+}
+function operands(argv, valueFlags = []) {
+    const out = [];
+    let all = false;
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (all || a === "-" || !a.startsWith("-"))
+            out.push(a);
+        else if (a === "--")
+            all = true;
+        else if (valueFlags.includes(a))
+            i++;
+    }
+    return out;
+}
+function previewSegment(segment, c) {
+    const { rest, targets } = splitRedirects(segment);
+    for (const { word, append } of targets) {
+        if (NULL_DEVICES.has(word.toLowerCase()))
+            continue;
+        pathLine(append ? "追加写入" : "覆盖写入", word, c);
+    }
+    const argv = commandWords(rest);
+    const name = basename(argv[0] ?? "");
+    if (name === "cd" && argv.length === 2 && !UNEXPANDED.test(argv[1])) {
+        c.cwd = resolvePath(argv[1], c.cwd);
+        return;
+    }
+    if (name === "rm" || name === "rmdir" || name === "unlink") {
+        const paths = operands(argv);
+        if (paths.length === 0)
+            c.target(`${name}：路径来自管道或展开，范围未知`);
+        for (const p of paths)
+            pathLine("删除", p, c);
+    }
+    else if (name === "mv") {
+        const paths = operands(argv, ["-t", "-S", "--target-directory", "--suffix"]);
+        const t = argv.indexOf("-t");
+        const dest = t > 0 ? argv[t + 1] : paths.pop();
+        for (const p of paths)
+            pathLine("移动", p, c);
+        if (dest !== undefined && paths.length > 0) {
+            const info = UNEXPANDED.test(dest) ? undefined : tryStat(resolvePath(dest, c.cwd));
+            const note = info?.isDirectory() ? "（已存在的目录，移入其中）" : "（已存在，将被覆盖）";
+            pathLine("移到", dest, c, info === undefined ? "" : note);
+        }
+    }
+    else if (name === "git") {
+        previewGit(argv, c);
+    }
+}
+const GIT_VALUE_OPTS = ["-C", "-c", "--git-dir", "--work-tree", "--namespace"];
+function previewGit(argv, c) {
+    let i = 1;
+    let base = c.cwd;
+    while (i < argv.length && argv[i].startsWith("-")) {
+        if (argv[i] === "-C" && argv[i + 1] !== undefined)
+            base = resolvePath(argv[i + 1], base);
+        i += GIT_VALUE_OPTS.includes(argv[i]) ? 2 : 1;
+    }
+    const sub = argv[i];
+    const args = argv.slice(i);
+    const saved = c.cwd;
+    c.cwd = base;
+    try {
+        if (sub === "clean" &&
+            !args.some((a) => a === "-n" || a === "--dry-run" || /^-[a-z]*n/.test(a))) {
+            const paths = operands(args, ["-e", "--exclude"]);
+            for (const p of paths.length > 0 ? paths : ["."]) {
+                pathLine("git clean 范围", p, c, "（计数含已跟踪文件，实际只删未跟踪的）");
+            }
+            // 与危险规则无关地标红：`git -C 目录 clean -f` 之类危险表认不出的写法也算
+            if (args.some((a) => a === "--force" || /^-[A-Za-z]*f/.test(a)))
+                c.raise("danger");
+        }
+        else if (sub === "checkout" && args.includes("--")) {
+            for (const p of args.slice(args.indexOf("--") + 1))
+                pathLine("丢弃改动", p, c);
+        }
+        else if (sub === "reset" && args.includes("--hard")) {
+            c.lines.push("git reset --hard：丢弃工作区与暂存区的全部未提交改动");
+            c.raise("danger");
+        }
+    }
+    finally {
+        c.cwd = saved;
+    }
+}
+function previewBash(command, c, dangerous) {
+    const hit = matchDangerous(command);
+    if (hit !== undefined)
+        c.lines.push(`危险：${hit.description}`);
+    if (hit !== undefined || dangerous)
+        c.raise("danger");
+    const nested = collectNestedCommands(command);
+    const start = c.cwd;
+    for (const text of [command, ...nested.commands]) {
+        c.cwd = start;
+        for (const segment of splitShellSegments(text)) {
+            if (c.timedOut)
+                break;
+            previewSegment(segment, c);
+        }
+    }
+    c.cwd = start;
+    if (nested.tooDeep) {
+        c.lines.push("嵌套过深，内层命令未展开");
+        c.raise("warn");
+    }
+}
+function readSmall(abs, info) {
+    return info.size > PREVIEW_MAX_READ_BYTES ? undefined : readFileSync(abs, "utf8");
+}
+function unread(abs, request, c, tool) {
+    const readFiles = request.context?.readFiles;
+    if (readFiles === undefined || readFiles.has(abs))
+        return;
+    c.lines.push(`本会话未 read 过此文件，${tool} 会被拒绝（先 read）`);
+    c.raise("warn");
+}
+function previewWrite(input, request, c) {
+    const abs = resolvePath(String(input["path"] ?? ""), c.cwd);
+    const content = typeof input["content"] === "string" ? input["content"] : "";
+    const next = `${countLines(content)} 行，${formatBytes(Buffer.byteLength(content, "utf8"))}`;
+    const shown = displayPath(abs, c.root);
+    const info = tryStat(abs, true);
+    if (info === undefined) {
+        c.target(`新建 ${shown}：${next}`, { path: shown, exists: false });
+        return;
+    }
+    if (info.isDirectory()) {
+        c.target(`${shown} 是目录，write 会失败`, { path: `${shown}/`, exists: true });
+        c.raise("warn");
+        return;
+    }
+    const old = readSmall(abs, info);
+    const before = old === undefined ? formatBytes(info.size) : `${countLines(old)} 行，${formatBytes(info.size)}`;
+    c.target(`覆盖 ${shown}：${before} → ${next}`, { path: shown, exists: true, bytes: info.size });
+    unread(abs, request, c, "write");
+}
+function editFailure(message) {
+    const many = /^(\S+) matches (\d+) times/.exec(message);
+    if (many)
+        return `${many[1]} 匹配不唯一（${many[2]} 处）`;
+    const missing = /^Could not find (\S+)/.exec(message);
+    if (missing)
+        return `未找到 ${missing[1]}`;
+    if (message.includes("overlap"))
+        return "多处修改的区间重叠";
+    if (message.includes("no change"))
+        return "修改前后内容相同";
+    return message;
+}
+function previewEdit(input, request, c) {
+    const abs = resolvePath(String(input["path"] ?? ""), c.cwd);
+    const shown = displayPath(abs, c.root);
+    const info = tryStat(abs, true);
+    if (info === undefined || !info.isFile()) {
+        c.target(`${shown} 不存在或不是文件，edit 会失败`, { path: shown, exists: info !== undefined });
+        c.raise("warn");
+        return;
+    }
+    const target = { path: shown, exists: true, bytes: info.size };
+    const raw = readSmall(abs, info);
+    if (raw === undefined) {
+        c.target(`修改 ${shown}：${formatBytes(info.size)}，文件过大，未干跑`, target);
+        unread(abs, request, c, "edit");
+        return;
+    }
+    const content = normalizeToLF(splitBom(raw).text);
+    const edits = Array.isArray(input["edits"]) ? input["edits"] : [];
+    try {
+        const plan = planEdits(content, edits, input["replaceAll"] === true);
+        const fuzzy = plan.fuzzy ? "（空白 / 引号归一后匹配）" : "";
+        c.target(`修改 ${shown}：${plan.replacements} 处替换${fuzzy}`, target);
+        edits.slice(0, 5).forEach((e, i) => {
+            c.lines.push(`  #${i + 1} −${countLines(e.oldText)}/+${countLines(e.newText)} 行`);
+        });
+        if (edits.length > 5)
+            c.lines.push(`  … 另 ${edits.length - 5} 处`);
+        c.lines.push(`  共 ${countLines(content)} → ${countLines(plan.result)} 行`);
+    }
+    catch (err) {
+        if (!(err instanceof EditError))
+            throw err;
+        c.target(`修改 ${shown}：干跑失败——${editFailure(err.message)}`, target);
+        c.raise("warn");
+    }
+    unread(abs, request, c, "edit");
+}
+const SUMMARY_KEYS = ["path", "command", "pattern", "description", "query", "url", "name"];
+/** 审批请求的执行前预览；纯读，不抛错（内部错误返回空预览）。 */
+export function previewAction(request, options) {
+    const c = new Collector(options);
+    const input = typeof request.input === "object" && request.input !== null
+        ? request.input
+        : {};
+    const kind = request.toolName === "bash" || request.toolName === "write" || request.toolName === "edit"
+        ? request.toolName
+        : "other";
+    try {
+        if (kind === "bash" && typeof input["command"] === "string") {
+            previewBash(input["command"], c, request.reason === "dangerous");
+        }
+        else if (kind === "write" && typeof input["path"] === "string") {
+            previewWrite(input, request, c);
+        }
+        else if (kind === "edit" && typeof input["path"] === "string") {
+            previewEdit(input, request, c);
+        }
+        else if (kind === "other") {
+            const key = SUMMARY_KEYS.find((k) => typeof input[k] === "string" && input[k] !== "");
+            if (key !== undefined)
+                c.lines.push(String(input[key])
+                    .replace(/\s*\n\s*/g, " ⏎ ")
+                    .slice(0, 120));
+        }
+    }
+    catch (err) {
+        c.lines.push(`预览失败：${err instanceof Error ? err.message : String(err)}`);
+    }
+    return c.finish(kind);
+}
+/** 对话框 / 行式界面里显示的预览行（`other` 已由输入摘要覆盖，不重复显示）。 */
+export function previewDisplayLines(preview, max = 10) {
+    if (preview === undefined || preview.kind === "other")
+        return [];
+    if (preview.lines.length <= max)
+        return preview.lines;
+    return [...preview.lines.slice(0, max - 1), `… 另 ${preview.lines.length - max + 1} 行`];
+}

package/dist/permissions/rules.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 权限规则（设计 §7.2、§5.2「通用安全」）。[B3]
+ *
+ * 语法：`tool` 或 `tool(pattern)`；`tool` 是工具名 glob（`canvas_*`、`*`）；pattern：
+ * - bash：对命令文本做通配（`*` 任意字符含空格与 `/`，`?` 单字符），命令先折叠空白；
+ * - 带 `path` 的工具（read / write / edit / ls / grep / glob 及宿主工具）：对路径做 glob（`**`）。
+ *   相对模式匹配 cwd 内的相对路径；以 `**` 开头的模式也匹配绝对路径（例如 .ssh 目录规则命中 ~/.ssh 下的文件）；
+ *   绝对模式（`/…`、`~/…`）匹配绝对路径。缺 path 的调用以 cwd 为路径。
+ * - 其它工具带 pattern 的规则不匹配（无可比对的对象）。
+ *
+ * bash 复合命令：deny 规则命中整条或**任一**段即生效；allow 规则要求**每一**段都被某条 allow 覆盖，
+ * 且命令里没有 `$(…)` / 反引号替换——否则 allow 不生效（回到「问」）。
+ *
+ * 来源约束（§7.2）：项目级只能收紧——allow 被忽略、mode 只能更严，均产生 warning。
+ */
+import type { PermissionMode, Rule, RuleSource } from "./types.js";
+/** 内置缺省 deny 表（用户可经 `builtinDeny` 选项移除）。 */
+export declare const BUILTIN_DENY_RULES: readonly string[];
+export declare function parseRule(raw: string, effect: "allow" | "deny", source: RuleSource): Rule;
+export declare function wildcardToRegExp(pattern: string): RegExp;
+export declare function toolNameMatches(ruleTool: string, toolName: string): boolean;
+export declare function normalizeCommand(command: string): string;
+/**
+ * 按 `&&`、`||`、`;`、`|`、`&`、换行切分（引号内不切），每段 trim 后返回非空段。
+ */
+export declare function splitShellSegments(command: string): string[];
+export declare function hasCommandSubstitution(command: string): boolean;
+/** 输入里的路径（绝对）；没有 path 字段的工具返回 undefined。 */
+export declare function inputPath(toolName: string, input: unknown, cwd: string): string | undefined;
+export declare function inputCommand(input: unknown): string | undefined;
+export declare function pathMatches(pattern: string, absPath: string, cwd: string): boolean;
+/** 第一条命中的 deny 规则。 */
+export declare function findDenyRule(rules: readonly Rule[], toolName: string, input: unknown, cwd: string): Rule | undefined;
+/** 覆盖本次调用的 allow 规则（复合命令返回第一段的覆盖者）；不覆盖返回 undefined。 */
+export declare function findAllowRule(rules: readonly Rule[], toolName: string, input: unknown, cwd: string): Rule | undefined;
+/** a 是否比 b 更严（或相等）。 */
+export declare function isAtLeastAsStrict(a: PermissionMode, b: PermissionMode): boolean;
+export interface PermissionLayer {
+    source: RuleSource;
+    mode?: PermissionMode;
+    allow?: readonly string[];
+    deny?: readonly string[];
+}
+export interface ResolvedPermissions {
+    mode: PermissionMode;
+    rules: Rule[];
+    warnings: string[];
+}
+export interface ResolveOptions {
+    /** 缺省 true = 启用全部内置 deny；false 全部移除；数组 = 要移除的那些原文。 */
+    builtinDeny?: boolean | readonly string[];
+    defaultMode?: PermissionMode;
+}
+/**
+ * 按给定顺序（调用方排好：用户级 → profile → 项目级 → 命令行）合并。项目级只能收紧。
+ * 不合法的规则文本记 warning 并跳过。
+ */
+export declare function resolvePermissionLayers(layers: readonly PermissionLayer[], options?: ResolveOptions): ResolvedPermissions;