@blockrun/franklin 3.0.0

package/dist/tools/edit.js

@@ -0,0 +1,148 @@
+/**
+ * Edit capability — targeted string replacement in files.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { partiallyReadFiles } from './read.js';
+/**
+ * Normalize curly/smart quotes to straight quotes.
+ * Claude Code does this to handle API-sanitized strings and editor paste artifacts.
+ */
+function normalizeQuotes(str) {
+    return str
+        .replace(/[\u201C\u201D]/g, '"') // " " → "
+        .replace(/[\u2018\u2019]/g, "'"); // ' ' → '
+}
+async function execute(input, ctx) {
+    const { file_path: filePath, old_string: oldStr, new_string: newStr, replace_all: replaceAll } = input;
+    if (!filePath) {
+        return { output: 'Error: file_path is required', isError: true };
+    }
+    if (oldStr === undefined || oldStr === null) {
+        return { output: 'Error: old_string is required', isError: true };
+    }
+    if (newStr === undefined || newStr === null) {
+        return { output: 'Error: new_string is required', isError: true };
+    }
+    if (oldStr === newStr) {
+        return { output: 'Error: old_string and new_string are identical', isError: true };
+    }
+    const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(ctx.workingDir, filePath);
+    // Warn if the file was only partially read — editing without full context risks mistakes
+    const isPartial = partiallyReadFiles.has(resolved);
+    try {
+        if (!fs.existsSync(resolved)) {
+            return { output: `Error: file not found: ${resolved}`, isError: true };
+        }
+        const content = fs.readFileSync(resolved, 'utf-8');
+        // Try exact match first, then quote-normalized fallback
+        let effectiveOldStr = oldStr;
+        if (!content.includes(oldStr)) {
+            const normalized = normalizeQuotes(oldStr);
+            const contentNormalized = normalizeQuotes(content);
+            if (normalized !== oldStr && contentNormalized.includes(normalized)) {
+                // Find the original text in content that corresponds to the normalized match
+                const idx = contentNormalized.indexOf(normalized);
+                effectiveOldStr = content.slice(idx, idx + normalized.length);
+            }
+        }
+        if (!content.includes(effectiveOldStr)) {
+            // Find lines containing fragments of old_string for helpful context
+            const lines = content.split('\n');
+            const searchTerms = oldStr.split('\n').map(l => l.trim()).filter(l => l.length > 3);
+            const matchedLines = [];
+            if (searchTerms.length > 0) {
+                for (let i = 0; i < lines.length && matchedLines.length < 5; i++) {
+                    if (searchTerms.some(term => lines[i].includes(term))) {
+                        matchedLines.push({ num: i + 1, text: lines[i] });
+                    }
+                }
+            }
+            let hint;
+            if (matchedLines.length > 0) {
+                const preview = matchedLines.map(m => `${m.num}\t${m.text}`).join('\n');
+                hint = `\n\nSimilar lines found:\n${preview}\n\nCheck for whitespace or formatting differences.`;
+            }
+            else {
+                const preview = lines.slice(0, 10).map((l, i) => `${i + 1}\t${l}`).join('\n');
+                hint = `\n\nFirst 10 lines of file:\n${preview}`;
+            }
+            return {
+                output: `Error: old_string not found in ${resolved}.${hint}`,
+                isError: true,
+            };
+        }
+        let updated;
+        let matchCount;
+        if (replaceAll) {
+            matchCount = content.split(effectiveOldStr).length - 1;
+            updated = content.split(effectiveOldStr).join(newStr);
+        }
+        else {
+            const firstIdx = content.indexOf(effectiveOldStr);
+            const secondIdx = content.indexOf(effectiveOldStr, firstIdx + 1);
+            if (secondIdx !== -1) {
+                const positions = [];
+                let searchFrom = 0;
+                while (true) {
+                    const idx = content.indexOf(effectiveOldStr, searchFrom);
+                    if (idx === -1)
+                        break;
+                    const lineNum = content.slice(0, idx).split('\n').length;
+                    positions.push(lineNum);
+                    searchFrom = idx + 1;
+                }
+                return {
+                    output: `Error: old_string matches ${positions.length} locations (lines: ${positions.join(', ')}). ` +
+                        `Provide more context to make it unique, or use replace_all: true.`,
+                    isError: true,
+                };
+            }
+            matchCount = 1;
+            updated = content.slice(0, firstIdx) + newStr + content.slice(firstIdx + effectiveOldStr.length);
+        }
+        fs.writeFileSync(resolved, updated, 'utf-8');
+        // File has been modified — remove from partial-read tracking so next read is fresh
+        partiallyReadFiles.delete(resolved);
+        // Build a concise diff preview
+        const oldLines = effectiveOldStr.split('\n');
+        const newLines = newStr.split('\n');
+        let diffPreview = '';
+        if (oldLines.length <= 5 && newLines.length <= 5) {
+            const removed = oldLines.map(l => `- ${l}`).join('\n');
+            const added = newLines.map(l => `+ ${l}`).join('\n');
+            diffPreview = `\n${removed}\n${added}`;
+        }
+        else {
+            diffPreview = ` (${oldLines.length} lines → ${newLines.length} lines)`;
+        }
+        const partialWarning = isPartial
+            ? '\nNote: file was only partially read before this edit.'
+            : '';
+        return {
+            output: `Updated ${resolved} — ${matchCount} replacement${matchCount > 1 ? 's' : ''} made.${diffPreview}${partialWarning}`,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { output: `Error editing file: ${msg}`, isError: true };
+    }
+}
+export const editCapability = {
+    spec: {
+        name: 'Edit',
+        description: 'Replace exact string in a file. old_string must be unique (or use replace_all).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                file_path: { type: 'string', description: 'Absolute path' },
+                old_string: { type: 'string', description: 'Text to find' },
+                new_string: { type: 'string', description: 'Replacement text' },
+                replace_all: { type: 'boolean', description: 'Replace all occurrences' },
+            },
+            required: ['file_path', 'old_string', 'new_string'],
+        },
+    },
+    execute,
+    concurrent: false,
+};

package/dist/tools/glob.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Glob capability — file pattern matching using native fs.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const globCapability: CapabilityHandler;

package/dist/tools/glob.js

@@ -0,0 +1,158 @@
+/**
+ * Glob capability — file pattern matching using native fs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_RESULTS = 200;
+const MAX_OUTPUT_CHARS = 12_000; // ~3,000 tokens — prevents huge glob results from blowing up context
+/**
+ * Simple glob matcher supporting *, **, and ? wildcards.
+ * No external dependencies.
+ */
+function globMatch(pattern, text) {
+    const regexStr = pattern
+        .replace(/\\/g, '/')
+        .split('**/')
+        .map(segment => segment
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]'))
+        .join('(?:.*/)?');
+    const regex = new RegExp(`^${regexStr}$`);
+    return regex.test(text.replace(/\\/g, '/'));
+}
+function walkDirectory(dir, baseDir, pattern, results, depth, visited) {
+    if (depth > 50 || results.length >= MAX_RESULTS)
+        return;
+    // Symlink loop protection
+    const visitedSet = visited ?? new Set();
+    let realDir;
+    try {
+        realDir = fs.realpathSync(dir);
+    }
+    catch {
+        return;
+    }
+    if (visitedSet.has(realDir))
+        return;
+    visitedSet.add(realDir);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // Permission denied or similar
+    }
+    for (const entry of entries) {
+        if (results.length >= MAX_RESULTS)
+            break;
+        // Skip hidden dirs and common large dirs
+        const isDir = entry.isDirectory() || (entry.isSymbolicLink() && isSymlinkDir(path.join(dir, entry.name)));
+        if (entry.name.startsWith('.') && isDir)
+            continue;
+        if (entry.name === 'node_modules' || entry.name === '__pycache__' || entry.name === '.git')
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(baseDir, fullPath);
+        if (entry.isFile() || (entry.isSymbolicLink() && !isDir)) {
+            if (globMatch(pattern, relativePath)) {
+                results.push(fullPath);
+            }
+        }
+        else if (isDir) {
+            // Recurse for ** patterns; for patterns with /, only recurse if current dir is on the path
+            if (pattern.includes('**')) {
+                walkDirectory(fullPath, baseDir, pattern, results, depth + 1, visitedSet);
+            }
+            else if (pattern.includes('/')) {
+                // Check if this directory could be part of the pattern path
+                const relativePath = path.relative(baseDir, fullPath);
+                const patternDir = pattern.split('/').slice(0, -1).join('/');
+                if (patternDir.startsWith(relativePath) || relativePath.startsWith(patternDir)) {
+                    walkDirectory(fullPath, baseDir, pattern, results, depth + 1, visitedSet);
+                }
+            }
+        }
+    }
+}
+function isSymlinkDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function execute(input, ctx) {
+    const { pattern, path: searchPath } = input;
+    if (!pattern) {
+        return { output: 'Error: pattern is required', isError: true };
+    }
+    const baseDir = searchPath
+        ? (path.isAbsolute(searchPath) ? searchPath : path.resolve(ctx.workingDir, searchPath))
+        : ctx.workingDir;
+    if (!fs.existsSync(baseDir)) {
+        return { output: `Error: directory not found: ${baseDir}`, isError: true };
+    }
+    const results = [];
+    walkDirectory(baseDir, baseDir, pattern, results, 0);
+    // Sort by modification time (most recent first)
+    const withMtime = results.map(f => {
+        try {
+            return { path: f, mtime: fs.statSync(f).mtimeMs };
+        }
+        catch {
+            return { path: f, mtime: 0 };
+        }
+    });
+    withMtime.sort((a, b) => b.mtime - a.mtime);
+    // Convert to relative paths to save tokens (same as Claude Code)
+    const sorted = withMtime.map(f => {
+        const rel = path.relative(ctx.workingDir, f.path);
+        return rel.startsWith('..') ? f.path : rel;
+    });
+    if (sorted.length === 0) {
+        // Suggest recursive pattern if user used non-recursive glob
+        const hint = !pattern.includes('**') && !pattern.includes('/')
+            ? ` Try "**/${pattern}" for recursive search.`
+            : '';
+        return { output: `No files matched pattern "${pattern}" in ${baseDir}.${hint}` };
+    }
+    let output = sorted.join('\n');
+    if (sorted.length >= MAX_RESULTS) {
+        output += `\n\n... (limited to ${MAX_RESULTS} results. Use a more specific pattern to narrow results.)`;
+    }
+    // Cap total output length to prevent context bloat
+    if (output.length > MAX_OUTPUT_CHARS) {
+        const lines = output.split('\n');
+        let trimmed = '';
+        let count = 0;
+        for (const line of lines) {
+            if ((trimmed + line).length > MAX_OUTPUT_CHARS)
+                break;
+            trimmed += (trimmed ? '\n' : '') + line;
+            count++;
+        }
+        const remaining = lines.length - count;
+        if (remaining > 0) {
+            output = `${trimmed}\n... (${remaining} more paths not shown — use a more specific pattern)`;
+        }
+    }
+    return { output };
+}
+export const globCapability = {
+    spec: {
+        name: 'Glob',
+        description: 'Find files by glob pattern (e.g. "**/*.ts", "src/**/*.tsx"). Returns up to 500 paths sorted by modification time. Skips node_modules, .git, hidden dirs.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Glob pattern to match files (e.g. "**/*.ts")' },
+                path: { type: 'string', description: 'Directory to search in. Defaults to working directory.' },
+            },
+            required: ['pattern'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/grep.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Grep capability — search file contents using ripgrep or native fallback.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const grepCapability: CapabilityHandler;

package/dist/tools/grep.js

@@ -0,0 +1,194 @@
+/**
+ * Grep capability — search file contents using ripgrep or native fallback.
+ */
+import { execSync, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_GREP_OUTPUT_CHARS = 16_000; // ~4,000 tokens — prevents huge grep results
+let _hasRipgrep = null;
+function hasRipgrep() {
+    if (_hasRipgrep !== null)
+        return _hasRipgrep;
+    try {
+        execSync('rg --version', { stdio: 'pipe' });
+        _hasRipgrep = true;
+    }
+    catch {
+        _hasRipgrep = false;
+    }
+    return _hasRipgrep;
+}
+async function execute(input, ctx) {
+    const opts = input;
+    if (!opts.pattern) {
+        return { output: 'Error: pattern is required', isError: true };
+    }
+    const searchPath = opts.path
+        ? (path.isAbsolute(opts.path) ? opts.path : path.resolve(ctx.workingDir, opts.path))
+        : ctx.workingDir;
+    if (!fs.existsSync(searchPath)) {
+        return { output: `Error: path not found: ${searchPath}`, isError: true };
+    }
+    const mode = opts.output_mode || 'files_with_matches';
+    const limit = opts.head_limit ?? 250;
+    if (hasRipgrep()) {
+        return runRipgrep(opts, searchPath, mode, limit, ctx.workingDir);
+    }
+    return runNativeGrep(opts, searchPath, mode, limit, ctx.workingDir);
+}
+function toRelative(absPath, cwd) {
+    const rel = path.relative(cwd, absPath);
+    return rel.startsWith('..') ? absPath : rel;
+}
+function runRipgrep(opts, searchPath, mode, limit, cwd) {
+    const args = [];
+    // Limit line length to prevent base64/minified content from cluttering output
+    args.push('--max-columns', '500');
+    switch (mode) {
+        case 'files_with_matches':
+            args.push('-l');
+            break;
+        case 'count':
+            args.push('-c');
+            break;
+        case 'content':
+            args.push('-n');
+            if (opts.context && opts.context > 0) {
+                args.push(`-C${opts.context}`);
+            }
+            else {
+                if (opts.before_context && opts.before_context > 0)
+                    args.push(`-B${opts.before_context}`);
+                if (opts.after_context && opts.after_context > 0)
+                    args.push(`-A${opts.after_context}`);
+            }
+            break;
+    }
+    if (opts.case_insensitive)
+        args.push('-i');
+    if (opts.multiline)
+        args.push('-U', '--multiline-dotall');
+    if (opts.glob)
+        args.push(`--glob=${opts.glob}`);
+    // Always exclude common noise + lock files (huge, rarely useful)
+    args.push('--glob=!node_modules', '--glob=!.git', '--glob=!dist', '--glob=!*.lock', '--glob=!package-lock.json', '--glob=!pnpm-lock.yaml');
+    args.push('--', opts.pattern);
+    args.push(searchPath);
+    try {
+        const result = execFileSync('rg', args, {
+            encoding: 'utf-8',
+            maxBuffer: 2 * 1024 * 1024,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const lines = result.split('\n').filter(Boolean);
+        const limited = limit > 0 ? lines.slice(0, limit) : lines;
+        // Convert absolute paths to relative paths to save tokens (same as Claude Code)
+        const relativized = limited.map(line => {
+            // Lines: /abs/path or /abs/path:rest (content mode)
+            const colonIdx = line.indexOf(':');
+            if (colonIdx > 0 && line.startsWith('/')) {
+                const filePart = line.slice(0, colonIdx);
+                return toRelative(filePart, cwd) + line.slice(colonIdx);
+            }
+            return line.startsWith('/') ? toRelative(line, cwd) : line;
+        });
+        let output = relativized.join('\n');
+        if (lines.length > limited.length) {
+            output += `\n\n... (${lines.length - limited.length} more results, use head_limit to see more)`;
+        }
+        // Cap total output to prevent context bloat
+        if (output.length > MAX_GREP_OUTPUT_CHARS) {
+            output = output.slice(0, MAX_GREP_OUTPUT_CHARS) + `\n... (output capped at ${MAX_GREP_OUTPUT_CHARS / 1000}KB — use more specific pattern or head_limit)`;
+        }
+        return { output: output || 'No matches found' };
+    }
+    catch (err) {
+        const exitErr = err;
+        if (exitErr.status === 1) {
+            return { output: 'No matches found' };
+        }
+        return {
+            output: `Grep error: ${exitErr.stderr || err.message}`,
+            isError: true,
+        };
+    }
+}
+function runNativeGrep(opts, searchPath, mode, limit, cwd) {
+    const args = ['-r', '-n'];
+    if (opts.case_insensitive)
+        args.push('-i');
+    switch (mode) {
+        case 'files_with_matches':
+            args.push('-l');
+            break;
+        case 'count':
+            args.push('-c');
+            break;
+    }
+    if (opts.glob) {
+        // Native grep --include doesn't support ** or path separators
+        // Extract file extension pattern for best compatibility
+        const nativeGlob = opts.glob
+            .replace(/^\*\*\//, '') // Strip leading **/
+            .replace(/^.*\//, '') // Strip path prefix (src/ etc.)
+            .replace(/\*\*/, '*'); // Convert ** to * for flat matching
+        args.push(`--include=${nativeGlob}`);
+    }
+    args.push('--exclude-dir=node_modules', '--exclude-dir=.git', '--exclude-dir=dist', '--exclude=*.lock', '--exclude=package-lock.json', '--exclude=pnpm-lock.yaml');
+    args.push('-e', opts.pattern, searchPath);
+    try {
+        const result = execFileSync('grep', args, {
+            encoding: 'utf-8',
+            maxBuffer: 2 * 1024 * 1024,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const lines = result.split('\n').filter(Boolean);
+        const limited = limit > 0 ? lines.slice(0, limit) : lines;
+        const relativized = limited.map(line => {
+            const colonIdx = line.indexOf(':');
+            if (colonIdx > 0 && line.startsWith('/')) {
+                return toRelative(line.slice(0, colonIdx), cwd) + line.slice(colonIdx);
+            }
+            return line.startsWith('/') ? toRelative(line, cwd) : line;
+        });
+        let output = relativized.join('\n');
+        if (lines.length > limited.length) {
+            output += `\n\n... (${lines.length - limited.length} more results)`;
+        }
+        if (output.length > MAX_GREP_OUTPUT_CHARS) {
+            output = output.slice(0, MAX_GREP_OUTPUT_CHARS) + `\n... (output capped at ${MAX_GREP_OUTPUT_CHARS / 1000}KB)`;
+        }
+        return { output: output || 'No matches found' };
+    }
+    catch (err) {
+        const exitErr = err;
+        if (exitErr.status === 1) {
+            return { output: 'No matches found' };
+        }
+        return { output: `Grep error: ${err.message}`, isError: true };
+    }
+}
+export const grepCapability = {
+    spec: {
+        name: 'Grep',
+        description: 'Search file contents by regex. Default output: file paths. output_mode "content" returns matching lines. Skips node_modules/.git/dist.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Regex pattern' },
+                path: { type: 'string', description: 'File or dir to search (default: cwd)' },
+                glob: { type: 'string', description: 'File filter e.g. "*.ts"' },
+                output_mode: { type: 'string', description: '"content" | "files_with_matches" | "count". Default: files_with_matches' },
+                context: { type: 'number', description: 'Context lines around match' },
+                before_context: { type: 'number', description: 'Lines before match' },
+                after_context: { type: 'number', description: 'Lines after match' },
+                case_insensitive: { type: 'boolean' },
+                head_limit: { type: 'number', description: 'Max results (default 250)' },
+                multiline: { type: 'boolean', description: 'Match across lines' },
+            },
+            required: ['pattern'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/imagegen.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Image Generation capability — generate images via BlockRun API.
+ * Uses x402 payment on Solana or Base.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const imageGenCapability: CapabilityHandler;