@phuetz/code-buddy 0.4.0 → 1.0.0

package/dist/tools/tools-md-generator.js

@@ -0,0 +1,249 @@
+/**
+ * TOOLS.md Generator
+ *
+ * Auto-generates .codebuddy/TOOLS.md from the tool registry,
+ * documenting all available tools with descriptions and parameters.
+ * Regenerated on startup if tools have changed.
+ */
+import { writeFile, readFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import { logger } from '../utils/logger.js';
+/**
+ * Human-readable display names for tool categories.
+ */
+const CATEGORY_DISPLAY_NAMES = {
+    file_read: 'File Reading',
+    file_write: 'File Writing',
+    file_search: 'File Search',
+    system: 'System Operations',
+    git: 'Git Operations',
+    web: 'Web Operations',
+    planning: 'Planning & Tasks',
+    media: 'Media',
+    document: 'Documents',
+    utility: 'Utility',
+    codebase: 'Codebase Analysis',
+    mcp: 'MCP (External)',
+};
+/**
+ * Stable ordering for categories in the generated document.
+ */
+const CATEGORY_ORDER = [
+    'file_read',
+    'file_write',
+    'file_search',
+    'system',
+    'git',
+    'web',
+    'planning',
+    'codebase',
+    'media',
+    'document',
+    'utility',
+    'mcp',
+];
+/**
+ * Format a single JSON-schema property as a Markdown parameter line.
+ */
+function formatParam(name, prop, isRequired) {
+    const parts = [];
+    parts.push(`- \`${name}\``);
+    const qualifiers = [];
+    if (prop.type)
+        qualifiers.push(prop.type);
+    if (isRequired)
+        qualifiers.push('required');
+    if (qualifiers.length > 0) {
+        parts.push(`(${qualifiers.join(', ')})`);
+    }
+    if (prop.description) {
+        // Collapse multi-line descriptions to a single line for the table
+        const desc = prop.description.replace(/\n/g, ' ').replace(/\s{2,}/g, ' ').trim();
+        parts.push(`- ${desc}`);
+    }
+    if (prop.enum && prop.enum.length > 0) {
+        parts.push(`  Values: ${prop.enum.map(v => `\`${v}\``).join(', ')}`);
+    }
+    if (prop.default !== undefined) {
+        parts.push(`  Default: \`${String(prop.default)}\``);
+    }
+    return parts.join(' ');
+}
+/**
+ * Render a single tool as Markdown.
+ */
+function renderTool(tool, meta) {
+    const fn = tool.function;
+    const lines = [];
+    lines.push(`### ${fn.name}`);
+    lines.push('');
+    // Use metadata description if shorter / cleaner; fall back to tool definition
+    const desc = meta?.description || fn.description || '';
+    // Take only the first sentence / line for the summary
+    const summary = (desc.split('\n')[0] ?? '').trim();
+    lines.push(summary);
+    lines.push('');
+    const props = fn.parameters?.properties;
+    const required = new Set(fn.parameters?.required ?? []);
+    if (props && Object.keys(props).length > 0) {
+        lines.push('**Parameters:**');
+        for (const [name, prop] of Object.entries(props)) {
+            lines.push(formatParam(name, prop, required.has(name)));
+        }
+        lines.push('');
+    }
+    if (meta?.keywords && meta.keywords.length > 0) {
+        lines.push(`**Keywords:** ${meta.keywords.join(', ')}`);
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Build the full Markdown content from the tool definitions and metadata.
+ */
+function buildMarkdown(tools, metadataMap) {
+    const lines = [];
+    lines.push('# Available Tools');
+    lines.push('');
+    lines.push('> Auto-generated tool reference for CodeBuddy. Do not edit manually.');
+    lines.push(`> Generated: ${new Date().toISOString().slice(0, 10)}`);
+    lines.push('');
+    // Group tools by category
+    const grouped = new Map();
+    for (const tool of tools) {
+        const meta = metadataMap.get(tool.function.name);
+        const category = meta?.category ?? 'utility';
+        if (!grouped.has(category)) {
+            grouped.set(category, []);
+        }
+        grouped.get(category).push({ tool, meta });
+    }
+    // Table of contents
+    lines.push('## Table of Contents');
+    lines.push('');
+    for (const cat of CATEGORY_ORDER) {
+        const items = grouped.get(cat);
+        if (!items || items.length === 0)
+            continue;
+        const displayName = CATEGORY_DISPLAY_NAMES[cat] || cat;
+        const anchor = displayName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+$/, '');
+        lines.push(`- [${displayName}](#${anchor}) (${items.length})`);
+    }
+    lines.push('');
+    // Emit each category
+    for (const cat of CATEGORY_ORDER) {
+        const items = grouped.get(cat);
+        if (!items || items.length === 0)
+            continue;
+        const displayName = CATEGORY_DISPLAY_NAMES[cat] || cat;
+        lines.push(`## ${displayName}`);
+        lines.push('');
+        // Sort tools within a category by priority (desc), then name (asc)
+        items.sort((a, b) => {
+            const pa = a.meta?.priority ?? 5;
+            const pb = b.meta?.priority ?? 5;
+            if (pb !== pa)
+                return pb - pa;
+            return a.tool.function.name.localeCompare(b.tool.function.name);
+        });
+        for (const { tool, meta } of items) {
+            lines.push(renderTool(tool, meta));
+        }
+    }
+    // Append any tools that didn't match a known category
+    Array.from(grouped.entries()).forEach(([cat, items]) => {
+        if (CATEGORY_ORDER.includes(cat))
+            return;
+        if (items.length === 0)
+            return;
+        const displayName = CATEGORY_DISPLAY_NAMES[cat] || cat;
+        lines.push(`## ${displayName}`);
+        lines.push('');
+        for (const { tool, meta } of items) {
+            lines.push(renderTool(tool, meta));
+        }
+    });
+    lines.push(`_Total tools: ${tools.length}_`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Compute a short content hash for change detection.
+ */
+function computeHash(tools) {
+    const payload = tools.map(t => {
+        const fn = t.function;
+        return `${fn.name}:${fn.description}:${JSON.stringify(fn.parameters)}`;
+    }).join('|');
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+/**
+ * Extract the hash stored in a previously generated TOOLS.md.
+ * The hash is stored as an HTML comment on the last line.
+ */
+function extractStoredHash(content) {
+    const match = content.match(/<!-- hash:([a-f0-9]+) -->/);
+    return match?.[1] ?? null;
+}
+/**
+ * Generate .codebuddy/TOOLS.md from the tool registry.
+ *
+ * Only regenerates if the file is missing or tools have changed
+ * (compared via a content hash).
+ */
+export async function generateToolsMd() {
+    try {
+        // Lazy-import to avoid pulling tool definitions into the critical startup path
+        const { initializeToolRegistry } = await import('../codebuddy/tools.js');
+        const { getToolRegistry } = await import('./registry.js');
+        const { TOOL_METADATA } = await import('./metadata.js');
+        // Ensure registry is populated
+        initializeToolRegistry();
+        const registry = getToolRegistry();
+        const tools = registry.getEnabledTools();
+        if (tools.length === 0) {
+            logger.debug('TOOLS.md generation skipped: no tools registered');
+            return;
+        }
+        // Compute hash for change detection
+        const hash = computeHash(tools);
+        // Resolve output path
+        const dir = join(process.cwd(), '.codebuddy');
+        const filePath = join(dir, 'TOOLS.md');
+        // Check if regeneration is needed
+        if (existsSync(filePath)) {
+            try {
+                const existing = await readFile(filePath, 'utf-8');
+                const storedHash = extractStoredHash(existing);
+                if (storedHash === hash) {
+                    logger.debug('TOOLS.md is up to date, skipping regeneration');
+                    return;
+                }
+            }
+            catch (_err) {
+                // File exists but couldn't be read - regenerate
+            }
+        }
+        // Build metadata map
+        const metadataMap = new Map(TOOL_METADATA.map(m => [m.name, m]));
+        // Generate markdown
+        const markdown = buildMarkdown(tools, metadataMap);
+        // Append hash as HTML comment for change detection
+        const content = markdown + `<!-- hash:${hash} -->\n`;
+        // Ensure directory exists
+        if (!existsSync(dir)) {
+            await mkdir(dir, { recursive: true });
+        }
+        await writeFile(filePath, content, 'utf-8');
+        logger.debug(`TOOLS.md generated with ${tools.length} tools`);
+    }
+    catch (err) {
+        // Never let TOOLS.md generation break startup
+        logger.debug('TOOLS.md generation failed', { error: err });
+    }
+}
+//# sourceMappingURL=tools-md-generator.js.map

package/dist/tools/types.d.ts

@@ -18,6 +18,21 @@ export interface ToolMetadata {
     priority: number;
     /** Human-readable description */
     description: string;
+    /**
+     * Whether this tool is safe to expose to remote peers via A2A / fleet.
+     *
+     * Default `false` (opt-in). A tool MUST satisfy ALL of:
+     *   - read-only OR strictly bounded side effects (no arbitrary code exec,
+     *     no host-side mutation that the local user hasn't explicitly authorized)
+     *   - cannot exfiltrate secrets (env, ~/.ssh, ~/.aws, credentials)
+     *   - cannot drive UI input (keyboard/mouse synthesis)
+     *   - bounded resource usage (no unbounded loops, sub-process forks, etc.)
+     *
+     * The fleet event bus and A2A executor inspect this flag before allowing
+     * a peer-originated invocation. Tools without `fleetSafe: true` are
+     * silently filtered out from peer-visible tool lists.
+     */
+    fleetSafe?: boolean;
 }
 /**
  * Result of classifying a user query into tool categories.

package/dist/tools/unified-diff-editor.js

@@ -213,7 +213,12 @@ export class UnifiedDiffEditor {
         let normPos = 0;
         const normalizedChars = normalized.split('');
         while (normPos < normalizedPos && origPos < original.length) {
+            // origPos < original.length guaranteed by loop condition, so origChar is defined.
             const origChar = original[origPos];
+            if (origChar === undefined)
+                break;
+            // normChar may be undefined if normalizedPos exceeds the normalized length;
+            // an undefined normChar never equals the string origChar, matching prior behavior.
             const normChar = normalizedChars[normPos];
             if (origChar === normChar) {
                 origPos++;
@@ -340,8 +345,9 @@ export class UnifiedDiffEditor {
             if (line.startsWith('diff --git')) {
                 flushHunk();
                 const match = line.match(/ b\/(.+)$/);
-                if (match) {
-                    currentOp = { filePath: match[1], hunks: [] };
+                const filePath = match?.[1];
+                if (filePath !== undefined) {
+                    currentOp = { filePath, hunks: [] };
                     operations.push(currentOp);
                 }
             }

package/dist/tools/video-analysis-tool.d.ts

@@ -0,0 +1,19 @@
+import type { MediaGenerationRuntime } from './media-generation-tool.js';
+export interface VideoAnalyzeInput {
+    videoUrl: string;
+    question: string;
+}
+export interface VideoAnalyzeResult {
+    success: boolean;
+    analysis: string;
+    kind: 'video_analyze_result';
+    videoSource: string;
+    question: string;
+    model: string;
+    generatedAt: string;
+    videoSizeBytes: number;
+    mimeType: string;
+    error?: string;
+    error_type?: string;
+}
+export declare function analyzeVideoWithModel(input: VideoAnalyzeInput, runtime?: MediaGenerationRuntime): Promise<VideoAnalyzeResult>;

package/dist/tools/video-analysis-tool.js

@@ -0,0 +1,210 @@
+import { randomUUID } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+const VIDEO_MIME_TYPES = {
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.avi': 'video/x-msvideo',
+    '.mkv': 'video/x-matroska',
+    '.mpeg': 'video/mpeg',
+    '.mpg': 'video/mpeg',
+};
+const MAX_VIDEO_BASE64_BYTES = 50 * 1024 * 1024;
+export async function analyzeVideoWithModel(input, runtime = {}) {
+    const videoSource = input.videoUrl.trim();
+    const question = input.question.trim();
+    if (!videoSource) {
+        throw new Error('video_url is required');
+    }
+    if (!question) {
+        throw new Error('question is required');
+    }
+    const fetchImpl = runtime.fetch ?? fetch;
+    const rootDir = path.resolve(runtime.rootDir ?? process.cwd());
+    const prepared = await prepareVideo(videoSource, {
+        rootDir,
+        fetchImpl,
+        createId: runtime.createId,
+    });
+    const dataUrl = await videoToBase64DataUrl(prepared.path, prepared.mimeType);
+    const config = resolveVideoAnalysisConfig(runtime.env ?? process.env);
+    const prompt = [
+        'Fully describe and explain everything happening in this video, including visual content, motion, audio cues, text overlays, and scene transitions.',
+        '',
+        'Then answer the following question:',
+        '',
+        question,
+    ].join('\n');
+    const response = await postChatCompletion(fetchImpl, config, prompt, dataUrl);
+    const analysis = extractAssistantText(response);
+    if (!analysis) {
+        throw new Error('Video-capable model returned an empty response');
+    }
+    return {
+        success: true,
+        analysis,
+        kind: 'video_analyze_result',
+        videoSource,
+        question,
+        model: config.model,
+        generatedAt: (runtime.now ?? (() => new Date()))().toISOString(),
+        videoSizeBytes: prepared.sizeBytes,
+        mimeType: prepared.mimeType,
+    };
+}
+async function prepareVideo(videoSource, options) {
+    if (/^https?:\/\//i.test(videoSource)) {
+        const response = await fetchWithTimeout(options.fetchImpl, videoSource, {
+            headers: { Accept: 'video/*,*/*;q=0.8' },
+        }, 60_000);
+        if (!response.ok) {
+            throw new Error(`Video download failed with HTTP ${response.status}: ${(await response.text()).slice(0, 300)}`);
+        }
+        const bytes = Buffer.from(await response.arrayBuffer());
+        if (bytes.length <= 0) {
+            throw new Error('Downloaded video was empty');
+        }
+        if (bytes.length > MAX_VIDEO_BASE64_BYTES) {
+            throw new Error(`Video too large (${bytes.length} bytes, max ${MAX_VIDEO_BASE64_BYTES})`);
+        }
+        const mimeType = detectMimeFromContentType(response.headers.get('content-type')) ?? 'video/mp4';
+        const ext = extensionForMime(mimeType);
+        const cacheDir = path.join(options.rootDir, '.codebuddy', 'video-analysis');
+        await fs.mkdir(cacheDir, { recursive: true });
+        const localPath = path.join(cacheDir, `video-${sanitizeId(options.createId?.() ?? randomUUID())}.${ext}`);
+        await fs.writeFile(localPath, bytes);
+        return { path: localPath, mimeType, sizeBytes: bytes.length };
+    }
+    const stripped = videoSource.startsWith('file://') ? videoSource.slice('file://'.length) : videoSource;
+    const localPath = path.isAbsolute(stripped) ? path.resolve(stripped) : path.resolve(options.rootDir, stripped);
+    const stat = await fs.stat(localPath);
+    const mimeType = detectVideoMimeType(localPath);
+    if (!mimeType) {
+        throw new Error(`Unsupported video format: ${path.extname(localPath)}. Supported: ${Object.keys(VIDEO_MIME_TYPES).join(', ')}`);
+    }
+    if (stat.size > MAX_VIDEO_BASE64_BYTES) {
+        throw new Error(`Video too large (${stat.size} bytes, max ${MAX_VIDEO_BASE64_BYTES})`);
+    }
+    return { path: localPath, mimeType, sizeBytes: stat.size };
+}
+function detectVideoMimeType(videoPath) {
+    return VIDEO_MIME_TYPES[path.extname(videoPath).toLowerCase()];
+}
+async function videoToBase64DataUrl(videoPath, mimeType) {
+    const bytes = await fs.readFile(videoPath);
+    return `data:${mimeType};base64,${bytes.toString('base64')}`;
+}
+function resolveVideoAnalysisConfig(env) {
+    const baseUrl = (env.CODEBUDDY_VIDEO_ANALYSIS_BASE_URL
+        ?? env.OPENAI_BASE_URL
+        ?? 'https://api.openai.com/v1').trim().replace(/\/+$/, '');
+    const apiKey = (env.CODEBUDDY_VIDEO_ANALYSIS_API_KEY ?? env.OPENAI_API_KEY ?? '').trim();
+    const model = (env.CODEBUDDY_VIDEO_ANALYSIS_MODEL
+        ?? env.AUXILIARY_VIDEO_MODEL
+        ?? env.AUXILIARY_VISION_MODEL
+        ?? 'gpt-4o-mini').trim();
+    if (!apiKey && !isLocalBaseUrl(baseUrl)) {
+        throw new Error('No video analysis credentials configured. Set CODEBUDDY_VIDEO_ANALYSIS_API_KEY or OPENAI_API_KEY.');
+    }
+    return { baseUrl, apiKey, model };
+}
+async function postChatCompletion(fetchImpl, config, prompt, videoDataUrl) {
+    const response = await fetchWithTimeout(fetchImpl, joinUrl(config.baseUrl, '/chat/completions'), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+            model: config.model,
+            temperature: 0.1,
+            max_tokens: 4000,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        { type: 'text', text: prompt },
+                        { type: 'video_url', video_url: { url: videoDataUrl } },
+                    ],
+                },
+            ],
+        }),
+    }, 180_000);
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`Video analysis API returned ${response.status}: ${text.slice(0, 500)}`);
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Video analysis API returned non-object JSON');
+    }
+    return parsed;
+}
+function extractAssistantText(response) {
+    const choices = response.choices;
+    if (!Array.isArray(choices) || choices.length === 0) {
+        return undefined;
+    }
+    const first = choices[0];
+    if (!first || typeof first !== 'object') {
+        return undefined;
+    }
+    const message = first.message;
+    if (!message || typeof message !== 'object') {
+        return undefined;
+    }
+    const content = message.content;
+    if (typeof content === 'string') {
+        return content.trim();
+    }
+    if (Array.isArray(content)) {
+        const parts = content
+            .map((part) => part && typeof part === 'object' ? part.text : undefined)
+            .filter((part) => typeof part === 'string' && part.trim().length > 0);
+        return parts.join('\n').trim() || undefined;
+    }
+    return undefined;
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function detectMimeFromContentType(contentType) {
+    const type = (contentType ?? '').split(';', 1)[0]?.trim().toLowerCase();
+    return type && type.startsWith('video/') ? type : undefined;
+}
+function extensionForMime(mimeType) {
+    if (mimeType === 'video/webm')
+        return 'webm';
+    if (mimeType === 'video/quicktime' || mimeType === 'video/mov')
+        return 'mov';
+    if (mimeType === 'video/mpeg')
+        return 'mpeg';
+    return 'mp4';
+}
+function joinUrl(baseUrl, suffix) {
+    const normalizedBase = baseUrl.replace(/\/+$/, '');
+    const normalizedSuffix = suffix.replace(/^\/+/, '');
+    return `${normalizedBase}/${normalizedSuffix}`;
+}
+function isLocalBaseUrl(baseUrl) {
+    try {
+        const host = new URL(baseUrl).hostname;
+        return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    }
+    catch {
+        return false;
+    }
+}
+function sanitizeId(id) {
+    const sanitized = id.trim().replace(/[^A-Za-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+    return sanitized || randomUUID();
+}
+//# sourceMappingURL=video-analysis-tool.js.map

package/dist/tools/video-tool.js

@@ -90,7 +90,9 @@ export class VideoTool {
                         info.codec = videoStream.codec_name;
                         if (videoStream.r_frame_rate) {
                             const [num, den] = videoStream.r_frame_rate.split('/');
-                            info.fps = Math.round(parseInt(num) / parseInt(den));
+                            if (num !== undefined && den !== undefined) {
+                                info.fps = Math.round(parseInt(num) / parseInt(den));
+                            }
                         }
                     }
                     if (format?.bit_rate) {
@@ -145,8 +147,7 @@ export class VideoTool {
             const frames = [];
             if (options.timestamps && options.timestamps.length > 0) {
                 // Extract specific timestamps
-                for (let i = 0; i < options.timestamps.length; i++) {
-                    const timestamp = options.timestamps[i];
+                for (const [i, timestamp] of options.timestamps.entries()) {
                     const outputPath = path.join(outputDir, `frame_${i + 1}.${format}`);
                     await this.extractFrameAtTimestamp(resolvedPath, timestamp, outputPath);
                     frames.push({

package/dist/tools/vision/image-processor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Image Processor Tool
+ *
+ * Uses sharp for native image manipulation, resizing, and analysis.
+ */
+export interface ImageAnalysisResult {
+    description: string;
+    labels: string[];
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    format?: string;
+    size?: number;
+    channels?: number;
+}
+export interface ResizeOptions {
+    width?: number;
+    height?: number;
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+}
+export declare class ImageProcessorTool {
+    private static instance;
+    private constructor();
+    static getInstance(): ImageProcessorTool;
+    analyze(imagePath: string): Promise<ImageAnalysisResult>;
+    resize(imagePath: string, options: ResizeOptions, outputPath?: string): Promise<string>;
+    convert(imagePath: string, format: 'jpeg' | 'png' | 'webp' | 'avif', outputPath?: string): Promise<string>;
+    compare(path1: string, path2: string): Promise<{
+        similarity: number;
+        description: string;
+        sameDimensions: boolean;
+    }>;
+    getSupportedFormats(): string[];
+    isValidImage(filePath: string): boolean;
+    private generateOutputPath;
+}