egovframe-scaffold-mcp 0.25.0 → 0.25.2

package/README.md

@@ -11,17 +11,18 @@
 Claude, VS Code(Copilot), Cursor 등 MCP를 지원하는 AI 도구에서 **대화 중 즉시** 표준프레임워크
 프로젝트를 만들고 공통컴포넌트·AI 계층을 조립할 수 있습니다. 기존 프로젝트 진단, 리포트, 안전한 upstream 재동기화도 지원합니다.
 
-현재 v0.25.0은 **도구 21종, 공식 템플릿 10종, 공통컴포넌트 카탈로그 190항목(리프 176종+그룹 14종)**을 제공합니다.
+현재 v0.25.2는 **도구 21종, 공식 템플릿 10종, 공통컴포넌트 카탈로그 190항목(리프 176종+그룹 14종)**을 제공합니다.
 
-## 진행 현황 (2026-09-12)
+## 진행 현황 (2026-09-13)
 
-- **소스 기준**: v0.25.0(`package.json`), 도구 21종·공식 템플릿 10종·카탈로그 190항목.
+- **소스 기준**: v0.25.2(`package.json`), 도구 21종·공식 템플릿 10종·카탈로그 190항목.
 - **안전성 기준선 완료**: [PR #7](https://github.com/EricSeokgon/egovframe-scaffold-mcp/pull/7)~[#16](https://github.com/EricSeokgon/egovframe-scaffold-mcp/pull/16)을 반영해 provenance·strict assertion·safe remove와 프로젝트 생성/레시피/직접 조립/AI 조립/업그레이드 transaction을 갖췄습니다.
 - **v0.22.0 추가**: `EGOVFRAME_ALLOWED_ROOTS`를 19개 도구 진입점에 적용해 `..`·symlink/junction 이탈을 차단하고, 실패 시 rollback 결과를 구조화해 반환합니다. [PR #16](https://github.com/EricSeokgon/egovframe-scaffold-mcp/pull/16)은 7파일(+340/−31), 로컬 16종 스위트 전체 통과 후 병합됐습니다.
 - **v0.23.0 추가**: `build_egovframe_project` — 생성한 프로젝트를 실제로 빌드(maven/gradle·mvnw/gradlew 자동 감지)하고 컴파일·테스트 오류를 파일/라인 단위로 구조화해 생성→검증 루프를 완성합니다. 타임아웃·로그 상한·허용 root·dryRun 포함. [PR #18](https://github.com/EricSeokgon/egovframe-scaffold-mcp/pull/18)은 4파일(+458/−3), 오프라인 40단언과 실제 spawn 경로를 검증했습니다.
 - **v0.24.0 추가**: 공식 템플릿 커버리지 7 → 10종(`msa-common-components`·`mobile-device-api`·`ai-rag`, 모두 멀티 프로젝트). [PR #19](https://github.com/EricSeokgon/egovframe-scaffold-mcp/pull/19).
 - **v0.25.0 추가**: `test_egovframe_project` — 테스트를 실행하고 빌드도구가 남기는 JUnit XML 리포트(surefire·gradle)를 읽어 스위트·케이스 단위로 결과를 구조화합니다. 실패 케이스의 메시지·예외 타입·테스트 파일/라인, `testFilter`(클래스/메서드 패턴), 이전 실행 리포트 제외, 종료 코드가 0이어도 리포트에 실패가 있으면 실패로 판정. 오프라인 54단언(`npm run test:test`).
-- **배포 상태**: 저장소 소스는 v0.25.0이며 npm은 v0.23.0까지 배포된 상태입니다(2026-09-12 `npm view` 기준). 배포 전에는 아래 설치 명령이 v0.23.0을 받을 수 있으므로, 기능 검증 시 소스 버전과 배포 버전을 구분해 확인하세요.
+- **v0.25.2 추가**: 보안·안정성 보강 — `generate_egovframe_ci`의 `jdk` 입력 검증(생성 YAML 주입 차단), 빌드·테스트 타임아웃 시 프로세스 트리 종료(래퍼가 띄운 JVM 때문에 타임아웃이 걸려도 호출이 끝나지 않던 문제 해결), MCP handshake 서버 버전을 `package.json`과 일치, 의존성 갱신으로 `npm audit` 0건.
+- **배포 상태**: npm 배포본은 **v0.25.1**(2026-09-13 실측), 저장소 소스는 v0.25.2 입니다. v0.25.2는 게시 전입니다.
 
 ## 제공 도구
 
@@ -54,9 +55,9 @@ Claude, VS Code(Copilot), Cursor 등 MCP를 지원하는 AI 도구에서 **대
 - `projectName` — 프로젝트명(artifactId). 소문자·숫자·하이픈 (예: `my-egov-app`)
 - `groupId` — 자바 groupId (예: `egovframework.example`)
 - `database` — `hsql`(기본) | `mysql` | `oracle` | `altibase` | `tibero` (템플릿 `Globals.DbType` 지원 값)
-- `template` — `simple-backend`(기본, Spring Boot REST) | `simple-react` | `simple-homepage` | `portal-site` | `enterprise-business` | `web-sample` | `msa-edu`
+- `template` — `simple-backend`(기본, Spring Boot REST) | `simple-react` | `simple-homepage` | `portal-site` | `enterprise-business` | `web-sample` | `msa-edu` | `msa-common-components` | `mobile-device-api` | `ai-rag` (전체 10종, `list_egovframe_templates`로 확인)
   - 레거시 템플릿(simple-homepage·portal-site·enterprise-business·web-sample)은 `egovProps/globals.properties`의 `Globals.DbType`에 DB 타입을 적용합니다.
-  - `msa-edu`는 멀티 프로젝트(backend/frontend/k8s)라 좌표·DB 자동 적용 없이 원본 그대로 생성하고 README 안내를 반환합니다.
+  - `msa-edu`·`msa-common-components`·`mobile-device-api`·`ai-rag`는 멀티 프로젝트라 좌표·DB 자동 적용 없이 원본 그대로 생성하고 README 안내를 반환합니다.
 - `outputDir` — 생성 위치 상위 디렉터리
 - `ref` — (선택) 내려받을 브랜치/태그. 미지정 시 템플릿 기본 브랜치. 예: `main`, `v4.3.0`
 - `dryRun` — (선택, 기본 `false`) `true`면 디스크에 쓰지 않고 생성 예정 파일 수·적용 설정만 미리보기
@@ -196,7 +197,7 @@ Claude Desktop / Claude Code 설정 예 (`mcpServers`):
 - 리포트 레벨: 픽스처로 `generate_egovframe_report`의 컴포넌트·테이블·가이드 링크 렌더링 검증 (`npm run test:report`, 네트워크 불필요)
 - 업그레이드 레벨: 3-way 판정 6분류(unchanged/update/user-modified/conflict/added/removed)·v1 보수모드·정상 적용/백업 계획·파일/매니페스트 fault-injection rollback·상위 symlink 경계 검증 (`npm run test:upgrade`, 네트워크 불필요)
 - 컴포넌트 설명 레벨: `explain_egovframe_component`의 의존성(직접·전이)·역의존·테이블·가이드 URL·미존재 예외 검증 (`npm run test:explain`, 네트워크 불필요)
-- CI 생성 레벨: `generate_egovframe_ci`의 maven/gradle 감지·YAML·dryRun 무기록·기존 파일 거부·빌드파일 부재 예외 검증 (`npm run test:ci`, 네트워크 불필요)
+- CI 생성 레벨: `generate_egovframe_ci`의 maven/gradle 감지·YAML·dryRun 무기록·기존 파일 거부·빌드파일 부재 예외·`jdk` 주입 입력 거부 검증 (`npm run test:ci`, 네트워크 불필요)
 - CRUD 생성 레벨: 공식 wizard 그룹, Classic/Boot 분기, DB 생성키, JUnit 5, dryRun, PK·경로 검증, 충돌 시 전체 무기록 검증 (`npm run test:crud`, 네트워크 불필요)
 - CRUD 컴파일 레벨: 공식 simple-backend/Boot CRUD 7파일과 web-sample/Classic CRUD 9파일 생성 → JDK 17에서 `mvn -q -DskipTests compile` (`npm run test:crud-integration`, 네트워크 필요, CI 실행)
 - 안전성 레벨: 19개 도구 공통 허용 root의 미설정 호환·격리·`..` 이탈·symlink 우회·다중 root·비대상 인자 무해 6케이스와 구조화 rollback 필드를 검증합니다 (`npm run test:allowed-roots`, `npm run test:transaction`, 네트워크 불필요).
@@ -238,6 +239,13 @@ v0.25.0까지 프로젝트·CRUD 생성, 검증된 공통컴포넌트 실행 자
 
 ## 변경 이력
 
+- **0.25.2** — 보안·안정성 보강(도구 인터페이스 하위 호환).
+  - `generate_egovframe_ci`: `jdk` 값이 생성 워크플로 YAML에 검증 없이 삽입되어 따옴표·줄바꿈으로 임의 step을 끼워 넣을 수 있던 문제를 수정했습니다. 숫자·점 형식(`17`, `21`, `1.8`, `17.0.9`)만 허용하며 도구 스키마와 함수 양쪽에서 거부합니다. 위반 시 파일을 만들지 않습니다.
+  - `build_egovframe_project`·`test_egovframe_project`: 타임아웃 시 직접 자식 프로세스만 종료해, `mvnw`/`gradlew`가 띄운 JVM이 출력 파이프를 붙잡은 채 살아남으면 타임아웃이 지나도 호출이 끝나지 않던 문제를 수정했습니다(재현: `timeoutMs` 1초 설정에 30초 후 반환). POSIX는 프로세스 그룹 단위 SIGKILL, Windows는 `taskkill /T /F`로 트리를 종료하고, 그래도 파이프가 닫히지 않으면 2초 유예 후 결과를 반환합니다. 실제 프로세스를 띄우는 회귀 테스트를 추가했습니다(`npm run test:build`).
+  - MCP handshake의 서버 버전이 `0.23.0`으로 고정되어 있던 것을 `package.json` 버전을 읽도록 변경했습니다.
+  - 의존성: `adm-zip` 0.6.1(0.6.0 이하 대상 symlink 추종·선언 크기 메모리 할당 권고 해소)과 MCP SDK 전이 의존성(hono·fast-uri·ip-address·qs)을 갱신해 `npm audit` 0건입니다.
+  - 문서: `create_egovframe_project` 템플릿 목록을 실제 10종으로 정정했습니다.
+- **0.25.1** — 문서 정정(코드 변경 없음): v0.25.0 시점까지 README 에 남아 있던 "npm 은 v0.23.0 까지 배포" 문구를 실제 배포 상태로 갱신했습니다. npm 패키지 페이지는 게시된 tarball 의 README 를 보여주므로, 문구 정정을 반영하려면 새 버전 게시가 필요해 패치 버전을 올렸습니다.
 - **0.25.0** — 테스트 실행·리포트 구조화: `test_egovframe_project` 추가. `build_egovframe_project(goal=test)`가 종료 코드와 로그만 돌려주던 한계를 보완해, 빌드도구가 쓰는 JUnit XML 리포트(maven-surefire `target/surefire-reports`, gradle `build/test-results/test`)를 1차 근거로 읽습니다. 스위트별 통과·실패·오류·건너뜀과 실패 케이스의 메시지·예외 타입·스택트레이스 내 테스트 클래스 프레임(파일:라인)을 반환하고, `testFilter`는 빌드도구 문법 그대로(`-Dtest=… -Dsurefire.failIfNoSpecifiedTests=false` / `--tests …`) 전달하되 인자 해석을 깨는 문자를 거부합니다. 이번 실행 이전의 리포트는 mtime으로 제외하고, 종료 코드가 0이어도 리포트에 실패가 있으면(`testFailureIgnore`) 실패로 판정하며, 리포트가 없으면 컴파일 오류(로그 파싱)와 원인 후보를 안내합니다. 타임아웃·로그 상한·허용 root·dryRun은 build 도구와 동일. 오프라인 54단언(`npm run test:test`), 외부 의존성 없음. 기존 20개 도구 하위 호환.
 - **0.24.0** — 공식 템플릿 커버리지 확대(7 → **10종**): eGovFrame VSCode Initializr 카탈로그(22항목)와 대조해 MCP가 다루지 않던 공식 자산을 식별하고, GitHub 공개 저장소로 제공되는 `msa-common-components`(MSA 공통컴포넌트, KRDS)·`mobile-device-api`(디바이스 API)·`ai-rag`(Spring AI·LangChain4j RAG 예제)를 추가했습니다. 세 템플릿 모두 하위 모듈을 가진 멀티 프로젝트이므로 `multiProject`로 표시해 좌표·DB 자동 재작성을 건너뛰고 하위 모듈 참조를 보호하며, 생성 결과에 좌표/DB 자동 적용이 없음을 명시합니다. `npm run test:templates`에 등록·표시·공식 저장소 경로 검증과 실제 아카이브를 내려받는 dryRun 통합 검증을 추가했습니다. 기존 7종·전체 도구 하위 호환.
 - **0.21.1 (완료, v0.22.0에 통합)** — 사용자 프로젝트를 손상시키지 않는 실패·복구 경계를 우선 강화했습니다.

package/dist/build-runner.js

@@ -105,27 +105,78 @@ export function capOutput(output, maxLines) {
         return { text: output, truncated: false, totalLines: lines.length };
     return { text: lines.slice(lines.length - maxLines).join("\n"), truncated: true, totalLines: lines.length };
 }
-/** child_process.spawn 기반 기본 runner(타임아웃·스트리밍). */
+/**
+ * 자식 프로세스와 그 하위 트리를 함께 종료한다.
+ *
+ * mvnw/gradlew 는 셸 스크립트라 실제 빌드는 손자 프로세스(JVM)에서 돈다. 직접 자식에게만
+ * 신호를 보내면 JVM 이 살아남아 stdout 파이프를 붙잡고, `close` 이벤트가 오지 않아
+ * 타임아웃이 걸려도 호출이 끝나지 않는다.
+ *  - POSIX: detached 로 띄운 프로세스 그룹 전체(-pid)에 SIGKILL
+ *  - Windows: taskkill /T /F 로 트리 종료
+ */
+export function killProcessTree(pid, platform = process.platform) {
+    if (!pid)
+        return;
+    if (platform === "win32") {
+        try {
+            spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => { });
+        }
+        catch {
+            /* taskkill 을 쓸 수 없는 환경 */
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            /* 이미 종료됨 */
+        }
+    }
+}
+/** 타임아웃으로 트리를 종료한 뒤에도 close 가 오지 않을 때 강제로 결과를 돌려주기까지의 유예. */
+export const KILL_GRACE_MS = 2_000;
+/** child_process.spawn 기반 기본 runner(타임아웃·스트리밍·프로세스 트리 종료). */
 export const defaultRunner = (cmd, opts) => new Promise((resolve) => {
+    const isWin = process.platform === "win32";
     const child = spawn(cmd.command, cmd.args, {
         cwd: cmd.cwd,
-        shell: process.platform === "win32",
+        shell: isWin,
+        // POSIX: 새 프로세스 그룹의 리더로 띄워 그룹 단위로 종료할 수 있게 한다.
+        detached: !isWin,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
     });
     let timedOut = false;
+    let settled = false;
+    let graceTimer;
+    const finish = (exitCode) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (graceTimer)
+            clearTimeout(graceTimer);
+        resolve({ exitCode, timedOut });
+    };
     const timer = setTimeout(() => {
         timedOut = true;
-        child.kill("SIGKILL");
+        killProcessTree(child.pid);
+        // 그룹 밖으로 빠져나간 프로세스가 파이프를 붙잡아도 호출이 끝나도록 보장한다.
+        graceTimer = setTimeout(() => {
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            finish(null);
+        }, KILL_GRACE_MS);
     }, opts.timeoutMs);
     child.stdout?.on("data", (d) => opts.onData(d.toString()));
     child.stderr?.on("data", (d) => opts.onData(d.toString()));
-    child.on("error", () => {
-        clearTimeout(timer);
-        resolve({ exitCode: null, timedOut });
-    });
-    child.on("close", (code) => {
-        clearTimeout(timer);
-        resolve({ exitCode: code, timedOut });
-    });
+    child.on("error", () => finish(null));
+    child.on("close", (code) => finish(code));
 });
 /**
  * 프로젝트를 빌드한다. dryRun이면 실행 없이 감지된 명령만 반환한다.

package/dist/index.js

@@ -28,10 +28,20 @@ export { CRUD_JAVA_TYPES, CRUD_PROFILES, generateCrud } from "./crud.js";
 export { inspectCatalogArchive, syncCatalog } from "./catalog-sync.js";
 export { ProjectFileTransaction, TransactionError, withDirectoryTransaction, withFileTransaction } from "./file-transaction.js";
 export { ALLOWED_ROOTS_ENV, AllowedRootsError, assertPathAllowed, describeAllowedRoots, enforceAllowedRoots, loadAllowedRoots } from "./allowed-roots.js";
-export { detectBuildToolAt, resolveGoals, resolveCommand, parseBuildErrors, capOutput, defaultRunner, runBuild } from "./build-runner.js";
+export { detectBuildToolAt, resolveGoals, resolveCommand, parseBuildErrors, capOutput, defaultRunner, killProcessTree, KILL_GRACE_MS, runBuild } from "./build-runner.js";
 export { reportDirFor, resolveTestArgs, validateTestFilter, locateInStack, parseJUnitXml, snapshotReports, readJUnitReports, summarizeReports, runTests } from "./test-runner.js";
 /** 템플릿 다운로드 제한 시간(ms) — 무응답 시 무한 대기를 방지한다. */
 export const DOWNLOAD_TIMEOUT_MS = 30_000;
+/** MCP handshake 에 알리는 서버 버전 — package.json 을 단일 출처로 사용한다. */
+export const SERVER_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+        return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 /** 지원 템플릿 목록 (공식 eGovFramework 조직 저장소) */
 export const TEMPLATES = {
     "simple-backend": {
@@ -1843,7 +1853,17 @@ function detectBuildTool(projectDir) {
         return "gradle";
     throw new Error(`빌드 파일(pom.xml·build.gradle)을 찾지 못했습니다: ${projectDir}`);
 }
-export function generateCiYaml(buildTool, jdk) {
+/** setup-java 의 java-version 으로 허용하는 형식: 8, 17, 21, 1.8, 17.0.9 등 숫자·점만. */
+export const CI_JDK_RE = /^[0-9]{1,2}(\.[0-9]{1,3}){0,2}$/;
+/** YAML 에 그대로 삽입되는 값이므로 따옴표·줄바꿈 등 구조를 깨는 입력을 거부한다. */
+export function validateCiJdk(jdk) {
+    const v = jdk.trim();
+    if (!CI_JDK_RE.test(v))
+        throw new Error(`jdk 는 숫자와 점으로 된 버전이어야 합니다 (예: 17, 21, 1.8): ${JSON.stringify(jdk)}`);
+    return v;
+}
+export function generateCiYaml(buildTool, jdkInput) {
+    const jdk = validateCiJdk(jdkInput);
     const buildStep = buildTool === "maven"
         ? "      - run: mvn -B verify"
         : "      - run: chmod +x ./gradlew\n      - run: ./gradlew build --no-daemon";
@@ -1899,7 +1919,7 @@ function extractDocSnippet(body, terms) {
     return (start > 0 ? "…" : "") + text.slice(start, start + 200) + (start + 200 < text.length ? "…" : "");
 }
 export function buildServer() {
-    const server = new McpServer({ name: "egovframe-scaffold-mcp", version: "0.23.0" });
+    const server = new McpServer({ name: "egovframe-scaffold-mcp", version: SERVER_VERSION });
     server.tool("list_egovframe_templates", "사용 가능한 전자정부 표준프레임워크 프로젝트 템플릿 목록을 반환합니다.", {}, async () => ({
         content: [
             {
@@ -2419,7 +2439,7 @@ export function buildServer() {
     // ── CI 설정 생성 도구 (v0.19.0) ────────────────────────
     server.tool("generate_egovframe_ci", "프로젝트에 GitHub Actions CI 워크플로(빌드·테스트)를 생성합니다. 빌드도구(maven/gradle) 자동 감지, JDK 지정. dryRun으로 내용만 미리볼 수 있고, 실제 생성 시 기존 파일이 있으면 덮어쓰지 않고 거부합니다.", {
         projectDir: z.string().describe("프로젝트 디렉터리(절대경로 권장)"),
-        jdk: z.string().default("17").describe("JDK 버전 (기본 17)"),
+        jdk: z.string().regex(CI_JDK_RE, "숫자와 점으로 된 버전만 허용 (예: 17, 21, 1.8)").default("17").describe("JDK 버전 (기본 17, 숫자·점만 허용)"),
         dryRun: z.boolean().default(false).describe("true면 파일 생성 없이 내용만 반환"),
     }, async (args) => {
         enforceAllowedRoots(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "egovframe-scaffold-mcp",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "description": "전자정부 표준프레임워크(eGovFrame) 프로젝트·CRUD 스캐폴딩과 검증된 공통컴포넌트 완전 조립 MCP 서버",
   "license": "Apache-2.0",
   "type": "module",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "adm-zip": "^0.6.0",
+    "adm-zip": "^0.6.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {