@hanhnd/agent-kit 1.0.0

package/dist/tools/integration.js

@@ -0,0 +1,310 @@
+/**
+ * Integration Tools - Bitbucket, Jira
+ * Tools: kit_get_bitbucket_pr, kit_jira_get_ticket
+ */
+import { z } from 'zod';
+import { sanitize } from './security.js';
+// Zod schema for Bitbucket PR REST API response
+const BitbucketPrSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    description: z.string().nullable().optional(),
+    state: z.enum(['OPEN', 'MERGED', 'DECLINED', 'SUPERSEDED']),
+    author: z.object({ display_name: z.string(), nickname: z.string() }),
+    source: z.object({ branch: z.object({ name: z.string() }) }),
+    destination: z.object({ branch: z.object({ name: z.string() }) }),
+});
+// MEDIUM 2: Jira ticket schema for runtime validation
+// ADF (Atlassian Document Format) can have many nested content types
+// We use a more permissive schema that accepts any ADF structure
+const AdfContentSchema = z
+    .object({
+    type: z.string().optional(),
+    content: z.array(z.unknown()).optional(),
+    text: z.string().optional(),
+})
+    .passthrough();
+const JiraFieldsSchema = z.object({
+    summary: z.string(),
+    status: z.object({ name: z.string() }).optional(),
+    priority: z.object({ name: z.string() }).optional(),
+    assignee: z.object({ displayName: z.string() }).nullable().optional(),
+    reporter: z.object({ displayName: z.string() }).nullable().optional(),
+    issuetype: z.object({ name: z.string() }).optional(),
+    // Handle both plain string and ADF (Atlassian Document Format) structures
+    description: z
+        .union([
+        z.string(),
+        z
+            .object({
+            type: z.string().optional(),
+            version: z.number().optional(),
+            content: z.array(AdfContentSchema).optional(),
+        })
+            .passthrough(), // Accept any additional ADF fields
+    ])
+        .nullable()
+        .optional(),
+    labels: z.array(z.string()).optional(),
+});
+const JiraTicketSchema = z.object({
+    errorMessages: z.array(z.string()).optional(),
+    fields: JiraFieldsSchema,
+});
+/**
+ * Extract plain text from ADF (Atlassian Document Format) content
+ * Recursively walks the content tree to find text nodes
+ */
+function extractAdfText(adf) {
+    if (!adf || typeof adf !== 'object')
+        return 'No description';
+    const content = adf.content;
+    if (!content || !Array.isArray(content))
+        return 'No description';
+    const textParts = [];
+    function extractText(nodes) {
+        for (const node of nodes) {
+            if (typeof node.text === 'string') {
+                textParts.push(node.text);
+            }
+            if (Array.isArray(node.content)) {
+                extractText(node.content);
+            }
+        }
+    }
+    extractText(content);
+    return textParts.join(' ') || 'No description';
+}
+function buildJiraBasicAuth() {
+    const email = process.env.ATLASSIAN_USER_EMAIL;
+    const token = process.env.ATLASSIAN_API_TOKEN;
+    if (!email || !token) {
+        throw new Error('Missing ATLASSIAN_USER_EMAIL or ATLASSIAN_API_TOKEN');
+    }
+    return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
+}
+function buildBitbucketBasicAuth() {
+    const email = process.env.BITBUCKET_USER_EMAIL;
+    const token = process.env.BITBUCKET_API_TOKEN;
+    if (!email || !token) {
+        throw new Error('Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN');
+    }
+    return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
+}
+async function callAtlassianRestApi(url) {
+    const auth = buildJiraBasicAuth();
+    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' } });
+    if (resp.status === 401) {
+        throw new Error('❌ Auth failed: check ATLASSIAN_USER_EMAIL and ATLASSIAN_API_TOKEN');
+    }
+    if (resp.status === 404) {
+        throw new Error(`❌ Not found: ${url}`);
+    }
+    if (!resp.ok) {
+        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
+    }
+    return await resp.json();
+}
+async function callBitbucketRestApi(url) {
+    const auth = buildBitbucketBasicAuth();
+    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' } });
+    if (resp.status === 401) {
+        throw new Error('❌ Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN');
+    }
+    if (resp.status === 404) {
+        throw new Error(`❌ Not found: ${url}`);
+    }
+    if (!resp.ok) {
+        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
+    }
+    return await resp.json();
+}
+async function callBitbucketDiffApi(url) {
+    const auth = buildBitbucketBasicAuth();
+    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'text/plain' } });
+    if (resp.status === 401) {
+        throw new Error('❌ Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN');
+    }
+    if (resp.status === 404) {
+        throw new Error(`❌ Not found: ${url}`);
+    }
+    if (!resp.ok) {
+        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
+    }
+    return await resp.text();
+}
+export function registerIntegrationTools(server) {
+    // TOOL: GET BITBUCKET PR
+    server.tool('kit_get_bitbucket_pr', 'Get Bitbucket PR details and optionally the diff. Accepts a full PR URL or a numeric PR ID with workspace + repoSlug.', {
+        input: z.string().describe('Bitbucket PR URL or numeric PR ID'),
+        workspace: z
+            .string()
+            .optional()
+            .describe('Bitbucket workspace slug (required for numeric ID if BITBUCKET_DEFAULT_WORKSPACE not set)'),
+        repoSlug: z.string().optional().describe('Bitbucket repo slug (required for numeric ID)'),
+        includeDiff: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Include unified diff in response'),
+    }, async ({ input, workspace, repoSlug, includeDiff }) => {
+        try {
+            const bbEmail = process.env.BITBUCKET_USER_EMAIL;
+            const bbToken = process.env.BITBUCKET_API_TOKEN;
+            if (!bbEmail || !bbToken) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN. Create an API token at id.atlassian.com/manage-profile/security/api-tokens.`,
+                        },
+                    ],
+                };
+            }
+            let ws;
+            let repo;
+            let prId;
+            // Try URL parse
+            const urlMatch = input.match(/bitbucket\.org\/([^/]+)\/([^/]+)\/pull-requests\/(\d+)/);
+            if (urlMatch) {
+                ws = urlMatch[1];
+                repo = urlMatch[2];
+                prId = parseInt(urlMatch[3], 10);
+            }
+            else if (input.match(/^\d+$/)) {
+                prId = parseInt(input, 10);
+                ws = workspace || process.env.BITBUCKET_DEFAULT_WORKSPACE;
+                repo = repoSlug;
+            }
+            if (!ws) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`,
+                        },
+                    ],
+                };
+            }
+            if (!repo || !prId) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`,
+                        },
+                    ],
+                };
+            }
+            const safeWs = sanitize(ws);
+            const safeRepo = sanitize(repo);
+            const prUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}`;
+            const jsonData = await callBitbucketRestApi(prUrl);
+            const parseResult = BitbucketPrSchema.safeParse(jsonData);
+            if (!parseResult.success) {
+                throw new Error(`Failed to parse PR response: ${parseResult.error.message}`);
+            }
+            const pr = parseResult.data;
+            let output = `## PR #${pr.id}: ${pr.title}
+**State:** ${pr.state}  **Author:** ${pr.author.display_name}
+**Branch:** ${pr.source.branch.name} → ${pr.destination.branch.name}
+
+### Description
+${pr.description || 'No description'}`;
+            if (includeDiff) {
+                const diffUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}/diff`;
+                const diff = await callBitbucketDiffApi(diffUrl);
+                const truncated = diff.slice(0, 8000) +
+                    (diff.length > 8000 ? `\n... (truncated — ${diff.length - 8000} chars omitted)` : '');
+                output += `\n\n### Diff\n\`\`\`diff\n${truncated}\n\`\`\``;
+            }
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorMsg }] };
+        }
+    });
+    // TOOL: JIRA GET TICKET
+    server.tool('kit_jira_get_ticket', 'Get ticket details from Jira using the Atlassian REST API', {
+        ticketId: z.string().describe('Jira ticket ID (e.g., PROJ-123)'),
+    }, async ({ ticketId }) => {
+        try {
+            const cloudId = process.env.ATLASSIAN_CLOUD_ID;
+            const userEmail = process.env.ATLASSIAN_USER_EMAIL;
+            const apiToken = process.env.ATLASSIAN_API_TOKEN;
+            if (!cloudId || !userEmail || !apiToken) {
+                const missing = [
+                    !cloudId && 'ATLASSIAN_CLOUD_ID',
+                    !userEmail && 'ATLASSIAN_USER_EMAIL',
+                    !apiToken && 'ATLASSIAN_API_TOKEN',
+                ]
+                    .filter(Boolean)
+                    .join(', ');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Missing ${missing}. Create an API Token at id.atlassian.com/manage-profile/security/api-tokens.`,
+                        },
+                    ],
+                };
+            }
+            const safeTicketId = ticketId.match(/^[A-Z]+-\d+$/)?.[0];
+            if (!safeTicketId) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Invalid ticket ID format: ${ticketId}\n\nExpected format: PROJ-123`,
+                        },
+                    ],
+                };
+            }
+            const url = `https://api.atlassian.com/ex/jira/${cloudId}/rest/api/3/issue/${safeTicketId}`;
+            const jsonData = await callAtlassianRestApi(url);
+            const parseResult = JiraTicketSchema.safeParse(jsonData);
+            if (!parseResult.success) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Invalid Jira response format: ${parseResult.error.message}`,
+                        },
+                    ],
+                };
+            }
+            const ticket = parseResult.data;
+            if (ticket.errorMessages && ticket.errorMessages.length > 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Ticket not found: ${ticketId}\n\n${ticket.errorMessages.join('\n')}`,
+                        },
+                    ],
+                };
+            }
+            const output = `## 🎫 ${ticketId}: ${ticket.fields.summary}
+
+**Status:** ${ticket.fields.status?.name || 'Unknown'}
+**Priority:** ${ticket.fields.priority?.name || 'None'}
+**Assignee:** ${ticket.fields.assignee?.displayName || 'Unassigned'}
+**Reporter:** ${ticket.fields.reporter?.displayName || 'Unknown'}
+**Type:** ${ticket.fields.issuetype?.name || 'Unknown'}
+
+### Description
+${typeof ticket.fields.description === 'string'
+                ? ticket.fields.description
+                : extractAdfText(ticket.fields.description)}
+
+### Labels
+${ticket.fields.labels?.join(', ') || 'None'}`;
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }] };
+        }
+    });
+}

package/dist/tools/orchestration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Core Tools - Project context, handoff, and artifact management
+ * Extracted from kit-server.ts for better modularity
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register core tools with MCP server
+ */
+export declare function registrerOrchestrationTools(server: McpServer): void;

package/dist/tools/orchestration.js

@@ -0,0 +1,168 @@
+/**
+ * Core Tools - Project context, handoff, and artifact management
+ * Extracted from kit-server.ts for better modularity
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import { getExtensionRoot, getWorkspaceRoot } from '../utils.js';
+import { WORKFLOWS } from '../workflows.js';
+/**
+ * Resolve lifecycle configuration (Project > Extension)
+ */
+function getWorkflows() {
+    return WORKFLOWS;
+}
+/**
+ * Register core tools with MCP server
+ */
+export function registrerOrchestrationTools(server) {
+    // ═══════════════════════════════════════════════════════════════
+    // TOOL: GET NEXT PHASE
+    // Persists the rolling summary and returns transition instructions
+    // ═══════════════════════════════════════════════════════════════
+    server.tool('kit_get_next_phase', 'Persists the rolling summary and returns transition instructions. currentPhase format: "workflow:phase" (e.g., "code:ANALYSIS")', {
+        summary: z.object({
+            original_goal: z.string(),
+            completed_tasks: z.array(z.string()),
+            pending_tasks: z.array(z.string()),
+            current_context_brief: z.string(),
+        }),
+        transitionTo: z
+            .string()
+            .optional()
+            .describe('Force transition to a specific phase (e.g., "INGESTION")'),
+        currentPhase: z.string().describe('The current workflow and phase (e.g., "code:ANALYSIS")'),
+    }, async ({ summary, transitionTo, currentPhase }) => {
+        try {
+            const [workflowId, phaseId] = currentPhase.split(':');
+            if (!workflowId) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: '❌ Invalid currentPhase format. Use "workflowId" or "workflow:phase".',
+                        },
+                    ],
+                };
+            }
+            const handoffDir = path.join(getWorkspaceRoot(), '.claude-kit', 'handoffs', 'active');
+            const summaryPath = path.join(handoffDir, `${workflowId}-summary.md`);
+            // 1. Ensure directory exists
+            if (!fs.existsSync(handoffDir)) {
+                fs.mkdirSync(handoffDir, { recursive: true });
+            }
+            // 2. Format Markdown
+            const markdown = `
+# 📝 Rolling Summary: ${workflowId.toUpperCase()} Workflow
+
+## 🎯 Original Goal
+${summary.original_goal}
+
+## ✅ Completed Tasks
+${summary.completed_tasks.map((t) => `- ${t}`).join('\n')}
+
+## ⏳ Pending Tasks
+${summary.pending_tasks.map((t) => `- ${t}`).join('\n')}
+
+## 🧠 Current Context Brief
+${summary.current_context_brief}
+
+---
+*Updated: ${new Date().toLocaleString()}*
+`;
+            // 3. Persist summary
+            fs.writeFileSync(summaryPath, markdown, 'utf8');
+            // 4. Resolve next state
+            const workflows = getWorkflows();
+            let nextPhaseId = null;
+            if (workflows[workflowId]) {
+                const workflow = workflows[workflowId];
+                const currentState = phaseId ? workflow.states[phaseId] : null;
+                // Handle bootstrap case: if phaseId is missing, fallback to initial
+                if (!currentState) {
+                    nextPhaseId = transitionTo || workflow.initial;
+                }
+                else {
+                    nextPhaseId = transitionTo || currentState?.next || null;
+                }
+                if (nextPhaseId && !workflow.states[nextPhaseId]) {
+                    nextPhaseId = null;
+                }
+            }
+            // 5. Persist machine-readable state
+            const statePath = path.join(handoffDir, `${workflowId}-state.json`);
+            const stateData = {
+                workflowId,
+                currentPhase: phaseId || 'START',
+                nextPhase: nextPhaseId,
+                summary,
+                updatedAt: new Date().toISOString(),
+            };
+            fs.writeFileSync(statePath, JSON.stringify(stateData, null, 2), 'utf8');
+            // 6. Return transition instructions
+            if (!workflows[workflowId]) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ Summary persisted to ${summaryPath}.\n⚠️ Warning: Workflow "${workflowId}" not found in lifecycle.json.`,
+                        },
+                    ],
+                };
+            }
+            const workflow = workflows[workflowId];
+            if (!nextPhaseId || !workflow.states[nextPhaseId]) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ Summary persisted. Workflow: ${workflowId}, Phase: ${phaseId || 'START'}. No next phase defined.`,
+                        },
+                    ],
+                };
+            }
+            const currentState = phaseId ? workflow.states[phaseId] : null;
+            const nextState = workflow.states[nextPhaseId];
+            const extensionRoot = getExtensionRoot();
+            // Resolve agent content only if it changes
+            const currentAgent = currentState?.agent || workflow.agent;
+            const nextAgent = nextState.agent || workflow.agent;
+            let agentContent = '[UNCHANGED]';
+            if (nextAgent && nextAgent !== currentAgent) {
+                const agentPath = path.join(extensionRoot, 'agents', nextAgent + '.md');
+                if (fs.existsSync(agentPath)) {
+                    agentContent = fs.readFileSync(agentPath, 'utf8');
+                }
+                else {
+                    agentContent = `⚠️ Warning: Agent persona file not found at ${agentPath}`;
+                }
+            }
+            else if (nextAgent && !currentState) {
+                // First phase transition (bootstrap)
+                const agentPath = path.join(extensionRoot, 'agents', nextAgent + '.md');
+                if (fs.existsSync(agentPath)) {
+                    agentContent = fs.readFileSync(agentPath, 'utf8');
+                }
+            }
+            const nextInstructions = `${nextState.instructions}\n\n**PHASE_STOP:** You MUST STOP immediately after completing the instructions above. Do not speculate, do not perform any "extra" work, and do not initiate the next phase. Summarize your progress and call 'kit_get_next_phase' to transition, or WAIT for user feedback if you need to ask_user or a gate is present.`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `PHASE_TRANSITION:
+Next Phase: ${workflowId}:${nextPhaseId}
+Agent Content: ${agentContent}
+Skills: ${JSON.stringify(nextState.skills || [])}
+Instructions: ${nextInstructions}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error updating summary/transition: ${error}` }],
+            };
+        }
+    });
+}

package/dist/tools/security.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Security Helpers - Prevent Command Injection
+ * Exported utilities for safe command execution
+ */
+/**
+ * Sanitize string for safe use with execFileSync
+ * Only removes dangerous shell operators - safe chars like !?#* are allowed
+ * since execFileSync doesn't invoke a shell and handles args safely
+ *
+ * NOTE: Flag injection is NOT handled here because:
+ * 1. execFileSync uses arg arrays, not shell parsing
+ * 2. Adding -- prefix would corrupt content (e.g., commit messages)
+ * 3. Callers should use '--' separator when needed for specific commands
+ */
+export declare function sanitize(input: string): string;
+/**
+ * Validate file path to prevent path traversal attacks
+ * Uses stricter path.sep check to prevent prefix matching flaws
+ * (e.g., /.geminit-kit/handoffs/app should not match /.geminit-kit/handoffs/app-secret)
+ */
+export declare function validatePath(filePath: string, baseDir?: string): string;
+/**
+ * Safe git command execution using execFileSync
+ * Includes stderr in error message for better debugging
+ *
+ * @param timeout Default from GEMINI_KIT_GIT_TIMEOUT env var or 30s
+ */
+export declare function safeGit(args: string[], options?: {
+    timeout?: number;
+    cwd?: string;
+}): string;
+/**
+ * Check if a command exists (cross-platform)
+ * Uses 'where' on Windows, 'which' on macOS/Linux
+ */
+export declare function commandExists(cmd: string): boolean;
+/**
+ * Async file finder - non-blocking for large repos
+ * Uses queue-based approach to prevent stack overflow on deep directories
+ */
+export declare function findFilesAsync(dir: string, extensions: string[], maxFiles: number, excludeDirs?: string[]): Promise<string[]>;

package/dist/tools/security.js

@@ -0,0 +1,131 @@
+/**
+ * Security Helpers - Prevent Command Injection
+ * Exported utilities for safe command execution
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getWorkspaceRoot } from '../utils.js';
+/**
+ * Sanitize string for safe use with execFileSync
+ * Only removes dangerous shell operators - safe chars like !?#* are allowed
+ * since execFileSync doesn't invoke a shell and handles args safely
+ *
+ * NOTE: Flag injection is NOT handled here because:
+ * 1. execFileSync uses arg arrays, not shell parsing
+ * 2. Adding -- prefix would corrupt content (e.g., commit messages)
+ * 3. Callers should use '--' separator when needed for specific commands
+ */
+export function sanitize(input) {
+    // Only remove truly dangerous shell operators
+    // Keep: ! ? # * ( ) [ ] { } - for valid content like "Fix bug!" or "- TODO item"
+    return String(input)
+        .replace(/[;&|`$<>\\]/g, '')
+        .trim()
+        .slice(0, 500); // Limit length
+}
+/**
+ * Validate file path to prevent path traversal attacks
+ * Uses stricter path.sep check to prevent prefix matching flaws
+ * (e.g., /.geminit-kit/handoffs/app should not match /.geminit-kit/handoffs/app-secret)
+ */
+export function validatePath(filePath, baseDir = process.cwd()) {
+    const resolved = path.resolve(baseDir, filePath);
+    const root = path.resolve(baseDir);
+    // Stricter: exact match OR starts with root + separator
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new Error(`Path traversal detected: ${filePath}`);
+    }
+    return resolved;
+}
+/**
+ * Extract stderr from error for better logging
+ */
+function extractStderr(error) {
+    if (error && typeof error === 'object' && 'stderr' in error) {
+        return String(error.stderr);
+    }
+    return '';
+}
+// Configurable timeouts via environment variables
+const GIT_TIMEOUT = parseInt(process.env.GEMINI_KIT_GIT_TIMEOUT || '30000', 10);
+/**
+ * Safe git command execution using execFileSync
+ * Includes stderr in error message for better debugging
+ *
+ * @param timeout Default from GEMINI_KIT_GIT_TIMEOUT env var or 30s
+ */
+export function safeGit(args, options) {
+    try {
+        return execFileSync('git', args, {
+            encoding: 'utf8',
+            timeout: options?.timeout || GIT_TIMEOUT,
+            cwd: options?.cwd || getWorkspaceRoot(),
+            maxBuffer: 10 * 1024 * 1024, // 10MB
+        });
+    }
+    catch (error) {
+        const stderr = extractStderr(error);
+        const baseMsg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Git command failed: ${baseMsg}${stderr ? `\nDetails: ${stderr}` : ''}`);
+    }
+}
+/**
+ * Check if a command exists (cross-platform)
+ * Uses 'where' on Windows, 'which' on macOS/Linux
+ */
+export function commandExists(cmd) {
+    try {
+        const checkCmd = process.platform === 'win32' ? 'where' : 'which';
+        execFileSync(checkCmd, [cmd], {
+            encoding: 'utf8',
+            cwd: getWorkspaceRoot(),
+            timeout: 5000,
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Async file finder - non-blocking for large repos
+ * Uses queue-based approach to prevent stack overflow on deep directories
+ */
+export async function findFilesAsync(dir, extensions, maxFiles, excludeDirs = ['node_modules', '.git', 'dist', 'build', 'coverage']) {
+    const results = [];
+    // Use queue instead of recursion to prevent stack overflow
+    const queue = [
+        { fullPath: dir, relativePath: '' },
+    ];
+    while (queue.length > 0 && results.length < maxFiles) {
+        const current = queue.shift();
+        let entries;
+        try {
+            entries = await fs.promises.readdir(current.fullPath, { withFileTypes: true });
+        }
+        catch {
+            continue; // Skip directories we can't read
+        }
+        for (const entry of entries) {
+            if (results.length >= maxFiles)
+                break;
+            const entryFullPath = path.join(current.fullPath, entry.name);
+            const entryRelPath = current.relativePath
+                ? path.join(current.relativePath, entry.name)
+                : entry.name;
+            if (entry.isDirectory()) {
+                if (!excludeDirs.includes(entry.name)) {
+                    queue.push({ fullPath: entryFullPath, relativePath: entryRelPath });
+                }
+            }
+            else if (entry.isFile()) {
+                if (extensions.some((ext) => entry.name.endsWith(ext))) {
+                    results.push(entryRelPath);
+                }
+            }
+        }
+    }
+    return results;
+}

package/dist/utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for agent-kit
+ */
+export declare function getWorkspaceRoot(): string;
+/**
+ * Resolve path to plugin root.
+ * When installed as a Claude Code plugin, CLAUDE_PLUGIN_ROOT is set automatically.
+ * Falls back to resolving from the bundled file location for local development.
+ */
+export declare function getExtensionRoot(): string;