commitgate 0.1.2 → 0.2.1

package/README.en.md

@@ -6,6 +6,8 @@
 
 AI coding agents can move quickly, but unreviewed changes should not go straight into your history. CommitGate wraps each change in a REQ ticket and only allows the staged tree approved by Codex to be committed. If the code changes after approval, or if evidence is missing, it fails closed.
 
+[![CI](https://github.com/sol5288/commitgate/actions/workflows/ci.yml/badge.svg)](https://github.com/sol5288/commitgate/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/commitgate.svg)](https://www.npmjs.com/package/commitgate)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 ---
@@ -71,6 +73,7 @@ CommitGate is designed to block **unreviewed changes from being committed**, not
 - If the approved staged tree differs from the current staged tree, the commit is blocked.
 - Workflow files such as `state.json` and `responses/` cannot be mixed into the source commit.
 - If Codex CLI is missing or fails, the workflow fails instead of silently passing.
+- During install, existing `cross-spawn` versions below the verified floor warn by default and fail with `--strict`.
 - Approval responses and evidence are kept under `workflow/REQ-.../responses/`.
 
 In short: **approved changes pass, ambiguous changes stop.**
@@ -95,6 +98,14 @@ Preview without writing files:
 npx commitgate --dry-run
 ```
 
+Treat the security floor warning as an install failure:
+
+```sh
+npx commitgate --strict
+```
+
+If an existing `cross-spawn` is below the verified floor, CommitGate stops before copying files.
+
 ---
 
 ## Prerequisites
@@ -160,6 +171,8 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 | Command | Purpose |
 |---|---|
 | `npx commitgate` | Install CommitGate into a project |
+| `npx commitgate --dry-run` | Preview the install plan without writing files |
+| `npx commitgate --strict` | Treat low `cross-spawn` version warnings as install failures |
 | `req:new <slug> --run` | Create a REQ ticket, branch, and design docs |
 | `req:review-codex <id> --kind design --run` | Review the design |
 | `req:review-codex <id> --kind phase --run` | Review the implementation |
@@ -194,6 +207,9 @@ No. If the staged tree changes after approval, CommitGate treats the approval as
 **Why should I not stage `state.json` or `responses/`?**
 They are workflow state and evidence files. Mixing them into the source commit weakens the approval binding, so `req:commit` blocks it.
 
+**What should I do if I see a cross-spawn version warning?**
+It means the target project may already have a `cross-spawn` version below CommitGate's verified floor. Upgrade it with `npm i -D cross-spawn@^7.0.6`. In CI or security-sensitive installs, use `npx commitgate --strict` to treat the warning as a failure.
+
 **Does running install twice overwrite files?**
 No. Existing files are skipped. Use `--force` if you intentionally want to refresh them.
 
@@ -203,12 +219,17 @@ No. Existing files are skipped. Use `--force` if you intentionally want to refre
 
 The current release is **Stage A: vendored scaffold model**. `npx commitgate` copies workflow files into the target project.
 
+Current verification:
+
+- GitHub Actions runs a `ubuntu-latest`, `macos-latest`, `windows-latest` × Node 18/20/22 matrix.
+- `npm run smoke` installs the packed tarball and runs the installed `commitgate` bin.
+- A Windows `.cmd` wrapper injection regression test protects package-manager and Codex wrapper paths.
+
 Future scope:
 
 - Running directly from `node_modules` as a library-style model
 - Non-git VCS support
 - More design document templates
-- Broader Linux/macOS CI smoke coverage
 
 ---
 

package/README.md

@@ -6,6 +6,8 @@
 
 AI 에이전트가 코드를 빠르게 만들더라도, 리뷰 없이 바로 커밋되면 위험합니다. CommitGate는 변경을 티켓 단위로 묶고, Codex가 승인한 staged tree만 커밋되게 합니다. 승인 후 코드가 바뀌거나 증거가 부족하면 기본적으로 막습니다.
 
+[![CI](https://github.com/sol5288/commitgate/actions/workflows/ci.yml/badge.svg)](https://github.com/sol5288/commitgate/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/commitgate.svg)](https://www.npmjs.com/package/commitgate)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 ---
@@ -71,6 +73,7 @@ CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지
 - 승인된 staged tree와 지금 커밋하려는 staged tree가 다르면 막습니다.
 - `state.json`, `responses/` 같은 워크플로 내부 파일을 source 커밋에 섞으면 막습니다.
 - Codex CLI가 없거나 실행에 실패하면 조용히 통과하지 않고 실패합니다.
+- 설치 시 기존 `cross-spawn`이 검증 하한보다 낮으면 경고하고, `--strict`에서는 중단합니다.
 - 승인 응답과 증거 파일은 `workflow/REQ-.../responses/`에 남습니다.
 
 한 줄로 말하면, **확실히 승인된 변경만 통과하고 애매하면 멈추는 방식**입니다.
@@ -95,6 +98,14 @@ CommitGate가 막는 것은 단순한 명령 실수가 아니라 **리뷰받지
 npx commitgate --dry-run
 ```
 
+보안 하한 경고를 설치 실패로 취급하려면:
+
+```sh
+npx commitgate --strict
+```
+
+기존 `cross-spawn`이 검증 하한보다 낮으면 파일을 복사하기 전에 중단합니다.
+
 ---
 
 ## 준비물
@@ -160,6 +171,8 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 | 명령 | 용도 |
 |---|---|
 | `npx commitgate` | 프로젝트에 CommitGate 설치 |
+| `npx commitgate --dry-run` | 파일을 쓰지 않고 설치 계획 확인 |
+| `npx commitgate --strict` | 낮은 `cross-spawn` 버전 경고를 설치 실패로 처리 |
 | `req:new <slug> --run` | REQ 티켓, 브랜치, 설계문서 생성 |
 | `req:review-codex <id> --kind design --run` | 설계 리뷰 |
 | `req:review-codex <id> --kind phase --run` | 구현 리뷰 |
@@ -194,6 +207,9 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 **`state.json`이나 `responses/`는 왜 stage하면 안 되나요?**
 워크플로 증거와 상태 파일입니다. source 커밋에 섞이면 승인 바인딩이 흐려지므로 `req:commit`이 막습니다.
 
+**cross-spawn 버전 경고가 나오면 어떻게 하나요?**
+대상 프로젝트의 기존 `cross-spawn`이 CommitGate가 검증한 하한보다 낮을 수 있다는 뜻입니다. `npm i -D cross-spawn@^7.0.6`으로 올리세요. CI나 보안 민감 환경에서는 `npx commitgate --strict`를 사용해 경고를 실패로 다루세요.
+
 **두 번 설치하면 덮어쓰나요?**
 아니요. 기존 파일은 건너뜁니다. 강제로 갱신하려면 `--force`를 사용하세요.
 
@@ -203,12 +219,17 @@ npm run req:commit -- 2026-001 --run --message-file commit-message.txt
 
 현재 버전은 **Stage A: vendored scaffold 모델**입니다. 즉 `npx commitgate`가 대상 프로젝트에 워크플로 파일을 복사합니다.
 
+현재 운영 중인 검증입니다.
+
+- GitHub Actions에서 `ubuntu-latest`, `macos-latest`, `windows-latest` × Node 18/20/22 매트릭스를 실행합니다.
+- `npm run smoke`는 pack tarball 설치본의 `commitgate` bin을 실행합니다.
+- Windows `.cmd` 래퍼 주입 회귀 테스트가 패키지 매니저와 Codex wrapper 경로를 보호합니다.
+
 아래는 후속 범위입니다.
 
 - `node_modules`에서 직접 실행하는 라이브러리 모델
 - 비-git VCS 지원
 - 더 다양한 설계문서 템플릿
-- Linux/macOS CI smoke 확대
 
 ---
 

package/bin/init.ts

@@ -25,6 +25,7 @@ import { resolve, join, dirname, relative } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { loadConfig, stripBom, type PackageManager } from '../scripts/req/lib/config'
 import { createGitAdapter } from '../scripts/req/lib/adapters'
+import * as semver from 'semver'
 
 /** 이 패키지 루트(bin/ 기준 1단계 위). 복사 원본. */
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
@@ -37,10 +38,13 @@ const REQ_SCRIPTS: Record<string, string> = {
   'req:commit': 'tsx scripts/req/req-commit.ts',
 }
 
+/** cross-spawn 주입 spec(= 보안 하한 SSOT). 진단(#1)과 주입이 이 값을 공유. */
+const CROSS_SPAWN_SPEC = '^7.0.6'
+
 /** 대상 package.json에 주입할 devDeps(워크플로 실행 전제). cross-spawn = 복사된 adapters.ts의 안전 spawn(P1) 런타임 의존. */
 const REQ_DEV_DEPS: Record<string, string> = {
   ajv: '^8.20.0',
-  'cross-spawn': '^7.0.6',
+  'cross-spawn': CROSS_SPAWN_SPEC,
   tsx: '^4.19.1',
 }
 
@@ -48,6 +52,7 @@ export interface InitOptions {
   dir: string
   force: boolean
   dryRun: boolean
+  strict: boolean // cross-spawn 하한 미만이면 WARN 대신 throw(#1)
 }
 
 export interface InitResult {
@@ -59,6 +64,7 @@ export interface InitResult {
   packageJsonAdded: string[] // 추가된 script/devDep 키
   agentsCreated: boolean
   packageManager: PackageManager
+  crossSpawnFloorWarned: boolean // 기존 cross-spawn이 보안 하한 미만이라 경고(#1)
   dryRun: boolean
 }
 
@@ -142,6 +148,92 @@ function parseJsonObject(path: string, label: string): Record<string, unknown> {
   return parsed as Record<string, unknown>
 }
 
+// ─────────────────────────────── cross-spawn 버전 하한 진단 (#1) ──
+
+/** 보안 하한 = 주입 spec의 최소버전(SSOT — 하드코딩 이중화 금지). '^7.0.6' → 7.0.6. */
+const CROSS_SPAWN_FLOOR = semver.minVersion(CROSS_SPAWN_SPEC)
+
+/** obj가 plain object일 때 obj[key](문자열). 아니면 undefined. */
+function stringField(obj: unknown, key: string): string | undefined {
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    const v = (obj as Record<string, unknown>)[key]
+    if (typeof v === 'string') return v
+  }
+  return undefined
+}
+
+/** 대상의 기존 cross-spawn spec(devDeps 우선, 없으면 deps). 없으면 null. */
+function existingCrossSpawnSpec(pkg: Record<string, unknown>): string | null {
+  return stringField(pkg.devDependencies, 'cross-spawn') ?? stringField(pkg.dependencies, 'cross-spawn') ?? null
+}
+
+/** node_modules에 실제 설치된 cross-spawn 버전(valid semver). 없으면 null. */
+function installedCrossSpawnVersion(targetRoot: string): string | null {
+  const p = join(targetRoot, 'node_modules', 'cross-spawn', 'package.json')
+  if (!existsSync(p)) return null
+  try {
+    const v = (JSON.parse(stripBom(readFileSync(p, 'utf8'))) as { version?: unknown }).version
+    return typeof v === 'string' && semver.valid(v) ? v : null
+  } catch {
+    return null
+  }
+}
+
+/** lockfile 해소 cross-spawn 버전(package-lock v2/v3 JSON 우선, pnpm/yarn best-effort). 없으면 null. */
+function lockedCrossSpawnVersion(targetRoot: string): string | null {
+  const pl = join(targetRoot, 'package-lock.json')
+  if (existsSync(pl)) {
+    try {
+      const j = JSON.parse(stripBom(readFileSync(pl, 'utf8'))) as {
+        packages?: Record<string, { version?: unknown }>
+        dependencies?: Record<string, { version?: unknown }>
+      }
+      const v = j.packages?.['node_modules/cross-spawn']?.version ?? j.dependencies?.['cross-spawn']?.version
+      if (typeof v === 'string' && semver.valid(v)) return v
+    } catch {
+      /* best-effort */
+    }
+  }
+  for (const [file, re] of [
+    ['pnpm-lock.yaml', /cross-spawn@(\d+\.\d+\.\d+)/],
+    ['yarn.lock', /(?:^|\n)"?cross-spawn@[^\n]*:[\s\S]*?\n\s+version:?\s+"?(\d+\.\d+\.\d+)"?/],
+  ] as const) {
+    const fp = join(targetRoot, file)
+    if (!existsSync(fp)) continue
+    try {
+      const m = readFileSync(fp, 'utf8').match(re)
+      if (m?.[1] && semver.valid(m[1])) return m[1]
+    } catch {
+      /* best-effort */
+    }
+  }
+  return null
+}
+
+/**
+ * 기존 cross-spawn이 보안 하한 미만인지 판정(#1). 우선순위: **설치버전 → lockfile 해소버전 → range**.
+ * range fallback은 `>=floor`로 절대 해소 불가한 spec만 below로 본다(‘^7.0.0’·‘~7.0.1’ 오탐 방지 — R1 P2).
+ * 기존 cross-spawn 없으면 null(우리가 `^7.0.6` 주입 → 진단 불필요).
+ */
+export function crossSpawnBelowFloor(
+  targetRoot: string,
+  pkg: Record<string, unknown>,
+): { below: boolean; detail: string } | null {
+  if (!CROSS_SPAWN_FLOOR) return null // 이론상 도달 불가(REQ_DEV_DEPS 고정값)
+  const floor = CROSS_SPAWN_FLOOR.version
+  const spec = existingCrossSpawnSpec(pkg)
+  if (!spec) return null
+
+  const installed = installedCrossSpawnVersion(targetRoot)
+  if (installed) return { below: semver.lt(installed, floor), detail: `설치버전 ${installed}` }
+
+  const locked = lockedCrossSpawnVersion(targetRoot)
+  if (locked) return { below: semver.lt(locked, floor), detail: `lockfile ${locked}` }
+
+  if (semver.validRange(spec)) return { below: !semver.intersects(spec, `>=${floor}`), detail: `범위 ${spec}` }
+  return { below: false, detail: `범위 ${spec}(파싱 불가 — 무경고)` }
+}
+
 /**
  * 설치 코어. IO는 여기서만(테스트가 임시 repo로 직접 호출).
  * **Preflight(전 검증·파싱) → Apply(쓰기) 2단계** — malformed 입력에 대해 어떤 파일도 복사·수정하기 전에 실패한다(부분 설치 방지, design R2 P2).
@@ -161,11 +253,23 @@ export function runInit(opts: InitOptions): InitResult {
     scripts?: Record<string, string>
     devDependencies?: Record<string, string>
   }
-  // scripts·devDependencies가 존재하면 반드시 plain object — 배열/원시면 patch가 조용히 유실되어(성공 보고인데 req:* 미주입) fail-closed 위반(phase R1 P2).
-  for (const field of ['scripts', 'devDependencies'] as const) {
+  // scripts·devDependencies·dependencies가 존재하면 반드시 plain object — 배열/원시면 patch 유실(scripts/devDeps, phase R1 P2)
+  // 또는 cross-spawn 진단(dependencies, design R1 P3) 오동작. 읽기 전에 shape 검증(fail-closed).
+  for (const field of ['scripts', 'devDependencies', 'dependencies'] as const) {
     const v = (pkg as Record<string, unknown>)[field]
     if (v !== undefined && (typeof v !== 'object' || v === null || Array.isArray(v)))
-      throw new Error(`package.json의 ${field} 필드가 객체가 아님(${pkgPath}) — req:* 주입 불가(배열/원시 미지원).`)
+      throw new Error(`package.json의 ${field} 필드가 객체가 아님(${pkgPath}) — 배열/원시 미지원.`)
+  }
+
+  // cross-spawn 보안 하한 진단(#1): 기존 cross-spawn이 하한 미만이면 WARN(기본)/throw(--strict). preflight라 strict throw 시 부분 설치 없음.
+  let crossSpawnFloorWarned = false
+  const floorCheck = crossSpawnBelowFloor(targetRoot, pkg as Record<string, unknown>)
+  if (floorCheck?.below) {
+    const spec = CROSS_SPAWN_SPEC
+    const msg = `기존 cross-spawn(${floorCheck.detail})이 보안 하한 >=${CROSS_SPAWN_FLOOR?.version} 미만 — CommitGate 안전 경계(safeSpawnSync)는 ${spec} 검증분입니다. 'npm i -D cross-spawn@${spec}' 권장.`
+    if (opts.strict) throw new Error(`[--strict] ${msg}`)
+    console.warn(`⚠️  ${msg} (설치는 계속 — 강제 중단하려면 --strict)`)
+    crossSpawnFloorWarned = true
   }
 
   const cfgPath = join(targetRoot, 'req.config.json')
@@ -247,6 +351,7 @@ export function runInit(opts: InitOptions): InitResult {
     packageJsonAdded,
     agentsCreated,
     packageManager,
+    crossSpawnFloorWarned,
     dryRun: opts.dryRun,
   }
 }
@@ -255,6 +360,7 @@ export function parseArgs(argv: string[]): InitOptions {
   let dir = process.cwd()
   let force = false
   let dryRun = false
+  let strict = false
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--dir') {
@@ -266,6 +372,8 @@ export function parseArgs(argv: string[]): InitOptions {
       force = true
     } else if (a === '--dry-run') {
       dryRun = true
+    } else if (a === '--strict') {
+      strict = true
     } else if (a === '-h' || a === '--help') {
       printHelp()
       process.exit(0)
@@ -273,7 +381,7 @@ export function parseArgs(argv: string[]): InitOptions {
       throw new Error(`알 수 없는 인자: ${a}`)
     }
   }
-  return { dir: resolve(dir), force, dryRun }
+  return { dir: resolve(dir), force, dryRun, strict }
 }
 
 function printHelp(): void {
@@ -286,6 +394,7 @@ function printHelp(): void {
   --dir <path>   대상 repo 루트(기본: 현재 디렉터리)
   --force        기존 kit 파일 덮어쓰기(기본: 스킵)
   --dry-run      변경 없이 수행 예정 목록만 출력
+  --strict       기존 cross-spawn이 보안 하한(>=7.0.6) 미만이면 경고 대신 중단(fail-closed)
   -h, --help     도움말
 
 설치 후:
@@ -315,6 +424,7 @@ export function main(argv: string[]): void {
     `${tag}  package.json: ${r.packageJsonAdded.length > 0 ? '추가 ' + r.packageJsonAdded.join(', ') : '변경 없음'}`,
   )
   console.log(`${tag}  AGENTS.md: ${r.agentsCreated ? '템플릿 생성' : '이미 존재(유지)'}`)
+  if (r.crossSpawnFloorWarned) console.log(`${tag}  ⚠️ cross-spawn 버전 하한 경고(위 참조) — 강제 중단은 --strict`)
   if (!r.dryRun) {
     console.log(`\n다음:`)
     console.log(`  1. cd ${r.targetRoot} && ${r.packageManager} install`)

package/package.json

@@ -1,63 +1,66 @@
-{
-  "name": "commitgate",
-  "version": "0.1.2",
-  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
-  "type": "module",
-  "license": "MIT",
-  "author": "sol5288",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sol5288/commitgate.git"
-  },
-  "homepage": "https://github.com/sol5288/commitgate#readme",
-  "bugs": {
-    "url": "https://github.com/sol5288/commitgate/issues"
-  },
-  "keywords": [
-    "ai",
-    "code-review",
-    "workflow",
-    "codex",
-    "claude",
-    "git",
-    "commit-gate",
-    "fail-closed",
-    "review-gate",
-    "cli"
-  ],
-  "bin": {
-    "commitgate": "bin/commitgate.mjs"
-  },
-  "scripts": {
-    "req:new": "tsx scripts/req/req-new.ts",
-    "req:review-codex": "tsx scripts/req/review-codex.ts",
-    "req:doctor": "tsx scripts/req/req-doctor.ts",
-    "req:commit": "tsx scripts/req/req-commit.ts",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "files": [
-    "scripts",
-    "workflow/machine.schema.json",
-    "workflow/req.config.schema.json",
-    "bin",
-    "AGENTS.template.md",
-    "req.config.json.sample",
-    "README.md",
-    "README.en.md"
-  ],
-  "engines": {
-    "node": ">=18.17"
-  },
-  "dependencies": {
-    "ajv": "^8.20.0",
-    "cross-spawn": "^7.0.6",
-    "tsx": "^4.19.1"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^22.7.4",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.2"
-  }
-}
+{
+  "name": "commitgate",
+  "version": "0.2.1",
+  "description": "CommitGate — Builder↔Reviewer(Claude↔Codex) fail-closed 커밋 게이트: 리뷰·승인·증거 없인 커밋을 통과시키지 않는 AI REQ 워크플로 kit (req:new/review-codex/doctor/commit)",
+  "type": "module",
+  "license": "MIT",
+  "author": "sol5288",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sol5288/commitgate.git"
+  },
+  "homepage": "https://github.com/sol5288/commitgate#readme",
+  "bugs": {
+    "url": "https://github.com/sol5288/commitgate/issues"
+  },
+  "keywords": [
+    "ai",
+    "code-review",
+    "workflow",
+    "codex",
+    "claude",
+    "git",
+    "commit-gate",
+    "fail-closed",
+    "review-gate",
+    "cli"
+  ],
+  "bin": {
+    "commitgate": "bin/commitgate.mjs"
+  },
+  "scripts": {
+    "req:new": "tsx scripts/req/req-new.ts",
+    "req:review-codex": "tsx scripts/req/review-codex.ts",
+    "req:doctor": "tsx scripts/req/req-doctor.ts",
+    "req:commit": "tsx scripts/req/req-commit.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "files": [
+    "scripts/req",
+    "workflow/machine.schema.json",
+    "workflow/req.config.schema.json",
+    "bin",
+    "AGENTS.template.md",
+    "req.config.json.sample",
+    "README.md",
+    "README.en.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "cross-spawn": "^7.0.6",
+    "semver": "^7.6.3",
+    "tsx": "^4.19.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.7.4",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  }
+}