devkit-debugging-mcp 0.1.0

package/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md (devkit-debugging-mcp)
+
+코드 및 주석은 영어로 한다.
+이 레포는 npm에 배포할 **Custom MCP 서버**이며, Codex/Claude 등 다양한 MCP 클라이언트 설정에 결합될 수 있어야 한다.
+
+## 0) 목적 (Mission)
+
+이 MCP는 **Next.js + Supabase** 프로젝트에서의 **테스팅/디버깅/리팩토링(안전한 범위)**을 표준화한다.
+
+핵심은:
+
+- 에러/테스트 실패를 **빠르게 분류(triage)**
+- 원인을 **최소 컨텍스트로 좁히고**
+- **dry-run 변경 계획(패치)**으로 수정안을 제안
+- 검증 절차(테스트/빌드/재현)를 함께 제공
+
+## 1) 기본 원칙 (Non‑Negotiables)
+
+1. **Safety first**: 민감정보/권한/RLS/서버경계를 훼손하는 제안 금지.
+2. **Small diffs**: “큰 리팩토링”보다 “최소 변경”을 우선.
+3. **Dry-run 우선**: 파일 수정은 변경 계획을 먼저 제시.
+4. **Verifiable**: 항상 “확인 방법(명령/기대결과)”을 포함.
+5. **Idempotent**: 같은 입력/상태에서 결과가 흔들리지 않게.
+
+## 2) 타겟 범위
+
+- Next.js App Router 기반 프로젝트
+- Supabase(Postgres, migrations, RLS) 기반 프로젝트
+- TypeScript strict, ESLint, 테스트 러너(jest/vitest/playwright 등) 혼재 가능
+
+## 3) 레포 문서의 역할
+
+- `PRD.md`: 제품 요구사항/범위/성공 기준
+- `TRD.md`: 기술 설계/계약/툴 스펙
+- 각 폴더의 `AGENTS.md`: 해당 디렉토리 트리에서 지켜야 할 작업 규칙
+
+## 4) 작업 방식(Agent Workflow)
+
+새 tool 추가 시 순서:
+
+1. `src/tools/<tool>.ts`에 1 tool 1 file로 구현
+2. 입력/출력 Zod 스키마를 정의하고 계약을 문서화
+3. dry-run change plan을 기본 경로로 지원
+4. 스냅샷 테스트 추가(`tests/`)
+5. 가드레일(민감정보/권한/서버경계) 점검 로직을 통과
+
+금지:
+
+- 사용자의 프로젝트를 임의로 “대규모 리팩토링”하는 변경 제안
+- RLS 약화/서비스키 노출을 유도하는 변경
+- `.env`/키/토큰을 출력하거나 로그로 남기는 행위
+

package/PRD.md

@@ -0,0 +1,86 @@
+# PRD (devkit-debugging-mcp)
+
+## 0) 한 줄 소개
+
+`devkit-debugging-mcp`는 **Next.js(App Router) + Supabase** 프로젝트에서 발생하는 **테스트 실패/런타임 에러/빌드 에러**를 빠르게 **분류(triage)하고**, 안전한 범위에서 **원인 분석 + 수정 제안(패치)** + **리팩토링 가이드**를 제공하는 **Custom MCP 서버(npm 패키지)**다.
+
+핵심 의도는 “문서로 부탁”이 아니라, **도구(tool)로 디버깅/테스팅 워크플로우를 표준화**하는 것이다.
+
+## 1) 사용자(Who) & 사용 시나리오(When)
+
+- 대상 사용자
+  - Next.js + Supabase 기반 제품을 개발/운영하는 팀
+  - 코드 에이전트(Codex/Claude 등)로 디버깅을 자동화하고 싶은 개발자
+- 주 사용 상황
+  - CI에서 테스트가 깨짐(단위/통합/E2E 포함)
+  - `next dev`에서 런타임 오류/서버 오류/클라이언트 오류 발생
+  - `next build`/`next lint`/`tsc` 에러 발생
+  - Supabase migration/RLS 정책/권한 관련 이슈 발생
+  - 기능 리팩토링 중 회귀(regression) 의심
+
+## 2) 문제 정의(Problem)
+
+Next.js + Supabase 프로젝트에서 에러가 나면, 에이전트가 다음을 반복적으로 수행한다:
+
+- 로그/스택트레이스를 해석하고 원인을 추적
+- 관련 파일을 찾아 컨텍스트를 구성
+- 재현/검증 절차를 제안하고, 수정안을 작성
+- 수정 후 회귀를 막기 위해 테스트를 보강/정리
+
+하지만 프로젝트마다 폴더 구조/컨벤션/테스트 런너/환경변수/DB 정책이 달라 **반복 비용이 크고** 실수로 **위험한 수정(과도한 리팩토링, 보안 취약점, RLS 붕괴)**이 발생하기 쉽다.
+
+## 3) 목표(Goals)
+
+1. **빠른 분류(Triage)**: 에러/테스트 실패를 “무엇이 깨졌는지”로 빠르게 구조화한다.
+2. **원인 추적(Root cause)**: 최소 컨텍스트로 실제 원인 후보를 좁힌다.
+3. **안전한 수정 제안(Safe fixes)**: 큰 리팩토링 대신, 작은 변경으로 해결하는 패치 제안을 우선한다.
+4. **검증 가능(Verifiable)**: 제안은 항상 “어떻게 확인할지(명령/절차/기대결과)”를 포함한다.
+5. **리팩토링 지원(Refactor assist)**: 기능 변경이 아닌, 안정성/가독성/테스트 용이성 중심 리팩토링을 돕는다.
+6. **Next/Supabase 표준 준수**: env 분리, 서버/클라이언트 경계, RLS 최소권한 등 안전장치를 유지한다.
+
+## 4) 비목표(Non-goals)
+
+- 프로젝트 도메인 로직을 추측해 기능을 “대신 구현”하지 않는다.
+- 과도한 자동 리팩토링(대규모 파일 이동/아키텍처 재구성)을 목표로 하지 않는다.
+- 민감정보(키/토큰/서비스 롤 키)를 수집/로그/출력하지 않는다.
+- 네트워크가 필요한 외부 서비스 의존(원격 LLM 호출, 원격 API 탐색)을 기본 기능으로 요구하지 않는다.
+
+## 5) MVP 범위(What we ship first)
+
+MVP는 “디버깅의 80%를 가장 안전하게” 처리하는 데 집중한다.
+
+### 5.1 제공할 도구(초기 제안)
+
+- `triage_issue`
+  - 입력: 에러 메시지/스택트레이스/테스트 실패 로그(텍스트)
+  - 출력: 문제 유형 분류, 우선순위, 즉시 확인 체크리스트, 의심 파일/키워드
+- `suggest_patch`
+  - 입력: 문제 요약 + 관련 파일 경로(선택) + 원하는 변경 수준(“minimal/medium”)
+  - 출력: **dry-run 패치(변경 계획)** + 리스크/검증 절차
+- `refactor_guarded`
+  - 입력: 리팩토링 목표(가독성/테스트 용이성/중복 제거) + 대상 파일/심볼
+  - 출력: **행동 제한(guardrails)** 하에서의 변경 계획 + 회귀 방지 체크
+- `check_debugging_readiness`
+  - 입력: 프로젝트 루트 경로
+  - 출력: 디버깅/테스트 관점에서의 “준비도 체크”(예: 스크립트 존재, 테스트 러너 감지, env 접근 패턴 등)
+
+> 주의: “실제 테스트 실행/커맨드 실행”은 기본 MVP에서 필수가 아니다. 대신 **실행할 명령과 기대결과를 제안**하는 형태를 우선한다.
+
+### 5.2 성공 기준(Success metrics)
+
+- 에러/테스트 실패 사례에서 “1~2회 반복”으로 원인 후보를 좁히는 비율 증가
+- 패치 제안이 “최소 변경 + 검증 절차 포함” 형태로 일관되게 생성
+- 위험한 변경(보안/권한/RLS 붕괴, client 번들로 키 노출) 제안 빈도 0에 가깝게 유지
+
+## 6) 제약/원칙(Constraints & Principles)
+
+- **멱등성**: 같은 입력으로 같은 제안을 내는 방향(비결정성 최소화)
+- **dry-run 우선**: 파일 쓰기/수정은 항상 dry-run 변경 계획을 먼저 제공
+- **친절한 실패**: 입력이 부족하면 “무엇이 더 필요한지”를 구체적으로 요청
+- **안전 가드레일**: env/키/RLS/서버경계 관련 규칙 위반을 유도하지 않는다
+
+## 7) 배포/통합(Distribution)
+
+- 형태: npm 패키지(ESM) + MCP 서버 실행 엔트리(`bin`)
+- 통합 대상: Codex/Claude 등 MCP 클라이언트 구성에 연결 가능
+

package/README.md

@@ -0,0 +1,21 @@
+# devkit-debugging-mcp
+
+Custom MCP server for **debugging, testing, and guarded refactoring** in **Next.js + Supabase** projects.
+
+- Focus: triage errors, propose minimal patches (dry-run), provide verification steps.
+- Safety: prevent secrets leakage, respect server/client boundary, keep Supabase RLS secure.
+
+## Status
+
+First release includes:
+
+- `triage_issue`: classify logs/test failures and return an actionable checklist (secrets redacted)
+- `check_debugging_readiness`: inspect a project root for debugging/testing readiness signals
+- `suggest_patch`: guarded, deterministic patch planning for a small set of common issues (dry-run by default)
+- `refactor_guarded`: no-behavior-change refactor planning with verification steps
+
+## Usage (MCP)
+
+Run via stdio transport (typical MCP client setup).
+
+- Command: `npx -y devkit-debugging-mcp`

package/TRD.md

@@ -0,0 +1,120 @@
+# TRD (devkit-debugging-mcp)
+
+## 0) 기술 목표
+
+- MCP 서버로서 **도구(tool) 기반 디버깅 워크플로우**를 제공한다.
+- 결과는 “텍스트 조언”이 아니라 **구조화된 출력(스키마) + 변경 계획(dry-run diff)** 중심으로 제공한다.
+- Next.js(App Router) + Supabase 프로젝트의 안전 규칙을 깨지 않도록 **가드레일을 1급 요구사항**으로 둔다.
+
+## 1) 런타임/스택
+
+- Node.js `>=18.18`
+- TypeScript (strict)
+- ESM 패키지(`"type": "module"`)
+- `@modelcontextprotocol/sdk`
+- `zod`
+
+네트워크 의존은 기본 TRD에서 제외(로컬 파일/로그 기반).
+
+## 2) 레포 구조(권장)
+
+- `src/`
+  - `bin.ts` : CLI 엔트리(MCP 서버 실행)
+  - `server/` : 서버 생성/등록
+  - `tools/` : MCP tool 구현(1 tool = 1 file)
+  - `core/`
+    - `errors.ts` : 에러 코드/에러 래핑
+    - `contracts.ts` : 공통 응답/변경계획 타입
+    - `diff/` : 변경 계획 preview 생성
+    - `fs/` : 안전한 파일 읽기/쓰기(옵션), walk 유틸
+    - `guards/` : Next/Supabase 안전 규칙(키 노출, server/client 경계 등)
+    - `triage/` : 로그/스택트레이스 파서
+- `tests/` : tool 단위 테스트(스냅샷 포함)
+- `docs/` : 추가 문서(필요 시)
+
+## 3) 공통 계약(Contracts)
+
+### 3.1 표준 응답 envelope
+
+모든 tool 응답은 아래 중 하나를 따른다.
+
+- 성공
+  - `{ ok: true, data: T, message?: string, nextSteps?: string[] }`
+- 실패
+  - `{ ok: false, error: { code: string, message: string, details?: unknown } }`
+
+### 3.2 변경 계획(Change Plan)
+
+파일을 수정/생성/삭제하는 tool은 **반드시** dry-run 변경 계획을 지원한다.
+
+- `changes: Array<{ type: "create"|"update"|"delete", path: string, preview: string }>`
+- 실제 write 모드(옵션)에서는 `filesWritten: string[]`를 함께 반환한다.
+
+## 4) Tool 설계(Design)
+
+### 4.1 입력 검증
+
+- 모든 입력은 Zod로 검증한다.
+- 입력이 부족하면 `INVALID_INPUT`으로 실패시키되, `details`에 “추가로 필요한 정보”를 포함한다.
+
+### 4.2 결정성(Determinism)
+
+- 동일 입력에 대해 출력 구조가 크게 흔들리지 않도록 한다.
+- 로그 파싱 결과는 “규칙 기반” 우선으로 구성한다(LLM 의존 최소화).
+
+### 4.3 안전 가드레일
+
+다음은 tool 레벨에서 금지/차단/경고한다.
+
+- `.env*` 내용, API 키, Supabase service role key 등 민감값을 출력/로그로 내보내는 행위
+- `NEXT_PUBLIC_*`로 서버 비밀을 노출하도록 유도하는 제안
+- Supabase RLS를 무력화(`using (true)` 등의 광범위 정책)하는 제안
+- 서버 전용 코드를 클라이언트 번들로 끌어오는 import/사용 패턴 제안
+
+## 5) MVP Tool 스펙(초안)
+
+### Tool A: `triage_issue`
+
+- 목적: 에러/테스트 실패 로그를 구조화하여 다음 액션을 명확히 한다.
+- 입력(예): `{ "text": "....stacktrace....", "contextHint"?: "next|supabase|jest|vitest|playwright|tsc|eslint" }`
+- 출력(예):
+  - `{ ok: true, data: { category, severity, suspectedFiles, checklist, questions } }`
+
+### Tool B: `suggest_patch`
+
+- 목적: 최소 변경으로 문제 해결 패치를 제안한다(dry-run 우선).
+- 입력(예): `{ "summary": "...", "files"?: ["..."], "changeLevel": "minimal|medium", "dryRun": true }`
+- 출력(예):
+  - `{ ok: true, data: { rationale, risks, verification }, changes: [...] }`
+
+### Tool C: `refactor_guarded`
+
+- 목적: 안전한 리팩토링(동작 변경 금지 원칙) 제안.
+- 입력(예): `{ "goal": "readability|testability|dedupe", "targets": [{ "file": "...", "symbol"?: "..." }], "dryRun": true }`
+- 출력(예): `{ ok: true, data: { plan, verification }, changes: [...] }`
+
+### Tool D: `check_debugging_readiness`
+
+- 목적: 프로젝트의 디버깅/테스트 준비도 진단.
+- 입력(예): `{ "path": ".", "strict": true }`
+- 출력(예): `{ ok: true, data: { detected, warnings, suggestions } }`
+
+## 6) 에러 코드(표준)
+
+- `INVALID_INPUT`
+- `NOT_FOUND`
+- `CONVENTION_VIOLATION`
+- `FILE_CONFLICT`
+- `INTERNAL_ERROR`
+
+## 7) 테스트 정책
+
+- 로그 파서/triage 결과는 스냅샷 테스트로 고정한다.
+- dry-run 변경 계획은 스냅샷 테스트로 고정한다.
+- “멱등성”: 동일 입력/동일 상태에서 change plan이 변하지 않는지 테스트한다.
+
+## 8) 로깅 정책
+
+- 기본 로그는 최소화한다(디버깅 정보가 필요하면 opt-in).
+- 민감정보 마스킹을 공통 유틸로 제공한다.
+

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createDebuggingServer } from "./server/createDebuggingServer.js";
+const server = createDebuggingServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,MAAM,MAAM,GAAG,qBAAqB,EAAE,CAAC;AACvC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class ToolErrorBase extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare class InvalidInputError extends ToolErrorBase {
+    constructor(message: string, details?: unknown);
+}
+export declare class NotFoundError extends ToolErrorBase {
+    constructor(message: string, details?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAM7D;AAED,qBAAa,iBAAkB,SAAQ,aAAa;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED,qBAAa,aAAc,SAAQ,aAAa;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C"}

package/dist/core/errors.js

@@ -0,0 +1,23 @@
+export class ToolErrorBase extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ToolError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export class InvalidInputError extends ToolErrorBase {
+    constructor(message, details) {
+        super("INVALID_INPUT", message, details);
+        this.name = "InvalidInputError";
+    }
+}
+export class NotFoundError extends ToolErrorBase {
+    constructor(message, details) {
+        super("NOT_FOUND", message, details);
+        this.name = "NotFoundError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtB,IAAI,CAAS;IACb,OAAO,CAAW;IAElC,YAAY,IAAY,EAAE,OAAe,EAAE,OAAiB;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,eAAe,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,aAAa;IAC9C,YAAY,OAAe,EAAE,OAAiB;QAC5C,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/dist/core/fs/readText.d.ts

@@ -0,0 +1,2 @@
+export declare function readTextFile(filePath: string, maxBytes?: number): Promise<string>;
+//# sourceMappingURL=readText.d.ts.map

package/dist/core/fs/readText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readText.d.ts","sourceRoot":"","sources":["../../../src/core/fs/readText.ts"],"names":[],"mappings":"AAEA,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAMxF"}

package/dist/core/fs/readText.js

@@ -0,0 +1,9 @@
+import fs from "node:fs/promises";
+export async function readTextFile(filePath, maxBytes = 512_000) {
+    const buf = await fs.readFile(filePath);
+    if (buf.byteLength > maxBytes) {
+        return buf.subarray(0, maxBytes).toString("utf8") + "\n<trimmed>";
+    }
+    return buf.toString("utf8");
+}
+//# sourceMappingURL=readText.js.map

package/dist/core/fs/readText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readText.js","sourceRoot":"","sources":["../../../src/core/fs/readText.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB,EAAE,QAAQ,GAAG,OAAO;IACrE,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,GAAG,CAAC,UAAU,GAAG,QAAQ,EAAE,CAAC;QAC9B,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC;IACpE,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC"}

package/dist/core/fs/walk.d.ts

@@ -0,0 +1,7 @@
+export type WalkOptions = {
+    rootDir: string;
+    maxFiles?: number;
+    ignoreDirNames?: string[];
+};
+export declare function walkFiles(options: WalkOptions): Promise<string[]>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/core/fs/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../../src/core/fs/walk.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAcF,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkCvE"}

package/dist/core/fs/walk.js

@@ -0,0 +1,48 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_IGNORES = [
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    "coverage",
+    ".turbo",
+    ".git",
+    ".vercel",
+    ".output",
+];
+export async function walkFiles(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const ignore = new Set(options.ignoreDirNames ?? DEFAULT_IGNORES);
+    const maxFiles = options.maxFiles ?? 5000;
+    const results = [];
+    const queue = [rootDir];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (!current)
+            break;
+        if (results.length >= maxFiles)
+            break;
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (results.length >= maxFiles)
+                break;
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (!ignore.has(entry.name))
+                    queue.push(full);
+                continue;
+            }
+            if (entry.isFile())
+                results.push(full);
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=walk.js.map

package/dist/core/fs/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../src/core/fs/walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAQ7B,MAAM,eAAe,GAAG;IACtB,cAAc;IACd,OAAO;IACP,MAAM;IACN,OAAO;IACP,UAAU;IACV,QAAQ;IACR,MAAM;IACN,SAAS;IACT,SAAS;CACV,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAoB;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,cAAc,IAAI,eAAe,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;IAE1C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAa,CAAC,OAAO,CAAC,CAAC;IAElC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,MAAM;QAEpB,IAAI,OAAO,CAAC,MAAM,IAAI,QAAQ;YAAE,MAAM;QAEtC,IAAI,OAAwC,CAAC;QAC7C,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,OAAO,CAAC,MAAM,IAAI,QAAQ;gBAAE,MAAM;YAEtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC9C,SAAS;YACX,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,EAAE;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/jsonc.d.ts

@@ -0,0 +1,2 @@
+export declare function parseJsonc(text: string): unknown;
+//# sourceMappingURL=jsonc.d.ts.map

package/dist/core/jsonc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonc.d.ts","sourceRoot":"","sources":["../../src/core/jsonc.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIhD"}

package/dist/core/jsonc.js

@@ -0,0 +1,6 @@
+export function parseJsonc(text) {
+    const withoutBlock = text.replace(/\/\*[\s\S]*?\*\//g, "");
+    const withoutLine = withoutBlock.replace(/(^|\s)\/\/.*$/gm, "$1");
+    return JSON.parse(withoutLine);
+}
+//# sourceMappingURL=jsonc.js.map

package/dist/core/jsonc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonc.js","sourceRoot":"","sources":["../../src/core/jsonc.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;IAC3D,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;AACjC,CAAC"}

package/dist/core/mcp/mcpResult.d.ts

@@ -0,0 +1,9 @@
+import type { ToolResult } from "../../types/contracts.js";
+export declare function toMcpResult(payload: ToolResult): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: ToolResult;
+};
+//# sourceMappingURL=mcpResult.d.ts.map

package/dist/core/mcp/mcpResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpResult.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/mcpResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU;;;;;;EAK9C"}

package/dist/core/mcp/mcpResult.js

@@ -0,0 +1,7 @@
+export function toMcpResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
+//# sourceMappingURL=mcpResult.js.map

package/dist/core/mcp/mcpResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpResult.js","sourceRoot":"","sources":["../../../src/core/mcp/mcpResult.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,WAAW,CAAC,OAAmB;IAC7C,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAC5E,iBAAiB,EAAE,OAAO;KAC3B,CAAC;AACJ,CAAC"}

package/dist/core/patch/suggestPatch.d.ts

@@ -0,0 +1,26 @@
+import type { ChangePreview } from "../../types/contracts.js";
+import { triageIssue } from "../triage/triageIssue.js";
+export type SuggestPatchInput = {
+    projectRoot: string;
+    text: string;
+    changeLevel: "minimal" | "medium";
+    dryRun: boolean;
+};
+export type SuggestPatchOutput = {
+    triage: ReturnType<typeof triageIssue>;
+    rationale: string;
+    risks: string[];
+    verification: string[];
+};
+export declare function suggestPatchPlan(input: SuggestPatchInput): Promise<{
+    data: SuggestPatchOutput;
+    changes: ChangePreview[];
+    filesWritten: string[];
+    nextSteps: string[];
+    warnings: Array<{
+        code: string;
+        message: string;
+        path?: string;
+    }>;
+}>;
+//# sourceMappingURL=suggestPatch.d.ts.map

package/dist/core/patch/suggestPatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestPatch.d.ts","sourceRoot":"","sources":["../../../src/core/patch/suggestPatch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAgFF,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC;IACxE,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnE,CAAC,CAoED"}

package/dist/core/patch/suggestPatch.js

@@ -0,0 +1,139 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { readTextFile } from "../fs/readText.js";
+import { walkFiles } from "../fs/walk.js";
+import { parseJsonc } from "../jsonc.js";
+import { triageIssue } from "../triage/triageIssue.js";
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toPrettyJson(value) {
+    return JSON.stringify(value, null, 2) + "\n";
+}
+function toChangePreview(update) {
+    return {
+        type: "update",
+        path: update.relativePath,
+        preview: `# ${update.relativePath}\n# ${update.note}\n\n${update.nextContent}`,
+    };
+}
+async function planTsconfigPathAliasFix(projectRoot, text) {
+    if (!/@\//.test(text))
+        return null;
+    const tsconfigPath = path.join(projectRoot, "tsconfig.json");
+    if (!(await exists(tsconfigPath)))
+        return null;
+    const raw = await readTextFile(tsconfigPath, 512_000);
+    let json;
+    try {
+        json = parseJsonc(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!json || typeof json !== "object")
+        return null;
+    const hasSrcDir = await exists(path.join(projectRoot, "src"));
+    const baseUrl = ".";
+    const target = hasSrcDir ? "./src/*" : "./*";
+    const next = structuredClone(json);
+    next.compilerOptions = next.compilerOptions ?? {};
+    next.compilerOptions.baseUrl = next.compilerOptions.baseUrl ?? baseUrl;
+    next.compilerOptions.paths = next.compilerOptions.paths ?? {};
+    const existing = next.compilerOptions.paths["@/*"];
+    const desired = [target];
+    const shouldUpdate = !Array.isArray(existing) || JSON.stringify(existing) !== JSON.stringify(desired);
+    if (!shouldUpdate)
+        return null;
+    next.compilerOptions.paths["@/*"] = desired;
+    return [
+        {
+            relativePath: "tsconfig.json",
+            note: "Add/adjust `@/*` path alias for `@/` imports.",
+            nextContent: toPrettyJson(next),
+        },
+    ];
+}
+async function detectNextSupabase(projectRoot) {
+    const pkgPath = path.join(projectRoot, "package.json");
+    if (!(await exists(pkgPath)))
+        return { hasNext: false, hasSupabase: false };
+    const pkg = JSON.parse(await readTextFile(pkgPath, 256_000));
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    return {
+        hasNext: Boolean(deps.next),
+        hasSupabase: Boolean(deps.supabase || deps["@supabase/supabase-js"] || deps["@supabase/ssr"]),
+    };
+}
+export async function suggestPatchPlan(input) {
+    const projectRoot = path.resolve(input.projectRoot);
+    const triage = triageIssue(input.text);
+    const warnings = [];
+    const { hasNext, hasSupabase } = await detectNextSupabase(projectRoot);
+    if (!hasNext)
+        warnings.push({ code: "NEXT_NOT_DETECTED", message: "Next.js dependency not detected in package.json." });
+    if (!hasSupabase)
+        warnings.push({ code: "SUPABASE_NOT_DETECTED", message: "Supabase dependency not detected in package.json." });
+    const plannedUpdates = [];
+    const filesWritten = [];
+    const aliasFix = await planTsconfigPathAliasFix(projectRoot, input.text);
+    if (aliasFix)
+        plannedUpdates.push(...aliasFix);
+    // Heuristic: encourage an env example if none exists (no file write by default).
+    const files = await walkFiles({ rootDir: projectRoot, maxFiles: 2000 });
+    const hasEnvExample = files.some((f) => /(?:^|\/)\.env\.example$/.test(f) || /(?:^|\/)\.env\.local\.example$/.test(f));
+    if (!hasEnvExample) {
+        warnings.push({
+            code: "NO_ENV_EXAMPLE",
+            message: "No `.env.example` (or `.env.local.example`) found; consider adding one (without secret values).",
+        });
+    }
+    if (!input.dryRun && plannedUpdates.length > 0) {
+        for (const update of plannedUpdates) {
+            const targetPath = path.join(projectRoot, update.relativePath);
+            await fs.writeFile(targetPath, update.nextContent, "utf8");
+            filesWritten.push(update.relativePath);
+        }
+    }
+    const changes = plannedUpdates.map(toChangePreview);
+    const rationale = changes.length > 0
+        ? "Generated a minimal, deterministic patch plan based on common Next.js/TS failure patterns."
+        : "No safe, deterministic patch recipe matched the provided input; returning triage + verification guidance only.";
+    const risks = [];
+    if (changes.some((c) => c.path === "tsconfig.json")) {
+        risks.push("Changing `tsconfig.json` may affect IDE/TS resolution and may reveal additional type errors.");
+    }
+    if (triage.category === "supabase_rls") {
+        risks.push("RLS fixes are security-sensitive; avoid broad allow-all policies and validate with the exact role/claims.");
+    }
+    const verification = [];
+    if (triage.category === "typescript" || changes.some((c) => c.path === "tsconfig.json"))
+        verification.push("npm run typecheck");
+    if (triage.category === "test_failure")
+        verification.push("npm test");
+    if (triage.category === "next_build")
+        verification.push("npm run build");
+    if (verification.length === 0)
+        verification.push("Re-run the exact command that produced the error and confirm the first error block changed.");
+    const nextSteps = [];
+    if (changes.length > 0) {
+        nextSteps.push(input.dryRun ? "Review the proposed patch preview, then re-run with `dryRun: false` to apply." : "Re-run verification commands.");
+    }
+    else {
+        nextSteps.push("If you want patch generation, provide project root + the exact failing command output and the relevant file contents.");
+    }
+    return {
+        data: { triage, rationale, risks, verification },
+        changes,
+        filesWritten,
+        nextSteps,
+        warnings,
+    };
+}
+//# sourceMappingURL=suggestPatch.js.map