@axplusb/kepler 0.0.1 → 1.0.0

package/src/tools/enter-worktree.mjs

@@ -0,0 +1,69 @@
+/**
+ * EnterWorktree Tool — create and enter a git worktree for isolation.
+ *
+ * Creates a temporary worktree branch so edits do not affect the main branch.
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+import os from 'os';
+
+export const EnterWorktreeTool = {
+    name: 'EnterWorktree',
+    description: 'Create a git worktree for isolated file editing.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            branch: {
+                type: 'string',
+                description: 'Branch name for the worktree (auto-generated if omitted)',
+            },
+            path: {
+                type: 'string',
+                description: 'Directory for the worktree (temp dir if omitted)',
+            },
+        },
+        required: [],
+    },
+
+    // Shared state for active worktree
+    _activeWorktree: null,
+
+    validateInput() { return []; },
+
+    async call(input) {
+        if (this._activeWorktree) {
+            return `Already in worktree at ${this._activeWorktree.path}. Use ExitWorktree first.`;
+        }
+
+        try {
+            // Verify we are in a git repo
+            execSync('git rev-parse --is-inside-work-tree', { encoding: 'utf-8' });
+        } catch {
+            return 'Error: not inside a git repository';
+        }
+
+        const branch = input.branch || `occ-worktree-${Date.now()}`;
+        const worktreePath = input.path || path.join(os.tmpdir(), `occ-wt-${Date.now()}`);
+        const originalCwd = process.cwd();
+
+        try {
+            execSync(`git worktree add -b "${branch}" "${worktreePath}"`, {
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            });
+
+            this._activeWorktree = {
+                path: worktreePath,
+                branch,
+                originalCwd,
+            };
+
+            process.chdir(worktreePath);
+
+            return `Entered worktree:\n  Branch: ${branch}\n  Path: ${worktreePath}\n  Original: ${originalCwd}`;
+        } catch (err) {
+            return `Error creating worktree: ${err.message}`;
+        }
+    },
+};

package/src/tools/exit-worktree.mjs

@@ -0,0 +1,57 @@
+/**
+ * ExitWorktree Tool — exit and clean up a git worktree.
+ */
+
+import { execSync } from 'child_process';
+
+export const ExitWorktreeTool = {
+    name: 'ExitWorktree',
+    description: 'Exit the current git worktree and return to the original directory.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            cleanup: {
+                type: 'boolean',
+                description: 'Remove the worktree branch after exiting (default: true)',
+            },
+        },
+        required: [],
+    },
+
+    validateInput() { return []; },
+
+    async call(input) {
+        const { EnterWorktreeTool } = await import('./enter-worktree.mjs');
+        const wt = EnterWorktreeTool._activeWorktree;
+
+        if (!wt) {
+            return 'Not currently in a worktree.';
+        }
+
+        const cleanup = input.cleanup !== false;
+
+        try {
+            process.chdir(wt.originalCwd);
+
+            if (cleanup) {
+                try {
+                    execSync(`git worktree remove "${wt.path}" --force`, {
+                        encoding: 'utf-8',
+                        stdio: 'pipe',
+                    });
+                    execSync(`git branch -D "${wt.branch}"`, {
+                        encoding: 'utf-8',
+                        stdio: 'pipe',
+                    });
+                } catch {
+                    // Best effort cleanup
+                }
+            }
+
+            EnterWorktreeTool._activeWorktree = null;
+            return `Exited worktree. Returned to ${wt.originalCwd}${cleanup ? ' (cleaned up)' : ''}`;
+        } catch (err) {
+            return `Error exiting worktree: ${err.message}`;
+        }
+    },
+};

package/src/tools/glob.mjs

@@ -0,0 +1,117 @@
+/**
+ * Glob Tool — matches Claude Code's exact behavior.
+ *
+ * Features:
+ * - Proper glob matching (not shell find)
+ * - Sort by modification time
+ * - path parameter for directory scoping
+ */
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Minimal glob implementation without external dependencies.
+ * Supports *, **, and ? wildcards.
+ */
+function globMatch(pattern, str) {
+    const regex = globToRegex(pattern);
+    return regex.test(str);
+}
+
+function globToRegex(pattern) {
+    let regex = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            if (pattern[i + 1] === '*') {
+                // ** matches everything including /
+                regex += '.*';
+                i += 2;
+                if (pattern[i] === '/') i++; // skip trailing /
+                continue;
+            }
+            regex += '[^/]*';
+        } else if (ch === '?') {
+            regex += '[^/]';
+        } else if (ch === '.') {
+            regex += '\\.';
+        } else if (ch === '{') {
+            regex += '(';
+        } else if (ch === '}') {
+            regex += ')';
+        } else if (ch === ',') {
+            regex += '|';
+        } else {
+            regex += ch;
+        }
+        i++;
+    }
+    return new RegExp('^' + regex + '$');
+}
+
+function walkDir(dir, maxDepth = 20, depth = 0) {
+    const results = [];
+    if (depth > maxDepth) return results;
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            // Skip hidden dirs and node_modules
+            if (entry.name.startsWith('.') && depth > 0) continue;
+            if (entry.name === 'node_modules') continue;
+
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                results.push(...walkDir(full, maxDepth, depth + 1));
+            } else {
+                results.push(full);
+            }
+        }
+    } catch {
+        // Permission denied or other error
+    }
+    return results;
+}
+
+export const GlobTool = {
+    name: 'Glob',
+    description: 'Find files matching a glob pattern, sorted by modification time.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Glob pattern (e.g. "**/*.js")' },
+            path: { type: 'string', description: 'Directory to search in' },
+        },
+        required: ['pattern'],
+    },
+    validateInput(input) { return input.pattern ? [] : ['pattern required']; },
+    async call(input) {
+        try {
+            const baseDir = path.resolve(input.path || '.');
+            if (!fs.existsSync(baseDir)) {
+                return `Error: Directory not found: ${baseDir}`;
+            }
+
+            const allFiles = walkDir(baseDir);
+
+            // Match against pattern
+            const matches = allFiles.filter(f => {
+                const rel = path.relative(baseDir, f);
+                return globMatch(input.pattern, rel) || globMatch(input.pattern, path.basename(f));
+            });
+
+            if (matches.length === 0) return 'No matches found.';
+
+            // Sort by modification time (newest first)
+            matches.sort((a, b) => {
+                try {
+                    return fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs;
+                } catch { return 0; }
+            });
+
+            return matches.join('\n');
+        } catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+};

package/src/tools/grep.mjs

@@ -0,0 +1,129 @@
+/**
+ * Grep Tool — matches Claude Code's exact behavior.
+ *
+ * Features:
+ * - Case insensitive (-i)
+ * - Line numbers (-n, default true for content mode)
+ * - Context lines (-A, -B, -C)
+ * - output_mode: content, files_with_matches, count
+ * - glob filter and type filter
+ * - head_limit (default 250)
+ * - multiline mode
+ */
+import { spawnSync } from 'child_process';
+import path from 'path';
+
+export const GrepTool = {
+    name: 'Grep',
+    description: 'Search file contents with regex (powered by ripgrep or grep).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Regex pattern to search for' },
+            path: { type: 'string', description: 'File or directory to search in' },
+            '-i': { type: 'boolean', description: 'Case insensitive' },
+            '-n': { type: 'boolean', description: 'Show line numbers (default true)' },
+            '-A': { type: 'number', description: 'Lines after match' },
+            '-B': { type: 'number', description: 'Lines before match' },
+            '-C': { type: 'number', description: 'Context lines (before and after)' },
+            context: { type: 'number', description: 'Alias for -C' },
+            output_mode: {
+                type: 'string',
+                enum: ['content', 'files_with_matches', 'count'],
+                description: 'Output mode (default: files_with_matches)',
+            },
+            glob: { type: 'string', description: 'Glob pattern to filter files' },
+            type: { type: 'string', description: 'File type filter (e.g. js, py)' },
+            head_limit: { type: 'number', description: 'Max output lines (default 250)' },
+            multiline: { type: 'boolean', description: 'Enable multiline matching' },
+        },
+        required: ['pattern'],
+    },
+    validateInput(input) { return input.pattern ? [] : ['pattern required']; },
+    async call(input) {
+        try {
+            const dir = path.resolve(input.path || '.');
+            const mode = input.output_mode || 'files_with_matches';
+            const limit = input.head_limit ?? 250;
+
+            // Pass regex and paths as process arguments. Joining these into a
+            // shell command would turn regex operators such as | into pipelines.
+            const args = [];
+            const useRg = hasRipgrep();
+            const command = useRg ? 'rg' : 'grep';
+
+            if (useRg) {
+                if (input['-i']) args.push('-i');
+                if (input.multiline) args.push('-U', '--multiline-dotall');
+
+                if (mode === 'files_with_matches') {
+                    args.push('-l');
+                } else if (mode === 'count') {
+                    args.push('-c');
+                } else {
+                    // content mode
+                    const showLineNumbers = input['-n'] !== false;
+                    if (showLineNumbers) args.push('-n');
+                }
+
+                const ctx = input['-C'] || input.context;
+                if (ctx && mode === 'content') args.push('-C', String(ctx));
+                if (input['-A'] && mode === 'content') args.push('-A', String(input['-A']));
+                if (input['-B'] && mode === 'content') args.push('-B', String(input['-B']));
+
+                if (input.glob) args.push('--glob', input.glob);
+                if (input.type) args.push('--type', input.type);
+
+                args.push('--', input.pattern, dir);
+            } else {
+                args.push('-r');
+                if (input['-i']) args.push('-i');
+
+                if (mode === 'files_with_matches') {
+                    args.push('-l');
+                } else if (mode === 'count') {
+                    args.push('-c');
+                } else {
+                    if (input['-n'] !== false) args.push('-n');
+                }
+
+                const ctx = input['-C'] || input.context;
+                if (ctx && mode === 'content') args.push('-C', String(ctx));
+                if (input['-A'] && mode === 'content') args.push('-A', String(input['-A']));
+                if (input['-B'] && mode === 'content') args.push('-B', String(input['-B']));
+
+                if (input.glob) args.push('--include', input.glob);
+
+                args.push('--', input.pattern, dir);
+            }
+
+            const result = spawnSync(command, args, {
+                encoding: 'utf-8',
+                maxBuffer: 10 * 1024 * 1024,
+                timeout: 30000,
+            });
+
+            if (result.error || (result.status !== 0 && result.status !== 1)) {
+                return 'No matches found.';
+            }
+
+            const output = (result.stdout || '').trim();
+            if (!output) return 'No matches found.';
+            if (limit <= 0) return output;
+            return output.split('\n').slice(0, limit).join('\n');
+        } catch {
+            return 'No matches found.';
+        }
+    },
+};
+
+let _hasRg = null;
+function hasRipgrep() {
+    if (_hasRg !== null) return _hasRg;
+    const result = spawnSync('rg', ['--version'], {
+        encoding: 'utf-8',
+        timeout: 5000,
+    });
+    _hasRg = !result.error && result.status === 0;
+    return _hasRg;
+}

package/src/tools/lint.mjs

@@ -0,0 +1,71 @@
+/**
+ * Lint Tool — run linters and type checkers.
+ *
+ * Always safe: read-only, no side effects (unless --fix).
+ * Agent should use this instead of shell("ruff check .").
+ *
+ * Execution: direct on host (no sandbox needed for read-only).
+ * With --fix: routes through sandbox if available.
+ */
+
+import { BashTool } from './bash.mjs';
+
+const LINTERS = {
+    ruff:    { cmd: (p, fix) => `ruff check ${fix ? '--fix ' : ''}${p}`, lang: 'python' },
+    mypy:    { cmd: (p) => `mypy ${p} --no-error-summary`, lang: 'python' },
+    pyright: { cmd: (p) => `pyright ${p}`, lang: 'python' },
+    pylint:  { cmd: (p) => `pylint ${p} --output-format=text`, lang: 'python' },
+    eslint:  { cmd: (p, fix) => `eslint ${fix ? '--fix ' : ''}${p}`, lang: 'javascript' },
+    tsc:     { cmd: () => 'tsc --noEmit', lang: 'typescript' },
+    flake8:  { cmd: (p) => `flake8 ${p}`, lang: 'python' },
+    biome:   { cmd: (p, fix) => `biome check ${fix ? '--fix ' : ''}${p}`, lang: 'javascript' },
+};
+
+export const LintTool = {
+    name: 'Lint',
+    description: 'Run a linter or type checker. Fast, read-only (unless --fix). Use this instead of Bash for code checking.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            tool: {
+                type: 'string',
+                enum: Object.keys(LINTERS),
+                description: 'Which linter to run',
+            },
+            path: {
+                type: 'string',
+                description: 'File or directory to lint (default: ".")',
+                default: '.',
+            },
+            fix: {
+                type: 'boolean',
+                description: 'Apply auto-fixes (default: false)',
+                default: false,
+            },
+        },
+        required: ['tool'],
+    },
+    validateInput(input) {
+        const errors = [];
+        if (!input.tool) errors.push('tool is required');
+        if (input.tool && !LINTERS[input.tool]) errors.push(`Unknown linter: ${input.tool}. Supported: ${Object.keys(LINTERS).join(', ')}`);
+        return errors;
+    },
+    async call(input) {
+        const linter = LINTERS[input.tool];
+        if (!linter) return `Unknown linter: ${input.tool}`;
+
+        const targetPath = input.path || '.';
+        const command = linter.cmd(targetPath, input.fix);
+
+        const result = await BashTool.call({
+            command,
+            timeout: 30000, // linters should be fast
+            description: `Lint: ${input.tool} ${targetPath}`,
+        });
+
+        return result;
+    },
+    // Metadata for execution policy
+    _executionPolicy: 'direct', // no sandbox for read-only; 'contained' if fix=true
+};

package/src/tools/ls.mjs

@@ -0,0 +1,58 @@
+/**
+ * LS Tool — directory listing with metadata.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export const LsTool = {
+    name: 'LS',
+    description: 'List directory contents with file sizes and types.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Directory path to list (default: cwd)' },
+            all: { type: 'boolean', description: 'Include hidden files (default: false)' },
+        },
+        required: [],
+    },
+
+    validateInput() { return []; },
+
+    async call(input) {
+        const dirPath = path.resolve(input.path || '.');
+
+        try {
+            const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+            const results = [];
+
+            for (const entry of entries) {
+                if (!input.all && entry.name.startsWith('.')) continue;
+
+                const fullPath = path.join(dirPath, entry.name);
+                let size = '';
+                try {
+                    const stat = fs.statSync(fullPath);
+                    size = entry.isDirectory() ? '' : formatSize(stat.size);
+                } catch {
+                    size = '?';
+                }
+
+                const type = entry.isDirectory() ? 'd' : entry.isSymbolicLink() ? 'l' : '-';
+                results.push(`${type} ${size.padStart(8)} ${entry.name}${entry.isDirectory() ? '/' : ''}`);
+            }
+
+            if (results.length === 0) return 'Empty directory';
+            return `${dirPath}:\n${results.join('\n')}`;
+        } catch (err) {
+            return `Error: ${err.message}`;
+        }
+    },
+};
+
+function formatSize(bytes) {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+    if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}G`;
+}

package/src/tools/lsp.mjs

@@ -0,0 +1,115 @@
+/**
+ * LSP Tool — Language Server Protocol integration stub.
+ *
+ * Provides a tool interface for language server features:
+ * - diagnostics (errors/warnings)
+ * - completions
+ * - hover information
+ * - go-to-definition
+ * - references
+ *
+ * This is a stub implementation. Full LSP would spawn an actual language
+ * server process and communicate via JSON-RPC.
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+
+export const LspTool = {
+    name: 'LSP',
+    description: 'Query language server for diagnostics, completions, hover, and definitions.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['diagnostics', 'completions', 'hover', 'definition', 'references'],
+                description: 'LSP action to perform',
+            },
+            file: {
+                type: 'string',
+                description: 'File path to query',
+            },
+            line: {
+                type: 'number',
+                description: 'Line number (0-based)',
+            },
+            character: {
+                type: 'number',
+                description: 'Character position (0-based)',
+            },
+            language: {
+                type: 'string',
+                description: 'Language ID (e.g., "typescript", "python")',
+            },
+        },
+        required: ['action', 'file'],
+    },
+
+    validateInput(input) {
+        const errors = [];
+        if (!input.action) errors.push('action is required');
+        if (!input.file) errors.push('file is required');
+        return errors;
+    },
+
+    async call(input) {
+        const filePath = path.resolve(input.file);
+        const action = input.action;
+
+        switch (action) {
+            case 'diagnostics':
+                return getDiagnostics(filePath, input.language);
+            case 'completions':
+                return `[LSP stub] Completions at ${filePath}:${input.line}:${input.character} not yet implemented.`;
+            case 'hover':
+                return `[LSP stub] Hover at ${filePath}:${input.line}:${input.character} not yet implemented.`;
+            case 'definition':
+                return `[LSP stub] Go-to-definition at ${filePath}:${input.line}:${input.character} not yet implemented.`;
+            case 'references':
+                return `[LSP stub] Find references at ${filePath}:${input.line}:${input.character} not yet implemented.`;
+            default:
+                return `Unknown LSP action: ${action}`;
+        }
+    },
+};
+
+function getDiagnostics(filePath, language) {
+    const ext = path.extname(filePath);
+    const lang = language || extToLanguage(ext);
+
+    try {
+        switch (lang) {
+            case 'typescript':
+            case 'javascript': {
+                const result = execSync(
+                    `npx tsc --noEmit --pretty false "${filePath}" 2>&1 || true`,
+                    { encoding: 'utf-8', timeout: 15000 }
+                );
+                return result.trim() || 'No diagnostics.';
+            }
+            case 'python': {
+                const result = execSync(
+                    `python3 -m py_compile "${filePath}" 2>&1 || true`,
+                    { encoding: 'utf-8', timeout: 10000 }
+                );
+                return result.trim() || 'No diagnostics.';
+            }
+            default:
+                return `[LSP stub] No diagnostic provider for language: ${lang}`;
+        }
+    } catch (err) {
+        return `Diagnostics error: ${err.message}`;
+    }
+}
+
+function extToLanguage(ext) {
+    const map = {
+        '.ts': 'typescript', '.tsx': 'typescript',
+        '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript',
+        '.py': 'python',
+        '.rs': 'rust', '.go': 'go', '.java': 'java',
+        '.rb': 'ruby', '.php': 'php', '.cs': 'csharp',
+    };
+    return map[ext] || 'unknown';
+}