@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/cli-commit-guard-command.js

@@ -0,0 +1,74 @@
+'use strict';
+const cliUsage = require("./cli-usage");
+const cliFlags = require("./cli-flags");
+const { parseFlags } = cliFlags;
+const commitHook = require("./commit-hook");
+const { evaluateStaged, evaluateCommit } = commitHook;
+const fs = require("node:fs");
+const USAGE = `usage: bouncer commit-guard (--staged | --command-stdin) [--repo <dir>]
+
+`;
+/**
+ * 커밋 범위 검사 CLI. 두 모드 중 정확히 하나만 받는다.
+ * - `--staged`: git pre-commit 훅용. staged 인덱스를 판정한다.
+ * - `--command-stdin`: PreToolUse 훅용. stdin 전체를 명령 원문으로 읽어
+ *   `evaluateCommit`으로 판정한다(명령 탐지·alias·FAIL_CLOSED 규칙 포함).
+ * 둘 다 있거나 둘 다 없으면 사용법 오류(exit 2)로 끝내 판정 예외(exit 1,
+ * 커밋 차단)와 구분한다.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.argv - `commit-guard` 뒤 인자
+ * @param {string} opts.cwd - `--repo`가 없을 때 쓸 저장소 루트
+ * @param {Function} [opts.evaluate] - 기본 `evaluateStaged`. 테스트 seam
+ * @param {Function} [opts.evaluateCommand] - 기본 `evaluateCommit`. 테스트 seam
+ * @param {Function} [opts.readInput] - 기본 stdin 전체 읽기. 테스트 seam
+ * @param {Function} [opts.stderr] - 차단 사유·사용법 싱크. 생략 시 stderr
+ * @returns {number} 0 허용, 1 차단 또는 내부 오류, 2 사용법
+ */
+function runCommitGuard({ argv, cwd, evaluate, evaluateCommand, readInput, stderr, }) {
+    const err = stderr || ((s) => {
+        process.stderr.write(s);
+    });
+    const staged = argv.includes('--staged');
+    const commandStdin = argv.includes('--command-stdin');
+    // 상호 배타: 둘 다 주면 어느 판정을 원하는지 모호하므로 사용법 오류로 거절한다.
+    if (staged === commandStdin) {
+        err(USAGE);
+        return 2;
+    }
+    const flags = parseFlags(argv);
+    const repoRoot = typeof flags.repo === 'string' && flags.repo ? flags.repo : cwd;
+    const judge = evaluate || evaluateStaged;
+    let result;
+    try {
+        if (commandStdin) {
+            const judgeCommand = evaluateCommand || evaluateCommit;
+            const read = readInput || (() => fs.readFileSync(0, 'utf8'));
+            // stdin 읽기 실패도 이 try 안에서 internal error(exit 1)로 막는다.
+            result = judgeCommand({ command: read(), repoRoot });
+        }
+        else {
+            result = judge({ repoRoot });
+        }
+    }
+    catch (error) {
+        // evaluate가 던지는 모든 예외를 흡수한다. hook 안에서 uncaught로 죽으면
+        // git은 막히지만 정해진 진단 문자열이 아니라 스택이 나와 복구 힌트가 없다.
+        const message = error instanceof Error ? error.message : String(error);
+        err(`commit-guard: internal error, blocking commit: ${message}\n`);
+        return 1;
+    }
+    if (result.block) {
+        err(`${result.reason || 'commit blocked'}\n`);
+        return 1;
+    }
+    return 0;
+}
+function cmdCommitGuard(rest, io) {
+    return runCommitGuard({ argv: rest, cwd: process.cwd(), stderr: io.err });
+}
+module.exports = {
+    runCommitGuard,
+    run: cmdCommitGuard,
+    usage: cliUsage.COMMAND_USAGE['commit-guard'],
+};

package/dist/cli-config-command.js

@@ -0,0 +1,47 @@
+'use strict';
+const cliUsage = require("./cli-usage");
+const codexAgents = require("./codex-agents");
+const { NAMED_AGENTS } = codexAgents;
+const subagents = require("./subagents");
+const { SUBAGENT_PROVIDERS, SUBAGENT_DISPATCH_VALUES } = subagents;
+const USAGE = 'usage: bouncer config --help\n';
+// 출력 한 줄이 max-len(120)을 넘어 템플릿 밖 상수로 뺀다. 출력 바이트는 그대로다.
+const PROVIDER_DEFAULT = 'unset — CLAUDE_PLUGIN_ROOT selects claude, PLUGIN_ROOT selects codex; '
+    + 'cursor and antigravity must be set';
+// provider·agent 이름은 상수에서만 채운다. docs/configuration.md 표와의 일치는
+// test/config-help.test.js가 이 출력을 파싱해 확인하므로 줄 형식을 바꾸면 그 테스트도 맞춘다.
+const HELP = `${USAGE}
+Keys under "subagents" in .bouncer/config.json (read-only help; this command writes nothing):
+  subagents.provider            ${SUBAGENT_PROVIDERS.join(' | ')}
+                                default: ${PROVIDER_DEFAULT}
+  subagents.dispatch            ${SUBAGENT_DISPATCH_VALUES.join(' | ')} | absent
+                                default: absent (host Task subagents); read only when provider is cursor
+  subagents.<provider>.<agent>  inherit | <host model slug>
+                                default: inherit (parent session model; missing, empty, or non-string also inherit)
+    <agent>: ${NAMED_AGENTS.join(', ')}
+
+Key under "metrics" (read by "bouncer metrics end"):
+  metrics.pricing               { "<model slug>": { "input_per_mtok": <n>, "output_per_mtok": <n> } } | absent
+                                default: absent (cost is recorded as null with reason no-pricing)
+`;
+/**
+ * `bouncer config` 핸들러. 인자가 정확히 `--help` 또는 `-h` 하나일 때만
+ * 도움말을 stdout에 쓰고, 그 외(인자 없음·다른 토큰)는 usage를 stderr에 쓴다.
+ * 파일을 읽거나 쓰지 않는다.
+ *
+ * @param {string[]} rest - `config` 뒤 원시 argv
+ * @param {CliIo} io - stdout/stderr 싱크
+ * @returns {number} 도움말 0, 그 외 사용법 거절 2
+ */
+function cmdConfig(rest, io) {
+    if (rest.length === 1 && (rest[0] === '--help' || rest[0] === '-h')) {
+        io.out(HELP);
+        return 0;
+    }
+    io.err(USAGE);
+    return 2;
+}
+module.exports = {
+    run: cmdConfig,
+    usage: cliUsage.COMMAND_USAGE['config'],
+};

package/dist/cli-context-review-command.js

@@ -0,0 +1,273 @@
+'use strict';
+const cliUsage = require("./cli-usage");
+const cliFlags = require("./cli-flags");
+const { parseFlags, argvRequestsHelp } = cliFlags;
+// validate-sections는 의도적으로 가벼운 모듈이라 argv 검증 전에 context-review-state를
+// 적재하지 않는 현재 순서를 깨지 않고 도움말 열거값을 검증기 상수에서 만들 수 있다.
+const validateSections = require("./validate-sections");
+const { REVIEW_SEVERITY, CONTEXT_REVIEW_STATUS, REPORT_FINDING_STATUS, FINDING_ACTIONABILITY, FINDING_ORIGIN, CONTEXT_ROUND_MODES, CONTEXT_REPORT_STATUS, CONTEXT_REVIEW_PERSPECTIVE, findingFingerprint, } = validateSections;
+const ALLOWED_STATUS = CONTEXT_REPORT_STATUS;
+const USAGE_BLOCK = '  context-review <start|record|close|restart|route> --blueprint <dir>\n'
+    + '             Track plan context-review cycles; limit full restarts to one.\n';
+const USAGE = 'usage: bouncer context-review start --blueprint <dir> --dispatch <json>\n'
+    + '       bouncer context-review record --blueprint <dir> --dispatch <json> --round <json> '
+    + '[--status <requested|addressed|accepted>] [--accept-risk <id[,id...]>] [--repo <dir>]\n'
+    + '       bouncer context-review close --blueprint <dir> --dispositions <json> '
+    + '[--accept-risk <id[,id...]>] [--repo <dir>]\n'
+    + '       bouncer context-review restart --blueprint <dir> --dispatch <json> --reason <text> [--repo <dir>]\n'
+    + '       bouncer context-review route --blueprint <dir> --dispatch <json> [--repo <dir>]\n'
+    + '       (each accepts --repo <dir>)\n'
+    + '\n'
+    + USAGE_BLOCK;
+// 예시 finding의 구성 요소. fingerprint는 검증기와 같은 함수로 계산해 손으로 쓴 값이
+// 공식과 어긋나는 일을 없앤다(cli-review-dispatch-command의 예시와 같은 방식).
+const EXAMPLE_FILE = '.bouncer/context/epics/014-auth/blueprints/001-signup/tasks/001/tasks.md';
+const EXAMPLE_FINDINGS = [
+    {
+        id: 'CR-1', category: 'scope', brief_clause: 'tasks/001 touch', symbol: 'touch',
+        severity: 'major', actionability: 'must_fix',
+    },
+    {
+        id: 'CR-2', category: 'scope', brief_clause: 'tasks/001 wording', symbol: 'wording',
+        severity: 'minor', actionability: 'advisory',
+    },
+].map((f) => ({
+    id: f.id,
+    severity: f.severity,
+    status: 'open',
+    category: f.category,
+    brief_clause: f.brief_clause,
+    file: EXAMPLE_FILE,
+    symbol: f.symbol,
+    fingerprint: findingFingerprint({ ...f, file: EXAMPLE_FILE }, 'context'),
+    actionability: f.actionability,
+    origin: 'discovery',
+    first_seen_round: 1,
+    last_seen_round: 1,
+}));
+/**
+ * 도움말 예시 round 보고 하나를 JSON 문자열로 만든다. 바꿀 자리는 `<target.digest>`
+ * 하나뿐이며 `review-dispatch plan` 출력의 target.digest를 그대로 넣는다.
+ *
+ * @param {number} round - round 번호(discovery는 1, delta는 2)
+ * @param {string} mode - round mode
+ * @param {object[]} findings - 이 round가 보고하는 finding 목록
+ * @returns {string} 파일 하나로 복사할 수 있는 들여쓴 JSON
+ */
+function exampleRound(round, mode, findings) {
+    return JSON.stringify({
+        round: {
+            round,
+            mode,
+            target: { digest: '<target.digest>' },
+            perspectives: [{ name: 'combined', target_digest: '<target.digest>' }],
+            severity_changes: [],
+        },
+        findings,
+    }, null, 2);
+}
+const EXAMPLE_DISPOSITIONS = JSON.stringify([
+    { id: 'CR-1', status: 'resolved' },
+    { id: 'CR-2', status: 'accepted', note: 'Wording only; the clause is still unambiguous.' },
+], null, 2);
+const HELP = `${USAGE}
+--dispatch is the JSON printed by \`review-dispatch plan --blueprint <dir>\`.
+--round is { "round": object, "findings": object[] } (discovery, then delta).
+--dispositions is a JSON array of [{ id, status, note }] to dispose folded findings.
+
+Each example below is a complete file. Replace only <target.digest> with the
+target.digest from the \`review-dispatch plan\` JSON.
+
+--round, discovery (round 1):
+\`\`\`json
+${exampleRound(1, 'discovery', EXAMPLE_FINDINGS)}
+\`\`\`
+
+--round, delta (round 2; findings may be [] when nothing new is reported):
+\`\`\`json
+${exampleRound(2, 'delta', [])}
+\`\`\`
+
+--dispositions (close; one entry per finding still open or to be disposed):
+\`\`\`json
+${EXAMPLE_DISPOSITIONS}
+\`\`\`
+
+Allowed values:
+  round.round: 1 for discovery, 2 for delta (record in that order)
+  round.mode: ${CONTEXT_ROUND_MODES.join('|')}
+  finding severity: ${REVIEW_SEVERITY.join('|')}
+  finding status (--round): ${REPORT_FINDING_STATUS.join('|')}
+  finding actionability: ${FINDING_ACTIONABILITY.join('|')}
+  finding origin: ${FINDING_ORIGIN.join('|')}
+  perspectives[].name (also finding category): ${CONTEXT_REVIEW_PERSPECTIVE.join('|')}
+  perspectives dispatch (review_contract brief): discovery round lists every dispatch perspective, e.g.
+  perspectives: [{ name: consistency, target_digest: <target.digest> }, ...];
+  delta lists combined (full) or verifiability (light)
+  disposition status (--dispositions): ${CONTEXT_REVIEW_STATUS.join('|')} (accepted requires note)
+  --status: ${ALLOWED_STATUS.join('|')}
+
+--status accepted or close with dispositions closes the cycle: every finding must be resolved or accepted
+with a note; a must_fix accepted needs --accept-risk <id> and explicit user consent.
+When it closes the cycle, close and record --status accepted also write <blueprint>/context-review.md
+(status accepted, rounds, findings, and the ## Findings list) and return its path as written; a rerun
+of the same input rewrites it. A missing context-review.md is rejected: bouncer scaffold context-review.
+
+Exit: 0 success or help, 1 rejected transition, 2 usage error.
+Failure JSON: { ok: false, reason, cause, next }. reason is one of
+  context-review-restart-limit | context-review-state-conflict |
+  context-review-unresolved-findings | context-review-target-invalid |
+  context-review-legacy-evidence | context-review-round-order |
+  context-review-input-invalid
+A recorded success is not a plan gate pass.
+record success may carry warnings: [{ code: 'finding-merge-candidate', file, symbol, ids }] when findings
+of that round share a file and symbol under different categories; the key is omitted when there is none
+(and on a noop rerun). A warning never blocks the record; the controller decides whether to merge them.
+record rejects (context-review-input-invalid) a round whose merged findings share a fingerprint under different
+ids, at any --status and before writing anything; merge them into one finding and record the same round again.
+record overwrites each finding's fingerprint with the context formula and, when the id key is omitted,
+assigns CR-<first 8 hex of sha256(fingerprint)> (stable across rounds; dispose it by that id in close).
+An explicit id must be a non-empty string; null, "", blank or non-string ids and a generated id taken by a
+different fingerprint are context-review-input-invalid. record success (and its noop rerun) carries
+finding_ids: this round's normalized ids in input order without duplicates. Stored report bytes stay as
+given; fold, close and noop projections apply the formula, so an earlier wrong fingerprint is repaired.
+
+route is read-only: it reads follow_up from the --dispatch payload (a
+review-dispatch plan run with --previous) and prints { ok, next_action, reason,
+cause, next, cycle } with next_action reuse | close | delta | restart | user. It never
+writes state; a payload without follow_up is context-review-input-invalid.
+close means the structure and the Interface/Touch contract equal the reviewed baseline and only
+the body changed: run close to certify the current snapshot (no new round). delta is a contract-only
+change after discovery; restart is a structure change. close and an accepted record write
+closure_target_digest (64 lowercase hex) to the runtime closure and the context-review.md frontmatter;
+a closed cycle may be closed again after a body-only edit, and close refuses a changed structure or contract.
+`;
+/**
+ * argv를 검증한다. 필수 플래그 누락·중복·허용 밖 값은 상태 파일을 열기 전에
+ * 거절해 exit 2(사용법)와 exit 1(전이 거절)을 가른다. 중복 플래그는 parseFlags가
+ * 마지막 값만 남겨 다른 대상에 기록하게 되므로 덮이기 전에 센다.
+ *
+ * @param {string[]} rest - `context-review` 뒤 argv
+ * @returns {Parsed} 성공 필드 또는 `{error}`
+ */
+function parseArgs(rest) {
+    const fail = (message) => ({ error: `context-review: ${message}\n${USAGE}` });
+    const verb = rest[0];
+    if (verb !== 'start' && verb !== 'record' && verb !== 'close' && verb !== 'restart' && verb !== 'route') {
+        return fail('command must be start, record, close, restart or route');
+    }
+    const flags = rest.slice(1);
+    for (const name of ['blueprint', 'dispatch', 'round', 'dispositions', 'status', 'accept-risk', 'reason', 'repo']) {
+        if (flags.filter((t) => t === `--${name}`).length > 1)
+            return fail(`--${name} specified more than once`);
+    }
+    const f = parseFlags(flags);
+    const text = (name) => {
+        const v = f[name];
+        return typeof v === 'string' && v !== '' ? v : null;
+    };
+    const blueprint = text('blueprint');
+    if (!blueprint)
+        return fail('--blueprint is required');
+    const dispatch = text('dispatch');
+    const dispositions = text('dispositions');
+    const round = text('round');
+    const reason = text('reason');
+    if (verb === 'close') {
+        if (f.dispatch !== undefined)
+            return fail('--dispatch is not valid for close');
+        if (!dispositions)
+            return fail('--dispositions <json-file> is required');
+    }
+    else {
+        if (f.dispositions !== undefined)
+            return fail('--dispositions is only valid for close');
+        if (!dispatch)
+            return fail('--dispatch <json-file> is required');
+    }
+    if (verb === 'record' && !round)
+        return fail('--round <json-file> is required');
+    if (verb === 'restart' && !reason)
+        return fail('--reason is required');
+    if (verb !== 'record' && (round || f.status !== undefined)) {
+        return fail('--round and --status are only valid for record');
+    }
+    if (verb !== 'record' && verb !== 'close' && f['accept-risk'] !== undefined) {
+        return fail('--accept-risk is only valid for record and close');
+    }
+    if (verb !== 'restart' && f.reason !== undefined)
+        return fail('--reason is only valid for restart');
+    const status = text('status');
+    if (f.status !== undefined && (status === null || !ALLOWED_STATUS.includes(status))) {
+        return fail('--status must be requested, addressed, or accepted');
+    }
+    if (f['accept-risk'] !== undefined && text('accept-risk') === null) {
+        return fail('--accept-risk requires finding ids');
+    }
+    if (f.repo !== undefined && text('repo') === null)
+        return fail('--repo requires a directory');
+    return {
+        verb,
+        blueprint,
+        dispatch,
+        round,
+        dispositions,
+        status,
+        acceptRisk: (text('accept-risk') || '').split(',').map((s) => s.trim()).filter(Boolean),
+        reason,
+        repo: text('repo') || undefined,
+    };
+}
+/**
+ * 공개 `context-review` 핸들러. 도움말은 상태 모듈을 열기 전에 끝내고, 그 외는
+ * argv 검증과 상태 전이 호출·JSON 출력·exit만 연결한다.
+ *
+ * @param {string[]} rest - 동사와 플래그
+ * @param {CliIo} io - stdout/stderr 싱크
+ * @returns {number} 성공 0, 전이 거절 1, 사용법 2
+ */
+function cmdContextReview(rest, io) {
+    if (argvRequestsHelp(rest)) {
+        io.out(HELP);
+        return 0;
+    }
+    const parsed = parseArgs(rest);
+    if ('error' in parsed) {
+        io.err(parsed.error);
+        return 2;
+    }
+    // argv를 통과한 뒤에만 상태 모듈을 적재한다. 사용법 거절이 파일 I/O 경로를 열지 않게 한다.
+    const state = require('./context-review-state');
+    const repoRoot = parsed.repo ? parsed.repo : process.cwd();
+    let result;
+    if (parsed.verb === 'start') {
+        result = state.startCycle({ repoRoot, blueprintDir: parsed.blueprint, dispatchFile: parsed.dispatch });
+    }
+    else if (parsed.verb === 'record') {
+        result = state.recordReport({
+            repoRoot, blueprintDir: parsed.blueprint, dispatchFile: parsed.dispatch,
+            roundFile: parsed.round, status: parsed.status, acceptRisk: parsed.acceptRisk,
+        });
+    }
+    else if (parsed.verb === 'close') {
+        result = state.closeCycle({
+            repoRoot, blueprintDir: parsed.blueprint, dispositionsFile: parsed.dispositions,
+            acceptRisk: parsed.acceptRisk,
+        });
+    }
+    else if (parsed.verb === 'route') {
+        result = state.routeFollowUp({ repoRoot, blueprintDir: parsed.blueprint, dispatchFile: parsed.dispatch });
+    }
+    else {
+        result = state.restartCycle({
+            repoRoot, blueprintDir: parsed.blueprint, dispatchFile: parsed.dispatch,
+            reason: parsed.reason,
+        });
+    }
+    io.out(`${JSON.stringify(result, null, 2)}\n`);
+    return result.ok ? 0 : 1;
+}
+module.exports = {
+    run: cmdContextReview,
+    usage: cliUsage.COMMAND_USAGE['context-review'],
+};