@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/session-graph.js

@@ -0,0 +1,337 @@
+'use strict';
+const guards = require("./guards");
+const { catchMessageOrString } = guards;
+const initMod = require("./init");
+const { init, inspectBootstrap } = initMod;
+const time = require("./time");
+const { nowIsoKst } = time;
+const graphScope = require("./graph-scope");
+const { realGraphifyEnabled, realSourceDirs, realTestDirs, realExcludeDirs, realExistingDirs, newestMtimeUnder, realNewestMtime, realGraphMtime, resolveGraphScopes, SCAN_EXCLUDED_DIRS, DEFAULT_SOURCE_OUT, DEFAULT_TEST_OUT, } = graphScope;
+const graphExec = require("./graph-exec");
+const { realHasGraphify, defaultExecGraphify, normalizeGraphPaths, runGraphifyUpdate, partOutDir, } = graphExec;
+const graphify = require("./graphify");
+const { checkGraphifyCompatibility } = graphify;
+// 계획·오케스트레이션·경고 문구 + 공개 배럴.
+// 훅과 테스트는 이 파일 이름만 본다. 구현이 형제로 옮겨도 키 집합은 유지한다.
+/**
+ * 한 scope의 freshness를 결정한다. unconfigured·dirs 부재는 force보다 먼저
+ * 고정한다 — 승격이 소스 없는 test leftover를 빌드 대상으로 올리지 않게.
+ *
+ * @param {{ name: string, dirs: string[], outDir: string, scanDirs?: string[],
+ *   watchFiles?: string[], excludeDirs?: string[], unconfiguredReason?: string,
+ *   existingDirs: Function, newestMtime: Function, graphMtime: Function,
+ *   force?: boolean }} args
+ * @returns {GraphPlan}
+ */
+function planOneGraph(args) {
+    const { name, dirs, outDir, scanDirs, watchFiles, excludeDirs, unconfiguredReason, existingDirs, newestMtime, graphMtime, force, } = args;
+    // 미설정·무효 test는 디스크 leftover graph.json이 있어도 build/skip-fresh로
+    // 가지 않는다. missing·SessionStart 경고에도 올리지 않으려면 action이
+    // skip-unconfigured로 먼저 고정돼야 한다.
+    if (unconfiguredReason) {
+        return {
+            name,
+            dirs: [],
+            configured: [],
+            outDir,
+            action: 'skip-unconfigured',
+            reason: unconfiguredReason,
+        };
+    }
+    const present = existingDirs(dirs);
+    const mtime = graphMtime(outDir);
+    // `configured`는 전체 config 목록; `dirs`는 present만 유지해 호출자가
+    // config를 다시 읽지 않고 "X를 요청했지만 Y만 존재"라고 말할 수 있게 한다.
+    // scanDirs/watchFiles 는 결정 객체에 그대로 실어 소비 측이 scanDirs||dirs /
+    // watchFiles||[] 로 읽게 한다. configured 문구에는 섞지 않는다.
+    const base = {
+        name, dirs: present, configured: dirs, outDir, action: '', reason: '',
+    };
+    if (scanDirs !== undefined)
+        base.scanDirs = scanDirs;
+    if (watchFiles !== undefined)
+        base.watchFiles = watchFiles;
+    // source merge 뒤 필터가 읽을 수 있게 계획에 유지. 빈 배열도 명시성
+    // 테스트가 보므로 키가 있으면 그대로 싣는다.
+    if (excludeDirs !== undefined)
+        base.excludeDirs = excludeDirs;
+    if (present.length === 0) {
+        return { ...base, action: 'skip-no-dirs', reason: `${name} dirs missing` };
+    }
+    // 승격은 패키지 schema가 바뀌므로 mtime이 같아도 두 graph를 다시 만들어야 한다.
+    // skip-fresh를 그대로 두면 stampGraphSchema가 옛 graph.json만 다시 찍는다.
+    if (force === true) {
+        return { ...base, action: 'build', reason: `${name} graph force rebuild` };
+    }
+    if (mtime === null) {
+        return { ...base, action: 'build', reason: `${name} graph missing` };
+    }
+    const newest = newestMtime(present, watchFiles || []);
+    if (newest <= mtime) {
+        return { ...base, action: 'skip-fresh', reason: `${name} graph is up to date` };
+    }
+    return { ...base, action: 'build', reason: `${name} sources changed since last build` };
+}
+/**
+ * SessionStart·graph-sync용 freshness 계획. force는 승격 경로만 넘긴다.
+ *
+ * @param {{ repoRoot: string, deps?: SessionGraphDeps, force?: boolean }} opts
+ * @returns {SessionDecision}
+ */
+function planSessionGraph({ repoRoot, deps, force }) {
+    const d = {
+        inspectBootstrap: () => inspectBootstrap({ repoRoot }),
+        init: () => init({ repoRoot, timestamp: nowIsoKst() }),
+        graphifyEnabled: () => realGraphifyEnabled(repoRoot),
+        hasGraphify: () => realHasGraphify(repoRoot),
+        checkCompatibility: () => checkGraphifyCompatibility({ repoRoot }),
+        sourceDirs: () => realSourceDirs(repoRoot),
+        existingDirs: (dirs) => realExistingDirs(repoRoot, dirs),
+        newestMtime: (dirs, watchFiles) => realNewestMtime(repoRoot, dirs, watchFiles),
+        graphMtime: (outDir) => realGraphMtime(repoRoot, outDir),
+        ...(deps || {}),
+    };
+    let bootstrap = d.inspectBootstrap();
+    if (bootstrap === 'missing') {
+        const initialized = d.init();
+        if (!initialized.ok) {
+            return { bootstrap: 'partial', action: 'skip-partial-bootstrap', reason: initialized.reason, graphs: [] };
+        }
+        bootstrap = initialized.skipped ? 'ready' : 'created';
+    }
+    if (bootstrap === 'partial') {
+        return { bootstrap, action: 'skip-partial-bootstrap', reason: 'partial-bouncer-state', graphs: [] };
+    }
+    if (bootstrap === 'legacy') {
+        return { bootstrap, action: 'skip-legacy-bootstrap', reason: 'legacy-bootstrap-state', graphs: [] };
+    }
+    if (!d.graphifyEnabled()) {
+        return { bootstrap, action: 'skip-graph-disabled', reason: 'graphify auto-build disabled', graphs: [] };
+    }
+    if (!d.hasGraphify()) {
+        return { bootstrap, action: 'skip-no-graphify', reason: 'graphify not on PATH', graphs: [] };
+    }
+    const compat = d.checkCompatibility
+        ? d.checkCompatibility()
+        : checkGraphifyCompatibility({ repoRoot });
+    if (compat && compat.status === 'version-incompatible') {
+        // 조회 경로는 설치를 고치지 않는다. 두 graph 빌드를 건너뛰고 상태만 남긴다.
+        return {
+            bootstrap,
+            action: 'skip-version-incompatible',
+            reason: 'version-incompatible',
+            status: 'version-incompatible',
+            graphs: [],
+            compatibility: compat,
+        };
+    }
+    // deps가 testDirs/excludeDirs를 넘기면 config 파서를 우회한다(단위 테스트).
+    // 그 외에는 real*가 무효 필드를 적용하지 않고 skips에 사유를 모은다.
+    // testDirs null은 더 이상 scope 생략이 아니라 skip-unconfigured 자리표시다.
+    const skips = [];
+    let testDirs = null;
+    let testUnconfiguredReason;
+    let excludeDirs;
+    if (deps && Object.prototype.hasOwnProperty.call(deps, 'testDirs')) {
+        testDirs = d.testDirs ? d.testDirs() : null;
+        if (testDirs == null) {
+            testUnconfiguredReason = 'graphify.test_dirs is not configured';
+        }
+    }
+    else {
+        const testList = realTestDirs(repoRoot);
+        if (testList.present && testList.dirs === null) {
+            // 무효 값은 skips(SessionStart 진단)와 graphs[].reason에 같이 남긴다.
+            skips.push(testList.skipReason);
+            testUnconfiguredReason = testList.skipReason;
+        }
+        else if (testList.present) {
+            testDirs = testList.dirs;
+        }
+        else {
+            testUnconfiguredReason = 'graphify.test_dirs is not configured';
+        }
+    }
+    if (deps && Object.prototype.hasOwnProperty.call(deps, 'excludeDirs')) {
+        excludeDirs = d.excludeDirs ? d.excludeDirs() : [];
+    }
+    else {
+        const excludeList = realExcludeDirs(repoRoot);
+        if (excludeList.skipReason)
+            skips.push(excludeList.skipReason);
+        excludeDirs = excludeList.dirs;
+    }
+    const scopes = resolveGraphScopes({
+        sourceDirs: d.sourceDirs(),
+        testDirs,
+        excludeDirs,
+        testUnconfiguredReason,
+    });
+    const graphs = scopes.map((scope) => planOneGraph({
+        ...scope,
+        existingDirs: d.existingDirs,
+        newestMtime: d.newestMtime,
+        graphMtime: d.graphMtime,
+        force: force === true,
+    }));
+    const withSkips = (decision) => (skips.length ? { ...decision, skips } : decision);
+    const toBuild = graphs.filter((g) => g.action === 'build');
+    if (toBuild.length) {
+        return withSkips({
+            bootstrap,
+            action: 'build',
+            // 하위 호환: 첫 build target의 dirs(hook은 graphs[]를 선호).
+            dirs: toBuild[0].dirs,
+            graphs,
+            reason: toBuild.map((g) => g.reason).join('; '),
+        });
+    }
+    // skip-unconfigured는 빌드 시도가 아니다. 요약 집계에서 빼야 source가
+    // skip-no-dirs인 저장소가 항상 실리는 test 자리 때문에 skip-fresh로
+    // 뒤집히지 않는다. 제외 후 남는 항목이 없으면 skip-no-dirs를 유지한다.
+    const countable = graphs.filter((g) => g.action !== 'skip-unconfigured');
+    if (countable.length === 0 || countable.every((g) => g.action === 'skip-no-dirs')) {
+        return withSkips({
+            bootstrap, action: 'skip-no-dirs', graphs, reason: 'no graph source dirs exist',
+        });
+    }
+    return withSkips({
+        bootstrap, action: 'skip-fresh', graphs, reason: 'graphs are up to date',
+    });
+}
+// graph 작업을 시도하지 않고 조기 종료 — 해당 scope를 "missing"으로 보고하면
+// 의도적 no-op(disabled/bootstrap)을 사용자 탓으로 돌린다.
+const NO_GRAPH_WORK = new Set([
+    'skip-graph-disabled',
+    'skip-partial-bootstrap',
+    'skip-legacy-bootstrap',
+    'skip-no-graphify',
+    'skip-version-incompatible',
+]);
+/**
+ * source + test graph freshness를 계획하고 stale한 것을 재빌드한다.
+ * SessionStart와 /bouncer-plan(graphify-runner) query 전에 다시 사용.
+ * graphs[]는 config와 무관하게 두 항목이지만, skip-unconfigured test는
+ * 빌드·missing·경고 대상이 아니다. force는 명시적 승격 전용 — 일반
+ * graph-sync가 skip-fresh를 버리게 하지 않는다.
+ *
+ * @param {{ repoRoot: string, deps?: SessionGraphDeps,
+ *   execGraphify?: (graph: GraphPlan) => unknown, force?: boolean }} opts
+ * @returns {SessionDecision & { built: string[], failed: Array<{ name: string, message: string }>, missing: string[] }}
+ */
+function syncSessionGraphs({ repoRoot, deps, execGraphify, force }) {
+    const decision = planSessionGraph({ repoRoot, deps, force });
+    const run = execGraphify || ((graph) => defaultExecGraphify(repoRoot, graph));
+    const built = [];
+    const failed = [];
+    if (decision.action === 'build') {
+        for (const graph of decision.graphs) {
+            if (graph.action !== 'build' || !graph.dirs.length)
+                continue;
+            try {
+                // context digest 제거 후 defaultExecGraphify는 skippedEmpty/touched를
+                // 반환하지 않는다. 성공하면 항상 built에 올린다.
+                run(graph);
+                built.push(graph.name);
+            }
+            catch (error) {
+                failed.push({ name: graph.name, message: catchMessageOrString(error) });
+            }
+        }
+    }
+    // planSessionGraph가 쓰는 것과 같은 deps.graphMtime 주입 — build loop 후
+    // 실제 graph.json을 probe; action 문자열로 부재를 추론하지 말 것
+    // (이전 세션 graph는 skip-no-dirs에서도 present로 친다).
+    const graphMtime = (deps && deps.graphMtime)
+        ? deps.graphMtime
+        : (outDir) => realGraphMtime(repoRoot, outDir);
+    // NO_GRAPH_WORK 는 그래프를 시도하지 않은 상태. missing 을 채우거나
+    // ok 를 뒤집으면 disabled/bootstrap 을 실패로 보이게 된다.
+    // skip-unconfigured는 graph.json 존재와 무관하게 missing에서 뺀다 —
+    // 미설정 test leftover 산출물이 SessionStart 경고를 만들지 않게.
+    const missing = NO_GRAPH_WORK.has(decision.action)
+        ? []
+        : decision.graphs
+            .filter((g) => g.action !== 'skip-unconfigured')
+            .filter((g) => graphMtime(g.outDir) === null)
+            .map((g) => g.name);
+    return { ...decision, built, failed, missing };
+}
+/**
+ * sync decision을 SessionStart용 stderr 경고 줄로 변환.
+ * 순서: bootstrap(partial/legacy) → no-graphify → skips → missing → failed.
+ * NO_GRAPH_WORK 종료는 missing을 비우므로 bootstrap 줄이 missing/failed와
+ * stderr를 공유하지 않는다. 각 줄은 hook용으로 \n으로 끝난다.
+ */
+function graphSyncWarnings(decision) {
+    const lines = [];
+    if (decision.bootstrap === 'partial') {
+        lines.push('Bouncer: partial Bouncer state detected; preserving .bouncer and skipping SessionStart work.\n');
+    }
+    else if (decision.bootstrap === 'legacy') {
+        lines.push('Bouncer: legacy state detected; remove or migrate legacy files, then run /bouncer-init.\n');
+    }
+    if (decision.action === 'skip-no-graphify') {
+        // enabled인데 CLI가 없을 때만 경고 — disabled면 이 action에 오지 않는다.
+        lines.push('Bouncer: graphify.enabled is true but graphify is not on PATH — path suggestions '
+            + 'will fall back to manual affected_paths. '
+            + 'Install: pip install graphifyy && graphify install. See docs/install.md.\n');
+    }
+    if (decision.action === 'skip-version-incompatible') {
+        lines.push('Bouncer: graphify is version-incompatible with the plugin contract. '
+            + 'Run bouncer init --upgrade-graphify. Search and graph-sync will not install or mutate the venv.\n');
+    }
+    // 잘못된 exclude_dirs·무효 test_dirs는 skips에 남는다(test는 graphs에도
+    // skip-unconfigured로 실린다). SessionStart가 못 보면 운영자가 왜 필드가
+    // 무시됐는지 알 수 없다.
+    for (const reason of decision.skips || []) {
+        lines.push(`Bouncer: skipped graphify config — ${reason}. `
+            + 'Update .bouncer/config.json; path suggestions may be incomplete.\n');
+    }
+    const byName = Object.fromEntries((decision.graphs || []).map((g) => [g.name, g]));
+    // failed scope는 전용 줄이 있음; configured dirs가 missing이라고
+    // 중복 주장하지 말 것(dirs는 있었고 build가 실패).
+    // skip-unconfigured는 missing에 안 들어가지만, 방어적으로 action도 건너뛴다.
+    const failedNames = new Set((decision.failed || []).map((f) => f.name));
+    for (const name of decision.missing || []) {
+        if (failedNames.has(name))
+            continue;
+        const graph = (byName[name] || {});
+        if (graph.action === 'skip-unconfigured')
+            continue;
+        const configured = Array.isArray(graph.configured) ? graph.configured : [];
+        // test는 config 상 graphify.test_dirs. source는 루트 키.
+        const dirsKey = name === 'test' ? 'graphify.test_dirs' : `${name}_dirs`;
+        // "none of … exist"는 skip-no-dirs/빈 present dirs일 때만 참.
+        const noDirs = graph.action === 'skip-no-dirs'
+            || !Array.isArray(graph.dirs)
+            || graph.dirs.length === 0;
+        if (noDirs) {
+            lines.push(`Bouncer: graphify is enabled but no ${name} graph was built — none of `
+                + `${dirsKey} ${JSON.stringify(configured)} exist. Update .bouncer/config.json; path `
+                + 'suggestions will fall back to manual affected_paths.\n');
+        }
+        else {
+            lines.push(`Bouncer: graphify is enabled but no ${name} graph was built after sync. `
+                + 'Path suggestions will fall back to manual affected_paths.\n');
+        }
+    }
+    if (decision.failed && decision.failed.length) {
+        lines.push(`Bouncer: graphify sync failed for ${decision.failed.map((f) => f.name).join(', ')}. `
+            + 'Plan will re-check; confirm affected_paths manually if graphs stay stale.\n');
+    }
+    return lines;
+}
+module.exports = {
+    planSessionGraph,
+    syncSessionGraphs,
+    graphSyncWarnings,
+    resolveGraphScopes,
+    normalizeGraphPaths,
+    newestMtimeUnder,
+    runGraphifyUpdate,
+    partOutDir,
+    SCAN_EXCLUDED_DIRS,
+    DEFAULT_SOURCE_OUT,
+    DEFAULT_TEST_OUT,
+};

package/dist/subagents.js

@@ -0,0 +1,86 @@
+'use strict';
+const guards = require("./guards");
+const { isRecord } = guards;
+const config = require("./config");
+const { readConfig } = config;
+// `bouncer config --help`와 docs 일치 테스트의 원본 값 목록. provider 이름은
+// 그동안 init 기본 블록·print-dispatch·주석에만 흩어져 있어, 도움말이 문자열을
+// 다시 적지 않도록 여기 한 곳에 둔다. 값 검증 게이트로 쓰지 않는다(읽기 전용 안내).
+const SUBAGENT_PROVIDERS = ['claude', 'cursor', 'codex', 'antigravity'];
+// `subagents.dispatch`가 받는 값. 부재가 기본(호스트 Task 서브에이전트)이라 목록에 넣지 않는다.
+const SUBAGENT_DISPATCH_VALUES = ['print'];
+/**
+ * provider 해석 순서(먼저 맞는 것이 이김):
+ *   1. 명시적 `provider` 인자(skill override)
+ *   2. `config.subagents.provider`(프로젝트 pin — Cursor·Antigravity에 필수)
+ *   3. CLAUDE_PLUGIN_ROOT → 'claude'
+ *   4. PLUGIN_ROOT → 'codex'
+ *   5. 호스트가 자기 터미널에 직접 내보내는 세션 변수:
+ *      CLAUDECODE → 'claude', CODEX_THREAD_ID → 'codex'
+ *   6. null
+ *
+ * BOUNCER_HOME은 의도적으로 무시한다: 어떤 호스트에서도 설정 가능한
+ * 수동 plugin-root override이므로 Cursor(또는 다른 provider)를 의미하지
+ * 않는다. Cursor 사용자는 `subagents.provider: "cursor"`를 설정해야 한다.
+ *
+ * 5번은 plugin-root 변수가 주입되지 않는 터미널(예: Bash 도구)에서 provider가
+ * null로 풀려 역할별 모델이 조용히 inherit로 떨어지는 것을 막는다. Claude Code 안에서
+ * codex를 띄우는 식의 중첩에서는 더 안쪽 호스트가 아니라 CLAUDECODE가 이긴다 —
+ * 틀리면 `subagents.provider`로 명시 고정한다. Cursor는 CURSOR_AGENT가 있어도
+ * 자동 감지하지 않는다(print dispatch 분기가 걸려 있어 명시 고정만 허용).
+ *
+ * Antigravity도 plugin-root 환경 변수를 내보내지 않으므로 env 표에 분기를
+ * 추가하지 않는다 — `subagents.provider: "antigravity"` 명시 pin만 허용.
+ */
+function resolveProvider(config, providerArg) {
+    if (typeof providerArg === 'string' && providerArg.length > 0) {
+        return providerArg;
+    }
+    const subagents = isRecord(config) ? config.subagents : undefined;
+    const pinned = isRecord(subagents) ? subagents.provider : undefined;
+    if (typeof pinned === 'string' && pinned.length > 0) {
+        return pinned;
+    }
+    if (process.env.CLAUDE_PLUGIN_ROOT)
+        return 'claude';
+    if (process.env.PLUGIN_ROOT)
+        return 'codex';
+    if (process.env.CLAUDECODE)
+        return 'claude';
+    if (process.env.CODEX_THREAD_ID)
+        return 'codex';
+    return null;
+}
+/**
+ * 활성 호스트용 named-agent model slug를 조회한다.
+ * 절대 throw하지 않으며, 모든 miss/inherit/비문자열은
+ * `{ model: null }`로 수렴해 호출자가 부모 세션 model을 상속하게 한다.
+ *
+ * @param {{ repoRoot: string, agentName: string, provider?: string }} opts
+ * @returns {{ model: string | null, provider: string | null }}
+ */
+function resolveSubagentModel({ repoRoot, agentName, provider: providerArg, } = {}) {
+    // 부재·깨진 JSON은 null. ?? {}로 받아야 resolveProvider가 throw 없이
+    // inherit fallback({ model: null })으로 수렴한다. session-graph는 null을
+    // 구분하지만 이쪽은 "설정 없음 = 빈 설정"이 안전하다.
+    const config = readConfig(repoRoot) ?? {};
+    const provider = resolveProvider(config, providerArg);
+    if (!provider) {
+        return { model: null, provider: null };
+    }
+    const subagents = isRecord(config) ? config.subagents : undefined;
+    const block = isRecord(subagents) ? subagents[provider] : undefined;
+    if (!block || typeof block !== 'object') {
+        return { model: null, provider };
+    }
+    // agentName이 빠지면 예전 `block[undefined]`와 같이 키 'undefined'를 본다.
+    // 배열도 typeof object라 통과시켜, 인덱스 키 조회를 객체만 받도록 바꾸지 않는다.
+    const value = block[`${agentName}`];
+    // 'inherit'은 "부모 세션 model 사용"을 위한 문서화된 sentinel이다.
+    // 비문자열(숫자, 객체, null)도 동일하게 취급 — 절대 throw하지 않음.
+    if (typeof value !== 'string' || value.length === 0 || value === 'inherit') {
+        return { model: null, provider };
+    }
+    return { model: value, provider };
+}
+module.exports = { resolveSubagentModel, SUBAGENT_PROVIDERS, SUBAGENT_DISPATCH_VALUES };