termdock-ast

name	termdock-ast
description	Use the Termdock AST API to locate symbols, dependencies, callers/callees, or impact before exploring unknown code. Skip when the user gives an exact file path or only needs a literal string search.

Termdock AST API

When to Use This Skill

Use AST API first when:

• The user asks "where is X", "who calls X", "what does X call", or "what depends on X"
• You need a file path or symbol ownership before editing
• You expect a change to touch multiple files or affect behavior
• You are about to run broad search without a known target

Skip AST API when:

• The user provides an exact file path or a snippet to edit
• The task is doc-only or config-only (SKILL.md, README, settings)
• You only need a literal-string search

Default rule: Use AST for discovery and impact; skip it for known-file edits.

If API is unavailable: Fall back to rg/rg --files and note the limitation.

---

Quick Start

Step 1: Get Workspace ID (Required First)

curl -s 'http://localhost:3033/api/workspaces' | jq '.data.workspaces[0].id'

Save this ID for all subsequent calls.

Step 2: Choose Your Query Type

Goal	API	Example
Find symbol by name	/api/search	"Where is UserService?"
See file imports/exports	/api/graph/deps	"What does this file import?"
Find callers	/api/graph/callers	"Who calls this function?"
Find callees	/api/graph/calls	"What does this function call?"
Impact analysis	/api/impact	"What breaks if I change this?"

---

API Reference

1. Search Symbols

curl 'http://localhost:3033/api/search?q=<name>&workspace=<wsId>&limit=10'

Response fields:

• symbolId: Use for callers/calls queries
• file: Absolute path
• line: 0-indexed (add 1 for display)
• type: 5=Class, 6=Method, 11=Interface, 12=Function

2. File Dependencies

curl 'http://localhost:3033/api/graph/deps?file=src/path/to/file.ts&workspace=<wsId>'

Returns: imports (what this file uses) and exports (what it provides)

3. Who Calls This?

curl 'http://localhost:3033/api/graph/callers?to=<symbolId>&workspace=<wsId>'

4. What Does This Call?

curl 'http://localhost:3033/api/graph/calls?from=<symbolId>&workspace=<wsId>'

5. Impact Analysis

curl 'http://localhost:3033/api/impact?symbolId=<id>&depth=2&workspace=<wsId>'

Returns all symbols and files affected by changing this symbol.

---

Decision Flowchart

User asks about code
        |
        v
Is it a "where is X?" question?
    |yes              |no
    v                 v
/api/search      Is it about dependencies?
    |                 |yes         |no
    v                 v            v
Got symbolId?    /api/graph/deps  Is it about call chain?
    |yes                              |yes         |no
    v                                 v            v
Need callers? -----> /api/graph/callers   Use other tools
Need callees? -----> /api/graph/calls
Need impact?  -----> /api/impact

---

Common Patterns

Pattern A: Find and Understand a Class

# 1. Find it
curl 'http://localhost:3033/api/search?q=TerminalService&workspace=ws_xxx&limit=1'
# Note: symbolId, file

# 2. See dependencies
curl 'http://localhost:3033/api/graph/deps?file=src/main/services/TerminalService.ts&workspace=ws_xxx'

# 3. Now read the file with context

Pattern B: Trace Usage

# 1. Find function
curl 'http://localhost:3033/api/search?q=createSession&workspace=ws_xxx&limit=5'
# Pick the right symbolId

# 2. Find all callers
curl 'http://localhost:3033/api/graph/callers?to=<symbolId>&workspace=ws_xxx'

Pattern C: Safe Refactoring

# Before changing a function, check impact
curl 'http://localhost:3033/api/impact?symbolId=<id>&depth=2&workspace=ws_xxx'
# Review impactedFiles before making changes

---

Error Handling

Error	Cause	Action
No workspace found	API not running	Start Termdock app
Empty search results	Symbol not indexed	Try partial name or rebuild index
404 on symbolId	Stale ID after code change	Re-search to get new ID

Rebuild index after code changes:

curl -X POST 'http://localhost:3033/api/index/update' -H 'Content-Type: application/json' -d '{"workspace":"<wsId>"}'

---

Response Format

All APIs return:

{
  "success": true|false,
  "data": {...},
  "error": {"code": "...", "message": "..."}
}

Always check success before using data.

---

Key Notes

1. Line numbers are 0-indexed - Add 1 when showing to users
2. Use relative paths for /api/graph/deps (e.g., src/main/...)
3. Symbol IDs are stable until code changes
4. API base: http://localhost:3033 (prod) or :3032 (dev)