token-pilot 0.19.1 → 0.19.2

package/dist/ast-index/binary-manager.d.ts

@@ -2,14 +2,14 @@ export interface BinaryStatus {
     available: boolean;
     path: string;
     version: string | null;
-    source: 'system' | 'managed' | 'none';
+    source: 'system' | 'npm' | 'managed' | 'none';
 }
 /**
- * Find ast-index binary: check system PATH first, then managed install.
+ * Find ast-index binary: config → system PATH → npm global → managed install.
  */
 export declare function findBinary(configPath?: string | null): Promise<BinaryStatus>;
 /**
- * Download and install ast-index binary from GitHub releases.
+ * Install ast-index: tries npm global first (all platforms), falls back to GitHub download.
  */
 export declare function installBinary(onProgress?: (msg: string) => void): Promise<BinaryStatus>;
 /**

package/dist/ast-index/binary-manager.js

@@ -12,7 +12,7 @@ const REPO = 'defendend/Claude-ast-index-search';
 const BINARY_NAME = platform() === 'win32' ? 'ast-index.exe' : 'ast-index';
 const INSTALL_DIR = resolve(homedir(), '.token-pilot', 'bin');
 /**
- * Find ast-index binary: check system PATH first, then managed install.
+ * Find ast-index binary: config → system PATH → npm global → managed install.
  */
 export async function findBinary(configPath) {
     // 1. Config override
@@ -28,7 +28,15 @@ export async function findBinary(configPath) {
         const version = await getBinaryVersion(systemPath);
         return { available: true, path: systemPath, version, source: 'system' };
     }
-    // 3. Managed install
+    // 3. npm global install (@ast-index/cli)
+    const npmPath = await findViaNpmBin();
+    if (npmPath) {
+        const version = await getBinaryVersion(npmPath);
+        if (version) {
+            return { available: true, path: npmPath, version, source: 'npm' };
+        }
+    }
+    // 4. Managed install (GitHub download)
     const managedPath = resolve(INSTALL_DIR, BINARY_NAME);
     const version = await getBinaryVersion(managedPath);
     if (version) {
@@ -37,24 +45,53 @@ export async function findBinary(configPath) {
     return { available: false, path: '', version: null, source: 'none' };
 }
 /**
- * Download and install ast-index binary from GitHub releases.
+ * Install ast-index: tries npm global first (all platforms), falls back to GitHub download.
  */
 export async function installBinary(onProgress) {
     const log = onProgress ?? (() => { });
+    // Try npm first — simpler, handles all platforms including Windows
+    try {
+        return await installViaNpm(log);
+    }
+    catch (npmErr) {
+        log(`npm install failed (${npmErr instanceof Error ? npmErr.message : npmErr}), trying GitHub download...`);
+    }
+    // GitHub download fallback
+    return installViaNpmFallback(log);
+}
+async function installViaNpm(onProgress) {
+    onProgress('Installing @ast-index/cli via npm...');
+    await new Promise((resolve, reject) => {
+        execFile('npm', ['install', '-g', '@ast-index/cli'], { timeout: 120_000 }, (err, _stdout, stderr) => {
+            if (err)
+                reject(new Error(stderr.trim() || err.message));
+            else
+                resolve();
+        });
+    });
+    const binPath = await findViaNpmBin();
+    if (!binPath) {
+        throw new Error('@ast-index/cli installed but binary not found in npm prefix');
+    }
+    const version = await getBinaryVersion(binPath);
+    onProgress(`Installed ast-index ${version} via npm at ${binPath}`);
+    return { available: true, path: binPath, version, source: 'npm' };
+}
+async function installViaNpmFallback(onProgress) {
     // Determine platform/arch
     const plat = getPlatform();
     const ar = getArch();
     if (!plat || !ar) {
         throw new Error(`Unsupported platform: ${platform()} ${arch()}`);
     }
-    log('Fetching latest release info...');
+    onProgress('Fetching latest release info...');
     const release = await fetchLatestRelease();
     const assetName = buildAssetName(release.tag, plat, ar);
     const asset = release.assets.find(a => a.name === assetName);
     if (!asset) {
         throw new Error(`No binary found for ${plat}-${ar}. Available: ${release.assets.map(a => a.name).join(', ')}`);
     }
-    log(`Downloading ${asset.name} (${(asset.size / 1024 / 1024).toFixed(1)}MB)...`);
+    onProgress(`Downloading ${asset.name} (${(asset.size / 1024 / 1024).toFixed(1)}MB)...`);
     await mkdir(INSTALL_DIR, { recursive: true });
     const tmpPath = resolve(INSTALL_DIR, `${BINARY_NAME}.tmp`);
     const finalPath = resolve(INSTALL_DIR, BINARY_NAME);
@@ -62,19 +99,16 @@ export async function installBinary(onProgress) {
         if (assetName.endsWith('.tar.gz')) {
             await downloadAndExtractTarGz(asset.url, INSTALL_DIR, BINARY_NAME);
         }
-        else if (assetName.endsWith('.zip')) {
-            // For Windows, download zip and extract
+        else {
             await downloadFile(asset.url, tmpPath);
-            // Simple approach: use system unzip if available
-            throw new Error('ZIP extraction not yet supported. Please install ast-index manually on Windows.');
+            throw new Error('ZIP extraction not yet supported. Please use: npm install -g @ast-index/cli');
         }
         await chmod(finalPath, 0o755);
         const version = await getBinaryVersion(finalPath);
-        log(`Installed ast-index ${version} to ${finalPath}`);
+        onProgress(`Installed ast-index ${version} to ${finalPath}`);
         return { available: true, path: finalPath, version, source: 'managed' };
     }
     catch (err) {
-        // Cleanup on failure
         try {
             await rm(tmpPath, { force: true });
         }
@@ -130,6 +164,35 @@ export function isNewerVersion(current, latest) {
     return false;
 }
 // --- Internal helpers ---
+/**
+ * Find ast-index binary installed via `npm install -g @ast-index/cli`.
+ * Checks the npm global prefix bin directory.
+ */
+async function findViaNpmBin() {
+    try {
+        const prefix = await new Promise((resolve, reject) => {
+            execFile('npm', ['config', 'get', 'prefix'], { timeout: 3000 }, (err, stdout) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(stdout.trim());
+            });
+        });
+        // Unix: <prefix>/bin/ast-index  |  Windows: <prefix>\ast-index.exe or <prefix>\bin\ast-index.exe
+        const candidates = platform() === 'win32'
+            ? [resolve(prefix, BINARY_NAME), resolve(prefix, 'bin', BINARY_NAME)]
+            : [resolve(prefix, 'bin', BINARY_NAME)];
+        for (const candidate of candidates) {
+            try {
+                await access(candidate);
+                return candidate;
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return null;
+}
 function getPlatform() {
     switch (platform()) {
         case 'darwin': return 'darwin';

package/dist/ast-index/client.d.ts

@@ -27,12 +27,16 @@ export declare class AstIndexClient {
     symbol(name: string): Promise<AstIndexSymbolDetail | null>;
     search(query: string, options?: {
         inFile?: string;
+        type?: string;
         maxResults?: number;
         fuzzy?: boolean;
     }): Promise<AstIndexSearchResult[]>;
     usages(symbolName: string): Promise<AstIndexUsageResult[]>;
     implementations(name: string): Promise<AstIndexImplementation[]>;
-    hierarchy(name: string): Promise<AstIndexHierarchyNode | null>;
+    hierarchy(name: string, options?: {
+        inFile?: string;
+        module?: string;
+    }): Promise<AstIndexHierarchyNode | null>;
     stats(): Promise<string | null>;
     listFiles(): Promise<string[]>;
     refs(symbolName: string, limit?: number): Promise<AstIndexRefsResponse>;

package/dist/ast-index/client.js

@@ -223,6 +223,8 @@ export class AstIndexClient {
         const args = ['search', query, '--format', 'json'];
         if (options?.inFile)
             args.push('--in-file', options.inFile);
+        if (options?.type)
+            args.push('--type', options.type);
         if (options?.maxResults)
             args.push('--limit', String(options.maxResults));
         if (options?.fuzzy)
@@ -295,10 +297,15 @@ export class AstIndexClient {
             return [];
         }
     }
-    async hierarchy(name) {
+    async hierarchy(name, options) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['hierarchy', name, '--format', 'json']);
+            const args = ['hierarchy', name, '--format', 'json'];
+            if (options?.inFile)
+                args.push('--in-file', options.inFile);
+            if (options?.module)
+                args.push('--module', options.module);
+            const result = await this.exec(args);
             try {
                 return JSON.parse(result);
             }

package/dist/hooks/installer.d.ts

@@ -8,11 +8,17 @@ export interface HookUninstallResult {
     fatal: boolean;
     message: string;
 }
+export interface HookInstallOptions {
+    /** Absolute path to the entry script (dist/index.js). When provided, hooks use absolute paths instead of bare "token-pilot". */
+    scriptPath?: string;
+    /** Absolute path to the node binary. Defaults to process.execPath. */
+    nodeExecPath?: string;
+}
 /**
  * Install Token Pilot hook into Claude Code settings.
  * Creates or updates .claude/settings.json with PreToolUse hook.
  */
-export declare function installHook(projectRoot: string): Promise<HookInstallResult>;
+export declare function installHook(projectRoot: string, options?: HookInstallOptions): Promise<HookInstallResult>;
 /**
  * Remove Token Pilot hook from Claude Code settings.
  */

package/dist/hooks/installer.js

@@ -1,35 +1,55 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
-const HOOK_CONFIG = {
-    hooks: {
-        PreToolUse: [
-            {
-                matcher: "Read",
-                hooks: [
-                    {
-                        type: "command",
-                        command: "token-pilot hook-read",
-                    },
-                ],
-            },
-            {
-                matcher: "Edit",
-                hooks: [
-                    {
-                        type: "command",
-                        command: "token-pilot hook-edit",
-                    },
-                ],
-            },
-        ],
-    },
-};
+/**
+ * Build hook command that works in any shell (/bin/sh, bash, etc.)
+ * Uses absolute paths to node + script to avoid PATH/nvm issues.
+ * Falls back to bare "token-pilot" only for manual CLI installs.
+ */
+function buildHookCommand(action, options) {
+    if (options?.scriptPath) {
+        const node = options.nodeExecPath || process.execPath;
+        return `${node} ${options.scriptPath} ${action}`;
+    }
+    return `token-pilot ${action}`;
+}
+function createHookConfig(options) {
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: "Read",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand('hook-read', options),
+                        },
+                    ],
+                },
+                {
+                    matcher: "Edit",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand('hook-edit', options),
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
 /**
  * Install Token Pilot hook into Claude Code settings.
  * Creates or updates .claude/settings.json with PreToolUse hook.
  */
-export async function installHook(projectRoot) {
+export async function installHook(projectRoot, options) {
+    // Skip auto-install when running as a Claude Code plugin —
+    // the plugin system already registers hooks via .claude-plugin/hooks/hooks.json
+    if (process.env.CLAUDE_PLUGIN_ROOT) {
+        return { installed: false, fatal: false, message: 'Running as plugin — hooks registered via plugin system.' };
+    }
     const settingsPath = resolve(projectRoot, '.claude', 'settings.json');
+    const hookConfig = createHookConfig(options);
     try {
         // Ensure .claude dir exists
         await mkdir(dirname(settingsPath), { recursive: true });
@@ -63,16 +83,26 @@ export async function installHook(projectRoot) {
         const existingHooks = settings.hooks?.PreToolUse;
         const isTokenPilotHook = (h) => h.hooks?.some((hook) => hook.command?.includes('token-pilot'));
         if (Array.isArray(existingHooks)) {
-            const hasRead = existingHooks.some((h) => h.matcher === 'Read' && isTokenPilotHook(h));
-            const hasEdit = existingHooks.some((h) => h.matcher === 'Edit' && isTokenPilotHook(h));
-            if (hasRead && hasEdit) {
-                return { installed: false, fatal: false, message: 'Token Pilot hooks already installed.' };
+            // Remove old broken hooks (bare "token-pilot" without absolute path)
+            // and replace with working ones using absolute paths
+            const oldBrokenHooks = existingHooks.filter((h) => isTokenPilotHook(h) && h.hooks?.some((hook) => hook.command?.match(/^token-pilot\s/) // bare command without path
+            ));
+            if (oldBrokenHooks.length > 0 && options?.scriptPath) {
+                // Remove old broken hooks, will re-add with absolute paths below
+                settings.hooks.PreToolUse = existingHooks.filter((h) => !isTokenPilotHook(h));
+            }
+            else {
+                const hasRead = existingHooks.some((h) => h.matcher === 'Read' && isTokenPilotHook(h));
+                const hasEdit = existingHooks.some((h) => h.matcher === 'Edit' && isTokenPilotHook(h));
+                if (hasRead && hasEdit) {
+                    return { installed: false, fatal: false, message: 'Token Pilot hooks already installed.' };
+                }
             }
             // Add missing hooks
-            for (const hookDef of HOOK_CONFIG.hooks.PreToolUse) {
-                const exists = existingHooks.some((h) => h.matcher === hookDef.matcher && isTokenPilotHook(h));
+            for (const hookDef of hookConfig.hooks.PreToolUse) {
+                const exists = settings.hooks.PreToolUse.some((h) => h.matcher === hookDef.matcher && isTokenPilotHook(h));
                 if (!exists) {
-                    existingHooks.push(hookDef);
+                    settings.hooks.PreToolUse.push(hookDef);
                 }
             }
         }
@@ -80,7 +110,7 @@ export async function installHook(projectRoot) {
             // Create hooks section
             if (!settings.hooks)
                 settings.hooks = {};
-            settings.hooks.PreToolUse = HOOK_CONFIG.hooks.PreToolUse;
+            settings.hooks.PreToolUse = hookConfig.hooks.PreToolUse;
         }
         await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
         return {

package/dist/index.js

@@ -122,7 +122,16 @@ export async function startServer(cliArgs = process.argv.slice(2)) {
     const binaryStatus = await findBinary(config.astIndex.binaryPath);
     checkAllUpdates(config, binaryStatus).catch(() => { });
     // Auto-install PreToolUse hook (non-blocking, Claude Code only)
-    installHook(projectRoot).then(result => {
+    // Uses absolute paths to node + script so hooks work in /bin/sh (nvm, npx, etc.)
+    let hookOptions;
+    try {
+        const rawPath = fileURLToPath(new URL('./index.js', import.meta.url));
+        hookOptions = { scriptPath: realpathSync(rawPath), nodeExecPath: process.execPath };
+    }
+    catch {
+        // Can't resolve script path (e.g. running from src/ in tests) — fall back to bare command
+    }
+    installHook(projectRoot, hookOptions).then(result => {
         if (result.installed) {
             console.error(`[token-pilot] hook auto-installed: ${result.message}`);
         }
@@ -239,7 +248,15 @@ export function handleHookEdit() {
     process.exit(0);
 }
 export async function handleInstallHook(projectRoot) {
-    const result = await installHook(projectRoot);
+    let hookOptions;
+    try {
+        const rawPath = fileURLToPath(new URL('./index.js', import.meta.url));
+        hookOptions = { scriptPath: realpathSync(rawPath), nodeExecPath: process.execPath };
+    }
+    catch {
+        // Fall back to bare command
+    }
+    const result = await installHook(projectRoot, hookOptions);
     console.log(result.message);
     process.exit(result.fatal ? 1 : 0);
 }
@@ -443,25 +460,25 @@ export async function checkAllUpdates(config, binaryStatus) {
     }
 }
 export function printHelp() {
-    console.log(`token-pilot v${getVersion()} — MCP server for token-efficient code reading
-
-Usage:
-  token-pilot [project-root]        Start MCP server (default: cwd)
-  token-pilot init [dir]            Create .mcp.json with token-pilot + context-mode
-  token-pilot install-hook [root]   Install PreToolUse hook (Claude Code only)
-  token-pilot uninstall-hook [root] Remove PreToolUse hook
-  token-pilot install-ast-index     Download ast-index binary (auto on first run)
-  token-pilot doctor                Run diagnostics (check ast-index, config, updates)
-  token-pilot --version             Show version
-  token-pilot --help                Show this help
-
-Quick start:
-  npx token-pilot init              Setup .mcp.json (token-pilot + context-mode)
-
-MCP Tools (18):
-  smart_read, read_symbol, read_range, read_diff, read_for_edit, smart_read_many,
-  find_usages, find_unused, related_files, outline, project_overview, session_analytics,
-  code_audit, module_info, smart_diff, explore_area, smart_log, test_summary
+    console.log(`token-pilot v${getVersion()} — MCP server for token-efficient code reading
+
+Usage:
+  token-pilot [project-root]        Start MCP server (default: cwd)
+  token-pilot init [dir]            Create .mcp.json with token-pilot + context-mode
+  token-pilot install-hook [root]   Install PreToolUse hook (Claude Code only)
+  token-pilot uninstall-hook [root] Remove PreToolUse hook
+  token-pilot install-ast-index     Download ast-index binary (auto on first run)
+  token-pilot doctor                Run diagnostics (check ast-index, config, updates)
+  token-pilot --version             Show version
+  token-pilot --help                Show this help
+
+Quick start:
+  npx token-pilot init              Setup .mcp.json (token-pilot + context-mode)
+
+MCP Tools (18):
+  smart_read, read_symbol, read_range, read_diff, read_for_edit, smart_read_many,
+  find_usages, find_unused, related_files, outline, project_overview, session_analytics,
+  code_audit, module_info, smart_diff, explore_area, smart_log, test_summary
 `);
     process.exit(0);
 }

package/package.json

@@ -1,87 +1,87 @@
-{
-  "name": "token-pilot",
-  "version": "0.19.1",
-  "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "token-pilot": "dist/index.js"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "start.sh",
-    ".claude-plugin/",
-    ".mcp.json",
-    "skills/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "prebuild": "node --input-type=module -e \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build && node --input-type=module -e \"import { chmod } from 'node:fs/promises'; await chmod('dist/index.js', 0o755);\""
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "claude",
-    "claude-code",
-    "cursor",
-    "codex",
-    "cline",
-    "ai-coding",
-    "llm-tools",
-    "token-savings",
-    "token-reduction",
-    "context-window",
-    "context-optimization",
-    "ast",
-    "code-reading",
-    "code-navigation",
-    "smart-read",
-    "developer-tools",
-    "tree-sitter"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Digital-Threads/token-pilot.git"
-  },
-  "homepage": "https://github.com/Digital-Threads/token-pilot#readme",
-  "bugs": {
-    "url": "https://github.com/Digital-Threads/token-pilot/issues"
-  },
-  "mcpName": "io.github.Digital-Threads/token-pilot",
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "chokidar": "^4.0.3"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^3.2.4",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "peerDependencies": {
-    "ast-index": ">=0.1.0"
-  },
-  "peerDependenciesMeta": {
-    "ast-index": {
-      "optional": true
-    }
-  },
-  "optionalDependencies": {
-    "@ast-grep/cli": "^0.41.0"
-  }
-}
+{
+  "name": "token-pilot",
+  "version": "0.19.2",
+  "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "token-pilot": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "start.sh",
+    ".claude-plugin/",
+    ".mcp.json",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prebuild": "node --input-type=module -e \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && node --input-type=module -e \"import { chmod } from 'node:fs/promises'; await chmod('dist/index.js', 0o755);\""
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "cline",
+    "ai-coding",
+    "llm-tools",
+    "token-savings",
+    "token-reduction",
+    "context-window",
+    "context-optimization",
+    "ast",
+    "code-reading",
+    "code-navigation",
+    "smart-read",
+    "developer-tools",
+    "tree-sitter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Digital-Threads/token-pilot.git"
+  },
+  "homepage": "https://github.com/Digital-Threads/token-pilot#readme",
+  "bugs": {
+    "url": "https://github.com/Digital-Threads/token-pilot/issues"
+  },
+  "mcpName": "io.github.Digital-Threads/token-pilot",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "chokidar": "^4.0.3"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "ast-index": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "ast-index": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@ast-grep/cli": "^0.41.0"
+  }
+}