nolo-cli 0.1.23 → 0.1.29

package/server/handlers/applyLineEditsHandler.ts

@@ -0,0 +1,1058 @@
+// 文件路径: packages/server/handlers/applyLineEditsHandler.ts
+
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { file as bunFile, write as bunWrite } from "bun";
+import { diffLines } from "diff";
+
+const ALLOW_TYPECHECK_BYPASS = process.env.ALLOW_TYPECHECK_BYPASS === "1";
+const DEFAULT_TYPECHECK_TIMEOUT_MS = 15000;
+type CodeEditValidationMode = "syntax" | "typecheck" | "none";
+const DEFAULT_CODE_EDIT_VALIDATION_MODE: CodeEditValidationMode = "syntax";
+
+type LineEditCommon = {
+    /**
+     * 可选：LLM 在规划这次编辑时看到的原始代码片段。
+     *
+     * 用法建议：
+     * - replaceRange / deleteRange：填入 startLine~endLine 对应的那几行原文（用 \n 拼起来）。
+     * - insertBefore / insertAfter：填入插入点附近的一两行（通常是插入点所在行）。
+     *
+     * 行为（提高成功率，而不是拦截）：
+     * - 后端会把传入的 startLine / endLine / line 当成“粗定位”；
+     * - 若提供 originalSnippet，会在这个行号附近优先搜索同样的片段；
+     * - 若能在附近找到，就以搜索结果为准自动纠正编辑位置；
+     * - 若找不到，则退化为直接按行号编辑（与当前行为一致），不会额外拒绝。
+     */
+    originalSnippet?: string;
+};
+
+type ReplaceRangeEdit = LineEditCommon & {
+    type: "replaceRange";
+    startLine: number;
+    endLine: number;
+    replacement: string;
+};
+
+type InsertBeforeEdit = LineEditCommon & {
+    type: "insertBefore";
+    line: number;
+    content: string;
+};
+
+type InsertAfterEdit = LineEditCommon & {
+    type: "insertAfter";
+    line: number;
+    content: string;
+};
+
+type DeleteRangeEdit = LineEditCommon & {
+    type: "deleteRange";
+    startLine: number;
+    endLine: number;
+};
+
+type LineEdit =
+    | ReplaceRangeEdit
+    | InsertBeforeEdit
+    | InsertAfterEdit
+    | DeleteRangeEdit;
+
+interface ApplyLineEditsRequestBody {
+    filePath: string;
+    edits: LineEdit[];
+}
+
+export type TypeCheckResult =
+    | {
+          success: true;
+          kind: "ok";
+          errors: string[];
+      }
+    | {
+          success: false;
+          kind: "syntax-errors" | "type-errors" | "timeout" | "unavailable";
+          errors: string[];
+      };
+
+type TypeCheckFailureResult = Extract<TypeCheckResult, { success: false }>;
+
+const JSON_HEADERS = {
+    "Content-Type": "application/json; charset=utf-8",
+    "Access-Control-Allow-Origin": "*",
+};
+
+// 与 read/write/list/search 保持一致：以当前进程工作目录作为项目根
+const PROJECT_ROOT = path.resolve(process.env.PROJECT_ROOT ?? process.cwd());
+const CODE_EDIT_VALIDATION_MODE = parseCodeEditValidationMode(
+    process.env.CODE_EDIT_VALIDATION_MODE
+);
+const TYPECHECK_TIMEOUT_MS = parsePositiveTimeoutMs(
+    process.env.TYPECHECK_TIMEOUT_MS,
+    DEFAULT_TYPECHECK_TIMEOUT_MS
+);
+
+function parseCodeEditValidationMode(
+    value: string | undefined
+): CodeEditValidationMode {
+    switch (value) {
+        case "none":
+        case "typecheck":
+        case "syntax":
+            return value;
+        default:
+            return DEFAULT_CODE_EDIT_VALIDATION_MODE;
+    }
+}
+
+function parsePositiveTimeoutMs(value: string | undefined, fallback: number): number {
+    if (!value) return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return Math.floor(parsed);
+}
+
+function typeCheckSuccessResult(): TypeCheckResult {
+    return { success: true, kind: "ok", errors: [] };
+}
+
+export function shouldBypassTypeCheckFailure(
+    result: TypeCheckFailureResult,
+    allowBypass = ALLOW_TYPECHECK_BYPASS
+): boolean {
+    if (!allowBypass) return false;
+    return result.kind === "timeout" || result.kind === "unavailable";
+}
+
+function typeCheckFailureResult(
+    kind: TypeCheckFailureResult["kind"],
+    errors: string[]
+): TypeCheckFailureResult {
+    return { success: false, kind, errors };
+}
+
+function isTypeCheckResult(value: unknown): value is TypeCheckResult {
+    if (!value || typeof value !== "object") return false;
+    const candidate = value as Partial<TypeCheckResult>;
+    return (
+        typeof candidate.success === "boolean" &&
+        (candidate.kind === "ok" ||
+            candidate.kind === "syntax-errors" ||
+            candidate.kind === "type-errors" ||
+            candidate.kind === "timeout" ||
+            candidate.kind === "unavailable") &&
+        Array.isArray(candidate.errors) &&
+        candidate.errors.every((item) => typeof item === "string")
+    );
+}
+
+function getDisplayPath(filePath: string): string {
+    const relativePath = path.relative(PROJECT_ROOT, filePath);
+    return relativePath && !relativePath.startsWith("..") ? relativePath : filePath;
+}
+
+function getTypeCheckWorkerPath(): string {
+    return path.join(PROJECT_ROOT, "packages/server/handlers/typecheckWorker.ts");
+}
+
+function getTypeCheckRuntime(): string {
+    return Bun.which("bun") ?? process.execPath;
+}
+
+function getSyntaxLoader(filePath: string): "js" | "jsx" | "ts" | "tsx" | null {
+    switch (path.extname(filePath).toLowerCase()) {
+        case ".js":
+            return "js";
+        case ".jsx":
+            return "jsx";
+        case ".ts":
+            return "ts";
+        case ".tsx":
+            return "tsx";
+        default:
+            return null;
+    }
+}
+
+function formatWorkerStream(text: string): string[] {
+    const trimmed = text.trim();
+    if (!trimmed) return [];
+    return trimmed
+        .split("\n")
+        .slice(0, 6)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+
+async function performTypeCheckInSubprocess(
+    filePath: string,
+    content: string,
+    originalContent: string
+): Promise<TypeCheckResult> {
+    const workerPath = getTypeCheckWorkerPath();
+    const displayPath = getDisplayPath(filePath);
+
+    return await new Promise<TypeCheckResult>((resolve) => {
+        let settled = false;
+        let stdout = "";
+        let stderr = "";
+
+        const finish = (result: TypeCheckResult) => {
+            if (settled) return;
+            settled = true;
+            resolve(result);
+        };
+
+        const child = spawn(getTypeCheckRuntime(), [workerPath], {
+            cwd: PROJECT_ROOT,
+            env: process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            finish(
+                typeCheckFailureResult("timeout", [
+                    `Type check timed out after ${TYPECHECK_TIMEOUT_MS}ms for ${displayPath}.`,
+                ])
+            );
+        }, TYPECHECK_TIMEOUT_MS);
+
+        const finishAndCleanup = (result: TypeCheckResult) => {
+            clearTimeout(timer);
+            finish(result);
+        };
+
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk: string) => {
+            stdout += chunk;
+        });
+
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk: string) => {
+            stderr += chunk;
+        });
+
+        child.on("error", (error) => {
+            finishAndCleanup(
+                typeCheckFailureResult("unavailable", [
+                    `Type check worker failed to start for ${displayPath}: ${error.message}`,
+                ])
+            );
+        });
+
+        child.stdin.on("error", (error) => {
+            finishAndCleanup(
+                typeCheckFailureResult("unavailable", [
+                    `Failed to send type check payload for ${displayPath}: ${error.message}`,
+                ])
+            );
+        });
+
+        child.on("close", (code, signal) => {
+            if (settled) return;
+            clearTimeout(timer);
+
+            const trimmedStdout = stdout.trim();
+            if (code === 0) {
+                if (!trimmedStdout) {
+                    finish(
+                        typeCheckFailureResult("unavailable", [
+                            `Type check worker returned no result for ${displayPath}.`,
+                            ...formatWorkerStream(stderr),
+                        ])
+                    );
+                    return;
+                }
+
+                try {
+                    const parsed = JSON.parse(trimmedStdout);
+                    if (!isTypeCheckResult(parsed)) {
+                        throw new Error("Worker returned invalid type check result shape.");
+                    }
+                    finish(parsed);
+                    return;
+                } catch (error) {
+                    finish(
+                        typeCheckFailureResult("unavailable", [
+                            `Failed to parse type check worker output for ${displayPath}: ${
+                                error instanceof Error ? error.message : String(error)
+                            }`,
+                            ...formatWorkerStream(stderr),
+                        ])
+                    );
+                    return;
+                }
+            }
+
+            finish(
+                typeCheckFailureResult("unavailable", [
+                    `Type check worker exited unexpectedly for ${displayPath}: code=${code ?? "null"} signal=${signal ?? "none"}.`,
+                    ...formatWorkerStream(stderr),
+                    ...formatWorkerStream(trimmedStdout),
+                ])
+            );
+        });
+
+        child.stdin.end(
+            JSON.stringify({
+                filePath,
+                content,
+                originalContent,
+            })
+        );
+    });
+}
+
+export function performSyntaxCheck(
+    filePath: string,
+    content: string
+): TypeCheckResult {
+    const loader = getSyntaxLoader(filePath);
+    if (!loader) {
+        return typeCheckSuccessResult();
+    }
+
+    try {
+        new Bun.Transpiler({ loader }).transformSync(content);
+        return typeCheckSuccessResult();
+    } catch (error) {
+        return typeCheckFailureResult("syntax-errors", [
+            `Syntax error in ${getDisplayPath(filePath)}: ${
+                error instanceof Error ? error.message : String(error)
+            }`,
+        ]);
+    }
+}
+
+export function buildTypeCheckFailureResponse(
+    filePath: string,
+    result: TypeCheckFailureResult
+): {
+    status: number;
+    body: {
+        success: false;
+        filePath: string;
+        error: string;
+        details: string[];
+        suggestion: string;
+    };
+} {
+    if (result.kind === "syntax-errors") {
+        return {
+            status: 400,
+            body: {
+                success: false,
+                filePath,
+                error: "Syntax check failed",
+                details: result.errors,
+                suggestion: "Please fix the syntax errors above and retry.",
+            },
+        };
+    }
+
+    if (result.kind === "type-errors") {
+        return {
+            status: 400,
+            body: {
+                success: false,
+                filePath,
+                error: "Type check failed",
+                details: result.errors,
+                suggestion: "Please fix the type errors above and retry.",
+            },
+        };
+    }
+
+    const error =
+        result.kind === "timeout"
+            ? "Type check timed out"
+            : "Type checker unavailable";
+
+    return {
+        status: 503,
+        body: {
+            success: false,
+            filePath,
+            error,
+            details: result.errors,
+            suggestion:
+                "Retry later, reduce the edit scope, or set ALLOW_TYPECHECK_BYPASS=1 for emergency override.",
+        },
+    };
+}
+
+/**
+ * 校验并解析 filePath，确保不会跳出 PROJECT_ROOT
+ */
+export function resolveSafePath(filePath: string): string {
+    if (!filePath || typeof filePath !== "string") {
+        throw new Error("Invalid filePath");
+    }
+
+    if (filePath.includes("\0")) {
+        throw new Error("Invalid filePath");
+    }
+
+    const absRoot = path.resolve(PROJECT_ROOT);
+    const absPath = path.resolve(absRoot, filePath);
+    const rel = path.relative(absRoot, absPath);
+
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error("filePath is outside of project root");
+    }
+
+    return absPath;
+}
+
+/**
+ * 对 TypeScript 文件执行完整项目级类型检查（仅在 CODE_EDIT_VALIDATION_MODE=typecheck 时使用）
+ *
+ * 策略：基于项目级 tsconfig + TypeScript Compiler API，
+ * 在内存中覆盖目标文件内容进行检查，不写磁盘临时文件。
+ */
+export async function performTypeCheckInProcess(
+    filePath: string,
+    content: string,
+    _originalContent: string
+): Promise<TypeCheckResult> {
+    try {
+        // 只检查 .ts 和 .tsx 文件
+        if (!filePath.match(/\.(ts|tsx)$/i)) {
+            return typeCheckSuccessResult();
+        }
+
+        const tsModule = await import("typescript").catch(() => null);
+        if (!tsModule) {
+            if (ALLOW_TYPECHECK_BYPASS) {
+                console.warn("[performTypeCheck] TypeScript module not found, bypassing type check");
+                return typeCheckSuccessResult();
+            }
+            return typeCheckFailureResult("unavailable", ["TypeScript module not found"]);
+        }
+
+        const ts = tsModule.default ?? tsModule;
+        const configFilePath = ts.findConfigFile(PROJECT_ROOT, ts.sys.fileExists, "tsconfig.json");
+        if (!configFilePath) {
+            if (ALLOW_TYPECHECK_BYPASS) {
+                console.warn("[performTypeCheck] tsconfig.json not found, bypassing type check");
+                return typeCheckSuccessResult();
+            }
+            return typeCheckFailureResult("unavailable", [
+                "tsconfig.json not found in project root",
+            ]);
+        }
+
+        const configRead = ts.readConfigFile(configFilePath, ts.sys.readFile);
+        if (configRead.error) {
+            const message = ts.flattenDiagnosticMessageText(configRead.error.messageText, "\n");
+            return typeCheckFailureResult("unavailable", [
+                `TS${configRead.error.code}: ${message}`,
+            ]);
+        }
+
+        const parsedConfig = ts.parseJsonConfigFileContent(
+            configRead.config,
+            ts.sys,
+            path.dirname(configFilePath),
+            undefined,
+            configFilePath
+        );
+        if (parsedConfig.errors && parsedConfig.errors.length > 0) {
+            const errors = parsedConfig.errors
+                .slice(0, 10)
+                .map((diag: any) => `TS${diag.code}: ${ts.flattenDiagnosticMessageText(diag.messageText, "\n")}`);
+            return typeCheckFailureResult("unavailable", errors);
+        }
+
+        const targetAbsPath = path.resolve(filePath);
+        const rootNames = parsedConfig.fileNames.includes(targetAbsPath)
+            ? parsedConfig.fileNames
+            : [...parsedConfig.fileNames, targetAbsPath];
+
+        const compilerOptions = {
+            ...parsedConfig.options,
+            noEmit: true,
+        };
+
+        const host = ts.createCompilerHost(compilerOptions, true);
+        const originalReadFile = host.readFile;
+        host.readFile = (name: string): string | undefined => {
+            if (path.resolve(name) === targetAbsPath) {
+                return content;
+            }
+            return originalReadFile(name);
+        };
+
+        const program = ts.createProgram({
+            rootNames,
+            options: compilerOptions,
+            host,
+            projectReferences: parsedConfig.projectReferences,
+        });
+
+        const allDiagnostics = ts.getPreEmitDiagnostics(program);
+        const fileDiagnostics = allDiagnostics.filter((diag: any) => {
+            if (!diag.file?.fileName) return false;
+            return path.resolve(diag.file.fileName) === targetAbsPath;
+        });
+
+        const blockingDiagnostics = fileDiagnostics.filter((diag: any) => diag.code !== 2307);
+
+        if (blockingDiagnostics.length > 0) {
+            const errors = blockingDiagnostics.slice(0, 10).map((diag: any) => {
+                const message = ts.flattenDiagnosticMessageText(diag.messageText, "\n");
+                return `TS${diag.code}: ${message}`;
+            });
+            return typeCheckFailureResult("type-errors", errors);
+        }
+
+        return typeCheckSuccessResult();
+    } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+
+        if (ALLOW_TYPECHECK_BYPASS) {
+            console.warn("[performTypeCheck] Type check bypassed due to ALLOW_TYPECHECK_BYPASS=1:", message);
+            return typeCheckSuccessResult();
+        }
+        return typeCheckFailureResult("unavailable", [
+                `Type checker unavailable: ${message}`,
+                "Install TypeScript (tsc) on server or set ALLOW_TYPECHECK_BYPASS=1 for emergency override.",
+            ]);
+    }
+}
+
+export async function performTypeCheck(
+    filePath: string,
+    content: string,
+    originalContent: string
+): Promise<TypeCheckResult> {
+    const displayPath = getDisplayPath(filePath);
+    const startedAt = Date.now();
+    console.log(
+        `[performTypeCheck] start file=${displayPath} mode=${CODE_EDIT_VALIDATION_MODE} timeoutMs=${TYPECHECK_TIMEOUT_MS}`
+    );
+
+    let result: TypeCheckResult;
+    if (CODE_EDIT_VALIDATION_MODE === "none") {
+        result = typeCheckSuccessResult();
+    } else if (CODE_EDIT_VALIDATION_MODE === "syntax") {
+        result = performSyntaxCheck(filePath, content);
+    } else {
+        try {
+            result = await performTypeCheckInSubprocess(
+                filePath,
+                content,
+                originalContent
+            );
+        } catch (error) {
+            result = typeCheckFailureResult("unavailable", [
+                `Failed to run type check for ${displayPath}: ${
+                    error instanceof Error ? error.message : String(error)
+                }`,
+            ]);
+        }
+    }
+
+    if (!result.success && shouldBypassTypeCheckFailure(result)) {
+        console.warn(
+            `[performTypeCheck] bypassing ${result.kind} for ${displayPath} because ALLOW_TYPECHECK_BYPASS=1`
+        );
+        result = typeCheckSuccessResult();
+    }
+
+    console.log(
+        `[performTypeCheck] done file=${displayPath} mode=${CODE_EDIT_VALIDATION_MODE} success=${result.success} kind=${result.kind} durationMs=${
+            Date.now() - startedAt
+        }`
+    );
+    return result;
+}
+
+/** 校验并强制解析为正整数：支持字符串数字（"5"）和整数浮点（5.0），<= 0 报验证错误 */
+export function ensurePositiveInt(value: unknown, name: string): number {
+    let n: number;
+    if (typeof value === "string") {
+        n = Number(value);
+    } else if (typeof value === "number") {
+        n = value;
+    } else {
+        throw Object.assign(new Error(`${name} must be positive integer, got ${JSON.stringify(value)}`), { isValidation: true });
+    }
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+        // 对整数浮点（如 5.0）做自动取整
+        const floored = Math.floor(n);
+        if (floored > 0 && Math.abs(n - floored) < 1e-9) return floored;
+        throw Object.assign(new Error(`${name} must be positive integer, got ${value}`), { isValidation: true });
+    }
+    return n;
+}
+
+// ---- snippet 辅助函数（纯函数，方便单测）----
+
+type LineRange = { startLine: number; endLine: number };
+
+/**
+ * 把 \r\n 正规化成 \n 再按行拆分。
+ */
+export function splitToLines(text: string): string[] {
+    if (!text) return [];
+    const normalized =
+        text.indexOf("\r\n") >= 0 ? text.replace(/\r\n/g, "\n") : text;
+    return normalized.split("\n");
+}
+
+/**
+ * 在 hint 附近的窗口里寻找 snippetLines 的精确匹配（按行完全相等）。
+ * 找到则返回实际的 [startLine, endLine]（1-based），否则返回 null。
+ */
+function findSnippetAroundHint(
+    fileLines: string[],
+    snippetLines: string[],
+    hintStartLine: number,
+    windowRadius: number
+): LineRange | null {
+    if (snippetLines.length === 0 || fileLines.length === 0) return null;
+    if (snippetLines.length > fileLines.length) return null;
+
+    const n = fileLines.length;
+    const m = snippetLines.length;
+
+    const hintIndex = Math.min(Math.max(hintStartLine - 1, 0), n - 1);
+    const startIndex = Math.max(0, hintIndex - windowRadius);
+    const endIndex = Math.min(n - m, hintIndex + windowRadius);
+
+    for (let i = startIndex; i <= endIndex; i++) {
+        let match = true;
+        for (let j = 0; j < m; j++) {
+            if (fileLines[i + j] !== snippetLines[j]) {
+                match = false;
+                break;
+            }
+        }
+        if (match) {
+            return { startLine: i + 1, endLine: i + m };
+        }
+    }
+    return null;
+}
+
+/**
+ * 在整个文件里寻找 snippetLines 的第一次精确匹配。
+ * 找到则返回 [startLine, endLine]，否则 null。
+ */
+function findSnippetInFile(
+    fileLines: string[],
+    snippetLines: string[]
+): LineRange | null {
+    if (snippetLines.length === 0 || fileLines.length === 0) return null;
+    if (snippetLines.length > fileLines.length) return null;
+
+    const n = fileLines.length;
+    const m = snippetLines.length;
+
+    for (let i = 0; i <= n - m; i++) {
+        let match = true;
+        for (let j = 0; j < m; j++) {
+            if (fileLines[i + j] !== snippetLines[j]) {
+                match = false;
+                break;
+            }
+        }
+        if (match) {
+            return { startLine: i + 1, endLine: i + m };
+        }
+    }
+    return null;
+}
+
+/**
+ * 综合行号+snippet，给出“最佳行区间”：
+ * - 先在 hint 附近的窗口里找 snippet；
+ * - 找不到再全文件找；
+ * - 全都找不到则退回原始 hint 区间（裁剪到合法范围）。
+ */
+export function resolveRangeWithSnippet(
+    fileLines: string[],
+    hintRange: LineRange,
+    originalSnippet?: string
+): LineRange {
+    const totalLines = fileLines.length;
+    if (!totalLines) {
+        return { startLine: 1, endLine: 0 }; // 空文件，后续逻辑会特别处理
+    }
+
+    // 先把 hint 行号裁剪到 [1, totalLines]
+    const boundedStart = Math.min(
+        Math.max(hintRange.startLine, 1),
+        totalLines
+    );
+    const boundedEnd = Math.min(
+        Math.max(hintRange.endLine, boundedStart),
+        totalLines
+    );
+    let bestRange: LineRange = {
+        startLine: boundedStart,
+        endLine: boundedEnd,
+    };
+
+    if (!originalSnippet) {
+        return bestRange;
+    }
+
+    const snippetLines = splitToLines(originalSnippet);
+    if (snippetLines.length === 0) {
+        return bestRange;
+    }
+
+    const windowRadius = 50;
+
+    const around = findSnippetAroundHint(
+        fileLines,
+        snippetLines,
+        hintRange.startLine,
+        windowRadius
+    );
+    if (around) {
+        return around;
+    }
+
+    const anywhere = findSnippetInFile(fileLines, snippetLines);
+    if (anywhere) {
+        return anywhere;
+    }
+
+    // 找不到 snippet，就退回裁剪后的 hint 区间，不额外报错
+    return bestRange;
+}
+
+/**
+ * 对 insertBefore/insertAfter：用 originalSnippet 当锚点定位插入行。
+ * - 若 snippet 能找到，则以 snippet 的起始或结束行为基准插入；
+ * - 若找不到，则退化为用行号（并裁剪到合法范围）。
+ */
+export function resolveInsertLineWithSnippet(
+    fileLines: string[],
+    hintLine: number,
+    originalSnippet: string | undefined,
+    mode: "before" | "after"
+): number {
+    const totalLines = fileLines.length;
+    if (!totalLines) {
+        // 空文件：insertBefore(1)/insertAfter(1) 都等价于在文件头（也是尾）追加
+        return 1;
+    }
+
+    const maxLine = mode === "before" ? totalLines + 1 : totalLines;
+    const boundedLine = Math.min(Math.max(hintLine, 1), maxLine);
+
+    if (!originalSnippet) {
+        return mode === "before" ? boundedLine : boundedLine;
+    }
+
+    const snippetLines = splitToLines(originalSnippet);
+    if (snippetLines.length === 0 || snippetLines.length > totalLines) {
+        return mode === "before" ? boundedLine : boundedLine;
+    }
+
+    const windowRadius = 50;
+    const around = findSnippetAroundHint(
+        fileLines,
+        snippetLines,
+        hintLine,
+        windowRadius
+    );
+    const anywhere = around ?? findSnippetInFile(fileLines, snippetLines);
+
+    if (!anywhere) {
+        return mode === "before" ? boundedLine : boundedLine;
+    }
+
+    if (mode === "before") {
+        return anywhere.startLine;
+    }
+    // after：插在 snippet 之后一行
+    return anywhere.endLine;
+}
+
+/**
+ * 在内存中按顺序应用一组 LineEdit。
+ * 注意：后续 edit 的“hint 行号”是基于“前一个 edit 应用之后”的文本。
+ * 使用统一的 \n 作为行分隔符。
+ */
+export function applyLineEditsToText(original: string, edits: LineEdit[]): string {
+    let text = original;
+
+    for (let i = 0; i < edits.length; i++) {
+        const edit = edits[i];
+        const lines = text.split(/\n/); // original 已经是统一的 \n
+
+        switch (edit.type) {
+            case "replaceRange": {
+                // 若提供了 originalSnippet，行号作为搜索 hint 可以缺省（默认 1）
+                const startLineHint = (edit.startLine == null && edit.originalSnippet)
+                    ? 1
+                    : ensurePositiveInt(edit.startLine, "startLine");
+                const endLineHint = (edit.endLine == null && edit.originalSnippet)
+                    ? 1
+                    : ensurePositiveInt(edit.endLine, "endLine");
+                if (startLineHint > endLineHint) {
+                    throw new Error(
+                        "startLine must be <= endLine for replaceRange"
+                    );
+                }
+
+                const resolved = resolveRangeWithSnippet(
+                    lines,
+                    { startLine: startLineHint, endLine: endLineHint },
+                    edit.originalSnippet
+                );
+
+                const before = lines.slice(0, resolved.startLine - 1);
+                const after = lines.slice(resolved.endLine);
+                // 兼容模型有时误用 newSnippet 字段（正确字段名为 replacement）
+                const replacementText = edit.replacement ?? (edit as any).newSnippet;
+                const replacementLines = replacementText
+                    ? splitToLines(replacementText)
+                    : [];
+
+                text = [...before, ...replacementLines, ...after].join("\n");
+                break;
+            }
+            case "insertBefore": {
+                const lineHint = (edit.line == null && edit.originalSnippet)
+                    ? 1
+                    : ensurePositiveInt(edit.line, "line");
+                const insertLine = resolveInsertLineWithSnippet(
+                    lines,
+                    lineHint,
+                    edit.originalSnippet,
+                    "before"
+                );
+                const insertIndex = Math.min(insertLine - 1, lines.length);
+                const before = lines.slice(0, insertIndex);
+                const after = lines.slice(insertIndex);
+                const insertLines = edit.content
+                    ? splitToLines(edit.content)
+                    : [];
+
+                text = [...before, ...insertLines, ...after].join("\n");
+                break;
+            }
+            case "insertAfter": {
+                const lineHint = (edit.line == null && edit.originalSnippet)
+                    ? 1
+                    : ensurePositiveInt(edit.line, "line");
+                const anchorLine = resolveInsertLineWithSnippet(
+                    lines,
+                    lineHint,
+                    edit.originalSnippet,
+                    "after"
+                );
+                const insertIndex = Math.min(anchorLine, lines.length);
+                const before = lines.slice(0, insertIndex);
+                const after = lines.slice(insertIndex);
+                const insertLines = edit.content
+                    ? splitToLines(edit.content)
+                    : [];
+
+                text = [...before, ...insertLines, ...after].join("\n");
+                break;
+            }
+            case "deleteRange": {
+                const startLineHint = (edit.startLine == null && edit.originalSnippet)
+                    ? 1
+                    : ensurePositiveInt(edit.startLine, "startLine");
+                const endLineHint = (edit.endLine == null && edit.originalSnippet)
+                    ? 1
+                    : ensurePositiveInt(edit.endLine, "endLine");
+                if (startLineHint > endLineHint) {
+                    throw new Error(
+                        "startLine must be <= endLine for deleteRange"
+                    );
+                }
+
+                const resolved = resolveRangeWithSnippet(
+                    lines,
+                    { startLine: startLineHint, endLine: endLineHint },
+                    edit.originalSnippet
+                );
+
+                const before = lines.slice(0, resolved.startLine - 1);
+                const after = lines.slice(resolved.endLine);
+                text = [...before, ...after].join("\n");
+                break;
+            }
+            default: {
+                const _exhaustiveCheck: never = edit;
+                throw new Error(
+                    `Unsupported line edit type: ${(edit as any).type}`
+                );
+            }
+        }
+    }
+
+    return text;
+}
+
+export async function handleApplyLineEdits(req: Request): Promise<Response> {
+    try {
+        const body = (await req.json()) as Partial<ApplyLineEditsRequestBody>;
+
+        if (!body.filePath || !Array.isArray(body.edits) || body.edits.length === 0) {
+            return new Response(
+                JSON.stringify({
+                    error: "filePath and non-empty edits are required",
+                }),
+                { status: 400, headers: JSON_HEADERS }
+            );
+        }
+
+        const targetPath = resolveSafePath(body.filePath);
+
+        // 读原文件内容
+        let originalRaw: string;
+        try {
+            originalRaw = await bunFile(targetPath).text();
+        } catch (e: any) {
+            const code = e?.code || e?.errno || e?.name;
+            const msg = String(e?.message || "");
+            if (code === "ENOENT" || /ENOENT|no such file|not exist/i.test(msg)) {
+                return new Response(
+                    JSON.stringify({
+                        error: `File does not exist: ${body.filePath}`,
+                    }),
+                    { status: 404, headers: JSON_HEADERS }
+                );
+            }
+
+            console.error(
+                "[handleApplyLineEdits] read file error:",
+                e,
+                "targetPath:",
+                targetPath
+            );
+            return new Response(
+                JSON.stringify({
+                    error: `File cannot be read: ${body.filePath}`,
+                }),
+                { status: 500, headers: JSON_HEADERS }
+            );
+        }
+
+        // 记录原始换行风格，便于最终写回时保持一致
+        const hadCRLF = originalRaw.indexOf("\r\n") >= 0;
+        const originalText = hadCRLF
+            ? originalRaw.replace(/\r\n/g, "\n")
+            : originalRaw;
+
+        // 在内存中应用编辑（基于统一的 \n）
+        const editSummary = (body.edits as LineEdit[]).map((e: any) =>
+            e.type === "replaceRange" || e.type === "deleteRange"
+                ? `${e.type}(${e.startLine}-${e.endLine})`
+                : `${e.type}(L${e.line})`
+        ).join(", ");
+        console.log(`[applyLineEdits] file=${body.filePath} edits=[${editSummary}]`);
+        const newText = applyLineEditsToText(
+            originalText,
+            body.edits as LineEdit[]
+        );
+
+        // 若内容未变化，可早退
+        if (newText === originalText) {
+            return new Response(
+                JSON.stringify({
+                    success: true,
+                    filePath: body.filePath,
+                    editCount: body.edits.length,
+                    changed: false,
+                    message: "Edits applied but content is identical to original.",
+                    newContent: newText,
+                    diff: [], // 没变化就给空 diff
+                }),
+                { status: 200, headers: JSON_HEADERS }
+            );
+        }
+
+        // 对 TypeScript 文件执行轻量校验（默认语法检查，可切换到完整类型检查）
+        const isTypeScriptFile = /\.(ts|tsx)$/i.test(body.filePath);
+        if (isTypeScriptFile) {
+            console.log(`[applyLineEdits] validate:start file=${body.filePath}`);
+            const typeCheckResult = await performTypeCheck(targetPath, newText, originalText);
+            console.log(
+                `[applyLineEdits] validate:done file=${body.filePath} success=${typeCheckResult.success} kind=${typeCheckResult.kind}`
+            );
+            if (!typeCheckResult.success) {
+                console.warn(`[applyLineEdits] validation failed for ${body.filePath}:`, typeCheckResult.errors);
+                const failure = buildTypeCheckFailureResponse(
+                    body.filePath,
+                    typeCheckResult
+                );
+                return new Response(
+                    JSON.stringify(failure.body),
+                    { status: failure.status, headers: JSON_HEADERS }
+                );
+            }
+            // 类型检查通过后写入文件
+            const diff = diffLines(originalText, newText);
+            const outputText = hadCRLF ? newText.replace(/\n/g, "\r\n") : newText;
+            const dir = path.dirname(targetPath);
+            console.log(`[applyLineEdits] write:start file=${body.filePath}`);
+            await mkdir(dir, { recursive: true });
+            await bunWrite(targetPath, outputText);
+            console.log(`[applyLineEdits] write:done file=${body.filePath}`);
+            return new Response(
+                JSON.stringify({
+                    success: true,
+                    filePath: body.filePath,
+                    editCount: body.edits.length,
+                    changed: true,
+                    newContent: newText,
+                    diff,
+                }),
+                { status: 200, headers: JSON_HEADERS }
+            );
+        }
+
+        // 生成 diff（基于统一的 \n）
+        const diff = diffLines(originalText, newText);
+
+        // 写回文件时尽量保持原始换行风格
+        const outputText = hadCRLF ? newText.replace(/\n/g, "\r\n") : newText;
+        const dir = path.dirname(targetPath);
+        await mkdir(dir, { recursive: true });
+        await bunWrite(targetPath, outputText);
+
+        return new Response(
+            JSON.stringify({
+                success: true,
+                filePath: body.filePath,
+                editCount: body.edits.length,
+                changed: true,
+                newContent: newText, // 统一为 \n，给前端预览用
+                diff,
+            }),
+            { status: 200, headers: JSON_HEADERS }
+        );
+    } catch (e: any) {
+        const message = e?.message || String(e);
+        // 行号校验错误 → 400（客户端输入问题），其余 → 500（服务器异常）
+        const isValidation = e?.isValidation === true ||
+            /must be positive integer|startLine must be <= endLine/.test(message);
+        if (isValidation) {
+            console.warn("[handleApplyLineEdits] validation error:", message);
+            return new Response(JSON.stringify({ error: message }), {
+                status: 400,
+                headers: JSON_HEADERS,
+            });
+        }
+        console.error("[handleApplyLineEdits] unexpected error:", e);
+        return new Response(JSON.stringify({ error: message }), {
+            status: 500,
+            headers: JSON_HEADERS,
+        });
+    }
+}