@claudetools/tools 0.1.0

package/dist/helpers/api-client.d.ts

@@ -0,0 +1,50 @@
+export interface MemoryContext {
+    relevant_facts: {
+        fact: string;
+        source_name?: string;
+        target_name?: string;
+        relation_type: string;
+        created_at: string;
+    }[];
+    relevant_entities: {
+        name: string;
+        labels: string[];
+        summary?: string;
+    }[];
+    metadata: {
+        query: string;
+        retrieval_time_ms: number;
+        total_facts: number;
+    };
+}
+export declare function apiRequest<T>(endpoint: string, method?: 'GET' | 'POST', body?: unknown): Promise<T>;
+export declare function addMemory(projectId: string, sessionId: string, messages: {
+    role: string;
+    content: string;
+}[], extractFacts?: boolean): Promise<{
+    success: boolean;
+    episode_ids: string[];
+}>;
+export declare function searchMemory(projectId: string, query: string, limit?: number): Promise<MemoryContext>;
+export declare function storeFact(projectId: string, entity1: string, relationship: string, entity2: string, context: string): Promise<{
+    success: boolean;
+    fact_id: string;
+}>;
+export declare function getContext(projectId: string, query?: string): Promise<MemoryContext>;
+export declare function getSummary(projectId: string): Promise<string>;
+export declare function getEntities(projectId: string): Promise<{
+    name: string;
+    labels: string[];
+    entity_id: string;
+}[]>;
+export declare function injectContext(projectId: string, query: string, userId?: string): Promise<{
+    augmentedSystemPrompt: string;
+    metadata: {
+        memoryNeeded: boolean;
+        retrievalTimeMs: number;
+        factsScored: number;
+        factsIncluded: number;
+        avgRelevanceScore: number;
+        reason?: string;
+    };
+}>;

package/dist/helpers/api-client.js

@@ -0,0 +1,60 @@
+// =============================================================================
+// API Client and Memory Operations
+// =============================================================================
+import { API_BASE_URL, DEFAULT_USER_ID } from './config.js';
+export async function apiRequest(endpoint, method = 'GET', body) {
+    const url = `${API_BASE_URL}${endpoint}`;
+    const options = {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+        },
+    };
+    if (body) {
+        options.body = JSON.stringify(body);
+    }
+    const response = await fetch(url, options);
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+export async function addMemory(projectId, sessionId, messages, extractFacts = true) {
+    return apiRequest(`/api/v1/memory/${projectId}/add`, 'POST', {
+        session_id: sessionId,
+        messages,
+        extract_facts: extractFacts,
+    });
+}
+export async function searchMemory(projectId, query, limit = 10) {
+    return apiRequest(`/api/v1/memory/${projectId}/search`, 'POST', {
+        query,
+        limit,
+    });
+}
+export async function storeFact(projectId, entity1, relationship, entity2, context) {
+    return apiRequest(`/api/v1/memory/${projectId}/fact`, 'POST', {
+        entity1,
+        relationship,
+        entity2,
+        context,
+    });
+}
+export async function getContext(projectId, query) {
+    const params = query ? `?query=${encodeURIComponent(query)}` : '';
+    return apiRequest(`/api/v1/memory/${projectId}/context${params}`);
+}
+export async function getSummary(projectId) {
+    const response = await fetch(`${API_BASE_URL}/api/v1/memory/${projectId}/summary`);
+    return response.text();
+}
+export async function getEntities(projectId) {
+    return apiRequest(`/api/v1/memory/${projectId}/entities`);
+}
+export async function injectContext(projectId, query, userId) {
+    const response = await apiRequest(`/api/v1/memory/${projectId}/inject`, 'POST', {
+        query,
+        userId: userId || DEFAULT_USER_ID,
+    });
+    return response.data;
+}

package/dist/helpers/config-manager.d.ts

@@ -0,0 +1,68 @@
+export interface ClaudeToolsConfig {
+    apiUrl: string;
+    apiKey?: string;
+    autoRegister: boolean;
+    defaultProjectId?: string;
+    defaultUserId?: string;
+    autoInjectContext: boolean;
+    contextRelevanceThreshold: number;
+    maxContextFacts: number;
+    verbosity: 'quiet' | 'normal' | 'verbose' | 'debug';
+    logToFile: boolean;
+    logFilePath?: string;
+    watchedDirectories: string[];
+    cacheTimeout: number;
+    maxRetries: number;
+    requestTimeout: number;
+}
+export declare const DEFAULT_CONFIG: ClaudeToolsConfig;
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export declare function getProjectsPath(): string;
+/**
+ * Ensures the ~/.claudetools directory exists
+ */
+export declare function ensureConfigDir(): Promise<void>;
+/**
+ * Synchronous version for initialization
+ */
+export declare function ensureConfigDirSync(): void;
+/**
+ * Loads configuration from ~/.claudetools/config.json
+ * Creates default configuration if file doesn't exist
+ */
+export declare function loadConfigFromFile(): Promise<Partial<ClaudeToolsConfig>>;
+/**
+ * Synchronous version for startup initialization
+ */
+export declare function loadConfigFromFileSync(): Partial<ClaudeToolsConfig>;
+/**
+ * Saves configuration to ~/.claudetools/config.json
+ */
+export declare function saveConfig(config: ClaudeToolsConfig): Promise<void>;
+/**
+ * Synchronous version for startup initialization
+ */
+export declare function saveConfigSync(config: ClaudeToolsConfig): void;
+/**
+ * Returns the complete configuration with environment overrides
+ * Priority: Environment Variables > Config File > Defaults
+ */
+export declare function getConfig(): ClaudeToolsConfig;
+/**
+ * Resets the cached configuration (useful for testing or runtime updates)
+ */
+export declare function resetConfigCache(): void;
+/**
+ * Updates a specific configuration value and saves to file
+ */
+export declare function updateConfig(updates: Partial<ClaudeToolsConfig>): Promise<ClaudeToolsConfig>;
+/**
+ * Resets configuration to defaults
+ */
+export declare function resetConfig(): Promise<ClaudeToolsConfig>;
+/**
+ * Initialize configuration on module load
+ * This ensures config file exists and is loaded early
+ */
+export declare function initializeConfig(): ClaudeToolsConfig;

package/dist/helpers/config-manager.js

@@ -0,0 +1,306 @@
+// =============================================================================
+// ClaudeTools Configuration Manager
+// =============================================================================
+// Unified configuration system with file-based config and environment overrides
+// Creates ~/.claudetools/config.json with sensible defaults on first run
+// =============================================================================
+import { mcpLogger } from '../logger.js';
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// -----------------------------------------------------------------------------
+// Default Configuration
+// -----------------------------------------------------------------------------
+export const DEFAULT_CONFIG = {
+    // API Configuration
+    apiUrl: 'https://api.claudetools.dev',
+    apiKey: undefined,
+    // Project Management
+    autoRegister: true,
+    defaultProjectId: undefined,
+    defaultUserId: 'default',
+    // Context Injection
+    autoInjectContext: false, // Disabled by default for backward compatibility
+    contextRelevanceThreshold: 0.5,
+    maxContextFacts: 10,
+    // Logging & Verbosity
+    verbosity: 'normal',
+    logToFile: false,
+    logFilePath: undefined,
+    // Watched Directories
+    watchedDirectories: [],
+    // Performance
+    cacheTimeout: 300, // 5 minutes
+    maxRetries: 3,
+    requestTimeout: 30, // 30 seconds
+};
+// -----------------------------------------------------------------------------
+// Environment Variable Mapping
+// -----------------------------------------------------------------------------
+const ENV_VAR_MAP = {
+    CLAUDETOOLS_API_URL: 'apiUrl',
+    CLAUDETOOLS_API_KEY: 'apiKey',
+    CLAUDETOOLS_AUTO_REGISTER: 'autoRegister',
+    CLAUDETOOLS_PROJECT_ID: 'defaultProjectId',
+    CLAUDETOOLS_USER_ID: 'defaultUserId',
+    AUTO_INJECT_CONTEXT: 'autoInjectContext',
+    CLAUDETOOLS_VERBOSITY: 'verbosity',
+    CLAUDETOOLS_LOG_TO_FILE: 'logToFile',
+    CLAUDETOOLS_LOG_FILE_PATH: 'logFilePath',
+    CLAUDETOOLS_CACHE_TIMEOUT: 'cacheTimeout',
+    CLAUDETOOLS_MAX_RETRIES: 'maxRetries',
+    CLAUDETOOLS_REQUEST_TIMEOUT: 'requestTimeout',
+};
+// -----------------------------------------------------------------------------
+// Path Helpers
+// -----------------------------------------------------------------------------
+export function getConfigDir() {
+    return path.join(os.homedir(), '.claudetools');
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), 'config.json');
+}
+export function getProjectsPath() {
+    return path.join(getConfigDir(), 'projects.json');
+}
+// -----------------------------------------------------------------------------
+// Directory Management
+// -----------------------------------------------------------------------------
+/**
+ * Ensures the ~/.claudetools directory exists
+ */
+export async function ensureConfigDir() {
+    const configDir = getConfigDir();
+    try {
+        await fs.access(configDir);
+    }
+    catch {
+        mcpLogger.debug('CONFIG', `Creating config directory: ${configDir}`);
+        await fs.mkdir(configDir, { recursive: true });
+    }
+}
+/**
+ * Synchronous version for initialization
+ */
+export function ensureConfigDirSync() {
+    const configDir = getConfigDir();
+    if (!fsSync.existsSync(configDir)) {
+        mcpLogger.debug('CONFIG', `Creating config directory: ${configDir}`);
+        fsSync.mkdirSync(configDir, { recursive: true });
+    }
+}
+// -----------------------------------------------------------------------------
+// Configuration File Operations
+// -----------------------------------------------------------------------------
+/**
+ * Loads configuration from ~/.claudetools/config.json
+ * Creates default configuration if file doesn't exist
+ */
+export async function loadConfigFromFile() {
+    const configPath = getConfigPath();
+    try {
+        await ensureConfigDir();
+        // Check if config file exists
+        try {
+            await fs.access(configPath);
+        }
+        catch {
+            // Config doesn't exist, create with defaults
+            mcpLogger.debug('CONFIG', `Creating default config at: ${configPath}`);
+            await saveConfig(DEFAULT_CONFIG);
+            return DEFAULT_CONFIG;
+        }
+        // Read and parse config file
+        const content = await fs.readFile(configPath, 'utf-8');
+        try {
+            const config = JSON.parse(content);
+            mcpLogger.debug('CONFIG', `Loaded config from: ${configPath}`);
+            return config;
+        }
+        catch (parseError) {
+            mcpLogger.error('CONFIG', `Failed to parse config file: ${parseError}`);
+            mcpLogger.info('CONFIG', 'Using default configuration');
+            return DEFAULT_CONFIG;
+        }
+    }
+    catch (error) {
+        mcpLogger.error('CONFIG', `Error loading config: ${error}`);
+        return {};
+    }
+}
+/**
+ * Synchronous version for startup initialization
+ */
+export function loadConfigFromFileSync() {
+    const configPath = getConfigPath();
+    try {
+        ensureConfigDirSync();
+        // Check if config file exists
+        if (!fsSync.existsSync(configPath)) {
+            // Config doesn't exist, create with defaults
+            mcpLogger.debug('CONFIG', `Creating default config at: ${configPath}`);
+            saveConfigSync(DEFAULT_CONFIG);
+            return DEFAULT_CONFIG;
+        }
+        // Read and parse config file
+        const content = fsSync.readFileSync(configPath, 'utf-8');
+        try {
+            const config = JSON.parse(content);
+            mcpLogger.debug('CONFIG', `Loaded config from: ${configPath}`);
+            return config;
+        }
+        catch (parseError) {
+            mcpLogger.error('CONFIG', `Failed to parse config file: ${parseError}`);
+            mcpLogger.info('CONFIG', 'Using default configuration');
+            return DEFAULT_CONFIG;
+        }
+    }
+    catch (error) {
+        mcpLogger.error('CONFIG', `Error loading config: ${error}`);
+        return {};
+    }
+}
+/**
+ * Saves configuration to ~/.claudetools/config.json
+ */
+export async function saveConfig(config) {
+    const configPath = getConfigPath();
+    try {
+        await ensureConfigDir();
+        const content = JSON.stringify(config, null, 2);
+        await fs.writeFile(configPath, content, 'utf-8');
+        mcpLogger.debug('CONFIG', `Saved config to: ${configPath}`);
+    }
+    catch (error) {
+        mcpLogger.error('CONFIG', `Failed to save config: ${error}`);
+        throw error;
+    }
+}
+/**
+ * Synchronous version for startup initialization
+ */
+export function saveConfigSync(config) {
+    const configPath = getConfigPath();
+    try {
+        ensureConfigDirSync();
+        const content = JSON.stringify(config, null, 2);
+        fsSync.writeFileSync(configPath, content, 'utf-8');
+        mcpLogger.debug('CONFIG', `Saved config to: ${configPath}`);
+    }
+    catch (error) {
+        mcpLogger.error('CONFIG', `Failed to save config: ${error}`);
+        throw error;
+    }
+}
+// -----------------------------------------------------------------------------
+// Environment Variable Overrides
+// -----------------------------------------------------------------------------
+/**
+ * Reads configuration overrides from environment variables
+ */
+function getEnvOverrides() {
+    const overrides = {};
+    for (const [envVar, configKey] of Object.entries(ENV_VAR_MAP)) {
+        const value = process.env[envVar];
+        if (value !== undefined && value !== '') {
+            // Type conversion based on default config type
+            const defaultValue = DEFAULT_CONFIG[configKey];
+            if (typeof defaultValue === 'boolean') {
+                overrides[configKey] = value.toLowerCase() === 'true';
+            }
+            else if (typeof defaultValue === 'number') {
+                const numValue = parseInt(value, 10);
+                if (!isNaN(numValue)) {
+                    overrides[configKey] = numValue;
+                }
+            }
+            else if (Array.isArray(defaultValue)) {
+                // Parse comma-separated values
+                overrides[configKey] = value.split(',').map(s => s.trim());
+            }
+            else {
+                overrides[configKey] = value;
+            }
+            mcpLogger.debug('CONFIG', `Environment override: ${configKey} = ${value}`);
+        }
+    }
+    return overrides;
+}
+// -----------------------------------------------------------------------------
+// Merged Configuration
+// -----------------------------------------------------------------------------
+let cachedConfig = null;
+/**
+ * Returns the complete configuration with environment overrides
+ * Priority: Environment Variables > Config File > Defaults
+ */
+export function getConfig() {
+    // Return cached config if available
+    if (cachedConfig) {
+        return cachedConfig;
+    }
+    // Load config from file
+    const fileConfig = loadConfigFromFileSync();
+    // Get environment overrides
+    const envOverrides = getEnvOverrides();
+    // Merge: defaults < file < environment
+    cachedConfig = {
+        ...DEFAULT_CONFIG,
+        ...fileConfig,
+        ...envOverrides,
+    };
+    // Log final configuration in verbose mode
+    if (cachedConfig.verbosity === 'verbose' || cachedConfig.verbosity === 'debug') {
+        mcpLogger.debug('CONFIG', 'Final configuration:');
+        mcpLogger.debug('CONFIG', JSON.stringify(cachedConfig, null, 2));
+    }
+    return cachedConfig;
+}
+/**
+ * Resets the cached configuration (useful for testing or runtime updates)
+ */
+export function resetConfigCache() {
+    cachedConfig = null;
+    mcpLogger.debug('CONFIG', 'Configuration cache reset');
+}
+/**
+ * Updates a specific configuration value and saves to file
+ */
+export async function updateConfig(updates) {
+    const currentConfig = getConfig();
+    const newConfig = { ...currentConfig, ...updates };
+    await saveConfig(newConfig);
+    resetConfigCache();
+    mcpLogger.info('CONFIG', 'Configuration updated');
+    return newConfig;
+}
+/**
+ * Resets configuration to defaults
+ */
+export async function resetConfig() {
+    await saveConfig(DEFAULT_CONFIG);
+    resetConfigCache();
+    mcpLogger.info('CONFIG', 'Configuration reset to defaults');
+    return DEFAULT_CONFIG;
+}
+// -----------------------------------------------------------------------------
+// Initialization
+// -----------------------------------------------------------------------------
+/**
+ * Initialize configuration on module load
+ * This ensures config file exists and is loaded early
+ */
+export function initializeConfig() {
+    ensureConfigDirSync();
+    return getConfig();
+}
+// Auto-initialize on import
+const initialConfig = initializeConfig();
+// Log configuration status on startup
+if (initialConfig.verbosity !== 'quiet') {
+    mcpLogger.info('CONFIG', `ClaudeTools configuration loaded from: ${getConfigPath()}`);
+    mcpLogger.info('CONFIG', `API URL: ${initialConfig.apiUrl}`);
+    mcpLogger.info('CONFIG', `Verbosity: ${initialConfig.verbosity}`);
+    mcpLogger.info('CONFIG', `Auto-inject context: ${initialConfig.autoInjectContext}`);
+}

package/dist/helpers/config.d.ts

@@ -0,0 +1,55 @@
+export declare const API_BASE_URL: string;
+export declare const CLAUDETOOLS_DIR: string;
+export declare const PROJECTS_FILE: string;
+export interface ProjectBinding {
+    project_id: string;
+    project_name: string;
+    org_id: string;
+    local_path: string;
+    git_remote?: string;
+    cached_at: string;
+}
+export interface ProjectsCache {
+    bindings: ProjectBinding[];
+    last_sync: string;
+}
+/**
+ * Validates that a project ID is a proper UUID format
+ */
+export declare function isValidProjectId(id: string): boolean;
+/**
+ * Finds a project binding in the cache by directory path
+ */
+export declare function findProjectBinding(dirPath: string): ProjectBinding | null;
+/**
+ * Look up project ID from local cache based on current working directory
+ * Synchronous version - throws if not already resolved
+ */
+export declare function resolveProjectId(): string;
+/**
+ * Async version that auto-registers if needed
+ * Should be called during server startup
+ */
+export declare function resolveProjectIdAsync(): Promise<string>;
+/**
+ * Gets the default project ID (synchronous version)
+ * Throws if not already resolved - call resolveProjectIdAsync() first
+ */
+export declare function getDefaultProjectId(): string;
+/**
+ * Async version for server startup
+ */
+export declare function getDefaultProjectIdAsync(): Promise<string>;
+export declare const DEFAULT_USER_ID: string;
+export declare const AUTO_INJECT_CONTEXT: boolean;
+export declare let lastContextUsed: {
+    augmentedSystemPrompt: string;
+    metadata: {
+        memoryNeeded: boolean;
+        retrievalTimeMs: number;
+        factsScored: number;
+        factsIncluded: number;
+        avgRelevanceScore: number;
+    };
+} | null;
+export declare function setLastContextUsed(context: typeof lastContextUsed): void;