xcoder-dna 0.0.0-stage → 1.3.1

package/dist/tools/sed-tool.js

@@ -0,0 +1,402 @@
+// xcoder:version 2 | xcoder:task task-456d3f | xcoder:updated 2026-08-03T15:41:37.782Z | xcoder:subtask code-st-97a4d4
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { getOrBuildIndex, upsertEntry, toPosixPath } from "./workspace-index.js";
+import { indexGlobTool } from "./search-tools.js";
+import { getCommentSyntax, injectVersionHeader, } from "./file-header-manager.js";
+import { incrementFileVersion } from "../store/file-version-store.js";
+// ── Constants ────────────────────────────────────────────────────────────
+const ALLOWED_FLAGS = new Set(["g", "i", "m", "s"]);
+// ── Helpers ──────────────────────────────────────────────────────────────
+class WorkspaceEscapeError extends Error {
+}
+function resolveInWorkspace(root, relPath) {
+    const full = path.resolve(root, relPath);
+    const normalizedRoot = path.resolve(root) + path.sep;
+    if (full + path.sep !== normalizedRoot && !full.startsWith(normalizedRoot)) {
+        throw new WorkspaceEscapeError(`path "${relPath}" resolves outside the workspace root — refusing.`);
+    }
+    return full;
+}
+/**
+ * Validate the SedToolInput before processing.
+ * Returns an error string if invalid, null if valid.
+ */
+function validateInput(input) {
+    // Operation must be valid
+    const validOps = ["substitute", "delete", "deleteRange", "insert", "appendAfter"];
+    if (!validOps.includes(input.operation)) {
+        return `invalid_operation: "${input.operation}" is not a valid operation. Must be one of: ${validOps.join(", ")}`;
+    }
+    // Target: glob takes precedence, then path, then neither → no_target
+    const hasPath = input.path !== undefined && input.path !== "";
+    const hasGlob = input.glob !== undefined && input.glob !== "";
+    if (!hasPath && !hasGlob) {
+        return "no_target: neither 'path' nor 'glob' was provided. Provide at least one target.";
+    }
+    // Operation-specific validation
+    switch (input.operation) {
+        case "substitute":
+            if (input.pattern === undefined || input.pattern === "") {
+                return "invalid_operation: 'substitute' requires a 'pattern' field.";
+            }
+            if (input.replacement === undefined) {
+                return "invalid_operation: 'substitute' requires a 'replacement' field.";
+            }
+            break;
+        case "delete":
+            if (input.pattern === undefined || input.pattern === "") {
+                return "invalid_operation: 'delete' requires a 'pattern' field.";
+            }
+            break;
+        case "deleteRange":
+            if (input.startLine === undefined || input.endLine === undefined) {
+                return "invalid_operation: 'deleteRange' requires both 'startLine' and 'endLine'.";
+            }
+            if (!Number.isInteger(input.startLine) || input.startLine < 1) {
+                return "invalid_operation: 'startLine' must be an integer >= 1.";
+            }
+            if (!Number.isInteger(input.endLine) || input.endLine < 1) {
+                return "invalid_operation: 'endLine' must be an integer >= 1.";
+            }
+            if (input.endLine < input.startLine) {
+                return "invalid_operation: 'endLine' must be >= 'startLine'.";
+            }
+            break;
+        case "insert":
+            if (input.text === undefined) {
+                return "invalid_operation: 'insert' requires a 'text' field.";
+            }
+            if (input.afterLine !== undefined && (!Number.isInteger(input.afterLine) || input.afterLine < 0)) {
+                return "invalid_operation: 'afterLine' must be an integer >= 0.";
+            }
+            break;
+        case "appendAfter":
+            if (input.pattern === undefined || input.pattern === "") {
+                return "invalid_operation: 'appendAfter' requires a 'pattern' field.";
+            }
+            if (input.text === undefined) {
+                return "invalid_operation: 'appendAfter' requires a 'text' field.";
+            }
+            break;
+    }
+    // Flags validation (if provided)
+    if (input.flags !== undefined) {
+        for (const ch of input.flags) {
+            if (!ALLOWED_FLAGS.has(ch)) {
+                return `invalid_regex: flag "${ch}" is not allowed. Allowed flags: ${[...ALLOWED_FLAGS].join("")}`;
+            }
+        }
+    }
+    // Regex validation (if pattern provided)
+    if (input.pattern) {
+        try {
+            new RegExp(input.pattern, input.flags ?? "");
+        }
+        catch (e) {
+            return `invalid_regex: ${e.message}`;
+        }
+    }
+    return null; // valid
+}
+// ── Target Resolution ────────────────────────────────────────────────────
+/**
+ * Resolve target files: glob takes precedence over path.
+ */
+async function resolveTargetFiles(root, input) {
+    if (input.glob !== undefined && input.glob !== "") {
+        const index = await getOrBuildIndex(root);
+        const result = indexGlobTool(index, input.glob);
+        return result.matches;
+    }
+    if (input.path !== undefined && input.path !== "") {
+        return [input.path];
+    }
+    return [];
+}
+// ── Line Ending Detection & Normalization ────────────────────────────────
+function detectLineEndings(content) {
+    const crlfCount = (content.match(/\r\n/g) || []).length;
+    // Match LF not preceded by CR (pure LF lines)
+    const lfOnlyCount = (content.match(/(?<!\r)\n/g) || []).length;
+    if (crlfCount > 0 && lfOnlyCount === 0)
+        return "CRLF";
+    if (lfOnlyCount > 0 && crlfCount === 0)
+        return "LF";
+    if (crlfCount === 0 && lfOnlyCount === 0)
+        return "LF"; // empty or single line without newline
+    return "mixed";
+}
+function normalizeToLF(content, _style) {
+    return content.replace(/\r\n/g, "\n");
+}
+function restoreLineEndings(normalized, style) {
+    if (style === "CRLF") {
+        return normalized.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n");
+    }
+    return normalized;
+}
+// ── Operations ───────────────────────────────────────────────────────────
+function buildRegex(pattern, flags) {
+    return new RegExp(pattern, flags);
+}
+/**
+ * Replace back-reference placeholders in the replacement string.
+ * Supports $& (full match), $1-$9 (capture groups), and $$ (literal $).
+ */
+function expandReplacement(replacement, match, ...groups) {
+    return replacement.replace(/\$([&1-9]|\$)/g, (_, ref) => {
+        if (ref === "&")
+            return match;
+        if (ref === "$")
+            return "$";
+        const idx = parseInt(ref, 10);
+        return groups[idx - 1] ?? "$" + ref;
+    });
+}
+function applySubstitute(lines, pattern, replacement, flags) {
+    const re = buildRegex(pattern, flags);
+    let changes = 0;
+    const result = lines.map((line) => {
+        let changed = false;
+        const newLine = line.replace(re, (...args) => {
+            changed = true;
+            const match = args[0];
+            const groups = args.slice(1, -2);
+            return expandReplacement(replacement, match, ...groups);
+        });
+        if (changed)
+            changes++;
+        return newLine;
+    });
+    return { lines: result, changes };
+}
+function applyDelete(lines, pattern, flags) {
+    const re = buildRegex(pattern, flags);
+    let changes = 0;
+    const result = lines.filter((line) => {
+        const match = re.test(line);
+        if (match)
+            changes++;
+        return !match;
+    });
+    return { lines: result, changes };
+}
+function applyDeleteRange(lines, startLine, endLine) {
+    const max = lines.length;
+    const start = Math.max(1, startLine);
+    const end = Math.min(max, endLine);
+    if (start > max || end < start) {
+        return { lines, changes: 0 };
+    }
+    const count = end - start + 1;
+    const result = [...lines.slice(0, start - 1), ...lines.slice(end)];
+    return { lines: result, changes: count };
+}
+function applyInsert(lines, afterLine, text) {
+    // afterLine 0 = before first line
+    // Clamp: if afterLine > lines.length, append at end
+    const pos = Math.min(afterLine, lines.length);
+    const result = [...lines.slice(0, pos), text, ...lines.slice(pos)];
+    return { lines: result, changes: 1 };
+}
+function applyAppendAfter(lines, pattern, text, flags) {
+    const re = buildRegex(pattern, flags);
+    let changes = 0;
+    const result = [];
+    for (const line of lines) {
+        result.push(line);
+        if (re.test(line)) {
+            result.push(text);
+            changes++;
+        }
+    }
+    return { lines: result, changes };
+}
+// ── Per-File Processing ──────────────────────────────────────────────────
+async function processFile(root, relPath, input, ctx) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, relPath);
+    }
+    catch {
+        return {
+            relPath,
+            matched: false,
+            changes: 0,
+            output: undefined,
+        };
+    }
+    // Read file
+    let content;
+    try {
+        content = await fs.readFile(full, "utf8");
+    }
+    catch {
+        return {
+            relPath,
+            matched: false,
+            changes: 0,
+            output: undefined,
+        };
+    }
+    // Detect and normalize line endings
+    const lineEndingStyle = detectLineEndings(content);
+    const normalized = normalizeToLF(content, lineEndingStyle);
+    // Split into lines. A trailing empty string from split("\n") represents
+    // a trailing newline in the file — we strip it before operating on
+    // "real" lines (so line counts match user expectations), then re-add it
+    // after the join so the file's trailing-newline convention is preserved.
+    const rawLines = normalized.split("\n");
+    const hasTrailingNewline = rawLines.length > 0 && rawLines[rawLines.length - 1] === "";
+    const lines = hasTrailingNewline ? rawLines.slice(0, -1) : rawLines;
+    // Apply operation
+    let resultLines;
+    let changes;
+    switch (input.operation) {
+        case "substitute": {
+            const r = applySubstitute(lines, input.pattern, input.replacement, input.flags ?? "g");
+            resultLines = r.lines;
+            changes = r.changes;
+            break;
+        }
+        case "delete": {
+            const r = applyDelete(lines, input.pattern, input.flags ?? "");
+            resultLines = r.lines;
+            changes = r.changes;
+            break;
+        }
+        case "deleteRange": {
+            const r = applyDeleteRange(lines, input.startLine, input.endLine);
+            resultLines = r.lines;
+            changes = r.changes;
+            break;
+        }
+        case "insert": {
+            const r = applyInsert(lines, input.afterLine ?? lines.length, input.text);
+            resultLines = r.lines;
+            changes = r.changes;
+            break;
+        }
+        case "appendAfter": {
+            const r = applyAppendAfter(lines, input.pattern, input.text, input.flags ?? "");
+            resultLines = r.lines;
+            changes = r.changes;
+            break;
+        }
+        default:
+            return { relPath, matched: false, changes: 0 };
+    }
+    // Rejoin and restore line endings. Preserve trailing newline convention.
+    const joined = resultLines.join("\n") + (hasTrailingNewline ? "\n" : "");
+    const outputContent = restoreLineEndings(joined, lineEndingStyle);
+    const matched = changes > 0;
+    // Dry run: return output but don't write
+    if (input.dryRun) {
+        return { relPath, matched, changes, output: outputContent };
+    }
+    // Write back (with optional header injection)
+    try {
+        let finalContent = outputContent;
+        if (matched && ctx) {
+            const syntax = getCommentSyntax(relPath);
+            if (syntax) {
+                const meta = await incrementFileVersion(root, relPath, ctx.taskId, ctx.subtaskId);
+                const injected = injectVersionHeader(finalContent, syntax, meta);
+                finalContent = injected.content;
+            }
+        }
+        await fs.writeFile(full, finalContent, "utf8");
+        await upsertEntry(root, path.relative(root, full));
+        return { relPath, matched, changes };
+    }
+    catch {
+        return { relPath, matched: false, changes: 0 };
+    }
+}
+// ── Main Export ──────────────────────────────────────────────────────────
+/**
+ * Perform stream-editing operations on workspace files.
+ * Supports substitute, delete, deleteRange, insert, and appendAfter operations.
+ */
+export async function sedTool(root, input, ctx) {
+    // Validate input
+    const validationError = validateInput(input);
+    if (validationError) {
+        const code = validationError.startsWith("no_target")
+            ? "no_target"
+            : validationError.startsWith("invalid_regex")
+                ? "invalid_regex"
+                : "invalid_operation";
+        return { ok: false, code, error: validationError };
+    }
+    // Resolve target files
+    let targetFiles;
+    try {
+        targetFiles = await resolveTargetFiles(root, input);
+    }
+    catch (e) {
+        return { ok: false, code: "io_error", error: `Failed to resolve target files: ${e.message}` };
+    }
+    if (targetFiles.length === 0) {
+        const target = input.glob ? `glob "${input.glob}"` : `path "${input.path}"`;
+        return {
+            ok: false,
+            code: "file_not_found",
+            error: `No files matched ${target}. Check the pattern or run reindex_workspace to refresh the index.`,
+        };
+    }
+    // When using a single path (not glob), verify the file actually exists
+    // on disk before proceeding.
+    if (!input.glob && input.path) {
+        try {
+            const full = resolveInWorkspace(root, input.path);
+            try {
+                await fs.access(full);
+            }
+            catch {
+                return {
+                    ok: false,
+                    code: "file_not_found",
+                    error: `File "${input.path}" does not exist in the workspace.`,
+                };
+            }
+        }
+        catch {
+            return {
+                ok: false,
+                code: "workspace_escape",
+                error: `Path "${input.path}" resolves outside the workspace root.`,
+            };
+        }
+    }
+    // Process each file
+    const results = [];
+    let workspaceEscape = false;
+    for (const relPath of targetFiles) {
+        // Check for workspace escape
+        try {
+            resolveInWorkspace(root, relPath);
+        }
+        catch {
+            workspaceEscape = true;
+            continue;
+        }
+        const posixPath = toPosixPath(relPath).replace(/^\.\//, "");
+        try {
+            const result = await processFile(root, posixPath, input, ctx);
+            results.push(result);
+        }
+        catch {
+            results.push({ relPath: posixPath, matched: false, changes: 0 });
+        }
+    }
+    if (workspaceEscape && results.length === 0) {
+        return {
+            ok: false,
+            code: "workspace_escape",
+            error: `One or more target paths resolve outside the workspace root.`,
+        };
+    }
+    return { ok: true, results };
+}

package/dist/tools/shell-result.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared result interface for shell command execution.
+ * Used by both shell-tool.ts (exec-based) and runCommandTool.ts (spawn-based).
+ */
+export interface ShellResult {
+    ok: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}

package/dist/tools/shell-result.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/shell-tool.d.ts

@@ -0,0 +1,45 @@
+import type { ShellResult } from "./shell-result.js";
+export type { ShellResult } from "./shell-result.js";
+/**
+ * Minimal shell-quote-aware split: respects single-quoted and double-quoted
+ * strings. Does NOT handle escaped quotes, nested quoting, or advanced
+ * features — it just needs to be good enough to split "npm run build" into
+ * ["npm", "run", "build"] and preserve "echo 'hello world'" as
+ * ["echo", "hello world"].
+ *
+ * Migrated from runCommandTool.ts. Exported for testing but intended as
+ * an internal utility of shell-tool.ts.
+ */
+export declare function splitCommand(command: string): string[];
+/**
+ * Windows-specific PATHEXT resolution: wraps .cmd/.bat/.ps1 commands
+ * with the appropriate interpreter so they work on Windows even when
+ * passed to exec(). This is a transparent safety net — exec() already
+ * handles .cmd/.bat natively in many shells, but wrapping ensures
+ * consistent behavior across all Windows configurations.
+ *
+ * On non-Windows platforms this is a no-op.
+ *
+ * Migrated from runCommandTool.ts. Exported for testing but intended as
+ * an internal utility of shell-tool.ts.
+ */
+export declare function resolveWindowsExecutable(command: string, args: string[]): {
+    command: string;
+    args: string[];
+};
+export declare function isDenied(command: string): string | null;
+/**
+ * The single entry point for executing shell commands via the run_command
+ * tool. Internally:
+ * 1. Checks the denylist — denied commands return immediately.
+ * 2. Splits the command to identify the executable.
+ * 3. On Windows, wraps .cmd/.bat/.ps1 executables with the appropriate
+ *    interpreter via resolveWindowsExecutable().
+ * 4. Executes via child_process.exec().
+ *
+ * @param command  - The full command string, e.g. "npm run build".
+ * @param cwd      - Working directory (the workspace root).
+ * @param timeoutMs - Optional timeout in milliseconds (default 120_000).
+ * @returns A ShellResult promise.
+ */
+export declare function runCommandTool(command: string, cwd: string, timeoutMs?: number): Promise<ShellResult>;

package/dist/tools/shell-tool.js

@@ -0,0 +1,141 @@
+// xcoder:version 2 | xcoder:task task-a73fdc | xcoder:updated 2026-08-03T20:52:06.503Z | xcoder:subtask code-st-dd8b38
+import { exec } from "node:child_process";
+/**
+ * A denylist, not a sandbox. This catches the obviously destructive
+ * one-liners a model might produce while "cleaning up" or "starting
+ * fresh" — it is NOT a security boundary against an adversarial actor.
+ * Xcoder SDLC is designed to run each task inside its own disposable container
+ * or VM (the same isolation principle Agent Factory's Tool Execution
+ * Sandbox uses) — this denylist is a courtesy guardrail on top of that,
+ * not a substitute for it.
+ */
+const DENYLIST_PATTERNS = [
+    /\brm\s+-rf\s+\/(?:\s|$)/, // rm -rf /
+    /\brm\s+-rf\s+~(?:\s|$)/, // rm -rf ~
+    /\bmkfs\b/,
+    /:\(\)\{.*:\|:.*\};:/, // fork bomb
+    /\bdd\s+if=.*of=\/dev\/(sd|nvme|hd)/,
+    /\bchmod\s+-R\s+777\s+\//,
+    /\bcurl\b.*\|\s*sh\b/, // pipe-to-shell from a URL — force an explicit review step instead
+    />\s*\/dev\/sd/,
+];
+/**
+ * Minimal shell-quote-aware split: respects single-quoted and double-quoted
+ * strings. Does NOT handle escaped quotes, nested quoting, or advanced
+ * features — it just needs to be good enough to split "npm run build" into
+ * ["npm", "run", "build"] and preserve "echo 'hello world'" as
+ * ["echo", "hello world"].
+ *
+ * Migrated from runCommandTool.ts. Exported for testing but intended as
+ * an internal utility of shell-tool.ts.
+ */
+export function splitCommand(command) {
+    const parts = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+        }
+        else if (ch === " " || ch === "\t") {
+            if (current.length > 0) {
+                parts.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.length > 0) {
+        parts.push(current);
+    }
+    return parts;
+}
+/**
+ * Windows-specific PATHEXT resolution: wraps .cmd/.bat/.ps1 commands
+ * with the appropriate interpreter so they work on Windows even when
+ * passed to exec(). This is a transparent safety net — exec() already
+ * handles .cmd/.bat natively in many shells, but wrapping ensures
+ * consistent behavior across all Windows configurations.
+ *
+ * On non-Windows platforms this is a no-op.
+ *
+ * Migrated from runCommandTool.ts. Exported for testing but intended as
+ * an internal utility of shell-tool.ts.
+ */
+export function resolveWindowsExecutable(command, args) {
+    if (process.platform !== "win32")
+        return { command, args };
+    const lower = command.toLowerCase();
+    if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+        return { command: "cmd.exe", args: ["/c", command, ...args] };
+    }
+    if (lower.endsWith(".ps1")) {
+        return { command: "powershell.exe", args: ["-File", command, ...args] };
+    }
+    return { command, args };
+}
+export function isDenied(command) {
+    for (const pattern of DENYLIST_PATTERNS) {
+        if (pattern.test(command)) {
+            return `command matches a denylisted destructive pattern (${pattern}) and was not run.`;
+        }
+    }
+    return null;
+}
+/**
+ * The single entry point for executing shell commands via the run_command
+ * tool. Internally:
+ * 1. Checks the denylist — denied commands return immediately.
+ * 2. Splits the command to identify the executable.
+ * 3. On Windows, wraps .cmd/.bat/.ps1 executables with the appropriate
+ *    interpreter via resolveWindowsExecutable().
+ * 4. Executes via child_process.exec().
+ *
+ * @param command  - The full command string, e.g. "npm run build".
+ * @param cwd      - Working directory (the workspace root).
+ * @param timeoutMs - Optional timeout in milliseconds (default 120_000).
+ * @returns A ShellResult promise.
+ */
+export function runCommandTool(command, cwd, timeoutMs = 120_000) {
+    const denyReason = isDenied(command);
+    if (denyReason) {
+        return Promise.resolve({ ok: false, exitCode: null, stdout: "", stderr: denyReason, timedOut: false });
+    }
+    // Apply OS-aware executable wrapping for Windows .cmd/.bat/.ps1 commands
+    const trimmed = command.trim();
+    let finalCommand = trimmed;
+    if (trimmed.length > 0 && process.platform === "win32") {
+        const parts = splitCommand(trimmed);
+        const executable = parts[0];
+        const rawArgs = parts.slice(1);
+        const { command: resolvedCmd, args } = resolveWindowsExecutable(executable, rawArgs);
+        if (resolvedCmd !== executable) {
+            // The executable was wrapped — reconstruct the command string
+            finalCommand = [resolvedCmd, ...args].map((a) => a.includes(" ") ? `"${a}"` : a).join(" ");
+        }
+    }
+    return new Promise((resolve) => {
+        const child = exec(finalCommand, { cwd, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+            const timedOut = !!error && error.killed === true && error.signal === "SIGTERM";
+            resolve({
+                ok: !error,
+                exitCode: error ? (typeof error.code === "number" ? error.code : 1) : 0,
+                stdout,
+                stderr,
+                timedOut,
+            });
+        });
+        void child;
+    });
+}

package/dist/tools/siteCrawlerTool.d.ts

@@ -0,0 +1,32 @@
+export interface SitePage {
+    url: string;
+    title: string;
+    depth: number;
+    links: string[];
+    status: number;
+}
+export interface SiteMap {
+    rootUrl: string;
+    totalPages: number;
+    maxDepth: number;
+    pages: SitePage[];
+    /** Adjacency list: page URL -> list of linked page URLs (internal only) */
+    graph: Record<string, string[]>;
+    /** Breadcrumb / hierarchy: page URL -> parent URL (first discovered parent) */
+    parent: Record<string, string>;
+}
+/**
+ * Crawl a URL and build a site map of all discoverable internal pages.
+ *
+ * Uses BFS to traverse same-domain links up to `maxPages` pages.
+ * Respects `maxDepth` to limit how deep the crawl goes.
+ */
+export declare function crawlSiteMap(url: string, options?: {
+    maxPages?: number;
+    maxDepth?: number;
+    sameDomain?: boolean;
+}): Promise<SiteMap>;
+/**
+ * Format the site map as a human-readable tree string.
+ */
+export declare function formatSiteMap(siteMap: SiteMap): string;