tarsk 0.2.5 → 0.3.0

package/dist/routes/threads.js

@@ -0,0 +1,352 @@
+/**
+ * Thread routes for the REST API
+ *
+ * Handles all thread-related operations:
+ * - POST /api/threads - Create a new thread
+ * - GET /api/threads?projectId=xxx - List threads for a project
+ * - DELETE /api/threads/:id - Delete a thread
+ */
+import { Hono } from 'hono';
+import { validateThreadName } from '../utils/validation.js';
+import { streamAsyncGenerator } from '../lib/stream-helper.js';
+import { ResponseBuilder } from '../lib/response-builder.js';
+const extractTextBlocksFromContent = (content) => {
+    const trimmed = content.trim();
+    if (!trimmed.startsWith('[') && !trimmed.startsWith('{')) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) {
+            return parsed
+                .filter((block) => block && typeof block === 'object' && block.type === 'text')
+                .map((block) => (typeof block.text === 'string' ? block.text : ''))
+                .filter((text) => text.length > 0);
+        }
+        if (parsed && typeof parsed === 'object' && typeof parsed.text === 'string') {
+            return [parsed.text];
+        }
+    }
+    catch {
+        return [];
+    }
+    return [];
+};
+const extractAssistantContent = (events, fallback) => {
+    if (!events || events.length === 0) {
+        return fallback;
+    }
+    const resultEvent = [...events].reverse().find((event) => event.type === 'result');
+    if (resultEvent && typeof resultEvent.content === 'string' && resultEvent.content.trim().length > 0) {
+        return resultEvent.content;
+    }
+    const assistantMessages = events.filter((event) => event.type === 'message' && event.role === 'assistant');
+    let lastTextBlock = null;
+    const assistantChunks = [];
+    for (const event of assistantMessages) {
+        if (typeof event.content !== 'string') {
+            continue;
+        }
+        assistantChunks.push(event.content);
+        const textBlocks = extractTextBlocksFromContent(event.content);
+        if (textBlocks.length > 0) {
+            lastTextBlock = textBlocks[textBlocks.length - 1];
+        }
+    }
+    if (lastTextBlock) {
+        return lastTextBlock;
+    }
+    if (assistantChunks.length === 0) {
+        return fallback;
+    }
+    const combined = assistantChunks.join('');
+    return combined.trim().length > 0 ? combined : fallback;
+};
+export function createThreadRoutes(threadManager, gitManager, conversationManager) {
+    const router = new Hono();
+    /**
+     * POST /api/threads
+     * Create a new thread for a project
+     *
+     * Request body:
+     * {
+     *   "projectId": "uuid",
+     *   "title": "Optional thread title"
+     * }
+     *
+     * Response: Newline-delimited JSON stream of ThreadEvent objects
+     *
+     * Requirements:
+     * - 6.3 - THE CLI SHALL expose REST API endpoints for Thread operations
+     * - 8.3 - WHEN creating a Thread, THE App SHALL send a POST request with the Project identifier to the CLI
+     * - 8.4 - THE CLI SHALL support streaming responses to the client
+     */
+    router.post('/', async (c) => {
+        try {
+            const body = await c.req.json();
+            const { projectId, title } = body;
+            // Validate projectId is provided
+            if (!projectId || typeof projectId !== 'string') {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'projectId is required and must be a string', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            // Validate title if provided
+            if (title !== undefined && typeof title !== 'string') {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'title must be a string if provided', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            // Validate thread name (empty/whitespace is allowed, will auto-generate)
+            if (title && title.trim() !== '') {
+                const nameError = validateThreadName(title);
+                if (nameError) {
+                    const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', nameError, 400);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return c.json(response, statusCode);
+                }
+                // Check for duplicate branch names
+                const existingThreads = await threadManager.listThreads(projectId);
+                const sanitizedNewName = gitManager.sanitizeBranchName(title);
+                const existingSanitized = existingThreads.map(t => gitManager.sanitizeBranchName(t.title));
+                if (existingSanitized.includes(sanitizedNewName)) {
+                    const { response, statusCode } = ResponseBuilder.error('DUPLICATE_BRANCH', `A thread with branch name "${sanitizedNewName}" already exists`, 409);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return c.json(response, statusCode);
+                }
+            }
+            // Stream the thread creation events
+            return streamAsyncGenerator(c, threadManager.createThread(projectId, title));
+        }
+        catch (error) {
+            const { response, statusCode } = ResponseBuilder.error('REQUEST_PARSE_ERROR', 'Failed to parse request body', 400, error instanceof Error ? error.message : String(error));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+    });
+    /**
+     * GET /api/threads?projectId=xxx
+     * List all threads for a specific project
+     *
+     * Query parameters:
+     * - projectId (required): The project ID to filter threads
+     *
+     * Response:
+     * [
+     *   {
+     *     "id": "uuid",
+     *     "projectId": "uuid",
+     *     "title": "Thread title",
+     *     "path": "/path/to/thread",
+     *     "currentBranch": "branch-name",
+     *     "createdAt": "2024-01-01T00:00:00Z"
+     *   }
+     * ]
+     *
+     * Requirements:
+     * - 6.3 - THE CLI SHALL expose REST API endpoints for Thread operations
+     */
+    router.get('/', async (c) => {
+        try {
+            const projectId = c.req.query('projectId');
+            // Validate projectId is provided
+            if (!projectId) {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'projectId query parameter is required', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            const threads = await threadManager.listThreads(projectId);
+            return c.json(threads);
+        }
+        catch (error) {
+            const { response, statusCode } = ResponseBuilder.error('LIST_THREADS_ERROR', 'Failed to list threads', 500, error instanceof Error ? error.message : String(error));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+    });
+    /**
+     * DELETE /api/threads/:id
+     * Delete a thread
+     *
+     * Response:
+     * {
+     *   "success": true,
+     *   "message": "Thread deleted successfully"
+     * }
+     *
+     * Requirements:
+     * - 6.3 - THE CLI SHALL expose REST API endpoints for Thread operations
+     * - 8.4 - WHEN deleting a Thread, THE App SHALL send a DELETE request with the Thread identifier to the CLI
+     */
+    router.delete('/:id', async (c) => {
+        try {
+            const threadId = c.req.param('id');
+            if (!threadId) {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'Thread ID is required', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            await threadManager.deleteThread(threadId);
+            const { response, statusCode } = ResponseBuilder.success({ success: true, message: 'Thread deleted successfully' });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Check if it's a "not found" error
+            if (errorMessage.includes('not found')) {
+                const { response, statusCode } = ResponseBuilder.error('THREAD_NOT_FOUND', errorMessage, 404);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            const { response, statusCode } = ResponseBuilder.error('DELETE_THREAD_ERROR', 'Failed to delete thread', 500, errorMessage);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+    });
+    /**
+     * POST /api/threads/:id/select
+     * Select a thread as the active thread
+     *
+     * Response:
+     * {
+     *   "success": true,
+     *   "message": "Thread selected successfully",
+     *   "threadId": "uuid"
+     * }
+     *
+     * Requirements:
+     * - 6.3 - THE CLI SHALL expose REST API endpoints for Thread operations
+     */
+    router.post('/:id/select', async (c) => {
+        try {
+            const threadId = c.req.param('id');
+            if (!threadId) {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'Thread ID is required', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            // Verify thread exists
+            const thread = await threadManager.getThread(threadId);
+            if (!thread) {
+                const { response, statusCode } = ResponseBuilder.error('THREAD_NOT_FOUND', `Thread not found: ${threadId}`, 404);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            await threadManager.selectThread(threadId);
+            const { response, statusCode } = ResponseBuilder.success({ success: true, message: 'Thread selected successfully', threadId });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+        catch (error) {
+            const { response, statusCode } = ResponseBuilder.error('SELECT_THREAD_ERROR', 'Failed to select thread', 500, error instanceof Error ? error.message : String(error));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+    });
+    /**
+     * GET /api/threads/:id/messages
+     * Get chat history for a thread
+     */
+    router.get('/:id/messages', async (c) => {
+        try {
+            const threadId = c.req.param('id');
+            if (!threadId) {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'Thread ID is required', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            const thread = await threadManager.getThread(threadId);
+            if (!thread) {
+                const { response, statusCode } = ResponseBuilder.error('THREAD_NOT_FOUND', `Thread not found: ${threadId}`, 404);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            const history = await conversationManager.getConversationHistory(thread.path);
+            if (!history || history.messages.length === 0) {
+                return c.json([]);
+            }
+            const messages = history.messages.flatMap((message) => {
+                const userMessage = {
+                    messageId: `user-${message.id}`,
+                    sender: 'user',
+                    content: message.request.message,
+                    contentType: 'text',
+                    timestamp: message.timestamp,
+                    model: message.request.model,
+                    attachments: message.request.attachments?.map((attachment) => ({
+                        fileName: attachment.name,
+                        content: attachment.content,
+                        size: attachment.size,
+                    }))
+                };
+                if (!message.response) {
+                    return [userMessage];
+                }
+                const agentMessage = {
+                    messageId: `agent-${message.id}`,
+                    sender: 'agent',
+                    content: extractAssistantContent(message.response.events, message.response.content),
+                    contentType: 'markdown',
+                    timestamp: message.response.completedAt,
+                    model: message.request.model,
+                };
+                return [userMessage, agentMessage];
+            });
+            return c.json(messages);
+        }
+        catch (error) {
+            const { response, statusCode } = ResponseBuilder.error('GET_THREAD_MESSAGES_ERROR', 'Failed to load thread messages', 500, error instanceof Error ? error.message : String(error));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+    });
+    /**
+     * GET /api/threads/:id/files
+     * List all files in a thread's directory
+     */
+    router.get('/:id/files', async (c) => {
+        try {
+            const threadId = c.req.param('id');
+            if (!threadId) {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'Thread ID is required', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            const files = await threadManager.listFiles(threadId);
+            return c.json(files);
+        }
+        catch (error) {
+            const { response, statusCode } = ResponseBuilder.error('LIST_THREAD_FILES_ERROR', 'Failed to list thread files', 500, error instanceof Error ? error.message : String(error));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+    });
+    /**
+     * PATCH /api/threads/:id
+     * Update thread metadata
+     */
+    router.patch('/:id', async (c) => {
+        try {
+            const threadId = c.req.param('id');
+            const body = await c.req.json();
+            if (!threadId) {
+                const { response, statusCode } = ResponseBuilder.error('INVALID_REQUEST', 'Thread ID is required', 400);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response, statusCode);
+            }
+            await threadManager.updateThread(threadId, body);
+            const { response, statusCode } = ResponseBuilder.success({ success: true, message: 'Thread updated successfully' });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const { response, statusCode } = ResponseBuilder.error('UPDATE_THREAD_ERROR', 'Failed to update thread', 500, errorMessage);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response, statusCode);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=threads.js.map

package/dist/types/models.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Data models for the Project Threads Manager
+ *
+ * This file defines the core data structures used throughout the application
+ * for projects, threads, chat messages, and file attachments.
+ */
+/**
+ * Available IDEs/editors for opening projects
+ */
+export declare const AVAILABLE_PROGRAMS: string[];
+/**
+ * Command represents a custom shell command that can be run on a project
+ */
+export interface Command {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Lucide icon name */
+    icon: string;
+    /** The shell command to execute */
+    commandLine: string;
+}
+/**
+ * Project represents a git repository with associated threads
+ */
+export interface Project {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** Project name derived from git URL */
+    name: string;
+    /** Original git repository URL */
+    gitUrl: string;
+    /** Absolute path to project folder */
+    path: string;
+    /** Timestamp when project was created */
+    createdAt: Date;
+    /** Array of thread IDs belonging to this project */
+    threads: string[];
+    /** Preferred IDE to open the project in (VS Code, Cursor, Windsurf, Xcode, Android Studio) */
+    openWith?: string;
+    /** Custom commands defined for this project */
+    commands?: Command[];
+}
+/**
+ * Thread represents a specific clone instance of a project's git repository
+ */
+export interface Thread {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** Parent project ID */
+    projectId: string;
+    /** User-defined or auto-generated title */
+    title: string;
+    /** Absolute path to thread folder */
+    path: string;
+    /** Current git branch for this thread */
+    currentBranch: string;
+    /** Timestamp when thread was created */
+    createdAt: Date;
+}
+/**
+ * ChatMessage represents a message in the agent conversation
+ * (Frontend only - not persisted by CLI)
+ */
+export interface ChatMessage {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** Associated thread ID */
+    threadId: string;
+    /** Message sender role */
+    role: 'user' | 'agent';
+    /** Message content */
+    content: string;
+    /** Timestamp when message was sent */
+    timestamp: Date;
+    /** Optional file attachments */
+    attachments?: FileAttachment[];
+}
+/**
+ * FileAttachment represents a file attached to a chat message
+ */
+export interface FileAttachment {
+    /** File name */
+    name: string;
+    /** File path relative to thread */
+    path: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type of the file */
+    mimeType: string;
+}
+/**
+ * Event types for streaming operations
+ */
+/**
+ * ProjectEvent is yielded during project creation operations
+ */
+export interface ProjectEvent {
+    /** Event type */
+    type: 'progress' | 'complete' | 'error';
+    /** Progress or error message */
+    message?: string;
+    /** Error details (only present on 'error' type) */
+    error?: unknown;
+    /** Completed project data (only present on 'complete' type) */
+    project?: Project;
+}
+/**
+ * ThreadEvent is yielded during thread creation operations
+ */
+export interface ThreadEvent {
+    /** Event type */
+    type: 'progress' | 'complete' | 'error';
+    /** Progress or error message */
+    message?: string;
+    /** Error details (only present on 'error' type) */
+    error?: unknown;
+    /** Completed thread data (only present on 'complete' type) */
+    thread?: Thread;
+}
+/**
+ * GitEvent is yielded during git clone operations
+ */
+export interface GitEvent {
+    /** Event type */
+    type: 'stdout' | 'stderr' | 'complete' | 'error';
+    /** Output data from git command */
+    data?: string;
+    /** Error message (only present on 'error' type) */
+    message?: string;
+    /** Error details (only present on 'error' type) */
+    error?: unknown;
+}
+/**
+ * NeovateEvent is yielded during neovate SDK prompt execution
+ */
+export interface NeovateEvent {
+    /** Event type */
+    type: 'message' | 'result' | 'error';
+    /** Role of the message sender (for 'message' type) */
+    role?: string;
+    /** Message or result content */
+    content?: string;
+    /** Error details (only present on 'error' type) */
+    error?: {
+        /** Machine-readable error code */
+        code?: string;
+        /** Human-readable error message */
+        message: string;
+        /** Additional error context */
+        details?: unknown;
+    };
+}
+/**
+ * ExecutionContext provides context for neovate SDK prompt execution
+ */
+export interface ExecutionContext {
+    /** Thread ID for context */
+    threadId: string;
+    /** Absolute path to thread directory */
+    threadPath: string;
+    /** Optional model selection */
+    model?: string;
+    /** Optional provider selection (e.g., 'openrouter', 'anthropic') */
+    provider?: string;
+    /** Optional file attachments */
+    attachments?: FileData[];
+    /** Optional plan mode flag */
+    planMode?: boolean;
+}
+/**
+ * FileData represents file data for transmission over API
+ */
+export interface FileData {
+    /** File name */
+    name: string;
+    /** File content (base64 encoded for binary files) */
+    content: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    mimeType: string;
+}
+/**
+ * API Request/Response types
+ */
+/**
+ * ChatRequest is sent from frontend to CLI for chat messages
+ */
+export interface ChatRequest {
+    /** Thread ID for context */
+    threadId: string;
+    /** User message content */
+    content: string;
+    /** Selected model */
+    model: string;
+    /** Selected provider (lowercased name like 'openrouter', 'anthropic', etc.) */
+    provider?: string;
+    /** Optional file attachments */
+    attachments?: FileData[];
+    /** Optional plan mode flag */
+    planMode?: boolean;
+}
+/**
+ * ChatResponse is streamed from CLI to frontend during chat
+ */
+export interface ChatResponse {
+    /** Message ID */
+    messageId: string;
+    /** Response content (may be partial during streaming) */
+    content: string;
+    /** Whether the response is complete */
+    isComplete: boolean;
+}
+/**
+ * StreamEvent wraps streaming responses with type information
+ */
+export interface StreamEvent<T> {
+    /** Event type */
+    type: 'progress' | 'complete' | 'error';
+    /** Event data (type depends on T) */
+    data?: T;
+    /** Progress or error message */
+    message?: string;
+    /** Progress percentage (0-100) */
+    progress?: number;
+}
+/**
+ * ErrorResponse is returned for failed API operations
+ */
+export interface ErrorResponse {
+    error: {
+        /** Machine-readable error code */
+        code: string;
+        /** Human-readable error message */
+        message: string;
+        /** Additional error context */
+        details?: unknown;
+        /** ISO 8601 timestamp */
+        timestamp: string;
+    };
+}
+/**
+ * Conversation history types
+ */
+/**
+ * ConversationMessage represents a single request/response exchange
+ */
+export interface ConversationMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Timestamp of the request */
+    timestamp: string;
+    /** User's request */
+    request: {
+        /** User message content */
+        message: string;
+        /** Model used for the request */
+        model: string;
+        /** Optional file attachments */
+        attachments?: FileData[];
+        /** Optional plan mode flag */
+        planMode?: boolean;
+    };
+    /** Agent's response (null if incomplete) */
+    response: {
+        /** Complete response content */
+        content: string;
+        /** All events captured during execution */
+        events: NeovateEvent[];
+        /** Response completion timestamp */
+        completedAt: string;
+    } | null;
+}
+/**
+ * ConversationHistory stores all conversation messages for a thread
+ */
+export interface ConversationHistory {
+    /** Thread ID */
+    threadId: string;
+    /** Array of conversation messages */
+    messages: ConversationMessage[];
+    /** Last updated timestamp */
+    lastUpdated: string;
+}
+/**
+ * Model represents an AI model available from a provider
+ */
+export interface Model {
+    /** Unique model identifier (e.g., "gpt-4", "openrouter/gpt-4") */
+    id: string;
+    /** Human-readable model name */
+    name: string;
+    /** Detailed description of the model */
+    description: string;
+    /** Provider that offers this model */
+    provider: string;
+    /**
+     * Pricing information for the model (optional).
+     * If omitted, pricing is unknown for this provider/model.
+     */
+    pricing?: {
+        /** Cost per token in USD */
+        prompt: number;
+        /** Cost per token in USD */
+        completion: number;
+    };
+    /** Supported parameters for this model (optional) */
+    supportedParameters?: {
+        /** Whether this model supports function/tool calling */
+        tools?: boolean;
+    };
+}
+//# sourceMappingURL=models.d.ts.map

package/dist/types/models.js

@@ -0,0 +1,11 @@
+/**
+ * Data models for the Project Threads Manager
+ *
+ * This file defines the core data structures used throughout the application
+ * for projects, threads, chat messages, and file attachments.
+ */
+/**
+ * Available IDEs/editors for opening projects
+ */
+export const AVAILABLE_PROGRAMS = ['VS Code', 'Cursor', 'Windsurf', 'Xcode', 'Android Studio', 'Kiro'];
+//# sourceMappingURL=models.js.map

package/dist/utils/env-manager.d.ts

@@ -0,0 +1,3 @@
+export declare function updateEnvFile(keyNames: Record<string, string>): Promise<void>;
+export declare function readEnvFile(): Promise<Record<string, string>>;
+//# sourceMappingURL=env-manager.d.ts.map