commitgate 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "commitgate",
+  "version": "0.1.0",
+  "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"
+  ],
+  "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"
+  }
+}

package/req.config.json.sample

@@ -0,0 +1,13 @@
+{
+  "ticketRoot": "workflow",
+  "schemaPath": "workflow/machine.schema.json",
+  "handoffPath": null,
+  "branchPrefix": "feat/req-",
+  "packageManager": "npm",
+  "granularityMaxFiles": 8,
+  "designDocs": {
+    "requirement": "00-requirement.md",
+    "design": "01-design.md",
+    "plan": "02-plan.md"
+  }
+}

package/scripts/req/lib/adapters.ts

@@ -0,0 +1,139 @@
+/**
+ * req 워크플로 어댑터 모듈 (REQ-2026-017 Phase 3, portability kit).
+ *
+ * 목적: git·codex(reviewer) 호출을 **얇은 경계 인터페이스**로 추상화 — plumbing 로직·승인 바인딩은 불변.
+ *   - GitAdapter: 모든 git 호출을 단일 경계로(default = execFileSync('git', …, {cwd: root})). 비-git VCS는 후속 확장 여지.
+ *   - ReviewerAdapter: codex 호출(exec/resume + thread 파싱 + --output-last-message)을 단일 경계로. 테스트는 FakeReviewerAdapter로 live codex 없이 검증.
+ *
+ * 안전(fail-closed): codex 미설치/실패는 default 구현이 그대로 throw(silent 금지, D-017-4·D-017-7).
+ * 본 모듈은 req 스크립트에 의존하지 않는 leaf(순환 의존 금지) — parseThreadId도 여기로 이동(codex CLI 전용 로직).
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import spawn from 'cross-spawn'
+
+// ─────────────────────────────────────────────── 안전 spawn (P1) ──
+
+/** safeSpawnSync 옵션(필요분만). stdio 미지정 = 'pipe'(stdout 반환). */
+export interface SafeSpawnOptions {
+  cwd?: string
+  input?: string
+  stdio?: 'pipe' | 'inherit'
+  maxBuffer?: number
+}
+
+/**
+ * 크로스플랫폼 **안전** 동기 spawn. cross-spawn으로 **shell 없이** 실행한다.
+ * - 인자의 shell 메타문자(`& | < > ^ " ' 백틱 $ ; ( ) ! %` 등)가 별도 명령으로 해석되지 않는다(명령 주입 차단).
+ * - 공백 포함 경로도 올바르게 전달된다(shell:true는 인용을 안 해 깨졌음).
+ * - Windows의 `.cmd` 래퍼(codex·npm·pnpm·yarn)도 안전하게 해소한다(과거 `shell:true`가 필요했던 이유를 대체).
+ * 실패(spawn 오류·exit≠0)면 throw(fail-closed — 기존 execFileSync 의미 보존).
+ */
+export function safeSpawnSync(file: string, args: readonly string[], opts: SafeSpawnOptions = {}): string {
+  const res = spawn.sync(file, args as string[], {
+    cwd: opts.cwd,
+    input: opts.input,
+    stdio: opts.stdio ?? 'pipe',
+    maxBuffer: opts.maxBuffer ?? 64 * 1024 * 1024,
+  })
+  if (res.error) throw res.error
+  if (res.status !== 0) {
+    const err = res.stderr ? res.stderr.toString('utf8') : ''
+    throw new Error(`명령 실패(exit=${res.status ?? 'null'}): ${file}\n${err}`.trim())
+  }
+  return res.stdout ? res.stdout.toString('utf8') : ''
+}
+
+// ──────────────────────────────────────────────────────────── Git ──
+
+/** git 호출 경계(D-017-3). exec(args) = trim된 stdout, 실패 시 throw(fail-closed). */
+export interface GitAdapter {
+  exec(args: string[]): string
+}
+
+/** GitAdapter default 구현의 내부 실행자(주입 가능 — 테스트). encoding:'utf8'이라 string 반환. */
+export type GitRunner = (file: string, args: string[], opts: { cwd: string; encoding: 'utf8' }) => string
+const defaultGitRunner: GitRunner = (file, args, opts) => execFileSync(file, args, opts)
+
+/**
+ * default GitAdapter — `execFileSync('git', args, {cwd: root, encoding:'utf8'})` 후 **trailing 공백만 제거**.
+ * ⚠️ `.trim()`이 아니라 `.replace(/\s+$/, '')` — `git status --porcelain`의 **선행 공백(XY 코드)**을 보존(behavior-preserving).
+ */
+export function createGitAdapter(root: string, run: GitRunner = defaultGitRunner): GitAdapter {
+  return { exec: (args) => run('git', args, { cwd: root, encoding: 'utf8' }).replace(/\s+$/, '') }
+}
+
+// ─────────────────────────────────────────────── Reviewer (codex) ──
+
+export interface ReviewRequest {
+  prompt: string
+  schemaPath: string
+  resumeThreadId: string | null
+  cwd: string
+}
+export interface ReviewResult {
+  rawStdout: string
+  lastMessage: string
+  threadId: string | null
+}
+/** codex 리뷰 경계(D-017-4). default=codex CLI, 테스트=FakeReviewerAdapter. */
+export interface ReviewerAdapter {
+  review(req: ReviewRequest): ReviewResult
+}
+
+/** `codex exec --json` JSONL에서 thread.started.thread_id 추출(0차 실측). 없으면 null. (review-codex에서 이동) */
+export function parseThreadId(jsonl: string): string | null {
+  for (const line of jsonl.split('\n')) {
+    const t = line.trim()
+    if (!t) continue
+    try {
+      const ev = JSON.parse(t) as { type?: string; thread_id?: string }
+      if (ev.type === 'thread.started' && typeof ev.thread_id === 'string') return ev.thread_id
+    } catch {
+      // JSONL 외 라인 무시
+    }
+  }
+  return null
+}
+
+/** codex 실행자(주입 가능 — 테스트). stdout 반환, 실패 시 throw. */
+export type CodexRunner = (args: string[], input: string, cwd: string) => string
+const defaultCodexRunner: CodexRunner = (args, input, cwd) =>
+  // shell 없이 안전 실행(safeSpawnSync/cross-spawn). 프롬프트는 stdin(input)으로 전달.
+  // ⚠️ 과거 `shell:true`는 args(schemaPath·resumeThreadId 등)의 메타문자로 **명령 주입**이 가능했고 공백 경로도 깨졌음 — P1 수정.
+  safeSpawnSync('codex', args, { cwd, input, maxBuffer: 64 * 1024 * 1024 })
+
+/**
+ * default ReviewerAdapter(codex CLI). exec(신규)/resume(thread_id) 분기 + `--output-last-message`(임시파일) 캡처 + thread 파싱.
+ * - resume은 `--sandbox` 미수용(0차 실측) → 생략(정책 상속). exec은 `--sandbox read-only`.
+ * - threadId: resume이면 resumeThreadId, exec이면 parseThreadId(stdout)(없으면 null → 호출처가 fail-closed).
+ * - codex 미설치/실패 → runner가 throw(그대로 전파, fail-closed).
+ */
+export function createCodexReviewerAdapter(run: CodexRunner = defaultCodexRunner): ReviewerAdapter {
+  return {
+    review({ prompt, schemaPath, resumeThreadId, cwd }) {
+      const lastPath = join(mkdtempSync(join(tmpdir(), 'req-codex-')), 'last.json')
+      const args = resumeThreadId
+        ? ['exec', 'resume', resumeThreadId, '--json', '--output-schema', schemaPath, '--output-last-message', lastPath, '-']
+        : ['exec', '--json', '--sandbox', 'read-only', '--output-schema', schemaPath, '--output-last-message', lastPath, '-']
+      const rawStdout = run(args, prompt, cwd)
+      const threadId = resumeThreadId ?? parseThreadId(rawStdout)
+      const lastMessage = existsSync(lastPath) ? readFileSync(lastPath, 'utf8') : ''
+      return { rawStdout, lastMessage, threadId }
+    },
+  }
+}
+
+/** 테스트 전용 ReviewerAdapter — canned 응답 반환 + 받은 요청 기록(live codex 없이 review-codex 플로 검증, 수용기준 #4). */
+export function createFakeReviewerAdapter(result: ReviewResult): ReviewerAdapter & { requests: ReviewRequest[] } {
+  const requests: ReviewRequest[] = []
+  return {
+    requests,
+    review(req: ReviewRequest): ReviewResult {
+      requests.push(req)
+      return result
+    },
+  }
+}

package/scripts/req/lib/config.ts

@@ -0,0 +1,177 @@
+/**
+ * req 워크플로 config 모듈 (REQ-2026-017 Phase 1, portability kit).
+ *
+ * 목적: 경로·이름·패키지매니저를 `req.config.json`으로 외부화하되, **파일 부재 시 현재 동작 100% 유지**(DEFAULTS=현재 하드코딩 값).
+ * 본 Phase는 **모듈만** 제공 — 4 스크립트 배선·`--root` CLI는 Phase 2, 어댑터는 Phase 3.
+ *
+ * 안전(fail-closed): config가 게이트를 무력화하거나 경로를 탈출하지 못하도록 AJV 스키마 + 해상도 confinement로 강제.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, join, dirname, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Ajv from 'ajv'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export type PackageManager = 'pnpm' | 'npm' | 'yarn'
+
+export interface DesignDocs {
+  requirement: string
+  design: string
+  plan: string
+}
+
+/** 사용자가 `req.config.json`에 줄 수 있는 부분 config(전부 선택). */
+export interface RawConfig {
+  ticketRoot?: string
+  schemaPath?: string
+  handoffPath?: string | null
+  branchPrefix?: string
+  packageManager?: PackageManager
+  granularityMaxFiles?: number
+  designDocs?: Partial<DesignDocs>
+}
+
+/** 해소된 config(DEFAULTS 병합 + 파생 절대경로). */
+export interface ResolvedConfig {
+  root: string
+  ticketRoot: string
+  schemaPath: string
+  handoffPath: string | null
+  branchPrefix: string
+  packageManager: PackageManager
+  granularityMaxFiles: number
+  designDocs: DesignDocs
+  // 파생(절대경로)
+  workflowDirAbs: string
+  schemaPathAbs: string
+  handoffPathAbs: string | null
+}
+
+/** ⚠️ 현재 하드코딩 값 — 변경 시 behavior-preserving(수용기준 #1) 깨짐. */
+export const DEFAULTS = {
+  ticketRoot: 'workflow',
+  schemaPath: 'workflow/machine.schema.json',
+  handoffPath: '../palm-kiosk/docs/evaluation/project-memory/ai-handoff.md',
+  branchPrefix: 'feat/req-',
+  packageManager: 'pnpm' as PackageManager,
+  granularityMaxFiles: 8,
+  designDocs: { requirement: '00-requirement.md', design: '01-design.md', plan: '02-plan.md' } as DesignDocs,
+}
+
+const BASENAME_RE = '^[A-Za-z0-9][A-Za-z0-9._-]*$' // basename만(슬래시·백슬래시·선행 `.`(→`..`) 금지)
+
+/** `req.config.json` AJV 스키마(fail-closed). 미지정 키는 DEFAULTS로 병합. */
+export const CONFIG_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    ticketRoot: { type: 'string', minLength: 1 },
+    schemaPath: { type: 'string', minLength: 1 },
+    handoffPath: { type: ['string', 'null'] },
+    branchPrefix: { type: 'string', minLength: 1 }, // 빈 prefix는 D11 무력화 → 금지
+    packageManager: { type: 'string', enum: ['pnpm', 'npm', 'yarn'] },
+    granularityMaxFiles: { type: 'integer', minimum: 1 },
+    designDocs: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        requirement: { type: 'string', pattern: BASENAME_RE },
+        design: { type: 'string', pattern: BASENAME_RE },
+        plan: { type: 'string', pattern: BASENAME_RE },
+      },
+    },
+  },
+} as const
+
+const ajv = new Ajv({ allErrors: true })
+const validateConfig = ajv.compile(CONFIG_SCHEMA)
+
+/** kit 패키지 루트(= 현재 APP_ROOT와 동일 디렉터리). config.ts는 scripts/req/lib/ 이므로 3단계 상위. */
+export function packageRoot(): string {
+  return resolve(__dirname, '..', '..', '..')
+}
+
+/**
+ * root 해소(순수에 가깝게, IO=existsSync만). 우선순위: ① `--root`(opts.root) → ② cwd 상향탐색으로 `req.config.json` 발견 → ③ package-root fallback.
+ */
+export function resolveRoot(opts: { root?: string | null; cwd?: string } = {}): string {
+  if (opts.root) return resolve(opts.root)
+  let dir = resolve(opts.cwd ?? process.cwd())
+  for (;;) {
+    if (existsSync(join(dir, 'req.config.json'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break // 파일시스템 루트
+    dir = parent
+  }
+  return packageRoot()
+}
+
+/** 절대경로(POSIX `/`·Windows `C:\`·드라이브상대·UNC `\\`)면 throw — repo-내부 자원은 상대경로만(portable). */
+function assertRelative(rel: string, name: string): void {
+  if (/^([/\\]|[A-Za-z]:)/.test(rel)) throw new Error(`req.config: ${name}는 절대경로 불가(repo-상대만): ${rel}`)
+}
+
+/** abs가 rootAbs 하위인지(자기 자신 포함). 탈출 시 throw. */
+function assertUnderRoot(rootAbs: string, rel: string, name: string): void {
+  const abs = resolve(rootAbs, rel)
+  if (abs !== rootAbs && !abs.startsWith(rootAbs + sep)) throw new Error(`req.config: ${name}가 root 밖으로 탈출: ${rel}`)
+}
+
+/** UTF-8 BOM(U+FEFF) 제거 — PowerShell 5 `Set-Content -Encoding UTF8` 등이 BOM을 붙여 JSON.parse가 실패하는 것 방지(P3). */
+export function stripBom(s: string): string {
+  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s
+}
+
+/**
+ * config 로드(fail-closed). root 결정 → `<root>/req.config.json` 있으면 파싱+AJV 검증+confinement → DEFAULTS 병합 → 파생경로.
+ * 파일 부재 시 DEFAULTS만(현재 동작). 위반은 명확한 throw(자동 보정·기본값 강등 금지).
+ */
+export function loadConfig(opts: { root?: string | null; cwd?: string } = {}): ResolvedConfig {
+  const rootAbs = resolveRoot(opts)
+  const cfgPath = join(rootAbs, 'req.config.json')
+  let raw: RawConfig = {}
+  if (existsSync(cfgPath)) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(stripBom(readFileSync(cfgPath, 'utf8')))
+    } catch (e) {
+      throw new Error(`req.config.json 파싱 실패(${cfgPath}): ${(e as Error).message}`)
+    }
+    if (!validateConfig(parsed)) throw new Error(`req.config.json 스키마 위반: ${ajv.errorsText(validateConfig.errors)}`)
+    raw = parsed as RawConfig
+  }
+
+  const merged = {
+    ticketRoot: raw.ticketRoot ?? DEFAULTS.ticketRoot,
+    schemaPath: raw.schemaPath ?? DEFAULTS.schemaPath,
+    handoffPath: raw.handoffPath !== undefined ? raw.handoffPath : DEFAULTS.handoffPath, // null = 명시적 비활성
+    branchPrefix: raw.branchPrefix ?? DEFAULTS.branchPrefix,
+    packageManager: raw.packageManager ?? DEFAULTS.packageManager,
+    granularityMaxFiles: raw.granularityMaxFiles ?? DEFAULTS.granularityMaxFiles,
+    designDocs: { ...DEFAULTS.designDocs, ...(raw.designDocs ?? {}) },
+  }
+
+  // repo-내부 자원(ticketRoot·schemaPath)은 **상대경로 + root 하위**만(절대경로·탈출 금지 → portable). handoffPath는 읽기 전용 참조라 면제.
+  assertRelative(merged.ticketRoot, 'ticketRoot')
+  assertRelative(merged.schemaPath, 'schemaPath')
+  assertUnderRoot(rootAbs, merged.ticketRoot, 'ticketRoot')
+  assertUnderRoot(rootAbs, merged.schemaPath, 'schemaPath')
+
+  return {
+    root: rootAbs,
+    ...merged,
+    workflowDirAbs: resolve(rootAbs, merged.ticketRoot),
+    schemaPathAbs: resolve(rootAbs, merged.schemaPath),
+    handoffPathAbs: merged.handoffPath ? resolve(rootAbs, merged.handoffPath) : null,
+  }
+}
+
+/**
+ * 패키지매니저별 스크립트 호출 argv 빌더(순수). 문자열 치환만으론 npm 불가.
+ * pnpm/yarn → `[pm, script, ...args]`, npm → `[npm, run, script, --, ...args]`.
+ */
+export function buildScriptInvocation(pm: PackageManager, scriptName: string, args: string[]): string[] {
+  if (pm === 'npm') return ['npm', 'run', scriptName, '--', ...args]
+  return [pm, scriptName, ...args]
+}