@sean.holung/minicode 0.2.0 → 0.2.1

package/dist/src/prompt/system-prompt.js

@@ -1,91 +0,0 @@
-import { existsSync } from "node:fs";
-import path from "node:path";
-function detectProjectType(workspaceRoot) {
-    const checks = [
-        { file: "package.json", type: "Node.js / TypeScript" },
-        { file: "pyproject.toml", type: "Python" },
-        { file: "requirements.txt", type: "Python" },
-        { file: "go.mod", type: "Go" },
-        { file: "Cargo.toml", type: "Rust" },
-        { file: "pom.xml", type: "Java (Maven)" },
-    ];
-    for (const check of checks) {
-        if (existsSync(path.join(workspaceRoot, check.file))) {
-            return check.type;
-        }
-    }
-    return "Unknown";
-}
-function renderToolList(tools) {
-    return tools
-        .map((tool) => `- ${tool.name}: ${tool.description}`)
-        .join("\n");
-}
-function hasTool(tools, name) {
-    return tools.some((t) => t.name === name);
-}
-export function buildSystemPrompt(config, tools, codeMapResult) {
-    const projectType = detectProjectType(config.workspaceRoot);
-    const sections = [
-        "[Identity]",
-        "You are a coding agent. You help developers read, understand, and modify code in their projects.",
-        "",
-        "[Workspace Context]",
-        `Working directory: ${config.workspaceRoot}`,
-        `Project type: ${projectType}`,
-        "",
-    ];
-    const hasSearchCodeMap = hasTool(tools, "search_code_map");
-    if (codeMapResult && codeMapResult.text.length > 0) {
-        sections.push("[Project Code Map]", codeMapResult.text, "");
-        const truncated = codeMapResult.totalCount > 0 &&
-            codeMapResult.shownCount < codeMapResult.totalCount;
-        if (truncated) {
-            const hint = hasSearchCodeMap
-                ? " Use search_code_map to find symbols not listed above."
-                : "";
-            sections.push(`Showing ${codeMapResult.shownCount} of ${codeMapResult.totalCount} symbols.${hint}`, "");
-        }
-    }
-    const hasReadSymbol = hasTool(tools, "read_symbol");
-    const hasFindRefs = hasTool(tools, "find_references");
-    const hasGetDeps = hasTool(tools, "get_dependencies");
-    const hasSpecializedTools = hasReadSymbol || hasFindRefs || hasGetDeps || hasSearchCodeMap;
-    const toolGuidelines = [
-        "[Tool Usage Guidelines]",
-        "- Always read a file before editing it.",
-        "- Prefer edit_file over write_file for existing files.",
-        "- Run tests or lint after code changes when applicable.",
-        "- Default to using preferred tools when doing planning, code exploration, or investigation."
-    ];
-    if (hasSpecializedTools) {
-        toolGuidelines.push("", "[Code exploration PREFERRED TOOLS — prefer these over read_file and search]", ...(hasReadSymbol
-            ? [
-                "- PREFER read_symbol over read_file for .ts/.tsx/.js/.jsx when you need a function or class. The code map lists all symbols; use read_symbol(name) for targeted reads — it returns only the relevant code and avoids bloating context.",
-                "- Use read_file only for config files, small files, non-code files, or when the symbol name is unknown.",
-            ]
-            : []), ...(hasFindRefs
-            ? [
-                "- Use find_references to see what calls or uses a symbol — essential for understanding impact before changes.",
-            ]
-            : []), ...(hasGetDeps
-            ? [
-                "- Use get_dependencies to see what a symbol depends on — essential for understanding implementation and data flow.",
-            ]
-            : []), "- Use search only when you don't know the symbol name; once you find a symbol in the code map or search results, use read_symbol (not read_file) to read it.", "- When tracing code: use get_dependencies to go inward (what does X call?), find_references to go outward (what calls X?).", ...(hasSearchCodeMap
-            ? [
-                "- PREFER search_code_map over search. When the code map is truncated, use search_code_map to find symbols by name or substring — then use read_symbol with the result.",
-            ]
-            : []));
-    }
-    else {
-        toolGuidelines.push("", "- Use read_file with offset and limit for large files to read only needed portions.", "- Use search to find relevant code before making changes.");
-    }
-    sections.push("[Tool Descriptions]", "You have the following tools available:", renderToolList(tools), "", ...toolGuidelines, "", "[Code Reading Strategy]", "- Start with entry points (e.g. index.ts, main) and follow the flow.", ...(hasSpecializedTools
-        ? [
-            "- Use find_references to see who uses a symbol; use get_dependencies to see what it calls.",
-            "- Trace usage outward (find_references) or implementation inward (get_dependencies) as needed.",
-        ]
-        : ["- Use search to locate relevant code, then read_file to inspect it."]), "", "[Termination Policy]", "- When the user asks you to do something (edit code, search, run commands, etc.), you MUST use the appropriate tools first. Do not conclude until you have actually performed the work.", "- When the task is complete, respond with a concise summary of what you changed.", "- If you cannot complete the task, explain what is blocking you.", "- Do not respond with empty text. Always provide a summary or explanation.", "- Do not continue exploring once the task is done.", "", "[Safety Rules]", "- Never modify files outside the workspace directory.", "- Never run destructive commands without explicit user confirmation.", "- Ask for clarification if user intent is ambiguous.", "- When asked to perform a task, communicate your execution plan to the user and ask for their confirmation before proceeding with any modifications.");
-    return sections.join("\n");
-}

package/dist/src/safety/guardrails.js

@@ -1,55 +0,0 @@
-import path from "node:path";
-const DESTRUCTIVE_COMMAND_PATTERNS = [
-    /\brm\s+-rf\b/i,
-    /\bmv\b.+\s+\/dev\/null\b/i,
-    /\bgit\s+reset\s+--hard\b/i,
-    /\bgit\s+clean\s+-fdx?\b/i,
-];
-export function normalizeWorkspaceRoot(workspaceRoot) {
-    return path.resolve(workspaceRoot);
-}
-export function resolveWorkspacePath(requestedPath, workspaceRoot) {
-    const normalizedRoot = normalizeWorkspaceRoot(workspaceRoot);
-    const absolutePath = path.resolve(normalizedRoot, requestedPath);
-    if (!isWithinWorkspacePath(absolutePath, normalizedRoot)) {
-        throw new Error(`Path "${requestedPath}" resolves outside workspace root "${normalizedRoot}".`);
-    }
-    return absolutePath;
-}
-export function isWithinWorkspacePath(absolutePath, workspaceRoot) {
-    const normalizedRoot = normalizeWorkspaceRoot(workspaceRoot);
-    const relative = path.relative(normalizedRoot, absolutePath);
-    if (relative === "") {
-        return true;
-    }
-    return !relative.startsWith("..") && !path.isAbsolute(relative);
-}
-export function validatePath(requestedPath, workspaceRoot) {
-    try {
-        resolveWorkspacePath(requestedPath, workspaceRoot);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function validateCommand(command, denylist) {
-    for (const pattern of denylist) {
-        if (pattern.test(command)) {
-            throw new Error(`Command "${command}" blocked by safety denylist (${pattern}).`);
-        }
-    }
-}
-export function isDestructiveCommand(command) {
-    return DESTRUCTIVE_COMMAND_PATTERNS.some((pattern) => pattern.test(command));
-}
-export function ensureStepWithinLimit(step, maxSteps) {
-    if (step >= maxSteps) {
-        throw new Error(`Reached maximum step limit (${maxSteps}). Stopping tool loop.`);
-    }
-}
-export function validateFileReadSize(actualSizeBytes, maxFileSizeBytes) {
-    if (actualSizeBytes > maxFileSizeBytes) {
-        throw new Error(`File too large to read (${actualSizeBytes} bytes). Limit is ${maxFileSizeBytes} bytes.`);
-    }
-}

package/dist/src/session/session.js

@@ -1,95 +0,0 @@
-import { randomUUID } from "node:crypto";
-function estimateMessageTokens(message) {
-    if (message.role === "tool") {
-        return Math.ceil((message.toolName.length + message.content.length) / 4);
-    }
-    const toolCallTokens = message.role === "assistant" && message.toolCalls?.length
-        ? Math.ceil(JSON.stringify(message.toolCalls).length / 4)
-        : 0;
-    return Math.ceil(message.content.length / 4) + toolCallTokens;
-}
-export class Session {
-    id;
-    createdAt;
-    messages;
-    constructor(id = randomUUID()) {
-        this.id = id;
-        this.createdAt = new Date();
-        this.messages = [];
-    }
-    addMessage(message) {
-        this.messages.push(message);
-    }
-    getMessages() {
-        return [...this.messages];
-    }
-    getTokenEstimate() {
-        return this.messages.reduce((total, message) => total + estimateMessageTokens(message), 0);
-    }
-    trim(maxTokens, keepRecentMessages) {
-        if (keepRecentMessages < 0) {
-            return;
-        }
-        while (this.getTokenEstimate() > maxTokens &&
-            this.messages.length > keepRecentMessages) {
-            const protectedStart = this.getProtectedStart(keepRecentMessages);
-            if (protectedStart <= 0) {
-                return;
-            }
-            const removed = this.removeOldestChunk(protectedStart);
-            if (!removed) {
-                return;
-            }
-        }
-    }
-    getProtectedStart(keepRecentMessages) {
-        let protectedStart = Math.max(0, this.messages.length - keepRecentMessages);
-        const boundaryMessage = this.messages[protectedStart];
-        if (!boundaryMessage || boundaryMessage.role !== "tool") {
-            return protectedStart;
-        }
-        while (protectedStart > 0 &&
-            this.messages[protectedStart - 1]?.role === "tool") {
-            protectedStart -= 1;
-        }
-        const potentialToolCallMessage = this.messages[protectedStart - 1];
-        if (potentialToolCallMessage?.role === "assistant" &&
-            potentialToolCallMessage.toolCalls?.length) {
-            protectedStart -= 1;
-        }
-        return protectedStart;
-    }
-    removeOldestChunk(removableCount) {
-        if (removableCount <= 0 || this.messages.length === 0) {
-            return false;
-        }
-        const first = this.messages[0];
-        if (!first) {
-            return false;
-        }
-        if (first.role === "assistant" && first.toolCalls?.length) {
-            let removeCount = 1;
-            while (this.messages[removeCount]?.role === "tool") {
-                removeCount += 1;
-            }
-            if (removeCount > removableCount) {
-                return false;
-            }
-            this.messages.splice(0, removeCount);
-            return true;
-        }
-        if (first.role === "tool") {
-            let removeCount = 1;
-            while (this.messages[removeCount]?.role === "tool") {
-                removeCount += 1;
-            }
-            if (removeCount > removableCount) {
-                return false;
-            }
-            this.messages.splice(0, removeCount);
-            return true;
-        }
-        this.messages.splice(0, 1);
-        return true;
-    }
-}

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

@@ -1,73 +0,0 @@
-import path from "node:path";
-import { readFile, writeFile } from "node:fs/promises";
-import { resolveWorkspacePath } from "../safety/guardrails.js";
-import { expectNonEmptyString } from "./helpers.js";
-function expectString(input, key) {
-    const value = input[key];
-    if (typeof value !== "string") {
-        throw new Error(`Input "${key}" must be a string.`);
-    }
-    return value;
-}
-function countOccurrences(haystack, needle) {
-    if (needle.length === 0) {
-        return 0;
-    }
-    let count = 0;
-    let index = 0;
-    while (true) {
-        const found = haystack.indexOf(needle, index);
-        if (found === -1) {
-            break;
-        }
-        count += 1;
-        index = found + needle.length;
-    }
-    return count;
-}
-export function createEditFileTool(config, projectIndex) {
-    return {
-        name: "edit_file",
-        description: "Replace exactly one instance of old_string with new_string in a file.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: {
-                    type: "string",
-                    description: "Path to file relative to workspace root.",
-                },
-                old_string: {
-                    type: "string",
-                    description: "Exact text to replace (must match once).",
-                },
-                new_string: {
-                    type: "string",
-                    description: "Replacement text.",
-                },
-            },
-            required: ["path", "old_string", "new_string"],
-            additionalProperties: false,
-        },
-        execute: async (input) => {
-            const requestedPath = expectNonEmptyString(input, "path");
-            const oldString = expectNonEmptyString(input, "old_string");
-            const newString = expectString(input, "new_string");
-            const filePath = resolveWorkspacePath(requestedPath, config.workspaceRoot);
-            const current = await readFile(filePath, "utf8");
-            const occurrences = countOccurrences(current, oldString);
-            if (occurrences === 0) {
-                throw new Error(`old_string was not found in "${requestedPath}".`);
-            }
-            if (occurrences > 1) {
-                throw new Error(`old_string matched ${occurrences} times in "${requestedPath}". It must be unique.`);
-            }
-            const updated = current.replace(oldString, newString);
-            await writeFile(filePath, updated, "utf8");
-            if (projectIndex) {
-                const relPath = path.relative(config.workspaceRoot, filePath);
-                projectIndex.reindexFile(relPath, updated);
-            }
-            return `Updated "${requestedPath}" successfully.`;
-        },
-    };
-}

package/dist/src/tools/helpers.js

@@ -1,42 +0,0 @@
-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

@@ -1,63 +0,0 @@
-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

@@ -1,79 +0,0 @@
-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/run-command.js

@@ -1,92 +0,0 @@
-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");
-        },
-    };
-}