@claudetools/tools 0.1.0

package/dist/helpers/project-registration.js

@@ -0,0 +1,338 @@
+// =============================================================================
+// Auto Project Registration System
+// =============================================================================
+// Automatically registers projects with the ClaudeTools API when used in
+// unregistered directories. Caches project bindings locally for fast lookups.
+// =============================================================================
+import { mcpLogger } from '../logger.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execSync } from 'child_process';
+import { API_BASE_URL, PROJECTS_FILE, CLAUDETOOLS_DIR } from './config.js';
+import { getConfig } from './config-manager.js';
+// -----------------------------------------------------------------------------
+// System Registration
+// -----------------------------------------------------------------------------
+/**
+ * Get unique system identifier (hostname)
+ */
+function getSystemInfo() {
+    return {
+        hostname: os.hostname(),
+        platform: os.platform(),
+        username: os.userInfo().username,
+    };
+}
+/**
+ * Get or register this machine as a system
+ * Returns system_id for binding projects
+ */
+async function ensureSystemRegistered() {
+    const cache = loadProjectsCache();
+    // Check if we already have a system_id cached
+    if (cache.system_id) {
+        mcpLogger.debug('REGISTRATION', `Using cached system ID: ${cache.system_id}`);
+        return cache.system_id;
+    }
+    // Register this system
+    const systemInfo = getSystemInfo();
+    mcpLogger.info('REGISTRATION', `Registering new system: ${systemInfo.hostname}`);
+    try {
+        const config = getConfig();
+        const apiKey = config.apiKey || process.env.MEMORY_API_KEY || process.env.CLAUDETOOLS_API_KEY;
+        if (!apiKey) {
+            throw new Error('No API key found. Set CLAUDETOOLS_API_KEY or MEMORY_API_KEY in environment, ' +
+                'or configure via ~/.claudetools/config.json');
+        }
+        const response = await fetch(`${API_BASE_URL}/api/v1/systems/register`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                hostname: systemInfo.hostname,
+                platform: systemInfo.platform,
+                username: systemInfo.username,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`System registration failed: ${response.status} ${error}`);
+        }
+        const result = await response.json();
+        const systemId = result.data?.system_id || result.system_id;
+        if (!systemId) {
+            throw new Error('System registration did not return a system_id');
+        }
+        mcpLogger.info('REGISTRATION', `System registered successfully: ${systemId}`);
+        // Cache the system_id
+        cache.system_id = systemId;
+        saveProjectsCache(cache);
+        return systemId;
+    }
+    catch (error) {
+        mcpLogger.error('REGISTRATION', `System registration failed: ${error}`);
+        throw new Error(`Failed to register system: ${error}`);
+    }
+}
+// -----------------------------------------------------------------------------
+// Git Detection
+// -----------------------------------------------------------------------------
+/**
+ * Try to detect git remote for a directory
+ */
+function detectGitRemote(localPath) {
+    try {
+        const gitRemote = execSync('git config --get remote.origin.url', {
+            cwd: localPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        }).trim();
+        return gitRemote || undefined;
+    }
+    catch {
+        // Not a git repo or no remote configured
+        return undefined;
+    }
+}
+// -----------------------------------------------------------------------------
+// Project Registration
+// -----------------------------------------------------------------------------
+/**
+ * Register a new project via API
+ */
+async function registerProject(localPath) {
+    const systemId = await ensureSystemRegistered();
+    const projectName = path.basename(localPath);
+    const gitRemote = detectGitRemote(localPath);
+    mcpLogger.info('REGISTRATION', `Registering new project: ${projectName} at ${localPath}`);
+    try {
+        const config = getConfig();
+        const apiKey = config.apiKey || process.env.MEMORY_API_KEY || process.env.CLAUDETOOLS_API_KEY;
+        if (!apiKey) {
+            throw new Error('No API key found. Set CLAUDETOOLS_API_KEY or MEMORY_API_KEY in environment, ' +
+                'or configure via ~/.claudetools/config.json');
+        }
+        // Step 1: Create project
+        const projectResponse = await fetch(`${API_BASE_URL}/api/v1/projects`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                name: projectName,
+                description: `Auto-registered project from ${localPath}`,
+                git_remote: gitRemote,
+            }),
+        });
+        if (!projectResponse.ok) {
+            const error = await projectResponse.text();
+            throw new Error(`Project creation failed: ${projectResponse.status} ${error}`);
+        }
+        const projectResult = await projectResponse.json();
+        const projectId = projectResult.data?.project_id || projectResult.project_id;
+        const orgId = projectResult.data?.org_id || projectResult.org_id || 'default';
+        if (!projectId) {
+            throw new Error('Project creation did not return a project_id');
+        }
+        mcpLogger.info('REGISTRATION', `Project created: ${projectId}`);
+        // Step 2: Create binding (link project to local path on this system)
+        const bindingResponse = await fetch(`${API_BASE_URL}/api/v1/systems/${systemId}/bindings`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                project_id: projectId,
+                local_path: localPath,
+                git_remote: gitRemote,
+            }),
+        });
+        if (!bindingResponse.ok) {
+            const error = await bindingResponse.text();
+            throw new Error(`Binding creation failed: ${bindingResponse.status} ${error}`);
+        }
+        const bindingResult = await bindingResponse.json();
+        const bindingId = bindingResult.data?.binding_id || bindingResult.binding_id;
+        if (!bindingId) {
+            throw new Error('Binding creation did not return a binding_id');
+        }
+        mcpLogger.info('REGISTRATION', `Binding created: ${bindingId}`);
+        const binding = {
+            binding_id: bindingId,
+            project_id: projectId,
+            system_id: systemId,
+            local_path: localPath,
+            git_remote: gitRemote,
+            project_name: projectName,
+            org_id: orgId,
+            cached_at: new Date().toISOString(),
+        };
+        // Update local cache
+        updateProjectsCache(binding);
+        mcpLogger.info('REGISTRATION', `Successfully registered project: ${projectName} → ${projectId}`);
+        // Also cache the system_id at top level for future use
+        const cache = loadProjectsCache();
+        if (!cache.system_id) {
+            cache.system_id = systemId;
+            saveProjectsCache(cache);
+        }
+        return binding;
+    }
+    catch (error) {
+        mcpLogger.error('REGISTRATION', `Project registration failed: ${error}`);
+        throw new Error(`Failed to register project: ${error}`);
+    }
+}
+// -----------------------------------------------------------------------------
+// Cache Management
+// -----------------------------------------------------------------------------
+/**
+ * Load projects cache from disk
+ */
+function loadProjectsCache() {
+    try {
+        // Ensure directory exists
+        if (!fs.existsSync(CLAUDETOOLS_DIR)) {
+            fs.mkdirSync(CLAUDETOOLS_DIR, { recursive: true });
+        }
+        if (fs.existsSync(PROJECTS_FILE)) {
+            const content = fs.readFileSync(PROJECTS_FILE, 'utf-8');
+            const cache = JSON.parse(content);
+            // Ensure bindings array exists
+            if (!cache.bindings) {
+                cache.bindings = [];
+            }
+            return cache;
+        }
+    }
+    catch (error) {
+        mcpLogger.error('REGISTRATION', `Error loading projects cache: ${error}`);
+    }
+    // Return empty cache
+    return {
+        bindings: [],
+        last_sync: new Date().toISOString(),
+    };
+}
+/**
+ * Save projects cache to disk
+ */
+function saveProjectsCache(cache) {
+    try {
+        // Ensure directory exists
+        if (!fs.existsSync(CLAUDETOOLS_DIR)) {
+            fs.mkdirSync(CLAUDETOOLS_DIR, { recursive: true });
+        }
+        cache.last_sync = new Date().toISOString();
+        const content = JSON.stringify(cache, null, 2);
+        fs.writeFileSync(PROJECTS_FILE, content, 'utf-8');
+        mcpLogger.debug('REGISTRATION', `Projects cache saved to ${PROJECTS_FILE}`);
+    }
+    catch (error) {
+        mcpLogger.error('REGISTRATION', `Error saving projects cache: ${error}`);
+        throw error;
+    }
+}
+/**
+ * Update local cache with new binding
+ */
+function updateProjectsCache(binding) {
+    const cache = loadProjectsCache();
+    // Remove any existing binding for this path
+    cache.bindings = cache.bindings.filter(b => b.local_path !== binding.local_path);
+    // Add new binding
+    cache.bindings.push(binding);
+    saveProjectsCache(cache);
+}
+// -----------------------------------------------------------------------------
+// Main Entry Point
+// -----------------------------------------------------------------------------
+/**
+ * Get or register project for a local path
+ * This is the main function called by config.ts
+ *
+ * Returns the project_id (UUID) for the given path
+ */
+export async function getOrRegisterProject(localPath) {
+    const config = getConfig();
+    // Check if auto-registration is disabled
+    if (!config.autoRegister) {
+        throw new Error(`No project binding found for ${localPath} and auto-registration is disabled. ` +
+            'Enable auto-registration in ~/.claudetools/config.json or manually register this project.');
+    }
+    mcpLogger.debug('REGISTRATION', `Looking up project for: ${localPath}`);
+    // Load cache and check for existing binding
+    const cache = loadProjectsCache();
+    // Try exact match first
+    const exactMatch = cache.bindings.find(b => b.local_path === localPath);
+    if (exactMatch) {
+        mcpLogger.debug('REGISTRATION', `Found exact match: ${exactMatch.project_id}`);
+        return exactMatch.project_id;
+    }
+    // Try prefix match (for subdirectories)
+    const prefixMatches = cache.bindings
+        .filter(b => localPath.startsWith(b.local_path + '/') || localPath === b.local_path)
+        .sort((a, b) => b.local_path.length - a.local_path.length);
+    if (prefixMatches.length > 0) {
+        mcpLogger.debug('REGISTRATION', `Found prefix match: ${prefixMatches[0].project_id}`);
+        return prefixMatches[0].project_id;
+    }
+    // No match found - register new project
+    mcpLogger.info('REGISTRATION', `No binding found for ${localPath}, registering...`);
+    try {
+        const binding = await registerProject(localPath);
+        return binding.project_id;
+    }
+    catch (error) {
+        mcpLogger.error('REGISTRATION', `Auto-registration failed: ${error}`);
+        throw new Error(`Failed to auto-register project for ${localPath}: ${error}\n\n` +
+            'Please check:\n' +
+            '1. API key is configured (CLAUDETOOLS_API_KEY or MEMORY_API_KEY)\n' +
+            '2. API URL is correct in ~/.claudetools/config.json\n' +
+            '3. Network connectivity to ClaudeTools API\n\n' +
+            'You can disable auto-registration by setting autoRegister: false in config.');
+    }
+}
+/**
+ * Sync projects from API (for future use)
+ * This would fetch all bindings from the API and update local cache
+ */
+export async function syncProjectsFromAPI() {
+    const systemId = await ensureSystemRegistered();
+    mcpLogger.info('REGISTRATION', 'Syncing projects from API...');
+    try {
+        const config = getConfig();
+        const apiKey = config.apiKey || process.env.MEMORY_API_KEY || process.env.CLAUDETOOLS_API_KEY;
+        if (!apiKey) {
+            throw new Error('No API key found for sync operation');
+        }
+        const response = await fetch(`${API_BASE_URL}/api/v1/systems/${systemId}/bindings`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch bindings: ${response.status}`);
+        }
+        const result = await response.json();
+        const bindings = result.data?.bindings || result.bindings || [];
+        // Update cache
+        const cache = loadProjectsCache();
+        cache.bindings = bindings.map((b) => ({
+            ...b,
+            cached_at: new Date().toISOString(),
+        }));
+        saveProjectsCache(cache);
+        mcpLogger.info('REGISTRATION', `Synced ${bindings.length} project bindings from API`);
+    }
+    catch (error) {
+        mcpLogger.error('REGISTRATION', `Sync failed: ${error}`);
+        throw error;
+    }
+}

package/dist/helpers/tasks.d.ts

@@ -0,0 +1,152 @@
+import type { ExpertWorker } from './workers.js';
+export interface Task {
+    id: string;
+    type: 'epic' | 'task' | 'subtask';
+    parent_id: string | null;
+    user_id: string;
+    project_id: string;
+    title: string;
+    description: string;
+    acceptance_criteria: string | string[];
+    status: string;
+    priority: string;
+    blocked_by: string | string[];
+    agent_type: string | null;
+    domain: string | null;
+    assigned_to: string | null;
+    locked_at: string | null;
+    lock_expires_at: string | null;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+    estimated_effort: string | null;
+    tags: string | string[];
+    metadata: Record<string, unknown>;
+}
+export interface TaskContext {
+    id: string;
+    task_id: string;
+    context_type: string;
+    content: string;
+    source: string | null;
+    added_by: string;
+    created_at: string;
+}
+export interface DispatchableTask {
+    task: Task;
+    worker: ExpertWorker;
+    context: TaskContext[];
+    parentContext?: Task;
+    dependencies?: Task[];
+}
+export declare function parseJsonArray(value: string | string[] | null | undefined): string[];
+export declare function createTask(userId: string, projectId: string, taskData: {
+    type: 'epic' | 'task' | 'subtask';
+    title: string;
+    description?: string;
+    parent_id?: string;
+    priority?: string;
+    acceptance_criteria?: string[];
+    blocked_by?: string[];
+    estimated_effort?: string;
+    tags?: string[];
+    agent_type?: string;
+    domain?: string;
+}): Promise<{
+    success: boolean;
+    data: Task;
+}>;
+export declare function listTasks(userId: string, projectId: string, filters?: {
+    type?: string;
+    status?: string;
+    parent_id?: string;
+    assigned_to?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    success: boolean;
+    data: Task[];
+    meta: {
+        limit: number;
+        offset: number;
+        count: number;
+    };
+}>;
+export declare function getTask(userId: string, projectId: string, taskId: string, full?: boolean): Promise<{
+    success: boolean;
+    data: Task | {
+        task: Task;
+        context: TaskContext[];
+        subtasks: Task[];
+        parent?: Task;
+    };
+}>;
+export declare function claimTask(userId: string, projectId: string, taskId: string, agentId: string, lockDurationMinutes?: number): Promise<{
+    success: boolean;
+    data: {
+        claimed: boolean;
+        lock_expires_at: string;
+        task: Task;
+        context: TaskContext[];
+    };
+}>;
+export declare function releaseTask(userId: string, projectId: string, taskId: string, agentId: string, newStatus?: string, workLog?: string): Promise<{
+    success: boolean;
+    data: {
+        released: boolean;
+        task: Task;
+    };
+}>;
+export declare function updateTaskStatus(userId: string, projectId: string, taskId: string, status: string, agentId?: string): Promise<{
+    success: boolean;
+    data: Task;
+}>;
+export declare function addTaskContext(userId: string, projectId: string, taskId: string, contextType: string, content: string, addedBy: string, source?: string): Promise<{
+    success: boolean;
+    data: TaskContext;
+}>;
+export declare function getTaskSummary(userId: string, projectId: string): Promise<{
+    success: boolean;
+    data: {
+        by_status: Record<string, number>;
+        by_type: Record<string, number>;
+        active_agents: number;
+        recent_events: {
+            id: string;
+            task_id: string;
+            event_type: string;
+            task_title: string;
+            created_at: string;
+        }[];
+    };
+}>;
+export declare function heartbeatTask(userId: string, projectId: string, taskId: string, agentId: string, extendMinutes?: number): Promise<{
+    success: boolean;
+    data: {
+        extended: boolean;
+        new_expires_at: string;
+    };
+}>;
+/**
+ * Get all tasks ready for parallel dispatch
+ * - Filters for 'ready' status
+ * - Excludes already claimed tasks
+ * - Resolves dependencies (only returns unblocked tasks)
+ * - Matches each to appropriate expert worker
+ */
+export declare function getDispatchableTasks(userId: string, projectId: string, epicId?: string, maxParallel?: number): Promise<DispatchableTask[]>;
+/**
+ * Get full execution context for a worker agent
+ */
+export declare function getExecutionContext(userId: string, projectId: string, taskId: string): Promise<{
+    task: Task;
+    worker: ExpertWorker;
+    systemPrompt: string;
+    context: TaskContext[];
+    parentTask?: Task;
+    siblingTasks?: Task[];
+}>;
+/**
+ * Find newly unblocked tasks after a completion
+ */
+export declare function resolveTaskDependencies(userId: string, projectId: string, completedTaskId: string, epicId?: string): Promise<Task[]>;