@suco/su-auggie-mcp 0.1.0

package/dist/tools/debug.js

@@ -0,0 +1,179 @@
+/**
+ * Debug tool - inspect internal server state (only available with --debug)
+ */
+import { z } from 'zod';
+import { workspaceManager } from '../workspace-manager.js';
+import { createLogger } from '../logger.js';
+import { INDEXING_CONFIG, WATCHER_CONFIG, PERSISTENCE_CONFIG, isPersistenceEnabled } from '../config.js';
+import { sendLogToClient, clientSupportsElicitation, elicitInput, getMcpServer, } from '../mcp-notifications.js';
+const logger = createLogger('DebugTool');
+/** Tool name */
+export const DEBUG_TOOL_NAME = 'debug';
+/** Tool description */
+export const DEBUG_TOOL_DESCRIPTION = `Inspect internal server state for troubleshooting.
+
+Actions:
+- state: Dump full internal state (contexts, watchers, queues)
+- stats: Index statistics (file counts, sizes, timings)
+- config: Show current configuration values
+- capabilities: Show client MCP capabilities (elicitation, logging, etc.)
+- emit: Test MCP client notifications (logging or elicitation)
+
+Parameters:
+- action: Required action to perform
+- root: Workspace root path for workspace-specific info (optional)
+- type: For emit action: "logging" or "elicitation"
+- message: Message for emit action (optional)`;
+/** Input schema for zod validation */
+export const debugInputSchema = z.object({
+    action: z.enum(['state', 'stats', 'config', 'capabilities', 'emit']),
+    root: z.string().optional(),
+    type: z.enum(['logging', 'elicitation']).optional(),
+    message: z.string().optional(),
+});
+/** Zod schema shape for MCP tool registration */
+export const DEBUG_PARAMS_SHAPE = {
+    action: z.enum(['state', 'stats', 'config', 'capabilities', 'emit']).describe('Debug action to perform'),
+    root: z.string().optional().describe('Workspace root path (optional)'),
+    type: z.enum(['logging', 'elicitation']).optional().describe('For emit: type of notification to send'),
+    message: z.string().optional().describe('Message for emit action'),
+};
+/** Handle debug tool call */
+export async function handleDebugTool(input) {
+    // Validate input
+    const parsed = debugInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`Invalid input: ${parsed.error.message}`);
+    }
+    const { action, root, type, message } = parsed.data;
+    logger.debug(`Debug action: ${action}, root: ${root ?? 'all'}`);
+    switch (action) {
+        case 'state': {
+            const workspaces = root
+                ? [workspaceManager.getWorkspace(root)].filter(Boolean)
+                : workspaceManager.getAllWorkspaces();
+            const state = {
+                workspaceCount: workspaceManager.count,
+                workspaces: workspaces.map((ws) => {
+                    if (!ws)
+                        return null;
+                    const status = ws.getStatus();
+                    return {
+                        root: ws.root,
+                        status: status.status,
+                        indexed: status.indexed,
+                        pending: status.pending,
+                        watching: status.watching,
+                        lastIndexed: status.lastIndexed,
+                        error: status.error,
+                        progress: status.progress,
+                    };
+                }).filter(Boolean),
+            };
+            return JSON.stringify(state, null, 2);
+        }
+        case 'stats': {
+            const workspaces = root
+                ? [workspaceManager.getWorkspace(root)].filter(Boolean)
+                : workspaceManager.getAllWorkspaces();
+            const stats = {
+                totalWorkspaces: workspaceManager.count,
+                workspaces: workspaces.map((ws) => {
+                    if (!ws)
+                        return null;
+                    const status = ws.getStatus();
+                    const paths = ws.getIndexedPaths();
+                    return {
+                        root: ws.root,
+                        indexedFiles: paths.length,
+                        status: status.status,
+                        pending: status.pending,
+                    };
+                }).filter(Boolean),
+                totals: {
+                    indexedFiles: workspaces.reduce((sum, ws) => sum + (ws?.getIndexedPaths().length ?? 0), 0),
+                    pending: workspaces.reduce((sum, ws) => sum + (ws?.getStatus().pending ?? 0), 0),
+                },
+            };
+            return JSON.stringify(stats, null, 2);
+        }
+        case 'config': {
+            const config = {
+                indexing: INDEXING_CONFIG,
+                watcher: WATCHER_CONFIG,
+                persistence: {
+                    ...PERSISTENCE_CONFIG,
+                    enabled: isPersistenceEnabled(),
+                },
+                environment: {
+                    SUCO_AUGGIE_DEBUG: process.env.SUCO_AUGGIE_DEBUG ?? '(not set)',
+                    SUCO_AUGGIE_DEBOUNCE_MS: process.env.SUCO_AUGGIE_DEBOUNCE_MS ?? '(not set)',
+                    AUGMENT_API_TOKEN: process.env.AUGMENT_API_TOKEN ? '(set)' : '(not set)',
+                    AUGMENT_API_URL: process.env.AUGMENT_API_URL ?? '(not set)',
+                },
+            };
+            return JSON.stringify(config, null, 2);
+        }
+        case 'capabilities': {
+            const server = getMcpServer();
+            const clientCaps = server?.server.getClientCapabilities();
+            const caps = {
+                serverConnected: !!server,
+                clientCapabilities: clientCaps ?? null,
+                features: {
+                    elicitation: clientSupportsElicitation(),
+                    logging: true, // We always try to send logs
+                },
+            };
+            return JSON.stringify(caps, null, 2);
+        }
+        case 'emit': {
+            const emitType = type ?? 'logging';
+            const msg = message ?? 'Test message from debug tool';
+            if (emitType === 'logging') {
+                await sendLogToClient('info', msg);
+                return JSON.stringify({
+                    type: 'logging',
+                    sent: true,
+                    message: msg,
+                }, null, 2);
+            }
+            if (emitType === 'elicitation') {
+                if (!clientSupportsElicitation()) {
+                    return JSON.stringify({
+                        type: 'elicitation',
+                        supported: false,
+                        error: 'Client does not support elicitation',
+                    }, null, 2);
+                }
+                const result = await elicitInput({
+                    message: msg,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            response: {
+                                type: 'string',
+                                title: 'Your Response',
+                                description: 'Enter any text to test elicitation',
+                            },
+                            confirmed: {
+                                type: 'boolean',
+                                title: 'Confirm',
+                                description: 'Check to confirm',
+                            },
+                        },
+                        required: ['response'],
+                    },
+                });
+                return JSON.stringify({
+                    type: 'elicitation',
+                    supported: true,
+                    result: result ?? { error: 'Elicitation returned null' },
+                }, null, 2);
+            }
+            throw new Error(`Unknown emit type: ${emitType}`);
+        }
+        default:
+            throw new Error(`Unknown action: ${action}`);
+    }
+}

package/dist/tools/index-tool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Index tool - manage and inspect indexing state
+ */
+import { z } from 'zod';
+/** Tool name */
+export declare const INDEX_TOOL_NAME = "index";
+/** Tool description */
+export declare const INDEX_TOOL_DESCRIPTION = "Manage and inspect codebase indexing state.\n\nActions:\n- status: Get indexing status for all workspaces\n- list: List top-level indexed directories with file counts\n- reindex: Force full re-index of all workspaces (clears and rebuilds)\n\nParameters:\n- action: \"status\", \"list\", or \"reindex\" (required)";
+/** Input schema for zod validation */
+export declare const indexInputSchema: z.ZodObject<{
+    action: z.ZodEnum<["status", "list", "reindex"]>;
+}, "strip", z.ZodTypeAny, {
+    action: "status" | "list" | "reindex";
+}, {
+    action: "status" | "list" | "reindex";
+}>;
+/** Zod schema shape for MCP tool registration */
+export declare const INDEX_PARAMS_SHAPE: {
+    action: z.ZodEnum<["status", "list", "reindex"]>;
+};
+/** Handle index tool call */
+export declare function handleIndexTool(input: unknown): Promise<string>;

package/dist/tools/index-tool.js

@@ -0,0 +1,86 @@
+/**
+ * Index tool - manage and inspect indexing state
+ */
+import { z } from 'zod';
+import { workspaceManager } from '../workspace-manager.js';
+import { createLogger } from '../logger.js';
+const logger = createLogger('IndexTool');
+/** Tool name */
+export const INDEX_TOOL_NAME = 'index';
+/** Tool description */
+export const INDEX_TOOL_DESCRIPTION = `Manage and inspect codebase indexing state.
+
+Actions:
+- status: Get indexing status for all workspaces
+- list: List top-level indexed directories with file counts
+- reindex: Force full re-index of all workspaces (clears and rebuilds)
+
+Parameters:
+- action: "status", "list", or "reindex" (required)`;
+/** Input schema for zod validation */
+export const indexInputSchema = z.object({
+    action: z.enum(['status', 'list', 'reindex']),
+});
+/** Zod schema shape for MCP tool registration */
+export const INDEX_PARAMS_SHAPE = {
+    action: z.enum(['status', 'list', 'reindex']).describe('Action to perform'),
+};
+/** Handle index tool call */
+export async function handleIndexTool(input) {
+    // Validate input
+    const parsed = indexInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`Invalid input: ${parsed.error.message}`);
+    }
+    const { action } = parsed.data;
+    logger.debug(`Index action: ${action}`);
+    switch (action) {
+        case 'status': {
+            const statuses = workspaceManager.getStatus();
+            if (statuses.length === 0) {
+                return JSON.stringify({ workspaces: [], message: 'No workspaces configured' });
+            }
+            return JSON.stringify({ workspaces: statuses }, null, 2);
+        }
+        case 'list': {
+            const paths = workspaceManager.getIndexedPaths();
+            // Group by top-level directory
+            const dirCounts = {};
+            for (const filePath of paths) {
+                const parts = filePath.split('/');
+                // Get first directory component (or file if at root)
+                const topLevel = parts.length > 1 ? parts[0] : '(root files)';
+                dirCounts[topLevel] = (dirCounts[topLevel] ?? 0) + 1;
+            }
+            // Sort by count descending
+            const directories = Object.entries(dirCounts)
+                .sort((a, b) => b[1] - a[1])
+                .map(([dir, count]) => ({ directory: dir, files: count }));
+            return JSON.stringify({
+                totalFiles: paths.length,
+                directories,
+            }, null, 2);
+        }
+        case 'reindex': {
+            const workspaces = workspaceManager.getAllWorkspaces();
+            const results = [];
+            for (const workspace of workspaces) {
+                // Trigger reindex without waiting - runs in background
+                workspace.reindex(true).catch(err => {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logger.error(`Reindex failed for ${workspace.root}: ${msg}`);
+                });
+                results.push({
+                    root: workspace.root,
+                    status: 'indexing',
+                });
+            }
+            return JSON.stringify({
+                message: `Full reindex triggered for ${workspaces.length} workspace(s). Use 'status' action to monitor progress.`,
+                workspaces: results,
+            }, null, 2);
+        }
+        default:
+            throw new Error(`Unknown action: ${action}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Type definitions for suco-auggie-mcp
+ */
+/** Workspace indexing status */
+export type WorkspaceStatusType = 'initializing' | 'indexing' | 'ready' | 'error';
+/** Progress tracking for indexing operations */
+export interface IndexingProgress {
+    /** Files discovered so far (grows during scan) */
+    discovered: number;
+    /** Files indexed so far */
+    indexed: number;
+    /** Whether discovery is still in progress */
+    discovering: boolean;
+    /** Batches queued for indexing */
+    batchesQueued: number;
+    /** Batches completed (success or permanent failure) */
+    batchesCompleted: number;
+    /** Batches that failed and are pending retry */
+    batchesFailed: number;
+    /** Batches successfully retried */
+    batchesRetried: number;
+}
+/** Error classification for retry logic */
+export type BatchErrorType = 'retryable' | 'fatal' | 'permanent';
+/** Failed batch awaiting retry */
+export interface FailedBatch {
+    /** Batch number for logging */
+    batchNum: number;
+    /** Files in the batch */
+    files: Array<{
+        path: string;
+        contents: string;
+    }>;
+    /** Total bytes in the batch */
+    bytes: number;
+    /** Number of retry attempts so far */
+    attempts: number;
+    /** Error type classification */
+    errorType: BatchErrorType;
+    /** Last error message */
+    lastError: string;
+    /** Timestamp of last attempt */
+    lastAttemptAt: Date;
+    /** Next retry scheduled at (null if not scheduled) */
+    nextRetryAt: Date | null;
+}
+/** Retry statistics for status reporting */
+export interface RetryStats {
+    /** Batches currently pending immediate retry */
+    pendingRetries: number;
+    /** Total files in pending immediate retry batches */
+    pendingRetryFiles: number;
+    /** Batches that were successfully retried (immediate) */
+    retriedBatches: number;
+    /** Files that were successfully retried (immediate) */
+    retriedFiles: number;
+    /** Batches that permanently failed (exhausted all retries including cooldown) */
+    permanentlyFailedBatches: number;
+    /** Files that permanently failed */
+    permanentlyFailedFiles: number;
+    /** Cooldown queue stats */
+    cooldown: CooldownStats;
+}
+/** Cooldown queue statistics */
+export interface CooldownStats {
+    /** Files currently in cooldown queue */
+    pendingFiles: number;
+    /** Current cooldown cycle (0 if not in cooldown) */
+    currentCycle: number;
+    /** Maximum cooldown cycles allowed */
+    maxCycles: number;
+    /** Next cooldown retry time (ISO string, null if not scheduled) */
+    nextRetryAt: string | null;
+    /** Files recovered via cooldown */
+    recoveredFiles: number;
+}
+/** Entry in the cooldown queue (persisted) - stores paths only, re-reads contents on retry */
+export interface CooldownEntry {
+    /** Relative file path */
+    path: string;
+    /** Cooldown cycle count (how many cooldown periods completed) */
+    cooldownCycle: number;
+    /** Last error message */
+    lastError: string;
+    /** Timestamp when added to cooldown (ISO string) */
+    addedAt: string;
+    /** Timestamp of last cooldown retry attempt (ISO string, null if not yet retried) */
+    lastRetryAt: string | null;
+}
+/** Persisted cooldown queue structure */
+export interface PersistedCooldownQueue {
+    /** Version for future schema migrations */
+    version: 1;
+    /** Timestamp when queue was last saved */
+    savedAt: string;
+    /** Next scheduled cooldown retry (ISO string, null if not scheduled) */
+    nextRetryAt: string | null;
+    /** Cooldown entries */
+    entries: CooldownEntry[];
+}
+/** Drift reconciliation statistics */
+export interface DriftStats {
+    /** Files that were deleted while MCP was offline */
+    deletedFiles: number;
+    /** Files that were modified while MCP was offline */
+    modifiedFiles: number;
+    /** Whether drift reconciliation was performed */
+    reconciled: boolean;
+    /** Time taken for reconciliation in ms */
+    reconcileTimeMs: number | null;
+}
+/** Stored metadata for a single file (for mtime-based change detection) */
+export interface FileMetadataEntry {
+    /** File modification time in milliseconds since epoch */
+    mtimeMs: number;
+    /** File size in bytes */
+    size: number;
+}
+/** Map of relative paths to their metadata */
+export type FileMetadataMap = Record<string, FileMetadataEntry>;
+/** Persisted metadata file structure */
+export interface PersistedMetadata {
+    /** Version for future schema migrations */
+    version: 1;
+    /** Timestamp when metadata was last saved */
+    savedAt: string;
+    /** File metadata entries */
+    files: FileMetadataMap;
+}
+/** Status of a single workspace */
+export interface WorkspaceStatus {
+    /** Absolute path to workspace root */
+    root: string;
+    /** Current status */
+    status: WorkspaceStatusType;
+    /** Total files processed (indexed + skipped + failed + pending) */
+    total: number;
+    /** Files skipped (too large, binary, unreadable, etc.) */
+    skipped: number;
+    /** Files that permanently failed indexing */
+    failed: number;
+    /** Number of pending files (change queue + retry queue) */
+    pending: number;
+    /** Number of indexed files */
+    indexed: number;
+    /** Whether file watcher is active */
+    watching: boolean;
+    /** Last indexing timestamp (ISO string) */
+    lastIndexed: string | null;
+    /** Error message if status is 'error' */
+    error?: string;
+    /** Indexing progress if status is 'indexing' */
+    progress?: IndexingProgress;
+    /** Timing information */
+    timing?: {
+        /** ISO timestamp when current indexing started (null if not indexing) */
+        startedAt: string | null;
+        /** Elapsed seconds since indexing started (live during indexing) */
+        elapsedSeconds: number | null;
+        /** Initial full index time in seconds (null if not yet completed) */
+        initialIndexSeconds: number | null;
+        /** Last incremental/delta index time in seconds (null if no deltas yet) */
+        lastDeltaSeconds: number | null;
+    };
+    /** Retry statistics */
+    retry?: RetryStats;
+    /** Concurrency metrics */
+    concurrency?: {
+        /** Current concurrency level */
+        current: number;
+        /** Peak concurrency reached */
+        peak: number;
+        /** Min/max concurrency bounds */
+        bounds: {
+            min: number;
+            max: number;
+        };
+        /** Batch size limits */
+        batchLimits: {
+            maxBytes: number;
+            maxFiles: number;
+        };
+    };
+    /** Drift reconciliation stats (only when persistence enabled) */
+    drift?: DriftStats;
+}
+/** Codebase tool input - search mode */
+export interface CodebaseSearchInput {
+    mode: 'search';
+    query: string;
+    root?: string;
+}
+/** Codebase tool input - ask mode */
+export interface CodebaseAskInput {
+    mode: 'ask';
+    query: string;
+    prompt?: string;
+    root?: string;
+}
+/** Codebase tool input union */
+export type CodebaseInput = CodebaseSearchInput | CodebaseAskInput;
+/** Index tool input - status action */
+export interface IndexStatusInput {
+    action: 'status';
+    root?: string;
+}
+/** Index tool input - list action */
+export interface IndexListInput {
+    action: 'list';
+    root?: string;
+    limit?: number;
+}
+/** Index tool input - reindex action */
+export interface IndexReindexInput {
+    action: 'reindex';
+    root?: string;
+    full?: boolean;
+}
+/** Index tool input union */
+export type IndexInput = IndexStatusInput | IndexListInput | IndexReindexInput;
+/** File entry for indexing */
+export interface FileEntry {
+    /** Relative path from workspace root */
+    path: string;
+    /** File contents */
+    contents: string;
+}
+/** File change event */
+export interface FileChange {
+    type: 'add' | 'change' | 'unlink';
+    path: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for suco-auggie-mcp
+ */
+export {};

package/dist/workspace-manager.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Multi-workspace coordinator
+ */
+import { Workspace } from './workspace.js';
+import type { WorkspaceStatus } from './types.js';
+/** Manages multiple workspaces */
+export declare class WorkspaceManager {
+    private workspaces;
+    private defaultRoot;
+    /** Add a workspace by path */
+    addWorkspace(rootPath: string): Promise<Workspace>;
+    /** Add multiple workspaces, deduplicating by resolved path */
+    addWorkspaces(rootPaths: string[]): Promise<void>;
+    /** Get a workspace by root path, or default if not specified */
+    getWorkspace(root?: string): Workspace | null;
+    /** Resolve root parameter to a workspace, throwing if not found */
+    resolveWorkspace(root?: string): Workspace;
+    /** Get all workspaces */
+    getAllWorkspaces(): Workspace[];
+    /** Get status for all workspaces */
+    getStatus(): WorkspaceStatus[];
+    /** Get indexed paths from all workspaces (relative to workspace root) */
+    getIndexedPaths(): string[];
+    /** Check if any workspaces are configured */
+    hasWorkspaces(): boolean;
+    /** Get count of workspaces */
+    get count(): number;
+    /** Close all workspaces */
+    close(): Promise<void>;
+    /** Re-initialize all workspaces in error state (called when auth becomes available) */
+    reinitializeErrored(): Promise<void>;
+}
+/** Singleton instance */
+export declare const workspaceManager: WorkspaceManager;

package/dist/workspace-manager.js

@@ -0,0 +1,104 @@
+/**
+ * Multi-workspace coordinator
+ */
+import * as path from 'node:path';
+import { Workspace } from './workspace.js';
+import { createLogger } from './logger.js';
+const logger = createLogger('WorkspaceManager');
+/** Manages multiple workspaces */
+export class WorkspaceManager {
+    workspaces = new Map();
+    defaultRoot = null;
+    /** Add a workspace by path */
+    async addWorkspace(rootPath) {
+        const resolved = path.resolve(rootPath);
+        // Check if already exists
+        if (this.workspaces.has(resolved)) {
+            logger.debug(`Workspace already exists: ${resolved}`);
+            return this.workspaces.get(resolved);
+        }
+        logger.info(`Adding workspace: ${resolved}`);
+        const workspace = await Workspace.create(resolved);
+        this.workspaces.set(resolved, workspace);
+        // Set first workspace as default
+        if (this.defaultRoot === null) {
+            this.defaultRoot = resolved;
+        }
+        return workspace;
+    }
+    /** Add multiple workspaces, deduplicating by resolved path */
+    async addWorkspaces(rootPaths) {
+        const uniquePaths = [...new Set(rootPaths.map((p) => path.resolve(p)))];
+        for (const rootPath of uniquePaths) {
+            await this.addWorkspace(rootPath);
+        }
+    }
+    /** Get a workspace by root path, or default if not specified */
+    getWorkspace(root) {
+        if (root) {
+            const resolved = path.resolve(root);
+            return this.workspaces.get(resolved) ?? null;
+        }
+        if (this.defaultRoot) {
+            return this.workspaces.get(this.defaultRoot) ?? null;
+        }
+        return null;
+    }
+    /** Resolve root parameter to a workspace, throwing if not found */
+    resolveWorkspace(root) {
+        const workspace = this.getWorkspace(root);
+        if (!workspace) {
+            if (root) {
+                throw new Error(`Workspace not found: ${root}`);
+            }
+            throw new Error('No workspaces configured');
+        }
+        return workspace;
+    }
+    /** Get all workspaces */
+    getAllWorkspaces() {
+        return [...this.workspaces.values()];
+    }
+    /** Get status for all workspaces */
+    getStatus() {
+        return this.getAllWorkspaces().map((w) => w.getStatus());
+    }
+    /** Get indexed paths from all workspaces (relative to workspace root) */
+    getIndexedPaths() {
+        let paths = [];
+        for (const workspace of this.getAllWorkspaces()) {
+            paths = paths.concat(workspace.getIndexedPaths());
+        }
+        return paths;
+    }
+    /** Check if any workspaces are configured */
+    hasWorkspaces() {
+        return this.workspaces.size > 0;
+    }
+    /** Get count of workspaces */
+    get count() {
+        return this.workspaces.size;
+    }
+    /** Close all workspaces */
+    async close() {
+        const closePromises = [...this.workspaces.values()].map((w) => w.close());
+        await Promise.all(closePromises);
+        this.workspaces.clear();
+        this.defaultRoot = null;
+        logger.info('All workspaces closed');
+    }
+    /** Re-initialize all workspaces in error state (called when auth becomes available) */
+    async reinitializeErrored() {
+        const erroredWorkspaces = this.getAllWorkspaces().filter((w) => w.getStatus().status === 'error');
+        if (erroredWorkspaces.length === 0) {
+            logger.debug('No errored workspaces to reinitialize');
+            return;
+        }
+        logger.info(`Re-initializing ${erroredWorkspaces.length} errored workspace(s)`);
+        for (const workspace of erroredWorkspaces) {
+            await workspace.reinitialize();
+        }
+    }
+}
+/** Singleton instance */
+export const workspaceManager = new WorkspaceManager();