@agentdevjs/shell-feature 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @agentdevjs/shell-feature
+
+Shell execution feature for AgentDev framework.
+
+## Installation
+
+```bash
+npm install @agentdevjs/shell-feature
+```
+
+## Usage
+
+```typescript
+import { BasicAgent } from 'agentdev';
+import { ShellFeature } from '@agentdevjs/shell-feature';
+
+const agent = new BasicAgent().use(new ShellFeature());
+```
+
+## Features
+
+- **Bash Execution**: Execute shell commands via Git Bash
+- **Safe Trash**: Delete, list, and restore files safely with trash bin

package/dist/index.d.ts

@@ -0,0 +1,344 @@
+import { ToolTerminationReason, Tool, AgentFeature, FeatureManifestDefinition, FeatureInitContext, PackageInfo } from '@agentdevjs/core';
+
+/**
+ * Shell 共享核心（ticket 024 / ADR-0005）
+ *
+ * bash 与 powershell 共用的「spawn + collect + 截断落盘 + 终止收集」管线：
+ * - 正常完成：沿用既有语义（成功 stdout/stderr 独立截断落盘；失败合并截断后 reject）。
+ * - 终止收集（toolContext.signal aborted，ticket 023 合并 signal 契约）：
+ *   kill（Windows taskkill /PID <pid> /T /F 进程树；POSIX 进程组 SIGKILL）
+ *   → 继续读 stdout/stderr 到 EOF（上限 1s，孙进程占 pipe 兜底）
+ *   → resolve（不再 reject），结果文本为部分输出 + 尾部 <shell_metadata> 块。
+ *
+ * 计时职责归框架 executor（Tool.timeout 声明契约）：本模块不设内部 setTimeout
+ * race；args.timeout 由 executor 经 fromArg 消费并 clamp。
+ */
+
+/** 元数据块标记（仅终止态出现在结果尾部）。 */
+declare const SHELL_METADATA_OPEN = "<shell_metadata>";
+declare const SHELL_METADATA_CLOSE = "</shell_metadata>";
+interface ShellRunResult {
+    stdout: string;
+    stderr: string;
+    output: string;
+}
+interface ShellRunContext {
+    /** 框架注入的合并 signal（用户打断与框架超时共用，见 ticket 023） */
+    signal?: AbortSignal;
+    /** 终止原因查询（executor 注入；未走终止协议时恒返回 null） */
+    termination?: () => ToolTerminationReason | null;
+    /** 当前终止 settle 的绝对截止时间（epoch ms）；shell drain 消费同一预算 */
+    terminationDeadline?: () => number | null;
+    /**
+     * 进度发射上下文（工单 025）：提供后执行中每 ~300ms 发射一次
+     * tool.progress 通知；缺省不发射（纯增量，行为不变）。
+     */
+    progress?: {
+        /** LLM 生成的 call.id */
+        callId?: string;
+        /** 工具名称 */
+        toolName: string;
+        /** 本次调用生效超时（毫秒）；未声明 timeout 时为 null */
+        timeoutMs: number | null;
+    };
+}
+/**
+ * 截断输出并持久化完整内容到磁盘。
+ *
+ * 当输出超过 limit 时：
+ * 1. 将完整输出写入 workdir/.agentdev/temp/bash-output-<timestamp>-<random>.log
+ * 2. 返回截断版本（头 60% + 尾 40%），中间插入截断提示和文件路径引用
+ *
+ * 如果写盘失败，fallback 到纯截断（不丢失截断提示，但完整内容不可恢复）。
+ *
+ * @param forcePersist true 时无论长度一律落盘（终止态使用：被杀进程的已积累
+ *   输出必须可恢复），并返回 logPath 供元数据引用。
+ */
+declare function processOutputWithPersistence(output: string, workdir: string, limit?: number, forcePersist?: boolean): Promise<[string, string | null]>;
+interface ShellMetadataFields {
+    terminated: boolean;
+    reason: ToolTerminationReason;
+    durationMs: number;
+    exitCode: number | null;
+    outputBytes: number;
+    truncated: boolean;
+    logPath: string | null;
+}
+declare function formatShellMetadata(meta: ShellMetadataFields): string;
+
+/**
+ * Shell Feature 工具定义
+ *
+ * 提供 bash 工具，在 Windows 上通过 Git Bash、在 Linux/macOS 上通过原生 bash 执行 Shell 命令，支持 AbortSignal 中断。
+ *
+ * 改进点（照搬 Claude Code 的优秀实践）：
+ * 1. 命令引用：eval + 单引号包裹，彻底解决 syntax error near unexpected token '('
+ * 2. 非 -i 模式：去掉 interactive flag，消除 job control 警告
+ * 3. stdin redirect：自动添加 < /dev/null 防止命令挂起
+ * 4. Windows null rewrite：>nul → >/dev/null
+ * 5. 动态 bash 路径检测（Windows: Git Bash; Linux/macOS: $SHELL || /bin/bash）
+ * 6. 输出截断：防止大输出撑爆 LLM 上下文
+ *
+ * 终止语义（ticket 024 / ADR-0005）：超时计时归框架 executor（Tool.timeout
+ * 声明契约）；signal aborted 时 kill → drain 到 EOF → resolve 部分输出 +
+ * <shell_metadata> 块（见 shell-core.ts）。
+ */
+
+interface ShellCommandToolOptions {
+    workspaceDir?: string;
+    workdir?: string;
+    resourceRoot?: string;
+    /** Override bash path detection (used when ShellFeature pre-detects the path) */
+    bashPath?: string;
+    /** 覆盖默认超时（manifest 配置 defaultTimeoutMs）；缺省 120000 */
+    timeoutMs?: number;
+    /** 覆盖超时上限（manifest 配置 maxTimeoutMs）；缺省 600000 */
+    maxTimeoutMs?: number;
+}
+interface ShellExecutionResult {
+    stdout: string;
+    stderr: string;
+    output: string;
+}
+/**
+ * 动态查找 Git Bash 的 bash.exe 路径。
+ *
+ * 查找顺序：
+ * 1. configuredPath 参数（来自 manifest 配置）
+ * 2. 环境变量 AGENTDEV_GIT_BASH_PATH
+ * 3. 环境变量 SHELL（如果包含 bash）
+ * 4. where bash（Windows）
+ * 5. 常见安装位置
+ *
+ * 返回 null 表示未找到（调用方应据此决定是否注册工具）。
+ */
+declare function findGitBashPath(configuredPath?: string): string | null;
+/**
+ * 运行 Shell 命令（支持 AbortSignal 中断；终止时收集部分输出并附元数据块）
+ *
+ * 关键改进：
+ * - 使用 eval + 单引号引用替代 naive 的双引号转义
+ * - 去掉 -i（interactive）flag
+ * - 添加 stdin redirect
+ * - 重写 Windows null redirect
+ */
+declare function runShellCommand(command: string, options?: ShellCommandToolOptions, context?: ShellRunContext): Promise<ShellExecutionResult>;
+declare function createShellCommandTool(description: string, options?: ShellCommandToolOptions): Tool;
+
+/**
+ * PowerShell 命令执行工具
+ *
+ * 提供 PowerShell 路径检测、命令执行和工具定义。
+ * 与 bash 工具平行，共用 shell-core.ts 的「spawn + collect + 截断落盘 +
+ * 终止收集」管线（ticket 024），行为逐项一致（render 模板本就共用 bash.render.ts）。
+ */
+
+/**
+ * 查找 PowerShell 可执行文件路径。
+ *
+ * 查找顺序：
+ * 1. configuredPath 参数（来自 manifest 配置）
+ * 2. 环境变量 AGENTDEV_POWERSHELL_PATH
+ * 3. pwsh（PowerShell 7+，跨平台）
+ * 4. powershell.exe（Windows PowerShell 5.1）
+ * 5. Windows 已知系统路径
+ *
+ * 返回 null 表示未找到。
+ */
+declare function findPowerShellPath(configuredPath?: string): string | null;
+interface PowerShellToolOptions {
+    workspaceDir?: string;
+    workdir?: string;
+    resourceRoot?: string;
+    /** 已检测到的 PowerShell 路径 */
+    psPath?: string;
+    /** 覆盖默认超时（manifest 配置 defaultTimeoutMs）；缺省 120000 */
+    timeoutMs?: number;
+    /** 覆盖超时上限（manifest 配置 maxTimeoutMs）；缺省 600000 */
+    maxTimeoutMs?: number;
+}
+/**
+ * 运行 PowerShell 命令（支持 AbortSignal 中断；终止时收集部分输出并附元数据块）
+ */
+declare function runPowerShellCommand(command: string, options?: PowerShellToolOptions, context?: ShellRunContext): Promise<{
+    stdout: string;
+    stderr: string;
+    output: string;
+}>;
+declare function createPowerShellTool(description: string, options?: PowerShellToolOptions): Tool;
+
+/**
+ * Shell command quoting utilities.
+ *
+ * Ported from Claude Code's shellQuoting.ts + shellQuote.ts.
+ *
+ * 核心思路：用单引号整体包裹命令字符串，使所有特殊字符（括号、管道符、
+ * 分号、$、反引号等）被 bash 视为字面量。然后通过 `eval` 进行二次解析。
+ *
+ * 这彻底解决了 `syntax error near unexpected token '('` 问题：
+ *   - 旧方案：command.replace(/"/g, '\\"') 只转义双引号，
+ *     导致 `(`, `)`, `;`, `|` 等裸露在 bash 面前
+ *   - 新方案：单引号包裹整个命令，eval 二次解析
+ */
+/**
+ * 检测命令是否包含 heredoc 语法（<<EOF, <<'EOF', <<"EOF", <<-EOF 等）。
+ * 排除位运算左移（<<）的误判。
+ */
+declare function containsHeredoc(command: string): boolean;
+/**
+ * 检测命令是否已有 stdin 重定向（如 < file, </path, < /dev/null）。
+ * 排除 << (heredoc)、<< (位运算)、<(进程替换)。
+ */
+declare function hasStdinRedirect(command: string): boolean;
+/**
+ * 判断是否应该为命令添加 `< /dev/null` stdin 重定向。
+ *
+ * - heredoc 命令不需要（它们有自己的输入）
+ * - 已有 stdin 重定向的命令不需要
+ */
+declare function shouldAddStdinRedirect(command: string): boolean;
+declare function rewriteWindowsNullRedirect(command: string): string;
+/**
+ * 对 shell 命令进行安全引用，保留 heredoc 和多行字符串的完整性。
+ *
+ * 返回的字符串可直接用于 `eval`，例如：
+ *   const quoted = quoteShellCommand('echo "hello (world)"');
+ *   // quoted === "'echo \"hello (world)\"' < /dev/null"
+ *   // 完整命令: eval 'echo "hello (world)"' < /dev/null
+ *
+ * @param command 要引用的原始命令
+ * @param addStdinRedirect 是否追加 `< /dev/null` stdin 重定向
+ * @returns 安全引用后的命令字符串
+ */
+declare function quoteShellCommand(command: string, addStdinRedirect?: boolean): string;
+
+/**
+ * Safe Trash 工具定义
+ */
+
+declare function createSafeTrashDeleteTool(workspaceDir?: string): Tool;
+declare function createSafeTrashListTool(workspaceDir?: string): Tool;
+declare function createSafeTrashRestoreTool(workspaceDir?: string): Tool;
+declare const safeTrashDeleteTool: Tool;
+declare const safeTrashListTool: Tool;
+declare const safeTrashRestoreTool: Tool;
+
+/**
+ * 已删除文件的信息
+ */
+interface TrashedFileInfo {
+    index: number;
+    originalPath: string;
+    deletionDate: string;
+    operator: string | null;
+    trashFile: string;
+    infoFile: string;
+    size: number;
+}
+/**
+ * 恢复结果
+ */
+interface RestoreResult {
+    success: boolean;
+    restored: string[];
+    failed: Array<{
+        path: string;
+        error: string;
+    }>;
+    skipped: string[];
+    restoredCount: number;
+    failedCount: number;
+    skippedCount: number;
+}
+/**
+ * 删除操作结果
+ */
+interface SafeRmResult {
+    success: boolean;
+    moved: string[];
+    failed: string[];
+    movedCount: number;
+    failedCount: number;
+}
+/**
+ * 列表操作结果
+ */
+interface ListResult {
+    success: boolean;
+    total: number;
+    files: TrashedFileInfo[];
+}
+/**
+ * 恢复目标类型
+ */
+type RestoreTarget = number | string | number[] | string[];
+
+/**
+ * SafeRm - 安全删除核心逻辑
+ */
+
+declare function safeRm(workingDir: string | null, rmCommand: string, trashDir: string, operator?: string | null, verbose?: number): SafeRmResult;
+
+/**
+ * SafeRestore - 安全恢复核心逻辑
+ */
+
+declare function listTrashed(trashDir: string, operator?: string | null): ListResult;
+declare function restore(trashDir: string, target: RestoreTarget, operator?: string | null, overwrite?: boolean, dryRun?: boolean, parseIndexRanges?: boolean): RestoreResult;
+
+/**
+ * Shell Feature - 独立 npm 包
+ *
+ * 支持 Bash（Windows: Git Bash / Linux/macOS: 原生 bash）和 PowerShell 两种 Shell 环境。
+ * 根据用户配置和运行时探测结果，条件注册 Bash 和/或 PowerShell 工具。
+ *
+ * @example
+ * ```typescript
+ * import { ShellFeature } from '@agentdevjs/shell-feature';
+ * import { BasicAgent } from '@agentdevjs/core';
+ *
+ * const agent = new BasicAgent().use(new ShellFeature());
+ * ```
+ */
+
+interface ShellFeatureConfig {
+    workspaceDir?: string;
+    workdir?: string;
+    resourceRoot?: string;
+}
+/**
+ * Shell Feature 实现
+ */
+declare class ShellFeature implements AgentFeature {
+    readonly name = "shell";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u63D0\u4F9B Bash/PowerShell \u547D\u4EE4\u6267\u884C\u80FD\u529B\uFF0C\u4EE5\u53CA\u5B89\u5168\u5220\u9664\u3001\u6062\u590D\u548C\u67E5\u770B\u5783\u573E\u6876\u5DE5\u5177\u3002";
+    private bashDescription?;
+    private powershellDescription?;
+    private _packageInfo;
+    private readonly workspaceDir;
+    private readonly workdir;
+    private readonly resourceRoot;
+    constructor(config?: ShellFeatureConfig);
+    /**
+     * 获取同步工具（垃圾桶工具）
+     */
+    getTools(): Tool[];
+    getFeatureManifest(): FeatureManifestDefinition;
+    private resolveShellConfig;
+    /**
+     * 获取异步工具（bash/powershell 工具，条件注册）
+     */
+    getAsyncTools(ctx: FeatureInitContext): Promise<Tool[]>;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+}
+
+export { SHELL_METADATA_CLOSE, SHELL_METADATA_OPEN, type ShellCommandToolOptions, type ShellExecutionResult, ShellFeature, type ShellFeatureConfig, type ShellMetadataFields, type ShellRunResult, containsHeredoc, createPowerShellTool, createSafeTrashDeleteTool, createSafeTrashListTool, createSafeTrashRestoreTool, createShellCommandTool, findGitBashPath, findPowerShellPath, formatShellMetadata, hasStdinRedirect, listTrashed, processOutputWithPersistence, quoteShellCommand, restore, rewriteWindowsNullRedirect, runPowerShellCommand, runShellCommand, safeRm, safeTrashDeleteTool, safeTrashListTool, safeTrashRestoreTool, shouldAddStdinRedirect };