xcoder-dna 0.0.0-stage → 1.3.1

package/dist/tools/patch-tools.js

@@ -0,0 +1,153 @@
+// xcoder:version 1 | xcoder:task task-e6370a | xcoder:updated 2026-08-12T16:18:11.500Z | xcoder:subtask code-st-cd4444
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { upsertEntry } from "./workspace-index.js";
+import { getCommentSyntax, injectVersionHeader, } from "./file-header-manager.js";
+import { incrementFileVersion } from "../store/file-version-store.js";
+export class WorkspaceEscapeError extends Error {
+}
+/**
+ * Every path a tool touches is resolved and pinned inside the workspace root.
+ * No `..` escapes — the same 8-line guard every other path-taking tool uses.
+ */
+export 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;
+}
+// ---------------------------------------------------------------------------
+// Staleness helpers (AC-11 / AC-19)
+// ---------------------------------------------------------------------------
+/**
+ * Full-file sha1, byte-for-byte identical to the one `workspace-index.ts`
+ * stores per entry — so a sha1 taken here is directly comparable with the
+ * index's value and with the `readSha1` returned by range reads.
+ */
+export async function hashFile(fullPath) {
+    const buf = await fs.readFile(fullPath);
+    return crypto.createHash("sha1").update(buf).digest("hex");
+}
+/**
+ * The reusable staleness core behind every stale-enforced write tool.
+ * Compares the file's CURRENT sha1 against the sha1 the caller observed
+ * earlier (via read_file's `readSha1`). A mismatch means the file changed
+ * under the caller — the write MUST NOT proceed.
+ */
+export async function assertFileUnchanged(fullPath, expectedSha1) {
+    const actualSha1 = await hashFile(fullPath);
+    if (actualSha1 !== expectedSha1)
+        return { ok: false, actualSha1 };
+    return { ok: true };
+}
+/**
+ * Replace lines [startLine..endLine] (1-indexed, inclusive) with newContent.
+ *
+ * Staleness contract: `expectedSha1` is REQUIRED. It must come from the
+ * `readSha1` field of a prior read_file range call. The file is hashed
+ * immediately before any mutation; a mismatch returns `stale` and performs
+ * ZERO writes — never a blind line splice onto a file that changed under
+ * the agent.
+ */
+export async function linePatchTool(root, input, ctx) {
+    if (typeof input.expectedSha1 !== "string" || input.expectedSha1 === "") {
+        return {
+            ok: false,
+            code: "stale_field_missing",
+            error: `line_patch requires "expectedSha1" — the file may have changed since you last read it. ` +
+                `Re-read the file with read_file (a range read includes "readSha1") and pass that sha1 here.`,
+        };
+    }
+    let full;
+    try {
+        full = resolveInWorkspace(root, input.path);
+    }
+    catch (e) {
+        return { ok: false, error: e.message, code: "workspace_escape" };
+    }
+    let content;
+    try {
+        content = await fs.readFile(full, "utf8");
+    }
+    catch {
+        return {
+            ok: false,
+            code: "file_not_found",
+            error: `"${input.path}" doesn't exist or can't be read. Use write_file to create a new file instead of line_patch.`,
+        };
+    }
+    // Range validation BEFORE any mutation.
+    const lines = content.split("\n");
+    const start = Number(input.startLine);
+    const end = Number(input.endLine);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start < 1 || end < start) {
+        return {
+            ok: false,
+            code: "invalid_range",
+            error: `invalid line range [${String(input.startLine)}..${String(input.endLine)}] — startLine must be >= 1 and endLine must be >= startLine.`,
+        };
+    }
+    if (end > lines.length) {
+        return {
+            ok: false,
+            code: "invalid_range",
+            error: `endLine ${end} exceeds the file's ${lines.length} lines. Re-read the file to confirm its current size.`,
+        };
+    }
+    // Staleness check: hash immediately before any write.
+    let checked;
+    try {
+        checked = await assertFileUnchanged(full, input.expectedSha1);
+    }
+    catch (e) {
+        return { ok: false, error: e.message, code: "io_error" };
+    }
+    if (!checked.ok) {
+        return {
+            ok: false,
+            code: "stale",
+            error: `the file changed since you read it (expected sha1 ${input.expectedSha1.slice(0, 12)}, ` +
+                `actual ${checked.actualSha1.slice(0, 12)}). Re-read the file and retry with the fresh readSha1 — no changes were written.`,
+            actualSha1: checked.actualSha1,
+        };
+    }
+    // Line splice: replace [start..end] (1-indexed, inclusive) with newContent.
+    const before = lines.slice(0, start - 1);
+    const after = lines.slice(end);
+    const replacement = input.newContent.split("\n");
+    const nextLines = [...before, ...replacement, ...after];
+    let next = nextLines.join("\n");
+    // Header injection (when context is available and file type supports it).
+    if (ctx) {
+        const syntax = getCommentSyntax(input.path);
+        if (syntax) {
+            try {
+                const meta = await incrementFileVersion(root, input.path, ctx.taskId, ctx.subtaskId);
+                const injected = injectVersionHeader(next, syntax, meta);
+                next = injected.content;
+            }
+            catch (e) {
+                return { ok: false, error: e.message, code: "io_error" };
+            }
+        }
+    }
+    try {
+        await fs.writeFile(full, next, "utf8");
+        await upsertEntry(root, path.relative(root, full));
+        const sha1After = await hashFile(full);
+        return {
+            ok: true,
+            relPath: path.relative(root, full).split(path.sep).join("/"),
+            replacedLines: [start, end],
+            newContentChars: input.newContent.length,
+            linesAfter: next.split("\n").length,
+            sha1After,
+        };
+    }
+    catch (e) {
+        return { ok: false, error: e.message, code: "io_error" };
+    }
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Declarative test steps only — the model describes *what* to do, this
+ * module is the only thing that ever touches a browser or an HTTP client.
+ * That split is what keeps a resolved credential out of the model's
+ * context: the model hands us a `credentialRef` (an env var name); we
+ * resolve it here, use it, and never put the resolved value in the
+ * returned result.
+ */
+export type UiStep = {
+    op: "goto";
+    url: string;
+} | {
+    op: "fill";
+    selector: string;
+    value: string;
+} | {
+    op: "click";
+    selector: string;
+} | {
+    op: "expect_text";
+    selector: string;
+    text: string;
+} | {
+    op: "expect_url";
+    contains: string;
+} | {
+    op: "login_with_credential";
+    usernameSelector: string;
+    passwordSelector: string;
+    submitSelector: string;
+    usernameValue: string;
+};
+export interface UiTestInput {
+    kind: "ui";
+    url: string;
+    credentialRef?: string;
+    steps: UiStep[];
+}
+export interface ApiTestInput {
+    kind: "api";
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    credentialRef?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    expectStatus?: number;
+    expectBodyContains?: string;
+}
+export type PlaywrightToolInput = UiTestInput | ApiTestInput;
+export interface PlaywrightToolResult {
+    ok: boolean;
+    detail: string;
+    steps: {
+        op: string;
+        ok: boolean;
+        note: string;
+    }[];
+}
+export declare function runApiTest(input: ApiTestInput): Promise<PlaywrightToolResult>;
+/**
+ * Requires the optional `playwright` dependency (`npm install`, then
+ * `npx playwright install chromium` once). Imported dynamically so the
+ * rest of Xcoder SDLC works without it if a task never needs a UI test.
+ */
+export declare function runUiTest(input: UiTestInput): Promise<PlaywrightToolResult>;
+export declare function runPlaywrightTool(input: PlaywrightToolInput): Promise<PlaywrightToolResult>;

package/dist/tools/playwright-tool.js

@@ -0,0 +1,121 @@
+import { resolveCredential, redact } from "./credential.js";
+export async function runApiTest(input) {
+    const headers = { ...(input.headers ?? {}) };
+    if (input.credentialRef) {
+        headers["Authorization"] = `Bearer ${resolveCredential(input.credentialRef)}`;
+    }
+    try {
+        const res = await fetch(input.url, {
+            method: input.method,
+            headers,
+            body: input.body !== undefined ? JSON.stringify(input.body) : undefined,
+        });
+        const text = await res.text();
+        const statusOk = input.expectStatus === undefined || res.status === input.expectStatus;
+        const bodyOk = !input.expectBodyContains || text.includes(input.expectBodyContains);
+        const ok = statusOk && bodyOk;
+        const detail = redact(`${input.method} ${input.url} → ${res.status}` +
+            (input.expectStatus !== undefined ? ` (expected ${input.expectStatus})` : "") +
+            (input.expectBodyContains ? `, body ${bodyOk ? "contains" : "MISSING"} expected substring` : ""), input.credentialRef);
+        return {
+            ok,
+            detail,
+            steps: [{ op: "http_request", ok, note: detail }],
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            detail: redact(`request failed: ${e.message}`, input.credentialRef),
+            steps: [{ op: "http_request", ok: false, note: e.message }],
+        };
+    }
+}
+/**
+ * Requires the optional `playwright` dependency (`npm install`, then
+ * `npx playwright install chromium` once). Imported dynamically so the
+ * rest of Xcoder SDLC works without it if a task never needs a UI test.
+ */
+export async function runUiTest(input) {
+    let chromium;
+    try {
+        ({ chromium } = await import("playwright"));
+    }
+    catch {
+        return {
+            ok: false,
+            detail: "the `playwright` package isn't installed. Run `npm install` (it's an " +
+                "optionalDependency) then `npx playwright install chromium`.",
+            steps: [],
+        };
+    }
+    const browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage();
+    const stepResults = [];
+    let overallOk = true;
+    try {
+        await page.goto(input.url, { waitUntil: "domcontentloaded" });
+        stepResults.push({ op: "goto", ok: true, note: input.url });
+        for (const step of input.steps) {
+            try {
+                switch (step.op) {
+                    case "goto":
+                        await page.goto(step.url, { waitUntil: "domcontentloaded" });
+                        stepResults.push({ op: "goto", ok: true, note: step.url });
+                        break;
+                    case "fill":
+                        await page.fill(step.selector, step.value);
+                        stepResults.push({ op: "fill", ok: true, note: step.selector });
+                        break;
+                    case "click":
+                        await page.click(step.selector);
+                        stepResults.push({ op: "click", ok: true, note: step.selector });
+                        break;
+                    case "expect_text": {
+                        const content = await page.textContent(step.selector);
+                        const ok = !!content && content.includes(step.text);
+                        stepResults.push({
+                            op: "expect_text",
+                            ok,
+                            note: ok ? "matched" : `expected "${step.text}", got "${content}"`,
+                        });
+                        if (!ok)
+                            overallOk = false;
+                        break;
+                    }
+                    case "expect_url": {
+                        const ok = page.url().includes(step.contains);
+                        stepResults.push({ op: "expect_url", ok, note: ok ? "matched" : `got ${page.url()}` });
+                        if (!ok)
+                            overallOk = false;
+                        break;
+                    }
+                    case "login_with_credential": {
+                        const password = resolveCredential(input.credentialRef ?? "");
+                        await page.fill(step.usernameSelector, step.usernameValue);
+                        await page.fill(step.passwordSelector, password);
+                        await page.click(step.submitSelector);
+                        stepResults.push({ op: "login_with_credential", ok: true, note: "submitted (value redacted)" });
+                        break;
+                    }
+                }
+            }
+            catch (e) {
+                overallOk = false;
+                stepResults.push({ op: step.op, ok: false, note: redact(e.message, input.credentialRef) });
+                break; // stop on first hard failure — no point clicking further into a broken page
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return {
+        ok: overallOk,
+        detail: overallOk ? "all steps passed" : "one or more steps failed — see `steps`",
+        steps: stepResults,
+    };
+}
+export async function runPlaywrightTool(input) {
+    return input.kind === "api" ? runApiTest(input) : runUiTest(input);
+}

package/dist/tools/project-detect.d.ts

@@ -0,0 +1,20 @@
+import type { WorkspaceIndex } from "./workspace-index.js";
+export interface DetectedCommands {
+    stack: string;
+    build?: string;
+    test?: string;
+    lint?: string;
+    typecheck?: string;
+    reproduceHint: string;
+}
+/**
+ * A guessed set of commands, not a guaranteed one — surfaced to the model
+ * as a strong hint so it calls `run_command` with something that actually
+ * exists in this project instead of assuming `npm test` everywhere (or
+ * `pytest` in a Node project, etc.). This is what "inform the LLM ... run
+ * tests / linter / type-checker / reproduce the bug" means in practice:
+ * give it the real command names up front rather than making it discover
+ * them by trial and error.
+ */
+export declare function detectProjectCommands(root: string, index: WorkspaceIndex): Promise<DetectedCommands>;
+export declare function detectedCommandsPromptBlock(cmds: DetectedCommands): string;

package/dist/tools/project-detect.js

@@ -0,0 +1,87 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * A guessed set of commands, not a guaranteed one — surfaced to the model
+ * as a strong hint so it calls `run_command` with something that actually
+ * exists in this project instead of assuming `npm test` everywhere (or
+ * `pytest` in a Node project, etc.). This is what "inform the LLM ... run
+ * tests / linter / type-checker / reproduce the bug" means in practice:
+ * give it the real command names up front rather than making it discover
+ * them by trial and error.
+ */
+export async function detectProjectCommands(root, index) {
+    const has = (p) => index.entries.some((e) => e.relPath === p);
+    if (has("package.json")) {
+        try {
+            const raw = await fs.readFile(path.join(root, "package.json"), "utf8");
+            const pkg = JSON.parse(raw);
+            const scripts = pkg.scripts ?? {};
+            return {
+                stack: "node",
+                build: scripts.build ? "npm run build" : undefined,
+                test: scripts.test ? "npm test" : undefined,
+                lint: scripts.lint ? "npm run lint" : undefined,
+                typecheck: scripts.typecheck ?? scripts["type-check"] ? "npm run typecheck" : (has("tsconfig.json") ? "npx tsc --noEmit" : undefined),
+                reproduceHint: "Reproduce a reported bug with the narrowest test file/command you can, before writing a fix.",
+            };
+        }
+        catch {
+            return { stack: "node", reproduceHint: "package.json exists but couldn't be parsed — read it directly first." };
+        }
+    }
+    if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) {
+        return {
+            stack: "python",
+            test: "pytest",
+            lint: "ruff check .",
+            typecheck: "mypy .",
+            reproduceHint: "Reproduce with a minimal pytest case before patching.",
+        };
+    }
+    if (has("go.mod")) {
+        return {
+            stack: "go",
+            build: "go build ./...",
+            test: "go test ./...",
+            lint: "go vet ./...",
+            reproduceHint: "Reproduce with a targeted `go test -run <TestName>` before patching.",
+        };
+    }
+    if (index.entries.some((e) => e.relPath.endsWith("pom.xml"))) {
+        return {
+            stack: "java-maven",
+            build: "mvn compile",
+            test: "mvn test",
+            reproduceHint: "Reproduce with a targeted `mvn test -Dtest=<TestClass>` before patching.",
+        };
+    }
+    if (index.entries.some((e) => e.relPath.endsWith("build.gradle") || e.relPath.endsWith("build.gradle.kts"))) {
+        return {
+            stack: "java-gradle",
+            build: "./gradlew build",
+            test: "./gradlew test",
+            reproduceHint: "Reproduce with a targeted `./gradlew test --tests <TestClass>` before patching.",
+        };
+    }
+    return {
+        stack: "unknown",
+        reproduceHint: "No recognized project manifest found in the workspace index. Use `search_workspace`/`glob` to look for a " +
+            "manifest before guessing a build/test command.",
+    };
+}
+export function detectedCommandsPromptBlock(cmds) {
+    const lines = [`## Detected project tooling (stack: ${cmds.stack})`];
+    if (cmds.build)
+        lines.push(`- build: \`${cmds.build}\``);
+    if (cmds.test)
+        lines.push(`- test: \`${cmds.test}\``);
+    if (cmds.lint)
+        lines.push(`- lint: \`${cmds.lint}\``);
+    if (cmds.typecheck)
+        lines.push(`- typecheck: \`${cmds.typecheck}\``);
+    if (!cmds.build && !cmds.test && !cmds.lint && !cmds.typecheck) {
+        lines.push("- (none detected — verify with `search_workspace`/`glob` before assuming a command exists)");
+    }
+    lines.push(cmds.reproduceHint);
+    return lines.join("\n");
+}

package/dist/tools/prompt-guidance.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared cheapest-first guidance fragments, embedded into the manifest
+ * descriptions of the efficient-filesystem toolset so every agent that
+ * renders `buildToolManifest` output (Sub/Samurai/Genesis agents, the
+ * conversation runner, debate, the Samurai CLI, and therefore the SDLC
+ * orchestrator, swarm, healing, and validation-gate paths) automatically
+ * sees the efficiency hierarchy next to each tool.
+ *
+ * The fragments are deliberately plain-language and action-oriented:
+ * they tell the model which cheaper alternative exists for a given tool
+ * BEFORE it spends tokens on the expensive one.
+ */
+export declare const PROMPT_GUIDANCE: {
+    /** Guidance for read-side tools: prefer the cheapest structural read. */
+    readFirst: string;
+    /** Guidance for write-side tools: prefer surgical edits over full rewrites. */
+    editFirst: string;
+    /** Guidance after any edit: validate just the patched file. */
+    validateAfterEdit: string;
+    /** Guidance for source-control reads: prefer summaries over raw output. */
+    gitFirst: string;
+};

package/dist/tools/prompt-guidance.js

@@ -0,0 +1,23 @@
+// xcoder:version 1 | xcoder:task task-e6370a | xcoder:updated 2026-08-12T16:17:53.138Z | xcoder:subtask code-st-cd4444
+/**
+ * Shared cheapest-first guidance fragments, embedded into the manifest
+ * descriptions of the efficient-filesystem toolset so every agent that
+ * renders `buildToolManifest` output (Sub/Samurai/Genesis agents, the
+ * conversation runner, debate, the Samurai CLI, and therefore the SDLC
+ * orchestrator, swarm, healing, and validation-gate paths) automatically
+ * sees the efficiency hierarchy next to each tool.
+ *
+ * The fragments are deliberately plain-language and action-oriented:
+ * they tell the model which cheaper alternative exists for a given tool
+ * BEFORE it spends tokens on the expensive one.
+ */
+export const PROMPT_GUIDANCE = {
+    /** Guidance for read-side tools: prefer the cheapest structural read. */
+    readFirst: "Cheapest read first: read_outline for a structural skeleton, or read_multiple_files for batched sections — before read_file/read_full_file.",
+    /** Guidance for write-side tools: prefer surgical edits over full rewrites. */
+    editFirst: "Cheapest edit first: line_patch / edit_file / sed_tool for surgical changes; write_file only for new files or genuine full rewrites (add force: true above 200 lines).",
+    /** Guidance after any edit: validate just the patched file. */
+    validateAfterEdit: "After any edit, call validate_file to syntax/type-check the patched file before moving on.",
+    /** Guidance for source-control reads: prefer summaries over raw output. */
+    gitFirst: "Prefer git_diff / git_log (low-token summaries) over raw run_command git invocations — cheaper and workspace-pinned.",
+};

package/dist/tools/scheduleTool.d.ts

@@ -0,0 +1,19 @@
+export interface ScheduledJob {
+    id: string;
+    cronExpr: string;
+    command: string;
+}
+/** Registers a recurring job: cron on POSIX, a translated Windows Task Scheduler task on
+ *  win32, tagged with an id for later listing/removal. */
+export declare function scheduleCron(id: string, cronExpr: string, command: string): Promise<{
+    id: string;
+    cronExpr: string;
+}>;
+/** Schedules a one-off command to run after `delaySeconds`, surviving beyond the current process. */
+export declare function scheduleOnce(delaySeconds: number, command: string): Promise<{
+    scheduledFor: string;
+}>;
+export declare function listScheduled(): Promise<ScheduledJob[]>;
+export declare function removeScheduled(id: string): Promise<{
+    removed: boolean;
+}>;