tarsk 0.2.5 → 0.3.0

package/dist/managers/project-manager.js

@@ -0,0 +1,465 @@
+/**
+ * ProjectManager handles project lifecycle and metadata management
+ *
+ * This manager is responsible for:
+ * - Creating new projects from git URLs
+ * - Managing project metadata
+ * - Coordinating with GitManager for repository cloning
+ * - Providing CRUD operations for projects
+ */
+import { randomUUID } from 'crypto';
+import { join, relative } from 'path';
+import { realpathSync } from 'fs';
+/**
+ * ProjectManagerImpl provides the implementation for project operations
+ */
+export class ProjectManagerImpl {
+    rootFolder;
+    metadataManager;
+    gitManager;
+    /**
+     * Create a new ProjectManager
+     * @param rootFolder - Base directory where projects will be stored
+     * @param metadataManager - Manager for persisting metadata
+     * @param gitManager - Manager for git operations
+     *
+     * Requirements:
+     * - 1.1 - WHEN a user provides a git URL to create a new Project, THE CLI SHALL clone the repository into a folder under the Root_Folder
+     * - 1.4 - THE CLI SHALL determine the storage path for each Project folder
+     */
+    constructor(rootFolder, metadataManager, gitManager) {
+        this.rootFolder = rootFolder;
+        this.metadataManager = metadataManager;
+        this.gitManager = gitManager;
+    }
+    /**
+     * Creates a new project from a git URL
+     *
+     * This method:
+     * 1. Validates the git URL
+     * 2. Generates a unique project ID
+     * 3. Derives the project name from the git URL
+     * 4. Generates the project path
+     * 5. Delegates to GitManager for cloning
+     * 6. Saves project metadata
+     * 7. Yields progress events during the operation
+     * 8. Creates an initial thread automatically
+     *
+     * @param gitUrl - The git repository URL
+     * @yields ProjectEvent objects during the creation process
+     *
+     * Requirements:
+     * - 1.1 - WHEN a user provides a git URL to create a new Project, THE CLI SHALL clone the repository into a folder under the Root_Folder
+     * - 1.2 - WHEN a Project is created, THE App SHALL display the Project in the Side_Panel with its associated Thread
+     * - 1.4 - THE CLI SHALL determine the storage path for each Project folder
+     * - 1.5 - WHEN a Project folder is created, THE System SHALL associate it with the provided git URL
+     */
+    async *createProject(gitUrl) {
+        // Validate git URL
+        if (!this.gitManager.validateGitUrl(gitUrl)) {
+            yield {
+                type: 'error',
+                message: `Invalid git URL format: ${gitUrl}`
+            };
+            return;
+        }
+        try {
+            // Generate unique project ID
+            const projectId = randomUUID();
+            // Derive project name from git URL
+            const projectName = this.deriveProjectName(gitUrl);
+            // Generate project path
+            const projectPath = this.generateProjectPath(projectName);
+            yield {
+                type: 'progress',
+                message: `Creating project "${projectName}" from ${gitUrl}...`
+            };
+            // Generate unique thread ID for the initial thread
+            const initialThreadId = randomUUID();
+            const firstThreadPath = join(projectPath, initialThreadId);
+            yield {
+                type: 'progress',
+                message: `Cloning repository to ${firstThreadPath}...`
+            };
+            // Stream git clone events
+            for await (const gitEvent of this.gitManager.cloneRepository(gitUrl, firstThreadPath)) {
+                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
+                    };
+                }
+            }
+            // Create and checkout branch for initial thread
+            const initialThreadTitle = 'Thread 1';
+            let branchName = this.gitManager.sanitizeBranchName(initialThreadTitle);
+            yield {
+                type: 'progress',
+                message: `Creating initial branch "${branchName}"...`
+            };
+            // Check if branch exists and find a unique name if needed
+            let branchExists = await this.gitManager.checkBranchExists(firstThreadPath, branchName);
+            let counter = 2;
+            const baseBranchName = branchName;
+            while (branchExists) {
+                branchName = `${baseBranchName}-${counter}`;
+                branchExists = await this.gitManager.checkBranchExists(firstThreadPath, 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(firstThreadPath, branchName)) {
+                if (gitEvent.type === 'error') {
+                    yield {
+                        type: 'error',
+                        message: `Failed to create initial 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 project metadata
+            const project = {
+                id: projectId,
+                name: projectName,
+                gitUrl,
+                path: projectPath,
+                createdAt: new Date(),
+                threads: [initialThreadId] // Add initial thread ID
+            };
+            // Create initial thread metadata
+            const initialThread = {
+                id: initialThreadId,
+                projectId,
+                title: initialThreadTitle,
+                path: firstThreadPath,
+                currentBranch: branchName,
+                createdAt: new Date()
+            };
+            // Save project and thread metadata
+            const projects = await this.metadataManager.loadProjects();
+            projects.push(project);
+            await this.metadataManager.saveProjects(projects);
+            const threads = await this.metadataManager.loadThreads();
+            threads.push(initialThread);
+            await this.metadataManager.saveThreads(threads);
+            yield {
+                type: 'progress',
+                message: `Project "${projectName}" created successfully with initial thread`
+            };
+            // Yield complete event with project data
+            yield {
+                type: 'complete',
+                message: 'Project creation complete',
+                project
+            };
+        }
+        catch (error) {
+            yield {
+                type: 'error',
+                message: `Failed to create project: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    /**
+     * Gets a project by ID
+     * @param projectId - The project ID
+     * @returns The project or null if not found
+     */
+    async getProject(projectId) {
+        const projects = await this.metadataManager.loadProjects();
+        return projects.find(p => p.id === projectId) || null;
+    }
+    /**
+     * Lists all projects
+     * @returns Array of all projects
+     */
+    async listProjects() {
+        return await this.metadataManager.loadProjects();
+    }
+    /**
+     * Deletes a project and all its threads (cascade delete)
+     *
+     * This method:
+     * 1. Finds the project by ID
+     * 2. Removes all associated threads from metadata
+     * 3. Removes the project directory from filesystem
+     * 4. Removes the project from metadata
+     *
+     * @param projectId - The project ID to delete
+     * @throws Error if project not found
+     *
+     * Requirements:
+     * - 1.1 - Cascade delete for projects (remove all threads)
+     */
+    async deleteProject(projectId) {
+        const projects = await this.metadataManager.loadProjects();
+        const projectIndex = projects.findIndex(p => p.id === projectId);
+        if (projectIndex === -1) {
+            throw new Error(`Project not found: ${projectId}`);
+        }
+        const project = projects[projectIndex];
+        // Load threads and remove all threads associated with this project
+        const threads = await this.metadataManager.loadThreads();
+        const remainingThreads = threads.filter(t => t.projectId !== projectId);
+        await this.metadataManager.saveThreads(remainingThreads);
+        // Remove project directory from filesystem
+        try {
+            const { rm } = await import('fs/promises');
+            await rm(project.path, { recursive: true, force: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to remove project directory: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Remove project from metadata
+        projects.splice(projectIndex, 1);
+        await this.metadataManager.saveProjects(projects);
+    }
+    /**
+     * Derives a project name from a git URL
+     *
+     * Examples:
+     * - https://github.com/user/repo.git -> repo
+     * - https://github.com/user/repo -> repo
+     * - git@github.com:user/repo.git -> repo
+     *
+     * @param gitUrl - The git URL
+     * @returns The derived project name
+     */
+    deriveProjectName(gitUrl) {
+        // Remove .git suffix if present
+        let name = gitUrl.replace(/\.git$/, '');
+        // Extract the last part of the path
+        const parts = name.split(/[/:]/).filter(p => p.length > 0);
+        name = parts[parts.length - 1] || 'project';
+        // Sanitize the name (remove special characters)
+        name = name.replace(/[^a-zA-Z0-9._-]/g, '-');
+        return name;
+    }
+    /**
+     * Generates a project path under the root folder
+     *
+     * @param projectName - The project name
+     * @returns The absolute path to the project folder
+     *
+     * Requirements:
+     * - 1.4 - THE CLI SHALL determine the storage path for each Project folder
+     */
+    generateProjectPath(projectName) {
+        return join(this.rootFolder, projectName);
+    }
+    /**
+     * Gets the root folder path
+     * @returns The root folder path
+     */
+    getRootFolder() {
+        return this.rootFolder;
+    }
+    /**
+     * Opens a project in the specified program
+     *
+     * @param projectId - The project ID
+     * @param program - The program to open the project in (VS Code, Cursor, Windsurf, Xcode, Android Studio, Kiro)
+     */
+    async openWith(projectId, program) {
+        const project = await this.getProject(projectId);
+        if (!project) {
+            throw new Error(`Project not found: ${projectId}`);
+        }
+        const { spawn } = await import('child_process');
+        const projectPath = project.path;
+        let command;
+        let args = [];
+        switch (program) {
+            case 'VS Code':
+                command = 'code';
+                args = [projectPath];
+                break;
+            case 'Cursor':
+                command = 'cursor';
+                args = [projectPath];
+                break;
+            case 'Windsurf':
+                command = 'windsurf';
+                args = [projectPath];
+                break;
+            case 'Xcode':
+                command = 'open';
+                args = [projectPath, '-a', 'Xcode'];
+                break;
+            case 'Android Studio':
+                command = 'open';
+                args = [projectPath, '-a', 'Android Studio'];
+                break;
+            case 'Kiro':
+                command = 'kiro';
+                args = [projectPath];
+                break;
+            default:
+                throw new Error(`Unsupported program: ${program}`);
+        }
+        return new Promise((resolve, reject) => {
+            const process = spawn(command, args, {
+                detached: true,
+                stdio: 'ignore'
+            });
+            process.on('error', (error) => {
+                reject(new Error(`Failed to open ${program}: ${error.message}`));
+            });
+            // Detach the child process so it doesn't block
+            process.unref();
+            // Resolve immediately as the IDE will open asynchronously
+            resolve();
+        });
+    }
+    /**
+     * Updates the project's open-with program preference
+     *
+     * @param projectId - The project ID
+     * @param program - The program name to set
+     */
+    async updateOpenWith(projectId, program) {
+        const projects = await this.metadataManager.loadProjects();
+        const projectIndex = projects.findIndex(p => p.id === projectId);
+        if (projectIndex === -1) {
+            throw new Error(`Project not found: ${projectId}`);
+        }
+        // Update the project's open-with program preference
+        projects[projectIndex].openWith = program;
+        // Save the updated projects back to metadata
+        await this.metadataManager.saveProjects(projects);
+    }
+    /**
+     * Saves (adds or updates) a command for a project
+     * @param projectId - The project ID
+     * @param command - The command to save
+     */
+    async saveCommand(projectId, command) {
+        const projects = await this.metadataManager.loadProjects();
+        const projectIndex = projects.findIndex(p => p.id === projectId);
+        if (projectIndex === -1) {
+            throw new Error(`Project not found: ${projectId}`);
+        }
+        const project = projects[projectIndex];
+        if (!project.commands) {
+            project.commands = [];
+        }
+        const commandIndex = project.commands.findIndex(c => c.id === command.id);
+        if (commandIndex !== -1) {
+            project.commands[commandIndex] = command;
+        }
+        else {
+            project.commands.push(command);
+        }
+        await this.metadataManager.saveProjects(projects);
+    }
+    /**
+     * Deletes a command from a project
+     * @param projectId - The project ID
+     * @param commandId - The ID of the command to delete
+     */
+    async deleteCommand(projectId, commandId) {
+        const projects = await this.metadataManager.loadProjects();
+        const projectIndex = projects.findIndex(p => p.id === projectId);
+        if (projectIndex === -1) {
+            throw new Error(`Project not found: ${projectId}`);
+        }
+        const project = projects[projectIndex];
+        if (project.commands) {
+            project.commands = project.commands.filter(c => c.id !== commandId);
+        }
+        await this.metadataManager.saveProjects(projects);
+    }
+    /**
+     * Runs a command in a thread's directory
+     * @param threadId - The thread ID where to run the command
+     * @param commandLine - The command line to execute
+     */
+    async *runCommand(threadId, commandLine, cwd) {
+        const threads = await this.metadataManager.loadThreads();
+        const thread = threads.find(t => t.id === threadId);
+        if (!thread) {
+            throw new Error(`Thread not found: ${threadId}`);
+        }
+        const { spawn } = await import('child_process');
+        const workingDir = cwd ? (cwd.startsWith('/') ? cwd : join(thread.path, cwd)) : thread.path;
+        // Use shell for complex command lines
+        // Append a command to output the final working directory
+        const child = spawn(`${commandLine}; printf "\\n___CWD___%s\\n" "$(pwd)"`, {
+            shell: true,
+            cwd: workingDir,
+        });
+        const decoder = new TextDecoder();
+        const outputBuffer = [];
+        let isDone = false;
+        child.stdout.on('data', (data) => {
+            const text = decoder.decode(data);
+            // Check if this chunk contains our CWD marker
+            if (text.includes("___CWD___")) {
+                const parts = text.split("___CWD___");
+                if (parts[0])
+                    outputBuffer.push(parts[0]);
+                const newCwd = parts[1].trim();
+                if (newCwd) {
+                    try {
+                        const realThreadPath = realpathSync(thread.path);
+                        const realNewCwd = realpathSync(newCwd);
+                        let relativeCwd = relative(realThreadPath, realNewCwd);
+                        if (!relativeCwd)
+                            relativeCwd = ".";
+                        outputBuffer.push({ type: 'cwd', path: relativeCwd });
+                    }
+                    catch {
+                        outputBuffer.push({ type: 'cwd', path: "." });
+                    }
+                }
+            }
+            else {
+                outputBuffer.push(text);
+            }
+        });
+        child.stderr.on('data', (data) => {
+            outputBuffer.push({ type: 'error', message: decoder.decode(data) });
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                outputBuffer.push({ type: 'error', message: `Process exited with code ${code}` });
+            }
+            isDone = true;
+        });
+        child.on('error', (err) => {
+            outputBuffer.push({ type: 'error', message: err.message });
+            isDone = true;
+        });
+        while (!isDone || outputBuffer.length > 0) {
+            if (outputBuffer.length > 0) {
+                yield outputBuffer.shift();
+            }
+            else {
+                await new Promise(resolve => setTimeout(resolve, 50));
+            }
+        }
+    }
+}
+//# sourceMappingURL=project-manager.js.map

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

@@ -0,0 +1,193 @@
+/**
+ * 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 { Thread, ThreadEvent } from '../types/models.js';
+import { MetadataManager } from './metadata-manager.js';
+import { GitManager } from './git-manager.js';
+/**
+ * ThreadManager interface defines the contract for thread operations
+ */
+export interface ThreadManager {
+    /**
+     * Creates a new thread for an existing project
+     * @param projectId - The parent project ID
+     * @param title - Optional thread title (auto-generated if not provided)
+     * @yields ThreadEvent objects during the creation process
+     */
+    createThread(projectId: string, title?: string): AsyncGenerator<ThreadEvent>;
+    /**
+     * Gets a thread by ID
+     * @param threadId - The thread ID
+     * @returns The thread or null if not found
+     */
+    getThread(threadId: string): Promise<Thread | null>;
+    /**
+     * Lists all threads for a specific project
+     * @param projectId - The project ID to filter threads
+     * @returns Array of threads for the project
+     */
+    listThreads(projectId: string): Promise<Thread[]>;
+    /**
+     * Deletes a thread and removes its directory
+     * @param threadId - The thread ID to delete
+     */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Updates a thread's metadata with partial data
+     * @param threadId - The thread ID to update
+     * @param updates - Partial thread data to merge
+     */
+    updateThread(threadId: string, updates: Partial<Omit<Thread, 'id'>>): Promise<void>;
+    /**
+     * Selects a thread as the active thread
+     * @param threadId - The thread ID to select
+     */
+    selectThread(threadId: string): Promise<void>;
+    /**
+     * Gets the currently selected thread ID
+     * @returns The selected thread ID or null
+     */
+    getSelectedThreadId(): Promise<string | null>;
+    /**
+     * Lists all files in a thread's directory (tracked and untracked, but not ignored)
+     * @param threadId - The thread ID
+     * @returns Array of file paths relative to the thread root
+     */
+    listFiles(threadId: string): Promise<string[]>;
+}
+/**
+ * ThreadManagerImpl provides the implementation for thread operations
+ */
+export declare class ThreadManagerImpl implements ThreadManager {
+    private metadataManager;
+    private 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: MetadataManager, 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
+     */
+    createThread(projectId: string, title?: string): AsyncGenerator<ThreadEvent>;
+    /**
+     * Gets a thread by ID
+     * @param threadId - The thread ID
+     * @returns The thread or null if not found
+     */
+    getThread(threadId: string): Promise<Thread | 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
+     */
+    listThreads(projectId: string): Promise<Thread[]>;
+    /**
+     * 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
+     */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * 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
+     */
+    updateThread(threadId: string, updates: Partial<Omit<Thread, 'id'>>): Promise<void>;
+    /**
+     * Selects a thread as the active thread
+     *
+     * @param threadId - The thread ID to select
+     */
+    selectThread(threadId: string): Promise<void>;
+    /**
+     * Gets the currently selected thread ID
+     *
+     * @returns The selected thread ID or null
+     */
+    getSelectedThreadId(): Promise<string | null>;
+    /**
+     * 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
+     */
+    private generateThreadPath;
+    /**
+     * 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
+     */
+    private generateThreadTitle;
+    /**
+     * Lists all files in a thread's directory (tracked and untracked, but not ignored)
+     * @param threadId - The thread ID
+     * @returns Array of file paths relative to the thread root
+     */
+    listFiles(threadId: string): Promise<string[]>;
+}
+//# sourceMappingURL=thread-manager.d.ts.map