dsh-tool-ast-grep 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jaylor Wang (Jaylor-Wang)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# dsh-tool-ast-grep
+
+[English](README.md) | [中文](README.zh.md)
+
+**AST-based structural code search and outline plugin for DeepSeek Harness (DSH)**, powered by [ast-grep](https://ast-grep.github.io/).
+
+Provides structural code searching and outline inspection capabilities for coding agents, dramatically outperforming traditional regular expression search (`grep`) in token efficiency and semantic accuracy.
+
+---
+
+## Features
+
+- **`ast_search`**: Search code structures using AST patterns and meta-variables (`$NAME`, `$$$`).
+  - Finds structural patterns across multiple lines regardless of formatting or whitespace.
+  - Supports node kind queries (e.g. `function_declaration`, `interface_declaration`, `class_declaration`).
+  - Supports strictness modes (`smart`, `relaxed`, `ast`, `cst`).
+  - Supports file path and glob filtering.
+- **`ast_outline`**: Extract an ultra-compact structural outline (functions, classes, types, interfaces, exports) from a source file.
+  - Saves 80%–95% tokens compared to reading the entire file.
+  - Supports depth control (top-level vs. nested methods).
+- **Zero Shell Quoting Issues**: Invoked safely via child processes with JSON streaming — immune to Windows shell argument escaping and quoting pitfalls.
+
+---
+
+## Prerequisites
+
+This plugin requires `ast-grep` CLI installed on your machine:
+
+- **npm**:
+  ```bash
+  npm install -g @ast-grep/cli
+  ```
+- **pip**:
+  ```bash
+  pip install ast-grep-cli
+  ```
+- **cargo**:
+  ```bash
+  cargo install ast-grep --locked
+  ```
+- **brew** (macOS/Linux):
+  ```bash
+  brew install ast-grep
+  ```
+
+Verify with:
+```bash
+ast-grep --version
+```
+
+---
+
+## Installation in DSH
+
+### Option 1: Via DSH Market (Recommended)
+
+Once published and indexed, search for `dsh-tool-ast-grep` in **Settings → Plugin Market** and click **Install**.
+
+Or run in terminal:
+```bash
+dsh plugin --profile web add dsh-tool-ast-grep
+```
+
+### Option 2: Mount in an Agent Preset
+
+In your agent configuration (e.g. `~/.dsh/.agent-presets/your-agent/agent.cordis.yml`):
+
+```yaml
+id: my-agent
+name: My Agent
+tools:
+  - id: tool-ast-grep
+    name: dsh-tool-ast-grep
+    config:
+      maxResults: 50
+      timeoutMs: 60000
+```
+
+---
+
+## Tool API Overview
+
+### 1. `ast_search`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `pattern` | `string` | AST pattern, e.g. `function $NAME($$$) { $$$ }` or `$OBJ.push($ITEM)` |
+| `kind` | `string` | AST node kind, e.g. `class_declaration`, `function_declaration` |
+| `path` | `string` | Directory or file path to search in (defaults to workspace root) |
+| `lang` | `string` | Language override (`ts`, `tsx`, `js`, `jsx`, `python`, `rust`, `go`, etc.) |
+| `globs` | `string` | File glob pattern to include/exclude (e.g. `src/**/*.ts`) |
+| `limit` | `integer` | Max matches to return (default: 50) |
+
+### 2. `ast_outline`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `file_path` | `string` | Path of the file to inspect |
+| `lang` | `string` | Language override (auto-detected if omitted) |
+| `depth` | `integer` | `1` for top-level only (default), `2` to include class methods |
+
+---
+
+## Supported Languages
+
+TypeScript (`ts`, `tsx`), JavaScript (`js`, `jsx`), Python (`py`), Rust (`rs`), Go (`go`), Java (`java`), C (`c`, `h`), C++ (`cpp`, `hpp`, `cc`).
+
+---
+
+## License
+
+MIT © Jaylor Wang (Jaylor-Wang)

package/README.zh.md

@@ -0,0 +1,114 @@
+# dsh-tool-ast-grep
+
+[English](README.md) | 中文
+
+**专为 DeepSeek Harness (DSH) 打造的语法级 AST 代码检索与大纲提取插件**，基于 Rust 高性能语法解析工具 [ast-grep](https://ast-grep.github.io/) 驱动。
+
+为 Coding Agent 提供精准的代码语法树（AST）检索能力与文件架构提取能力，在语义精度和 Token 消耗控制上彻底超越传统的纯文本正则搜索（`grep`）。
+
+---
+
+## 核心特性
+
+- **`ast_search`（AST 结构化检索）**：
+  - 使用 AST 模式语法与元变量（如 `$NAME` 匹配单节点，`$$$` 匹配任意多节点/参数）精准定位目标代码。
+  - 语法无关排版：不论是单行书写、换行还是空格格式差异，均能准确匹配。
+  - 支持节点类型（Kind）检索（如 `class_declaration`, `interface_declaration`, `method_definition`）。
+  - 支持严格度模式（`smart`, `relaxed`, `ast`, `cst`）及文件 Glob 过滤。
+- **`ast_outline`（极速代码大纲提取）**：
+  - 一键提取源码文件的结构化大纲（顶层函数、类、接口、类型别名、导出语句）。
+  - 相比把整个长文件塞进大模型上下文，**可节省 80%–95% 的 Token 消耗**。
+  - 支持深度控制：默认只看顶层接口，可展开类内部方法与构造函数。
+- **消灭 Shell 引号与转义地狱**：
+  - 采用 Node.js 原生参数列表调用，彻底规避 Windows Shell 下特殊字符（如 `$VAR` 被吞、引号被截断）引发的运行报错。
+
+---
+
+## 前置要求
+
+使用本插件需要在系统中安装 `ast-grep` 命令行工具（二选一即可）：
+
+- **通过 npm 全局安装**：
+  ```bash
+  npm install -g @ast-grep/cli
+  ```
+- **通过 Python pip 安装**：
+  ```bash
+  pip install ast-grep-cli
+  ```
+- **通过 Cargo 安装 (Rust)**：
+  ```bash
+  cargo install ast-grep --locked
+  ```
+- **macOS / Homebrew**：
+  ```bash
+  brew install ast-grep
+  ```
+
+验证安装：
+```bash
+ast-grep --version
+```
+
+---
+
+## 在 DeepSeek Harness 中安装
+
+### 方式 1：通过插件市场一键安装（推荐）
+
+在 Web UI 导航至 **设置 → 插件市场**，搜索 `dsh-tool-ast-grep`，点击安装即可。
+
+或在终端中运行：
+```bash
+dsh plugin --profile web add dsh-tool-ast-grep
+```
+
+### 方式 2：在智能体预设（Preset）中引入
+
+在你的预设文件（如 `~/.dsh/.agent-presets/my-agent/agent.cordis.yml`）中挂载：
+
+```yaml
+id: my-agent
+name: My Agent
+tools:
+  - id: tool-ast-grep
+    name: dsh-tool-ast-grep
+    config:
+      maxResults: 50
+      timeoutMs: 60000
+```
+
+---
+
+## 工具参数说明
+
+### 1. `ast_search`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `pattern` | `string` | AST 匹配模式，如 `function $NAME($$$) { $$$ }` 或 `$OBJ.push($ITEM)` |
+| `kind` | `string` | AST 语法节点类型，如 `class_declaration`, `function_declaration` |
+| `path` | `string` | 搜索的目标目录或文件路径（默认为工作区根目录） |
+| `lang` | `string` | 指定语言（`ts`, `tsx`, `js`, `jsx`, `python`, `rust`, `go` 等） |
+| `globs` | `string` | 文件过滤规则（如 `src/**/*.ts` 或 `!**/*.test.ts`） |
+| `limit` | `integer` | 最大返回条数（默认 50） |
+
+### 2. `ast_outline`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `file_path` | `string` | 目标源码文件路径（相对路径或绝对路径） |
+| `lang` | `string` | 指定语言（如省略则根据文件后缀自动推断） |
+| `depth` | `integer` | 大纲深度：`1` 仅展示顶层定义（默认），`2` 展开类方法与构造器 |
+
+---
+
+## 支持的语言
+
+TypeScript (`ts`, `tsx`), JavaScript (`js`, `jsx`), Python (`py`), Rust (`rs`), Go (`go`), Java (`java`), C (`c`, `h`), C++ (`cpp`, `hpp`, `cc`)。
+
+---
+
+## 许可证
+
+MIT © Jaylor Wang (Jaylor-Wang)

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-tool-ast-grep bundle patch: inserts AST tools into profile layer stack
+- insert:
+    - id: tool-ast-grep
+      name: dsh-tool-ast-grep
+      inject: [tools]
+      config:
+        maxResults: 50
+        timeoutMs: 60000

package/index.js

@@ -0,0 +1,439 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import path from "path";
+import fs from "fs";
+
+const execFileAsync = promisify(execFile);
+
+export const name = "dsh-tool-ast-grep";
+export const Config = z.object({
+  maxResults: z.number().default(50).description("Maximum search results to return"),
+  timeoutMs: z.number().default(60000).description("Execution timeout in milliseconds"),
+});
+
+export const inject = ["tools"];
+
+const OUTLINE_KINDS = {
+  ts: {
+    topLevel:
+      "function_declaration, generator_function_declaration, class_declaration, abstract_class_declaration, interface_declaration, type_alias_declaration, enum_declaration, export_statement, lexical_declaration",
+    nested: "method_definition, public_field_definition",
+  },
+  tsx: {
+    topLevel:
+      "function_declaration, generator_function_declaration, class_declaration, abstract_class_declaration, interface_declaration, type_alias_declaration, enum_declaration, export_statement, lexical_declaration",
+    nested: "method_definition, public_field_definition",
+  },
+  js: {
+    topLevel:
+      "function_declaration, generator_function_declaration, class_declaration, export_statement, lexical_declaration, variable_declaration",
+    nested: "method_definition",
+  },
+  jsx: {
+    topLevel:
+      "function_declaration, generator_function_declaration, class_declaration, export_statement, lexical_declaration, variable_declaration",
+    nested: "method_definition",
+  },
+  python: {
+    topLevel:
+      "function_definition, async_function_definition, class_definition, decorated_definition",
+    nested: "function_definition, async_function_definition",
+  },
+  rust: {
+    topLevel:
+      "function_item, struct_item, enum_item, trait_item, impl_item, type_item, mod_item, macro_definition",
+    nested: "function_item",
+  },
+  go: {
+    topLevel: "function_declaration, method_declaration, type_declaration",
+    nested: "method_declaration",
+  },
+  java: {
+    topLevel: "class_declaration, interface_declaration, enum_declaration",
+    nested: "method_declaration, constructor_declaration",
+  },
+  c: {
+    topLevel: "function_definition, struct_specifier, enum_specifier, type_definition",
+    nested: "field_declaration",
+  },
+  cpp: {
+    topLevel: "function_definition, class_specifier, struct_specifier, enum_specifier, type_definition",
+    nested: "function_definition, field_declaration",
+  },
+};
+
+function detectLang(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  switch (ext) {
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return "js";
+    case ".jsx":
+      return "jsx";
+    case ".py":
+    case ".pyi":
+      return "python";
+    case ".rs":
+      return "rust";
+    case ".go":
+      return "go";
+    case ".java":
+      return "java";
+    case ".c":
+    case ".h":
+      return "c";
+    case ".cpp":
+    case ".hpp":
+    case ".cc":
+    case ".cxx":
+      return "cpp";
+    default:
+      return null;
+  }
+}
+
+function truncateSnippet(text, maxLines = 8) {
+  const lines = text.split("\n");
+  if (lines.length <= maxLines) {
+    return lines.map((l) => "    " + l).join("\n");
+  }
+  const head = lines.slice(0, 4).map((l) => "    " + l);
+  const tail = lines.slice(-2).map((l) => "    " + l);
+  const omitted = lines.length - 6;
+  return [...head, `    ... (${omitted} lines omitted) ...`, ...tail].join("\n");
+}
+
+let cachedAstGrepBinary = null;
+
+function resolveBinary() {
+  if (cachedAstGrepBinary) return cachedAstGrepBinary;
+
+  // 1. Check direct binary in PATH
+  const binaryName = process.platform === "win32" ? "ast-grep.exe" : "ast-grep";
+  
+  // 2. Check common paths on Windows
+  if (process.platform === "win32") {
+    const userProfile = process.env.USERPROFILE || "";
+    const localAppData = process.env.LOCALAPPDATA || "";
+    const candidates = [
+      binaryName,
+      path.join(userProfile, "AppData", "Local", "Programs", "Python", "Python313", "Scripts", "ast-grep.exe"),
+      path.join(userProfile, "AppData", "Local", "Programs", "Python", "Python312", "Scripts", "ast-grep.exe"),
+      path.join(userProfile, "AppData", "Local", "Programs", "Python", "Python311", "Scripts", "ast-grep.exe"),
+      path.join(localAppData, "Programs", "Python", "Python313", "Scripts", "ast-grep.exe"),
+      path.join(userProfile, "AppData", "Roaming", "npm", "ast-grep.cmd"),
+      path.join(userProfile, "AppData", "Roaming", "npm", "ast-grep.exe"),
+      path.join(userProfile, ".cargo", "bin", "ast-grep.exe"),
+    ];
+
+    for (const cand of candidates) {
+      if (cand === binaryName) continue;
+      if (fs.existsSync(cand)) {
+        cachedAstGrepBinary = cand;
+        return cand;
+      }
+    }
+  }
+
+  cachedAstGrepBinary = binaryName;
+  return binaryName;
+}
+
+async function runAstGrep(args, cwd, signal, timeoutMs = 60000) {
+  const binary = resolveBinary();
+  try {
+    const res = await execFileAsync(binary, args, {
+      cwd,
+      signal,
+      timeout: timeoutMs,
+      maxBuffer: 20 * 1024 * 1024,
+      windowsHide: true,
+    });
+    return res.stdout || "[]";
+  } catch (err) {
+    if (err.code === 1 && typeof err.stdout === "string" && err.stdout.trim().startsWith("[")) {
+      return err.stdout;
+    }
+    if (err.name === "AbortError" || signal?.aborted) {
+      throw err;
+    }
+    if (err.code === "ENOENT" || err.message?.includes("ENOENT")) {
+      throw new Error(
+        `ast-grep binary was not found in PATH or standard directories.\n` +
+          `Please install ast-grep to use this plugin:\n` +
+          `- npm:  npm install -g @ast-grep/cli\n` +
+          `- pip:  pip install ast-grep-cli\n` +
+          `- cargo: cargo install ast-grep --locked\n` +
+          `- brew: brew install ast-grep (macOS/Linux)`
+      );
+    }
+    const errText = err.stderr?.trim() || err.message;
+    throw new Error(`ast-grep execution failed: ${errText}`);
+  }
+}
+
+export function apply(ctx, config = {}) {
+  const maxResultsDefault = config.maxResults || 50;
+  const timeoutMsDefault = config.timeoutMs || 60000;
+
+  const systemPrompt = ctx.get("systemPrompt");
+  if (systemPrompt) {
+    try {
+      systemPrompt.section({
+        name: "tool:ast-grep",
+        order: systemPrompt.getSectionOrder?.("TOOLS_SDK") ?? 5000,
+        text: "When searching for code structures (e.g. function/class/interface definitions, API usages) or inspecting file outline, prefer `ast_search` and `ast_outline` over plain-text grep or reading entire files. Use $VAR for single nodes and $$$ for multi-node wildcards.",
+      });
+    } catch {
+      // safe fallback if systemPrompt not mounted
+    }
+  }
+
+  // 1. ast_search
+  ctx.tools.register(
+    defineTool({
+      name: "ast_search",
+      description:
+        "Perform structural AST code search across the workspace or a directory using ast-grep. Matches code by syntax tree patterns instead of regex strings. Use $VAR for single node meta-variables (e.g. $NAME) and $$$ for multiple nodes/statements/arguments. Example patterns: 'function $NAME($$$) { $$$ }', 'interface $NAME { $$$ }', 'class $NAME extends $BASE { $$$ }', '$OBJ.push($ITEM)'.",
+      parameters: {
+        pattern: {
+          type: "string",
+          description:
+            "AST pattern to match. Use $VAR for single node meta-variables and $$$ for wildcard nodes. Example: 'function $NAME($$$) { $$$ }'. Either pattern or kind must be provided.",
+        },
+        kind: {
+          type: "string",
+          description:
+            "AST node kind to match (e.g. 'function_declaration', 'class_declaration', 'interface_declaration', 'method_definition').",
+        },
+        selector: {
+          type: "string",
+          description:
+            "Sub-syntax node kind selector for the pattern (see ast-grep --selector).",
+        },
+        path: {
+          type: "string",
+          description: "Target directory or file path. Defaults to workspace root.",
+        },
+        lang: {
+          type: "string",
+          description:
+            "Programming language (ts, tsx, js, jsx, rust, python, go, c, cpp, java). Auto-detected if omitted.",
+        },
+        globs: {
+          type: "string",
+          description: 'File glob pattern to filter, e.g. "src/**/*.ts" or "!**/*.test.ts".',
+        },
+        strictness: {
+          type: "string",
+          description:
+            'Strictness mode: "smart" (default), "cst", "ast", "relaxed", "signature", "template".',
+        },
+        limit: {
+          type: "integer",
+          description: "Maximum number of matches to return (default 50).",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            text: { type: "string", required: true },
+          },
+        },
+        render: (_args, value) => [{ type: "text", text: value.text }],
+      },
+      async execute(args, exec) {
+        if (!args.pattern && !args.kind) {
+          throw new Error("ast_search requires either 'pattern' or 'kind' to be specified.");
+        }
+        const cwd = exec.agent?.session?.header?.cwd ?? process.cwd();
+        const limit = args.limit || maxResultsDefault;
+        const targetPath = args.path ? path.resolve(cwd, args.path) : cwd;
+
+        const cmdArgs = ["run", "--json=compact"];
+        if (args.pattern) cmdArgs.push("--pattern", args.pattern);
+        if (args.kind) cmdArgs.push("--kind", args.kind);
+        if (args.selector) cmdArgs.push("--selector", args.selector);
+        if (args.lang) cmdArgs.push("--lang", args.lang);
+        if (args.globs) cmdArgs.push("--globs", args.globs);
+        if (args.strictness) cmdArgs.push("--strictness", args.strictness);
+        cmdArgs.push(targetPath);
+
+        const rawJson = await runAstGrep(cmdArgs, cwd, exec.signal, timeoutMsDefault);
+        let matches = [];
+        try {
+          matches = JSON.parse(rawJson);
+        } catch {
+          matches = [];
+        }
+
+        if (matches.length === 0) {
+          const query = args.pattern ? `pattern '${args.pattern}'` : `kind '${args.kind}'`;
+          return { text: `No AST matches found for ${query}` };
+        }
+
+        const total = matches.length;
+        const sliced = matches.slice(0, limit);
+
+        // Group by file
+        const byFile = new Map();
+        for (const m of sliced) {
+          const rel = path.relative(cwd, m.file).replace(/\\/g, "/");
+          const list = byFile.get(rel) || [];
+          list.push(m);
+          byFile.set(rel, list);
+        }
+
+        const sections = [];
+        for (const [filePath, fileMatches] of byFile) {
+          const lines = [`### ${filePath}`];
+          for (const m of fileMatches) {
+            const startLine = m.range.start.line + 1;
+            const endLine = m.range.end.line + 1;
+            const lineStr = startLine === endLine ? `Line ${startLine}` : `Lines ${startLine}-${endLine}`;
+
+            // Meta variables summary
+            let metaStr = "";
+            if (m.metaVariables?.single) {
+              const vars = Object.entries(m.metaVariables.single)
+                .map(([k, v]) => `$${k} = ${JSON.stringify(v.text)}`)
+                .join(", ");
+              if (vars) metaStr = ` [${vars}]`;
+            }
+
+            lines.push(`- **${lineStr}**${metaStr}:\n${truncateSnippet(m.text)}`);
+          }
+          sections.push(lines.join("\n"));
+        }
+
+        let output = sections.join("\n\n");
+        if (total > limit) {
+          output += `\n\n(Showing ${limit} of ${total} matches. Narrow your search with \`path\` or \`globs\` if needed.)`;
+        }
+        return { text: output };
+      },
+    })
+  );
+
+  // 2. ast_outline
+  ctx.tools.register(
+    defineTool({
+      name: "ast_outline",
+      description:
+        "Extract a concise structural outline (functions, classes, interfaces, types, exports) from a source file using AST. Much faster and saves significant tokens compared to reading the entire file.",
+      parameters: {
+        file_path: {
+          type: "string",
+          required: true,
+          description: "Path of the source file to inspect (relative to workspace or absolute).",
+        },
+        lang: {
+          type: "string",
+          description: "Language override (ts, tsx, js, jsx, rust, python, go, java, c, cpp).",
+        },
+        depth: {
+          type: "integer",
+          description:
+            "Outline depth: 1 for top-level definitions only (default), 2 to include class methods and inner declarations.",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            text: { type: "string", required: true },
+          },
+        },
+        render: (_args, value) => [{ type: "text", text: value.text }],
+      },
+      async execute(args, exec) {
+        const cwd = exec.agent?.session?.header?.cwd ?? process.cwd();
+        const filePath = path.isAbsolute(args.file_path)
+          ? args.file_path
+          : path.resolve(cwd, args.file_path);
+
+        if (!fs.existsSync(filePath)) {
+          throw new Error(`File not found: ${args.file_path}`);
+        }
+
+        const lang = args.lang || detectLang(filePath);
+        if (!lang) {
+          throw new Error(
+            `Unable to determine language for ${args.file_path}. Please provide the 'lang' parameter.`
+          );
+        }
+
+        const langConfig = OUTLINE_KINDS[lang];
+        if (!langConfig) {
+          throw new Error(`Unsupported outline language: ${lang}`);
+        }
+
+        const depth = args.depth || 1;
+        let kinds = langConfig.topLevel;
+        if (depth >= 2 && langConfig.nested) {
+          kinds = `${langConfig.topLevel}, ${langConfig.nested}`;
+        }
+
+        const cmdArgs = ["run", "--kind", kinds, "--lang", lang, "--json=compact", filePath];
+        const rawJson = await runAstGrep(cmdArgs, cwd, exec.signal, timeoutMsDefault);
+
+        let items = [];
+        try {
+          items = JSON.parse(rawJson);
+        } catch {
+          items = [];
+        }
+
+        if (items.length === 0) {
+          return { text: `No outline symbols found in ${args.file_path}` };
+        }
+
+        items.sort(
+          (a, b) =>
+            a.range.start.line - b.range.start.line || a.range.start.column - b.range.start.column
+        );
+
+        const lines = [`Outline for \`${path.relative(cwd, filePath).replace(/\\/g, "/")}\` (${lang}):`];
+        const seenLines = new Set();
+
+        for (const item of items) {
+          const col = item.range.start.column;
+          if (depth === 1 && col > 2) {
+            continue;
+          }
+
+          const startLine = item.range.start.line + 1;
+          const endLine = item.range.end.line + 1;
+
+          if (seenLines.has(startLine)) continue;
+          seenLines.add(startLine);
+
+          const rawFirstLine = item.text.split("\n")[0].trim();
+          const cleanSig = rawFirstLine.replace(/\{$/, "").replace(/:$/, "").trim();
+
+          const indent = col > 2 ? "  └─ " : "- ";
+          const lineRef = startLine === endLine ? `Line ${startLine}` : `Lines ${startLine}-${endLine}`;
+          lines.push(`${indent}**${lineRef}**: \`${cleanSig}\``);
+        }
+
+        if (lines.length === 1) {
+          return { text: `No top-level outline symbols matched in ${args.file_path}` };
+        }
+
+        return { text: lines.join("\n") };
+      },
+    })
+  );
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "dsh-tool-ast-grep",
+  "version": "0.1.0",
+  "description": "AST-based structural code search and syntax outline tool for DeepSeek Harness powered by ast-grep",
+  "type": "module",
+  "main": "index.js",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "ast-grep",
+    "ast",
+    "code-search",
+    "outline"
+  ],
+  "author": "Jaylor-Wang",
+  "license": "MIT",
+  "homepage": "https://github.com/Jaylor-Wang/dsh-tool-ast-grep#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jaylor-Wang/dsh-tool-ast-grep.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Jaylor-Wang/dsh-tool-ast-grep/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ]
+}