@yuaone/core 0.1.0

package/dist/approval.js

@@ -0,0 +1,299 @@
+/**
+ * @module approval
+ * @description 승인 시스템 — 위험 작업 실행 전 사용자 승인 요청/대기.
+ *
+ * 플로우:
+ * 1. Governor가 위험 작업 감지 (ApprovalRequiredError)
+ * 2. ApprovalManager가 승인 요청 이벤트 emit
+ * 3. CLI/UI에서 사용자에게 프롬프트 표시
+ * 4. 사용자 응답 (approve/reject/always_approve)
+ * 5. 결과를 Agent Loop에 반환
+ *
+ * @see 설계 문서 Section 6.3
+ */
+import { EventEmitter } from "node:events";
+// ─── Constants ───
+/** 항상 승인이 필요한 액션 (기본값) */
+const ALWAYS_REQUIRE_APPROVAL = [
+    "DELETE_FILE",
+    "GIT_PUSH",
+    "CREATE_PR",
+];
+/** 도구별 승인 규칙 */
+const TOOL_APPROVAL_RULES = [
+    {
+        toolName: "file_write",
+        actionType: "OVERWRITE_FILE",
+        riskLevel: "medium",
+        // 기존 파일 덮어쓰기일 때만 (새 파일 생성은 승인 불필요)
+        condition: (args) => args.overwrite === true,
+    },
+    {
+        toolName: "shell_exec",
+        actionType: "INSTALL_PACKAGE",
+        riskLevel: "medium",
+        condition: (args) => {
+            const cmd = String(args.command ?? args.cmd ?? "");
+            const exec = String(args.executable ?? "");
+            const full = `${exec} ${cmd}`.trim();
+            return (/\bnpm\s+install\b/.test(full) ||
+                /\bpnpm\s+add\b/.test(full) ||
+                /\byarn\s+add\b/.test(full) ||
+                /\bpip\s+install\b/.test(full));
+        },
+    },
+    {
+        toolName: "shell_exec",
+        actionType: "RUN_DANGEROUS_CMD",
+        riskLevel: "high",
+    },
+    {
+        toolName: "file_write",
+        actionType: "MODIFY_CONFIG",
+        riskLevel: "medium",
+        condition: (args) => {
+            const path = String(args.path ?? args.file ?? "");
+            return /(?:tsconfig|package|\.eslintrc|\.prettierrc|webpack|vite)/.test(path);
+        },
+    },
+    {
+        toolName: "file_edit",
+        actionType: "MODIFY_CONFIG",
+        riskLevel: "medium",
+        condition: (args) => {
+            const path = String(args.path ?? args.file ?? "");
+            return /(?:tsconfig|package|\.eslintrc|\.prettierrc|webpack|vite)/.test(path);
+        },
+    },
+    {
+        toolName: "git_ops",
+        actionType: "GIT_PUSH",
+        riskLevel: "critical",
+        condition: (args) => {
+            const op = String(args.operation ?? args.op ?? "");
+            return op === "push";
+        },
+    },
+];
+// ─── ApprovalManager ───
+/**
+ * ApprovalManager — 위험 작업의 승인 프로세스를 관리.
+ *
+ * 역할:
+ * - 도구 호출이 승인 필요한지 판단
+ * - 승인 요청 생성 및 핸들러 호출
+ * - always_approve 세션 캐시 관리
+ * - 승인 타임아웃 처리
+ *
+ * @example
+ * ```typescript
+ * const manager = new ApprovalManager();
+ *
+ * // CLI에서 핸들러 등록
+ * manager.setHandler(async (request) => {
+ *   const answer = await askUser(`Approve ${request.reason}? [Y/n/a]`);
+ *   if (answer === 'a') return 'always_approve';
+ *   return answer === 'n' ? 'reject' : 'approve';
+ * });
+ *
+ * // Agent Loop에서 사용
+ * if (manager.needsApproval('file_write', args)) {
+ *   const response = await manager.requestApproval(request);
+ *   if (response === 'reject') { ... }
+ * }
+ * ```
+ */
+export class ApprovalManager extends EventEmitter {
+    /** always_approve로 승인된 도구 (세션 내 유지) */
+    alwaysApproved = new Set();
+    /** 자동 승인 설정 */
+    autoApproveActions;
+    /** 항상 승인 필요한 액션 */
+    requireApprovalActions;
+    /** 승인 핸들러 (CLI/UI가 등록) */
+    handler = null;
+    /** 기본 타임아웃 (ms) */
+    defaultTimeout;
+    constructor(config, defaultTimeout = 120_000) {
+        super();
+        this.autoApproveActions = new Set(config?.autoApprove ?? []);
+        this.requireApprovalActions = new Set(config?.requireApproval ?? ALWAYS_REQUIRE_APPROVAL);
+        this.defaultTimeout = defaultTimeout;
+    }
+    /**
+     * 승인 핸들러 등록.
+     * CLI에서 readline 기반 프롬프트, UI에서 웹소켓 기반 프롬프트를 구현한다.
+     * @param handler 승인 요청을 처리할 함수
+     */
+    setHandler(handler) {
+        this.handler = handler;
+    }
+    /**
+     * 도구 호출이 승인 필요한지 판단.
+     * @param toolName 도구 이름
+     * @param args 도구 인자
+     * @returns 승인이 필요하면 해당 ApprovalRequest 정보, 불필요하면 null
+     */
+    checkApproval(toolName, args) {
+        // always_approve된 도구는 스킵
+        const toolKey = this.buildToolKey(toolName, args);
+        if (this.alwaysApproved.has(toolName) || this.alwaysApproved.has(toolKey)) {
+            return null;
+        }
+        // 승인 규칙 매칭
+        for (const rule of TOOL_APPROVAL_RULES) {
+            if (rule.toolName !== toolName)
+                continue;
+            // 조건이 있으면 평가
+            if (rule.condition && !rule.condition(args))
+                continue;
+            // 자동 승인 액션이면 스킵
+            if (this.autoApproveActions.has(rule.actionType) &&
+                !this.requireApprovalActions.has(rule.actionType)) {
+                return null;
+            }
+            // 승인 필요
+            const request = {
+                id: crypto.randomUUID(),
+                toolName,
+                arguments: args,
+                riskLevel: rule.riskLevel,
+                reason: this.buildReason(rule.actionType, toolName, args),
+                diff: this.extractDiff(toolName, args),
+                timeout: this.defaultTimeout,
+            };
+            return request;
+        }
+        return null;
+    }
+    /**
+     * 승인 필요 여부를 간단히 확인하는 편의 메서드.
+     * @param toolName 도구 이름
+     * @param args 도구 인자
+     * @returns 승인이 필요하면 true
+     */
+    needsApproval(toolName, args) {
+        return this.checkApproval(toolName, args) !== null;
+    }
+    /**
+     * 승인 요청을 핸들러에 전달하고 응답을 반환.
+     * 핸들러가 없으면 기본적으로 reject.
+     * @param request 승인 요청
+     * @returns 승인 응답
+     */
+    async requestApproval(request) {
+        this.emit("approval:requested", request);
+        if (!this.handler) {
+            // 핸들러 미등록 → reject (안전 기본값)
+            this.emit("approval:no_handler", request);
+            return "reject";
+        }
+        // 타임아웃 처리 — clear timer after race resolves to prevent leak
+        let timer;
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                this.emit("approval:timeout", request.id);
+                resolve("reject");
+            }, request.timeout);
+        });
+        const response = await Promise.race([
+            this.handler(request),
+            timeoutPromise,
+        ]);
+        clearTimeout(timer);
+        // always_approve 처리
+        if (response === "always_approve") {
+            this.addAlwaysApprove(request.toolName);
+            this.emit("approval:always_approved", request.toolName);
+        }
+        this.emit("approval:responded", { request, response });
+        return response;
+    }
+    /**
+     * 도구를 always_approve 목록에 추가.
+     * 세션 내에서 해당 도구의 모든 호출이 자동 승인된다.
+     * @param toolName 도구 이름
+     */
+    addAlwaysApprove(toolName) {
+        this.alwaysApproved.add(toolName);
+    }
+    /**
+     * always_approve 목록을 초기화.
+     */
+    clearAlwaysApproved() {
+        this.alwaysApproved.clear();
+    }
+    /**
+     * 현재 always_approve 목록을 반환.
+     */
+    getAlwaysApproved() {
+        return this.alwaysApproved;
+    }
+    /**
+     * ToolCall에서 PendingAction을 생성하는 헬퍼.
+     * AgentLoop에서 agent:approval_needed 이벤트 emit에 사용.
+     */
+    buildPendingAction(toolCall, request) {
+        return {
+            id: request.id,
+            type: this.resolveActionType(request.toolName, request.arguments),
+            description: request.reason,
+            details: request.arguments,
+            risk: request.riskLevel === "critical" ? "high" : request.riskLevel,
+            timeout: request.timeout,
+        };
+    }
+    // ─── Private ───
+    buildToolKey(toolName, args) {
+        const path = String(args.path ?? args.file ?? "");
+        return path ? `${toolName}:${path}` : toolName;
+    }
+    buildReason(actionType, toolName, args) {
+        const path = String(args.path ?? args.file ?? "");
+        switch (actionType) {
+            case "DELETE_FILE":
+                return `File deletion: ${path}`;
+            case "OVERWRITE_FILE":
+                return `File overwrite: ${path}`;
+            case "INSTALL_PACKAGE": {
+                const cmd = String(args.command ?? args.cmd ?? "");
+                return `Package installation: ${cmd}`;
+            }
+            case "RUN_DANGEROUS_CMD": {
+                const cmd = String(args.command ?? args.cmd ?? "");
+                return `Dangerous command: ${cmd}`;
+            }
+            case "MODIFY_CONFIG":
+                return `Config file modification: ${path}`;
+            case "GIT_PUSH":
+                return "Git push to remote";
+            case "CREATE_PR":
+                return "Pull request creation";
+            default:
+                return `${toolName} requires approval`;
+        }
+    }
+    extractDiff(toolName, args) {
+        if (toolName === "file_write") {
+            const content = String(args.content ?? "");
+            return content.length > 500 ? content.slice(0, 500) + "\n..." : content;
+        }
+        if (toolName === "file_edit") {
+            const old = String(args.old_string ?? args.old ?? "");
+            const newStr = String(args.new_string ?? args.new ?? "");
+            return `--- old\n${old}\n+++ new\n${newStr}`;
+        }
+        return undefined;
+    }
+    resolveActionType(toolName, args) {
+        for (const rule of TOOL_APPROVAL_RULES) {
+            if (rule.toolName !== toolName)
+                continue;
+            if (rule.condition && !rule.condition(args))
+                continue;
+            return rule.actionType;
+        }
+        return "RUN_DANGEROUS_CMD";
+    }
+}
+//# sourceMappingURL=approval.js.map

package/dist/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"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"}

package/dist/async-completion-queue.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module async-completion-queue
+ * @description 비동기 완료 큐 — 병렬 에이전트 완료 이벤트 수집용.
+ *
+ * 생산자(push)와 소비자(shift)를 비동기로 연결하는 제네릭 큐.
+ * 버퍼에 아이템이 있으면 즉시 반환, 없으면 push될 때까지 대기.
+ */
+/**
+ * 병렬 에이전트 완료 이벤트를 수집하는 비동기 큐.
+ *
+ * @typeParam T - 큐에 저장할 아이템 타입
+ *
+ * @example
+ * ```ts
+ * const queue = new AsyncCompletionQueue<TaskResult>();
+ *
+ * // Producer
+ * queue.push(result);
+ *
+ * // Consumer (awaits if buffer is empty)
+ * const item = await queue.shift();
+ * ```
+ */
+export declare class AsyncCompletionQueue<T> {
+    private buffer;
+    private waiters;
+    /**
+     * 아이템을 큐에 추가한다.
+     * 대기 중인 소비자가 있으면 즉시 전달하고, 없으면 버퍼에 저장한다.
+     *
+     * @param item - 큐에 추가할 아이템
+     */
+    push(item: T): void;
+    /**
+     * 큐에서 아이템을 하나 꺼낸다.
+     * 버퍼에 아이템이 있으면 즉시 반환하고, 없으면 push될 때까지 대기한다.
+     *
+     * @returns 큐에서 꺼낸 아이템
+     */
+    shift(): Promise<T>;
+    /**
+     * 현재 버퍼에 있는 모든 아이템을 즉시 반환한다 (논블로킹, 동기).
+     * 반환 후 버퍼는 비워진다.
+     *
+     * Note: 의도적으로 동기 메서드입니다. dag-orchestrator의 for...of 루프에서
+     * 즉시 반환이 필요하므로 async가 아닌 sync로 유지합니다.
+     *
+     * @returns 버퍼에 있던 모든 아이템 배열
+     */
+    drain(): T[];
+    /**
+     * 현재 버퍼에 대기 중인 아이템 수.
+     */
+    get length(): number;
+}
+//# sourceMappingURL=async-completion-queue.d.ts.map

package/dist/async-completion-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-completion-queue.d.ts","sourceRoot":"","sources":["../src/async-completion-queue.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IACjC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,OAAO,CAAgC;IAE/C;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IASnB;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC;IAUzB;;;;;;;;OAQG;IACH,KAAK,IAAI,CAAC,EAAE;IAKZ;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;CACF"}

package/dist/async-completion-queue.js

@@ -0,0 +1,77 @@
+/**
+ * @module async-completion-queue
+ * @description 비동기 완료 큐 — 병렬 에이전트 완료 이벤트 수집용.
+ *
+ * 생산자(push)와 소비자(shift)를 비동기로 연결하는 제네릭 큐.
+ * 버퍼에 아이템이 있으면 즉시 반환, 없으면 push될 때까지 대기.
+ */
+/**
+ * 병렬 에이전트 완료 이벤트를 수집하는 비동기 큐.
+ *
+ * @typeParam T - 큐에 저장할 아이템 타입
+ *
+ * @example
+ * ```ts
+ * const queue = new AsyncCompletionQueue<TaskResult>();
+ *
+ * // Producer
+ * queue.push(result);
+ *
+ * // Consumer (awaits if buffer is empty)
+ * const item = await queue.shift();
+ * ```
+ */
+export class AsyncCompletionQueue {
+    buffer = [];
+    waiters = [];
+    /**
+     * 아이템을 큐에 추가한다.
+     * 대기 중인 소비자가 있으면 즉시 전달하고, 없으면 버퍼에 저장한다.
+     *
+     * @param item - 큐에 추가할 아이템
+     */
+    push(item) {
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter(item);
+        }
+        else {
+            this.buffer.push(item);
+        }
+    }
+    /**
+     * 큐에서 아이템을 하나 꺼낸다.
+     * 버퍼에 아이템이 있으면 즉시 반환하고, 없으면 push될 때까지 대기한다.
+     *
+     * @returns 큐에서 꺼낸 아이템
+     */
+    async shift() {
+        const item = this.buffer.shift();
+        if (item !== undefined) {
+            return item;
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    /**
+     * 현재 버퍼에 있는 모든 아이템을 즉시 반환한다 (논블로킹, 동기).
+     * 반환 후 버퍼는 비워진다.
+     *
+     * Note: 의도적으로 동기 메서드입니다. dag-orchestrator의 for...of 루프에서
+     * 즉시 반환이 필요하므로 async가 아닌 sync로 유지합니다.
+     *
+     * @returns 버퍼에 있던 모든 아이템 배열
+     */
+    drain() {
+        const items = this.buffer.splice(0);
+        return items;
+    }
+    /**
+     * 현재 버퍼에 대기 중인 아이템 수.
+     */
+    get length() {
+        return this.buffer.length;
+    }
+}
+//# sourceMappingURL=async-completion-queue.js.map

package/dist/async-completion-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-completion-queue.js","sourceRoot":"","sources":["../src/async-completion-queue.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,oBAAoB;IACvB,MAAM,GAAQ,EAAE,CAAC;IACjB,OAAO,GAA6B,EAAE,CAAC;IAE/C;;;;;OAKG;IACH,IAAI,CAAC,IAAO;QACV,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,CAAC;QACf,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,EAAE;YAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF"}

package/dist/auto-fix.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @module auto-fix
+ * @description 자동 수정 루프 — 도구 실행 결과를 검증하고, 실패 시 자동 수정 시도.
+ *
+ * 플로우:
+ * 1. 도구 실행 결과 수신
+ * 2. 결과 검증 (lint 에러, 빌드 에러, 타입 에러 등)
+ * 3. 실패 시 → 에러 메시지를 LLM에 피드백할 프롬프트 생성
+ * 4. LLM이 수정 제안 → 도구 재실행
+ * 5. 최대 maxRetries 반복 후 포기
+ *
+ * @see 설계 문서 Section 6.4
+ */
+/** 자동 수정 루프 설정 */
+export interface AutoFixConfig {
+    /** 최대 수정 시도 횟수 (기본 3) */
+    maxRetries: number;
+    /** file_write/edit 후 자동 lint 실행 */
+    autoLint: boolean;
+    /** 변경 후 자동 테스트 (Phase 1b) */
+    autoTest: boolean;
+    /** 변경 후 자동 빌드 체크 */
+    autoBuild: boolean;
+}
+/** 검증 결과 */
+export interface ValidationResult {
+    /** 검증 통과 여부 */
+    passed: boolean;
+    /** 실패한 검증 항목 */
+    failures: ValidationFailure[];
+}
+/** 검증 실패 항목 */
+export interface ValidationFailure {
+    /** 검증 종류 */
+    type: AutoFixTrigger;
+    /** 에러 메시지 */
+    message: string;
+    /** 관련 파일 경로 */
+    file?: string;
+    /** 관련 라인 번호 */
+    line?: number;
+    /** 원본 명령 출력 */
+    rawOutput: string;
+}
+/** 자동 수정 트리거 유형 */
+export type AutoFixTrigger = "BUILD_FAIL" | "TEST_FAIL" | "LINT_ERROR" | "RUNTIME_ERROR" | "TYPE_ERROR" | "IMPORT_ERROR";
+/** 수정 시도 기록 */
+export interface FixAttempt {
+    /** 시도 번호 (1-based) */
+    iteration: number;
+    /** 발생한 에러 */
+    error: string;
+    /** 수정 내용 설명 */
+    fix: string;
+    /** 수정 성공 여부 */
+    success: boolean;
+    /** 소요 시간 (ms) */
+    durationMs: number;
+}
+/** lint 실행 결과 */
+export interface LintResult {
+    /** 성공 여부 */
+    passed: boolean;
+    /** 에러 수 */
+    errorCount: number;
+    /** 경고 수 */
+    warningCount: number;
+    /** 원본 출력 */
+    output: string;
+}
+/** 빌드 체크 결과 */
+export interface BuildResult {
+    /** 성공 여부 */
+    passed: boolean;
+    /** 에러 수 */
+    errorCount: number;
+    /** 원본 출력 */
+    output: string;
+}
+/** 기본 자동 수정 설정 */
+export declare const DEFAULT_AUTO_FIX_CONFIG: AutoFixConfig;
+/**
+ * AutoFixLoop — 도구 실행 결과를 검증하고 자동 수정 루프를 관리.
+ *
+ * 이 클래스 자체는 LLM을 호출하지 않는다.
+ * 검증 실패 시 LLM에 피드백할 프롬프트를 생성하고,
+ * AgentLoop이 해당 프롬프트를 LLM에 전달하여 수정 도구 호출을 받는다.
+ *
+ * @example
+ * ```typescript
+ * const autoFix = new AutoFixLoop({ maxRetries: 3, autoLint: true, autoBuild: true, autoTest: false });
+ *
+ * // 도구 실행 후 검증
+ * const validation = await autoFix.validateResult('file_write', result, '/project');
+ * if (!validation.passed) {
+ *   const fixPrompt = autoFix.buildFixPrompt(
+ *     validation.failures[0].message,
+ *     'Writing component file'
+ *   );
+ *   // fixPrompt를 LLM에 전달 → 수정 도구 호출 수신
+ * }
+ * ```
+ */
+export declare class AutoFixLoop {
+    private readonly config;
+    private readonly attempts;
+    constructor(config?: Partial<AutoFixConfig>);
+    /**
+     * 도구 실행 결과를 검증.
+     * file_write/file_edit 후에는 lint/빌드 체크를 자동 실행한다.
+     *
+     * @param toolName 실행된 도구 이름
+     * @param toolOutput 도구 실행 결과 출력
+     * @param success 도구 실행 성공 여부
+     * @param workDir 프로젝트 루트 경로
+     * @returns 검증 결과
+     */
+    validateResult(toolName: string, toolOutput: string, success: boolean, workDir: string): Promise<ValidationResult>;
+    /**
+     * 실패 시 LLM에 피드백할 수정 프롬프트를 생성.
+     *
+     * @param error 에러 메시지
+     * @param context 현재 작업 컨텍스트
+     * @returns LLM에 전달할 프롬프트 문자열
+     */
+    buildFixPrompt(error: string, context: string): string;
+    /**
+     * 수정 시도를 기록.
+     * @param error 에러 메시지
+     * @param fix 수정 내용 설명
+     * @param success 수정 성공 여부
+     * @param durationMs 소요 시간
+     */
+    recordAttempt(error: string, fix: string, success: boolean, durationMs: number): void;
+    /**
+     * 남은 수정 시도 횟수를 반환.
+     */
+    getRemainingRetries(): number;
+    /**
+     * 수정 시도를 더 할 수 있는지 반환.
+     */
+    canRetry(): boolean;
+    /**
+     * 수정 시도 기록을 반환.
+     */
+    getAttempts(): readonly FixAttempt[];
+    /**
+     * 수정 시도 기록을 초기화 (새 도구 호출 시작 시).
+     */
+    resetAttempts(): void;
+    /**
+     * 현재 설정을 반환.
+     */
+    getConfig(): Readonly<AutoFixConfig>;
+    /**
+     * 프로젝트에서 lint를 실행.
+     * 순서: eslint → npx tsc --noEmit (lint 대체)
+     * @param workDir 프로젝트 루트 경로
+     */
+    runLint(workDir: string): Promise<LintResult>;
+    /**
+     * 프로젝트에서 빌드 체크 (tsc --noEmit) 를 실행.
+     * @param workDir 프로젝트 루트 경로
+     */
+    runBuildCheck(workDir: string): Promise<BuildResult>;
+    private runTscCheck;
+    private classifyError;
+    private isBuildTypeError;
+    private detectShellErrors;
+    private truncateOutput;
+    private fileExists;
+    private exec;
+}
+//# sourceMappingURL=auto-fix.d.ts.map

package/dist/auto-fix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-fix.d.ts","sourceRoot":"","sources":["../src/auto-fix.ts"],"names":[],"mappings":"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"}