@gotza02/sequential-thinking 2026.1.23 → 2026.1.25

package/README.md

@@ -24,70 +24,117 @@ When connected to this server, you should follow these guidelines to maximize pr
 4.  **Local Execution**: Use `shell_execute` to run tests, linters, or build commands to verify your changes. Always read files using `read_file` before attempting to write or modify them.
 5.  **Persistence**: The thinking process is saved automatically. You can resume previous sessions by reviewing the `thoughts_history.json` file if needed.
 
-## Tool
+## Detailed Tool Guide
 
-### sequentialthinking
+### 🧠 Cognitive Tools
 
-Facilitates a detailed, step-by-step thinking process for problem-solving and analysis.
+#### `sequentialthinking`
+The core engine for structured problem-solving. It forces a step-by-step analysis before arriving at a conclusion.
 
-**(See inputs above)**
+**Inputs:**
+- `thought` (string, required): The content of the current thinking step.
+- `thoughtNumber` (integer, required): Current step number (starts at 1).
+- `totalThoughts` (integer, required): Estimated total steps needed (can be adjusted dynamically).
+- `nextThoughtNeeded` (boolean, required): `true` if you need to think more, `false` only when the final answer is ready.
+- `thoughtType` (enum): The nature of the thought:
+  - `analysis`: Breaking down the problem.
+  - `generation`: Brainstorming solutions.
+  - `evaluation`: Weighing options (use with `score`).
+  - `reflexion`: Reviewing previous thoughts (use with `isRevision`).
+  - `selection`: Choosing a path.
+- `isRevision` (boolean): Set to `true` if you are correcting a previous mistake.
+- `revisesThought` (integer): The thought number you are fixing.
+- `branchFromThought` (integer): The parent thought number if creating a new reasoning branch.
+- `branchId` (string): A name for the new branch.
+
+**Best Practice:** Use this for ANY non-trivial task. Don't just answer; think first.
+
+### 🌐 External Knowledge
+
+#### `web_search`
+Retrieves real-time information from the internet.
 
-### web_search
+**Inputs:**
+- `query` (string, required): What you want to find.
+- `provider` (enum, optional):
+  - `brave`: General web search (Requires `BRAVE_API_KEY`).
+  - `exa`: AI-optimized search for deep content (Requires `EXA_API_KEY`).
+  - `google`: Google Custom Search (Requires `GOOGLE_SEARCH_API_KEY` & `GOOGLE_SEARCH_CX`).
 
-Search the web using Brave or Exa APIs.
+#### `fetch`
+Performs a direct HTTP request to a URL. Useful for getting raw HTML, JSON, or text from a specific source found via search.
 
 **Inputs:**
-- `query` (string): The search query.
-- `provider` (enum, optional): 'brave', 'exa', or 'google'.
-
-**Configuration:**
-Requires one of the following environment variable sets:
-- `BRAVE_API_KEY` (for Brave Search)
-- `EXA_API_KEY` (for Exa Search)
-- `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_CX` (for Google Custom Search)
+- `url` (string, required): The target URL.
+- `method`: `GET` (default), `POST`, `PUT`, `DELETE`.
+- `headers`: JSON object for headers (e.g., `{"Authorization": "Bearer..."}`).
+- `body`: Request body for POST/PUT.
 
-### fetch
+### 🏗 Codebase Intelligence
 
-Perform an HTTP request.
+#### `build_project_graph`
+**RUN THIS FIRST** when entering a new project. It scans the directory and builds a map of file dependencies using TypeScript AST analysis.
 
 **Inputs:**
-- `url` (string): URL to fetch.
-- `method` (string, optional): HTTP method (GET, POST, etc.).
-- `headers` (object, optional): Request headers.
-- `body` (string, optional): Request body.
+- `path` (string, optional): Root directory (defaults to `.`).
 
-### shell_execute
+#### `get_project_graph_summary`
+Returns high-level stats: total files and the top 5 most-referenced files. Use this to identify the "core" modules of the application.
 
-Execute a shell command. **Use with caution.**
+#### `get_file_relationships`
+Zoom in on a specific file to see its context.
 
 **Inputs:**
-- `command` (string): The command to run.
+- `filePath` (string, required): Path to the file (e.g., `src/index.ts`).
+**Returns:**
+- `imports`: What this file needs.
+- `importedBy`: Who relies on this file.
 
-### read_file / write_file
+### 🛠 System Operations
 
-Manage files on the local system.
+#### `read_file`
+Reads the content of a file. Always read a file before editing it to ensure you have the latest context.
 
 **Inputs:**
-- `path` (string): File path.
-- `content` (string, for write_file): Content to write.
+- `path` (string, required): File path.
 
-### build_project_graph
+#### `write_file`
+Creates or overwrites a file.
 
-Scan directory and build dependency graph.
+**Inputs:**
+- `path` (string, required): File path.
+- `content` (string, required): The full content to write.
+
+#### `shell_execute`
+Executes a shell command. Use for running tests (`npm test`), building (`npm run build`), or file operations (`ls`, `mkdir`).
 
 **Inputs:**
-- `path` (string, optional): Root directory to scan.
+- `command` (string, required): The command line string.
+**Warning:** Use with caution. Avoid commands that might delete data or expose secrets.
 
-### get_file_relationships
+## Recommended System Instruction
 
-Get imports and references for a specific file.
+To optimize your AI agent's performance with these tools, we recommend adding the following instructions to its system prompt:
 
-**Inputs:**
-- `filePath` (string): Path to the file.
+```text
+# Tools & Workflow
 
-### get_project_graph_summary
+1.  **Core Reasoning (`sequentialthinking`)**
+    *   **Mandatory Step:** For any complex query, bug fix, or feature request, you MUST start by using the `sequentialthinking` tool.
+    *   **Methodology:** Break the problem down. If your first hypothesis fails, use the tool again to revise your plan (`isRevision: true`).
+    *   **Goal:** Do not output code or final answers until you have a clear, verified plan.
 
-Get overview of project structure and most referenced files.
+2.  **Codebase Navigation**
+    *   **Initial Scan:** On start, run `build_project_graph`.
+    *   **Context:** Before reading a file, check its context with `get_file_relationships`. This prevents "hallucinating" imports or breaking existing dependencies.
+
+3.  **External Verification**
+    *   **Docs & Facts:** If you need to use a library you aren't 100% sure about, use `web_search` to check the documentation.
+
+4.  **Safety & Persistence**
+    *   **Files:** Always `read_file` before `write_file`.
+    *   **History:** Your thoughts are saved. If you get stuck, review your previous thoughts.
+```
 
 ## Usage
 
@@ -146,6 +193,11 @@ npm run build
 npm test
 ```
 
+## Recent Updates (v2026.1.24)
+
+- **Bug Fixes**:
+  - Fixed `get_file_relationships` to correctly resolve absolute imports and imports from project root (e.g., `src/utils`), ensuring the dependency graph is complete for projects using path aliases or absolute paths.
+
 ## Recent Updates (v2026.1.22)
 
 - **Environment Variables**:

package/dist/graph.js

@@ -79,15 +79,19 @@ export class ProjectKnowledgeGraph {
             if (!currentNode)
                 return;
             for (const importPath of imports) {
+                let resolvedPath = null;
                 if (importPath.startsWith('.')) {
-                    const resolvedPath = await this.resolvePath(path.dirname(filePath), importPath);
-                    if (resolvedPath && this.nodes.has(resolvedPath)) {
-                        if (!currentNode.imports.includes(resolvedPath)) {
-                            currentNode.imports.push(resolvedPath);
-                        }
-                        if (!this.nodes.get(resolvedPath)?.importedBy.includes(filePath)) {
-                            this.nodes.get(resolvedPath)?.importedBy.push(filePath);
-                        }
+                    resolvedPath = await this.resolvePath(path.dirname(filePath), importPath);
+                }
+                else {
+                    resolvedPath = await this.resolvePath(this.rootDir, importPath);
+                }
+                if (resolvedPath && this.nodes.has(resolvedPath)) {
+                    if (!currentNode.imports.includes(resolvedPath)) {
+                        currentNode.imports.push(resolvedPath);
+                    }
+                    if (!this.nodes.get(resolvedPath)?.importedBy.includes(filePath)) {
+                        this.nodes.get(resolvedPath)?.importedBy.push(filePath);
                     }
                 }
             }

package/dist/graph_repro.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ProjectKnowledgeGraph } from './graph.js';
+import * as fs from 'fs/promises';
+vi.mock('fs/promises');
+describe('ProjectKnowledgeGraph Reproduction', () => {
+    let graph;
+    beforeEach(() => {
+        graph = new ProjectKnowledgeGraph();
+        vi.resetAllMocks();
+    });
+    it('should resolve absolute imports from project root', async () => {
+        // Scenario: /app/src/feature/a.ts imports 'src/shared/b.ts'
+        const mockContentA = `import { b } from 'src/shared/b';`;
+        fs.readdir.mockResolvedValue([
+            { name: 'src', isDirectory: () => true },
+            { name: 'feature', isDirectory: () => true },
+            { name: 'shared', isDirectory: () => true },
+            { name: 'a.ts', isDirectory: () => false },
+            { name: 'b.ts', isDirectory: () => false }
+        ]);
+        // Mock getAllFiles behavior by manually setting up the file system structure conceptually
+        // Since getAllFiles is recursive and hard to mock perfectly with just readdir,
+        // we'll focus on the result of getAllFiles which populates the graph.
+        // Wait, the test uses the REAL getAllFiles, so we must mock readdir correctly.
+        // Let's simplify: Flat structure for test.
+        // Root: /app
+        // Files: /app/a.ts, /app/b.ts
+        // a.ts content: "import ... from 'b'" (no dot)
+        // OR
+        // a.ts content: "import ... from 'app/b'" (if root is /)
+        // Let's try the 'src/...' pattern which is common.
+        // Root: /root
+        // File: /root/src/index.ts -> imports 'src/utils'
+        // File: /root/src/utils.ts
+        const rootDir = '/root';
+        const indexFile = '/root/src/index.ts';
+        const utilsFile = '/root/src/utils.ts';
+        // Mock readdir to simulate:
+        // /root -> [src]
+        // /root/src -> [index.ts, utils.ts]
+        fs.readdir.mockImplementation(async (dir) => {
+            if (dir === '/root')
+                return [{ name: 'src', isDirectory: () => true }];
+            if (dir === '/root/src')
+                return [
+                    { name: 'index.ts', isDirectory: () => false },
+                    { name: 'utils.ts', isDirectory: () => false }
+                ];
+            return [];
+        });
+        fs.readFile.mockImplementation(async (filePath) => {
+            if (filePath === indexFile)
+                return `import { u } from 'src/utils';`;
+            return '';
+        });
+        await graph.build(rootDir);
+        const relationships = graph.getRelationships(indexFile);
+        // We expect 'src/utils.ts' to be in imports.
+        // Note: graph.getRelationships returns relative paths.
+        // relative('/root', '/root/src/utils.ts') -> 'src/utils.ts'
+        expect(relationships?.imports).toContain('src/utils.ts');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotza02/sequential-thinking",
-  "version": "2026.1.23",
+  "version": "2026.1.25",
   "publishConfig": {
     "access": "public"
   },