@sean.holung/minicode 0.1.0

package/dist/src/tools/find-references.js

@@ -0,0 +1,52 @@
+import { expectNonEmptyString, expectOptionalNumber, } from "./helpers.js";
+const DEFAULT_LIMIT = 50;
+export function createFindReferencesTool(projectIndex) {
+    return {
+        name: "find_references",
+        description: "Find all symbols that reference or call a given symbol. Use to understand impact before changes. Prefer over search when you know the symbol name.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Symbol name or qualified name to find references for.",
+                },
+                skip: {
+                    type: "number",
+                    description: "Number of results to skip (for pagination). Default 0.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max number of results to return. Default 50.",
+                },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            const name = expectNonEmptyString(input, "name");
+            const skip = Math.max(0, expectOptionalNumber(input, "skip") ?? 0);
+            const limit = Math.max(1, Math.min(100, expectOptionalNumber(input, "limit") ?? DEFAULT_LIMIT));
+            const symbol = projectIndex.getSymbol(name);
+            if (!symbol) {
+                return `Symbol "${name}" not found in the project index.`;
+            }
+            const refs = projectIndex.dependencyEdges.filter((e) => e.to === symbol.qualifiedName || e.to === symbol.name);
+            if (refs.length === 0) {
+                return `No references found for "${name}".`;
+            }
+            const shown = refs.slice(skip, skip + limit);
+            const lines = shown.map((e) => `- ${e.from} (${e.kind})`);
+            const remaining = refs.length - skip - shown.length;
+            const footer = remaining > 0
+                ? `\n... and ${remaining} more (use skip: ${skip + limit}, limit: ${limit} for next page)`
+                : "";
+            return [
+                `# References to ${symbol.qualifiedName} (${refs.length} total)`,
+                "",
+                ...lines,
+                footer,
+            ].join("\n");
+        },
+    };
+}

package/dist/src/tools/get-dependencies.js

@@ -0,0 +1,56 @@
+import { expectNonEmptyString, expectOptionalNumber } from "./helpers.js";
+export function createGetDependenciesTool(projectIndex) {
+    return {
+        name: "get_dependencies",
+        description: "Get the dependency cone of a symbol — everything it calls or depends on. Use to understand implementation and data flow. Prefer over reading full files.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Symbol name or qualified name.",
+                },
+                depth: {
+                    type: "number",
+                    description: "How many levels of dependencies to include. Default 1.",
+                },
+                skip: {
+                    type: "number",
+                    description: "Number of results to skip (for pagination). Default 0.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max number of results to return. Default 50.",
+                },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            const name = expectNonEmptyString(input, "name");
+            const depth = expectOptionalNumber(input, "depth") ?? 1;
+            const skip = Math.max(0, expectOptionalNumber(input, "skip") ?? 0);
+            const limit = Math.max(1, Math.min(100, expectOptionalNumber(input, "limit") ?? 50));
+            const symbol = projectIndex.getSymbol(name);
+            if (!symbol) {
+                return `Symbol "${name}" not found in the project index.`;
+            }
+            const cone = projectIndex.getDependencyCone(name, depth);
+            const shown = cone.slice(skip, skip + limit);
+            const lines = shown.map((s) => {
+                const header = `${s.kind} ${s.qualifiedName}`;
+                return `${header}\n  ${s.signature}`;
+            });
+            const remaining = cone.length - skip - shown.length;
+            const footer = remaining > 0
+                ? `\n\n... and ${remaining} more (use skip: ${skip + limit}, limit: ${limit} for next page)`
+                : "";
+            return [
+                `# Dependencies of ${symbol.qualifiedName} (depth ${depth}, ${cone.length} total)`,
+                "",
+                ...lines,
+                footer,
+            ].join("\n\n");
+        },
+    };
+}

package/dist/src/tools/helpers.js

@@ -0,0 +1,42 @@
+export function expectNonEmptyString(input, key) {
+    const value = input[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Input "${key}" must be a non-empty string.`);
+    }
+    return value;
+}
+export function expectOptionalBoolean(input, key) {
+    const value = input[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`Input "${key}" must be a boolean when provided.`);
+    }
+    return value;
+}
+export function expectOptionalNumber(input, key) {
+    const value = input[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`Input "${key}" must be a finite number when provided.`);
+    }
+    return value;
+}
+export function formatWithLineNumbers(text, startLine = 1, limit) {
+    const lines = text.split(/\r?\n/);
+    const beginIndex = Math.max(startLine - 1, 0);
+    const endIndex = limit === undefined
+        ? lines.length
+        : Math.min(lines.length, beginIndex + Math.max(limit, 0));
+    const output = [];
+    for (let index = beginIndex; index < endIndex; index += 1) {
+        output.push(`${index + 1}|${lines[index] ?? ""}`);
+    }
+    return output.join("\n");
+}
+export function toJson(input) {
+    return JSON.stringify(input);
+}

package/dist/src/tools/list-files.js

@@ -0,0 +1,63 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveWorkspacePath } from "../safety/guardrails.js";
+import { expectOptionalNumber } from "./helpers.js";
+const EXCLUDED_DIRS = new Set(["node_modules", ".git", ".minicode"]);
+const DEFAULT_LIMIT = 200;
+function parsePath(input) {
+    const value = input.path;
+    if (value === undefined) {
+        return ".";
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Input "path" must be a non-empty string when provided.`);
+    }
+    return value;
+}
+export function createListFilesTool(config) {
+    return {
+        name: "list_files",
+        description: "List files and directories at a path.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Optional path to list, relative to workspace root. Defaults to current workspace root.",
+                },
+                skip: {
+                    type: "number",
+                    description: "Number of entries to skip (for pagination). Default 0.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max number of entries to return. Default 200.",
+                },
+            },
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            const requestedPath = parsePath(input);
+            const skip = Math.max(0, expectOptionalNumber(input, "skip") ?? 0);
+            const limit = Math.max(1, Math.min(500, expectOptionalNumber(input, "limit") ?? DEFAULT_LIMIT));
+            const dirPath = resolveWorkspacePath(requestedPath, config.workspaceRoot);
+            const entries = await readdir(dirPath, { withFileTypes: true });
+            const filtered = entries.filter((entry) => !(entry.isDirectory() &&
+                EXCLUDED_DIRS.has(entry.name)));
+            const sorted = filtered.sort((a, b) => a.name.localeCompare(b.name));
+            const listed = sorted
+                .slice(skip, skip + limit)
+                .map((entry) => entry.isDirectory()
+                ? `[dir]  ${path.join(requestedPath, entry.name)}`
+                : `[file] ${path.join(requestedPath, entry.name)}`);
+            if (listed.length === 0) {
+                return `Directory "${requestedPath}" is empty.`;
+            }
+            const remaining = sorted.length - skip - listed.length;
+            const footer = remaining > 0
+                ? `\n... and ${remaining} more (use skip: ${skip + limit}, limit: ${limit} for next page)`
+                : "";
+            return listed.join("\n") + footer;
+        },
+    };
+}

package/dist/src/tools/read-file.js

@@ -0,0 +1,79 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolveWorkspacePath, validateFileReadSize, } from "../safety/guardrails.js";
+import { expectNonEmptyString, expectOptionalNumber, formatWithLineNumbers, } from "./helpers.js";
+function parseLineOffset(totalLines, rawOffset) {
+    if (rawOffset === undefined) {
+        return 1;
+    }
+    if (!Number.isInteger(rawOffset) || rawOffset === 0) {
+        throw new Error(`"offset" must be a non-zero integer when provided.`);
+    }
+    if (rawOffset > 0) {
+        return rawOffset;
+    }
+    return Math.max(1, totalLines + rawOffset + 1);
+}
+const DEFAULT_LINE_LIMIT = 500;
+function parseLimit(rawLimit, totalLines) {
+    if (rawLimit !== undefined) {
+        if (!Number.isInteger(rawLimit) || rawLimit < 0) {
+            throw new Error(`"limit" must be a non-negative integer when provided.`);
+        }
+        return rawLimit;
+    }
+    if (totalLines > DEFAULT_LINE_LIMIT) {
+        return DEFAULT_LINE_LIMIT;
+    }
+    return totalLines;
+}
+export function createReadFileTool(config) {
+    return {
+        name: "read_file",
+        description: "Read file contents with line numbers. Use for config files, non-code files, or when symbol name is unknown. For code files (.ts/.tsx/.js/.jsx), prefer read_symbol when the symbol is in the code map. For large files, use offset and limit.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to the file relative to the workspace root.",
+                },
+                offset: {
+                    type: "number",
+                    description: "Optional 1-based line number to start from. Negative numbers count from file end.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Optional maximum number of lines to return.",
+                },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            const requestedPath = expectNonEmptyString(input, "path");
+            const offset = expectOptionalNumber(input, "offset");
+            const limit = expectOptionalNumber(input, "limit");
+            const filePath = resolveWorkspacePath(requestedPath, config.workspaceRoot);
+            const fileStat = await stat(filePath);
+            if (!fileStat.isFile()) {
+                throw new Error(`"${requestedPath}" is not a file.`);
+            }
+            validateFileReadSize(fileStat.size, config.maxFileSizeBytes);
+            const content = await readFile(filePath, "utf8");
+            if (content.length === 0) {
+                return "File is empty.";
+            }
+            const lines = content.split(/\r?\n/);
+            const startLine = parseLineOffset(lines.length, offset);
+            const effectiveLimit = parseLimit(limit, lines.length);
+            const output = formatWithLineNumbers(content, startLine, effectiveLimit);
+            if (limit === undefined &&
+                lines.length > DEFAULT_LINE_LIMIT &&
+                effectiveLimit < lines.length) {
+                const remaining = Math.max(0, lines.length - (startLine - 1) - effectiveLimit);
+                return `${output}\n\n[... truncated, ${remaining} more lines. Use offset and limit to read specific sections.]`;
+            }
+            return output;
+        },
+    };
+}

package/dist/src/tools/read-symbol.js

@@ -0,0 +1,96 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolveWorkspacePath, validateFileReadSize, } from "../safety/guardrails.js";
+import { expectNonEmptyString, expectOptionalBoolean } from "./helpers.js";
+const LEADING_CONTEXT_LINES = 3;
+export function createReadSymbolTool(config, projectIndex) {
+    return {
+        name: "read_symbol",
+        description: "Read a specific function, class, or type definition by name. " +
+            "Returns the symbol's source code, referenced types, callers, and callees. " +
+            "PREFER this over read_file for .ts/.tsx/.js/.jsx — use the code map to find symbol names.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Symbol name or qualified name (e.g. 'parseResponse' or 'CodingAgent.runTurn').",
+                },
+                includeBody: {
+                    type: "boolean",
+                    description: "If false, return signature only. Defaults to true.",
+                },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            const name = expectNonEmptyString(input, "name");
+            const includeBody = expectOptionalBoolean(input, "includeBody") ?? true;
+            const symbol = projectIndex.getSymbol(name);
+            if (!symbol) {
+                return `Symbol "${name}" not found in the project index. Try using search to find it, or use read_file to read the full file.`;
+            }
+            const filePath = resolveWorkspacePath(symbol.filePath, config.workspaceRoot);
+            const fileStat = await stat(filePath);
+            if (!fileStat.isFile()) {
+                return `File "${symbol.filePath}" is not a file.`;
+            }
+            validateFileReadSize(fileStat.size, config.maxFileSizeBytes);
+            const content = await readFile(filePath, "utf8");
+            const lines = content.split(/\r?\n/);
+            if (includeBody) {
+                const startLine = Math.max(1, symbol.startLine - LEADING_CONTEXT_LINES);
+                const endLine = Math.min(lines.length, symbol.endLine);
+                const excerptLines = lines.slice(startLine - 1, endLine);
+                const formatted = excerptLines
+                    .map((line, i) => `${startLine + i}|${line}`)
+                    .join("\n");
+                const parts = [
+                    `# ${symbol.qualifiedName} (${symbol.kind})`,
+                    `File: ${symbol.filePath}`,
+                    `Lines: ${symbol.startLine}-${symbol.endLine}`,
+                    "",
+                ];
+                if (symbol.docComment) {
+                    parts.push("## Description", "", symbol.docComment, "");
+                }
+                parts.push(formatted);
+                const usedBy = projectIndex.dependencyEdges
+                    .filter((e) => e.to === symbol.qualifiedName || e.to === symbol.name)
+                    .slice(0, 5)
+                    .map((e) => e.from);
+                if (usedBy.length > 0) {
+                    parts.push("", "## Used by", "", usedBy.map((s) => `- ${s}`).join("\n"));
+                }
+                const calls = projectIndex.dependencyEdges
+                    .filter((e) => e.from === symbol.qualifiedName || e.from === symbol.name)
+                    .slice(0, 5)
+                    .map((e) => e.to);
+                if (calls.length > 0) {
+                    parts.push("", "## Calls", "", calls.map((s) => `- ${s}`).join("\n"));
+                }
+                const cone = projectIndex.getDependencyCone(name, 1);
+                const typeRefs = cone.filter((s) => s.qualifiedName !== symbol.qualifiedName &&
+                    (s.kind === "interface" || s.kind === "type"));
+                if (typeRefs.length > 0) {
+                    parts.push("", "## Referenced Types", "");
+                    for (const ref of typeRefs) {
+                        parts.push(`### ${ref.qualifiedName}`, ref.signature, "");
+                    }
+                }
+                return parts.join("\n");
+            }
+            const sigParts = [
+                `# ${symbol.qualifiedName} (${symbol.kind})`,
+                `File: ${symbol.filePath}`,
+                `Lines: ${symbol.startLine}-${symbol.endLine}`,
+                "",
+            ];
+            if (symbol.docComment) {
+                sigParts.push("## Description", "", symbol.docComment, "");
+            }
+            sigParts.push(symbol.signature);
+            return sigParts.join("\n");
+        },
+    };
+}

package/dist/src/tools/registry.js

@@ -0,0 +1,68 @@
+import { createEditFileTool } from "./edit-file.js";
+import { createFindReferencesTool } from "./find-references.js";
+import { createGetDependenciesTool } from "./get-dependencies.js";
+import { createListFilesTool } from "./list-files.js";
+import { createReadFileTool } from "./read-file.js";
+import { createReadSymbolTool } from "./read-symbol.js";
+import { createRunCommandTool } from "./run-command.js";
+import { createSearchCodeMapTool } from "./search-code-map.js";
+import { createSearchTool } from "./search.js";
+import { createWriteFileTool } from "./write-file.js";
+function ensureInputObject(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw new Error("Tool input must be a JSON object.");
+    }
+    return input;
+}
+function toToolSchema(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.inputSchema,
+    };
+}
+export class ToolRegistry {
+    toolsByName = new Map();
+    constructor(tools) {
+        for (const tool of tools) {
+            if (this.toolsByName.has(tool.name)) {
+                throw new Error(`Duplicate tool registration for "${tool.name}".`);
+            }
+            this.toolsByName.set(tool.name, tool);
+        }
+    }
+    static createDefault(config, projectIndex) {
+        const tools = [
+            createReadFileTool(config),
+            createWriteFileTool(config, projectIndex),
+            createEditFileTool(config, projectIndex),
+            createSearchTool(config),
+            createListFilesTool(config),
+            createRunCommandTool(config),
+        ];
+        if (projectIndex) {
+            tools.splice(1, 0, createReadSymbolTool(config, projectIndex));
+            tools.splice(2, 0, createFindReferencesTool(projectIndex));
+            tools.splice(3, 0, createGetDependenciesTool(projectIndex));
+            tools.splice(4, 0, createSearchCodeMapTool(projectIndex));
+        }
+        return new ToolRegistry(tools);
+    }
+    getToolSchemas() {
+        return [...this.toolsByName.values()].map(toToolSchema);
+    }
+    async execute(name, input) {
+        const tool = this.toolsByName.get(name);
+        if (!tool) {
+            return `Tool error: Unknown tool "${name}".`;
+        }
+        try {
+            const inputObject = ensureInputObject(input);
+            return await tool.execute(inputObject);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown tool failure";
+            return `Tool error (${name}): ${message}`;
+        }
+    }
+}

package/dist/src/tools/run-command.js

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import { isDestructiveCommand, validateCommand, } from "../safety/guardrails.js";
+import { expectNonEmptyString, expectOptionalNumber } from "./helpers.js";
+function executeBashCommand(command, cwd, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("bash", ["-lc", command], { cwd });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            resolve({
+                stdout: stdout.trimEnd(),
+                stderr: stderr.trimEnd(),
+                exitCode: code,
+                timedOut,
+            });
+        });
+    });
+}
+function parseTimeout(rawTimeout, defaultTimeoutMs) {
+    if (rawTimeout === undefined) {
+        return defaultTimeoutMs;
+    }
+    if (!Number.isInteger(rawTimeout) || rawTimeout <= 0) {
+        throw new Error(`"timeout" must be a positive integer in milliseconds.`);
+    }
+    return Math.min(rawTimeout, 10 * 60 * 1000);
+}
+export function createRunCommandTool(config) {
+    return {
+        name: "run_command",
+        description: "Run a shell command in the workspace and return stdout/stderr/exit code.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "Shell command to execute within workspace root.",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Optional timeout in milliseconds. Defaults to configured command timeout.",
+                },
+            },
+            required: ["command"],
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            const command = expectNonEmptyString(input, "command");
+            const rawTimeout = expectOptionalNumber(input, "timeout");
+            const timeoutMs = parseTimeout(rawTimeout, config.commandTimeoutMs);
+            validateCommand(command, config.commandDenylist);
+            if (config.confirmDestructive && isDestructiveCommand(command)) {
+                throw new Error(`Command "${command}" appears destructive and requires explicit user confirmation.`);
+            }
+            const result = await executeBashCommand(command, config.workspaceRoot, timeoutMs);
+            const maxStdoutChars = 8_000;
+            const maxStderrChars = 4_000;
+            let stdoutOut = result.stdout.length > 0 ? result.stdout : "(empty)";
+            if (stdoutOut.length > maxStdoutChars) {
+                stdoutOut = `${stdoutOut.slice(0, maxStdoutChars)}\n[... truncated, ${result.stdout.length - maxStdoutChars} more chars ...]`;
+            }
+            let stderrOut = result.stderr.length > 0 ? result.stderr : "(empty)";
+            if (stderrOut.length > maxStderrChars) {
+                stderrOut = `${stderrOut.slice(0, maxStderrChars)}\n[... truncated, ${result.stderr.length - maxStderrChars} more chars ...]`;
+            }
+            return [
+                `exit_code: ${result.exitCode ?? "null"}`,
+                `timed_out: ${result.timedOut ? "true" : "false"}`,
+                "stdout:",
+                stdoutOut,
+                "stderr:",
+                stderrOut,
+            ].join("\n");
+        },
+    };
+}

package/dist/src/tools/search-code-map.js

@@ -0,0 +1,72 @@
+import { expectNonEmptyString, expectOptionalNumber, } from "./helpers.js";
+const DEFAULT_LIMIT = 30;
+function matchesPattern(text, pattern) {
+    const lowerText = text.toLowerCase();
+    const lowerPattern = pattern.toLowerCase();
+    return lowerText.includes(lowerPattern);
+}
+export function createSearchCodeMapTool(projectIndex) {
+    return {
+        name: "search_code_map",
+        description: "Search the full project index for symbols by name or substring. " +
+            "Use when the code map is truncated and you need to find a symbol not listed. " +
+            "Returns qualified names and file paths; use read_symbol with the result.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Substring to match against symbol name or qualified name (case-insensitive).",
+                },
+                kind: {
+                    type: "string",
+                    description: "Optional filter by symbol kind: function, class, interface, type, variable, method.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max results to return. Default 30.",
+                },
+                skip: {
+                    type: "number",
+                    description: "Number of results to skip (for pagination). Default 0.",
+                },
+            },
+            required: ["pattern"],
+            additionalProperties: false,
+        },
+        execute: async (input) => {
+            const pattern = expectNonEmptyString(input, "pattern");
+            const kindFilter = input.kind;
+            const kind = typeof kindFilter === "string" && kindFilter.trim().length > 0
+                ? kindFilter.trim().toLowerCase()
+                : undefined;
+            const limit = Math.max(1, Math.min(100, expectOptionalNumber(input, "limit") ?? DEFAULT_LIMIT));
+            const skip = Math.max(0, expectOptionalNumber(input, "skip") ?? 0);
+            const symbols = [...projectIndex.symbols.values()];
+            const matches = symbols.filter((sym) => {
+                if (!matchesPattern(sym.name, pattern) && !matchesPattern(sym.qualifiedName, pattern)) {
+                    return false;
+                }
+                if (kind && sym.kind !== kind) {
+                    return false;
+                }
+                return true;
+            });
+            const shown = matches.slice(skip, skip + limit);
+            const lines = shown.map((s) => `- ${s.qualifiedName} (${s.kind}) — ${s.filePath}`);
+            const remaining = matches.length - skip - shown.length;
+            const footer = remaining > 0
+                ? `\n... and ${remaining} more (use skip: ${skip + limit}, limit: ${limit} for next page)`
+                : "";
+            if (matches.length === 0) {
+                return `No symbols matching "${pattern}"${kind ? ` (kind: ${kind})` : ""}. Try a shorter or different pattern.`;
+            }
+            return [
+                `# Symbols matching "${pattern}" (${matches.length} total)`,
+                "",
+                ...lines,
+                footer,
+            ].join("\n");
+        },
+    };
+}