egovframe-scaffold-mcp

egovframe-scaffold-mcp

English summary: README.en.md · 도구 설명을 영문으로 받으려면 EGOVFRAME_LANG=en

전자정부 표준프레임워크(eGovFrame) 프로젝트 스캐폴딩·조립·진단을 제공하는 MCP(Model Context Protocol) 서버 — 커뮤니티 PoC

eGovFramework/egovframe-common-components#1120 제안의 개념 증명(Proof of Concept) 구현입니다. #628(eGovFrame MCP Server 제안)을 "프로젝트 생성 → 컴포넌트 조립 → 진단·업그레이드" 수명주기로 구체화했습니다.

Claude, VS Code(Copilot), Cursor 등 MCP를 지원하는 AI 도구에서 대화 중 즉시 표준프레임워크 프로젝트를 만들고 공통컴포넌트·AI 계층을 조립할 수 있습니다. 기존 프로젝트 진단, 리포트, 안전한 upstream 재동기화도 지원합니다.

현재 v0.43.0은 **도구 32종(title·annotations·구조화 출력 11종) + CLI 명령 10종, 공식 템플릿 22종, 설정 템플릿 21종, 5.x 전환 규칙(RTE 18모듈·클래스 331종 + 공통컴포넌트 1,089종 근거)과 적용·검증·재조립·사본 리허설, 의존성 기준(공식 parent 관리 좌표 139종+계열 6종+Spring Boot BOM 1,473종+RTE 전이 58종)·해석된 의존성 트리·CycloneDX·SPDX SBOM 생성·점검(최소 요소·비교·VEX), GitHub·GitLab·Jenkins CI 공급망 게이트, 규칙·기준 drift 감시, 폐쇄망 오프라인 번들, 네트워크 진단·AGENTS.md 생성, 공통컴포넌트 카탈로그 190항목(리프 176종+그룹 14종, v5.0.7)**을 제공합니다.

진행 현황 (2026-10-11)

• 源码基准：v0.43.0（package.json），32 种工具 + 10 种 CLI 命令、22 种官方模板、21 种配置模板、190 个目录条目（共通组件 v5.0.7）。
• 安全基线已完成：已纳入 PR #7～#16，具备 provenance、strict assertion、safe remove，以及项目创建、配方、直接组装、AI 组装、升级的 transaction。
• v0.22.0 新增：将 EGOVFRAME_ALLOWED_ROOTS 应用于 19 个工具入口，阻止通过 ..·symlink/junction 越界，并在失败时以结构化形式返回 rollback 结果。PR #16 涉及 7 个文件（+340/−31），本地 16 种测试套件全部通过后合并。
• v0.23.0 新增：build_egovframe_project — 实际构建生成的项目（自动检测 maven/gradle·mvnw/gradlew），并将编译·测试错误按文件/行结构化，完成生成→验证循环。包含超时·日志上限·允许的 root·dryRun。PR #18 涉及 4 个文件（+458/−3），验证了离线 40 条断言和实际 spawn 路径。
• v0.24.0 新增：官方模板覆盖范围从 7 种扩展至 10 种（msa-common-components·mobile-device-api·ai-rag，均为多项目）。PR #19。
• v0.25.0 新增：test_egovframe_project — 运行测试并读取构建工具生成的 JUnit XML 报告（surefire·gradle），按套件·用例结构化结果。包含失败用例的消息·异常类型·测试文件/行、testFilter（类/方法模式）、排除之前运行的报告；即使退出代码为 0，只要报告中有失败就判定为失败。离线 54 条断言（npm run test:test）。
• v0.25.2 新增：增强安全性与稳定性 — 验证 generate_egovframe_ci 的 jdk 输入（阻止注入生成的 YAML），构建·测试超时时终止进程树（解决因包装程序启动的 JVM 导致超时后调用仍无法结束的问题），使 MCP handshake 服务器版本与 package.json 一致，通过更新依赖使 npm audit 结果为 0 项。
• v0.25.3 新增：修复 Linux·macOS 上运行 npx egovframe-scaffold-mcp（经由 bin symlink）时服务器无法启动便退出的问题；CI 扩展为 ubuntu·windows × Node 18·20·22 矩阵。
• v0.26.0 新增：sync_egovframe_templates + catalog/templates.json — 将此前分散在 Initializr（项目 22 种 zip 目录）、MCP（TEMPLATES 中 10 种仓库来源）和 Development（wizards.xml 配置向导）中的“有哪些官方项目”统一为一种 schema。在 catalog/template-mapping.json 中整理映射（不自动推断），并通过工具查询与 upstream 的新增·删除·变更，以及 MCP 覆盖差距（目前 22 种中支持 9 种）。离线 148 条断言（npm run test:template-catalog）。
• v0.27.0 新增：官方模板覆盖范围从 10 种扩展至 22 种（按 Initializr 的 22 种标准，支持数量从 9 种增至 21 种）。通过 Initializr 的 zip（Git LFS）获取无独立仓库的 6 种 batch、空骨架（web·boot-web）、2 种移动端、2 种 MSA 门户模板，并固定 commit、sha256 和大小，以验证下载的字节。sync_egovframe_templates 也会报告 zip 指纹的 upstream 变化（设计：docs/design-initializr-zip-templates.md）。
• v0.28.0 新增：generate_egovframe_config — 将 21 种官方 Initializr 配置模板（datasource·transaction·cache·logging·scheduling·idGeneration·property）随包附带，离线生成 Spring 配置文件。支持 xml·javaConfig·yaml·properties 格式，字段名·默认值与 Initializr 表单一致，并保护已有文件。可通过资源 egovframe://catalog/config-templates 查询字段·默认值·选项；sync_egovframe_templates 会报告随包模板的 upstream 变化（设计：docs/design-config-generation.md）。
• v0.29.0 新增：migrate_egovframe_project 第 1 阶段 — 根据 5.x（Jakarta EE 9+、Spring 6、Java 17）标准扫描 3.x/4.x 项目，并按文件·行报告 RTE Maven 坐标·包·已移除/迁移的类·javax→jakarta·web.xml schema·已移除的 egov-* XML 命名空间·需要替换的库（只读，区分 auto/manual）。规则保存在通过比较 egovframe-runtime 标签（v3.10.0·v4.3.0-Final·v5.0.2-Final）源码树生成的 catalog/migration-rules.json 中，并在 CI 中确认 61 个目标坐标确实存在于 Maven 仓库。官方 5.x 模板中共 2 种，扫描结果为 0 项（设计：docs/design-migration.md）。
• v0.30.0 新增：migrate_egovframe_project 第 2 阶段（apply=true）— 在一个 transaction 中实际替换诊断结果中的 auto 项（默认 dryRun，保留原始文件至 migration-backup/，生成 migration-plan.json，失败时恢复）。在应用 3.10 坐标·javax 测试夹具后，于 CI 中确认 JDK 17 mvn compile 通过。check_egovframe_dependencies — 与从 2 种官方 5.x parent 中提取的基准（139 种受管理坐标 + 7 种 BOM 系列，catalog/dependency-baseline.json）对比依赖，并分类为符合基准/低于基准/由 parent 管理/迁移对象/需要替换/无基准，同时提供依据报告安全配置（sec.security·CSRF·XSS 过滤器·安全标头·HTTPS 仓库）是否存在。默认离线；offline=false 时查询 OSV 漏洞（设计：docs/design-dependency-check.md）。
• v0.31.0 新增：运维便利性 — diagnose_egovframe_network（对工具使用的 7 种主机进行 DNS·HEAD 探测，分类失败类型，并提供 HTTPS_PROXY+NODE_USE_ENV_PROXY·优先使用 IPv4·企业 CA 的 bash/cmd/PowerShell 命令）；所有下载失败消息均附上相同的一行解决建议；generate_agents_md（根据诊断结果生成供 AI 编码工具使用的 AGENTS.md，ko/en）；英文 README（README.en.md）和英文工具说明 EGOVFRAME_LANG=en；MCP Registry 元数据（server.json·mcpName）。规划的 3 个版本（v0.29–v0.31）均已完成。
• v0.32.0 新增：MCP 协议现代化 — 将 27 种工具迁移至 registerTool，在 tools/list 中公开 title（ko/en）和 annotations（readOnlyHint 14 种·destructiveHint 4 种·idempotentHint·openWorldHint）；此前提供 format=json 的 5 种工具（diagnose_egovframe_project·validate_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network）会同时返回 outputSchema 和 structuredContent（保留原有 text）。通过测试可移植性防护（scripts/check-test-portability.mjs，含门禁）和平台注入断言，防止 Windows 专属失败再次发生。
• v0.43.0 新增：CI·提交格式多样化 — generate_egovframe_ci(platform="gitlab"|"jenkins") 会以 .gitlab-ci.yml（JUnit·CycloneDX 报告）·Jenkinsfile（Declarative，Linux sh·Windows bat 通用）生成与 GitHub Actions 相同的构建·供应链门禁，并在三个平台的门禁中都加入 SBOM 最小元素检查（sbom-check --fail-on minimum）。企业 npm 注册表（npmRegistry）·离线包路径（offlineBundle）通过环境变量传入；如果缺少供应商线索，会提前提示门禁将失败。SBOM 也可输出为 SPDX 2.3 JSON — generate_egovframe_sbom(bomFormat="spdx-json") 包含软件包·DEPENDS_ON 关系（无依赖时为 NONE）·purl·供应商·creators·created·校验和·声明许可证·OSV 建议·基准判定（annotations）；check_egovframe_sbom 会自动判别格式，并使用同样的 7 种最小元素·重新判定·比较来检查 SPDX（VEX 仅支持 CycloneDX）。以官方 web 模板实际通过 Maven 生成的 SBOM 转换为 SPDX 后，component 数量仍为 67、最小元素判定（包括各元素满足数量）相同，SPDX ↔ CycloneDX 比较差异为 0；生成的 .gitlab-ci.yml 通过 GitLab 官方 CI schema 验证，SPDX 输出通过官方 spdx-spec v2.3 schema 验证。工具数仍为 32 种。
• v0.42.0 新增：封闭网络（网络隔离）运维 — 新工具 prepare_egovframe_offline_bundle（第 32 个）在可联网 PC 上将完整 OSV Maven 漏洞转储（≈10MB，7,190 条）·固定的共通组件归档（sha256 验证）·Initializr zip 模板（固定指纹）·用于重新组装的 22 个官方共通组件标签镜像（≈37MB）放入同一目录，并写入 bundle-manifest.json（逐文件记录 sha256·大小·来源 URL·获取时间）。在封闭网络 PC 上只需设置 EGOVFRAME_OFFLINE_BUNDLE：下载会验证指纹后使用包内文件（拒绝篡改），offline=false 时的 OSV 查询会根据本地转储判定（显示快照基准日期，超过 30 天会警告），重新组装会使用包内镜像。CI 确认：同一天获取的转储，其本地判定与在线 OSV 在 73/73 次查询·134/134 个 ID 上一致；在阻断网络的情况下，仅凭离线包即可完成项目创建·共通组件组装·重新组装预览·SBOM 复查（网络尝试次数为 0）。CLI bundle，网络诊断中的离线包解决建议。
• v0.41.0 新增：迁移演练 — 新工具 rehearse_egovframe_migration（第 31 个）不会触碰项目，而是在副本中执行共通组件重新组装 → 应用迁移的自动项目 → 编译 → 将 pom 调整为官方共通组件 v5.0.7 基准 → 再次编译，以测量“自动步骤后实际还剩多少需要人工修复的内容”（不受 javac 100 个错误上限影响，统计全部错误；通过执行前后指纹确认原始项目未变）。官方共通组件 v4.3.2 完整树（6,523 个文件）在自动步骤后有 6,003 个编译错误（CI·JDK 17；JDK 21 为 6,335 个），除 4 个外，其余均由缺失包及其连锁影响引起（pom 依赖项、因此无法运行的 Lombok getter 等）；调整 pom 后只剩 1 个（GPKI 供应商 jar 中的 javax 引用）——CI 将此数值固定为预期值。还修复了实测中发现的两个缺陷：必须先重新组装再应用迁移，才能识别原始标签（反过来会将 4.3.2 误认为 v5.0.1）；修正了将 4.x 的 org.egovframe.rte 坐标归类为 5.x 的问题，以及将 Maven 警告·fork 格式错误解析为编译错误的问题。评估报告第 6 节也包含近期演练实测结果。
• v0.40.0 新增：SBOM 运维 — 新工具 check_egovframe_sbom（第 30 个）检查已生成的 CycloneDX SBOM，作为提交材料。(1) 逐个 component 统计 7 种最小元素（供应商·组件名·版本·唯一标识符·依赖关系·作者·生成时间；NTIA 最小元素 = 韩国 SW 供应链安全指南的核心构成要素），判断“可提交/需要完善”；(2) 无需构建工具，仅凭 purl 重新进行基准判定和 OSV 查询，报告生成后变化的判定·新发现的漏洞；(3) 对比与旧 SBOM 之间的新增·删除·版本·判定·漏洞差异；(4) 若 vex=true，生成 CycloneDX VEX 草案（新漏洞标记为 in_triage，保留人工填写的判定）。generate_egovframe_sbom 提供 supplier·author 选项（默认使用 pom <organization>），并在生成阶段通过供应商表填充最小元素。官方 web 模板 SBOM 的供应商（含主 component 共 18 种）·作者字段为空，判定为“需要完善”；使用选项重新生成后则为“可提交”；SBOM·VEX 均通过 CycloneDX 1.6 官方 schema 验证。CLI sbom-check；评估报告第 5 节包含最小元素·VEX 状态。规划的 3 个版本（v0.38–v0.40）均已完成。
• v0.39.0 新增：CLI 模式和 CI 供应链门禁 — npx egovframe-scaffold-mcp <assess|check|sbom|migrate|validate|diagnose|network> 可在无需 AI 客户端的情况下执行相同分析并退出（不带参数时仍按原有 stdio 服务器运行）。--json 输出与 MCP structuredContent 相同的对象；若超过 --fail-on supplyChain:C·vulnerabilities·manual>20 等标准，则以退出代码 2 停止流水线。generate_egovframe_ci(supplyChain=true) 会创建从 SBOM 生成 → 评估报告（在 PR 摘要中显示等级）→ 构件的门禁 job（生成结果在 CI 中通过 actionlint 检查）。升级至 MCP SDK 1.32.1（协议 2025-11-25）。
• v0.38.0 新增：执行共通组件重新组装 — 新工具 reassemble_egovframe_components（第 29 个）通过将复制到 3.x/4.x 项目的共通组件源码的原始标签与官方仓库标签的 git blob id 对比来识别来源（不下载文件内容），逐个文件根据原始·当前·目标版本进行 3-way 判定，然后按 v5.0.7 重新组装。以相对于原始版本的 unified diff 补丁保留用户修改，并返回任务列表；同时生成 manifest，以供之后的 upgrade·validate·remove 直接应用。将共通组件目录·迁移规则的对应表更新为 upstream 新标签 v5.0.7（2026-10-06）。在修改了官方 v3.10.0 树中 cmm·bbs 的测试夹具上，CI 确认识别出原始 v3.10.0（99%）、780 个文件与 v5.0.7 tree 一致、validate 缺失数为 0、upgrade 变更数为 0。
• v0.37.0 新增：迁移就绪度评估报告 + 回归语料库 — generate_egovframe_report(sections=["assessment"]) 一次运行诊断·迁移诊断·依赖·安全配置·SBOM 检查，生成包含六节（概览·迁移范围·依赖处置清单·安全·SBOM·等级和依据）的评估报告。分别以 A–D 评定迁移难度和供应链状态，并在报告中完整列出各项因素·区间·分数计算方法，以便人工重新计算（测试也会实际重新计算）；支持 format=json（outputSchema）·outputPath（仅新文件，transaction）。回归语料库 test:migrate-corpus 在官方共通组件 v3.10.0·v4.3.2 部分树（固定 commit，sparse clone ≈3 秒）上运行诊断·dryRun 应用·依赖检查·评估报告，并在 CI 中断言结果与 catalog/migration-corpus.json 中的预期值相差不超过 ±1%——首次用实际资产验证 4.x→5.x 路径；两个版本均为确认需要检查的类 0、无基准 1（xerces）。发布工作流会继续未完成的发布（在 npm 的 gitHead commit 上打标签，等待传播 10 分钟·仅警告）。规划的 3 个版本（v0.35–v0.37）均已完成（设计：docs/design-assessment-report.md）。
• v0.36.0 新增：解析后的依赖树 + SBOM — check_egovframe_dependencies(resolve=true) 使用 Maven（dependency:tree）·Gradle（dependencies）解析传递依赖，并与基准·OSV 对比。每项包含 origin·树路径 via；与声明不同的解析版本标记为 differs。官方 egovframe-web 模板声明了 19 项·处置数量为 0，但解析后可看到 65 个 artifact 中有 11 项低于基准·24 项 OSV 建议。新工具 generate_egovframe_sbom（第 28 个）无需修改构建文件即可生成 CycloneDX 1.6 JSON（Maven 使用 cyclonedx-maven-plugin，包含哈希·许可证；Gradle 使用解析后的依赖树构建），为每个 component 添加基准判定（egovframe:status·basis·baseline）；offline=false 时将 OSV 结果写入 vulnerabilities[]——可用于 2027 年起分阶段实施的公共机构 SBOM 注册·提交。
• v0.35.0 新增：发布自动化 — main 上的 CI 成功后，release.yml 会检查四项条件（server.json 版本一致·存在变更记录条目·尚无标签·尚未发布至 npm），并依次发布到 npm（OIDC trusted publishing，自动提供 provenance）→ 在该 commit 上打标签 → GitHub Release（从变更记录中提取）→ MCP Registry（GitHub OIDC）。人工只需合并 PR。门禁新增 test:release（判定函数·发布说明·npm pack 内容·大小上限）和 server.json 描述 100 字符限制（注册表验证条件——修复了通过实际 mcp-publisher validate 发现的缺陷）。
• v0.34.0 新增：完善依赖基准 + 监控规则·基准 drift — 在 check_egovframe_dependencies 的基准中加入 完整 Spring Boot BOM（spring-boot-dependencies 3.5.6 直接条目 + 展开一层的 44 种 BOM import，共 1,473 个坐标）和 18 种 RTE 模块的传递依赖（58 个坐标，标明由哪个模块引入），并为每项标注基准来源（parent 直接·系列·Boot BOM·RTE 传递·迁移规则）；国内供应商·机构分发的坐标归类为 vendor；将 EOL·旧坐标（旧版 MySQL/Oracle 驱动·Jackson 1·xmlbeans·Ehcache 2·HttpClient 4·ANTLR 3·Spring Social）归类为替换规则，将官方共通组件 3.10 pom 中“无基准”项从 17 个降至 1 个。sync_egovframe_templates 会附带更新流程报告随包规则·基准的 upstream drift（egovframe-runtime·共通组件的新标签、官方 parent 新版本、固定 pom sha256 变化）。基准 parent 升级至 5.0.2。
• v0.33.0 新增：migrate_egovframe_project 第 3 阶段 — verify=true 会运行 compile，将编译错误与手动项目关联，并生成按“处理后可解决的错误数量”排序的任务列表（解析 javac 的 symbol:/location:）。在规则目录（schemaVersion 2）中加入共通组件 3.x→5.x 对应表（egovframe-common-components v3.10.0↔v5.0.6，移除 54 项·迁移 4 项），用于诊断 egovframework.com.* 已移除·迁移的类；对于混有 3.x 共通组件源码的项目，会建议按组件重新组装（使用 skipComponents 排除替换）。
• 后续计划：v0.41–v0.43 的规划均已完成（规划原文与结果）。尚无后续三个版本的规划。
• 发布状态：npm 最新发布版本以顶部 npm 徽章和 npm 包页面为唯一来源进行确认。本文档中的版本以仓库源码（package.json）为准；git 标签 vX.Y.Z 指向对应发布版本的 commit。

제공 도구

도구	설명
create_egovframe_project	공식 템플릿을 내려받아 projectName(artifactId)·groupId·DB 타입을 적용한 새 프로젝트 생성
list_egovframe_templates	사용 가능한 공식 템플릿 목록
sync_egovframe_catalog	공식 common-components 태그·commit·archive SHA-256/크기/파일 수 검증, sec.security와 미매핑 upstream 경로 탐지
list_egovframe_components	선택 설치 가능한 공통컴포넌트 카탈로그 (공식 v5.0.7 고정, 리프 176종 + 그룹 14종 — 리프는 서비스 단위, 그룹 id는 하위 일괄 설치)
add_egovframe_components	공통컴포넌트 완전 조립 — 소스·매퍼·JSP와 message·IDGN·scheduling·정적 자산·Spring/web fragment 복사, Maven 좌표 탐지, 컴포넌트별 선별 DDL·DML 생성(database), archive 검증·충돌 전체 거부·쓰기 실패 롤백·dryRun
search_egovframe_components	키워드로 컴포넌트 검색 (id·이름·설명, 점수순 상위 10건)
remove_egovframe_components	설치 매니페스트 기반 트랜잭션 제거 — 의존 컴포넌트·사용자 수정 hash 보호, dryRun 분류, force 시 remove-backup/ 백업 후 제거
validate_egovframe_project	조립 프로젝트 무결성 진단 — 파일 존재·DbType↔DB 스크립트 일치
get_egovframe_guide	컴포넌트의 공식 가이드 문서 조회 (egovframe-docs, 151종 매핑)
add_ai_components	공식 egovframe-ai-rag 샘플 기반 AI RAG 챗봇 조립 — Spring AI(Redis Stack)·LangChain4j(PGVector) 스택 선택(상호 배타), 소스·설정(application-ai.yml 프로필)·UI·인프라 복사, pom 누락 의존성만 마커 구간 삽입(백업 생성, 제거 시 원복), 충돌 시 전체 거부, dryRun 미리보기 (설계: docs/design-ai-components.md)
list_egovframe_recipes	큐레이션된 레시피(템플릿+컴포넌트 번들) 목록
apply_egovframe_recipe	레시피 하나로 생성→컴포넌트(→AI 계층)까지 조립하고 전체 성공 시에만 최종 경로로 atomic commit. 공식 템플릿이 제공하는 공통기반은 확인·보존하고 추가 컴포넌트만 설치 (dryRun 지원)
diagnose_egovframe_project	기존/레거시 프로젝트를 스캔해 빌드시스템·RTE 버전·DbType·설치 공통컴포넌트(pathPrefixes 지문)·설정 문제 진단 (읽기 전용)
search_egovframe_docs	공식 가이드 문서(egovframe-docs) 인덱스를 키워드로 검색 — 제목·경로·연계 컴포넌트, 문서 URL·조립용 id 반환 (오프라인)
generate_egovframe_report	프로젝트 리포트 — sections=["components"](기본) 설치 컴포넌트·참조 테이블·가이드 링크·이슈, sections=["assessment"] 5.x 전환 준비도 평가서(개요·전환 범위·의존성 조치·보안·SBOM·A–D 등급과 산식). Markdown/json, outputPath 로 새 파일 저장(선택)
reassemble_egovframe_components	3.x/4.x 프로젝트에 복사된 공통컴포넌트 소스를 v5.0.7 로 재조립 — 원본 태그 식별(git blob id 대조), 원본·현재·목표 3-way 판정, 사용자 수정은 패치·작업 목록으로 보존, 5.x 에서 없어진 파일은 백업 후 삭제, 매니페스트 생성, dryRun 기본·transaction·verify(compile)
rehearse_egovframe_migration	전환 리허설 — 프로젝트 사본에서 재조립 → 전환 적용 → 컴파일 → pom 맞춤(공식 공통컴포넌트 v5.0.7 기준 parent·좌표·버전·scope) → 컴파일. 두 시점의 오류 수(javac 상한 없이), 누락 패키지·후보 좌표·연쇄 오류, 남는 수동 항목·파일, 사라지는 오류 순 작업 목록, 사본 pom 패치. 원본 불변(지문 비교), 최근 결과는 평가서에 실측으로
upgrade_egovframe_project	설치 컴포넌트를 upstream과 3-way 비교해 갱신 — 사용자 수정 보존, dryRun 기본, 적용 직전 재검증, 파일·백업·매니페스트 단일 transaction (파괴적, 게이트)
explain_egovframe_component	컴포넌트 하나의 상세(설명·직접/전이 의존성·역의존·참조 테이블·가이드 링크·설치 명령)를 한 번에 반환 (읽기 전용)
generate_egovframe_ci	CI 설정 생성 — platform 으로 GitHub Actions(기본)·GitLab CI(.gitlab-ci.yml)·Jenkins(Jenkinsfile, Declarative), maven/gradle 자동 감지, dryRun, 기존 파일 보호. supplyChain=true 면 SBOM → 최소 요소 점검 → 전환 준비도 평가서 게이트(failOn 기준 초과 시 실패, 보고서·SBOM 보관), npmRegistry·offlineBundle 환경 변수
build_egovframe_project	생성한 프로젝트를 실제로 빌드(compile·test·package) — maven/gradle·mvnw/gradlew 자동 감지, 타임아웃·로그 상한, 컴파일 오류 파일/라인 구조화, dryRun
test_egovframe_project	테스트 실행 + JUnit XML 리포트(surefire·gradle) 구조화 — 스위트별 통과/실패/오류/건너뜀, 실패 케이스 메시지·예외 타입·테스트 파일/라인, testFilter, 이전 실행 리포트 제외, dryRun
generate_egovframe_crud	공식 Development CRUD wizard 입력 체계 기반 코드 생성 — VO·Mapper(XML)·Service·Controller·JSP(선택)·JUnit 5(선택), Classic/Boot 분기, 전체 충돌 사전 검사
sync_egovframe_templates	공식 프로젝트 템플릿 통합 카탈로그(Initializr·MCP·Development) upstream 대조 — 추가/삭제/변경 항목과 MCP 커버리지 격차, zip 조달 템플릿의 고정 지문(sha256·크기)과 동봉 설정 템플릿의 변화 보고, 동봉 5.x 전환 규칙·의존성 기준 카탈로그의 drift(새 RTE·공통컴포넌트 태그, 새 parent 버전, 고정 pom sha256 변화)와 갱신 절차 보고, 네트워크 필요
generate_egovframe_config	공식 Initializr 설정 템플릿 21종으로 Spring 설정 파일 생성(오프라인 동봉) — datasource(DBCP/C3P0/JDBC·JNDI)·transaction(datasource/JPA/JTA)·cache·logging(log4j2 5종)·scheduling(Quartz 5종)·idGeneration(3종)·property, xml/javaConfig/yaml/properties, Initializr 폼과 같은 필드·기본값, 기존 파일 거부, dryRun
migrate_egovframe_project	3.x/4.x 프로젝트의 5.x(Jakarta EE 9+·Spring 6·Java 17) 전환 — 진단(기본, 읽기 전용): RTE Maven 좌표(egovframework.rte:egovframework.rte.*·org.egovframe.rte:org.egovframe.rte.* → org.egovframe.rte:egovframe-rte-*)·RTE 버전·저장소 URL·5.x parent, 패키지 접두어·이름 변경·제거 클래스(대체 안내), javax→jakarta 패키지·의존성 좌표, web.xml 스키마, 제거된 egov-security/access/crypto 네임스페이스, 교체 필요 라이브러리를 파일·라인 단위 auto/manual 항목으로 보고. 적용(apply=true): auto 항목을 transaction 으로 치환, dryRun 기본, 원본 migration-backup/ 보관·migration-plan.json, 실패 시 복구, 적용 후 재진단. 검증(verify=true): compile 실행 후 컴파일 오류를 수동 항목과 연결한 작업 목록(해결될 오류 수 순). 공통컴포넌트 3.x→5.x 대응표(제거·이동 클래스)와 컴포넌트 단위 재조립 권고, skipComponents
check_egovframe_dependencies	의존성 점검(읽기 전용) — 선언된 의존성(resolve=true 면 Maven dependency:tree·Gradle dependencies 로 해석한 전이 의존성까지, 트리 경로·선언/해석 버전 차이 포함)을 공식 5.x parent 기준(관리 좌표 139종 + Spring/Security/Boot 등 BOM 계열) + Spring Boot BOM 전체(1,473종) + RTE 모듈 전이 의존성(58종)과 대조해 기준 충족/기준 미만/parent 관리/전환 대상(3.x·4.x RTE·javax)/교체 필요(DBCP 1.x·Log4j 1.x·Jackson 1·Ehcache 2 등)/벤더 배포(국내 DBMS·GPKI)/기준 없음 분류(항목마다 기준 출처 표시), 5.x parent·Java 버전 판정, 보안 설정 존재 점검(sec.security·CSRF·XSS 필터·보안 헤더·HTTPS 저장소, 파일·라인 근거). 기본 오프라인, offline=false 면 OSV 취약점 조회
diagnose_egovframe_network	도구가 내려받는 호스트 7종(codeload·raw·media.githubusercontent, maven.egovframe.go.kr, repo1.maven.org, registry.npmjs.org, api.osv.dev)에 DNS 조회·HEAD 요청을 보내 도달 여부·소요 시간·실패 종류(DNS·타임아웃·TLS·프록시 인증·거부)를 보고하고, 환경에 맞는 처방(HTTPS_PROXY+NODE_USE_ENV_PROXY=1, NODE_OPTIONS=--dns-result-order=ipv4first, NODE_EXTRA_CA_CERTS)을 bash/cmd/PowerShell 명령으로 안내. 프로젝트 디렉터리 불필요, 파일 무기록
prepare_egovframe_offline_bundle	폐쇄망 오프라인 번들 — 인터넷 PC 에서 OSV Maven 덤프·고정 공통컴포넌트 아카이브·Initializr zip 템플릿·공통컴포넌트 태그 미러를 sha256 manifest 와 함께 새 디렉터리에 담음(dryRun 기본). 폐쇄망에서는 EGOVFRAME_OFFLINE_BUNDLE 로 다운로드·OSV·재조립 원본을 번들로 대체
generate_egovframe_sbom	SBOM 생성 — Maven/Gradle 프로젝트의 CycloneDX 1.6 JSON(기본) 또는 SPDX 2.3 JSON(bomFormat="spdx-json")을 빌드 파일 변경 없이 생성(Maven: cyclonedx-maven-plugin makeAggregateBom, 해시·라이선스 포함 / Gradle: 해석된 의존성 트리로 구성). enrich 로 component 마다 기준 판정(egovframe:status·basis·baseline) 속성, offline=false 로 OSV 취약점을 vulnerabilities[] 에 포함. 출력은 프로젝트 안 경로(기본 sbom/bom.cdx.json, SPDX 는 sbom/bom.spdx.json), 기존 파일은 overwrite 없이는 거부, dryRun(기본)은 계획만
check_egovframe_sbom	SBOM 점검 — 기존 CycloneDX·SPDX 2.x SBOM(형식 자동 판별)의 최소 요소 7종(공급자·구성요소명·버전·고유식별자·의존관계·작성자·생성 시각) 충족 여부와 빠진 component, 빌드 도구 없이 purl 로 기준 재판정·OSV 재조회(생성 이후 새 취약점), baselinePath 와 비교(추가·제거·버전·판정·취약점), vex=true 면 CycloneDX VEX 초안(in_triage, BOM-Link, 사람의 판단 보존, CycloneDX 입력만). SBOM 파일은 바꾸지 않음
generate_agents_md	프로젝트 진단 결과로 AI 코딩 도구용 AGENTS.md 생성 — 빌드·테스트 명령(래퍼 감지), RTE·5.x 전환 상태, DbType, 기본 패키지·설정 디렉터리, 설치 컴포넌트(매니페스트 여부), 규칙(좌표·백업 디렉터리·비밀 정보·의존성 기준), MCP 도구 목록. 기존 파일은 overwrite 없이는 거부, dryRun, ko/en, 파일명 변경(CLAUDE.md 등)

create_egovframe_project 参数

• projectName — 项目名称（artifactId）。使用小写字母、数字和连字符（例如：my-egov-app）
• groupId — Java 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 | msa-common-components | mobile-device-api | ai-rag | web | boot-web | batch-file-scheduler | batch-file-commandline | batch-file-web | batch-db-scheduler | batch-db-commandline | batch-db-web | mobile-web | mobile-common-components | msa-portal-backend | msa-portal-frontend（共 22 种，通过 list_egovframe_templates 查看）
  • 旧版模板（simple-homepage·portal-site·enterprise-business·web-sample）会将 DB 类型应用到 egovProps/globals.properties 的 Globals.DbType。
  • msa-edu·msa-common-components·mobile-device-api·ai-rag 是多项目模板，会原样生成，不自动应用坐标和 DB 类型，并返回 README 指引。
  • 从 web 到 msa-portal-frontend 的 12 种模板使用 Initializr zip 获取。获取固定 commit 的 zip 后，会验证 sha256 和大小，再填充 pom.xml 中的 ###GROUP_ID### 等占位符，并将 DB 类型应用到 globals.properties（批处理模板位于 egovframework/batch/properties/）。msa-portal-* 这 2 种是多项目模板，不会自动应用设置。
• outputDir — 生成位置的上级目录
• ref — （可选）要下载的分支或标签。未指定时使用模板默认分支。例如：对于 v4.3.0 zip 获取模板，指定 ref 会跳过固定指纹验证，并在结果中注明这一点。
• dryRun — （可选，默认 false）设为 true 时不会写入磁盘，而是预览计划生成的文件数量和应用的设置

工作方式：下载官方模板 zip → 解压（防止 zip-slip）→ 应用 pom.xml 的 groupId/artifactId/name（保留父 POM 坐标）→ 设置 application.properties 的 Globals.DbType；前端模板还会设置 package.json 的 name。如果目标目录已存在，则拒绝操作。下载超时时间为 30 秒，无响应时不会无限等待。可先使用 dryRun 安全预览。

generate_egovframe_crud 核心参数

• projectDir — 目标 Maven/Gradle 项目
• tableName、entityName — DB 表名和要生成的类名（省略 entityName 时，会根据表名转换）
• basePackage — 基础包。也可以分别覆盖 mapper·VO·service·impl·controller 包。
• fields — 列规范，包括 columnName、javaType、jdbcType、primaryKey、generated、nullable、label。为安全生成 update/delete，至少需要一个主键。
• profile — classic（Spring MVC+JSP）或 boot（REST Controller）
• checkDataAccess、checkService、checkWeb — 对应官方 wizard.xml 的生成组
• includeJsp、withTest、dryRun — 选择生成 JSP·JUnit 5 测试，并支持不写入文件的预览

generate_egovframe_crud(
  projectDir="/work/my-egov-app",
  tableName="SAMPLE_BOARD",
  entityName="Board",
  basePackage="egovframework.example.board",
  profile="classic",
  fields=[
    { columnName: "BOARD_ID", javaType: "Long", jdbcType: "BIGINT", primaryKey: true, generated: true },
    { columnName: "TITLE", javaType: "String", jdbcType: "VARCHAR", nullable: false }
  ],
  withTest=true,
  dryRun=true
)

生成前会检查所有目标路径；只要有一个现有文件，就不会写入任何文件。支持的类型和输出约定请参阅CRUD 生成设计。

generate_egovframe_config 核心参数

• projectDir — 目标项目
• configId — 配置模板 ID：datasource datasource-jndi transaction-datasource transaction-jpa transaction-jta cache-ehcache-default cache-spring logging-console logging-file logging-rolling-file logging-time-rolling-file logging-jdbc scheduling-bean-job scheduling-method-job scheduling-simple-trigger scheduling-cron-trigger scheduling-scheduler idgen-sequence idgen-table idgen-uuid property
• format — xml（默认）| javaConfig | yaml | properties（yaml·properties 仅适用于 logging 系列）
• fields — 覆盖模板变量。字段名称和默认值与 Initializr 网页视图表单相同（例如：txtDatasourceName、rdoType（DBCP|C3P0|JDBC）、txtDriver、txtUrl、txtUser、txtPasswd、txtConfigPackage）。模板中不存在的字段或不在选项范围内的值会被拒绝。完整列表请参阅资源 egovframe://catalog/config-templates
• fileName — 文件名（不含扩展名）或 JavaConfig 类名。未指定时使用 Initializr 默认值（如 context-datasource、EgovDataSourceConfig 等）
• outputDir — 项目相对路径。未指定时，xml → src/main/resources/egovframework/spring（logging 为 src/main/resources），javaConfig → src/main/java/<패키지>
• dryRun — 仅返回内容·路径·上下文

generate_egovframe_config(
  projectDir="/work/my-egov-app",
  configId="datasource",
  format="javaConfig",
  fields={ txtConfigPackage: "kr.go.sample.config", rdoType: "C3P0", txtUrl: "jdbc:mysql://db:3306/app", txtUser: "app", txtPasswd: "…" }
)

如果文件已存在，则会拒绝操作且不会写入；结果的上下文中会隐藏密码字段。模板以 commit 和 sha256 固定的方式随附，来源为 eGovFramework/egovframe-vscode-initializr（Apache-2.0）的 templates/config。设计以及在 upstream 中发现的问题请参阅配置文件生成设计。

migrate_egovframe_project 파라미터

• projectDir — 진단할 프로젝트(허용 root 적용). pom.xml(다중 모듈 포함)·build.gradle(.kts)·*.java·*.xml·*.jsp·web.xml·*.properties/yml 을 읽으며 target/·build/·.git/·node_modules/ 는 건너뜁니다
• target — 5.x(기본이자 현재 유일)
• format — markdown(기본, 수동 항목 → 자동 항목 순 요약) | json(항목 배열 {file, line, kind, from, to, action, reason, edits?} 과 summary.byKind, sourceEra)
• apply — true 면 2단계(적용). dryRun(기본 true)이면 파일별 변경 미리보기만, false 면 실제 치환
• verify — true 면 3단계(검증): 진단 뒤 compile 을 실행해 컴파일 오류를 수동 항목과 연결한 작업 목록을 반환(빌드 도구 필요, 파일 무기록)
• skipComponents — true 면 3.x 공통컴포넌트 디렉터리(재조립 권고 대상)의 자동 항목을 치환하지 않고 수동으로 남김

migrate_egovframe_project(projectDir="/work/legacy-3.10-app")                       # 1단계 진단
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", apply=true)           # 적용 계획(미리보기)
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", apply=true, dryRun=false)  # 적용
migrate_egovframe_project(projectDir="/work/legacy-3.10-app", verify=true)   # 컴파일 → 오류 ↔ 수동 항목 작업 목록

action 이 auto 인 항목(좌표·RTE 버전 속성·패키지 접두어·패키지 이름 변경·javax→jakarta 패키지와 의존성 좌표·저장소 URL·Java 버전·web.xml 스키마)은 적용 단계가 원문 오프셋 기준으로 치환하고, manual(제거된 클래스·네임스페이스·교체 필요 라이브러리·Spring 버전·5.x parent 권고)은 사유와 대체 API 를 함께 남깁니다. 적용은 하나의 transaction 이며 원본을 migration-backup/<시각>-<id>/ 에 보관하고 migration-plan.json 을 남깁니다. 중간에 실패하면 작업 전 상태로 되돌립니다. 규칙의 출처와 제거 클래스 38종의 대체 근거는 전환 진단 설계를, 규칙 자체는 리소스 egovframe://catalog/migration-rules 를 참고하세요. 이 도구는 파일을 쓰지 않습니다.

check_egovframe_dependencies 파라미터

• projectDir — 점검할 프로젝트(허용 root 적용). Maven(다중 모듈 pom, <properties> 해석) 또는 Gradle
• offline — true(기본) 오프라인 기준 대조만 | false OSV(api.osv.dev) 취약점 조회 추가
• resolve — true 면 빌드 도구로 의존성 트리를 해석해 전이 의존성까지 판정(Maven maven-dependency-plugin:3.8.1:tree, Gradle dependencies --configuration runtimeClasspath; 빌드 도구·저장소 접근 필요). resolveScope runtime(기본) | all(test·provided 포함), resolveTimeoutMs
• format — markdown | json

check_egovframe_dependencies(projectDir="/work/my-egov-app", offline=false)
check_egovframe_dependencies(projectDir="/work/my-egov-app", resolve=true, offline=false)   # 실제로 실리는 artifact 전부

resolve=true 결과는 항목마다 origin(declared·transitive)과 전이 경로 via(예 egovframe-rte-ptl-mvc → spring-webmvc), 선언과 다르게 해석된 버전(treeVersion·resolution.differs)을 담고, parent 가 관리하는 좌표가 기준 미만 버전으로 해석되면 비고에 알립니다. 해석에 실패하면 선언 기준 결과에 이유를 붙여 돌려줍니다.

기준은 공식 5.x parent(org.egovframe.web:egovframe-web-config-parent·org.egovframe.boot:egovframe-boot-starter-parent 5.0.2)의 properties·dependencyManagement, Boot parent 가 상속하는 Spring Boot BOM 전체(spring-boot-dependencies 3.5.6 + import 한 단계), RTE 모듈 18종의 전이 의존성에서 추출한 catalog/dependency-baseline.json(schemaVersion 2) 이며 리소스 egovframe://catalog/dependency-baseline 로 조회할 수 있습니다. 대조 순서는 parent 직접 → 계열 → (Boot parent 프로젝트) Boot BOM → RTE 전이, 그 밖은 RTE 전이 → Boot BOM 이고 항목마다 basis 로 출처를 적습니다. RTE 전이 버전보다 낮게 명시한 좌표는 "충돌 가능" 사유와 함께 기준 미만으로 봅니다. 국내 벤더·기관 배포 좌표(Altibase·Tibero·CUBRID·GPKI·mGov)는 vendor, 기준에 없는 좌표는 unknown(판단 보류)으로 두고 둘 다 조치 목록에 넣지 않습니다. 보안 점검은 설정의 존재 여부와 근거만 보고합니다(설계: 의존성 점검 설계).

generate_egovframe_sbom 파라미터

• projectDir — Maven 또는 Gradle 프로젝트(허용 root 적용)
• bomFormat — cyclonedx-json(기본, CycloneDX 1.6) | spdx-json(v0.43, SPDX 2.3 — CycloneDX 로 만든 뒤 변환)
• outputPath — 프로젝트 상대 경로(기본 sbom/bom.cdx.json, SPDX 는 sbom/bom.spdx.json; ..·절대 경로·symlink 이탈 거부), overwrite — 기존 파일 덮어쓰기(기본 거부)
• scope — runtime(기본: compile+runtime) | all(test·provided 포함)
• enrich — true(기본) component 마다 egovframe:status·egovframe:basis·egovframe:baseline 속성 부착
• offline — true(기본) | false OSV 결과를 CycloneDX vulnerabilities[](affects 로 component 참조)로 포함
• dryRun — true(기본) 실행 없이 명령·출력 경로만 | false 생성·기록, timeoutMs(기본 600000)
• v0.40: supplier(공급자 — 주 component 와 metadata.supplier, 기본 pom <organization><name>)·author(metadata.authors, 기본 supplier)·componentName·componentVersion(주 component 덮어쓰기), fillSuppliers(기본 enrich 와 같음 — 공급자가 없는 component 를 catalog/sbom-rules.json 공급자 표로 보완하고 egovframe:supplierBasis=catalog 로 표시). 응답의 minimum 이 최소 요소 7종 판정을 요약합니다.

generate_egovframe_sbom(projectDir="/work/my-egov-app")                              # 계획만
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, offline=false)  # sbom/bom.cdx.json + OSV
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, supplier="○○기관", author="○○정보기술")  # 최소 요소까지
generate_egovframe_sbom(projectDir="/work/my-egov-app", dryRun=false, bomFormat="spdx-json", supplier="○○기관")  # sbom/bom.spdx.json (SPDX 2.3)

Maven 은 org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom 을 좌표를 완전히 적어 호출하므로 pom 을 바꾸지 않으며(해시·라이선스 포함, 멀티 모듈 합산), Gradle 은 해석된 트리로 이 서버가 문서를 구성합니다(해시·라이선스 없음, 빌드 파일 변경 없음). 문서의 metadata.tools 에 이 서버가 기록됩니다. 기준 판정은 check_egovframe_dependencies 와 같은 규칙입니다(설계: 의존성 점검 설계).

check_egovframe_sbom 파라미터 (SBOM 점검)

• sbomPath — 점검할 SBOM(기본 sbom/bom.cdx.json; CycloneDX JSON 또는 SPDX 2.x JSON, 형식 자동 판별), baselinePath — 비교할 이전 SBOM(선택, 형식이 달라도 purl 좌표로 비교)
• offline — true(기본) | false OSV 재조회(생성 이후 새로 알려진 취약점·지금 조회되지 않는 취약점)
• vex — true 면 VEX 초안 작성·갱신(vexPath, 기본 sbom/vex.cdx.json, CycloneDX 입력만), dryRun — vex 미리보기
• SBOM 파일은 바꾸지 않습니다. VEX 는 새 파일로 만들고, 다음 실행은 기존 판단을 그대로 두고 새 항목만 덧붙입니다(깨진 VEX 는 덮어쓰지 않고 중단)

SBOM 제출 준비

2027년까지 공공 분야에 도입되는 IT 시스템·SW 제품의 SBOM 제출이 제도화됩니다(SW 공급망 보안 로드맵, 2026-06). 제출물에는 "만들었다"보다 빠진 요소가 없고, 이전 제출본과 무엇이 달라졌으며, 알려진 취약점을 어떻게 판단했는지가 함께 있어야 합니다.

generate_egovframe_sbom(projectDir, dryRun=false, offline=false, supplier="○○기관", author="○○정보기술")   # 1. 생성(최소 요소 포함)
check_egovframe_sbom(projectDir)                                     # 2. 최소 요소 7종 — 제출 가능/보완 필요
check_egovframe_sbom(projectDir, offline=false, vex=true)            # 3. 새 취약점 확인 + VEX 초안(in_triage)
#    → 담당자가 sbom/vex.cdx.json 의 analysis.state 를 not_affected(+justification)·exploitable·resolved 등으로 기록
check_egovframe_sbom(projectDir, baselinePath="sbom/bom-2026Q3.cdx.json", offline=false, vex=true)   # 4. 다음 제출 전: 비교 + 새 취약점만 VEX 에 추가

최소 요소	CycloneDX 위치	SPDX 2.3 위치 (v0.43)	비고
공급자	component supplier·publisher·manufacturer (주 component 는 metadata.supplier 도)	PackageSupplier(없으면 PackageOriginator)	플러그인은 pom <organization> 이 있는 라이브러리만 publisher 를 채움 — 공식 web 템플릿 67종 중 17종(RTE 등)이 비어 공급자 표로 보완
구성요소명 · 버전	name · version	PackageName · PackageVersion(versionInfo)
고유식별자	purl(또는 cpe·swid)	externalRefs 의 purl(또는 cpe23Type·cpe22Type·swid)
의존관계	dependencies[] 에 그 component 의 bom-ref 항목	그 패키지가 주어인 DEPENDS_ON(또는 *_DEPENDENCY_OF 의 대상)	의존이 없어도 빈 dependsOn / DEPENDS_ON NONE 이 있어야 함(NOASSERTION 은 모름)
작성자	metadata.authors(또는 metadata.manufacturer)	creationInfo.creators 의 Person:·Organization:	생성 도구(metadata.tools / Tool:)만으로는 작성 주체가 드러나지 않음
생성 시각	metadata.timestamp	creationInfo.created	ISO 8601 — SPDX 는 필수 항목이라 원본에 없으면 변환 시각을 넣고 알림

규칙은 catalog/sbom-rules.json 데이터입니다(출처: NTIA 최소 요소 2021, SW 공급망 보안 가이드라인 1.0) — 국내 지침이 요소를 더하면 데이터로 추가합니다. CI 에서는 npx -y egovframe-scaffold-mcp sbom-check --offline=false --fail-on "minimum,newVulns" 로 제출 전 점검을 게이트로 걸 수 있습니다.

제출처가 SPDX 를 요구하면(가이드라인 1.0 은 SPDX·CycloneDX 를 모두 언급) bomFormat="spdx-json" 으로 같은 내용을 SPDX 2.3 JSON 으로 냅니다. 체크섬·선언 라이선스(이름만 있는 라이선스는 LicenseRef- + hasExtractedLicensingInfos)·OSV 권고(SECURITY/advisory externalRefs)·기준 판정(egovframe:* annotations)도 옮기므로, SPDX 로 낸 뒤 check_egovframe_sbom(sbomPath="sbom/bom.spdx.json") 의 재판정·비교가 CycloneDX 와 같은 결과를 냅니다. SPDX 3.0, 취약점 판단 자동화(VEX 상태는 사람의 결정), 중앙 저장소 제출 API 는 범위 밖입니다.

generate_egovframe_report 파라미터 (전환 준비도 평가서)

• projectDir — 평가할 프로젝트(허용 root 적용)
• sections — ["components"](기본, v0.16 리포트 그대로) | ["assessment"](평가서) | 둘 다(이어 붙임)
• resolve·resolveScope·resolveTimeoutMs — 평가서의 의존성 절을 빌드 도구로 해석한 전이 의존성까지 판정(기본 선언만)
• offline — true(기본) | false OSV 로 알려진 취약점 조회 — 공급망 등급은 취약점을 조회해야 "확정"으로 표시
• sbomPath — 요약할 SBOM(기본 sbom/bom.cdx.json; 없으면 "없음"으로 표시하고 만들지 않음), topN — 예상 수동 작업 상위 N(기본 20)
• outputPath — 프로젝트 상대 .md 경로. 주면 새 파일로만 저장(기존 파일 거부, ..·절대·symlink 이탈 거부, transaction), dryRun — 쓰지 않고 내용만
• format — markdown(기본) | json(outputSchema·structuredContent, 평가 데이터 포함)

generate_egovframe_report(projectDir="/work/legacy-app", sections=["assessment"])
generate_egovframe_report(projectDir="/work/legacy-app", sections=["assessment"], offline=false, resolve=true, outputPath="docs/assessment.md")

평가서 6절의 등급은 두 축입니다. 전환 난이도 = 수동 전환 항목 수(0 / 1–20 / 21–100 / 101+ → 0–3점) + 재조립 권고 공통컴포넌트 수(0 / 1–5 / 6–20 / 21+) + 제거된 API 참조 수(0 / 1–10 / 11–100 / 101+) + 현재 좌표 세대(5.x 0 · 4.x 1 · 3.x 2), 공급망 상태 = 기준 미만 의존성 수(0 / 1–3 / 4–10 / 11+) + 전환 대상·교체 필요 수(같은 구간) + 알려진 취약점이 있는 의존성 수(0 / 1–2 / 3–9 / 10+, 미조회면 0점으로 계산하고 주의) + 보안 설정 누락 수(0 / 1–2 / 3+ → 0–2점) + 5.x parent·Java 기준(각 미달 +1). 합계로 A=0 · B≤3 · C≤7 · D>7. 산식 전문은 리포트 안에 인쇄되며, 공식 5.x 템플릿은 전환 A, 공식 공통컴포넌트 3.10.0·4.3.2 전체 트리는 두 축 모두 D 입니다(구간을 정한 근거와 예시: docs/design-assessment-report.md). 비용·공수는 산정하지 않습니다.

평가서 발췌(공통컴포넌트 v4.3.2 전체 트리):

- **전환 난이도 D · 공급망 상태 D** (산식은 6절)
## 2. 전환 범위
- 항목 1352건 = 자동 치환 635 + 수동 717 · 대상 파일 689개
- 재조립 권고 공통컴포넌트 155종: cmm, cop.adb, bbs, …
- 제거된 API 참조 552건 (제거된 RTE 클래스 · 제거된 공통컴포넌트 클래스 · 제거된 RTE 모듈 · 제거된 XML 네임스페이스)
## 6. 등급과 근거
### 전환 난이도: **D** (10/11점, A=0 · B≤3 · C≤7 · D>7)
| 요인 | 값 | 구간 | 점수 | 비고 |
| 수동 전환 항목 수 | 717 | 101+ | 3 |  |
| 재조립 권고 공통컴포넌트 수 | 155 | 21+ | 3 |  |
| 제거된 API 참조 수 | 552 | 101+ | 3 |  |
| 현재 좌표 세대 | 1 | 1 | 1 | sourceEra=4.x |

reassemble_egovframe_components 파라미터 (공통컴포넌트 재조립)

• projectDir — 대상 프로젝트(허용 root 적용)
• components — 재조립할 컴포넌트 id(그룹 id 는 하위로 펼침). 미지정 시 diagnose_egovframe_project 가 감지한 컴포넌트 전부
• sourceTag — 원본 태그(기본 auto: 프로젝트 파일의 git blob id 를 좌표 세대에 맞는 공식 태그와 대조해 일치가 가장 많은 태그), 예: v3.10.0
• database — 지정 시 컴포넌트별 DDL·DML 을 scripts/egovframe-components/<db>/ 에 함께 생성
• dryRun — true(기본) 분류·계획만(파일 내용을 내려받지 않음) | false 적용, verify — 적용 뒤 compile 해 오류를 작업 목록 파일에 붙임
• format — markdown(기본) | json(outputSchema)

파일마다 판정은 목표와 같음(유지)·원본 그대로(교체)·사용자 수정(소스는 교체 + 원본 대비 패치 보존, 메시지·설정 조각·웹 자산은 사용자본 유지 + 목표본 참고 저장)·5.x 신규(추가)·5.x 에서 제거(백업 후 삭제, 사용자 수정이면 패치도)·원본 미확인(백업 후 교체)·사용자 추가(유지)입니다. 백업·패치·reassemble-plan.json 은 migration-backup/<시각>-reassemble-*/ 에, 매니페스트는 .egovframe-components.json 에 남습니다. 원본 태그 비교에는 git 이 필요하고, blob 없는 bare 미러를 EGOVFRAME_CACHE_DIR(기본 ~/.cache/egovframe-scaffold-mcp)에 태그당 수백 KB 로 캐시합니다. 사용자 패치를 자동으로 다시 적용하지는 않습니다(5.x 소스가 많이 바뀌어 fuzz 적용이 오히려 위험).

rehearse_egovframe_migration 파라미터 (전환 리허설)

• projectDir — 대상 프로젝트(읽기만 함, 허용 root 적용)
• steps — 기본 ["reassemble","migrate","verify","align-pom"](순서 고정, 일부만 고를 수 있음)
• components·sourceTag — 재조립 단계에 그대로 전달
• keepWorkspace — true 면 사본(EGOVFRAME_CACHE_DIR/rehearsal/<이름>-*)을 남기고 경로를 돌려줌(기본: 끝나면 삭제), timeoutMs — 컴파일 1회(기본 900000), topN — 작업 목록 수

사본은 빌드 산출물·VCS·백업 디렉터리를 빼고 만듭니다. 재조립을 전환 적용보다 먼저 하는 이유는 적용이 컴포넌트 소스를 바꾸면 원본 태그 지문이 깨지기 때문입니다(공식 4.3.2 트리를 거꾸로 돌리면 v5.0.1 로 오인되고 1,489개 파일이 "사용자 수정"이 됩니다). Maven 은 -Dmaven.compiler.fork=true 와 JDK_JAVAC_OPTIONS=-Xmaxerrs 100000 으로 javac 의 오류 100개 상한 없이 셉니다. pom 맞춤은 사본에만 적용하고 패치로 돌려주므로, 검토해서 실제 pom 에 반영하면 됩니다. 실측(공식 공통컴포넌트 v4.3.2 전체): 자동 단계 후 6,003건(JDK 17)·6,335건(JDK 21) → pom 맞춤 후 1건. javac 판본마다 같은 원인을 다른 모양으로 보고하므로(JDK 17 은 없는 패키지의 import 대신 쓰는 곳마다 "cannot find symbol") 분석은 파일의 import 문·타입 선언 파일·Lombok 사용 여부로 원인을 묶습니다. pom 에 소스 인코딩이 없으면 UTF-8 로 컴파일합니다(JDK 18+ 기본값).

3.x/4.x 프로젝트 전환 흐름:

generate_egovframe_report(projectDir, sections=["assessment"])        # 평가서: 재조립 권고·수동 항목·등급
rehearse_egovframe_migration(projectDir)                               # 사본에서 전 과정 실측: 남는 컴파일 오류·pom 변경안(원본 불변)
reassemble_egovframe_components(projectDir)                            # 미리보기: 원본 태그·파일별 판정
reassemble_egovframe_components(projectDir, dryRun=false)              # 공통컴포넌트 v5.0.7 재조립 + 패치·작업 목록
migrate_egovframe_project(projectDir, apply=true, dryRun=false)        # 나머지 좌표·패키지·Jakarta 자동 치환
migrate_egovframe_project(projectDir, verify=true)                     # compile 오류 ↔ 수동 항목 작업 목록

diagnose_egovframe_network / generate_agents_md

diagnose_egovframe_network()                       # 호스트 7종 전부, 호스트당 10초
diagnose_egovframe_network(hosts=["codeload.github.com"], timeoutMs=20000)
generate_agents_md(projectDir="/work/my-egov-app", dryRun=true)   # 내용만
generate_agents_md(projectDir="/work/my-egov-app", lang="en", fileName="CLAUDE.md", overwrite=true)

네트워크 진단은 프록시 URL 의 자격 증명을 가려서 보고하며, NODE_TLS_REJECT_UNAUTHORIZED=0 이 설정돼 있으면 경고합니다. 다운로드가 실패하는 다른 도구들도 오류 메시지 끝에 같은 분류와 한 줄 처방을 붙입니다([네트워크 timeout] … 자세한 진단: diagnose_egovframe_network). AGENTS.md 의 사실 항목은 diagnose_egovframe_project·migrate_egovframe_project·빌드 도구 감지에서 오고, 규칙 항목은 이 서버의 도구가 지키는 원칙입니다.

sync_egovframe_catalog / 컴포넌트 조립

• 카탈로그는 common-components 공식 v5.0.7 태그와 commit 7912e13c…에 고정됩니다(v0.38 에서 v5.0.6 → v5.0.7, v0.39 에서 upstream 이 태그를 옮겨 3756ab2c… → 7912e13c… 로 재고정).
• sync_egovframe_catalog()는 태그 이동, archive SHA-256·크기·파일 수 불일치, sec.security 누락, 미매핑 Java·Mapper·JSP를 검사합니다.
• add_egovframe_components는 기존 파일이 upstream과 동일하면 재사용하고 내용이 다르면 전체 조립을 거부합니다.
• 감지된 mavenDependencies는 결과에 반환합니다. 프로젝트별 dependency management·버전 정책을 보호하기 위해 기존 pom.xml과 web.xml은 자동 덮어쓰지 않습니다.

상세 스키마와 안전 게이트는 카탈로그 동기화·완전 조립 설계를 참고하세요.

설치·사용

npm에 배포되어 설치 없이 바로 실행할 수 있습니다:

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "npx",
      "args": ["-y", "egovframe-scaffold-mcp"]
    }
  }
}

영문 도구 설명이 필요하면(응답은 한국어 그대로) env 에 "EGOVFRAME_LANG": "en" 을 추가합니다. 사내 프록시 환경에서 프로젝트 생성이 타임아웃되면 "HTTPS_PROXY": "http://proxy:8080", "NODE_USE_ENV_PROXY": "1" 을 같은 env 에 넣고, 원인 확인은 diagnose_egovframe_network 로 합니다.

소스에서 직접 빌드하려면:

npm install
npm run build

Claude Desktop / Claude Code 설정 예 (mcpServers):

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "node",
      "args": ["/절대경로/egovframe-scaffold-mcp/dist/index.js"]
    }
  }
}

빌드 없이 실행하려면 (로컬 클론 후):

{
  "mcpServers": {
    "egovframe-scaffold": {
      "command": "npx",
      "args": ["-y", "tsx", "/절대경로/egovframe-scaffold-mcp/src/index.ts"]
    }
  }
}

사용 예 (AI 도구에서):

"표준프레임워크로 my-egov-app 프로젝트를 ~/work에 만들어줘. groupId는 egovframework.example, DB는 mysql."

CI 에서 쓰기 (CLI 모드)

AI 클라이언트가 없는 빌드 서버에서는 같은 패키지를 명령으로 실행합니다. 인자가 없으면 MCP 서버, 명령이 있으면 그 도구를 한 번 실행하고 종료합니다.

npx -y egovframe-scaffold-mcp assess --project . --offline=false --out assessment.md --fail-on supplyChain:C
npx -y egovframe-scaffold-mcp check --project . --resolve --json --fail-on "vulnerabilities,outdated>10"
npx -y egovframe-scaffold-mcp sbom --project . --write --offline=false
npx -y egovframe-scaffold-mcp sbom-check --project . --offline=false --fail-on "minimum,newVulns"
npx -y egovframe-scaffold-mcp migrate --project . --fail-on manual
npx -y egovframe-scaffold-mcp rehearse --project . --fail-on "errors>50"

명령	도구	비고
assess	generate_egovframe_report(sections=["assessment"])	등급 지표 migration·supplyChain(예: supplyChain:C = C 이상이면 실패)
check	check_egovframe_dependencies	outdated·legacy·replace·unknown·vulnerabilities·securityMissing
sbom	generate_egovframe_sbom	--write 가 있어야 파일을 씀(기본 계획만), --bom-format spdx-json 이면 SPDX 2.3
bundle	prepare_egovframe_offline_bundle	인터넷 PC 용, --output-dir 필수, --write 가 있어야 받음(기본 목록만)
rehearse	rehearse_egovframe_migration	사본에서 실측(원본 불변), 지표 errors(최종)·automation·aligned·files·unlinked·failedSteps
sbom-check	check_egovframe_sbom	CycloneDX·SPDX 자동 판별, minimum(보완 필요면 1)·gaps·newVulns·changed·비교 added·removed·versionChanged·diffVulns·VEX triage, --write 면 VEX 작성·갱신
migrate	migrate_egovframe_project	진단만(--apply 차단), manual·auto·items
validate · diagnose · network	같은 이름의 도구	invalid·missing · issues · failed

옵션은 도구 파라미터와 같은 이름(kebab-case 가능)이고, 공통 옵션은 --project·--json(MCP structuredContent 와 같은 객체)·--out·--step-summary(Markdown 을 $GITHUB_STEP_SUMMARY 에)·--fail-on 입니다. 종료 코드는 0 통과 · 2 --fail-on 기준 초과 · 3 실행 실패 · 64 사용법 오류, 본문은 stdout·한 줄 요약은 stderr 입니다. 쓰기 도구(생성·조립·적용·재조립)는 CLI 에 노출하지 않습니다.

CI 설정 생성: GitHub Actions · GitLab CI · Jenkins

generate_egovframe_ci(projectDir, platform, supplyChain=true) 가 세 플랫폼에 같은 빌드와 같은 게이트를 만듭니다. 게이트는 SBOM 생성(sbom --write --offline=false) → 최소 요소 7종 점검(sbom-check --fail-on minimum, v0.43) → 전환 준비도 평가서(assess --fail-on <failOn>) 순서이고, CLI 의 종료 코드 2(기준 초과)·3(실행 실패)는 job 실패입니다. 보고서(egovframe-assessment.md·egovframe-sbom-check.md)와 sbom/bom.cdx.json 은 실패해도 보관하며, 패키지 버전은 생성 시점의 서버 버전으로 고정됩니다.

platform	파일	빌드	게이트
github(기본)	.github/workflows/egovframe-ci.yml	mvn -B verify · ./gradlew build	별도 job, 등급을 PR 요약(--step-summary)에, upload-artifact
gitlab	.gitlab-ci.yml	maven:3.9-eclipse-temurin-<JDK>(Gradle 은 eclipse-temurin:<JDK>) 이미지, 로컬 저장소 캐시, JUnit 리포트	supply-chain job(needs: []), Node 가 없으면 apt 로 설치 시도, artifacts:reports:cyclonedx
jenkins	Jenkinsfile(Declarative)	stage('Build') — Linux sh·Windows bat 공용	SBOM → SBOM check → Assessment 단계, post { always { archiveArtifacts } }

generate_egovframe_ci(projectDir="/work/my-egov-app", platform="gitlab", supplyChain=true, supplier="○○기관")
generate_egovframe_ci(projectDir="/work/my-egov-app", platform="jenkins", supplyChain=true, failOn="supplyChain:C",
                      npmRegistry="https://nexus.example.go.kr/repository/npm-group/", offlineBundle="/opt/egov-bundle")

• npmRegistry 는 NPM_CONFIG_REGISTRY(npx 가 이 서버를 받는 사내 레지스트리), offlineBundle 은 EGOVFRAME_OFFLINE_BUNDLE(러너·에이전트에서 본 번들 경로)로 들어갑니다. 값은 따옴표·$·줄바꿈 없는 URL·절대 경로만 허용합니다(설정 파일 주입 차단).
• 공급자 단서가 없으면(supplier 미지정, pom <organization><name> 없음) SBOM 의 주 component 공급자·작성자가 비어 sbom-check 단계가 실패하므로, 생성 응답이 이를 미리 알립니다.
• GitLab 이미지는 공개 Docker Hub 기준입니다. 폐쇄망에서는 사내 레지스트리의 같은 이미지(JDK + Node.js 18 이상)로 바꾸세요. Jenkins 는 Pipeline 기본 단계(sh·bat·archiveArtifacts)만 쓰며 에이전트에 JDK·Maven·Node.js 가 있어야 합니다.
• 생성 .gitlab-ci.yml 은 테스트에서 GitLab 공식 CI 스키마로 검증하고, Jenkinsfile 은 Declarative 구조를 단언합니다(실제 Jenkins 실행 검증은 보류). 설계: docs/design-cli.md.

폐쇄망에서 쓰기 (오프라인 번들)

공공 개발 환경은 대부분 망분리라 인터넷 PC 에서 받은 자료를 반입해 씁니다. 이 서버가 실행 중에 인터넷을 쓰는 곳(공통컴포넌트 아카이브·Initializr zip 템플릿 다운로드, OSV 취약점 조회, 재조립 원본 태그 조회)을 번들 하나로 대신합니다.

# 1) 인터넷 PC — 번들 만들기(≈110MB: OSV 10 · 아카이브 45 · web 템플릿 15 · 태그 미러 37, 템플릿 12종 전부면 ≈150MB)
npx -y egovframe-scaffold-mcp bundle --output-dir ./egov-bundle --write
npx -y egovframe-scaffold-mcp bundle --output-dir ./egov-bundle --templates web,boot-web --write   # 템플릿 골라 담기

# 2) 폐쇄망 PC — 옮긴 디렉터리를 지정(MCP 클라이언트 설정의 env 에도 같은 값)
export EGOVFRAME_OFFLINE_BUNDLE=/opt/egov-bundle        # cmd: setx EGOVFRAME_OFFLINE_BUNDLE D:\egov-bundle

번들 항목	대신하는 것	검증
osv/Maven-all.zip (OSV Maven 전체 덤프)	offline=false 의 OSV 조회(check_egovframe_dependencies·generate_egovframe_sbom·check_egovframe_sbom·평가서)	결과에 "스냅숏 YYYY-MM-DD 기준" 표시, 30일(EGOVFRAME_BUNDLE_MAX_AGE_DAYS) 넘으면 경고
archives/…-7912e13ca5a0.zip (공통컴포넌트 v5.0.7)	add_egovframe_components·재조립·업그레이드의 아카이브 다운로드	카탈로그 고정 sha256·크기·파일 수
templates/<id>.zip (Initializr zip 템플릿)	create_egovframe_project 의 zip 템플릿	템플릿 고정 sha256·크기
origin/…git (공식 태그 22개, 내용 포함)	재조립·리허설의 원본 태그 식별·패치	원격 조회 없이 로컬 미러만

번들 파일은 쓸 때마다 manifest 의 sha256·크기와 대조하고 다르면 거부합니다. 번들에 없는 URL 은 평소처럼 네트워크로 가므로, 저장소 템플릿(simple-backend 등)이 필요하면 --templates 로 지정해 함께 담으세요. Maven 의존성 jar 는 번들에 넣지 않습니다 — 기관 Nexus·Artifactory 미러를 settings.xml 에 지정하세요. upstream 대조 도구(sync_egovframe_*)와 가이드 문서 조회는 인터넷이 필요합니다. 설계: docs/design-offline-bundle.md.

리소스·프롬프트 (MCP Resources/Prompts)

도구(tools)뿐 아니라 MCP의 리소스·프롬프트도 제공합니다 (MCP 3대 프리미티브 완비).

Resources (읽기 전용) — 지원 클라이언트에서 도구 호출 없이 카탈로그를 탐색·인용:

모든 도구는 MCP annotations(readOnlyHint·destructiveHint·idempotentHint·openWorldHint)와 ko/en title 을 노출합니다 — 읽기 전용 14종(목록·검색·진단·검증·리포트·점검·upstream 대조), 파괴 가능 4종(remove_egovframe_components·upgrade_egovframe_project·migrate_egovframe_project(apply)·generate_agents_md(overwrite)), 네트워크 사용 도구는 openWorldHint. diagnose_egovframe_project·validate_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network 는 outputSchema 를 선언하고 structuredContent 로 같은 결과를 구조화해 돌려줍니다(text 는 그대로).

• egovframe://catalog/components · egovframe://catalog/components/{id} · egovframe://catalog/templates · egovframe://catalog/recipes · egovframe://catalog/ai-components · egovframe://catalog/config-templates · egovframe://catalog/migration-rules · egovframe://catalog/dependency-baseline

Prompts — 가이드형 워크플로: scaffold_board_login, scaffold_ai_chatbot, scaffold_portal, maintain_existing

레시피 — 자주 쓰는 조합을 한 번에 조립합니다. 예: apply_egovframe_recipe(recipeId="board-login", projectName="my-egov-app", outputDir="~/work"). 목록은 catalog/recipes.json에서 관리하며 기여 환영합니다.

MCP Registry

MCP Registry 용 메타데이터는 저장소의 server.json(이름 io.github.EricSeokgon/egovframe-scaffold-mcp)과 package.json 의 mcpName 이며, npm run test:registry 가 두 파일의 이름·버전·npm 좌표 일치를 검사합니다. 등록은 npm 배포 뒤 저장소 루트에서:

mcp-publisher login github     # GitHub device flow — io.github.EricSeokgon/ 네임스페이스 권한
mcp-publisher publish          # server.json 을 레지스트리에 게시
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.EricSeokgon/egovframe-scaffold-mcp"

버전을 올릴 때 server.json 의 version·packages[0].version 도 함께 올립니다(릴리스 절차 참조).

보안 설정 — 허용 root (선택)

환경변수 EGOVFRAME_ALLOWED_ROOTS를 설정하면, 모든 도구의 디렉터리 인자(outputDir·projectDir)가 지정한 root 내부일 때만 실행됩니다. 미설정 시 기존과 동일하게 제한이 없습니다.

// MCP 클라이언트 설정 예 (여러 root는 OS 경로 구분자로 연결: POSIX ":", Windows ";")
{ "mcpServers": { "egovframe-scaffold": {
    "command": "npx", "args": ["-y", "egovframe-scaffold-mcp"],
    "env": { "EGOVFRAME_ALLOWED_ROOTS": "/home/user/workspaces" }
} } }

• 검사는 realpath 기준이라 symlink를 통한 우회도 차단합니다.
• 위반 시 도구는 아무 파일도 만들지 않고 AllowedRootsError(허용 root 목록 포함)로 거부합니다.
• transaction 실패 메시지에는 사람용 문구와 함께 기계가 읽을 수 있는 rollback-report: {...} JSON 한 줄(복원·제거·정리 건수, 실패 목록)이 포함됩니다.

검증

• 함수 레벨: 실제 템플릿(약 296파일) 생성, pom 좌표·DbType 적용, 중복 생성 거부, dryRun 미리보기(무기록) 확인 (npm run smoke)
• Maven 좌표 레벨: 프로젝트 직접 groupId/artifactId/name만 변경하고 parent·dependency artifactId 보존 (npm run test:pom, 네트워크 불필요)
• 카탈로그 레벨: schema v2, 고정 source/archive 지문, 자산 메타데이터, 무결성·위상 정렬·미리보기 검증 (npm run test:catalog, npm run test:catalog-sync, 네트워크 불필요)
• zip 조달 레벨: 자리표시자 치환·globals 경로 판별·12종 정의 유효성(npm run test:pom, 네트워크 불필요), batch-file-commandline 실생성으로 지문 검증·좌표·DbType·zip 루트 보존, 지문 불일치 거부와 무기록, ref 지정 시 검증 생략 표시(npm run test:templates, 네트워크 필요, CI 실행)
• 설정 생성 레벨: 동봉 템플릿 지문·카탈로그 무결성, 49건 전 형식 기본값 렌더링, 분기·필드 덮어쓰기, 필드·선택지·파일명·패키지 거부, dryRun 무기록, 충돌 거부, 비밀번호 가림, ..·절대경로·symlink 이탈 거부, CRLF 체크아웃 시뮬레이션 (npm run test:config, 506단언, 네트워크 불필요)
• 템플릿 카탈로그 레벨: catalog/templates.json 스키마·커버리지 계산·큐레이션 매핑 정합·변환기·upstream 차이 계산(추가/삭제/필드 변경) 검증 (npm run test:template-catalog, 256단언, zip 지문·동봉 설정 템플릿 drift·LFS 포인터 해석 포함, 네트워크 불필요)
• 동기화 레벨: 공식 v5.0.7 태그→commit, SHA-256·크기·파일 수, sec.security, 미매핑 경로 0건 검증 (npm run test:catalog-sync-live, 네트워크 필요)
• 조립 레벨: 실제 공통컴포넌트 저장소로 bbs+login+sec.security(+cmm) 843파일 조립, message·IDGN·웹 자산·공용 fragment·Maven 좌표·선별 DB 스크립트·충돌 전체 거부·파일/SQL/매니페스트 fault-injection rollback·상위 symlink 경계 검증 (npm run test:components)
• 수명주기 레벨: 설치 매니페스트 기록, 중복 설치 거부, 의존 컴포넌트 제거 보호, 제거·검증 동작 (npm run test:components)
• 프로토콜 레벨: 빌드된 서버를 실제 프로세스로 띄워 MCP initialize / tools/list 핸드셰이크, serverInfo.version↔package.json 일치, 핵심 도구 노출, jdk 패턴 제약 노출 확인 (npm run test:handshake, 네트워크 불필요)
• 릴리스 레벨: 배포 판정(버전·server.json·변경 이력·태그·npm 네 조건)과 릴리스 노트 추출, npm pack --dry-run 의 tarball 내용(포함·제외·크기 상한), server.json 설명 100자 제한 (npm run test:release·npm run test:registry, 네트워크 불필요); CI 통합이 mcp-publisher validate 로 레지스트리 스키마를 실제 검증
• 플랫폼 레벨: CI가 릴리스 게이트를 ubuntu·windows × Node 18·20·22 매트릭스로 실행하고, 공식 저장소를 내려받는 통합 테스트는 ubuntu/Node 20에서 실행합니다. 타임아웃 시 프로세스 트리 종료는 POSIX·Windows 모두 실제 프로세스로 검증합니다 (npm run test:build).
• 레시피 레벨: catalog/recipes.json의 컴포넌트 id·의존성·템플릿 제공 컴포넌트 정합 검증 (npm run test:recipes, 네트워크 불필요). 공식 simple-backend의 기존 cmm을 보존하고 board-login의 bbs 88파일·login 41파일·SQL 4건(총 133파일)을 조립한 뒤 검증하며, 컴포넌트 이후 fault injection의 전체 staging rollback도 확인 (npm run test:recipe-transaction)
• 진단 레벨: 픽스처(pom·DbType·컴포넌트 패키지)로 diagnose_egovframe_project의 빌드·버전·DbType·컴포넌트 지문·의존성 검출 검증 (npm run test:diagnose, 네트워크 불필요)
• 전환 진단 레벨: 3.10 스타일 픽스처(pom·gradle·java·Spring XML·MyBatis XML·web.xml·JSP)에서 항목 종류·auto/manual·라인·대응 좌표를 단언하고, 5.x 스타일 픽스처에서 항목 0건과 진단 전후 디스크 불변을 확인 (npm run test:migrate, 87단언, 네트워크 불필요). 규칙 카탈로그는 스키마·좌표 규칙성·제거 클래스의 대체가 동봉된 5.x 소스 트리에 존재하는지·JDK 내장 javax.* 제외·큐레이션과 생성물 일치를 검증 (npm run test:migration-rules, 579단언, 네트워크 불필요). 목적지 좌표(RTE 5.x 24종·3.x 원본 18종·parent 2종·Jakarta 좌표)가 표준프레임워크 Maven 저장소와 Maven Central 에 실제로 존재하는지는 CI 통합 job 에서 확인 (npm run test:migration-rules-live, 61건, 네트워크 필요)
• 전환 검증 레벨: 공통컴포넌트 대응표 판정(제거·이동·사용자 클래스 무시), 재조립 권고와 skipComponents, linkBuildError 8케이스(심볼·패키지 부재·라인 근접·규칙 심볼·javax 부재·무관), javac symbol:/location: 파싱(maven·gradle), 가짜 runner 로 verify 결과·작업 목록·Markdown·빌드 파일 없음 (npm run test:migrate 에 포함, 총 162단언). 실제 mvn compile 오류 3건이 수동 항목 2건에 전부 연결되는지는 CI 통합 job (npm run test:migrate-integration)
• 전환 적용 레벨: 3.10 픽스처에 대해 auto 항목의 편집 원문 일치, dryRun 무기록, fault-injection 롤백(내용·mtime 불변), 적용 후 pom·java·XML·web.xml·gradle·JSP 내용, 백업·migration-plan.json, 재적용 무기록, manual 항목 불변을 단언 (npm run test:migrate, 132단언, 네트워크 불필요). 3.10 좌표·javax 픽스처를 적용한 뒤 JDK 17 로 mvn compile 통과는 CI 통합 job 에서 확인 (npm run test:migrate-integration, 네트워크·JDK·Maven 필요)
• 의존성 점검 레벨: 기준 카탈로그 스키마·출처 sha256·RTE 5.x 모듈·BOM 계열, 분류 함수 12케이스, 3.10·5.x parent·gradle·빈 디렉터리 픽스처, OSV 모의 질의·매핑·실패 처리, 디스크 불변 (npm run test:dependencies, 68단언, 네트워크 불필요). 실제 OSV 조회는 CI 통합 job (npm run test:dependencies-live)
• 네트워크 진단 레벨: 오류 분류 8종, 프로브·DNS 주입으로 7가지 시나리오(전부 도달, 405/404/407/503, 프록시+타임아웃, 프록시 없음+IPv6 혼재, TLS, DNS, 필터)의 처방·안내·자격 증명 가림·셸별 명령을 단언하고, fetchWithTimeout 실패 메시지에 처방이 붙는지 확인 (npm run test:network, 33단언, 네트워크 불필요). 실제 호스트 7종 프로브는 CI 통합 job (npm run test:network-live)
• AGENTS.md 레벨: 5.x(매니페스트·래퍼·컴포넌트 2종·백업 디렉터리)와 3.x gradle 픽스처, 빈 디렉터리에서 사실 수집·ko/en 렌더링·dryRun 무기록·기존 파일 거부·overwrite·파일명 검증·staging 정리 (npm run test:agents-md, 22단언, 네트워크 불필요)
• 레지스트리 메타데이터 레벨: server.json ↔ package.json 의 이름(mcpName)·버전·npm 좌표·스키마 URL·환경변수 문서화 정합 (npm run test:registry, 네트워크 불필요)
• 프로토콜 레벨(추가): EGOVFRAME_LANG=en 으로 띄운 서버의 도구 32종 설명이 모두 영문이고 표에 빠진 도구가 없는지, tools/list 에 title·annotations(readOnly 13종·destructive 5종)·outputSchema 11종이 노출되는지 확인 (npm run test:handshake)
• SBOM·해석 레벨: Maven·Gradle 트리 파서(실제 출력 픽스처), resolve=true 의 전이 항목·경로·선언/해석 차이·실패 경로, CycloneDX 문서 구성·보강·취약점 병합·출력 경로 거부·overwrite·dryRun (npm run test:dependencies, npm run test:sbom, 네트워크 불필요); CI 통합이 공식 egovframe-web 템플릿을 실제 Maven 으로 해석하고 SBOM 을 생성 (npm run test:sbom-live)
• 오프라인 번들 레벨: Maven 버전 비교(숫자·한정자 순서·같은 표기), OSV 범위(여러 구간·fixed·last_affected), 덤프 색인(Maven 만·철회 제외·GIT 범위 무시)과 querybatch 같은 모양의 결과, 번들 만들기(dryRun·manifest 지문·고정 지문 불일치 거부·실패 시 무흔적·덮어쓰기 거부·로컬 git 원본 미러), 번들 읽기(fetch 훅·POST 제외·변조 거부·깨진 manifest), 원본 미러(태그·커밋·트리·blob, 없는 태그 안내), OSV 출처 노트와 30일 경고, 의존성 점검 연동, 네트워크 진단 처방 (npm run test:offline-bundle, 30단언, 네트워크 불필요); CI 통합이 실제 번들을 만들고 로컬 OSV 와 온라인 OSV 를 대조(97% 이상 일치 요구, 실측 100%)한 뒤 fetch 를 막고 생성·조립·재조립 미리보기·SBOM 재점검을 번들만으로 확인 (npm run test:bundle-live)
• 전환 리허설 레벨: pom 맞춤(parent 추가·교체, 누락 좌표, 버전·scope, parent 관리 속성, 주석·dependencyManagement·plugin 제외, 멱등), 누락 패키지·연쇄·수동 항목 분류와 후보 좌표, Maven fork 형식·경고 제외 파서, 사본 제외 규칙·원본 지문 불변, 단계 순서(재조립 → 적용 → 컴파일 → pom 맞춤 → 컴파일)·javac 상한 해제 인자, 단계 실패 계속, 기록과 평가서 6절 (npm run test:rehearse, 38단언, 네트워크 불필요); CI 통합이 공식 공통컴포넌트 v4.3.2 전체 트리를 실제로 리허설해 재조립·적용 수와 오류 6,003(±10%, 누락 패키지·연쇄 95% 이상)→≤5 를 단언 (npm run test:rehearse-live)
• SPDX 레벨: 실제 플러그인 출력 고정물을 SPDX 2.3 으로 바꿔 공식 spdx-spec v2.3 스키마 통과, 패키지 68·DEPENDS_ON 간선 수 = CycloneDX 의존 간선·의존 없음 NONE·체크섬·라이선스(LicenseRef)·DESCRIBES, 되읽었을 때 최소 요소 요소별 충족 수·purl·의존 간선·기준 판정(annotations)·취약점(advisory) 보존, 다른 도구 모양 SPDX(DEPENDENCY_OF·NOASSERTION·여러 DESCRIBES·Person/Organization/Tool)의 필드 대응, bomFormat="spdx-json" 생성·SPDX 입력 점검(형식 판별·CycloneDX 와 같은 판정·SPDX↔CycloneDX 비교 차이 0·VEX 거부)·outputSchema (npm run test:spdx, 43단언, 네트워크 불필요). 실제 Maven SBOM 의 SPDX 판정 일치는 CI 통합 test:sbom-live 가 확인
• SBOM 운영 레벨: 실제 플러그인 출력 고정물(공식 web 템플릿 67 component)로 최소 요소 7종(빠진 항목별)·공급자 표 보완·purl 재판정·가짜 OSV(새/사라진 ID)·비교(추가·제거·버전·판정·취약점)·VEX 생성/판단 보존/같은 ID 의 새 영향 component·깨진 VEX 중단을 단언하고, 생성 SBOM·VEX 를 CycloneDX 1.6 공식 JSON 스키마(specification 1.6.1)로 검증 (npm run test:sbom-check, 54단언, 네트워크 불필요); CI 통합이 실제 SBOM 으로 보완 필요(주 component 공급자·작성자) → supplier·author 로 보완(환경에 따른 다른 공백은 info: 로그), 두 SBOM 비교 차이 0, 실제 OSV VEX 초안·판단 보존을 확인 (npm run test:sbom-live)
• 메타데이터·구조화 출력 레벨: TOOL_META ↔ 등록 도구 일치, 읽기 전용·파괴·네트워크 힌트 배정, 영문 title, 7종 도구의 실제 결과(진단·검증·전환 진단/적용·의존성·네트워크·리포트, 빈 프로젝트 포함)가 outputSchema 를 통과하고 최상위 키가 전부 선언돼 있으며 잘못된 값은 거부 (npm run test:output-schemas, 47단언, 네트워크 불필요). MCP 프로토콜 경유 호출 시 SDK 가 structuredContent 를 스키마로 검증합니다
• 테스트 이식성 레벨: scripts/check-test-portability.mjs 가 test/*.mjs 에서 Windows 에서 깨지는 가정(정규화 없는 path.relative 비교, ./mvnw 리터럴 기대값, POSIX 절대 경로)을 찾아 실패시킵니다(npm run check:portability, 게이트 포함, 의도된 줄은 // portability: ok <사유>). 플랫폼 분기 함수(resolveCommand·collectAgentsFacts)는 platform 주입으로 linux·win32 양쪽을 단언합니다
• 문서 검색 레벨: search_egovframe_docs의 키워드 매칭·점수 정렬·컴포넌트 매핑·빈질의/미존재어 처리 검증 (npm run test:docs, 네트워크 불필요)
• 리포트 레벨: 픽스처로 generate_egovframe_report의 컴포넌트·테이블·가이드 링크 렌더링 검증 (npm run test:report, 네트워크 불필요)
• 평가서 레벨: 등급 산식 경계(구간·등급)와 리포트 숫자로의 재계산, 3.x(공통컴포넌트 소스·교체 라이브러리·http 저장소·벤더)·4.x 소형·5.x parent 픽스처의 절별 내용과 등급(5.x 는 전환 범위 0·A), OSV 조회·실패 시 취약점 요인, SBOM 요약·깨진 파일, 절 조립·중복 제거, outputPath 저장·dryRun·기존 파일/프로젝트 밖/절대 경로/symlink/.md 아님 거부, structuredContent 스키마 (npm run test:assessment, 55단언, 네트워크 불필요). CI 통합이 공식 5.x 템플릿 2종에서 전환 A 를 확인 (npm run test:dependencies-live)
• CLI 레벨: 인자 해석(--x·--x=v·--no-x)·스키마 형 변환·모르는 옵션, --fail-on 등급·임계값·오류, 종료 코드 0/2/3/64, 쓰기 옵션 차단, --json = 라이브러리 결과, --out·--step-summary, 실제 프로세스(인자 유무로 서버/CLI) (npm run test:cli, 32단언, 네트워크 불필요). CI 생성 레벨에 공급망 게이트 job·failOn 주입 거부 추가(npm run test:ci), CI 통합에서 생성 워크플로를 actionlint 로 검사하고 4.3.2 코퍼스 트리로 CLI 평가서를 실행해 job 요약에 등급을 남깁니다
• 재조립 레벨: 메모리 원본 저장소로 원본 태그 식별(세대 후보·지정·없는 태그), 8가지 판정(CRLF 체크아웃 포함)·처리, dryRun 무기록, 적용 후 파일·백업·자산 참고본·패치(원문 바이트 보존)·매니페스트·계획 파일, validate 누락 0, 매니페스트 관리 컴포넌트 거부, fault-injection rollback, 목표 내용 blob 불일치 거부, verify 오류 연결 (npm run test:reassemble, 46단언, 네트워크 불필요). CI 통합이 공식 v3.10.0 트리의 cmm·bbs 를 고친 픽스처를 실제 git 원본·sha256 검증 아카이브로 재조립해 v5.0.7 tree 일치·패치·validate·upgrade 변경 0 을 확인 (npm run test:reassemble-live)
• 회귀 코퍼스 레벨: 공식 공통컴포넌트 v3.10.0·v4.3.2 부분 트리(커밋 고정, sparse 클론, 캐시)에 진단·dryRun 적용·의존성 점검·평가서를 돌려 catalog/migration-corpus.json 기대값과 ±1% 안인지, 세대 판정·확인 필요 클래스 0·기준 없음은 xerces 뿐·계획=자동 전부·재조립 권고·등급 D/D·60초 미만을 단언 (npm run test:migrate-corpus, 20단언, git·네트워크 필요, CI 통합). 기대값 갱신은 npm run generate:migration-corpus(--check 는 차이만)
• 업그레이드 레벨: 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 무기록·기존 파일 거부·빌드파일 부재 예외·jdk·failOn·supplier·환경 변수 주입 입력 거부, 세 플랫폼 공통 게이트 명령(sbom → sbom-check → assess), 생성 .gitlab-ci.yml 의 GitLab 공식 CI 스키마(v19.4.1-ee 고정물) 통과, Jenkinsfile 의 Declarative 구조(pipeline·agent·options·stages·post, 괄호 짝, 단계 순서)·Windows 경로 이스케이프, 공급자 단서 없을 때 게이트 실패 예고 (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, 네트워크 불필요).

현재 지원 범위와 알려진 제약

• 공통컴포넌트 실행 자산과 Maven 좌표 탐지는 지원합니다. 기존 pom.xml·web.xml의 구조적 노드 병합은 프로젝트별 dependency management·설정 경로를 보호하기 위해 자동 수행하지 않습니다.
• 카탈로그는 공식 v5.0.7 태그·commit·archive 지문에 고정됩니다. 최신 main 변경은 sync_egovframe_catalog(ref="main") 결과를 검토한 뒤 생성 스크립트로 승격합니다.
• build_egovframe_project·test_egovframe_project는 로컬에 설치된 JDK와 maven/gradle(또는 프로젝트 래퍼)을 사용합니다. DB 등 외부 의존성이 필요한 테스트는 그 환경이 준비되지 않으면 오류(error)로 집계됩니다.
• 자바 패키지 구조 변경(groupId에 맞춘 소스 디렉터리 이동)은 미지원입니다. 현재는 IDE rename refactoring을 권장합니다.
• migrate_egovframe_project 의 적용은 진단이 auto 로 표시한 항목만 치환합니다. 정적 텍스트 스캔이므로 리플렉션·문자열 조립으로 만든 클래스명, 프로젝트 밖 라이브러리 안의 javax 사용, Spring Security 6·Hibernate 6 등 라이브러리 자체의 API 변경으로 인한 코드 수정 범위는 보고하지 않습니다(라이브러리 단위로 manual 안내만 합니다).
• 템플릿·컴포넌트·가이드 원본을 받을 때 GitHub(codeload.github.com, raw.githubusercontent.com, zip 조달 템플릿은 media.githubusercontent.com) 네트워크 접근이 필요합니다.

로드맵

v0.31.0까지 프로젝트·CRUD 생성, 검증된 공통컴포넌트 실행 자산 조립, 안전성 기반(테스트 판정 강제·사용자 파일 보호·전 도구 트랜잭션·허용 root·구조화 rollback 보고), 생성→검증 루프(실제 빌드·오류 구조화·테스트 리포트 구조화), 공식 템플릿 카탈로그 단일화와 커버리지 확대(22종 중 21종), 설정 파일 생성, 5.x 전환(진단·적용), 의존성 점검, 운영 편의(네트워크 진단·AGENTS.md·영문 설명·레지스트리 메타데이터)를 완료했습니다.

v0.32–v0.34 로 MCP 프로토콜 현대화, 5.x 전환 3단계(검증)와 공통컴포넌트 대응표, 의존성 기준 완성과 규칙·기준 drift 감시를, v0.35–v0.37 로 릴리스 자동화, 해석된 의존성 트리와 SBOM, 전환 준비도 평가서와 회귀 코퍼스를, v0.38–v0.40 으로 공통컴포넌트 재조립 실행, CLI 모드와 CI 공급망 게이트, SBOM 운영(최소 요소·비교·VEX)을, v0.41–v0.43 으로 전환 리허설, 폐쇄망 오프라인 번들, GitLab·Jenkins CI 와 SPDX 를 마쳤습니다(기획 원문과 결과: v0.41–v0.43 · v0.38–v0.40 · v0.35–v0.37). Homebrew 탭은 후순위에서 내렸습니다(npx 로 충분).

版本	核心功能	目标
v0.20 完成	generate_egovframe_crud	支持输入官方 wizard.xml 分组和路径，生成 VO、Mapper（XML）、Service、Controller、JSP（可选）；支持 Classic/Boot、JUnit 5、dryRun 和原子拒绝冲突。离线测试通过，官方 simple-backend/Boot·web-sample/Classic Maven compile 通过
v0.21 完成	sync_egovframe_catalog + 组件完整组装	固定 common-components v5.0.6 标签/commit/archive，共 190 项；组装 message·IDGN·scheduling·静态资源·web fragment，检测 Maven 坐标，验证 sec.security·未映射路径，使用清单 v3
v0.22 完成	所有工具的安全基础	所有写入路径采用 transaction，保护用户文件，为所有工具设置允许的 root，阻止 symlink/junction 越界，提供结构化 rollback 报告
v0.23 完成	build_egovframe_project	自动检测 Maven/Gradle·包装器（mvnw/gradlew），设置超时·日志上限，按文件/行结构化错误，完成生成→验证 Agent 循环（PR #18）。test_egovframe_project 于 v0.25 完成
v0.24 完成	扩大官方模板覆盖范围（7 → 10 种）	对照 Initializr 目录（22 项）识别未覆盖的官方资源，新增 msa-common-components（KRDS）·mobile-device-api·ai-rag。均标记为多项目，跳过坐标/DB 自动重写并保护子模块引用；通过实际归档下载集成测试验证
v0.25 完成	test_egovframe_project	执行测试后读取 JUnit XML 报告（surefire target/surefire-reports、gradle build/test-results/test），按套件·用例汇总失败消息·异常类型·测试文件/行，支持 testFilter，排除过期报告；即使 exit 0，若报告显示失败也判定为失败
v0.26 完成	IDE·Initializr·MCP 统一目录	将 Initializr templates-projects.json（22 种）、MCP TEMPLATES（10 种）、Development wizards.xml（8 个类别）整合到采用 schemaVersion: 1 的统一模式 catalog/templates.json 中。借助转换器（fromInitializr·fromMcpTemplates）、整理映射（catalog/template-mapping.json）和上游对照工具 sync_egovframe_templates，无需手动比较即可确认覆盖差距
v0.27 完成	扩大官方模板覆盖范围（10 → 22 种）	从统一目录计算出的 13 种未覆盖模板中，通过获取 Initializr zip（Git LFS）新增 12 种。固定 commit·sha256·大小并验证下载，替换 pom 占位符，根据各模板对应 globals.properties 路径，并由 sync_egovframe_templates 报告 zip 指纹 drift
v0.28 完成	generate_egovframe_config	随附固定 commit·sha256 的 21 种 Initializr 配置模板（Handlebars），支持离线生成。支持 xml·javaConfig·yaml·properties，字段·默认值与 Initializr 表单一致，并验证选项·文件名·包名，拒绝覆盖现有文件；sync_egovframe_templates 报告随附模板 drift
v0.29 完成	migrate_egovframe_project（第 1 阶段：诊断）	按 5.x（Jakarta）标准扫描 3.x/4.x 项目，以只读方式报告 RTE 坐标·包·已移除/移动的类·javax→jakarta·web.xml·XML 命名空间·库迁移项，并区分 auto/manual。规则通过比较 3 个 egovframe-runtime 标签生成（catalog/migration-rules.json），在 CI 中将目标坐标与实际仓库对照
v0.30 完成	migrate_egovframe_project（第 2 阶段：应用）+ check_egovframe_dependencies	通过原文偏移编辑以 transaction 应用诊断中的 auto 项（备份·默认 dryRun·计划文件·失败恢复；应用后通过 JDK 17 mvn compile CI 验证）；将依赖与从官方 5.x parent 提取的基准（139 种受管坐标 + 7 种 BOM 系列）对照，检查是否存在安全配置，并支持可选 OSV 查询
v0.31 完成	运维便利性	diagnose_egovframe_network（探测 7 种主机·分类故障·提供各 Shell 的解决办法，并在下载错误消息中附上解决办法），generate_agents_md（ko/en），英文 README 和 EGOVFRAME_LANG=en 工具说明，MCP Registry server.json·mcpName·一致性测试
v0.32 完成	MCP 协议现代化	切换到 registerTool（已弃用的 tool() 为 0 个），27 种工具添加 ko/en title·annotations（readOnly 14·destructive 4·openWorld），5 种工具添加 outputSchema+structuredContent，添加测试可移植性检查脚本（门禁）和平台注入断言
v0.33 完成	migrate_egovframe_project 第 3 阶段：验证	使用 verify=true，将 compile 错误与手动项关联，生成待办列表（解析 javac symbol/location，分 4 个阶段关联）；提供 common-components 3.x→5.x 对照表（移除 54·移动 4，schemaVersion 2）、重新组装建议和 skipComponents
v0.34 完成	完善依赖基准 + drift 监控	将完整 Spring Boot BOM（1,473 种）·RTE 模块传递依赖（58 种）纳入基准，并标明每项的基准来源；通过 vendor 分类·EOL 坐标替换规则，将 common-components 3.10 pom 中的 unknown 从 17 项降至 1 项；sync_egovframe_templates 报告规则·基准目录的上游 drift（新标签·新 parent·pom sha256）和更新流程
v0.35 完成	发布自动化（发布供应链）	release.yml：main 上 CI 成功 → 检查四项条件 → npm（OIDC trusted publishing、provenance）→ 为该 commit 打标签 → GitHub Release（提取变更记录）→ MCP Registry（OIDC）。test:release（判定·说明·tarball 内容·大小），server.json 说明限制为 100 字，CI 集成 mcp-publisher validate
v0.36 完成	已解析依赖树 + SBOM	check_egovframe_dependencies(resolve=true)：通过 Maven dependency:tree·Gradle dependencies 判定传递依赖（origin·via·differs）；新增工具 generate_egovframe_sbom（28 种）：CycloneDX 1.6 JSON（Maven 插件 / Gradle 树配置）+ 基准判定属性 + OSV vulnerabilities[]；解析官方 web 模板：65 个 artifact·67 个 SBOM component·24 条 OSV
v0.37 完成	迁移准备度评估报告 + 回归语料库	generate_egovframe_report(sections=["assessment"])：概述·迁移范围·依赖处置·安全·SBOM·A–D 评级（打印计算公式，并测试重新计算），支持 json·outputPath。test:migrate-corpus：固定官方 common-components v3.10.0·v4.3.2 部分树的预期值（±1%，CI），首次验证 4.x→5.x 实际资源。恢复发布工作流（npm gitHead 标签）
v0.38 完成	执行 common-components 重新组装	新增 reassemble_egovframe_components，执行评估报告中的“重新组装建议”：通过指纹查找 3.x/4.x 源代码的原始标签，进行三方比较（原始·当前·5.0.7）→ 使用最新 common-components v5.0.7（7912e13）组装，并将用户修改保留为补丁·待办列表；生成清单（供之后的 upgrade·validate 使用），支持 dryRun·transaction·compile 验证
v0.39 完成	CLI 模式 + CI 供应链门禁	npx egovframe-scaffold-mcp <assess|check|sbom|migrate|validate> — 无需 AI 客户端，即可在 CI·批处理中运行相同分析（JSON/Markdown、--fail-on 评级·判定阈值、退出代码）；generate_egovframe_ci 的供应链门禁阶段（评估报告·SBOM 工件），SDK 1.32（协议 2025-11-25）
v0.40 完成	SBOM 运维：最小要素·比较·VEX	check_egovframe_sbom：检查现有 SBOM 是否满足最小要素（供应商·组件名称·版本·唯一标识符·依赖关系·作者·生成时间），无需构建工具即可通过 purl 重新查询 OSV，与之前的 SBOM 比较（新增·移除·版本变更·新漏洞），生成 CycloneDX VEX 草案；为 generate_egovframe_sbom 添加供应商·作者元数据——为 2027 年公共 SBOM 提交制度化做准备
v0.41 完成	迁移演练	rehearse_egovframe_migration：在项目副本中运行 migrate apply → reassemble → JDK 17 compile，实测剩余编译错误数量·分布，以及“处理后能最多减少错误的任务”列表（原项目不变）；在评估报告评级旁显示实测结果，CLI rehearse — 固定官方 common-components v4.3.2 完整树的预期值
v0.42 完成	封闭网络运维：离线包	prepare_egovframe_offline_bundle：OSV Maven 转储·固定组件归档·Initializr zip·原始标签镜像 + sha256 manifest；通过 EGOVFRAME_OFFLINE_BUNDLE 将所有下载·OSV 查询替换为使用离线包（显示快照基准日期·过期警告）
v0.43 完成	CI·提交格式多样化	generate_egovframe_ci(platform=gitlab|jenkins)（通过 GitLab 官方 schema·Declarative Jenkinsfile），三个平台的门禁均添加 sbom-check --fail-on minimum，支持公司内部 npm 注册表·离线包变量，支持 SBOM SPDX 2.3 JSON 输出·检查（使用官方 spdx-spec v2.3 schema，并在实际 Maven SBOM 中确认判定结果与 CycloneDX 一致）

다음 버전 기획 (v0.41–v0.43)

v0.40.0 까지 끝난 상태(2026-10-07, 도구 30종 + CLI 명령 8종, 테스트 약 1,600건, npm 0.40.0 자동 배포)에서 다음 세 릴리스를 아래 순서로 진행합니다. 공통 원칙은 이전과 같습니다 — 규칙은 데이터로, 근거는 공식 저장소에서, 쓰기 도구는 dryRun·transaction, 각 버전은 "완료 정의"를 만족해야 릴리스합니다. 이번 세 버전의 공통 주제는 현장에서 그대로 쓰기 입니다 — 자동 단계를 모두 돌린 뒤 사람이 고칠 것이 실제로 얼마나 남는지를 사본에서 재고(v0.41), 망분리된 공공 개발 환경에서도 인터넷 없이 같은 결과를 내며(v0.42), GitHub Actions 와 CycloneDX 밖의 빌드 서버·제출 형식(Jenkins·GitLab, SPDX)으로 넓힙니다(v0.43). 선행 조사 근거는 맨 아래 "선행 조사 결과 (2026-10-07)"에 있습니다.

v0.41.0 — 전환 리허설 (rehearse_egovframe_migration)

목표: 평가서(v0.37)는 전환 난이도를 등급으로, migrate_egovframe_project(apply)와 reassemble_egovframe_components 는 각 단계의 실행을 맡지만, "자동 단계를 전부 돌린 뒤 컴파일 오류가 몇 개 남고, 무엇부터 고치면 가장 많이 줄어드는가"는 아직 실제로 재 보지 않습니다. 사용자 프로젝트를 건드리지 않고 사본에서 전 과정을 돌려 남는 작업을 실측합니다.

범위 (포함)

• 새 도구 rehearse_egovframe_migration(projectDir, steps=["migrate","reassemble","verify"], components?, sourceTag="auto", keepWorkspace=false, timeoutMs)(31번째, 프로젝트는 읽기 전용): (1) 사본 작성 — 캐시 디렉터리(EGOVFRAME_CACHE_DIR/rehearsal/<시각>)에 복사(.git·target·build·node_modules·migration-backup 제외, 원본 파일 수·바이트 기록) (2) 사본에 migrate apply → reassemble(dryRun=false) → JDK 17 compile (3) 결과 — 단계별 변경 파일 수, 컴파일 성공 여부, 남은 오류 수와 파일·패키지·오류 종류별 분포, 오류 ↔ 수동 항목·재조립 작업 목록 연결(v0.33 연결 로직 재사용), "이 작업을 처리하면 오류 N개가 사라진다" 순 상위 작업 목록. 단계 실패는 그 지점까지의 결과와 이유로 돌려줍니다.
• keepWorkspace=true 면 사본 경로를 돌려 사람이 열어 볼 수 있게 하고, 기본은 끝나면 지웁니다. 원본은 실행 전후 디렉터리 지문(경로·크기·mtime)이 같음을 결과에 적습니다.
• 평가서 6절: 프로젝트에 리허설 결과(--out 로 남긴 rehearsal.json, 또는 generate_egovframe_report(rehearsal=true) 로 즉석 실행)가 있으면 등급 옆에 "실측: 자동 전환 후 컴파일 오류 N건"을 함께 표시합니다(등급 산식은 바꾸지 않음).
• CLI rehearse(지표 errors·files·unlinked, 예: --fail-on errors>200).

범위 (제외): 남은 오류의 자동 수정(사람·AI 클라이언트의 일), 테스트 실행(컴파일까지), Gradle 멀티 프로젝트

검증 기준: 공식 공통컴포넌트 v4.3.2 전체 트리(선행 조사: 루트 pom 하나의 war 모듈, 6,523 파일, Java 1.8·Spring 5.3.37·의존성 70개)를 CI 통합에서 리허설해 자동 전환·재조립 뒤 남는 컴파일 오류 수와 상위 작업을 catalog/migration-corpus.json 에 기대값(±10%)으로 고정합니다 — v0.37 코퍼스가 "진단 항목 수"를 고정했다면 이번에는 "남는 오류 수"를 고정합니다. 원본 지문 불변, 단계별 실패 경로(가짜 runner), keepWorkspace 정리 확인.

완료 정의: 도구 31종, docs/design-migration.md 「리허설」 절, README 흐름 예시를 "진단 → 평가서 → 리허설 → 적용" 으로 갱신

결과(2026-10-08) — 완료: src/rehearse.ts. 실측(공식 공통컴포넌트 v4.3.2 전체 트리, 6,523 파일, 전 과정 약 1분): 재조립(원본 v4.3.2 식별, 교체 2,258·추가 69·삭제 62) → 전환 적용(자동 61건, 수동 38건 남음) → 컴파일 오류 6,003건(CI·JDK 17; 로컬 JDK 21 은 6,335건, 파일 503 — 4건을 뺀 전부가 누락 패키지 jakarta.annotation·org.egovframe.rte.ptl.reactive.validation·jakarta.websocket… 와 그 연쇄) → pom 맞춤(parent egovframe-web-config-parent 5.0.2 추가, 좌표 25 추가, 버전 44·scope 3 정리) → 1건(EgovCertInfoUtil — GPKI 벤더 jar 가 javax.servlet 을 참조). 계획과 달라진 점: (a) 단계 순서를 재조립 → 적용으로 바꿨습니다 — 계획대로 적용을 먼저 하면 적용이 컴포넌트 소스를 바꿔 원본 태그가 v5.0.1 로 오인되고 1,489개 파일이 사용자 수정으로 분류됩니다(실측). (b) 자동 단계 뒤 오류의 대부분이 pom 의존성이라 pom 맞춤 단계(align-pom, 사본 전용, 공식 고정 태그 pom 기준)를 더해 "코드 작업"을 분리했습니다. (c) javac 기본 상한(100)을 피하려고 Maven 은 fork + -Xmaxerrs 로 셉니다. 첫 CI 실행에서 JDK 17 이 같은 원인을 JDK 21 과 다른 모양으로 보고해(없는 패키지 import 대신 사용처마다 cannot find symbol, 다른 오류 때문에 Lombok 이 멈춰 getter 가 없음) 누락 의존성 비율이 15% 로 나왔으므로, 분석이 파일의 import 문·타입 선언 파일·Lombok 사용으로 원인을 묶게 고쳤고(두 JDK 모두 99.9%), pom 에 소스 인코딩이 없으면 -Dproject.build.sourceEncoding=UTF-8 을 줍니다(JDK 17 + POSIX 로케일의 한글 주석 오류 방지). (d) 리허설 결과는 프로젝트 안 파일이 아니라 캐시 디렉터리(EGOVFRAME_CACHE_DIR/rehearsal/records)에 남기고 평가서가 읽습니다(프로젝트 읽기 전용 유지). 함께 고친 결함: 4.x 의 org.egovframe.rte 좌표를 5.x 세대로 분류하던 문제(재조립 후보 태그가 5.x 로만 좁혀짐), Maven 출력의 [WARNING]·린트 경고 줄을 컴파일 오류로 세던 문제(build_egovframe_project·verify 에도 영향).

v0.42.0 — 폐쇄망(망분리) 운영: 오프라인 번들

목표: 공공 개발 환경은 대부분 망분리라 인터넷 PC 에서 받은 자료를 반입해 씁니다. 지금은 OSV 조회·공통컴포넌트 아카이브·Initializr zip·재조립 원본 태그·upstream 대조가 실행 시점에 인터넷을 씁니다. 반입 가능한 번들 하나로 같은 결과를 내게 합니다.

범위 (포함)

• 새 도구 prepare_egovframe_offline_bundle(outputDir, include=["osv","components","templates","origin"], dryRun=true)(32번째, 인터넷 쪽에서 실행): OSV Maven 전체 덤프(osv-vulnerabilities/Maven/all.zip)·고정 공통컴포넌트 아카이브(카탈로그 sha256 검증분)·Initializr zip 템플릿·재조립용 원본 태그 bare 미러를 한 디렉터리에 담고 bundle-manifest.json(파일별 sha256·크기·출처 URL·받은 시각·서버 버전)을 씁니다.
• 폐쇄망 쪽: EGOVFRAME_OFFLINE_BUNDLE=<dir> 가 있으면 모든 다운로드가 번들에서 먼저 찾고(지문 검증, 불일치 거부), offline=false 의 OSV 조회(check_egovframe_dependencies·generate_egovframe_sbom·check_egovframe_sbom·평가서)는 로컬 덤프로 대체합니다 — affected[].versions 목록 대조를 기본으로, 목록 없이 ECOSYSTEM 범위만 있는 레코드는 Maven 버전 비교로. 결과에 "OSV 스냅숏 YYYY-MM-DD 기준"을 표시하고 기준일이 오래되면(기본 30일) 경고합니다.
• diagnose_egovframe_network 의 처방에 번들 경로를 추가하고, CLI bundle 명령과 server.json 환경변수 EGOVFRAME_OFFLINE_BUNDLE 을 더합니다.

범위 (제외): Maven 의존성 jar 미러링(기관 Nexus·Artifactory 미러 설정 안내만), 번들 서명(manifest sha256 으로 대신, 요청 시 추가)

검증 기준: 같은 날 받은 덤프로 공식 web 템플릿 SBOM(67 component)의 로컬 OSV 결과가 온라인 querybatch 결과와 같은 ID 집합(차이가 있으면 원인 — 철회·범위 표기 — 를 기록), 프록시를 막은 상태에서 프로젝트 생성(zip 템플릿)·컴포넌트 조립·재조립·SBOM 점검이 번들만으로 성공, 지문이 다른 번들 파일 거부

완료 정의: 도구 32종, README 「폐쇄망에서 쓰기」 절, docs/design-offline-bundle.md

결과(2026-10-10) — 완료: src/offline-bundle.ts(번들 만들기·읽기·로컬 OSV·Maven 버전 비교)와 src/offline-bundle-plan.ts. 실측: 번들 106.8MB(OSV 덤프 9.9MB·7,190건, 아카이브 44.7MB, web 템플릿 14.8MB, 태그 22개 미러 37.3MB), 만드는 데 약 10초. 같은 날 받은 덤프의 로컬 판정이 온라인 querybatch 와 공식 web 템플릿 SBOM 67 component + 옛 버전 표본 6개에서 질의 73/73·ID 134/134 일치, fetch 를 막고 git 을 file 프로토콜로 제한한 상태에서 web 템플릿 생성·bbs 조립(797파일)·4.3.2 재조립 미리보기(원본 v4.3.2 식별)·SBOM 재점검(OSV 27건)이 네트워크 시도 0건으로 끝났습니다. 계획과 달라진 점: (a) 다운로드 훅을 도구마다 두지 않고 공용 fetchWithTimeout(와 카탈로그 아카이브 다운로드)에서 manifest 의 URL 과 맞춰 대체해, 앞으로 생기는 GET 다운로드도 번들에 넣기만 하면 됩니다. (b) 원본 미러는 blob 없는 캐시가 아니라 태그마다 내용까지 받은 미러로 담았습니다 — 22개 태그가 37MB 라 패치 생성까지 폐쇄망에서 됩니다. (c) 저장소 템플릿(브랜치 기준)은 고정 지문이 없어 기본에서 빼고 templates 로 지정할 때만 담습니다. (d) 번들은 새(또는 빈) 디렉터리에만 임시 디렉터리를 거쳐 쓰고 실패하면 남기지 않습니다.

v0.43.0 — CI·提交格式多样化：Jenkins·GitLab、SPDX

目标：公共项目的构建服务器中，Jenkins·GitLab 比 GitHub Actions 更常见，而 SBOM 的提交格式尚未确定（指南 1.0 同时提到了 SPDX·CycloneDX），因此可能会被要求使用 SPDX。将 v0.39 的门禁和 v0.40 的检查扩展到这些环境。

范围（包含）

• generate_egovframe_ci(platform="github"|"gitlab"|"jenkins")：生成 .gitlab-ci.yml·Jenkinsfile（Declarative），用于构建·测试和供应链门禁（使用相同的 CLI 命令 — sbom --write → sbom-check --fail-on minimum → assess --fail-on <failOn>，退出代码 2 视为失败，并保留制品）。企业内部 npm 注册表·离线捆绑包路径作为变量传入。向门禁 job 添加 sbom-check 步骤的改动也会同时应用于 GitHub。
• SPDX：generate_egovframe_sbom(bomFormat="spdx-json") — 将 CycloneDX 文档转换为 SPDX 2.3 JSON（包·DEPENDS_ON 关系·purl externalRefs·supplier·creationInfo.creators·created）；check_egovframe_sbom 也读取 SPDX 2.3 输入，将 7 种最低要素对应到 SPDX 字段并进行检查（VEX 仅支持 CycloneDX）。
• 测试：使用 GitLab 官方 CI JSON 架构验证生成的 .gitlab-ci.yml，并使用官方 spdx-spec v2.3 架构验证 SPDX 输出（与 v0.40 一样，使用固定测试数据 + ajv）。

范围（不包含）：SPDX 3.0、其他 CI（Azure DevOps·Bamboo 等）、Jenkins 插件安装·服务器配置

验证标准：将官方 web 模板 SBOM 转换为 SPDX 后，7 种最低要素的判定和 component 数量保持一致，且通过 SPDX 2.3 架构验证；生成的 .gitlab-ci.yml 通过架构验证；断言 Jenkinsfile 符合 Declarative 结构（pipeline·agent·stages·post）——实际 Jenkins 执行留作待办事项

完成定义：工具共 32 种（无变化）；README「在 CI 中使用」部分包含 GitLab·Jenkins 示例，「准备提交 SBOM」部分包含 SPDX；docs/design-cli.md 中的平台部分

结果（2026-10-11）— 已完成：新增 src/ci-config.ts（三个平台共用相同的门禁命令列表 supplyChainCommands）和 src/spdx.ts（cdxToSpdx·spdxToCdx）。实际测量结果：将使用实际 Maven·cyclonedx-maven-plugin 为官方 web 模板生成的 SBOM（67 个 component，27 条 OSV 记录）转换为 SPDX 2.3 后，生成 68 个包·165 个关系，通过官方 spdx-spec v2.3 架构验证。检查 SPDX 的结果与检查 CycloneDX 的结果在 component 67 个·7 种最低要素各项满足数量（68/68 …）·判定 ready 方面均相同，两者比较后差异为 0。生成的 .gitlab-ci.yml 在 maven·gradle·是否启用门禁·环境变量这 4 种组合下，均通过 GitLab 官方 CI 架构（固定版本 v19.4.1-ee）。与计划不同之处：(a) SPDX 检查不单独设置规则，而是将 SPDX 转换为内部的 CycloneDX 格式，直接复用相同的最低要素·重新判定·比较代码——对应关系（供应方 = PackageSupplier/PackageOriginator，依赖关系 = 以该包为主体的 DEPENDS_ON，作者 = creators 中的 Person·Organization）见 src/spdx.ts 文件头注释和「准备提交 SBOM」表格。(b) 为区分“无依赖”和“未知”，无依赖的包使用 DEPENDS_ON NONE（SPDX 2.3 §11.1）表示，NOASSERTION 则解读为未知。(c) 将基准判定（egovframe:*）和 OSV 结果转换为 SPDX 的 annotations·SECURITY/advisory externalRefs，以便提交为 SPDX 后，“生成后发生变化的判定”·“新发现的漏洞”仍能正常工作。(d) 生成时间是 SPDX 必填项；如果源文档中没有，则在转换时写入转换时间并发出提示（只有这种情况可能导致判定不同）。(e) 门禁的 sbom-check --fail-on minimum 在缺少供应方线索（supplier 或 pom <organization>）时会失败，因此新增了 supplier 参数，并在生成响应中提前提示。(f) GitLab 添加了 JUnit 报告和 artifacts:reports:cyclonedx；Jenkins 添加了 Linux·Windows Agent 通用执行方式（使用 isUnix() 区分 sh/bat）。Jenkins 实际执行验证仍留作待办事项。

待办·运维事项

• Jenkins 执行验证：生成的 Jenkinsfile 仅断言 Declarative 结构。尚未在实际 Jenkins（容器）中进行集成验证。
• 分支保护（所有者操作一次）：在 main 上启用“Require status checks to pass”（gate 6 + integration），即可避免失败状态的合并再次发生。gh api -X PUT repos/EricSeokgon/egovframe-scaffold-mcp/branches/main/protection --input protection.json（required_status_checks.contexts 中包含 7 个检查名称，enforce_admins: false、required_pull_request_reviews: null、restrictions: null）。
• Initializr 上游：最新标签 v5.0.6（84d3682）和 main（bc18641）中的模板 pom parent 仍然是 5.0.0（官方 parent 最新版本为 5.0.2）。值得与现有 3 个问题一起提交为上游问题。
• sbom-live 间歇性失败 — 已确认并解决原因（v0.43）：CI 运行器上的 cyclonedx-maven-plugin 输出有时缺少 metadata.timestamp（本地无法复现），导致“生成时间”这一最低要素缺失。v0.40 PR 的首次失败和 v0.43 PR 的 SPDX 判定不一致（SPDX 要求生成时间，因此会填入转换时间）是同一原因；现在生成器会在时间为空时填入生成时间并发出提示。
• 缺少基准的遗留项：xerces:xercesImpl 没有公开基准，因此保持原样。
• 响应正文英文版：评估报告·检查结果中的标签·标题英文版（--lang en）仍排在后续。
• MCP 新功能：tasks（长时间运行工具的异步执行）在 SDK 中仍处于实验阶段，因此暂缓——v0.41 演练需要数分钟，是第一个耗时较长的工具；稳定后将优先应用。elicitInput 使用 dryRun 模式已足够，因此不使用它。

前期调研结果（2026-10-07）

• 上游标签：egovframe-runtime 最新版为 v5.0.2-Final（与随附规则一致）；egovframe-common-components 为 v5.0.7（于 2026-10-07 重新标记为 7912e13，已在 v0.39 中反映）；egovframe-vscode-initializr 最新标签为 v5.0.6（84d3682），main 为 bc18641（固定 commit f8f5725）；模板 pom 的 parent 在 v5.0.6 和 main 中均为 5.0.0。
• 演练目标：官方公用组件 v4.3.2 是根目录下只有一个 pom.xml（war）的单一 Maven 模块，共有 6,523 个文件，java.version 为 1.8、Spring 5.3.37、含 70 个 <dependency>——可直接用于实际资产演练，一直测试到 JDK 17 编译（重用 v0.38 重组测试使用的 v5.0.7 归档和原始标签镜像）。
• OSV 离线转储：https://osv-vulnerabilities.storage.googleapis.com/Maven/all.zip 大小为 10,356,728 bytes（于 2026-10-06 19:47 GMT 更新，每日更新），包含 7,168 条记录，解压后为 24MB。affected 的范围包括 13,321 个 ECOSYSTEM 和 121 个 SEMVER；11,700 个 affected 中列出了明确版本，因此大多数情况只需比对列表即可判定。以 org.springframework:spring-webmvc 6.2.11 为例，本地转储中有 12 条记录（与在线结果一致是 v0.42 的验证标准）。
• SPDX：spdx/spdx-spec 标签 v2.3 的 schemas/spdx-schema.json（45,312 bytes）可用作测试固定文件。
• 工具依赖：@modelcontextprotocol/sdk 最新版为 1.32.1（2026-10-05，与随附版本一致）。@cyclonedx/cyclonedx-library 10.3.0 要求 Node ≥20.18，因此在包含 Node 18 的门禁中，继续采用与 v0.40 相同的 ajv + 官方架构固定文件方案。

先前规划（v0.38–v0.40，已完成）

在 v0.37.0 完成后（2026-10-05，28 种工具，约 1,500 项测试，npm 自动发布至 0.36.1，0.37.0 正在发布），我们按以下顺序推进了接下来的三个版本。截至 2026-10-07，三个版本均已完成；原始规划保留作记录，结果写在各项目下方。共同原则与之前相同——规则以数据形式管理，依据来自官方存储库，写入工具采用 dryRun·transaction，各版本必须满足“完成定义”才能发布。这三个版本的共同主题是从评估走向执行——由工具完成评估报告指出最耗费人力的公用组件重组工作（v0.38），在没有 AI 客户端的情况下于 CI 和批处理中运行相同分析（v0.39），并且不止于生成 SBOM，还要将其作为提交物进行验证、比较和追踪（v0.40）。前期调研依据见文末的“前期调研结果（2026-10-05）”。

v0.38.0 — 공통컴포넌트 재조립 실행 (reassemble_egovframe_components)

목표: 코퍼스가 보여 준 대로 3.x/4.x 프로젝트의 수동 전환 항목 대부분은 복사해 넣은 공통컴포넌트 소스 안에 있습니다(4.3.2 트리: 수동 717건 중 제거된 공통컴포넌트 클래스 524·재조립 권고 155). 지금은 "add_egovframe_components 로 5.0.6 을 다시 조립하고 사용자 수정은 백업과 diff 로 옮기세요"라고 안내만 합니다. 이 과정을 도구가 수행하되, 사용자가 손댄 파일을 한 줄도 잃지 않게 합니다.

범위 (포함)

• 선행: 공통컴포넌트 v5.0.7 대응 — upstream 이 2026-10-06 v5.0.7 을 냈습니다(v5.0.6 대비 1,672파일, 주로 uss·sym·cop 매퍼·JSP·uss/ion·cop/smt). 재조립 대상 버전이 곧 이 태그이므로, 먼저 컴포넌트 카탈로그(generate:catalog)·전환 규칙의 공통컴포넌트 대응표(components.toTag)·sync_egovframe_catalog 고정을 v5.0.7 로 올리고 회귀 코퍼스 기대값을 갱신합니다(drift 감시가 CI 에서 이미 경고 중).
• 새 도구 reassemble_egovframe_components(projectDir, components?, sourceTag="auto", database?, dryRun=true, verify=false)(29번째): (1) diagnose_egovframe_project 가 감지한 컴포넌트 중 전환 항목이 있는 것(평가서의 재조립 권고와 같은 기준)을 대상으로 삼고 components 로 좁힐 수 있습니다. (2) 원본 태그 식별 — 프로젝트의 컴포넌트 파일 해시를 세대에 맞는 후보 태그(3.x: v3.9.0·v3.10.0 / 4.x: v4.0.0–v4.3.2, 공식 저장소 태그 21종 중)의 같은 경로와 대조해 일치 비율이 가장 높은 태그를 고릅니다. 후보 트리는 v0.37 코퍼스의 sparse 부분 클론을 컴포넌트 접두어 단위로 재사용해(태그당 수 MB) .egov-cache 에 캐시하고, sourceTag 로 고정할 수 있습니다. (3) 3-way 분류 — 원본(식별한 태그)·현재·5.0.6 의 파일 해시로 unchanged(교체)·user-modified(교체 + 사용자 변경을 unified diff 패치로 보존)·added(사용자 파일, 유지)·removed-in-5.x(5.0.6 에 없는 파일, 백업 후 제거 — sec/rnc 실명확인·utl/sec 등 코퍼스에서 확인된 미대응 디렉터리는 작업 목록에 올림)로 나눕니다. upgrade_egovframe_project 의 classifyUpgrade 와 같은 규칙이며 매니페스트 대신 원본 태그가 기준선입니다. (4) 조립 — add_egovframe_components 의 계획기로 5.0.6 파일(소스·매퍼·JSP·메시지·설정 조각·DB 스크립트)을 내려받아 넣고 매니페스트(.egovframe-components.json, 해시 포함)를 기록해 이후 upgrade·validate·remove 수명주기 도구가 적용되게 합니다. 모든 변경은 하나의 transaction, 원본은 migration-backup/<timestamp>/, 사용자 패치는 migration-backup/<timestamp>/patches/<component>/*.patch 와 reassemble-plan.json(파일별 분류·패치 경로·작업 목록). (5) 작업 목록 — 사용자 수정 파일마다 "5.0.6 의 같은 파일에 이 패치를 다시 적용" 항목을, 5.x 에 없는 파일마다 "대체 방법" 항목을 내고, verify=true 면 build_egovframe_project(compile) 을 돌려 v0.33 의 연결 규칙으로 오류를 항목에 붙입니다. 결과는 Markdown·format=json(outputSchema), 도구 메타는 파괴적(destructive, 기존 파일 교체)·openWorld.
• migrate_egovframe_project 진단의 component-reassemble 항목 to 에 새 도구 호출을 안내하고, 평가서 2절의 재조립 권고에 "원본 태그 추정"을 미리 보여 줍니다(일치 비율).
• 회귀 코퍼스 확장: 4.3.2 트리에서 cmm·bbs 를 재조립(dryRun)했을 때 분류 건수(unchanged 전부, user-modified 0)와 원본 태그 식별(v4.3.2, 일치 100%)을 기대값으로 고정하고, 한 파일을 바꾼 뒤 user-modified 1·패치 1 을 단언합니다.

범위 (제외): 사용자 패치의 자동 재적용(5.0.6 소스가 많이 바뀌어 fuzz 적용은 오히려 위험 — 패치와 작업 목록까지), 컴포넌트 밖 애플리케이션 코드가 호출하는 제거 클래스의 수정(기존 class-removed 수동 항목 유지), DB 스키마 변경 스크립트 실행

검증 기준: 공식 5.x 템플릿에 공통컴포넌트 v3.10.0 의 bbs(+의존 cmm) 소스를 복사하고 파일 2개를 수정한 픽스처에서 — 원본 태그 v3.10.0 식별, 분류(unchanged·user-modified 2·added 0·removed-in-5.x ≥ 0), dryRun 무기록, 적용 후 5.0.6 파일 해시 일치·패치 2개·매니페스트 생성·validate_egovframe_project 통과, JDK 17 mvn compile 통과(CI 통합), fault-injection rollback. 코퍼스 기대값 갱신. Windows 게이트 3개 통과

완료 정의: 도구 29종, docs/design-migration.md 에 재조립 절(원본 태그 식별·3-way·보존 규칙), README 에 흐름 예시(진단 → 평가서 → 재조립 → apply → verify)

결과(2026-10-06) — 완료: 선행 작업으로 컴포넌트 카탈로그(190항목, 아카이브 sha256·크기·파일 수 6,604)와 전환 규칙의 공통컴포넌트 대응표를 v5.0.7 로 올렸습니다(제거 클래스 54 → 55, EgovDtaUseStatsContoller 추가; 회귀 코퍼스 기대값 변화 없음). 원본 태그 식별은 계획한 "파일 해시 대조"를 git blob id 로 구현해, 태그마다 blob 없는 shallow fetch(≈1초·수백 KB)와 ls-tree 만으로 끝나고 파일 내용은 사용자 수정 파일의 패치를 만들 때 그 blob 하나만 받습니다. CRLF 체크아웃도 LF 정규화 id 로 같은 파일로 봅니다. 계획과 다른 점: (a) 메시지·설정 조각·웹 자산은 사용자 수정이면 덮어쓰지 않고 유지하며 목표본을 참고로 저장(설정 파일 교체가 실행 환경을 깨뜨릴 위험), (b) CI 통합의 mvn compile 은 넣지 않았습니다 — cmm·bbs 만으로는 5.0.7 의 다른 컴포넌트 참조 때문에 단독 컴파일이 성립하지 않아, 대신 쓴 파일 전부가 v5.0.7 tree 의 blob 과 같은지(780개)와 validate·upgrade 정합을 단언합니다, (c) 평가서의 "원본 태그 추정" 미리보기는 평가서가 기본 오프라인이라 넣지 않고 재조립 dryRun 으로 대신합니다. 부수 수정: upgrade_egovframe_project 가 조립 때 함께 설치된 자산 파일을 upstream 에 없는 것으로 보고하던 결함(재조립 픽스처에서 621건 "removed"), 만료 토큰(401)이면 비인증으로 다시 조회.

v0.39.0 — CLI 모드 + CI 공급망 게이트

목표: 공공 사업의 빌드 서버(Jenkins·GitHub Actions·GitLab CI)에는 AI 클라이언트가 없습니다. 평가서·의존성 점검·SBOM 을 그 자리에서 사람 없이 돌리고, 등급·판정이 기준을 넘으면 파이프라인을 멈추게 합니다. 도구 로직은 그대로 두고 호출 통로만 하나 더 엽니다.

범위 (포함)

• CLI: npx egovframe-scaffold-mcp <command> [options] — 인자가 없으면 지금처럼 MCP stdio 서버로 뜨고(기존 호환), 명령이 있으면 그 도구를 실행하고 종료합니다. 명령은 읽기 전용·dryRun 도구로 한정: assess(평가서), check(의존성), sbom(--write 없으면 dryRun), migrate(진단만), validate, diagnose, network. 공통 옵션 --project <dir>, --json(structuredContent 그대로), --out <file>, --lang ko|en(라벨·헤더), 도구별 옵션은 MCP 파라미터와 같은 이름(--resolve, --offline=false, --scope all). 허용 root·네트워크 처방·오류 메시지는 MCP 경로와 동일. 구현은 src/cli.ts 가 server.ts 의 핸들러를 직접 호출(프로토콜 왕복 없음).
• 게이트 옵션 --fail-on: assess 에 migration:C·supplyChain:C(이 등급 이상이면 종료 코드 2), check 에 outdated·legacy·replace·vulnerabilities(건수 임계값 vulnerabilities>0), migrate 에 manual>0. 종료 코드 규약: 0 통과 · 2 기준 초과 · 3 실행 실패(빌드 도구 없음·네트워크) · 64 인자 오류. 결과 요약은 stderr 한 줄, 본문은 stdout — 파이프라인 로그와 아티팩트 둘 다에 맞춥니다.
• generate_egovframe_ci(supplyChain=true): 생성하는 워크플로에 "공급망 게이트" job 을 추가 — npx egovframe-scaffold-mcp@<이 버전> assess --json --out assessment.json --fail-on supplyChain:D 와 sbom --write --offline=false, 결과를 아티팩트로 업로드, PR 요약($GITHUB_STEP_SUMMARY)에 등급 표. 기존 빌드·테스트 job 은 그대로.
• SDK @modelcontextprotocol/sdk 1.29 → 1.32(프로토콜 2025-11-25): 변경 없는 업그레이드인지 핸드셰이크·구조화 출력 테스트로 확인하고, 실험 단계인 tasks(장시간 도구의 비동기 실행)는 안정화될 때까지 쓰지 않습니다(선행 조사 참조).
• 테스트: CLI 오프라인 스위트(명령·옵션 매핑·종료 코드·JSON 동일성 — 같은 입력에 MCP structuredContent 와 CLI --json 이 같은 객체), CI 생성 스냅샷, 통합 job 에서 생성된 워크플로 YAML 을 actionlint 로 검사하고 CLI 로 평가서를 실제 실행.

범위 (제외): 쓰기 도구의 CLI 노출(프로젝트 생성·조립·적용은 사람이 결과를 보는 MCP 경로로 유지), 대화형 프롬프트, 응답 본문 전체의 영문화(--lang en 은 평가서·점검 결과의 라벨·헤더까지 — 사유 문장은 한국어 유지)

검증 기준: npx egovframe-scaffold-mcp assess --project <공식 5.x 템플릿> --json 이 MCP 호출과 같은 JSON, --fail-on migration:B 로 코퍼스 트리에서 종료 코드 2, 인자 없는 실행은 기존 핸드셰이크 테스트 통과(stdio 서버), 생성 워크플로가 GitHub Actions 에서 실제로 등급 표를 남김(이 저장소의 통합 job 에서 1회)

완료 정의: 도구 29종(변화 없음) + CLI 명령 7종, README 「CI 에서 쓰기」 절, docs/design-cli.md

결과(2026-10-06) — 완료: src/cli.ts 는 핸들러를 직접 부르지 않고 SDK 의 InMemoryTransport 로 같은 서버에 붙은 클라이언트가 tools/call 을 보내게 했습니다 — 입력 검증·허용 root·outputSchema 검증이 MCP 경로와 같아 --json 동일성이 구조적으로 보장되고 SDK 내부 필드에 기대지 않습니다. 계획보다 늘어난 것: 명령 7종에 diagnose·network 포함, --fail-on 지표를 명령별로 정의(평가서의 등급 2종·건수 8종 등), sbom 은 --write 로만 기록. 계획과 다른 점: (a) --lang en 라벨 영문화는 넣지 않았습니다(렌더러마다 바꾸는 일이라 별도로), (b) 생성 워크플로의 "실제 Actions 실행"은 이 저장소 통합 job 에서 actionlint 검사와 CLI 평가서 실행(job 요약에 등급 표)으로 대신했습니다 — 게이트 job 자체는 npm 에 이 버전이 게시돼야 돌 수 있기 때문입니다. SDK 는 1.29 → 1.32.1(프로토콜 2025-11-25)로 올렸고 기존 테스트가 변화 없이 통과했습니다(tasks 는 실험 단계라 미사용).

v0.40.0 — SBOM 运维：最小要素·比较·VEX

目标：预计到 2027 年，公共领域 IT 系统和软件产品的 SBOM 提交将制度化（先行调查）。提交内容不能只是“已生成”，还必须同时说明是否缺少要素、与上次提交相比有哪些变化，以及对已知漏洞做出了什么判断。在 v0.36 的生成器上补充这三项能力。

范围（包含）

• 新增工具 check_egovframe_sbom(projectDir, sbomPath="sbom/bom.cdx.json", baselinePath?, offline=true, vex=false, format)（第 30 个，只读、可选写入）：（1）最小要素检查 — 统计文档和各 component 是否具备供应方（supplier/publisher）、组件名称、版本、唯一标识符（purl/cpe）、依赖关系（在 dependencies[] 中引用）、作者（metadata.authors/tools）和生成时间（metadata.timestamp），并给出“可提交/需要补充”结果及缺失的 component 列表（默认采用 NTIA 的 7 项最小要素规则；国内指南新增要求时，将其作为数据纳入）。 （2）无需构建工具即可重新检查 — 仅根据 SBOM 中的 purl，重新进行基准判定（v0.34 分类器）并查询 OSV，报告“生成后新发现的漏洞”（用于运行期间的定期检查）。 （3）比较 — 比较 baselinePath（先前的 SBOM）与当前 SBOM 的 component 集合，以表格列出新增、移除、版本变更、判定变化和新漏洞（比较部署前后及不同提交版本）。 （4）VEX 草案 — 当 vex=true 时，为每个发现的漏洞生成 CycloneDX VEX 文档（vulnerabilities[].analysis.state=in_triage，通过 affects 引用 component，通过 bom-link 引用原始 SBOM），并作为新文件写入 sbom/vex.cdx.json。判断（not_affected、exploitable 等）由人工填写；后续运行会保留现有 VEX 中的判断，只添加新漏洞。
• 为 generate_egovframe_sbom 增加 supplier、author、componentName、componentVersion 选项（若未指定，则从 pom 的 organization、name、version 获取；仍未获取到时留空，由检查标记为需要补充），并记录 metadata.lifecycles（build）— 在生成阶段填充最小要素。
• 评估报告第 5 节（SBOM）同时展示最小要素是否满足、最近检查日期和 VEX 是否存在。
• 测试：最小要素规则（按缺失项分别测试）、purl 重新判定、OSV 模拟查询、比较（新增、移除、版本、漏洞）、VEX 生成与保留、bom-link，以及对官方 web 模板 SBOM 进行实际 OSV 重新检查（集成至 CI）。

范围（不包含）：SPDX 输出与转换（有需求时集成 CycloneDX → SPDX 转换器）、漏洞判断自动化（VEX 状态由人工决定）、对接中央存储库提交 API（制度确定前）

验证标准：报告 v0.36 生成的官方 web 模板 SBOM（69 个 component）在最小要素检查中缺少哪些项目（预期：supplier、authors）；使用补充选项重新生成后检查通过；比较两个 SBOM 时仅报告预期差异；重新运行 VEX 时保留人工填写的状态

完成定义：工具共 30 种；docs/design-dependency-check.md 中新增 SBOM 运维章节；README 新增“SBOM 提交准备”章节

结果（2026-10-07）— 已完成：新增 src/sbom-check.ts（规则位于 catalog/sbom-rules.json — 每项要素的认可字段路径以数据形式配置，仅对依赖关系和生成时间进行特殊检查），并为 generate_egovframe_sbom 增加元数据选项。实测结果：对官方 web 模板实际运行 cyclonedx-maven-plugin 2.9.3 生成的 SBOM（67 个 component；计划中的 69 是 v0.36 当时的解析数量）进行检查后，供应方为 50/68（主 component、RTE、AspectJ、Micrometer 等 18 种没有 pom <organization>）且作者（插件仅记录 metadata.tools）为空，因此标记为“需要补充”；其余 5 项要素均为 68/68。与计划不同之处：（a）库的供应方无法通过选项填充，因此新增供应方表（suppliers，包含 10 条 groupId 前缀记录，每项均有 pom 依据），仅填充缺失的 component，并通过 egovframe:supplierBasis=catalog 标记来源 — 采用此表以及 supplier、author 重新生成后，7 项要素均满足。（b）主 component 名称直接使用 artifactId，而非 pom <name>（仅通过 componentName 覆盖）。（c）fillSuppliers 的默认值遵循 enrich（enrich=false 时，文档保持原样）。（d）如果 SBOM 中没有 vulnerabilities[]（离线生成），则将重新查询的结果标记为“未记录”，而不是“新发现”。（e）如果已完成判断的 ID 出现新的受影响 component，VEX 不会扩展该判断，而是为同一 ID 创建新的 in_triage 条目。生成的 SBOM 和 VEX 会在测试中通过 CycloneDX specification 1.6.1 官方 JSON 架构进行验证（架构仅作为测试固件，不随包提供）。新增 CLI 命令 sbom-check（包含 minimum、newVulns 等指标，通过 --write 写入 VEX）。

暂缓与运维事项（当时）

• 分支保护（所有者操作一次）：在 main 上启用“Require status checks to pass”（gate 6 + integration），可防止 #33、#36 等失败状态再次被合并。可通过 gh api -X PUT repos/EricSeokgon/egovframe-scaffold-mcp/branches/main/protection --input protection.json（required_status_checks.contexts 中包含 7 个检查名称，enforce_admins: false、required_pull_request_reviews: null、restrictions: null）一次性完成设置。
• 确认 MCP Registry 注册：v0.37.0 自动发布（Release #4）是首次发布。如果失败，下次合并 main 时，Release 会仅重试 Registry 阶段（v0.37 恢复判定）。
• Initializr upstream：固定 commit（f8f5725）和当前 main（bc18641）的模板 pom 均使用 parent 5.0.0（官方 parent 最新版本为 5.0.2）。这是评估报告将官方模板的供应链评级定为 B 的原因之一，值得作为 upstream 问题提交（与已有 3 项一并提交）。
• 无基准的剩余项：xerces:xercesImpl 没有公开基准，因此保持原样。v0.40 的 purl 重新判定结果也相同。
• 响应正文英文支持：使用 v0.39 的 --lang en 扩展评估报告和检查结果中的标签与标题；原因说明全文的英文翻译继续列为后续工作。Homebrew tap 已从后续事项中移除（npx 已足够）。

선행 조사 결과 (2026-10-05)

• 재조립 가능성(코퍼스): 3.10.0 트리의 java 디렉터리 454개 중 5.0.6 카탈로그 접두어에 대응하는 컴포넌트 id 153종(java 1,095개 중 1,085개 = 99%), 미대응은 com/sec/rnc(실명확인)·com/utl/sec 6개 디렉터리·10개 파일뿐. 4.3.2 는 154종·미대응 3개 디렉터리·5개 파일. 즉 재조립은 거의 전부에 적용되고, 5.x 에 없는 소수만 작업 목록으로 남습니다. 공식 공통컴포넌트 저장소 태그는 21종(v3.9.0·v3.10.0·v3.10.0-FINAL·v4.0.0–v4.3.2·v5.0.0–v5.0.6)이라 원본 태그 후보가 유한하고, v0.37 의 sparse 부분 클론(접두어 단위)으로 후보를 싸게 받을 수 있습니다.
• 공급망 보안 제도: 과기정통부·국정원의 SW 공급망 보안 로드맵(2026-06-24, 9개 분야)은 개발 단계 보안 내재화·SBOM 확산·위협 탐지·제도 정비를 담고, "공공분야에 도입되는 IT시스템 및 소프트웨어 제품에 대한 SBOM 제출을 2027년까지 제도화"가 명시됐습니다. SW 공급망 보안 가이드라인 1.0(2024-05)은 SBOM 유효성 검증·구성요소 관리·SBOM 기반 관리 방안을 다루며 형식(SPDX/CycloneDX)은 특정하지 않습니다. SBOM 핵심 구성요소는 NTIA 최소 요소와 같은 7종(공급자·구성요소명·버전·고유식별자·의존관계·작성자·생성 시각)으로 통용됩니다 — v0.40 의 점검 규칙 기본값.
• MCP SDK·프로토콜: @modelcontextprotocol/sdk 최신 1.32.0(2026-10-02), 동봉 1.29.0. 최신 프로토콜 2025-11-25(tasks/* 요청은 SDK 에서 experimental 네임스페이스 — 장시간 도구의 비동기 실행이지만 클라이언트 지원과 API 안정성이 확인되기 전까지 보류), elicitInput(서버가 사용자 입력을 요청)은 안정 API 로 존재하나 승인 UX 는 dryRun 패턴으로 충분해 쓰지 않습니다. 업그레이드는 v0.39 에서 테스트 변화 없음을 확인하며 수행.
• CycloneDX: cyclonedx-maven-plugin 최신 2.9.3(동봉과 같음), CycloneDX 1.6 은 VEX 를 같은 스키마의 vulnerabilities[].analysis(state·justification·response·detail)와 bom-link 로 표현하므로 별도 포맷 없이 VEX 문서를 낼 수 있습니다.
• upstream 상태: egovframe-runtime 최신 태그 v5.0.2-Final(동봉 규칙과 같음), egovframe-common-components v5.0.6(같음 — 단 2026-10-06 v5.0.7 이 나와 v0.38 선행 작업으로 반영), Initializr main 은 bc18641(고정 commit f8f5725 이후 변경이 있으나 템플릿 pom 의 parent 는 여전히 5.0.0).
• CLI 선례: Node MCP 서버가 같은 바이너리로 CLI 명령을 겸하는 패턴(인자 없음 → stdio 서버, 명령 → 실행 후 종료)은 기존 bin 과 핸드셰이크 테스트(인자 없는 기동)를 그대로 유지할 수 있습니다. 종료 코드 규약은 sysexits(64 = 사용법 오류)를 따릅니다.

이전 기획 (v0.35–v0.37, 완료)

v0.34.0 까지 끝난 상태(2026-10-04, 도구 27종, 테스트 약 1,300건, npm 0.33.1 배포·0.34.0 배포 대기)에서 다음 세 릴리스를 아래 순서로 진행했습니다. 세 버전 모두 2026-10-05 까지 완료했으며 기획 원문은 기록으로 남기고 결과를 항목 아래에 적었습니다. 공통 원칙은 이전과 같습니다 — 규칙은 데이터로, 근거는 공식 저장소에서, 쓰기 도구는 dryRun·transaction, 각 버전은 "완료 정의"를 만족해야 릴리스합니다. 이번 세 버전의 공통 주제는 배포와 운영을 사람 손에서 떼어 내는 것(v0.35), 선언된 의존성이 아니라 실제로 실리는 의존성을 보는 것(v0.36), 지금까지 만든 분석을 한 장의 평가서와 회귀 코퍼스로 묶는 것(v0.37)입니다. 선행 조사 근거는 맨 아래 "선행 조사 결과 (2026-10-04)"에 있습니다.

v0.35.0 — 릴리스 자동화 (배포 공급망)

목표: v0.29–v0.34 여섯 번의 릴리스에서 태그를 잘못된 커밋에 단 일(2회), npm 배포를 빠뜨린 일(0.32.0·0.33.0), Windows 게이트 실패 상태로 병합한 일(2회)이 모두 사람이 명령을 순서대로 치는 과정에서 났습니다. main 에 병합되면 나머지(게이트 재확인 → 태그 → npm → GitHub Release → MCP Registry)는 CI 가 하고, 사람은 PR 병합만 합니다. 배포물에는 provenance 가 붙어 "이 npm 패키지는 이 저장소의 이 커밋에서 이 워크플로가 만들었다"를 소비자가 검증할 수 있게 합니다.

범위 (포함)

• .github/workflows/release.yml: CI 워크플로가 main 에서 성공한 뒤(workflow_run)에만 실행. package.json 버전을 읽어 (a) server.json 두 version 과 같고, (b) README 변경 이력에 그 버전 항목이 있고, (c) 태그 vX.Y.Z 가 아직 없고, (d) npm 에 그 버전이 없을 때만 진행합니다. 네 조건 중 하나라도 어긋나면 이유를 적고 성공 종료(병합마다 도는 워크플로가 빨간불이 되지 않게).
• npm: trusted publishing(OIDC) 으로 토큰 없이 npm publish --access public. 공개 저장소·공개 패키지이므로 provenance 가 자동으로 붙습니다. 요구 조건은 npm CLI 11.5.1+·Node 22.14+·id-token: write·self-hosted 러너 금지이며, npmjs.com 의 패키지 설정에서 trusted publisher(저장소 EricSeokgon/egovframe-scaffold-mcp, 워크플로 파일명 release.yml)를 저장소 소유자가 한 번 등록해야 합니다(README 절차에 적음).
• 태그·Release: 배포가 성공한 그 main 커밋에 vX.Y.Z 태그를 만들고, scripts/release-notes.mjs 가 README 변경 이력에서 해당 버전 항목을 뽑아 GitHub Release 본문으로 씁니다(태그가 병합 전 커밋에 달리는 사고가 구조적으로 사라집니다).
• MCP Registry: mcp-publisher login github-oidc → mcp-publisher publish(io.github.EricSeokgon/* 네임스페이스는 GitHub OIDC 로 소유 증명, 비밀 없음). npm 에 패키지가 먼저 있어야 하므로 npm 단계 뒤에 둡니다. 첫 실행이 곧 "MCP Registry 첫 등록"(보류 항목)이 됩니다.
• 패키지 내용 검사: npm pack --dry-run --json 으로 tarball 에 dist/·catalog/·server.json·README*·LICENSE 만 들어가고 test/·scripts/·.github/ 가 없는지, 크기 상한(현재 약 1.2MB → 2MB)을 넘지 않는지 게이트에서 단언(test:package). test:registry 에 "변경 이력에 현재 버전 항목 존재" 단언 추가(변경 이력 누락을 게이트가 막음).
• README 릴리스 절차를 "PR 병합 → CI 가 나머지 수행 → npm view·Release 페이지 확인" 3단계로 줄이고, 수동 절차는 비상용으로만 남깁니다.

범위 (제외): 브랜치 보호 설정(저장소 설정이라 코드로 못 함 — 보류 항목에 유지), Homebrew 탭, Windows 서명

검증 기준: test:package·test:registry 게이트 통과. 워크플로는 실제 병합으로만 검증할 수 있으므로 v0.35.0 자체는 마지막 수동 릴리스로 내고, 병합 직후 release.yml 의 "조건 불충족 → 성공 종료" 경로(이미 태그·npm 이 있음)를 로그로 확인합니다. v0.36.0 부터 자동 배포. 배포 뒤 npm view egovframe-scaffold-mcp --json 의 dist.attestations 와 GitHub Release·MCP Registry 검색 결과를 확인합니다.

완료 정의: 도구 27종(변화 없음), release.yml 병합, npmjs.com trusted publisher 등록(소유자 수동 1회, README 에 체크리스트), v0.36.0 이 사람 명령 없이 npm·태그·Release·Registry 에 게시

결과(2026-10-04) — 완료: release.yml(workflow_run: CI 성공 후, workflow_dispatch 로 수동 재실행 가능) + scripts/release-check.mjs(네 조건 판정, GITHUB_OUTPUT) + scripts/release-notes.mjs(변경 이력 항목 → Release 본문에 설치 스니펫·검증 안내) + test/release.mjs 32단언. 기획과 달라진 점: (1) mcp-publisher validate 를 실제로 돌려 보니 server.json 의 description 이 레지스트리 상한 100자를 넘어 첫 등록이 실패할 상태였습니다 — 98자로 줄이고 test:registry 가 100자 이하를 단언하며, CI 통합과 release.yml 이 npm 게시 전에 validate 를 돌립니다(npm 에 없는 버전도 스키마 검증은 통과함을 확인). (2) 레지스트리 게시 단계는 continue-on-error 로 두어 npm·태그·Release 가 끝난 뒤의 실패가 릴리스 자체를 되돌리지 않게 하고 경고로 남깁니다. (3) 릴리스 노트는 변경 이력 항목의 "(1) (2)" 번호 앞에서 단락을 나눠 읽기 쉽게 합니다. 바이너리는 mcp-publisher v1.8.1(자산 이름 mcp-publisher_<os>_<arch>.tar.gz, 버전 접두 없음)로 고정했습니다. v0.35.0 자체는 마지막 수동 릴리스이며, 병합 뒤 release.yml 이 "태그·npm 이미 있음 → 배포 안 함" 으로 성공 종료하는지 확인합니다.

v0.36.0 — 해석된 의존성 트리 + SBOM

목표: check_egovframe_dependencies 는 pom 에 적힌 의존성만 봅니다. 공식 egovframe-web 템플릿은 선언 19건·조치 0건이지만, Maven 으로 실제 해석하면 런타임에 69개 artifact 가 실리고 그중 11개가 기준 미만, 9개가 기준 밖, 8개에 OSV 권고가 붙어 있습니다(선행 조사). 전이 의존성까지 보는 resolve=true 와, 2027년부터 공공기관 SW 등록에 요구될 SBOM 을 표준 형식(CycloneDX 1.6)으로 만들어 주는 도구를 추가합니다.

범위 (포함)

• check_egovframe_dependencies(resolve=true, resolveScope="runtime"|"all", timeoutMs): build_egovframe_project 의 러너(타임아웃·프로세스 트리 종료·래퍼 감지)로 Maven org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputFile -DoutputType=text(pom 변경 없이 좌표를 완전히 적어 호출) 또는 Gradle dependencies --configuration runtimeClasspath 를 실행해 트리를 파싱합니다. 결과 findings 에 origin: "declared" | "transitive" 와 via(트리 경로, 예 egovframe-rte-ptl-mvc → spring-webmvc)를 붙이고, 해석된 집합 전체를 기존 분류기(parent → 계열 → Boot BOM/RTE 전이, v0.34)로 판정합니다. summary 는 선언/해석을 나눠 세고, 선언한 버전과 해석된 버전이 다른 좌표(가까운 선언이 이김)는 resolvedDiffers 로 따로 보입니다. offline=false 면 OSV 조회도 해석된 집합에 대해 합니다. 빌드 도구가 없거나 해석이 실패하면 선언 기준 결과에 이유를 붙여 돌려줍니다(기존 동작 유지).
• 새 도구 generate_egovframe_sbom(projectDir, format="cyclonedx-json", outputPath="sbom/bom.cdx.json", enrich=true, offline=true, dryRun=true): Maven 은 org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom(멀티 모듈 합산, pom 변경 없음), Gradle 은 --init-script 로 cyclonedx-gradle-plugin 3.4.1 을 적용(빌드 파일 변경 없음)해 CycloneDX 1.6 JSON 을 만듭니다. enrich=true 면 component 마다 properties 에 egovframe:status(기준 판정)·egovframe:basis·egovframe:baseline 을 붙이고, offline=false 면 OSV 결과를 CycloneDX vulnerabilities[](affects 로 component 참조)로 넣습니다. 출력은 프로젝트 안 경로만 허용, 기존 파일은 overwrite=true 가 아니면 거부, transaction·dryRun(요약만) 적용. 응답은 component 수·직접/전이 수·판정 집계·취약점 수·파일 경로.
• 도구 메타: generate_egovframe_sbom 은 openWorldHint(빌드 도구가 저장소 접근)·비파괴(새 파일만, overwrite 는 명시)·outputSchema 선언. 영문 설명·README·AGENTS.md 생성기(사용 가능 도구 목록)에 반영.
• 기준 카탈로그 소급: 선행 조사에서 드러난 공통컴포넌트 4.3.2 pom 의 project:* groupId(system scope 로 로컬 jar 를 붙이는 관행)는 vendor 로 분류하고 사유에 "system scope 로컬 jar — SBOM 에서 공급자 확인 필요" 를 적습니다.

범위 (제외): SPDX 형식(요구가 생기면 CycloneDX → SPDX 변환기로), 취약점 DB 동봉, 라이선스 정책 판정(SBOM 에 라이선스는 플러그인이 넣는 그대로)

검증 기준: 공식 egovframe-web 템플릿(자리표시자 채운 pom)에서 resolve=true 가 60개 이상 해석·transitive 표시·via 경로 존재, SBOM 이 bomFormat: CycloneDX·specVersion: 1.6·component 60개 이상·모든 component 에 purl(pkg:maven/…)·enrich 속성 존재; offline=false 로 vulnerabilities[] 가 OSV 결과와 같은 수; Gradle 템플릿(egovframe-boot-web 를 Gradle 로 변환한 픽스처 또는 공식 Gradle 샘플)에서 init script 경로 통과; 오프라인 테스트는 트리 파서(Maven·Gradle 출력 픽스처)와 SBOM 보강을 가짜 러너로 단언; CI 통합에 실제 Maven 해석·SBOM 생성 추가

완료 정의: 도구 28종, test:dependencies 에 해석 경로 단언, 신규 test:sbom(오프라인)·test:sbom-live(CI), docs/design-dependency-check.md 에 해석·SBOM 절, README 에 SBOM 사용 예

결과(2026-10-04) — 완료: src/dependency-tree.ts(Maven·Gradle 트리 파서, 가장 얕은 경로로 중복 제거, 래퍼 감지 명령), check_egovframe_dependencies 의 resolve·resolveScope·resolveTimeoutMs, src/sbom.ts(generate_egovframe_sbom). 기획과 달라진 점: (1) Gradle 은 cyclonedx-gradle-plugin 을 init script 로 적용하는 대신 해석된 트리로 이 서버가 CycloneDX 문서를 직접 구성합니다 — 플러그인 버전별 API 차이 없이 결정적으로 동작하고 오프라인 테스트가 가능하며, 대가로 해시·라이선스가 빠집니다(문서 metadata.tools 와 응답 노트에 명시). (2) Maven 범위는 -Dscope=runtime(dependency:tree)·includeProvidedScope=false(플러그인)로 "실리는 것"에 맞추고 all 로 test·provided 를 포함합니다. (3) 선행 조사의 project:* system scope 좌표를 vendor 로, javax.faces:javax.faces-api 를 Jakarta 규칙(→ jakarta.faces:jakarta.faces-api 4.1.2, Boot BOM 기준)으로 소급해 공통컴포넌트 4.3.2 pom 의 unknown 11 → 1(xerces)이 됐습니다. 실측: 공식 egovframe-web 템플릿 해석 65 artifact(직접 14, 선언에 없던 전이 51; 기준 미만 11·기준 없음 9), SBOM 67 component·205KB·OSV 24건, Gradle 샘플 40~46 artifact. Windows 게이트가 깨진 전력 때문에 트리·SBOM 명령은 플랫폼을 주입해 mvn.cmd·gradle.bat 분기를 단언합니다.

v0.37.0 — 迁移准备度评估报告 + 回归语料库

目标：在公共 SI 项目现场，要回答“把这个 3.x/4.x 系统迁移到 5.x 要做多少工作、需要多久，目前的供应链状态如何”，现在必须依次调用 5 个工具。我们将通过一次调用生成评估报告，并将官方 3.x/4.x 资产的结果固定为语料库，以便在规则或基准发生变化时捕获回归。

范围（包含）

• generate_egovframe_report(sections=["assessment"], resolve=false, offline=true)：在现有报告（诊断）中添加评估报告章节 — (1) 项目概况（构建工具、RTE 世代、parent、Java、公共组件），(2) 迁移范围（migrate_egovframe_project 诊断摘要：自动/手动、按类型统计、文件数量、建议重组的组件、预计手动工作清单前 N 项），(3) 依赖项（基准判定汇总、措施清单、resolve=true 时包含传递依赖、OSV），(4) 安全配置检查，(5) SBOM 摘要（如已生成，则列出路径和 component 数量），(6) 等级与依据：分别为迁移难度（按手动项目数、建议重组的组件数、已移除类引用数分档）和供应链状态（低于基准、需要替换、漏洞数量）评定 A–D 等级，并在报告中原样列出评级公式，以便人工重新计算。支持 Markdown 和 format=json（outputSchema），还可选择将文件保存到 outputPath（transaction、dryRun）。
• 回归语料库 test:migrate-corpus（集成到 CI）：对官方 egovframe-common-components v3.10.0（1,148 个 java）和 v4.3.2（1,295 个 java，4.x 坐标为 org.egovframe.rte:org.egovframe.rte.*）的整个源代码树运行诊断、应用（dryRun）和依赖项检查，将按类型统计的数量、unknown、重组建议和应用计划数量作为预期值固定在 catalog/migration-corpus.json 中，并断言结果在 ±允许范围内。这是首次使用真实资产验证 4.x→5.x 路径，此前仅通过单元测试夹具验证。语料库结果也将用于确定评估报告等级公式的分档。
• 修复语料库揭示的缺陷（前期调查已发现一项：4.3.2 pom 中有 11 个 project:* system scope jar 被标记为 unknown — 在 v0.36 中回溯修正为 vendor；如果还存在 javax.faces 等未处理的 Jakarta 坐标，也会添加映射）。

范围（不包含）：成本和工作量估算（因人和组织而异 — 仅提供数量和等级）、PDF/HWP 输出（由调用方负责将 Markdown 转换为其他格式）

验证标准：固定 2 种语料库（3.10.0、4.3.2）的预期值后，门禁和 CI 均通过；官方 5.x 模板的评估报告显示“迁移范围 0、等级 A”，3.10 资产中将手动项目和重组建议作为等级依据显示；format=json 通过 outputSchema；测试可重新计算等级公式

完成定义：28 种工具（评估报告扩展现有工具）、catalog/migration-corpus.json、docs/design-assessment-report.md、README 中的评估报告示例

结果（2026-10-04）— 已完成：新增 src/assessment.ts（评估、评级、Markdown）和 src/report.ts（章节组装、保存），并为 generate_egovframe_report 添加了 sections、resolve、offline、sbomPath、topN、outputPath、dryRun、format（默认值 ["components"] 保持 v0.16 的原有输出）。评级公式作为数据（MIGRATION_RUBRIC、SUPPLY_CHAIN_RUBRIC）保存，在报告第 6 节中完整打印，并由测试根据报告中的数字重新计算。分档以官方 5.x 模板（迁移 A）和公共组件 3.10.0、4.3.2 的完整树（两项指标均为 D）作为两端基准。与计划不同的两点：outputPath 仅创建新文件，不覆盖现有文件（保持非破坏性）— 因此移除了只读提示（13 种）；官方模板的供应链等级为 B（只有 pom，缺少 3 项安全配置；Initializr 固定 commit 的 parent 为 5.0.0 < 5.0.2 — 两者都是事实，因此没有强行设为 A）。语料库采用稀疏部分克隆，仅克隆待扫描目录，而非完整仓库（约 250MB；每个标签约 3 秒、50MB）；没有发现新缺陷（此前 v0.36 的回溯修正已涵盖全部问题），两个世代均固定为需确认类 0 个、无基准的 xerces 1 项。同一 PR 还修复了 v0.36.1 首次自动发布时暴露的工作流缺陷（传播确认超过 2 分钟 → 漏掉标签和 Release，且无法重新运行），并将其纳入恢复判定。

运营备注（当时）：npm trusted publisher 已在 0.36.1 注册并完成首次 OIDC 发布；MCP Registry 的首次注册安排在 v0.37.0 自动发布时进行。

之前的规划（v0.32–v0.34，已完成）

截至 v0.31.0 已完成（2026-10-02，27 种工具，约 1,100 项测试）后，接下来的 3 个版本按以下顺序推进。三个版本均已于 2026-10-03 前完成，原始规划保留作记录，结果列在各条目下方。共同原则与之前相同 — 规则以数据形式保存，依据来自官方仓库，写入工具支持 dryRun 和 transaction，每个版本必须满足“完成定义”后才能发布。前期调查依据见下方“前期调查结果（2026-10-02）”。

v0.32.0 — MCP 프로토콜 현대화 + 테스트 플랫폼 중립 가드

목표: 도구의 "무엇을 하는가"를 설명문뿐 아니라 프로토콜 메타데이터로도 알려 MCP 클라이언트가 승인 UX(읽기 전용은 자동 허용, 파괴적 도구는 확인)와 구조화된 결과 처리를 할 수 있게 합니다. 외부 동작 변화는 없고, 기존 text 응답은 그대로 유지합니다.

범위 (포함)

• 등록 API: server.tool(...)(SDK 1.29 에서 deprecated) → server.registerTool(name, { title, description, inputSchema, outputSchema?, annotations }, cb) 로 27종 전환. i18n 의 설명 선택은 그대로 description 에 적용하고 title 도 ko/en 으로 둡니다.
• annotations: 읽기 전용 도구 14종(list_*·search_*·explain_*·get_*·diagnose_*·validate_*·generate_egovframe_report·check_egovframe_dependencies·migrate(apply=false)·sync_*)에 readOnlyHint: true, 파일을 지우거나 덮어쓰는 도구(remove_egovframe_components·upgrade_egovframe_project·migrate(apply)·generate_agents_md(overwrite))에 destructiveHint: true, 다시 실행해도 같은 결과인 도구에 idempotentHint, 네트워크를 쓰는 도구에 openWorldHint: true. migrate_egovframe_project 처럼 인자에 따라 성격이 바뀌는 도구는 보수적으로(파괴 가능) 표시하고 설명에 조건을 적습니다.
• 구조화 출력: 이미 format=json 을 제공하는 5종(diagnose_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network·validate_egovframe_project)에 zod outputSchema 를 선언하고 structuredContent 를 함께 돌려줍니다(text 는 유지). 스키마는 src/*.ts 의 결과 인터페이스에서 도출하며 테스트가 실제 결과를 스키마로 검증합니다.
• 테스트 플랫폼 중립 가드: v0.30·v0.31 에서 두 번 연속 Windows gate 만 깨진 원인(테스트가 POSIX 경로·래퍼 이름을 가정)을 구조적으로 막습니다 — (a) resolveCommand·walk·경로 비교처럼 플랫폼 분기가 있는 함수는 platform 주입 옵션을 두고 테스트가 win32·linux 양쪽을 명시적으로 단언, (b) scripts/check-test-portability.mjs 가 test/*.mjs 에서 "./mvnw"·endsWith("/…")·path.sep 미정규화 path.relative 같은 패턴을 찾아 실패시키고 prepublishOnly 에 포함, (c) README 릴리스 절차 2단계에 "Windows 체크아웃에서 통과" 조건을 명문화.

범위 (제외): 도구 추가, 응답 본문 변경, SDK 메이저 업그레이드(1.x 유지)

검증 기준: test:handshake 가 27종 전부 title·annotations 존재와 읽기 전용 도구의 readOnlyHint 를 단언, 구조화 출력 5종은 structuredContent 가 outputSchema 를 통과(오프라인 픽스처), 이식성 검사 스크립트가 현재 테스트에서 0건, Windows gate 3개 통과

완료 정의: 도구 27종(변화 없음), deprecated API 사용 0건, 기획 전 조사한 Claude Desktop·VS Code 에서 읽기 전용 도구가 승인 없이 실행되는지 수동 확인 1회

결과(2026-10-02) — 완료: server.tool() 27회 → registerTool 27회(deprecated 0건), src/tool-meta.ts(title ko/en·annotations)와 src/output-schemas.ts(zod, 핵심 필드 엄격·그 외 passthrough) 추가, test:output-schemas 41단언·handshake 확장. 이식성 검사는 과거 두 번의 Windows 실패 줄을 모두 잡는 것을 확인했고, 현재 테스트에서 잠복해 있던 같은 유형 1건(test/dependencies.mjs 의 path.relative 비교)을 추가로 고쳤습니다. 의도된 POSIX 경로 12줄은 사유를 달아 허용했습니다. 클라이언트 수동 확인(읽기 전용 도구 자동 승인)은 npm 배포 뒤 저장소 소유자가 수행합니다.

v0.33.0 — migrate_egovframe_project 3단계: 검증 + 공통컴포넌트 대응표

목표: 2단계 적용 뒤 남는 일(컴파일 오류 고치기)을 사람이 처음부터 찾지 않게 합니다. "컴파일 오류 N건 중 M건은 수동 항목 K 때문" 을 연결한 작업 목록을 돌려주고, 3.x 공통컴포넌트 소스가 섞인 프로젝트에는 5.0.6 기준 대응표와 재조립 권고를 냅니다.

범위 (포함)

• migrate_egovframe_project(mode="verify")(또는 apply=true, verify=true): build_egovframe_project(goal="compile") 을 실행해 파일·라인 단위 오류를 받은 뒤, 각 오류를 (1) 같은 파일의 수동 항목 — 라인 근접·심볼 일치(cannot find symbol … Mapper ↔ class-removed Mapper→EgovMapper), (2) 규칙 카탈로그의 제거 클래스·제거 모듈 심볼, (3) 분류 불가 로 나누고, 수동 항목별로 "이 항목을 처리하면 해결될 오류" 수를 붙여 우선순위를 매깁니다. 빌드 도구가 없으면 verify 는 건너뛰고 이유를 적습니다.
• 공통컴포넌트 3.x→5.x 대응표: scripts/generate-migration-rules.mjs 에 egovframe-common-components 저장소(v3.10.0 ↔ v5.0.6)를 두 번째 근거로 추가해 egovframework.com.* 의 제거 클래스(조사 시점 58종, 예: cmm.util.EgovMybaitsUtil, sec.rnc.service.EgovSocketClient, ext.oauth.*)·추가 52종·이름 변경 4종을 packages.components 로 기록합니다. 진단은 사용자 소스가 제거 클래스를 참조하면 class-removed(manual) 로 보고합니다.
• 재조립 권고: 진단에서 diagnose_egovframe_project 가 감지한 공통컴포넌트 패키지가 3.x 소스(egovframework.rte import 또는 javax.servlet)이면 "add_egovframe_components 로 5.0.6 을 다시 조립하고 사용자 수정은 백업과 diff 로 옮기라" 는 항목을 컴포넌트 단위로 1건씩 내고, 2단계 적용은 그 디렉터리를 치환 대상에서 뺄 수 있는 옵션(skipComponents)을 둡니다.

범위 (제외): 컴파일 오류 자동 수정, 공통컴포넌트 소스의 3-way 병합(그건 upgrade_egovframe_project 가 매니페스트가 있을 때만 하는 일)

검증 기준: 픽스처(2단계 적용 후 제거 클래스를 참조하는 java 2개)로 verify 가 오류 ↔ 수동 항목을 정확히 연결, CI 통합에서 실제 mvn compile 오류 파싱 경로 통과, 규칙 정합 테스트가 공통컴포넌트 대응표의 목적지가 v5.0.6 트리에 있는지 검증, 공식 5.x 템플릿에서 verify 오류 0건

완료 정의: 도구 27종, test:migrate 에 verify 단언 추가, docs/design-migration.md 3단계 절, 규칙 카탈로그 schemaVersion 2(하위 호환 필드 유지)

결과(2026-10-02) — 완료: verify 는 apply·dryRun 과 같은 도구의 파라미터로 두었고(mode 문자열 대신), 연결은 심볼 일치 → 라인 근접 → 규칙 심볼 → 미분류 4단계입니다. 공통컴포넌트 대응표의 실제 수치는 제거 54·이동 4·추가 52(기획의 58 은 트리 비교에서 단순명 이동 4건을 빼기 전 값)이며, 생성기가 루트형(src/main/java/) 저장소도 읽도록 고쳤습니다. 큐레이션 대체는 EgovMybaitsUtil→EgovMybatisUtil(오타 정정) 1건입니다. CI 통합에서 실제 mvn compile 오류 3건이 수동 항목 2건에 전부 연결됐습니다.

v0.34.0 — 의존성 기준 완성 + 규칙 drift 감시

목표: check_egovframe_dependencies 의 unknown 을 줄이고, 동봉 규칙·기준이 upstream 과 어긋나면 사람이 알게 합니다.

범위 (포함)

• Spring Boot BOM 전체: 생성기가 spring-boot-starter-parent → spring-boot-dependencies pom 을 Maven Central 에서 받아 dependencyManagement(약 300 좌표)와 그 안의 BOM import 를 한 단계 더 풀어 catalog/dependency-baseline.json 에 managedBoot 로 넣습니다(계열 규칙은 유지). Boot parent 프로젝트의 버전 없는 의존성은 managed 에 기준 버전을 함께 보입니다.
• RTE 모듈 전이 의존성: egovframe-runtime v5.0.2 모듈 pom 18종의 <dependencies> 를 읽어 mybatis·mybatis-spring·poi·quartz 등 RTE 가 끌어오는 버전을 managedRte 로 기록하고, 프로젝트가 같은 좌표를 더 낮은 버전으로 명시하면 outdated(사유: RTE 전이 버전과 충돌 가능) 로 봅니다.
• drift 감시: sync_egovframe_templates 에 migrationRules·dependencyBaseline 절을 추가해 (1) egovframe-runtime 최신 태그가 규칙의 toTag 보다 새로운지, (2) parent 2종의 최신 버전이 기준 sources 보다 새로운지, (3) parent pom sha256 이 바뀌었는지를 보고합니다(파일은 고치지 않음). 변화가 있으면 README 의 갱신 절차를 결과에 붙입니다.
• check_egovframe_dependencies 결과에 "기준 출처"(parent 직접 / 계열 / Boot BOM / RTE 전이)를 항목마다 표시합니다.

범위 (제외): 자동 버전 올리기(파일 수정), 취약점 DB 동봉

검증 기준: 공식 5.x egovframe-boot-web 템플릿에서 unknown 0건, 공식 공통컴포넌트 v3.10.0 pom 에서 unknown 18 → 5 이하, drift 테스트는 네트워크(CI 통합)와 오프라인 모의 양쪽, 기준 카탈로그 생성이 재현 가능(sha256 고정)

완료 정의: 도구 27종, test:dependencies 확장, docs/design-dependency-check.md 갱신, 기준 파일 크기 200KB 이하 유지

결과(2026-10-03) — 완료: 기준 파일 schemaVersion 2 에 boot(spring-boot-dependencies 3.5.6 직접 362 + import 44종 → 1,473 좌표, 충돌 1건은 Maven 순서대로 직접 항목 유지)와 rteTransitive(모듈 18종 pom → 58 좌표, 버전·scope·via)를 넣었고 크기는 150KB 입니다. 기획과 달라진 점: (1) 표준프레임워크 저장소가 maven-metadata.xml·디렉터리 목록을 막아 두어 "최신 parent 버전" 대신 다음 patch 3개·minor·major 후보를 HEAD 로 탐침합니다 — 이 탐침이 기준(5.0.1)보다 새 parent 5.0.2 를 찾아 이번에 기준을 5.0.2 로 올렸습니다(차이는 RTE 버전뿐). (2) 태그 조회는 GitHub API 가 막히면 태그 페이지(HTML)로 대체합니다(GITHUB_TOKEN 이 있으면 API 에 씀). (3) 계열 규칙이 org.springframework.social·.ldap 까지 org.springframework 로 묶던 결함을 고쳐 groupId 정확 일치(jackson 만 하위 포함)로 좁히고 달력형 릴리스 트레인(spring-cloud-dependencies)은 계열에서 뺐습니다. (4) 공통컴포넌트 3.10 pom 의 unknown 17건 가운데 공개 기준이 있을 수 없는 국내 벤더·기관 배포 6건은 새 분류 vendor(사유 표시)로, EOL·이전 좌표 8건은 전환 규칙 libraries 에 교체 규칙을 추가해(migrate_egovframe_project 의 manual 항목으로도 나옵니다) 남은 unknown 은 xerces:xercesImpl 1건입니다. 검증: 공식 egovframe-boot-web·egovframe-web 템플릿 pom unknown 0, drift 테스트는 오프라인 주입 26단언 + CI 통합 실제 조회, 기준 생성은 --cache/--offline 으로 재현 가능(같은 입력 → 같은 파일).

이전 기획 (v0.29–v0.31, 완료)

v0.28.1 까지의 상태에서 다음 세 릴리스를 아래 순서로 진행합니다. 각 항목은 "완료 정의"를 만족해야 릴리스합니다. 기획 시점(2026-09-26)의 조사 근거는 맨 아래 "선행 조사 결과"에 있습니다. v0.29.0 은 2026-09-27 에 완료했으며 기획 원문은 기록으로 남기고 결과를 항목 아래에 적었습니다.

v0.29.0 — migrate_egovframe_project 第 1 阶段：迁移诊断（只读）— 已完成

结果（2026-09-27）：已满足所有完成定义 — 24 种工具，test:migrate 的 87 项断言和 test:migration-rules 的 579 项断言均通过；test:migration-rules-live 的 61 项检查确认 RTE 5.x、3.x 原始坐标、parent 和 Jakarta 坐标在实际仓库中存在；官方 5.x egovframe-web 和 egovframe-boot-web 模板中检测到 0 项；在官方 egovframe-common-components v3.10.0 的 pom、web.xml 和部分源码中检测到 57 项（auto 48 项、manual 9 项）；设计文档见 docs/design-migration.md。与原计划的不同之处：规则依据不是“5.x 模板 pom + 公共组件包树”，而是对比 egovframe-runtime 仓库的 3 个标签（v3.10.0、v4.3.0-Final、v5.0.2-Final）的源码树，从而以机械方式推导类级别的迁移和移除（38 种移除项必须说明整理原因），并同时涵盖 4.x 坐标（org.egovframe.rte:org.egovframe.rte.*）。

目标：逐文件、逐行报告将使用标准框架 3.x/4.x 构建的现有项目迁移到 5.x（Jakarta EE 9+、Spring 6）需要进行的更改。本阶段不会写入文件。诊断结果必须准确，才能让人信任第 2 阶段的自动应用，因此先发布诊断工具，并在实际项目中验证。

范围（包含）

• Maven 坐标：egovframework.rte:egovframework.rte.<layer>.<module> → org.egovframe.rte:egovframe-rte-<layer>-<module> 对照表、RTE 版本属性、仓库 URL（https://maven.egovframe.go.kr/maven/）是否存在、parent（org.egovframe.web:egovframe-web-config-parent、org.egovframe.boot:egovframe-boot-starter-parent）是否使用
• Java 源码和 XML：egovframework.rte.* import、bean class → org.egovframe.rte.*
• Jakarta 迁移：列出使用 javax.servlet、javax.servlet.jsp、javax.validation、javax.persistence、javax.annotation（仅 Spring 6 中发生变化的部分）的位置 → 使用 jakarta.*。排除 javax.sql、javax.xml 等 JDK 内置包
• JSP/TLD：web.xml 架构版本、JSTL 坐标（jakarta.servlet.jsp.jstl）
• 报告无法自动转换的项目：3.x 中已移除或更改的 RTE API（在对照表中标记为 manual）、Spring 4→6 中消失的类，以及需要替换的库，例如 commons-dbcp（1.x）、log4j 1.x

范围（排除）：修改文件、运行构建、更新公共组件源码本身的版本（这属于 upgrade_egovframe_project 的范围）

设计要点

• 规则以数据而非代码形式保存：catalog/migration-rules.json（schemaVersion 1）包含坐标对照表、包对照表、javax→jakarta 列表和手动处理项；生成脚本会对照官方仓库（5.x 模板 pom、egovframe-common-components 5.x 包树）核实依据。规则一致性测试（test:migration-rules）会验证对照表中的目标坐标和包是否存在于实际 5.x 资源中。
• 工具 migrate_egovframe_project(projectDir, target="5.x", format="json|markdown") 会复用 diagnose_egovframe_project 的扫描结果（构建工具、RTE 版本、已安装组件），并为每个项目返回 {file, line, kind, from, to, auto|manual, reason}。也提供 Markdown 摘要（采用 generate_egovframe_report 格式）。
• 允许的 root 和只读保证与现有工具一致。

验证标准

• 离线 fixture：使用混合了 3.10 风格 pom、egovframework.rte import、javax.servlet 用法和 XML bean 的项目，断言项目分类（auto/manual）、行位置和对应坐标
• 实际项目：以官方 5.x web-sample 为目标，确认“迁移项目 0 项”（无误报）
• 规则一致性：对照表中所有 to 坐标都存在于 https://maven.egovframe.go.kr/maven/ 或 Maven Central 元数据中（网络测试，CI）

完成定义：24 种工具；fixture 和规则一致性测试通过；设计文档 docs/design-migration.md（包含对照表来源、手动处理项依据和第 2 阶段计划）

v0.30.0 — 应用迁移 + 依赖检查

migrate_egovframe_project 第 2 阶段（应用）

• 仅应用第 1 阶段报告中的 auto 项：替换 pom 坐标、import 和 bean class，将 javax 替换为 jakarta。manual 项会原样保留在结果中，交由人工处理。
• dryRun 默认值为 true。应用时，通过 ProjectFileTransaction 将文件、备份（migration-backup/）和报告（migration-plan.json）作为一个事务统一提交；中途失败时恢复到操作前的状态。无论用户是否修改过原文件，都会备份原文件（遵循与升级工具相同的原则）。
• 应用后建议下一步执行 build_egovframe_project(goal=compile)，并在出现编译错误时关联显示 manual 项。
• 验证：转换夹具项目后，使用 JDK 17 执行 mvn compile 通过（CI 集成测试）；应用过程中进行故障注入回滚测试

check_egovframe_dependencies(projectDir, offline=true)

• 将项目的 RTE、Spring、公共组件和主要库版本与 catalog/dependency-baseline.json（从官方 5.x 模板提取的基准版本）对照，并分类为 outdated、unknown 和 ok。考虑到封闭网络环境，默认离线；只有在 offline=false 时才会通过 OSV（https://api.osv.dev）查询已知漏洞。
• 安全配置检查（原 security_patch_advisor）整合为此工具的 checks 项：仅判断 CSRF 过滤器、sec.security 组件是否安装、web.xml 中是否存在安全头过滤器等，并一并返回判定依据（文件和行号）。

完成定义：25 种工具；转换夹具后 mvn compile 通过；基准版本文件生成脚本及一致性测试

结果（2026-09-28）— 已完成：共 25 种工具。应用功能通过原样应用第 1 阶段为每个 auto 项添加的原文偏移编辑实现（test:migrate 132 项断言）；应用 3.10 坐标和 javax 夹具后，JDK 17 下 mvn compile 通过（test:migrate-integration）；在官方公共组件 v3.10.0 资产中应用 48 个 auto 项、共 86 处修改后，重新诊断确认 auto 为 0。依赖基准由 2 种官方 parent 的 pom 生成（scripts/generate-dependency-baseline.mjs，139 种受管坐标 + 7 种 BOM 系列），并通过 test:dependencies 的 68 项断言和 test:dependencies-live（OSV）验证。与计划不同之处：由于 parent 通过 BOM 管理 spring-*，因此增加了“系列基准”（groupId 前缀）概念；未收录 Spring Boot BOM 的完整列表，而是将其分类为 managed。Jakarta 迁移规则的目标版本已调整为不低于 parent 基准（jstl-api 3.0.2、jsp-api 4.0.0、validation-api 3.1.1、annotation-api 3.0.0、websocket-api 2.2.0）。

v0.31.0 — 运维便利性

• diagnose_egovframe_network：报告工具所用主机（codeload.github.com、raw.githubusercontent.com、media.githubusercontent.com、maven.egovframe.go.kr、registry.npmjs.org）的连通性、耗时和错误类型（DNS、超时、TLS、代理认证），并提供环境变量解决方案（HTTPS_PROXY+NODE_USE_ENV_PROXY=1、NODE_OPTIONS=--dns-result-order=ipv4first）。依据是 2026-09-21 在新笔记本上因连接 codeload.github.com 超时导致 test:templates 失败的经历。现有下载路径失败时，也会在错误消息中附上相同的解决方案。
• 英文 README 和工具说明的英文对照（响应语言保持韩语，考虑 EGOVFRAME_LANG=en 选项）
• MCP Registry 注册和 server.json 元数据；Homebrew tap 优先级较低
• generate_agents_md：根据项目诊断结果，为 AI 编码工具生成 AGENTS.md（构建和测试命令、已安装组件、禁止事项）

结果（2026-09-30）— 已完成：共 27 种工具。网络诊断实际探测 7 种主机（计划中的 5 种 + repo1.maven.org、api.osv.dev），并将失败分为 8 种；运行时会检测 Node 是否支持 --use-env-proxy，并给出 NODE_USE_ENV_PROXY=1 解决方案。现有下载路径（fetchWithTimeout）失败时，会在错误消息中附上一行相同的错误分类和解决方案。英文内容通过 README.en.md 和 EGOVFRAME_LANG=en 工具说明提供（涵盖全部 27 种工具，handshake 测试可防止遗漏），响应仍保持韩语。MCP Registry 已准备好 server.json、mcpName 及一致性测试；实际发布（mcp-publisher publish）由存储库所有者在 npm 发布后执行。Homebrew tap 仍保持较低优先级。

发布流程（v0.35+，每个版本通用）

1. 更新 main 后创建功能分支 → 应用补丁（git am）或直接提交。同步更新 package.json 和 server.json（两处）的版本，并在 README 更新历史中添加 - **X.Y.Z** — … 条目（test:release 会断言这三项）
2. 在本地通过 npm ci && npm run prepublishOnly（Windows 克隆无论 core.autocrlf 如何设置都必须通过）。测试预期值必须与平台无关——平台分支函数应注入 platform 并断言两种情况，且 npm run check:portability 的结果必须为 0 项
3. 推送 → PR → 7 项 CI（ubuntu·windows × Node 18/20/22 + integration）全部通过 → squash 合并。到这里就是人的工作。
4. 合并后，若 main 的 CI 成功，Release 工作流（.github/workflows/release.yml）会通过 scripts/release-check.mjs 检查前提条件（server.json 版本一致·更新历史条目），并检查远程状态（npm·标签·GitHub Release·MCP Registry），仅执行剩余步骤：npm（OIDC trusted publishing，自动附加 provenance）→ 为已发布的提交创建 vX.Y.Z 标签 → GitHub Release（scripts/release-notes.mjs）→ MCP Registry（GitHub OIDC）。如果条件不满足，则说明原因并成功结束（仅修改文档的合并不会发布任何内容）
5. 验证：查看 Actions 中的 Release 摘要（各步骤结果）、npm view egovframe-scaffold-mcp version、Releases 页面和 Registry 搜索结果。如果流程中断（例如 v0.36.1 的 npm 传播延迟、Registry 失败等），无需手动处理；后续 main 合并（或 Run workflow）触发的 Release 会接着执行——如果只有 npm 已完成，则会在 npm 记录的 gitHead 提交上创建标签，以确保包和标签指向相同代码（如果该提交不是 main 的祖先，则会提示手动打标签并停止）

紧急情况下的手动流程（无法使用工作流时）：在 main 上通过 node -p "require('./package.json').version" 确认版本后，在 main 提交上创建并推送标签 → npm publish → mcp-publisher publish。标签必须打在已合并的 main 提交上（v0.25.2·v0.28.0·v0.28.1·v0.30.0·v0.33.0 曾打错标签，因此实现了自动化）。

前期调查结果（2026-10-04）

• npm trusted publishing：于 2025-07-31 正式发布。需要 npm CLI 11.5.1+·Node 22.14+、工作流中的 permissions: id-token: write，以及在 npmjs.com 注册 trusted publisher（组织/用户·仓库·工作流文件名·可选 environment）。对于公开仓库和公开包，会自动附加 provenance（可通过 provenance=false 关闭）。不支持 self-hosted runner；workflow_call 可复用工作流会按调用工作流名称进行检查，因此使用单个 release.yml 文件。
• MCP Registry：通过 mcp-publisher login github-oidc 无需密钥即可登录（id-token: write）；io.github.<owner>/* 命名空间以 GitHub 账户所有权作为证明。二进制文件按 OS/ARCH 提供 tar.gz，下载地址为 github.com/modelcontextprotocol/registry/releases。npm 中带有 mcpName 的包必须先发布，因此在 npm 步骤之后运行。仓库目前的搜索结果为 0 项。
• 已解析的依赖项：对官方 egovframe-web 模板 pom（仅填入占位符）运行 maven-dependency-plugin:3.8.1:list -DincludeScope=runtime → 67 个 artifact；运行 cyclonedx-maven-plugin:2.9.3:makeBom -DschemaVersion=1.6 → 不更改 pom，生成 186KB JSON，包含 69 个 component（包括 purl·MD5/SHA 哈希值·许可证）。使用 v0.34 分类器评估解析后的集合，parent 直接依赖 23 个·同系列 13 个·RTE 传递依赖 9 个·Boot BOM 4 个均为 ok；低于基准 11 个（RTE 5.0.0 有 7 个 + Boot BOM 有 4 个）；无基准 9 个（commons-collections 3·commons-logging·antlr 运行时等）；附带 OSV 建议的 component 有 8 个（spring-webmvc/-core/-web/-webflux/-expression 6.2.11、log4j-core/-api 2.25.3、commons-configuration2 2.11.0）。这与仅检查声明时的结果（0 项需处理）大不相同。插件最新版本：maven-dependency-plugin 3.11.0、cyclonedx-maven-plugin 2.9.3、cyclonedx-gradle-plugin 3.4.1（固定为已验证的版本）。
• SBOM 政策：韩国科学技术信息通信部·国家情报院的软件供应链安全路线图（2026-06）规划了分阶段要求：自 2027 年起，公共机构需在综合管理体系中登记所引入软件的 SBOM 并持续检查供应链风险；公共 IT 项目需提交 SBOM 和漏洞应对流程（未指定 SPDX/CycloneDX 格式——默认使用 CycloneDX 1.6 JSON，SPDX 则通过转换支持）。
• 4.x 资产：egovframe-common-components 的 v4.3.2 是 4.x 的最后一个标签（1,295 个 java 文件，70 个依赖项）。对 pom 执行当前诊断会发现 9 个 4.x 坐标·8 个 Jakarta·8 个库·1 个已移除模块（auto 19·manual 11）；依赖项检查中，project:* groupId 的 10 个 system scope 本地 jar（ojdbc6·altibase·tibero5·cubrid·goldilocks8·smeapi·gpki 2·onepass）和 javax.faces:javax.faces-api 仍为 unknown，是 v0.36 回溯检查和 v0.37 语料的首批修复对象。
• 发布事故记录（背景）：v0.30.0 标签指向合并前的提交（已修复）；v0.33.0 标签指向本地 main 提交（已修复）；0.32.0·0.33.0 未发布到 npm（0.33.0 因 Windows 门禁缺陷而有意跳过）；#33·#36 在 Windows 门禁失败的情况下合并。上述情况均发生在手动流程阶段。

前期调研结果（2026-10-02）

• 在安装的 @modelcontextprotocol/sdk 版本 1.29.0（最新版本为 1.31.0）中，McpServer.tool() 已弃用，registerTool() 接受 title、inputSchema、outputSchema、annotations（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）。当前服务调用了 tool() 27 次，未使用 annotations 和 outputSchema。
• egovframe-common-components 的最新版本为 v5.0.6（与目录一致），src/main/java 中的类数量从 v3.10.0 的 1,095 个变为 v5.0.6 的 1,089 个，删除 58 个、新增 52 个，按简单类名计有 4 个名称变更。包结构（egovframework.com.<domain>）保持不变，因此映射表规模较小。
• egovframe-runtime 的最新标签为 v5.0.2-Final（与规则目录一致），官方 parent 的 web 和 boot 版本均为 5.0.1，与基准目录一致——截至 2026-10-02 无漂移。
• 在 MCP Registry 中搜索 io.github.EricSeokgon/egovframe-scaffold-mcp，结果为 0 条，尚未发布。

前期调研结果（2026-09-26）

• 官方模板已是 5.x：egovframe-web-sample 使用 org.egovframe.web:egovframe-web-config-parent:5.0.1，egovframe-template-simple-backend 使用 org.egovframe.boot:egovframe-boot-starter-parent:5.0.1（项目版本为 5.0.2，Java 17）。依赖项为 jakarta.servlet、jakarta.validation、jakarta.json，部分库使用 jakarta classifier。因此，迁移工具的目标版本定为 5.x（Jakarta），而不是“4.x”。
• 5.x 运行时环境的坐标为 org.egovframe.rte:egovframe-rte-<layer>-<module>（例如：egovframe-rte-ptl-mvc、egovframe-rte-psl-dataaccess、egovframe-rte-fdl-idgnr、egovframe-rte-fdl-property），仓库有 Maven Central 和 https://maven.egovframe.go.kr/maven/ 两处。3.x 使用的 egovframework.rte:egovframework.rte.<layer>.<module> 命名规则不同，因此需要映射表。
• egovframe-docs 仓库中没有 3.x→4.x/5.x 迁移指南文档（截至 2026-09-26）。映射表必须从官方 5.x pom 和 egovframe-common-components 5.x 包树中推导，并将推导脚本和依据记录在 docs/design-migration.md 中。
• diagnose_egovframe_project 根据 pom 字符串模式推测 RTE 版本。迁移诊断会在此基础上增加基于坐标的判断（存在 egovframework.rte groupId 表示 3.x 系列），以提高准确度。
• 从 Initializr upstream 发现的 3 个问题（参见 v0.28.0 变更历史）可作为单独提交 issue 的候选项。

路线图依据：

• egovframe-development 中包含官方 CRUD 向导输入和两个模板树；MCP 使用相同的输入体系，可使 IDE 与对话式工具的体验保持一致。
• egovframe-vscode-initializr 已有可机读的项目和 context XML 目录；与其创建新列表，不如将其提升为通用架构，这样更利于维护。
• 对 egovframe-common-components v5.0.6 的分析表明，实际运行还需要源代码、Mapper、JSP 以外的资源、配置、按功能划分的依赖项以及安全补丁跟踪。

详细规划和调研依据由 egovframe-contribution-notes 的 v0.20+ 路线图维护。

同时改进开发基础设施：确保 GitHub Actions 与 prepublishOnly 的完整测试保持一致，基于 lockfile 实现可复现安装，并加强对 Windows、韩文路径和大型 zip 的验证。原本为单文件的 src/index.ts（约 3,200 行）已拆分为 14 个按领域划分的模块（公开 export 和 MCP 协议表面保持不变）；index.ts 仅负责入口和重新导出公开 API。

变更历史

• 0.43.0 — CI·提交格式多样化：GitLab·Jenkins、SPDX（工具数量保持 32 种）。（1）为 generate_egovframe_ci 添加 platform="github"|"gitlab"|"jenkins"：src/ci-config.ts — generateGitlabCi（.gitlab-ci.yml、maven:3.9-eclipse-temurin-<JDK>·eclipse-temurin:<JDK> 镜像、本地仓库缓存、JUnit 报告，supply-chain job 使用 needs: []·Node 准备·artifacts:reports:cyclonedx）·generateJenkinsfile（Declarative — options·environment·Build/SBOM/SBOM check/Assessment 阶段·post { always { archiveArtifacts } }，通过 isUnix() 选择 sh/bat），三个平台共用的门禁命令 supplyChainCommands（sbom → sbom-check --fail-on minimum（也添加到 GitHub 门禁）→ assess），新增参数 supplier（SBOM 供应方）·npmRegistry（NPM_CONFIG_REGISTRY）·offlineBundle（EGOVFRAME_OFFLINE_BUNDLE）——全部通过格式限制阻止注入配置文件；缺少供应方线索时会预告门禁失败（notes）。（2）SPDX 2.3：src/spdx.ts — cdxToSpdx（包·DESCRIBES·DEPENDS_ON（无依赖时为 NONE）·purl/cpe/swid externalRefs·supplier/originator·creators·created·校验和·声明的许可证（LicenseRef- + hasExtractedLicensingInfos）·OSV 建议 SECURITY/advisory·egovframe:* annotations，以 serialNumber UUID 作为确定性 namespace）·spdxToCdx（用于检查，反转 *_DEPENDENCY_OF·NOASSERTION 表示未知）。generate_egovframe_sbom(bomFormat="spdx-json")（默认路径 sbom/bom.spdx.json，通过重新读取 SPDX 判断最小要素），check_egovframe_sbom 自动识别 CycloneDX·SPDX 2.x（document.format，格式不同的 baseline 按 purl 比较，拒绝 SPDX 的 vex=true）。CLI sbom --bom-format spdx-json。（3）测试：新增 test:spdx，含 43 项断言（门禁、固定官方 spdx-spec v2.3 schema）；test:ci 中加入 GitLab 官方 CI schema（固定 gitlab v19.4.1-ee，devDependency yaml）·Jenkinsfile 结构·注入拒绝；test:sbom-live（CI 集成）检查实际 Maven SBOM 的 SPDX schema·判定一致性；更新 test:sbom-check 中拒绝非 CycloneDX 的断言，以适配 SPDX 3.0 等。（4）CI：integration job 中 Maven 遇到远程仓库 5xx（如 502）时，以 3 秒间隔最多重试 5 次（#53）。（5）generate_egovframe_sbom：如果 cyclonedx-maven-plugin 输出中没有 metadata.timestamp（CI runner 实测如此），则填入生成时间并发出提示——这是 v0.40 之后 sbom-live 最小要素检查间歇性失败的原因。server.json 0.43.0。

• 0.42.0 — 闭网离线包（工具数量从 31 增至 32 种）。（1）新增工具 prepare_egovframe_offline_bundle(outputDir, include=["osv","components","templates","origin"], templates?, dryRun=true, format)：src/offline-bundle.ts·src/offline-bundle-plan.ts — 将 OSV Maven 全量转储（osv-vulnerabilities/Maven/all.zip，记录数量·源数据更新时间）、固定目录提交的公共组件归档（验证 sha256·大小）、模板（默认：带固定指纹的 12 种 Initializr zip；指定时使用仓库模板的 codeload zip）、所有官方公共组件标签的完整 bare 镜像（git fetch --depth 1 +refs/tags/*）下载到临时目录，并与 bundle-manifest.json（schemaVersion 1，逐文件记录 path·kind·url·sha256·bytes·fetchedAt）一起移动到新建（或空）目录；固定指纹不匹配或失败时不留痕迹。工具元数据标记为不读取·非破坏性·openWorld，outputSchema（11 种），英文说明，AGENTS.md 工具列表。（2）EGOVFRAME_OFFLINE_BUNDLE：fetchWithTimeout（GET）和目录归档下载如果请求的 URL 与 manifest 中相同，则验证指纹后从离线包返回（拒绝篡改，每个进程验证一次）；defaultOsvQuery 使用本地转储进行判定（buildOsvIndex·queryOsvIndex·inOsvRange·compareMavenVersions — Maven ComparableVersion 的核心逻辑，支持 versions 列表或 ECOSYSTEM 范围，排除已撤销条目）；GitOriginSource 使用离线包镜像（for-each-ref 标签列表，不执行远程 fetch，提示缺失标签）；使用 OSV 的结果（依赖检查·SBOM 生成·SBOM 检查）附带快照基准日期说明和 30 天警告（EGOVFRAME_BUNDLE_MAX_AGE_DAYS）。（3）diagnose_egovframe_network 在失败时提供离线包解决方案（bash·cmd·PowerShell）并显示正在使用离线包；CLI bundle（仅通过 --write 接收，--output-dir 基于当前目录），server.json 环境变量 EGOVFRAME_OFFLINE_BUNDLE（4 种）。（4）测试：新增 test:offline-bundle，含 30 项断言（门禁）·test:bundle-live（CI 集成：实际离线包、本地 OSV = 在线、在阻止 fetch 的状态下进行生成·组装·重新组装·SBOM 重新检查），registry 环境变量 4 种，output-schemas·handshake 32 种·11 种，cli 命令 10 种。设计：docs/design-offline-bundle.md。（5）运行时依赖 handlebars 从 4.7.9 升级至 4.7.10（GHSA-xw65-4hp5-5hc7·GHSA-8r5x-fm3f-whwj·GHSA-p8wg-vrv2-v86f，npm audit --omit=dev 门禁）。server.json 0.42.0。

• 0.41.0 — 转换演练（工具数量从 30 增至 31 种）。（1）新增工具 rehearse_egovframe_migration(projectDir, steps=["reassemble","migrate","verify","align-pom"], components?, sourceTag="auto", keepWorkspace=false, timeoutMs=900000, topN=20, format)：src/rehearse.ts — 在副本（EGOVFRAME_CACHE_DIR/rehearsal，排除构建产物·VCS·备份；如果工作目录位于项目内则拒绝）中执行重新组装 → 应用转换 → 编译（Maven 使用 -Dmaven.compiler.fork=true·JDK_JAVAC_OPTIONS=-Xmaxerrs 100000）→ alignPomToReference（以官方公共组件固定标签 pom 为基准：添加·替换 parent，添加缺失坐标（排除 test），对齐版本·scope，删除项目中 parent 已定义的属性重定义，排除注释·dependencyManagement·plugin·profiles，幂等）→ 编译。analyzeErrors（缺失包——通过 "package X does not exist"·symbol 的 package·文件 import 语句查找类型的包；级联——同一文件·声明了缺失包中类型的文件所引用的成员·Lombok 生成的成员；其他；级联错误归属于文件中的第一个缺失包，候选坐标 packageHint，其他错误作为手动事项并关联规则，上级目录·文件），任务列表（pom 对齐消除的错误数 → 缺失包 → 文件），pom 补丁（上限 400 行），通过执行前后指纹（fingerprintTree）确认原件不变，步骤失败时记录并继续，将最近结果保存到 rehearsal/records/<路径哈希>.json。工具元数据标记为不读取·非破坏性·幂等·openWorld，outputSchema（10 种），英文说明，AGENTS.md 工具列表。（2）评估报告第 6 节加入最近一次实测演练（与评级公式无关），结语中的重新组装说明修正为先使用 reassemble_egovframe_components，再应用转换。（3）CLI rehearse（指标 errors·automation·aligned·files·unlinked·failedSteps）。（4）修复：parseBuildErrors 将 Maven [WARNING]·javac lint 警告（如 [removal]）行误计为错误的问题和 fork 格式的 error: 前缀问题；将 4.x 的 org.egovframe.rte 坐标（版本 4.*）误分为 5.x 系列的问题（导致重新组装候选标签仅限于 5.x）。runBuild(extraArgs, env)·ResolvedCommand.env，pom 中没有源代码编码时，演练编译使用 UTF-8。（5）测试：新增 test:rehearse，含 42 项断言（门禁）·test:rehearse-live（CI 集成：以官方 v4.3.2 整棵树为实际对象进行演练，预期值为 catalog/migration-corpus.json 中的 rehearsal），test:output-schemas 54 项·handshake outputSchema 10 种·test:cli 命令 9 种。设计：docs/design-migration.md 的演练章节。server.json 0.41.0。

• 0.40.0 — SBOM 运营：最小要素·比较·VEX（工具数量从 29 增至 30 种）。（1）新增工具 check_egovframe_sbom(projectDir, sbomPath="sbom/bom.cdx.json", baselinePath?, offline=true, vex=false, vexPath="sbom/vex.cdx.json", dryRun=false, format)：src/sbom-check.ts — 对包含根 component 在内的每个 component 逐一检查 7 种最小要素（catalog/sbom-rules.json：供应方·组件名·版本·唯一标识符·依赖关系·作者·生成时间，来源为 NTIA 2021·软件供应链安全指南 1.0），报告 ready/needs-work·缺失的 component（最多 20 个）·提示；仅凭 purl 使用 v0.34 分类器重新判定（可能不同于 SBOM 的 egovframe:status），并重新查询 OSV（newIds·goneIds；SBOM 中没有记录时标为“未记录”）；通过 baselinePath 比较（按 groupId:artifactId 统计新增·移除·版本·判定变化·新增/消失的漏洞）；vex=true 时生成 CycloneDX VEX（analysis.state=in_triage，affects 使用 BOM-Link urn:cdx:<serial>/<version>#<bom-ref>，没有 serial 时使用 bom-ref）——保留现有 VEX 判定·自定义字段，为 in_triage 条目添加 affects；对已完成判定的 ID 的新增影响单独添加条目，不删除未检测到的 ID，而是标记为 notDetected；没有变化时保持文件不变，损坏的 VEX 会中止操作。SBOM 不作修改，仅通过 transaction 写入 VEX。工具元数据标记为不读取·非破坏性·openWorld，outputSchema（9 种），英文说明，AGENTS.md 工具列表。（2）generate_egovframe_sbom(supplier, author, componentName, componentVersion, fillSuppliers)：metadata.supplier·根 component 的 supplier·metadata.authors（默认 pom <organization><name>）、metadata.lifecycles（build），以供应方映射表补齐缺少供应方的 component（egovframe:supplierBasis=catalog），响应中的 minimum 摘要。重新运行 enrichBom 时，仅更新 egovframe:status·basis·baseline，保留其他 egovframe:*。（3）评估报告第 5 节加入最小要素判定·VEX 条目/状态/最后检查时间。（4）CLI sbom-check（指标 minimum·gaps·changed·vulnerabilities·newVulns·added·removed·versionChanged·diffVulns·triage，--write → VEX，禁止直接指定 --vex）。（5）测试：新增 test:sbom-check，含 54 项断言（门禁、固定实际插件输出·通过 CycloneDX 1.6.1 官方 schema 验证——devDependencies ajv·ajv-formats）；test:sbom 41 项·test:cli 36 项·test:assessment 57 项·test:output-schemas 53 项断言，handshake outputSchema 9 种，test:sbom-live 检查实际 SBOM 最小要素·增强·比较·OSV VEX·判定保留。设计：docs/design-dependency-check.md 的 SBOM 运营章节。server.json 0.40.0。

• 0.39.0 — CLI 模式 + CI 供应链门禁（工具数量保持 29 种）。（0）upstream 在 2026-10-07 将 v5.0.7 标签从 3756ab2 移至 7912e13（新增修改 README·权限组·书签菜单控制器·菜单移动 JSP 的 3 个文件），导致目录固定验证失败，因此将组件目录（归档 sha256 a1a4b9a7…、46,904,430 bytes、6,604 files）和转换规则的 components.toCommit 重新固定到新提交（判定·语料库预期值无变化）。（1）src/cli.ts：npx egovframe-scaffold-mcp <assess|check|sbom|migrate|validate|diagnose|network> [选项]——不带参数时仍启动原有 stdio 服务（index.ts 分支）；命令由同一进程中通过 InMemoryTransport 连接到服务的客户端调用 tools/call（输入验证·允许的 root·outputSchema 验证方式相同）。选项使用工具参数名称（kebab-case，通过 tools/list JSON Schema 转换类型），通用选项 --project·--json（structuredContent）·--out·--step-summary·--fail-on·--write，禁止写入选项（如 migrate --apply·sbom --dry-run）。--fail-on 表达式（metric·metric>N·metric>=N·grade:C，按命令区分指标），退出代码 0/2/3/64，正文输出到 stdout·单行摘要输出到 stderr，支持 --help·--version。（2）generate_egovframe_ci(supplyChain, failOn="supplyChain:D", osv=true)：SBOM → 评估报告（--step-summary）→ 产物（if: always()）门禁 job，固定包版本，限制 failOn 格式（CI_FAIL_ON_RE，阻止 YAML 注入）。（3）@modelcontextprotocol/sdk 从 1.29 升级至 1.32.1。（4）测试：新增 test:cli，含 32 项断言（门禁）；test:ci 加入供应链门禁·注入拒绝；CI 集成中使用 actionlint 1.7.7 检查生成的 workflow，并对语料库树执行 CLI 评估报告（job 摘要）。设计：docs/design-cli.md。server.json 0.39.0。

• 0.38.0 — 执行公共组件重新组装（工具数量从 28 增至 29 种）。（1）新增工具 reassemble_egovframe_components(projectDir, components?, sourceTag="auto", database?, dryRun=true, verify=false, timeoutMs, format)：src/component-origin.ts（官方 egovframe-common-components 的无 blob bare 镜像 GitOriginSource——按标签执行 --depth 1 --filter=blob:none fetch·ls-tree·延迟 cat-file，测试用 MemoryOriginSource，gitBlobId·CRLF 规范化 blobIdsOf，缓存 EGOVFRAME_CACHE_DIR）和 src/reassemble.ts（选择目标组件——拒绝检测到的组件·展开组·由 manifest 管理的组件，采用最长前缀进行归属判定，按坐标系列对候选标签评分·同分时选较高版本·较短名称，8 种判定和 5 种处理，验证目标内容的 blob，通过一个 transaction 执行替换·添加·删除·备份·资产参考副本·补丁·SQL·manifest·reassemble-plan.json，将 verify 编译错误关联到任务列表，Markdown·outputSchema）。工具元数据标记为 destructive·openWorld（5 种），英文说明，server.json 环境变量 EGOVFRAME_CACHE_DIR。ProjectFileTransaction.removeFile（rollback 时恢复），拆分 buildComponentSqlPlan（组装·重新组装共用）。（2）公共组件 v5.0.7：组件目录（通过 generate-catalog.mjs --archive-sha256/--archive-bytes 固定 codeload 归档指纹，sha256 44a518c1…、46,903,152 bytes、6,604 files），转换规则 components.toTag v5.0.7（移除 55·移动 4），migrate_egovframe_project 的重新组装建议会指向新工具。（3）修复：upgrade_egovframe_project 未将组件资产文件（消息·IDGN·Web 资产等）纳入 upstream 比较，导致全部被报告为 "removed" 的缺陷；sync_egovframe_catalog 的 GitHub API 调用遇到过期 token（401）时改为使用未认证方式重试。也在此版本记录了 0.37.0 发布前进入 main 的 CI 修复（目录验证的 GitHub API 认证、proxy-addr 2.0.8、drift 监控不阻塞·探测重试）。（4）测试：新增 test:reassemble，含 46 项断言（门禁）·test:reassemble-live（CI 集成）；test:migrate-corpus 加入官方树重新组装预览（原件 100%·用户修改 0）；output-schemas·handshake 29 种·outputSchema 8 种·destructive 5 种，registry 环境变量 3 种。设计：docs/design-migration.md 的重新组装章节。server.json 0.38.0。

• 0.37.0 — 转换就绪度评估报告 + 回归语料库（工具数量保持 28 种）。（1）generate_egovframe_report(sections=["components"|"assessment"], resolve, resolveScope, resolveTimeoutMs, offline, sbomPath, topN, outputPath, dryRun, format)：assessment 一次性运行 diagnoseProject·migrateProject·checkDependencies（含安全检查）·SBOM 文件检查，生成 (1) 概述 (2) 转换范围——按类型分类的表、建议重新组装的组件、已移除 API 引用数、按（类型、目标）分组的预期手动工作量前 N 项 (3) 依赖——判定汇总、操作列表（一行操作说明）、解读摘要、OSV 漏洞、vendor·无基准提示 (4) 安全配置检查 (5) SBOM 摘要 (6) 评级及依据——转换难度（手动事项·需重新组装的组件·已移除 API 引用·坐标系列）与供应链状态（低于基准·转换/替换·漏洞·安全配置缺失·parent/Java），按因素区间评分累加，A=0·B≤3·C≤7·D>7，并在报告中打印完整公式；将未查询漏洞·解析失败标记为注意事项。format=json 使用 outputSchema（从 structuredContent 中排除 Markdown），outputPath 仅接受项目内的新 .md 文件（拒绝现有文件·..·绝对路径·脱离 symlink，使用 transaction，支持 dryRun）。默认 sections=["components"] 的正文与 v0.16 报告相同。工具元数据：移除只读提示（14 种 → 13 种，可创建文件·进行网络访问），非破坏性，ko/en title·英文说明。新增模块 src/assessment.ts（MIGRATION_RUBRIC·SUPPLY_CHAIN_RUBRIC·computeGrade·assessProject·renderAssessmentMarkdown）·src/report.ts（generateProjectReport），resolveOutputPath 供 SBOM·报告共用。（2）回归语料库：catalog/migration-corpus.json（官方 egovframe-common-components v3.10.0 aaebaa5·v4.3.2 bfa2ef5，include 5 个路径，tolerance 1%）、scripts/corpus-lib.mjs（sparse 部分克隆·提交验证·缓存标记·测量·比较）·scripts/generate-migration-corpus.mjs（--check）·test/migrate-corpus.mjs（20 项断言，CI 集成 + actions/cache）。预期值：3.10.0 条目 2,315（自动 1,507·手动 808，重新组装 159，依赖 66）·4.3.2 条目 1,352（自动 635·手动 717，重新组装 155，依赖 70）；两代均有待确认类 0·无基准 xerces:xercesImpl 1·评级 D/D。语料库未暴露新缺陷。（3）恢复发布：scripts/release-check.mjs 检查 npm 发布状态·npm gitHead·标签·GitHub Release·MCP Registry 版本，选择剩余步骤（mode=full|resume|none，逐步输出）；release.yml 使用分步 if 和摘要，并将等待 npm 传播的时间从 2 分钟延长至 10 分钟，仅发出警告（v0.36.1 Release #3 曾因传播延迟跳过标签·Release·Registry，重跑也停止）。test:release 断言从 33 项增至 44 项。（4）测试：新增 test:assessment，含 55 项断言（门禁）；test:output-schemas 从 42 项增至 47 项（报告 schema·未声明键）；handshake outputSchema 7 种·readOnly 13 种；test:dependencies-live 加入官方 5.x 模板转换 A 级断言。设计：docs/design-assessment-report.md。server.json 0.37.0。

• 0.36.1 — 修复首次自动发布（Release #2）在 npm 发布步骤的 prepublishOnly 中被 test:release 卡住的问题（0.36.0 未发布到 npm，因此跳过）。原因是 workflow 安装了 npm@latest，导致安装 npm 12；而 npm 12 的 npm pack --json 返回的是以包名为键的对象，而非数组，tarball 检查因此读取了 undefined。test/release.mjs 现在可读取两种格式（以及前置警告行）（parsePackJson），不会向嵌套 npm 调用传递父进程的 npm_config_*·lifecycle 环境，失败时会报告退出代码和输出的前 300 个字符（已使用 npm 10·12 验证）。release.yml 固定 npm 版本为 11（满足 trusted publishing 要求 ≥ 11.5.1，阻止主版本变更），CI 的 setup-java 升级至 v5。功能无变化。

• 0.36.0 — 已解析依赖树 + SBOM（工具数量从 27 增至 28 种，兼容现有参数）。（1）src/dependency-tree.ts：解析 Maven org.apache.maven.plugins:maven-dependency-plugin:3.8.1:tree -DoutputType=text -DoutputFile … -DappendOutput=true（不修改 pom，多模块项目按根目录逐个拼接；runtime 时使用 -Dscope=runtime）和 Gradle dependencies --configuration runtimeClasspath|testRuntimeClasspath -q --console=plain 的输出，获取每个 artifact 的深度·树路径（via）·scope·请求版本与解析版本（a:b:1.0 -> 1.2），相同坐标只保留路径最浅的一个（排除 project :x·(c)·(n)，排除根坐标）。执行时沿用 build_egovframe_project 的 Runner（超时·终止进程树·检测 mvnw/gradlew wrapper）。（2）check_egovframe_dependencies(resolve, resolveScope, resolveTimeoutMs)：将声明中没有的 artifact 作为 origin: "transitive" 条目（构建文件·行号 0·via·depth）加入，并使用 v0.34 分类器判定；声明坐标记录 treeVersion 和 resolution.differs（就近声明优先的结果）；如果 parent 管理的坐标解析到低于基准的版本，则在备注中提示。提供 resolution 摘要（artifact·直接·传递·判定汇总·命令·耗时）；OSV 查询也包含传递依赖，解析失败·超时则在基于声明的结果中附上原因。Markdown 加入解析摘要·差异·传递路径列，扩展 outputSchema。（3）新增工具 generate_egovframe_sbom(projectDir, outputPath="sbom/bom.cdx.json", bomFormat="cyclonedx-json", scope, enrich=true, offline=true, overwrite=false, dryRun=true, timeoutMs)：Maven 使用 org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom（JSON·schema 1.6·按 scope 决定 includeTestScope/ProvidedScope），输出到临时目录，保留哈希·许可证；Gradle 使用已解析的依赖树，由本服务构建 CycloneDX 1.6 文档（purl=bom-ref，根坐标取自 settings.gradle·build.gradle，依赖图 dependencies[]）。enrich 为每个 component 添加 egovframe:status·egovframe:basis·egovframe:baseline properties（重跑时更新，保留其他属性）；offline=false 时将 OSV 结果写入 vulnerabilities[]（按 ID 排序，相同 ID 合并到 affects 中，source 为 OSV），失败仅记入 osvError。输出仅接受项目内相对路径（拒绝 ..·绝对路径·驱动器路径·脱离 symlink），除非 overwrite=true，否则拒绝覆盖现有文件；通过 transaction 写入，dryRun 仅返回命令·路径，不执行命令。工具元数据（ko/en title，非破坏性·openWorld，outputSchema+structuredContent——由于文档正文写入文件，因此不包含在响应中），英文说明。（4）追溯更新规则：在 vendorCoordinates 中加入 project（system scope 本地 jar）·com.goldilocks，并加入 Jakarta artifact 映射 javax.faces:javax.faces-api → jakarta.faces:jakarta.faces-api:4.1.2。公共组件 4.3.2 pom 中无基准条目从 11 项降至 1 项。（5）将 workflow 中的 actions/checkout·setup-node 升级至 v5（解决 Node 20 deprecated 警告）。测试：test:dependencies 断言从 104 项增至 129 项（解析器·命令·伪 runner resolve·失败·超时·Gradle），新增 test:sbom，含 37 项断言（门禁）·test:sbom-live（CI 集成：官方 web 模板实际 Maven 解析 ≥60·SBOM ≥60 个 component·OSV 漏洞·Gradle 样例），更新 test:output-schemas·handshake 以支持 28 种工具·6 种 outputSchema，test:migration-rules 632 项。设计：docs/design-dependency-check.md 的解析·SBOM 章节。server.json 0.36.0。

• 0.35.0 — 发布自动化（发布供应链；工具数量保持 27 种，服务行为无变化）。（1）.github/workflows/release.yml：在 main 分支上的 CI workflow 成功后（workflow_run，也可手动 workflow_dispatch），scripts/release-check.mjs 使用 package.json 版本检查四个条件——server.json 两个 version 一致、README 变更历史中存在对应条目、远程不存在 vX.Y.Z 标签、npm 中不存在该版本——全部满足时才发布（否则说明原因并成功退出）。发布顺序为 mcp-publisher validate → npm publish --access public（npm trusted publishing：OIDC·无 token·公开包自动提供 provenance；Node 22·最新 npm）→ 确认 npm 已更新（重试）→ 在经过验证的 main 提交上创建并推送注释标签 → 使用 scripts/release-notes.mjs 从变更历史条目生成正文（编号段落·安装代码片段·验证说明）的 GitHub Release → mcp-publisher login github-oidc && mcp-publisher publish（即使失败也保留 release，仅发出警告）。前置条件是在 npmjs.com 注册一次 trusted publisher（release.yml）。（2）通过 mcp-publisher validate 发现 server.json 的 description 超过 MCP Registry 100 字符的上限，会导致首次注册失败，因此将其缩减至 98 字符，并在 test:registry 中加入不超过 100 字符的断言。CI 集成 job 加入 mcp-publisher validate 步骤。（3）新增 test:release（门禁，32 项断言）：判定函数（逐条件拒绝·累积原因）、变更历史条目提取·发布说明渲染、当前版本条目存在性、npm pack --dry-run 的 tarball 内容（包含 dist·catalog·配置模板·README·LICENSE，排除 test·scripts·src·.github·source map，压缩后上限 600KB·解压后上限 2MB）。脚本 release:check·release:notes。README 发布步骤改为“合并 PR 是人的工作”，并保留手动流程以备紧急使用。server.json 0.35.0。

• 0.34.0 — 完善依赖基准 + 规则·基准 drift 监控（工具数量保持 27 种，兼容现有参数）。（1）catalog/dependency-baseline.json schemaVersion 2：生成器从 Maven Central 下载与 Boot parent 父级相同版本的 spring-boot-dependencies，将直接条目和 44 种 BOM import 展开一层，写入 boot.managed（1,473 个坐标，按 Maven 解析顺序优先采用直接条目）；将 egovframe-runtime 模块 pom 18 种（+root）的非 test·非 optional 依赖写入 rteTransitive.managed（58 个坐标，记录版本·scope·引入模块）。所有 pom 均固定 url·sha256，支持通过 --cache/--offline 重现，文件大小 150KB。将基准 parent 升级至 5.0.2（与 5.0.1 的差异仅为 RTE 版本）。（2）check_egovframe_dependencies：按 parent 直接依赖 → 系列 →（使用 Boot parent 时）Boot BOM → RTE 传递依赖 /（其他情况）RTE 传递依赖 → Boot BOM 的顺序进行比对；每个条目标记 basis（parent·family·boot-bom·rte-transitive·migration-rules），Markdown 加入来源汇总·来源列。若显式指定的版本低于 RTE 传递依赖版本，则标记为低于基准，并说明可能存在冲突。对于使用 Boot parent 的项目，无版本依赖同时显示 Boot BOM 基准版本。新增 vendor 分类（国内 DBMS·GPKI·mGov 等供应商·机构分发的坐标，使用 catalog/migration-mapping.json 中的 vendorCoordinates，并显示原因）。将系列规则缩小为精确匹配 groupId（仅 jackson 包含子 groupId），修复将 org.springframework.social 等独立项目误判为 Spring 系列的问题；将日历版本发布列车（spring-cloud-dependencies 2025.0.0）从系列规则中排除，记录在 releaseTrains 中。（3）在转换规则 libraries 中加入 8 条 EOL·旧坐标替换规则——mysql:mysql-connector-java→com.mysql:mysql-connector-j、ojdbc:ojdbc→com.oracle.database.jdbc:ojdbc11、org.codehaus.jackson:*（Jackson 1）、xmlbeans:xbean、net.sf.ehcache:ehcache*（Spring 6 移除了对 EhCache 2 的支持）、org.apache.httpcomponents:httpclient（Spring 6 使用 HttpClient 5）、org.antlr:antlr（已移除的 spring-modules-validation 的传递依赖）、org.springframework.social:*。migrate_egovframe_project 的诊断也会将其列为手动事项。官方公共组件 v3.10.0 pom 中的“无基准”从 17 项降至 1 项（xerces:xercesImpl），官方 egovframe-boot-web·egovframe-web 模板 pom 为 0 项。（4）sync_egovframe_templates 增加 catalogs 部分（src/catalog-drift.ts）：从 egovframe-runtime·egovframe-common-components 标签列表（GitHub API → 失败时使用标签页面 HTML，可选 GITHUB_TOKEN）中查找比规则 toTag 更新的标签；探测官方两种 parent 的下一个 patch 3 个·minor·major 候选的 HEAD（仓库阻止访问 maven-metadata.xml·列表）；报告 parent pom·Boot BOM pom 的 sha256 变化，发生变化时附上更新步骤。查询失败逐项记录错误，不计为 drift，也不修改文件。更新英文工具说明·资源说明。测试：test:dependencies 断言从 68 项增至 104 项，test:migration-rules 从 613 项增至 628 项，新增 test:catalog-drift，含 26 项断言（门禁）·test:catalog-drift-live（CI 集成，传递 GITHUB_TOKEN），test:dependencies-live 加入官方模板·3.10 pom 基准的 4 项断言。设计：docs/design-dependency-check.md。server.json 0.34.0。

• 0.33.1 — 修复 Windows 构建错误路径。Maven·Gradle 编译错误解析器将 : 视为文件名边界，导致 C:\work\A.java 被截断为 :\work\A.java；现已修复，使其将驱动器字符识别为路径的一部分。因此 Windows 上 build_egovframe_project·test_egovframe_project 的错误文件路径会损坏，migrate_egovframe_project(verify=true) 无法将错误关联到手动事项，发布门禁 test:migrate 也会在 Windows 上失败（v0.33.0 CI Windows 门禁 3 项失败的原因）。在 test:migrate 中增加 3 项 Windows 驱动器路径断言（162 项 → 165 项）。功能无变化。

• 0.33.0 — 5.x 转换第 3 阶段（验证）+ 公共组件对照表（工具数量保持 27 种）。（1）migrate_egovframe_project(verify=true)：诊断后运行 compile，将编译错误与诊断条目关联——同一文件中的 symbol 匹配（cannot find symbol … class Mapper ↔ class-removed Mapper，package X does not exist ↔ 前缀匹配，优先关联手动事项）→ 同一文件相差 ±3 行的手动事项 → 规则目录中的已移除类·缺失的 egovframework.rte/javax 包（提示应用未完成）→ 未分类。按各手动事项“可解决的错误数”降序生成任务列表，并将与错误无关的手动事项也以 0 项列出，避免遗漏。parseBuildErrors 将 javac 后续行 symbol:·location: 附加到 BuildError.symbol/location（Maven·Gradle）。没有构建文件时跳过验证并说明原因。（2）规则目录 schemaVersion 2：生成器将 egovframe-common-components v3.10.0 ↔ v5.0.6 的源码树作为第二个依据进行比较，并记录到 packages.components（移除 54·移动 4·新增 52，固定 commit）。诊断会将 egovframework.com.* 引用中的对照表已移除类报告为 component-class-removed（manual，维护的替代映射 EgovMybaitsUtil→EgovMybatisUtil），将移动类报告为 component-class-moved（auto）；对照表中未列出的类可能是用户代码，因此不报告。（3）重新组装建议：如果检测到的公共组件目录中包含 3.x 转换条目，则每个组件生成 1 项 component-reassemble（manual）；skipComponents=true 时，将该目录中的自动条目改为手动并排除在替换之外。结构化输出 schema 增加 verify 字段，更新英文工具说明。测试：test:migrate 断言从 132 项增至 162 项，test:migration-rules 605 项断言，test:migrate-integration 加入 3 项实际编译错误关联测试。设计：docs/design-migration.md 的第 3 阶段章节。server.json 0.33.0。

• 0.32.0 — MCP 协议现代化（工具数量保持 27 种，响应正文无变化）。（1）将 SDK 1.29 中已弃用的 server.tool() 调用 27 处替换为 registerTool()，并在 tools/list 中公开 src/tool-meta.ts 的 ko/en title 和 annotations——readOnlyHint 14 种（列表·搜索·详情·指南·文档搜索·诊断·验证·报告·依赖检查·网络诊断·upstream 对照 2 种），destructiveHint 4 种（remove_egovframe_components·upgrade_egovframe_project·migrate_egovframe_project·generate_agents_md——对参数可能改变行为的工具采取保守标记），idempotentHint（只读·构建·测试），openWorldHint（下载·OSV·网络探测·构建）。MCP 客户端可据此判断是否无需批准即可执行只读工具，或是否需要在执行破坏性工具前确认。（2）为提供 format=json 的 5 种工具（diagnose_egovframe_project·validate_egovframe_project·migrate_egovframe_project·check_egovframe_dependencies·diagnose_egovframe_network）声明 src/output-schemas.ts 中的 zod outputSchema，并同时返回 structuredContent（保留 text；转换结果中的内部编辑偏移量 edits 不包含在结构化输出中）。SDK 会在调用时根据 schema 验证结果，结果接口不匹配时会立即暴露。（3）测试可移植性防护——v0.30·v0.31 中仅 Windows 门禁两次失败的原因是测试假定 POSIX；现通过 scripts/check-test-portability.mjs（未规范化的 path.relative 比较、./mvnw 字面量、POSIX 绝对路径）检测并加入 prepublishOnly，并为 collectAgentsFacts 添加 platform 注入，以同时验证 linux·win32。也修复了 1 个潜在的同类问题（test/dependencies.mjs）。buildServer({ lang }) 同样应用于 title。测试：test:output-schemas 41 项断言，扩展 handshake，check:portability。server.json 0.32.0。

• 0.31.0 — 运营便利性：工具数量从 25 增至 27 种。（1）diagnose_egovframe_network——向工具下载所用的 7 种主机实际发送 DNS 查询和 HEAD 请求，报告可达性·耗时·失败类型（DNS·超时·TLS·代理认证·拒绝·重置·不可达·HTTP 5xx）；同时显示环境变量（HTTPS_PROXY·NO_PROXY·NODE_USE_ENV_PROXY·NODE_OPTIONS·NODE_EXTRA_CA_CERTS，隐藏凭据）和 Node 是否支持 --use-env-proxy，随后根据情况通过 bash/cmd/PowerShell 命令提供解决方案（使用代理·优先 IPv4·内部 CA·代理认证·DNS 允许列表）。对 NODE_TLS_REJECT_UNAUTHORIZED=0 发出警告。所有下载路径（fetchWithTimeout）失败时，在错误消息中附加相同的分类和简短解决方案（起因是 2026-09-21 新笔记本上的 codeload 超时）。（2）generate_agents_md——根据诊断结果（构建工具·wrapper·RTE·5.x 转换状态·DbType·默认包·配置目录·已安装组件及其 manifest 状态·备份目录）生成供 AI 编码工具使用的 AGENTS.md。规则章节转述了本服务工具遵循的原则（坐标体系·备份目录不提交·机密信息·由 parent 管理的坐标）；支持 dryRun·overwrite·fileName（如 CLAUDE.md）·lang（ko/en），并使用 transaction 写入。（3）英文支持——README.en.md 和 EGOVFRAME_LANG=en（27 种工具的英文说明，响应为韩语）。（4）MCP Registry——server.json（io.github.EricSeokgon/egovframe-scaffold-mcp，记录 npm 包·stdio·2 种环境变量）及 package.json mcpName，一致性测试 test:registry。将 SERVER_VERSION 拆分到 src/version.ts（防止循环导入），新增 buildServer({lang}) 选项。测试：test:network 33 项断言·test:agents-md 22 项断言·test:registry，handshake 验证英文说明，CI 集成 job 加入 test:network-live。兼容原有 25 种工具。

• 0.30.0 — 应用 5.x 转换（第 2 阶段）+ 依赖检查：工具数量从 24 增至 25 种。（1）为 migrate_egovframe_project 添加 apply·dryRun 参数，将第 1 阶段诊断标记为 auto 的条目实际替换。诊断会为每个条目附加基于原文偏移量的编辑（edits），应用时按文件从后向前执行，因此预览和实际应用使用相同依据——RTE 坐标（groupId/artifactId/version 文本）、RTE 版本属性名称·值（<org.egovframe.rte.version>5.0.2）和 ${属性} 引用、包前缀·名称更改·移动、javax→jakarta 包和依赖坐标（仅当替换结果中没有 glassfish 实现时插入 JSTL）、仓库 URL、Java 17、web.xml 开始标签（xmlns·version·schemaLocation）、gradle 字符串。保留元素名称·缩进·注释，不修改 manual 条目。dryRun（默认）仅返回逐文件变更行预览；应用时通过 withFileTransaction 将原件备份到 migration-backup/<时间>-<id>/ 后执行替换，保留 migration-plan.json，中途失败时恢复到操作前状态（写入前重新比对诊断时的内容）。应用后附上重新诊断摘要（remaining，预期 auto 为 0）和 build_egovframe_project(goal="compile") 提示。之后的扫描会排除备份目录。调整了诊断逻辑，使 <source>${java.version}</source> 等属性引用由属性条目处理。（2）check_egovframe_dependencies——从标准框架仓库下载官方两种 5.x parent（egovframe-web-config-parent·egovframe-boot-starter-parent 5.0.1）的 pom，生成 catalog/dependency-baseline.json（139 种受管坐标、7 种从 BOM import·版本属性推导的系列基准，记录 sha256）（scripts/generate-dependency-baseline.mjs），并将项目依赖分类为满足基准/低于基准/parent 管理/转换对象（3.x·4.x RTE·javax 坐标）/需要替换（转换规则的库列表）/无基准/无版本。同时检查 5.x parent 使用情况·版本、Java 版本（识别 parent 管理）、5 种安全配置是否存在（sec.security 组件·CSRF·XSS 过滤器·安全响应头·HTTPS 仓库，提供文件·行号依据）；offline=false 时通过 OSV querybatch 为版本已确定的依赖附加已知漏洞（失败仅记入 osvError）。新增资源 egovframe://catalog/dependency-baseline。调整 Jakarta 转换规则的目标版本，使其不低于 parent 基准（test:migration-rules 检查此项），并使 fetchWithTimeout 接收请求选项。测试：test:migrate 断言从 87 项增至 132 项，test:dependencies 68 项断言，test:migration-rules 597 项断言，CI 集成 job 新增 test:migrate-integration（应用后使用 JDK 17 执行 mvn compile）·test:dependencies-live（OSV）。设计：docs/design-migration.md（第 2 阶段章节）、docs/design-dependency-check.md。兼容原有 24 种工具。

• 0.29.0 — 5.x 转换诊断（第 1 阶段）：新增 migrate_egovframe_project（工具数量从 23 增至 24）。以文件·行号为单位报告将标准框架 3.x/4.x 项目迁移至 5.x（Jakarta EE 9+、Spring 6、Java 17）所需的修改——RTE Maven 坐标（egovframework.rte:egovframework.rte.<module>·4.x 的 org.egovframe.rte:org.egovframe.rte.<module> → org.egovframe.rte:egovframe-rte-<module>，18 个模块）和 RTE 版本属性·仓库 URL（http → https）·5.x parent 建议、低于 Java 17 的编译设置、低于 Spring 6 的属性、包前缀（egovframework.rte.* → org.egovframe.rte.*）以及 5.x 中重命名的 4 个包（fdl.cryptography→fdl.crypto、security.securedobject→security.secureobject、security.config.internal/security.intercept→security.bean）、38 种已移除的类（@Mapper→@EgovMapper、AbstractServiceImpl→EgovAbstractServiceImpl、移除 @CommandMap·SimpleUrlAnnotationHandlerMapping·RteFieldChecks 等——同时说明替代方案和原因）、已移除的 RTE 模块 spring-modules-validation、28 种 javax→jakarta 包（排除 JDK 内置的 javax.sql·javax.xml.*·javax.crypto 等）和 26 种依赖坐标、web.xml schema、5.x 中已移除的 egov-security/egov-access/egov-crypto XML namespace、需要替换的库（DBCP 1.x·Log4j 1.x·commons-fileupload·Tiles·JUnit 4·旧版 Hibernate Validator 等）。每个条目标记 auto（第 2 阶段进行机械替换）·manual（需要修改代码），并以 markdown/json 返回，不写入文件。规则存放在非代码文件 catalog/migration-rules.json（schemaVersion 1）中，生成器 scripts/generate-migration-rules.mjs 比较 egovframe-runtime 的 v3.10.0·v4.3.0-Final·v5.0.2-Final 标签源码树，推导坐标·包迁移·移除项；如果已移除类没有经过维护的 catalog/migration-mapping.json 原因说明则失败。新增资源 egovframe://catalog/migration-rules。离线 test:migrate 含 87 项断言（3.10 fixture·5.x fixture 0 项·只读），test:migration-rules 579 项断言；CI 集成 job 的 test:migration-rules-live 检查 61 个目标坐标在实际仓库中存在。验证了官方两种 5.x 模板中误报 0 项、官方公共组件 v3.10.0 资产中检测到 57 项（设计：docs/design-migration.md）。兼容原有 23 种工具。

• 0.28.1 — 适配 Windows checkout（npm 安装包行为无变化）：修复开启 core.autocrlf 的 Git 克隆会将随附配置模板（catalog/config-templates/*.hbs）以 CRLF checkout，导致渲染前指纹比对失败，进而破坏 generate_egovframe_config·test:config·test:template-catalog 的问题（PR #28）。改为按 LF 换行符规范化后计算指纹（templateSha256，生成器·渲染器·sync·测试共用），按此规则重新生成目录指纹（模板内容不变），并通过 .gitattributes 禁止转换这些路径的换行符。在 test:config 中增加 CRLF checkout 模拟断言（506 项断言）。通过 npm 安装的 0.28.0 不受影响，因为 tarball 保留 LF。

• 0.28.0 — 生成配置文件：新增 generate_egovframe_config（工具数量从 22 增至 23）。将官方 eGovFrame VSCode Initializr 的 21 种配置向导模板（templates/config、Handlebars、Apache-2.0）以 commit 和逐文件 sha256 固定的方式随附于 catalog/config-templates/，无需联网即可生成 Spring 配置文件——datasource（DBCP/C3P0/JDBC·JNDI）、transaction（datasource/JPA/JTA）、cache（Ehcache 定义·Spring 缓存）、logging（log4j2 console/file/rolling/time-rolling/jdbc）、scheduling（Quartz bean job/method job/simple·cron trigger/scheduler）、idGeneration（sequence/table/uuid）、property。格式包括 xml（所有模板）·javaConfig（@Configuration）·yaml·properties（logging）；字段名称和默认值与 Initializr Web 表单一致，省略字段时会生成与 IDE 相同的结果。拒绝模板中没有的字段·选项范围之外的值·格式错误的文件名/类名/包名；输出路径必须位于项目内（拒绝 ..·绝对路径·脱离 symlink），不会覆盖现有文件。响应上下文中的密码字段会隐藏。渲染前比对随附文件指纹（将换行符规范化为 LF，以确保 Windows autocrlf checkout 下判定一致，增加 .gitattributes），sync_egovframe_templates 会将其与 upstream 对应文件比较并报告 configTemplates.drift。通过资源 egovframe://catalog/config-templates 查询各模板的格式·字段·默认值·选项。发现 upstream 的 3 个问题（不存在的 timeBasedRollingFile-java.hbs、内容为 XML 的 jdbc-properties.hbs、表单中的 txtPasswrd 拼写错误）通过维护排除·修正，并记录在设计文档中。添加运行时依赖 handlebars（npm audit 0 项）。通过离线 457 项断言（npm run test:config）、49 项输出的 XML·YAML 解析及 2 种 JavaConfig 的 mvn compile 验证。兼容原有 22 种工具。路线图的候选编号后移一位。

• 0.27.0 — 扩大官方模板覆盖范围（10 → 22 种，按 Initializr 22 种模板计算的覆盖数从 9 增至 21 种）：在 v0.26.0 的集成目录所计算出的 13 种未覆盖模板中，新增 12 种仅通过 Initializr 仓库的 zip（Git LFS，templates/projects/examples/）发布且没有独立 GitHub 仓库的模板——web·boot-web（空骨架）、batch-file-scheduler·batch-file-commandline·batch-file-web·batch-db-scheduler·batch-db-commandline·batch-db-web、mobile-web·mobile-common-components、msa-portal-backend·msa-portal-frontend（多项目）。分支会变化，因此将下载 URL 固定到 Initializr commit，并使用 LFS 指针的 sha256·大小校验下载字节；不匹配时拒绝写入任何内容（直接提供 ref 时跳过校验，并在结果中记录 archiveVerified: false 和警告）。zip 与 codeload 归档不同，不含顶层目录，因此不截去根目录；先填入 pom.xml 中的 ###GROUP_ID###·###ARTIFACT_ID###·###NAME###·###VERSION###·###URL### 占位符，再应用现有坐标。Globals.DbType 会查找各模板中路径不同的 globals.properties（批处理模板位于 egovframework/batch/properties/）并应用。sync_egovframe_templates 不读取 zip 正文，而是读取 LFS 指针并与固定指纹对比，报告 archivesChecked·archiveDrift，并在集成目录的 mcp.archive 中附带指纹。23MB 的一体化 egov-template-common-components 按照“公共组件应使用 add_egovframe_components 选择性组装”的既有维护决定予以排除。实际生成全部 12 种模板，确认没有占位符残留；batch-db-commandline·boot-web·mobile-web 通过 mvn compile。下载 zip 正文还需要访问 media.githubusercontent.com。兼容原有 10 种模板·全部工具。路线图的候选编号后移一位（namespace 转换 v0.27 → v0.28 等）。

• 0.26.0 — 统一官方模板目录：新增 sync_egovframe_templates（工具数量从 21 增至 22）。此前相同信息分别记录在三个地方——Initializr 在 templates/templates-projects.json 中记录 22 种项目的 zip·pom 快照；MCP 在 TEMPLATES（现为 src/project.ts）中记录 10 种模板的官方仓库获取方式；Development 在 eGovFrameTemplates/wizards.xml 中记录 8 类配置片段向导；v0.24.0 的覆盖扩展也需要人工逐项比对这两者。现在将其统一到单个 schemaVersion: 1 的 catalog/templates.json，并排记录每个项目在 Initializr 侧的 zip·pom 与 MCP 侧的仓库·分支·多项目状态，覆盖情况（22 种中匹配 9 种·未覆盖 13 种·仅 MCP 支持 2 种）由计算得出。映射由 catalog/template-mapping.json 维护，不会自动推断——例如 Initializr 的 egov-web（空 Web 骨架）和 MCP 的 web-sample（公告板示例）名称相似但生成产物不同，因此不将二者对应，并在 note 中记录依据。生成器 scripts/generate-template-catalog.mjs 遇到映射中没有的 upstream 项时会失败，避免静默遗漏；sync_egovframe_templates 会下载 upstream，对比新增·删除·更改（字段级）和 sha256 并报告，但不会修改文件。list_egovframe_templates 的响应也会附上覆盖摘要（目录不存在时保持原有行为）。离线 148 项断言（npm run test:template-catalog），兼容原有 21 种工具。为支持 Windows，生成器基于 file URL·realpath 处理 dist/index.js 加载和直接执行判断。

• 0.25.3 — 修复启动问题 + 扩展 CI（工具接口向后兼容）。

  • 修复 npx 启动失败（Linux·macOS）：入口判断通过比较 process.argv[1] 文件名末尾与 import.meta.url，因此 npm 在 POSIX 系统上将 bin 安装为 symlink（node_modules/.bin/egovframe-scaffold-mcp → dist/index.js）时，会误判当前文件不是入口，导致服务未启动且无错误地退出。这是 README 所示的 npx -y egovframe-scaffold-mcp 配置无法在 Linux·macOS 上运行的原因（Windows 使用 .cmd shim 直接执行 dist/index.js，不受影响；直接执行 node dist/index.js 也不受影响）。现改为解析双方路径的 realpath 后再比较，并将通过 symlink 启动固定为回归测试（npm run test:handshake）。
  • CI：在 ubuntu·windows × Node 18·20·22 矩阵中运行发布门禁，并将下载官方仓库的集成测试分离为单独 job（ubuntu/Node 20）。用平台无关的测试（test:handshake）替代 bash 管道式 handshake 检查，并将其加入 prepublishOnly；新增运行时依赖 npm audit（high 及以上）步骤。
  • 测试：将超时后终止进程树的回归测试改为基于 node 孙进程，以便在 Windows（taskkill /T /F 路径）上运行。
  • 文档：将随发布时间变化的“发布状态”文字统一为以 npm 徽章为单一来源的方式。

• 0.25.2 — 加固安全性与稳定性（工具接口向后兼容）。

  • generate_egovframe_ci：修复 jdk 值未经验证便插入生成 workflow YAML，可能通过引号·换行符插入任意 step 的问题。仅允许数字和点组成的格式（17、21、1.8、17.0.9），工具 schema 和函数都会拒绝非法值。违规时不会创建文件。
  • 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 无结果。
  • 文档：将 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）。返回每个 suite 的通过·失败·错误·跳过数量，以及失败用例的消息·异常类型·堆栈跟踪中的测试类帧（文件:行号）；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，跳过坐标·数据库自动重写，保护子模块引用，并在生成结果中说明不会自动应用坐标/数据库。npm run test:templates 新增注册·显示·官方仓库路径验证，以及实际下载归档的 dryRun 集成验证。兼容原有 7 种模板·所有工具。

• 0.21.1（已完成，已合并至 v0.22.0） — 优先强化避免损坏用户项目的失败·恢复边界。

  • PR #9：比较安装时的 SHA-256 与当前文件，将文件分类为 unchanged/modified/unverified/missing，默认保留用户修改的文件和未确认基准的文件。force=true 会先将现有文件和删除计划保存在 remove-backup/ 中再删除；中途失败时将文件·POM·manifest 回滚到操作前状态。
  • PR #10：引入可复用的 ProjectFileTransaction，将 AI 文件·POM 备份/更新·manifest 放在同一个 transaction 中 commit。
  • PR #11：在 sibling staging 目录中解压·自定义项目后进行 atomic rename；发生失败·目标路径竞争时，不会暴露不完整项目。
  • PR #12：在单个目录 transaction 中执行创建项目→公共组件→可选 AI 组装，所有步骤成功后才公开最终路径。包含官方模板·组件 rollback 集成测试和 CI gate。
  • PR #13：通过公共 file transaction 提交直接公共组件组装的文件·SQL·manifest；中途失败和脱离上级 symlink 边界时恢复到操作前状态。
  • PR #14：在应用前重新验证组件升级的目标 hash，并通过公共 transaction 更新文件·唯一备份·upgrade-plan.json·manifest。中途失败和脱离上级 symlink 边界时恢复到操作前状态。
  • PR #15：通过 providedComponents 检查·保留官方模板中已有的 cmm，仅安装 recipe 添加的 bbs/login。不覆盖现有 38 个文件，也不将其记录为工具管理的文件；通过集成测试验证组装·检查成功和后续 rollback。
  • PR #16：在所有工具入口点应用 EGOVFRAME_ALLOWED_ROOTS，并基于 realpath 阻止通过 symlink/junction 绕过。transaction 失败时提供 RollbackReport（filesAttempted·restoredFiles·removedNewFiles·cleanedDirs·failures·ok）。
  • 详细分析·验证·失败/恢复记录以 egovframe-contribution-notes/작업이력.md 为单一台账。

• 0.22.0 — 完成安全性基础：统一将所有写入工具改为可回滚的 transaction（创建项目·recipe·直接组装·AI 组装·升级），强制判定回归并使测试失败，并在移除组件时保护用户文件。新增 EGOVFRAME_ALLOWED_ROOTS，对所有工具统一强制允许的 root（基于 realpath，阻止 symlink 绕过，未设置时兼容原有的无限制行为）；transaction 失败时，除面向人的文字说明外，还提供机器可读的 rollback-report: {json}（恢复·删除·清理数量、失败列表）。包含保留 recipe 模板组件的修复。（#8–#16）

• 0.21.0 — 完整组装已验证的公共组件：新增 sync_egovframe_catalog，固定 common-components 官方 v5.0.6 标签·commit（23d01889…）·archive SHA-256/大小/文件数。将目录重新生成为 schema v2，含 190 个条目（叶节点 176+组 14），关联 278 条 message bundle、91 个 IDGN context、18 个 scheduling context、662 个 Web 资产、26 个 Spring/Web fragment 和 Maven 坐标。add_egovframe_components 会一并复制这些资产，并处理相同文件的重用、不同内容冲突时整体拒绝、写入失败时回滚、阻止非 DB 组件使用 SQL 回退。CI 会验证新的 sec.security 安全包和未映射的 upstream 路径；manifest schema v3 中记录 source 固定信息。兼容原有目录 schema v1·manifest v1/v2。

• 0.20.0 — CRUD 코드 생성: generate_egovframe_crud 추가. eGovFrame Development의 공식 wizard.xml 입력 그룹(author/createDate, DataAccess·Service·Web, mapper/VO/service/controller/JSP 경로)에 맞춰 VO·DefaultVO·EgovMapper 인터페이스·MyBatis XML·Service·ServiceImpl·Controller를 생성합니다. Classic은 MVC+JSP 2종, Boot는 REST Controller를 생성하고 withTest로 JUnit 5 계약 테스트를 추가합니다. PK 필수, SQL/Java 식별자·상대경로 검증, dryRun, 전체 충돌 사전 검사, 쓰기 실패 롤백을 적용했습니다. 오프라인 테스트(npm run test:crud)와 공식 simple-backend/Boot·web-sample/Classic Maven compile 통합 테스트를 추가했습니다. 프로젝트 직접 Maven 좌표만 변경해 parent·dependency를 보존하고, lockfile·npm 패키지 설계 문서·CI 전체 릴리스 게이트를 추가했으며 adm-zip 0.6.0으로 고위험 ZIP 취약점을 해소했습니다. 기존 17개 도구 하위 호환.

• 0.19.0 — CI 생성 + 문서 검색 deep: generate_egovframe_ci 추가(프로젝트에 GitHub Actions 빌드·테스트 워크플로 생성, maven/gradle 자동 감지·dryRun·기존 파일 거부). search_egovframe_docs에 fetchTop 옵션 추가 — 상위 결과 문서 본문을 내려받아 스니펫 제공(기본 0=오프라인). 테스트(npm run test:ci) 추가. 기존 도구 하위 호환.

• 0.18.0 — 컴포넌트 설명 + 리소스/프롬프트 확장: explain_egovframe_component 추가 — 컴포넌트 하나의 설명·직접/전이 의존성·이 컴포넌트에 의존하는 컴포넌트·참조 테이블·가이드 링크·설치 명령을 한 번에 반환(읽기 전용). 리소스 egovframe://catalog/ai-components 추가, 프롬프트 scaffold_portal·maintain_existing(진단→리포트→업그레이드) 추가. 테스트(npm run test:explain) 추가. 기존 도구 불변(완전 하위 호환).

• 0.17.0 — 컴포넌트 업그레이드: upgrade_egovframe_project 추가 — 매니페스트 설치 컴포넌트를 upstream 최신본과 3-way 비교(설치 기준선 해시·현재 디스크·upstream)해 갱신합니다. 사용자가 수정한 파일은 force 없이 보존, dryRun 기본(계획 미리보기), 덮어쓰기 전 upgrade-backup/에 백업, 하드 충돌 시 아무것도 쓰지 않고 거부. 매니페스트 스키마 v2(파일별 해시 기준선) — add_egovframe_components가 이후 설치본에 해시 기록. 오프라인 판정 테스트(npm run test:upgrade) 추가. 기존 도구·기존 매니페스트(v1) 하위 호환(해시 없으면 보수 모드).

• 0.16.0 — 프로젝트 리포트: generate_egovframe_report 추가 — 프로젝트를 스캔해 설치 공통컴포넌트·참조 테이블·가이드 문서 링크·이슈를 Markdown 리포트로 생성합니다(읽기 전용, diagnose+카탈로그+가이드 매핑 재사용). 조립 결과 문서화/README 첨부용. 테스트(npm run test:report) 추가. 기존 도구 불변(완전 하위 호환).

• 0.15.0 — 가이드 문서 검색: search_egovframe_docs 추가 — 카탈로그 가이드 매핑(제목·경로·연계 컴포넌트·카테고리)을 키워드로 점수순 검색하고 문서 URL과 조립용 컴포넌트 id를 반환합니다. 오프라인 동작(네트워크 불필요). 테스트(npm run test:docs) 추가. 기존 도구 불변(완전 하위 호환).

• 0.14.0 — 프로젝트 진단 도구: diagnose_egovframe_project 추가 — 기존(스캐폴딩 도구로 만들지 않은 것 포함) 프로젝트를 읽기 전용으로 스캔해 빌드시스템(maven/gradle)·eGovFrame RTE 버전·Globals.DbType·설치된 공통컴포넌트(카탈로그 pathPrefixes 지문 매칭)·AI 계층·매니페스트 유무를 파악하고, 의존성 누락·DbType 미설정 등 이슈와 다음 단계 제안을 리포트합니다. 픽스처 테스트(npm run test:diagnose) 추가. 기존 도구 불변(완전 하위 호환).

• 0.13.0 — MCP 리소스·프롬프트 + 레시피: tools 외에 resources(카탈로그·템플릿·가이드 읽기 전용 노출, 단일 컴포넌트는 resource template)와 prompts(scaffold_board_login·scaffold_ai_chatbot)를 지원해 MCP 3대 프리미티브를 완비. 레시피(catalog/recipes.json)와 list_egovframe_recipes·apply_egovframe_recipe 도구 추가 — 생성→컴포넌트→AI 계층 조립을 한 번에 오케스트레이션(각 단계 dryRun 전파·원자적 거부 계승). 정합성 테스트(npm run test:recipes) 추가. 기존 도구·카탈로그 불변(완전 하위 호환).

• 0.12.0 — 카탈로그 커버리지 확대(68 → 188항목): 컴포넌트 단위를 2단계 패키지에서 리프 패키지(서비스 단위, 최대 4단계) 로 세분화해 리프 174종을 개별 선택 설치할 수 있습니다. 기존 2단계 id는 children을 가진 그룹으로 유지되어 하위 호환됩니다(그룹 요청 시 리프로 확장 설치, 그룹+리프 동시 요청 중복 제거). 리프 한글명은 Service 인터페이스 Javadoc에서 자동 추출(96종), 가이드 문서 매핑은 리프 우선으로 재계산(151종).

• 0.11.0 — 템플릿 확장: 공식 템플릿 2종 → 7종 (simple-homepage·portal-site·enterprise-business·web-sample·msa-edu 추가). 레거시 템플릿은 egovProps/globals.properties의 Globals.DbType 적용을 새로 지원, 멀티 프로젝트(msa-edu)는 좌표/DB 재작성을 건너뛰어 하위 모듈 참조를 보호. 템플릿별 빌드 안내(nextSteps) 분기, 통합 테스트(npm run test:templates) 추가.

• 0.10.0 — AI 컴포넌트 조립 M3: langchain4j 스택 실조립·제거 사이클 통합 검증(init-scripts/ai/·JPA 의존성·pom 원복), validate_egovframe_project에 AI 실행 전제 진단(aiChecks) 추가 — application-ai.yml의 ONNX 모델/토크나이저·임베딩 설정 경로를 ${user.home}·환경변수 플레이스홀더까지 해석해 존재 확인, docker compose 기동 안내 (경고와 분리되어 ok 판정에 영향 없음).

• 0.9.0 — AI 컴포넌트 조립 M2(실조립): add_ai_components가 실제로 조립합니다 — 소스(com.example.chat)·설정(application-ai.yml 프로필, 기존 설정 불변)·UI·인프라(docker-compose.ai.yml·Dockerfile.ai·k8s/ai/) 복사(전체 사전 충돌 검사·원자적 거부), pom에 누락 좌표만 마커 주석 구간으로 삽입(exclusions 보존, pom.xml.bak-ai 백업), 매니페스트 기록으로 remove_egovframe_components가 파일·pom 삽입분을 함께 원복(바이트 단위 복원 검증), validate_egovframe_project에 pom 마커 진단 추가, 통합 테스트(npm run test:ai-assembly) 추가.

• 0.8.0 — AI 컴포넌트 조립 M1: add_ai_components dryRun 미리보기(파일 복사 계획·pom 의존성 diff·부모 POM 호환성 게이트·스택 상호 배타 검사), AI 카탈로그(catalog/ai-components.json, egovframe-ai-rag 모듈 스캔 자동 생성 npm run generate:ai-catalog), list_egovframe_components에 AI 컴포넌트 노출, 오프라인 테스트(npm run test:ai) 추가.

• 0.7.0 — get_egovframe_guide: 컴포넌트 id로 표준프레임워크 공식 가이드 문서(egovframe-docs)를 조회. 카탈로그에 문서 매핑 자동 생성(--docs, 지배적 패키지 참조 기준 45종) 추가. 한글명 큐레이션 12→27종.

• 0.6.0 — 컴포넌트별 테이블 선별 DDL(M4): 카탈로그에 매퍼 기반 참조 테이블 자동 추출(48/68종), database 지정 시 통합 스크립트에서 해당 컴포넌트 구문만 추출해 ddl|dml/<컴포넌트id>.sql 생성(테이블 미상 컴포넌트는 통합본 폴백), 매니페스트에 컴포넌트별 스크립트 귀속(제거 시 함께 정리).

• 0.5.0 — 조립 수명주기 완성: search_egovframe_components(키워드 검색), 설치 매니페스트(.egovframe-components.json) 기록, remove_egovframe_components(의존 보호·dryRun), validate_egovframe_project(파일 무결성·DbType↔DDL 일치 진단), 중복 설치 거부.

• 0.4.0 — 공통컴포넌트 선택 설치 M3: 저장소 구조 스캔으로 카탈로그 자동 생성(scripts/generate-catalog.mjs), 커버리지 3종 → 68종(2단계 패키지 단위, cmm 하위 통합). 이름·설명·의존성은 catalog/overrides.json으로 큐레이션(기본 의존성 휴리스틱: cmm).

• 0.3.0 — 공통컴포넌트 선택 설치 M2: add_egovframe_components 실제 조립 구현(의존성 포함 파일 복사, 전체 사전 충돌 검사 후 원자적 거부, zip-slip 방지, database 지정 시 DDL·DML 복사, zip 프로세스 캐시). 통합 테스트(test:components) 추가.

• 0.2.2 — 공통컴포넌트 선택 설치 M1: 컴포넌트 카탈로그(catalog/components.json, 대표 3종 cmm·bbs·login), list_egovframe_components·add_egovframe_components(dryRun 미리보기) 도구 추가, 카탈로그 오프라인 테스트 추가.

• 0.2.1 — 프론트엔드(simple-react) 템플릿의 package.json name을 프로젝트명으로 적용(백엔드는 기존대로 pom·DbType).

• 0.2.0 — 다운로드 타임아웃(30초), ref(브랜치/태그) 파라미터, dryRun 미리보기 모드 추가. list_egovframe_templates가 지원 DB 목록도 함께 반환.

• 0.1.0 — 최초 PoC: create_egovframe_project, list_egovframe_templates.

라이선스

Apache License 2.0