joonecli 0.1.0

package/dist/tools/index.js

@@ -0,0 +1,184 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ─── Configuration ──────────────────────────────────────────────────────────────
+/** Maximum file size (in bytes) the agent is allowed to read into context. */
+const MAX_FILE_SIZE_BYTES = 512 * 1024; // 512 KB
+/** Maximum number of lines to return if file exceeds line limit. */
+const MAX_FILE_LINES = 2000;
+// ─── Sandbox reference (set at session start) ───────────────────────────────────
+let _sandboxManager = null;
+let _fileSync = null;
+/**
+ * Binds the tools to a SandboxManager and FileSync instance.
+ * Must be called at session start before any tool executions.
+ */
+export function bindSandbox(sandbox, fileSync) {
+    _sandboxManager = sandbox;
+    _fileSync = fileSync;
+}
+/**
+ * Security: Validates that a resolved path is strictly inside the given workspace dir.
+ * Prevents directory traversal attacks from accessing sensitive host files.
+ */
+export function isPathInsideWorkspace(resolvedPath, workspaceDir = process.cwd()) {
+    const normalizedWorkspace = path.resolve(workspaceDir);
+    // path.relative returns a path relative to the first argument.
+    // If it starts with '..' or is absolute, it means resolvedPath has escaped normalizedWorkspace.
+    const relative = path.relative(normalizedWorkspace, resolvedPath);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+// ─── BashTool ───────────────────────────────────────────────────────────────────
+// Executes shell commands inside the E2B sandbox.
+// The ToolRouter routes this to SANDBOX — the host machine is never exposed.
+export const BashTool = {
+    name: "bash",
+    description: "Runs a shell command inside an isolated sandbox. Use for tests, scripts, or installing dependencies. The host machine is never exposed.",
+    schema: {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                description: "The shell command to execute",
+            },
+        },
+        required: ["command"],
+    },
+    execute: async (args) => {
+        if (!_sandboxManager || !_sandboxManager.isActive()) {
+            throw new Error("Sandbox is not active. Cannot execute bash commands without an active sandbox session.");
+        }
+        // Sync any dirty files from host → sandbox before executing
+        if (_fileSync && _fileSync.pendingCount() > 0) {
+            await _fileSync.syncToSandbox(_sandboxManager);
+        }
+        const result = await _sandboxManager.exec(args.command);
+        if (result.exitCode !== 0) {
+            return {
+                content: `Command failed (exit code ${result.exitCode}):\nSTDOUT:\n${result.stdout}\nSTDERR:\n${result.stderr}`,
+                metadata: { exitCode: result.exitCode },
+                isError: true
+            };
+        }
+        return {
+            content: result.stdout || "(no output)",
+            metadata: { exitCode: result.exitCode },
+            isError: false
+        };
+    },
+};
+// ─── ReadFileTool ───────────────────────────────────────────────────────────────
+// Reads files from the HOST filesystem (so the user's real project is visible).
+// Includes a built-in file size guardrail to prevent sending huge files to the LLM.
+export const ReadFileTool = {
+    name: "read_file",
+    description: "Reads a file from the host filesystem. Includes a file size guardrail — files over 512KB are truncated to prevent context overflow.",
+    schema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute or relative path to the file",
+            },
+            startLine: {
+                type: "number",
+                description: "Optional 1-indexed start line for partial reads",
+            },
+            endLine: {
+                type: "number",
+                description: "Optional 1-indexed end line for partial reads",
+            },
+        },
+        required: ["path"],
+    },
+    execute: async (args) => {
+        const filePath = path.resolve(args.path);
+        // ── Security Guardrail ──
+        if (!isPathInsideWorkspace(filePath)) {
+            return {
+                content: `Security Error: Access Denied. Cannot read files outside the current project workspace (${process.cwd()}).`,
+                isError: true
+            };
+        }
+        // ── Check existence ──
+        if (!fs.existsSync(filePath)) {
+            return {
+                content: `Error: File not found — ${filePath}`,
+                isError: true
+            };
+        }
+        // ── File Size Guardrail ──
+        const stat = fs.statSync(filePath);
+        if (stat.size > MAX_FILE_SIZE_BYTES) {
+            return {
+                content: `Error: File too large (${Math.round(stat.size / 1024)}KB). Maximum size is 512KB. Use line ranges or grep_search.`,
+                isError: true
+            };
+        }
+        const fileContent = fs.readFileSync(filePath, "utf-8");
+        const lines = fileContent.split("\n");
+        if (args.startLine !== undefined || args.endLine !== undefined) {
+            const start = Math.max(1, args.startLine ?? 1) - 1;
+            const end = Math.min(lines.length, args.endLine ?? lines.length);
+            const sliced = lines.slice(start, end);
+            return { content: sliced.map((line, i) => `${start + i + 1}: ${line}`).join("\n") };
+        }
+        // ── Line count guardrail ──
+        if (lines.length > MAX_FILE_LINES) {
+            const truncated = lines.slice(0, MAX_FILE_LINES);
+            return {
+                content: truncated.map((line, i) => `${i + 1}: ${line}`).join("\n") +
+                    `\n\n--- Truncated at ${MAX_FILE_LINES} lines (total: ${lines.length}) ---`
+            };
+        }
+        return { content: fileContent };
+    },
+};
+// ─── WriteFileTool ──────────────────────────────────────────────────────────────
+// Writes files to the HOST filesystem (so the user sees changes in their IDE).
+// Marks written files as dirty so FileSync uploads them before sandbox execution.
+export const WriteFileTool = {
+    name: "write_file",
+    description: "Writes content to a file on the host filesystem. The user will see changes in their IDE immediately. The file is automatically synced to the sandbox before the next command execution.",
+    schema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute or relative path to the file",
+            },
+            content: {
+                type: "string",
+                description: "The full file content to write",
+            },
+        },
+        required: ["path", "content"],
+    },
+    execute: async (args) => {
+        const filePath = path.resolve(args.path);
+        // ── Security Guardrail ──
+        if (!isPathInsideWorkspace(filePath)) {
+            return {
+                content: `Security Error: Access Denied. Cannot write files outside the current project workspace (${process.cwd()}).`,
+                isError: true
+            };
+        }
+        // Create parent directories if needed
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, args.content, "utf-8");
+        // Mark file as dirty for next sandbox sync
+        if (_fileSync) {
+            _fileSync.markDirty(filePath);
+        }
+        return { content: `File written: ${filePath}` };
+    },
+};
+// ─── Core Tool Set ──────────────────────────────────────────────────────────────
+export const CORE_TOOLS = [
+    BashTool,
+    ReadFileTool,
+    WriteFileTool,
+];
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,31 @@
+import { DynamicToolInterface } from "./index.js";
+/**
+ * Lazy Tool Registry
+ *
+ * Instead of loading all complex tools into the System Prompt (which burns tokens
+ * and risks cache invalidation if changed), this registry maintains "stubs" —
+ * lightweight descriptors that let the agent discover tools on demand.
+ *
+ * Tools in DeferredToolsDB are NOT sent to the LLM by default. The agent can
+ * search for them via SearchToolsTool, then activate them via ActivateToolTool.
+ */
+export declare const DeferredToolsDB: Record<string, DynamicToolInterface>;
+/**
+ * Returns a tool that has been dynamically activated.
+ */
+export declare function getActivatedTool(name: string): DynamicToolInterface | undefined;
+/**
+ * Returns all currently activated tools.
+ */
+export declare function getActivatedTools(): DynamicToolInterface[];
+/**
+ * Activates a tool from the deferred registry, making it available for execution.
+ * Returns the activated tool, or undefined if not found.
+ */
+export declare function activateTool(name: string): DynamicToolInterface | undefined;
+/**
+ * Resets all activated tools. For testing.
+ */
+export declare function resetActivatedTools(): void;
+export declare const SearchToolsTool: DynamicToolInterface;
+export declare const ActivateToolTool: DynamicToolInterface;

package/dist/tools/registry.js

@@ -0,0 +1,168 @@
+/**
+ * Lazy Tool Registry
+ *
+ * Instead of loading all complex tools into the System Prompt (which burns tokens
+ * and risks cache invalidation if changed), this registry maintains "stubs" —
+ * lightweight descriptors that let the agent discover tools on demand.
+ *
+ * Tools in DeferredToolsDB are NOT sent to the LLM by default. The agent can
+ * search for them via SearchToolsTool, then activate them via ActivateToolTool.
+ */
+// ─── Deferred (Lazy) Tools ─────────────────────────────────────────────────────
+export const DeferredToolsDB = {
+    git_commit: {
+        name: "git_commit",
+        description: "Creates a new git commit with staged changes.",
+        schema: {
+            type: "object",
+            properties: { message: { type: "string" } },
+            required: ["message"],
+        },
+        execute: async (args) => ({ content: `Committed with message: ${args.message}` }),
+    },
+    git_diff: {
+        name: "git_diff",
+        description: "Shows the diff of uncommitted changes or between two branches/commits.",
+        schema: {
+            type: "object",
+            properties: {
+                target: {
+                    type: "string",
+                    description: "Branch, commit, or file path (optional)",
+                },
+            },
+        },
+        execute: async (args) => ({ content: `Diff for: ${args.target || "working directory"}` }),
+    },
+    git_log: {
+        name: "git_log",
+        description: "Shows recent commit history with messages and hashes.",
+        schema: {
+            type: "object",
+            properties: {
+                count: {
+                    type: "number",
+                    description: "Number of recent commits to show (default: 10)",
+                },
+            },
+        },
+        execute: async (args) => ({ content: `Showing last ${args.count || 10} commits.` }),
+    },
+    grep_search: {
+        name: "grep_search",
+        description: "Searches for a text pattern across project files using ripgrep. Returns matching lines with filenames and line numbers.",
+        schema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search pattern (regex supported)" },
+                path: { type: "string", description: "Directory or file to search in (default: .)" },
+                includes: { type: "string", description: "File glob filter (e.g., '*.ts')" },
+            },
+            required: ["query"],
+        },
+        execute: async (args) => ({ content: `Search results for '${args.query}'` }),
+    },
+    list_dir: {
+        name: "list_dir",
+        description: "Lists the contents of a directory — files and subdirectories with sizes.",
+        schema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Directory path to list" },
+            },
+            required: ["path"],
+        },
+        execute: async (args) => ({ content: `Directory listing for: ${args.path}` }),
+    },
+};
+// ─── Active Tool Set (starts empty, filled by ActivateToolTool) ─────────────
+const activatedTools = new Map();
+/**
+ * Returns a tool that has been dynamically activated.
+ */
+export function getActivatedTool(name) {
+    return activatedTools.get(name);
+}
+/**
+ * Returns all currently activated tools.
+ */
+export function getActivatedTools() {
+    return Array.from(activatedTools.values());
+}
+/**
+ * Activates a tool from the deferred registry, making it available for execution.
+ * Returns the activated tool, or undefined if not found.
+ */
+export function activateTool(name) {
+    const tool = DeferredToolsDB[name];
+    if (!tool)
+        return undefined;
+    activatedTools.set(name, tool);
+    return tool;
+}
+/**
+ * Resets all activated tools. For testing.
+ */
+export function resetActivatedTools() {
+    activatedTools.clear();
+}
+// ─── SearchToolsTool ────────────────────────────────────────────────────────────
+/**
+ * Fuzzy search: matches on tool name OR any word in the description.
+ */
+function fuzzyMatch(query, tool) {
+    const q = query.toLowerCase();
+    const nameMatch = tool.name.toLowerCase().includes(q);
+    const descWords = tool.description.toLowerCase();
+    const descMatch = descWords.includes(q);
+    return nameMatch || descMatch;
+}
+export const SearchToolsTool = {
+    name: "search_tools",
+    description: "Search for advanced tools available in the environment. Matches by tool name or description keywords.",
+    schema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "Search query" },
+        },
+        required: ["query"],
+    },
+    execute: async (args) => {
+        const matches = Object.values(DeferredToolsDB).filter((tool) => fuzzyMatch(args.query, tool));
+        if (matches.length === 0) {
+            return { content: `No tools found matching '${args.query}'. Available categories: git, file, search.` };
+        }
+        const descriptions = matches.map((t) => `- **${t.name}**: ${t.description}`);
+        return {
+            content: `Found ${matches.length} tool(s):\n${descriptions.join("\n")}\n\n` +
+                `To use a tool, call activate_tool with its name.`
+        };
+    },
+};
+// ─── ActivateToolTool ───────────────────────────────────────────────────────────
+export const ActivateToolTool = {
+    name: "activate_tool",
+    description: "Activates a discovered tool for use. Call search_tools first to find available tools.",
+    schema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "The tool name to activate" },
+        },
+        required: ["name"],
+    },
+    execute: async (args) => {
+        const tool = activateTool(args.name);
+        if (!tool) {
+            return {
+                content: `Error: Tool '${args.name}' not found in the registry. Use search_tools to see available tools.`,
+                isError: true
+            };
+        }
+        return {
+            content: `✓ Tool '${args.name}' activated.\n` +
+                `Schema: ${JSON.stringify(tool.schema, null, 2)}\n` +
+                `You can now call it directly.`
+        };
+    },
+};
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}

package/dist/tools/router.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a tool executes — on the host machine or in the sandbox.
+ */
+export declare enum ToolTarget {
+    /** Run on the host (Node.js process). User sees changes in IDE. */
+    HOST = "host",
+    /** Run inside the E2B sandbox. Commands are isolated. */
+    SANDBOX = "sandbox"
+}
+/**
+ * Routes tool calls to either the host machine or the E2B sandbox.
+ *
+ * Design principle: File I/O runs on the host so the user sees changes
+ * in their IDE in real-time. Code execution runs in the sandbox for safety.
+ *
+ * Unknown tools default to SANDBOX (safe-by-default).
+ */
+export declare class ToolRouter {
+    /**
+     * Determines where a tool should execute.
+     *
+     * @param toolName The name of the tool being invoked.
+     * @returns ToolTarget.HOST or ToolTarget.SANDBOX
+     */
+    getTarget(toolName: string): ToolTarget;
+    /**
+     * Returns true if the tool should run on the host.
+     */
+    isHostTool(toolName: string): boolean;
+    /**
+     * Returns true if the tool should run in the sandbox.
+     */
+    isSandboxTool(toolName: string): boolean;
+}

package/dist/tools/router.js

@@ -0,0 +1,73 @@
+/**
+ * Where a tool executes — on the host machine or in the sandbox.
+ */
+export var ToolTarget;
+(function (ToolTarget) {
+    /** Run on the host (Node.js process). User sees changes in IDE. */
+    ToolTarget["HOST"] = "host";
+    /** Run inside the E2B sandbox. Commands are isolated. */
+    ToolTarget["SANDBOX"] = "sandbox";
+})(ToolTarget || (ToolTarget = {}));
+/**
+ * Tools that execute on the host machine (no code execution risk).
+ */
+const HOST_TOOLS = new Set([
+    "write_file",
+    "read_file",
+    "search_tools",
+    "activate_tool",
+    "list_files",
+    "search_files",
+    "web_search",
+    "search_skills",
+    "load_skill",
+]);
+/**
+ * Tools that execute inside the sandboxed environment.
+ */
+const SANDBOX_TOOLS = new Set([
+    "bash",
+    "run_tests",
+    "install_deps",
+    "run_command",
+    "python",
+    "security_scan",
+    "dep_scan",
+    "browser",
+]);
+/**
+ * Routes tool calls to either the host machine or the E2B sandbox.
+ *
+ * Design principle: File I/O runs on the host so the user sees changes
+ * in their IDE in real-time. Code execution runs in the sandbox for safety.
+ *
+ * Unknown tools default to SANDBOX (safe-by-default).
+ */
+export class ToolRouter {
+    /**
+     * Determines where a tool should execute.
+     *
+     * @param toolName The name of the tool being invoked.
+     * @returns ToolTarget.HOST or ToolTarget.SANDBOX
+     */
+    getTarget(toolName) {
+        if (HOST_TOOLS.has(toolName)) {
+            return ToolTarget.HOST;
+        }
+        // Default: sandbox (safe-by-default — never execute unknown tools on host)
+        return ToolTarget.SANDBOX;
+    }
+    /**
+     * Returns true if the tool should run on the host.
+     */
+    isHostTool(toolName) {
+        return this.getTarget(toolName) === ToolTarget.HOST;
+    }
+    /**
+     * Returns true if the tool should run in the sandbox.
+     */
+    isSandboxTool(toolName) {
+        return this.getTarget(toolName) === ToolTarget.SANDBOX;
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/tools/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/tools/router.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IACpB,mEAAmE;IACnE,2BAAa,CAAA;IACb,yDAAyD;IACzD,iCAAmB,CAAA;AACrB,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB;AAED;;GAEG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,YAAY;IACZ,WAAW;IACX,cAAc;IACd,eAAe;IACf,YAAY;IACZ,cAAc;IACd,YAAY;IACZ,eAAe;IACf,YAAY;CACb,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,MAAM;IACN,WAAW;IACX,cAAc;IACd,aAAa;IACb,QAAQ;IACR,eAAe;IACf,UAAU;IACV,SAAS;CACV,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACrB;;;;;OAKG;IACH,SAAS,CAAC,QAAgB;QACxB,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,OAAO,UAAU,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,2EAA2E;QAC3E,OAAO,UAAU,CAAC,OAAO,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,QAAgB;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB;QAC5B,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,UAAU,CAAC,OAAO,CAAC;IACzD,CAAC;CACF"}

package/dist/tools/security.d.ts

@@ -0,0 +1,28 @@
+import { SandboxManager } from "../sandbox/manager.js";
+import { LazyInstaller } from "../sandbox/bootstrap.js";
+import { DynamicToolInterface } from "./index.js";
+/**
+ * Binds the security tools to the sandbox and installer.
+ * Must be called at session start.
+ */
+export declare function bindSecuritySandbox(sandbox: SandboxManager, installer: LazyInstaller): void;
+/**
+ * Scans code for security vulnerabilities using the Gemini CLI Security Extension.
+ *
+ * Execution flow:
+ * 1. LazyInstaller ensures Gemini CLI + security extension are in the sandbox.
+ * 2. Runs `gemini -x security:analyze` in the sandbox.
+ * 3. Returns the generated security report.
+ *
+ * If Gemini CLI installation fails, returns a descriptive fallback message
+ * suggesting manual review or alternative tools.
+ */
+export declare const SecurityScanTool: DynamicToolInterface;
+/**
+ * Scans project dependencies for known vulnerabilities.
+ *
+ * Execution flow:
+ * 1. Try OSV-Scanner (more comprehensive, covers multiple ecosystems).
+ * 2. Fall back to `npm audit --json` (always available in Node sandboxes).
+ */
+export declare const DepScanTool: DynamicToolInterface;