tarsk 0.2.5 → 0.3.0

package/dist/managers/ThreadManager.js

@@ -0,0 +1,325 @@
+/**
+ * ThreadManager handles thread lifecycle and metadata management
+ *
+ * This manager is responsible for:
+ * - Creating new threads for existing projects
+ * - Managing thread metadata
+ * - Coordinating with GitManager for repository cloning
+ * - Providing CRUD operations for threads
+ * - Ensuring thread path uniqueness
+ */
+import { randomUUID } from 'crypto';
+import { join } from 'path';
+/**
+ * ThreadManagerImpl provides the implementation for thread operations
+ */
+export class ThreadManagerImpl {
+    metadataManager;
+    gitManager;
+    /**
+     * Create a new ThreadManager
+     * @param metadataManager - Manager for persisting metadata
+     * @param gitManager - Manager for git operations
+     *
+     * Requirements:
+     * - 2.1 - WHEN a user creates a new Thread for a Project, THE CLI SHALL create a new clone of the Project's git repository
+     * - 2.4 - THE System SHALL maintain a title for each Thread
+     */
+    constructor(metadataManager, gitManager) {
+        this.metadataManager = metadataManager;
+        this.gitManager = gitManager;
+    }
+    /**
+     * Creates a new thread for an existing project
+     *
+     * This method:
+     * 1. Validates that the project exists
+     * 2. Generates a unique thread ID
+     * 3. Gets the project's git URL
+     * 4. Generates a unique thread path
+     * 5. Delegates to GitManager for cloning
+     * 6. Saves thread metadata
+     * 7. Updates the project's thread list
+     * 8. Yields progress events during the operation
+     *
+     * @param projectId - The parent project ID
+     * @param title - Optional thread title (auto-generated if not provided)
+     * @yields ThreadEvent objects during the creation process
+     *
+     * Requirements:
+     * - 2.1 - WHEN a user creates a new Thread for a Project, THE CLI SHALL create a new clone of the Project's git repository
+     * - 2.2 - WHEN a Thread is created, THE App SHALL display it under its parent Project in the Side_Panel
+     * - 2.4 - THE System SHALL maintain a title for each Thread
+     * - 7.4 - THE CLI SHALL ensure each Thread clone is stored in a unique directory path
+     */
+    async *createThread(projectId, title) {
+        try {
+            // Load project to verify it exists and get git URL
+            const projects = await this.metadataManager.loadProjects();
+            const project = projects.find(p => p.id === projectId);
+            if (!project) {
+                yield {
+                    type: 'error',
+                    message: `Project not found: ${projectId}`
+                };
+                return;
+            }
+            // Generate unique thread ID
+            const threadId = randomUUID();
+            // Generate thread path: {projectPath}/{threadId}
+            const threadPath = this.generateThreadPath(project.path, threadId);
+            // Generate thread title if not provided
+            const existingThreads = await this.metadataManager.loadThreads();
+            const existingTitles = new Set(existingThreads
+                .filter(t => t.projectId === projectId)
+                .map(t => t.title));
+            const threadTitle = title || this.generateThreadTitle(existingTitles, threadId, project.name);
+            yield {
+                type: 'progress',
+                message: `Creating thread "${threadTitle}" for project "${project.name}"...`
+            };
+            yield {
+                type: 'progress',
+                message: `Cloning repository to ${threadPath}...`
+            };
+            // Stream git clone events
+            for await (const gitEvent of this.gitManager.cloneRepository(project.gitUrl, threadPath)) {
+                if (gitEvent.type === 'error') {
+                    yield {
+                        type: 'error',
+                        message: `Git clone failed: ${gitEvent.message}`
+                    };
+                    return;
+                }
+                else if (gitEvent.type === 'stdout' || gitEvent.type === 'stderr') {
+                    yield {
+                        type: 'progress',
+                        message: gitEvent.data
+                    };
+                }
+            }
+            // Sanitize the thread title to create a valid branch name
+            let branchName = this.gitManager.sanitizeBranchName(threadTitle);
+            yield {
+                type: 'progress',
+                message: `Creating branch "${branchName}"...`
+            };
+            // Check if branch exists and find a unique name if needed
+            let branchExists = await this.gitManager.checkBranchExists(threadPath, branchName);
+            let counter = 2;
+            const baseBranchName = branchName;
+            while (branchExists) {
+                branchName = `${baseBranchName}-${counter}`;
+                branchExists = await this.gitManager.checkBranchExists(threadPath, branchName);
+                counter++;
+            }
+            if (branchName !== baseBranchName) {
+                yield {
+                    type: 'progress',
+                    message: `Branch "${baseBranchName}" exists, using "${branchName}" instead`
+                };
+            }
+            // Create and checkout the new branch
+            for await (const gitEvent of this.gitManager.createAndCheckoutBranch(threadPath, branchName)) {
+                if (gitEvent.type === 'error') {
+                    yield {
+                        type: 'error',
+                        message: `Failed to create branch: ${gitEvent.message}`
+                    };
+                    return;
+                }
+                else if (gitEvent.type === 'stdout' || gitEvent.type === 'stderr') {
+                    yield {
+                        type: 'progress',
+                        message: gitEvent.data
+                    };
+                }
+            }
+            yield {
+                type: 'progress',
+                message: `Branch "${branchName}" created and checked out`
+            };
+            // Create thread metadata
+            const thread = {
+                id: threadId,
+                projectId,
+                title: threadTitle,
+                path: threadPath,
+                currentBranch: branchName,
+                createdAt: new Date()
+            };
+            // Save thread metadata
+            const threads = await this.metadataManager.loadThreads();
+            threads.push(thread);
+            await this.metadataManager.saveThreads(threads);
+            // Update project's thread list
+            project.threads.push(threadId);
+            const updatedProjects = projects.map(p => p.id === projectId ? project : p);
+            await this.metadataManager.saveProjects(updatedProjects);
+            yield {
+                type: 'progress',
+                message: `Thread "${threadTitle}" created successfully`
+            };
+            // Yield complete event with thread data
+            yield {
+                type: 'complete',
+                message: 'Thread creation complete',
+                thread
+            };
+        }
+        catch (error) {
+            yield {
+                type: 'error',
+                message: `Failed to create thread: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    /**
+     * Gets a thread by ID
+     * @param threadId - The thread ID
+     * @returns The thread or null if not found
+     */
+    async getThread(threadId) {
+        const threads = await this.metadataManager.loadThreads();
+        return threads.find(t => t.id === threadId) || null;
+    }
+    /**
+     * Lists all threads for a specific project
+     * @param projectId - The project ID to filter threads
+     * @returns Array of threads for the project
+     *
+     * Requirements:
+     * - 2.1 - WHEN a Thread is created, THE App SHALL display it under its parent Project in the Side_Panel
+     */
+    async listThreads(projectId) {
+        const threads = await this.metadataManager.loadThreads();
+        return threads.filter(t => t.projectId === projectId);
+    }
+    /**
+     * Deletes a thread and removes its directory
+     *
+     * This method:
+     * 1. Finds the thread by ID
+     * 2. Removes the thread directory from filesystem
+     * 3. Removes the thread from metadata
+     * 4. Updates the parent project's thread list
+     *
+     * @param threadId - The thread ID to delete
+     * @throws Error if thread not found
+     *
+     * Requirements:
+     * - 2.3 - WHEN a user deletes a Thread, THE System SHALL remove the Thread's folder and update the Side_Panel display
+     * - 7.5 - WHEN a Thread is deleted, THE CLI SHALL remove the associated git repository clone from the filesystem
+     */
+    async deleteThread(threadId) {
+        const threads = await this.metadataManager.loadThreads();
+        const threadIndex = threads.findIndex(t => t.id === threadId);
+        if (threadIndex === -1) {
+            throw new Error(`Thread not found: ${threadId}`);
+        }
+        const thread = threads[threadIndex];
+        // Remove thread directory from filesystem
+        try {
+            const { rm } = await import('fs/promises');
+            await rm(thread.path, { recursive: true, force: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to remove thread directory: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Remove thread from metadata
+        threads.splice(threadIndex, 1);
+        await this.metadataManager.saveThreads(threads);
+        // Update parent project's thread list
+        const projects = await this.metadataManager.loadProjects();
+        const project = projects.find(p => p.id === thread.projectId);
+        if (project) {
+            project.threads = project.threads.filter(id => id !== threadId);
+            await this.metadataManager.saveProjects(projects);
+        }
+    }
+    /**
+     * Updates a thread's metadata with partial data
+     *
+     * This method loads all threads, finds the target, merges the updates,
+     * and persists the result.
+     *
+     * @param threadId - The thread ID to update
+     * @param updates - Partial thread data to merge
+     * @throws Error if thread not found
+     */
+    async updateThread(threadId, updates) {
+        const threads = await this.metadataManager.loadThreads();
+        const threadIndex = threads.findIndex(t => t.id === threadId);
+        if (threadIndex === -1) {
+            throw new Error(`Thread not found: ${threadId}`);
+        }
+        threads[threadIndex] = { ...threads[threadIndex], ...updates };
+        await this.metadataManager.saveThreads(threads);
+    }
+    /**
+     * Selects a thread as the active thread
+     *
+     * @param threadId - The thread ID to select
+     */
+    async selectThread(threadId) {
+        await this.metadataManager.setSelectedThread(threadId);
+    }
+    /**
+     * Gets the currently selected thread ID
+     *
+     * @returns The selected thread ID or null
+     */
+    async getSelectedThreadId() {
+        return await this.metadataManager.getSelectedThread();
+    }
+    /**
+     * Generates a unique thread path
+     *
+     * Path format: {projectPath}/{threadId}
+     *
+     * This ensures thread paths are unique across all projects and threads.
+     *
+     * @param projectPath - The parent project path
+     * @param threadId - The thread ID
+     * @returns The absolute path to the thread folder
+     *
+     * Requirements:
+     * - 7.4 - THE CLI SHALL ensure each Thread clone is stored in a unique directory path
+     */
+    generateThreadPath(projectPath, threadId) {
+        return join(projectPath, threadId);
+    }
+    /**
+     * Generates a thread title if not provided
+     *
+     * Format: project-name Thread word1-word2
+     *
+     * @param existingTitles - Set of titles already in use
+     * @param threadId - Thread ID used as a fallback
+     * @param projectName - Optional project name to include in title
+     * @returns The generated thread title
+     */
+    generateThreadTitle(existingTitles, threadId, projectName) {
+        const wordsA = [
+            'amber', 'brisk', 'calm', 'drift', 'ember', 'frost', 'glow', 'hollow',
+            'ivory', 'jolly', 'keen', 'lucid', 'mellow', 'noble', 'opal', 'prism',
+            'quiet', 'ripple', 'sunny', 'timber', 'ultra', 'vivid', 'wisp', 'zen'
+        ];
+        const wordsB = [
+            'arch', 'bay', 'crest', 'dune', 'echo', 'fjord', 'glen', 'harbor',
+            'isle', 'jewel', 'knoll', 'lagoon', 'mesa', 'nest', 'oasis', 'peak',
+            'quarry', 'reef', 'strand', 'trail', 'vale', 'wharf', 'yard', 'zephyr'
+        ];
+        const prefix = projectName ? `${projectName} Thread ` : 'Thread ';
+        for (let attempt = 0; attempt < 12; attempt += 1) {
+            const word1 = wordsA[Math.floor(Math.random() * wordsA.length)];
+            const word2 = wordsB[Math.floor(Math.random() * wordsB.length)];
+            const candidate = `${prefix}${word1}-${word2}`;
+            if (!existingTitles.has(candidate)) {
+                return candidate;
+            }
+        }
+        return `${prefix}${threadId.slice(0, 8)}`;
+    }
+}
+//# sourceMappingURL=ThreadManager.js.map

package/dist/managers/conversation-manager.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ConversationManager handles conversation history storage and retrieval
+ *
+ * This manager is responsible for:
+ * - Storing request/response pairs in JSON format
+ * - Retrieving conversation history for a thread
+ * - Managing conversation persistence
+ */
+import { ConversationHistory, ConversationMessage, NeovateEvent, FileData } from '../types/models.js';
+/**
+ * ConversationManager interface defines the contract for conversation operations
+ */
+export interface ConversationManager {
+    /**
+     * Starts a new conversation message (request captured)
+     * @param threadId - The thread ID
+     * @param threadPath - The absolute path to the thread directory
+     * @param message - The user's message
+     * @param model - The model being used
+     * @param attachments - Optional file attachments
+     * @param planMode - Optional plan mode flag
+     * @returns The message ID for this conversation
+     */
+    startMessage(threadId: string, threadPath: string, message: string, model: string, attachments?: FileData[], planMode?: boolean): Promise<string>;
+    /**
+     * Completes a conversation message (response captured)
+     * @param threadPath - The absolute path to the thread directory
+     * @param messageId - The message ID to complete
+     * @param content - The complete response content
+     * @param events - All events captured during execution
+     */
+    completeMessage(threadPath: string, messageId: string, content: string, events: NeovateEvent[]): Promise<void>;
+    /**
+     * Gets the conversation history for a thread
+     * @param threadPath - The absolute path to the thread directory
+     * @returns The conversation history or null if not found
+     */
+    getConversationHistory(threadPath: string): Promise<ConversationHistory | null>;
+    /**
+     * Gets the last N messages from conversation history
+     * @param threadPath - The absolute path to the thread directory
+     * @param count - Number of messages to retrieve (default: 1)
+     * @returns Array of conversation messages
+     */
+    getLastMessages(threadPath: string, count?: number): Promise<ConversationMessage[]>;
+}
+/**
+ * ConversationManagerImpl provides the implementation for conversation operations
+ */
+export declare class ConversationManagerImpl implements ConversationManager {
+    private metadataDir;
+    /**
+     * Create a new ConversationManagerImpl
+     * @param rootFolder - Base directory where metadata will be stored
+     */
+    constructor(rootFolder?: string);
+    /**
+     * Starts a new conversation message
+     */
+    startMessage(threadId: string, threadPath: string, message: string, model: string, attachments?: FileData[], planMode?: boolean): Promise<string>;
+    /**
+     * Completes a conversation message
+     */
+    completeMessage(threadPath: string, messageId: string, content: string, events: NeovateEvent[]): Promise<void>;
+    /**
+     * Gets the conversation history for a thread
+     */
+    getConversationHistory(threadPath: string): Promise<ConversationHistory | null>;
+    /**
+     * Gets the last N messages from conversation history
+     */
+    getLastMessages(threadPath: string, count?: number): Promise<ConversationMessage[]>;
+    /**
+     * Saves conversation history to file
+     */
+    private saveConversationHistory;
+    /**
+     * Gets the file path for a thread's conversation history in the metadata folder
+     * Extracts threadId from threadPath and stores in .metadata/conversations/<threadId>/history.json
+     */
+    private getConversationFilePath;
+}
+//# sourceMappingURL=conversation-manager.d.ts.map

package/dist/managers/conversation-manager.js

@@ -0,0 +1,129 @@
+/**
+ * ConversationManager handles conversation history storage and retrieval
+ *
+ * This manager is responsible for:
+ * - Storing request/response pairs in JSON format
+ * - Retrieving conversation history for a thread
+ * - Managing conversation persistence
+ */
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+import { randomUUID } from 'crypto';
+const CONVERSATION_FILE = 'conversation-history.json';
+const METADATA_DIR = '.metadata';
+/**
+ * ConversationManagerImpl provides the implementation for conversation operations
+ */
+export class ConversationManagerImpl {
+    metadataDir;
+    /**
+     * Create a new ConversationManagerImpl
+     * @param rootFolder - Base directory where metadata will be stored
+     */
+    constructor(rootFolder = './projects') {
+        this.metadataDir = join(rootFolder, METADATA_DIR);
+    }
+    /**
+     * Starts a new conversation message
+     */
+    async startMessage(threadId, threadPath, message, model, attachments, planMode) {
+        const messageId = randomUUID();
+        const timestamp = new Date().toISOString();
+        // Load existing history or create new
+        let history = await this.getConversationHistory(threadPath);
+        if (!history) {
+            history = {
+                threadId,
+                messages: [],
+                lastUpdated: timestamp,
+            };
+        }
+        // Create incomplete message (will be completed later)
+        const incompleteMessage = {
+            id: messageId,
+            timestamp,
+            request: {
+                message,
+                model,
+                ...(attachments && { attachments }),
+                ...(planMode && { planMode }),
+            },
+            response: null,
+        };
+        history.messages.push(incompleteMessage);
+        history.lastUpdated = timestamp;
+        // Save to file
+        await this.saveConversationHistory(threadPath, history);
+        return messageId;
+    }
+    /**
+     * Completes a conversation message
+     */
+    async completeMessage(threadPath, messageId, content, events) {
+        const history = await this.getConversationHistory(threadPath);
+        if (!history) {
+            throw new Error('Conversation history not found');
+        }
+        // Find the message to complete
+        const message = history.messages.find((m) => m.id === messageId);
+        if (!message) {
+            throw new Error(`Message ${messageId} not found in conversation history`);
+        }
+        // Complete the message with response data
+        message.response = {
+            content,
+            events,
+            completedAt: new Date().toISOString(),
+        };
+        history.lastUpdated = new Date().toISOString();
+        // Save to file
+        await this.saveConversationHistory(threadPath, history);
+    }
+    /**
+     * Gets the conversation history for a thread
+     */
+    async getConversationHistory(threadPath) {
+        try {
+            const filePath = this.getConversationFilePath(threadPath);
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (error instanceof Error && error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Gets the last N messages from conversation history
+     */
+    async getLastMessages(threadPath, count = 1) {
+        const history = await this.getConversationHistory(threadPath);
+        if (!history || history.messages.length === 0) {
+            return [];
+        }
+        // Return last N messages
+        return history.messages.slice(-count);
+    }
+    /**
+     * Saves conversation history to file
+     */
+    async saveConversationHistory(threadPath, history) {
+        const filePath = this.getConversationFilePath(threadPath);
+        // Ensure all parent directories exist
+        await fs.mkdir(dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(history, null, 2), 'utf-8');
+    }
+    /**
+     * Gets the file path for a thread's conversation history in the metadata folder
+     * Extracts threadId from threadPath and stores in .metadata/conversations/<threadId>/history.json
+     */
+    getConversationFilePath(threadPath) {
+        // Extract thread ID from path (last part of the path)
+        const threadId = threadPath.split(/[\\/]/).pop() || 'unknown';
+        const conversationsDir = join(this.metadataDir, 'conversations');
+        return join(conversationsDir, threadId, CONVERSATION_FILE);
+    }
+}
+//# sourceMappingURL=conversation-manager.js.map

package/dist/managers/git-manager.d.ts

@@ -0,0 +1,133 @@
+/**
+ * GitManager handles git operations including URL validation and repository cloning
+ *
+ * This manager is responsible for:
+ * - Validating git URLs in various formats
+ * - Cloning repositories with streaming output
+ * - Handling git operation errors
+ */
+import { GitEvent } from '../types/models.js';
+/**
+ * GitManager interface defines the contract for git operations
+ */
+export interface GitManager {
+    /**
+     * Validates a git URL format
+     * @param url - The git URL to validate
+     * @returns true if the URL is a valid git URL, false otherwise
+     */
+    validateGitUrl(url: string): boolean;
+    /**
+     * Clones a git repository to the specified target path
+     * @param gitUrl - The git repository URL to clone
+     * @param targetPath - The local path where the repository should be cloned
+     * @yields GitEvent objects for stdout, stderr, complete, and error events
+     */
+    cloneRepository(gitUrl: string, targetPath: string): AsyncGenerator<GitEvent>;
+    /**
+     * Sanitizes a branch name to ensure it only contains valid git branch characters
+     * Replaces spaces with dashes and removes invalid characters
+     * @param name - The branch name to sanitize
+     * @returns The sanitized branch name
+     */
+    sanitizeBranchName(name: string): string;
+    /**
+     * Checks if a branch exists in a git repository
+     * @param repoPath - The path to the git repository
+     * @param branchName - The branch name to check
+     * @returns true if the branch exists, false otherwise
+     */
+    checkBranchExists(repoPath: string, branchName: string): Promise<boolean>;
+    /**
+     * Creates and checks out a new branch in a git repository
+     * @param repoPath - The path to the git repository
+     * @param branchName - The branch name to create
+     * @yields GitEvent objects for stdout, stderr, complete, and error events
+     */
+    createAndCheckoutBranch(repoPath: string, branchName: string): AsyncGenerator<GitEvent>;
+}
+/**
+ * GitManagerImpl provides the implementation for git operations
+ */
+export declare class GitManagerImpl implements GitManager {
+    /**
+     * Regular expressions for validating different git URL formats
+     */
+    private readonly gitUrlPatterns;
+    /**
+     * Validates a git URL against common git URL formats
+     *
+     * Supports the following formats:
+     * - HTTPS: https://github.com/user/repo.git
+     * - Git protocol: git://github.com/user/repo.git
+     * - SSH (git@): git@github.com:user/repo.git
+     * - SSH (ssh://): ssh://git@github.com/user/repo.git
+     *
+     * @param url - The URL to validate
+     * @returns true if the URL matches a valid git URL format, false otherwise
+     *
+     * Requirements: 7.1 - WHEN cloning a git repository, THE CLI SHALL validate the git URL format
+     */
+    validateGitUrl(url: string): boolean;
+    /**
+     * Clones a git repository to the specified target path with streaming output
+     *
+     * This method:
+     * 1. Validates the git URL
+     * 2. Creates the target directory if needed
+     * 3. Spawns a git clone process
+     * 4. Streams stdout and stderr output
+     * 5. Handles completion and errors
+     *
+     * @param gitUrl - The git repository URL to clone
+     * @param targetPath - The local path where the repository should be cloned
+     * @yields GitEvent objects during the clone operation
+     *
+     * Requirements:
+     * - 1.1 - WHEN a user provides a git URL to create a new Project, THE CLI SHALL clone the repository
+     * - 1.3 - WHEN the clone operation executes, THE CLI SHALL stream the git clone output back to the App
+     * - 7.1 - WHEN cloning a git repository, THE CLI SHALL validate the git URL format
+     * - 7.2 - IF a git clone operation fails, THEN THE CLI SHALL return a descriptive error message
+     * - 7.3 - WHEN a clone operation is in progress, THE CLI SHALL stream git output to provide progress feedback
+     */
+    cloneRepository(gitUrl: string, targetPath: string): AsyncGenerator<GitEvent>;
+    /**
+     * Sanitizes a branch name to ensure it only contains valid git branch characters
+     *
+     * This method:
+     * 1. Trims whitespace
+     * 2. Converts to lowercase
+     * 3. Replaces spaces with dashes
+     * 4. Removes invalid characters (only allows alphanumeric, dash, underscore, slash, dot)
+     * 5. Removes leading/trailing slashes and dots
+     * 6. Collapses multiple consecutive dashes into one
+     *
+     * @param name - The branch name to sanitize
+     * @returns The sanitized branch name (all lowercase)
+     */
+    sanitizeBranchName(name: string): string;
+    /**
+     * Checks if a branch exists in a git repository
+     *
+     * Uses `git show-ref` to check for the branch without checking out
+     *
+     * @param repoPath - The path to the git repository
+     * @param branchName - The branch name to check
+     * @returns true if the branch exists, false otherwise
+     */
+    checkBranchExists(repoPath: string, branchName: string): Promise<boolean>;
+    /**
+     * Creates and checks out a new branch in a git repository with streaming output
+     *
+     * This method:
+     * 1. Creates a new branch from the current HEAD
+     * 2. Checks out the new branch
+     * 3. Streams output during the operation
+     *
+     * @param repoPath - The path to the git repository
+     * @param branchName - The branch name to create
+     * @yields GitEvent objects during the branch creation
+     */
+    createAndCheckoutBranch(repoPath: string, branchName: string): AsyncGenerator<GitEvent>;
+}
+//# sourceMappingURL=git-manager.d.ts.map