tarsk 0.2.5 → 0.3.0

package/dist/managers/GitManager.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=GitManager.d.ts.map

package/dist/managers/GitManager.js

@@ -0,0 +1,330 @@
+/**
+ * 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 { spawn } from 'child_process';
+import { mkdir } from 'fs/promises';
+import { dirname } from 'path';
+/**
+ * GitManagerImpl provides the implementation for git operations
+ */
+export class GitManagerImpl {
+    /**
+     * Regular expressions for validating different git URL formats
+     */
+    gitUrlPatterns = [
+        // HTTPS URLs: https://github.com/user/repo.git or https://github.com/user/repo
+        /^https:\/\/[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(:[0-9]+)?\/[a-zA-Z0-9._/-]+(\.git)?$/,
+        // Git protocol URLs: git://github.com/user/repo.git or git://github.com/user/repo
+        /^git:\/\/[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(:[0-9]+)?\/[a-zA-Z0-9._/-]+(\.git)?$/,
+        // SSH URLs with git@ prefix: git@github.com:user/repo.git or git@github.com:user/repo
+        /^git@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}:[a-zA-Z0-9._/-]+(\.git)?$/,
+        // SSH URLs with ssh:// prefix: ssh://git@github.com/user/repo.git
+        /^ssh:\/\/(git@)?[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(:[0-9]+)?\/[a-zA-Z0-9._/-]+(\.git)?$/,
+    ];
+    /**
+     * 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) {
+        // Check if URL is empty or not a string
+        if (!url || typeof url !== 'string') {
+            return false;
+        }
+        // Trim whitespace
+        const trimmedUrl = url.trim();
+        // Check if URL is empty after trimming
+        if (trimmedUrl.length === 0) {
+            return false;
+        }
+        // Test against all supported patterns
+        return this.gitUrlPatterns.some(pattern => pattern.test(trimmedUrl));
+    }
+    /**
+     * 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
+     */
+    async *cloneRepository(gitUrl, targetPath) {
+        // Validate the git URL first
+        if (!this.validateGitUrl(gitUrl)) {
+            yield {
+                type: 'error',
+                message: `Invalid git URL format: ${gitUrl}`,
+                error: new Error(`Invalid git URL format: ${gitUrl}`)
+            };
+            return;
+        }
+        try {
+            // Create the parent directory if it doesn't exist
+            const parentDir = dirname(targetPath);
+            await mkdir(parentDir, { recursive: true });
+            // Spawn git clone process
+            // Use --progress to get progress output on stderr
+            const gitProcess = spawn('git', ['clone', '--progress', gitUrl, targetPath]);
+            // Create a queue for events
+            const eventQueue = [];
+            let processExited = false;
+            let exitCode = null;
+            let processError = null;
+            // Handle stdout data
+            gitProcess.stdout.on('data', (data) => {
+                const output = data.toString();
+                eventQueue.push({
+                    type: 'stdout',
+                    data: output
+                });
+            });
+            // Handle stderr data (git clone progress goes to stderr)
+            gitProcess.stderr.on('data', (data) => {
+                const output = data.toString();
+                eventQueue.push({
+                    type: 'stderr',
+                    data: output
+                });
+            });
+            // Handle process exit
+            gitProcess.on('close', (code) => {
+                exitCode = code;
+                processExited = true;
+            });
+            // Handle process errors
+            gitProcess.on('error', (err) => {
+                processError = err;
+                processExited = true;
+            });
+            // Yield events as they come in
+            while (!processExited || eventQueue.length > 0) {
+                if (eventQueue.length > 0) {
+                    const event = eventQueue.shift();
+                    if (event) {
+                        yield event;
+                    }
+                }
+                else {
+                    // Wait a bit before checking again
+                    await new Promise(resolve => setTimeout(resolve, 10));
+                }
+            }
+            // Check for process errors
+            if (processError) {
+                const errorMessage = processError instanceof Error
+                    ? processError.message
+                    : String(processError);
+                yield {
+                    type: 'error',
+                    message: errorMessage,
+                    error: processError
+                };
+                return;
+            }
+            // Check exit code
+            if (exitCode !== 0) {
+                const errorMsg = `Git clone failed with exit code ${exitCode}`;
+                yield {
+                    type: 'error',
+                    message: errorMsg,
+                    error: new Error(errorMsg)
+                };
+                return;
+            }
+            // Yield complete event
+            yield {
+                type: 'complete'
+            };
+        }
+        catch (error) {
+            // Handle any errors during the process
+            yield {
+                type: 'error',
+                message: error instanceof Error ? error.message : String(error),
+                error: error instanceof Error ? error : new Error(String(error))
+            };
+        }
+    }
+    /**
+     * 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) {
+        if (!name || typeof name !== 'string') {
+            return 'branch';
+        }
+        return name
+            .trim()
+            // Convert to lowercase
+            .toLowerCase()
+            // Replace spaces with dashes
+            .replace(/\s+/g, '-')
+            // Remove invalid characters (keep alphanumeric, dash, underscore, slash, dot)
+            .replace(/[^a-zA-Z0-9\-_/.]/g, '')
+            // Remove leading/trailing slashes and dots
+            .replace(/^[/.]+|[/.]+$/g, '')
+            // Collapse multiple consecutive dashes
+            .replace(/-+/g, '-')
+            // Ensure we have something left
+            || 'branch';
+    }
+    /**
+     * 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
+     */
+    async checkBranchExists(repoPath, branchName) {
+        return new Promise((resolve) => {
+            const gitProcess = spawn('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branchName}`], {
+                cwd: repoPath
+            });
+            gitProcess.on('close', (code) => {
+                // Exit code 0 means the branch exists
+                resolve(code === 0);
+            });
+            gitProcess.on('error', () => {
+                // If there's an error running git, assume branch doesn't exist
+                resolve(false);
+            });
+        });
+    }
+    /**
+     * 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
+     */
+    async *createAndCheckoutBranch(repoPath, branchName) {
+        try {
+            // Spawn git checkout process with -b flag to create new branch
+            const gitProcess = spawn('git', ['checkout', '-b', branchName], {
+                cwd: repoPath
+            });
+            // Create a queue for events
+            const eventQueue = [];
+            let processExited = false;
+            let exitCode = null;
+            let processError = null;
+            // Handle stdout data
+            gitProcess.stdout.on('data', (data) => {
+                const output = data.toString();
+                eventQueue.push({
+                    type: 'stdout',
+                    data: output
+                });
+            });
+            // Handle stderr data
+            gitProcess.stderr.on('data', (data) => {
+                const output = data.toString();
+                eventQueue.push({
+                    type: 'stderr',
+                    data: output
+                });
+            });
+            // Handle process exit
+            gitProcess.on('close', (code) => {
+                exitCode = code;
+                processExited = true;
+            });
+            // Handle process errors
+            gitProcess.on('error', (err) => {
+                processError = err;
+                processExited = true;
+            });
+            // Yield events as they come in
+            while (!processExited || eventQueue.length > 0) {
+                if (eventQueue.length > 0) {
+                    const event = eventQueue.shift();
+                    if (event) {
+                        yield event;
+                    }
+                }
+                else {
+                    // Wait a bit before checking again
+                    await new Promise(resolve => setTimeout(resolve, 10));
+                }
+            }
+            // Check for process errors
+            if (processError) {
+                const errorMessage = processError instanceof Error
+                    ? processError.message
+                    : String(processError);
+                yield {
+                    type: 'error',
+                    message: errorMessage,
+                    error: processError
+                };
+                return;
+            }
+            // Check exit code
+            if (exitCode !== 0) {
+                const errorMsg = `Failed to create and checkout branch '${branchName}' with exit code ${exitCode}`;
+                yield {
+                    type: 'error',
+                    message: errorMsg,
+                    error: new Error(errorMsg)
+                };
+                return;
+            }
+            // Yield complete event
+            yield {
+                type: 'complete'
+            };
+        }
+        catch (error) {
+            yield {
+                type: 'error',
+                message: error instanceof Error ? error.message : String(error),
+                error: error instanceof Error ? error : new Error(String(error))
+            };
+        }
+    }
+}
+//# sourceMappingURL=GitManager.js.map

package/dist/managers/MetadataManager.d.ts

@@ -0,0 +1,139 @@
+/**
+ * MetadataManager handles persistence of project and thread metadata
+ *
+ * This manager provides JSON file-based storage with atomic writes
+ * to ensure data consistency even if the process crashes during write operations.
+ */
+import { Project, Thread } from '../types/models.js';
+/**
+ * MetadataManager manages persistence of projects and threads
+ */
+interface AppState {
+    selectedThreadId: string | null;
+    providerKeys: Record<string, string>;
+    enabledModels: Record<string, string[]>;
+}
+export declare class MetadataManager {
+    private projectsFile;
+    private threadsFile;
+    private stateFile;
+    private metadataDir;
+    /**
+     * Create a new MetadataManager
+     * @param rootFolder - Base directory where metadata will be stored
+     */
+    constructor(rootFolder: string);
+    /**
+     * Initialize metadata directory if it doesn't exist
+     */
+    initialize(): Promise<void>;
+    /**
+     * Save projects to disk using atomic write
+     * @param projects - Array of projects to save
+     */
+    saveProjects(projects: Project[]): Promise<void>;
+    /**
+     * Load projects from disk
+     * @returns Array of projects
+     */
+    loadProjects(): Promise<Project[]>;
+    /**
+     * Save threads to disk using atomic write
+     * @param threads - Array of threads to save
+     */
+    saveThreads(threads: Thread[]): Promise<void>;
+    /**
+     * Load threads from disk
+     * @returns Array of threads
+     */
+    loadThreads(): Promise<Thread[]>;
+    /**
+     * Perform atomic write using temp file
+     *
+     * This ensures that if the process crashes during write,
+     * we don't end up with corrupted or partial data.
+     *
+     * @param filePath - Target file path
+     * @param data - Data to write
+     */
+    private atomicWrite;
+    /**
+     * Get the metadata directory path
+     */
+    getMetadataDir(): string;
+    /**
+     * Get the projects file path
+     */
+    getProjectsFile(): string;
+    /**
+     * Get the threads file path
+     */
+    getThreadsFile(): string;
+    /**
+     * Save application state to disk
+     * @param state - Application state to save
+     */
+    saveState(state: AppState): Promise<void>;
+    /**
+     * Load application state from disk
+     * @returns Application state
+     */
+    loadState(): Promise<AppState>;
+    /**
+     * Update all provider keys at once
+     * @param keys - Object mapping provider names to API keys
+     */
+    saveAllProviderKeys(keys: Record<string, string>): Promise<void>;
+    /**
+     * Update provider keys
+     * @param providerName - Name of the provider
+     * @param apiKey - API key to save
+     */
+    saveProviderKey(providerName: string, apiKey: string): Promise<void>;
+    /**
+     * Get all provider keys
+     * @returns Record of provider names to API keys
+     */
+    getProviderKeys(): Promise<Record<string, string>>;
+    /**
+     * Set the selected thread ID
+     * @param threadId - Thread ID to select (or null to deselect)
+     */
+    setSelectedThread(threadId: string | null): Promise<void>;
+    /**
+     * Get the selected thread ID
+     * @returns The selected thread ID or null
+     */
+    getSelectedThread(): Promise<string | null>;
+    /**
+     * Enable a model for a provider
+     * @param provider - Provider name
+     * @param modelId - Model ID to enable
+     */
+    enableModel(provider: string, modelId: string): Promise<void>;
+    /**
+     * Disable a model for a provider
+     * @param provider - Provider name
+     * @param modelId - Model ID to disable
+     */
+    disableModel(provider: string, modelId: string): Promise<void>;
+    /**
+     * Get enabled models for a provider
+     * @param provider - Provider name
+     * @returns Array of enabled model IDs
+     */
+    getEnabledModels(provider: string): Promise<string[]>;
+    /**
+     * Get all enabled models across all providers
+     * @returns Object mapping provider to array of model IDs
+     */
+    getAllEnabledModels(): Promise<Record<string, string[]>>;
+    /**
+     * Set enabled models for a provider
+     * @param provider - Provider name
+     * @param modelIds - Array of model IDs to enable
+     */
+    setEnabledModels(provider: string, modelIds: string[]): Promise<void>;
+}
+export {};
+//# sourceMappingURL=MetadataManager.d.ts.map