@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/codex-agents.js

@@ -0,0 +1,189 @@
+'use strict';
+const guards = require("./guards");
+const { isRecord } = guards;
+const fs = require('node:fs');
+const path = require('node:path');
+const frontmatter = require("./frontmatter");
+const { parseFrontmatter } = frontmatter;
+const layout = require("./layout");
+const { CODEX_AGENTS_DIR } = layout;
+const pluginRoot = require("./plugin-root");
+const { resolvePluginAssetRoot } = pluginRoot;
+const NAMED_AGENTS = [
+    'bouncer-reviewer',
+    'bouncer-implementer',
+    'bouncer-debugger',
+    'bouncer-context-reviewer',
+    'bouncer-coordinator',
+];
+// 이 마커가 첫 줄이면 init이 플러그인 md와 다시 맞춘다. 마커 없는 파일은
+// 사용자 소유로 보고 덮지 않는다 — Codex는 플러그인 디렉터리를 스캔하지
+// 않으므로 이 사본이 유일한 로드 경로다.
+const GENERATED_MARKER = '# bouncer-generated';
+/**
+ * 플러그인 루트의 `agents/` 절대 경로를 돌려준다. print 디스패치와 Codex
+ * 시드가 같은 기준을 써야 역할 문서와 TOML 소스가 갈라지지 않는다.
+ *
+ * @returns {string} 검증된 자산 루트(`resolvePluginAssetRoot`) 아래의 `agents/`
+ * @throws 자산 루트를 해석하지 못하면 resolver의 Error를 그대로 던진다
+ */
+function pluginAgentsDir() {
+    return path.join(resolvePluginAssetRoot(), 'agents');
+}
+/**
+ * Claude/Cursor/Antigravity용 `agents/*.md`를 Codex custom-agent TOML로 바꾼다.
+ * `model: inherit`는 키를 생략해 부모 세션 모델을 쓰게 한다.
+ *
+ * @param {string} markdown - YAML frontmatter가 있는 에이전트 문서
+ * @returns {string} Codex가 `.codex/agents/`에서 읽는 TOML
+ */
+function mdToCodexToml(markdown) {
+    const { data, body } = parseFrontmatter(markdown);
+    if (!isRecord(data)) {
+        throw new Error('agent frontmatter must be a mapping');
+    }
+    const name = data.name;
+    const description = data.description;
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error('agent name required');
+    }
+    if (typeof description !== 'string' || description.length === 0) {
+        throw new Error('agent description required');
+    }
+    const lines = [
+        GENERATED_MARKER,
+        `# Source: agents/${name}.md`,
+        '',
+        `name = ${JSON.stringify(name)}`,
+        `description = ${JSON.stringify(description)}`,
+    ];
+    if (data.readonly === true) {
+        lines.push('sandbox_mode = "read-only"');
+    }
+    const instructions = String(body).replace(/^\n+/, '').replace(/\n+$/, '');
+    lines.push('developer_instructions = """');
+    lines.push(instructions.replace(/"""/g, '\\"""'));
+    lines.push('"""');
+    lines.push('');
+    return lines.join('\n');
+}
+function shouldRefresh(existing, next) {
+    const first = existing.split(/\r?\n/, 1)[0];
+    if (first !== GENERATED_MARKER)
+        return false;
+    return existing !== next;
+}
+/**
+ * 로컬 `.codex/agents/<name>.toml`이 플러그인 md 생성본과 바이트 일치하는지
+ * 읽기만으로 판정한다. 파일을 만들지 않고, 마커 없는 사용자 파일은
+ * mismatch가 아니라 not-generated로 돌려 seed가 덮을 대상이 아님을 드러낸다.
+ *
+ * @param {{ repoRoot: string, agentName: string, agentsDir?: string }} opts
+ * @param {string} opts.repoRoot - 소비 저장소 루트
+ * @param {string} opts.agentName - `.toml` 파일 stem (예: bouncer-implementer)
+ * @param {string} [opts.agentsDir] - md 소스 디렉터리. 생략 시 플러그인 agents/
+ * @returns {CodexAgentCheckOk | CodexAgentCheckFail} ok면 in_sync·path, 아니면 reason·path
+ */
+function checkCodexAgent({ repoRoot, agentName, agentsDir, }) {
+    // 1. 상대 posix 경로를 JSON 계약의 path로 고정한다. OS 구분자로 바꾸면
+    //    에이전트가 `.codex/agents/<name>.toml` 리터럴을 찾지 못한다.
+    const rel = `${CODEX_AGENTS_DIR}/${agentName}.toml`;
+    const dest = path.join(repoRoot, rel);
+    if (!fs.existsSync(dest)) {
+        return { ok: false, in_sync: false, reason: 'missing', path: rel };
+    }
+    const existing = fs.readFileSync(dest, 'utf8');
+    // 2. 첫 줄만 본다. shouldRefresh와 같이 마커 없는 파일은 사용자 소유라
+    //    생성본과 비교하지 않는다 — 내용이 같아도 seed 대상이 아니다.
+    const first = existing.split(/\r?\n/, 1)[0];
+    if (first !== GENERATED_MARKER) {
+        return { ok: false, in_sync: false, reason: 'not-generated', path: rel };
+    }
+    // 3. 생성 기준은 ensureCodexAgents와 같은 mdToCodexToml이다. 변환을
+    //    여기서 다시 구현하면 seed와 check가 다른 바이트를 정본으로 삼는다.
+    const srcDir = agentsDir ?? pluginAgentsDir();
+    const next = mdToCodexToml(fs.readFileSync(path.join(srcDir, `${agentName}.md`), 'utf8'));
+    if (existing !== next) {
+        return { ok: false, in_sync: false, reason: 'mismatch', path: rel };
+    }
+    return { ok: true, in_sync: true, path: rel };
+}
+/**
+ * init이 `.codex/agents/*.toml`을 심을지. 호스트 이름·환경 변수는 신호가
+ * 아니다 — Claude-only 저장소에 빈 `.codex/`가 생기는 일을 막기 위해
+ * 디렉터리 존재 또는 명시적 opt-in만 본다.
+ *
+ * @param {string} repoRoot - 소비 저장소 루트
+ * @param {boolean} [optIn=false] - CLI `--seed-codex-agents` 등 명시 요청
+ * @returns {boolean}
+ */
+function shouldEnsureCodexAgents(repoRoot, optIn = false) {
+    if (optIn === true)
+        return true;
+    try {
+        return fs.statSync(path.join(repoRoot, '.codex')).isDirectory();
+    }
+    catch (_e) {
+        return false;
+    }
+}
+/**
+ * 소비 저장소 `.codex/agents/<name>.toml`을 심거나, 생성본이면 md와 맞춘다.
+ * 호출 측이 조건을 통과한 뒤에만 부른다. 조건 없이 호출하면 named agent
+ * 전부의 TOML을 심거나 생성본을 맞춘다. 플러그인 agents 디렉터리가 없으면 no-op —
+ * init 부트스트랩을 막지 않는다.
+ *
+ * @param {{ repoRoot: string, created: string[], agentsDir?: string }} opts
+ * @returns {void}
+ */
+function ensureCodexAgents({ repoRoot, created, agentsDir, }) {
+    let srcDir;
+    if (agentsDir !== undefined) {
+        srcDir = agentsDir;
+    }
+    else {
+        try {
+            srcDir = pluginAgentsDir();
+        }
+        catch (error) {
+            // resolver가 던지는 Error(무효 BOUNCER_HOME, 유효 루트 없음)만 흡수한다. 자산이 없으면
+            // 아래 existsSync 분기처럼 시드를 건너뛰는 것이 원래 계약이다. 그 외는 다시 던진다.
+            if (!(error instanceof Error))
+                throw error;
+            if ('code' in error && error.code === 'BOUNCER_PLUGIN_VERSION_MISMATCH')
+                throw error;
+            return;
+        }
+    }
+    if (!fs.existsSync(srcDir))
+        return;
+    const destDir = path.join(repoRoot, CODEX_AGENTS_DIR);
+    for (const name of NAMED_AGENTS) {
+        const src = path.join(srcDir, `${name}.md`);
+        if (!fs.existsSync(src))
+            continue;
+        const next = mdToCodexToml(fs.readFileSync(src, 'utf8'));
+        const rel = `${CODEX_AGENTS_DIR}/${name}.toml`;
+        const dest = path.join(repoRoot, rel);
+        if (fs.existsSync(dest)) {
+            const existing = fs.readFileSync(dest, 'utf8');
+            if (!shouldRefresh(existing, next))
+                continue;
+            fs.writeFileSync(dest, next);
+            continue;
+        }
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.writeFileSync(dest, next);
+        created.push(rel);
+    }
+}
+module.exports = {
+    NAMED_AGENTS,
+    GENERATED_MARKER,
+    CODEX_AGENTS_DIR,
+    pluginAgentsDir,
+    mdToCodexToml,
+    checkCodexAgent,
+    ensureCodexAgents,
+    shouldEnsureCodexAgents,
+};

package/dist/command-argv.js

@@ -0,0 +1,125 @@
+'use strict';
+// argv 검사 leaf 모듈. verification.ts가 의존 모듈이 많아, 같은 검사를 쓰려는
+// seed-worktree가 verification을 가져오면 import 순환 위험이 있다. 그래서 node
+// 내장 모듈과 config의 기본 허용 목록만 가져오는 이 모듈로 분리했다.
+const path = require('node:path');
+const config = require("./config");
+const { DEFAULT_VERIFY_ALLOWLIST } = config;
+// 실행 가능한 argv 문자열 하나만: 셸 체이닝, 리다이렉션, `cd` 접두사 없음.
+// Plan S12와 runtime VERIFY_COMMAND_INVALID가 parseVerifyArgv·allowlist를
+// 공유하므로 두 표면이 어긋날 수 없습니다.
+/**
+ * 검증 명령 문자열을 argv 배열로 파싱한다. 공백으로 나누되 작은따옴표·
+ * 큰따옴표 안의 공백은 한 인자로 유지한다. 셸 확장은 하지 않는다 —
+ * `shell: false` 실행과 같은 경계를 파싱 단계에서도 맞춘다.
+ *
+ * 메타문자 검사는 인용 **밖**에서만 한다. `node -e "a; b"`처럼 인자 안의
+ * `;`는 데이터이고, 인용 밖 `a; b`만 체이닝으로 거절해야 예전 config.verify
+ * 문자열과 실행 의미가 어긋나지 않는다.
+ *
+ * @param {unknown} command - `tasks.bouncer.verify` 또는 `config.verify` 문자열
+ * @returns {string[] | null} 성공 시 argv. 빈 값·메타문자·미종료 인용·`cd` 접두면 null
+ */
+function parseVerifyArgv(command) {
+    if (typeof command !== 'string')
+        return null;
+    const trimmed = command.trim();
+    if (!trimmed)
+        return null;
+    const argv = [];
+    let current = '';
+    let quote = null;
+    let sawToken = false;
+    for (let i = 0; i < trimmed.length; i += 1) {
+        const ch = trimmed[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+                sawToken = true;
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        // 인용 밖의 셸 메타·개행·$( 만 거절. 인자 값에 든 동일 문자는 허용.
+        if (ch === '$' && trimmed[i + 1] === '(')
+            return null;
+        if (/[&|;`<>\n]/.test(ch))
+            return null;
+        if (/\s/.test(ch)) {
+            if (sawToken || current.length > 0) {
+                argv.push(current);
+                current = '';
+                sawToken = false;
+            }
+            continue;
+        }
+        current += ch;
+        sawToken = true;
+    }
+    if (quote)
+        return null;
+    if (sawToken || current.length > 0) {
+        argv.push(current);
+    }
+    if (argv.length === 0)
+        return null;
+    // basename이 아니라 원본 argv0가 cd면 거절한다. `cd`는 셸 내장이고
+    // shell:false로도 의미가 없으며, 예전 S12 계약(`cd` 접두 금지)을 유지한다.
+    if (argv[0] === 'cd')
+        return null;
+    return argv;
+}
+/**
+ * argv0를 허용 목록 비교용 이름으로 정규화한다. basename만 남기고,
+ * Windows는 PATH가 `npm.cmd`·`node.exe`를 고르므로 관용 확장자를 벗긴다 —
+ * 목록은 `npm`/`node`처럼 확장자 없는 이름만 둔다.
+ *
+ * @param {string} argv0 - 파싱된 첫 인자
+ * @returns {string} 허용 목록과 비교할 이름
+ */
+function verifyExecutableName(argv0) {
+    const base = path.basename(argv0);
+    if (process.platform === 'win32') {
+        return base.replace(/\.(cmd|exe|bat)$/i, '');
+    }
+    return base;
+}
+/**
+ * 활성 포인터·config가 고른 검증 명령이 실행 가능한지 판정한다.
+ * 파싱 성공과 허용 목록(argv0 실행 파일명)을 함께 본다. allowlist를 생략하면
+ * 기본 목록을 쓴다. 저장소 정책을 이미 읽은 호출자는 그 목록을 넘겨
+ * S12와 runtime이 다른 답을 내지 않게 한다.
+ *
+ * @param {unknown} command - 검증 명령 문자열
+ * @param {readonly string[]} [allowlist] - argv0 실행 파일명 허용 목록
+ * @returns {boolean} 실행해도 되는 명령이면 true
+ */
+function isValidVerifyCommand(command, allowlist = DEFAULT_VERIFY_ALLOWLIST) {
+    const argv = parseVerifyArgv(command);
+    if (!argv)
+        return false;
+    return allowlist.includes(verifyExecutableName(argv[0]));
+}
+/**
+ * verify 명령을 비교용으로 정규화한다. 앞뒤 공백을 자르고 연속 공백을 하나로
+ * 접는다. G20(종단 전체 명령 금지)과 `coordinate repair --verify` 검사가 같은
+ * 함수를 써야 한 표면이 통과시킨 값을 다른 표면이 종단 명령으로 오인하지 않는다.
+ *
+ * @param {string} cmd - verify 명령 문자열
+ * @returns {string} 정규화된 문자열. 문자열이 아니면 빈 문자열
+ */
+function normalizeVerifyCommand(cmd) {
+    return typeof cmd === 'string' ? cmd.trim().replace(/\s+/g, ' ') : '';
+}
+module.exports = {
+    normalizeVerifyCommand,
+    parseVerifyArgv,
+    verifyExecutableName,
+    isValidVerifyCommand,
+};

package/dist/commit-guard.js

@@ -0,0 +1,72 @@
+// scripts/lib/commit-guard.js
+'use strict';
+const scope = require("./scope");
+const { makeAllowed, isRuntimeArtifact } = scope;
+const crossDrive = require("./cross-drive");
+const { crossDriveConflicts } = crossDrive;
+/**
+ * 커밋 범위 안전 판정의 단일 구현.
+ * `commitTask`(CLI)와 호스트 commit hook(`evaluateCommit`)이 같은
+ * `allow`·`violations`를 쓰기 위한 계약이다. 허용·거부 로직을 어댑터에
+ * 복제하지 말고 여기만 호출한다.
+ * 기존 worktree·revision 경계와 현재 scope를 먼저 확정한 뒤 다른 drive를 본다.
+ * 그래야 잘못된 checkout이나 범위 밖 쓰기가 상대 ledger 상태로 가려지지 않는다.
+ *
+ * @param {object} opts
+ * @param {unknown[]|null|undefined} [opts.files] - 호출자가 선택한 실제 경로.
+ *   G17 호출자는 staged 파일만 전달하며, 이 함수는 working tree를 다시 읽지 않는다.
+ *   null/undefined는 빈 목록으로 취급한다.
+ * @param {unknown} [opts.affectedPaths] - 활성 task의 `affected_paths`
+ * @param {unknown} [opts.blueprintDir] - blueprint 상대 경로(번들 문서 예외용)
+ * @param {unknown} [opts.executionKind] - verification이면 commit 흐름 자체를 거절
+ * @param {object} [opts.coordinator] - `scope.coordinatorContext` 결과.
+ *   `active`면 ledger의 현재 scope가 승인된 `affected_paths`를 대신하고,
+ *   `reason`이 있으면 worktree·revision 경계 위반이므로 범위 판정 전에 거절한다.
+ * @param {object} [opts.otherDrives] - 현재 scope 통과 뒤 비교할 다른 drive 원장 또는 읽기 실패
+ * @returns {object} allow·violations·code와, 충돌이면 conflicts 또는 ledgerFile
+ *   `allow === true`면 위반 없음(`violations`는 `[]`).
+ *   `allow === false`면 `code`가 거절 사유이고, `out-of-scope`일 때만
+ *   `violations`가 범위 밖 경로다. 경계 위반은 staged 경로 전체를 담는다.
+ *   runtime artifact(`isRuntimeArtifact`)는 위반으로 치지 않는다 —
+ *   `makeAllowed` 예외와 함께 이 모듈이 소유한다.
+ */
+function checkCommitSafety({ files, affectedPaths, blueprintDir, coordinator, executionKind, otherDrives, }) {
+    const candidates = (files || []).filter((f) => !isRuntimeArtifact(f));
+    // verification node는 빈 scope를 이용해 "변경 없음" commit으로 들어가는 것도
+    // 금지한다. 파일 수와 무관하게 종류 자체가 commit 권한을 갖지 않는다.
+    if (executionKind === 'verification') {
+        return { allow: false, code: 'verification-task-no-commit', violations: candidates };
+    }
+    const active = Boolean(coordinator && coordinator.active);
+    // worktree 경계와 revision 불일치는 범위 계산 이전의 거절이다. 여기서
+    // scope로 다시 판정하면 main worktree 커밋이 "범위 안"으로 통과한다.
+    if (active && coordinator && coordinator.reason) {
+        return { allow: false, code: coordinator.reason, violations: candidates };
+    }
+    // coordinator 실행에서 승인된 affected_paths는 초기 예상치다 — 현재 정본은
+    // ledger scope. ledger가 아직 scope를 기록하지 않았으면 승인값을 그대로 쓴다.
+    const scope = active && coordinator && Array.isArray(coordinator.scope)
+        ? coordinator.scope
+        : affectedPaths;
+    const allowed = makeAllowed({ affectedPaths: scope, blueprintDir });
+    const violations = candidates.filter((f) => !allowed(f));
+    if (violations.length > 0)
+        return { allow: false, code: 'out-of-scope', violations };
+    if (active && otherDrives) {
+        // 범위 검사를 먼저 끝내므로 cross-drive 결과는 승인된 후보만 비교한다.
+        if (!otherDrives.ok) {
+            return { allow: false, code: otherDrives.reason, violations: [], ledgerFile: otherDrives.ledgerFile };
+        }
+        const candidate = {
+            id: coordinator && coordinator.taskId ? coordinator.taskId : 'commit',
+            affected_paths: candidates.filter((file) => typeof file === 'string'),
+            exclusive_resources: coordinator && Array.isArray(coordinator.resources) ? coordinator.resources : [],
+        };
+        const conflicts = crossDriveConflicts([candidate], otherDrives.drives);
+        if (conflicts.length > 0) {
+            return { allow: false, code: 'cross-drive-conflict', violations: [], conflicts };
+        }
+    }
+    return { allow: true, violations: [] };
+}
+module.exports = { checkCommitSafety };