@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/plan-prerequisites.js

@@ -0,0 +1,197 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const layout = require("./layout");
+const { isCanonicalBlueprintDir, normalizeRepoPath } = layout;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const schema = require("./schema");
+const { PREREQUISITE_MERGED_COMMIT_RE: MERGED_COMMIT_RE } = schema;
+/**
+ * `bouncer.prerequisites` 값을 항목별로 판정해 위반 설명과 "유효한 항목"을 함께 돌려준다.
+ * 형식 검사(S39)·Git 조회 대상·순환 간선이 각자 선별 조건을 갖고 있으면 서로 다른 답을 내
+ * HEAD·짧은 SHA·중복이 승인 때 새어 나갔다. 그래서 선별을 이 한 곳에 모은다.
+ * 유효한 항목 = 정확한 두 키, 정본 경로, 40자 소문자 SHA, 자기참조 아님, 앞선 유효 항목과 중복 아님.
+ * 부재(undefined)와 `[]`는 선행 없음이라 통과한다. 존재·순환·병합 여부는 보지 않는다.
+ *
+ * @param {unknown} value - 프론트매터의 prerequisites 값. 키가 없으면 undefined
+ * @param {string} selfDir - 이 선언을 가진 blueprint의 저장소 상대 디렉터리(자기참조 판정용)
+ * @returns {{issues: string[], valid: ValidEntry[]}} 위반 설명 목록과 Git 조회·간선에 쓸 유효한 항목
+ */
+function classifyPrerequisites(value, selfDir) {
+    if (value === undefined)
+        return { issues: [], valid: [] };
+    if (!Array.isArray(value)) {
+        return { issues: ['prerequisites must be an array of {blueprint, merged_commit}'], valid: [] };
+    }
+    const issues = [];
+    const valid = [];
+    const seen = new Set();
+    const self = normalizeRepoPath(selfDir);
+    value.forEach((entry, i) => {
+        const label = `prerequisites[${i}]`;
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            issues.push(`${label} must be an object with blueprint and merged_commit`);
+            return;
+        }
+        const rec = entry;
+        const keys = Object.keys(rec).sort().join(',');
+        if (keys !== 'blueprint,merged_commit') {
+            issues.push(`${label} must have exactly blueprint and merged_commit`);
+            return;
+        }
+        const { blueprint, merged_commit: commit } = rec;
+        // 백슬래시·끝 슬래시·파일 경로는 같은 blueprint를 다른 문자열로 적게 하므로 정본 문자열 그대로만 받는다.
+        const canonical = typeof blueprint === 'string'
+            && normalizeRepoPath(blueprint) === blueprint && isCanonicalBlueprintDir(blueprint);
+        if (!canonical)
+            issues.push(`${label}.blueprint must be a canonical blueprint directory`);
+        const shaOk = typeof commit === 'string' && MERGED_COMMIT_RE.test(commit);
+        if (!shaOk)
+            issues.push(`${label}.merged_commit must be a 40-char lowercase sha`);
+        if (!canonical)
+            return;
+        const bp = blueprint;
+        let dup = false;
+        if (bp === self)
+            issues.push(`${label}.blueprint must not reference itself`);
+        else if (seen.has(bp)) {
+            issues.push(`${label}.blueprint duplicates an earlier entry`);
+            dup = true;
+        }
+        seen.add(bp);
+        if (shaOk && bp !== self && !dup)
+            valid.push({ blueprint: bp, merged_commit: commit });
+    });
+    return { issues, valid };
+}
+/**
+ * `bouncer.prerequisites` 한 값의 형식만 판정한다. validate-structural의 S39가 이 목록을 그대로
+ * 실패로 옮겨, 구조 검사·승인·helper가 같은 형식 판정을 쓰게 한다.
+ *
+ * @param {unknown} value - 프론트매터의 prerequisites 값. 키가 없으면 undefined
+ * @param {string} selfDir - 이 선언을 가진 blueprint의 저장소 상대 디렉터리(자기참조 판정용)
+ * @returns {string[]} 위반 설명 목록. 비어 있으면 형식이 맞다
+ */
+function prerequisiteFormatIssues(value, selfDir) {
+    return classifyPrerequisites(value, selfDir).issues;
+}
+/**
+ * 기본 Git 실행기. 셸을 거치지 않고 argv 배열로만 호출해 SHA·경로가 명령으로 해석될 여지를 없앤다.
+ * spawn 자체가 실패하면(status null) -1로 돌려 "미병합"(exit 1)과 섞이지 않게 한다.
+ *
+ * @param {string} repoRoot - git을 실행할 저장소 루트
+ * @returns {GitExec} argv → {status, stdout}
+ */
+function defaultExec(repoRoot) {
+    return (args) => {
+        const r = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8' });
+        return { status: typeof r.status === 'number' ? r.status : -1, stdout: r.stdout || '' };
+    };
+}
+/**
+ * blueprint index.md의 prerequisites 원값을 읽는다. 문서가 없거나 frontmatter를 못 읽으면
+ * found/raw를 비워 돌려준다 — 참조 누락은 report의 blueprintFound로, 형식 오류는 그 문서의 S39로
+ * 따로 드러나므로 여기서 던지면 한 문서의 오류가 전체 판정을 가린다. 그 밖의 오류(권한 등)는 다시 던진다.
+ *
+ * @param {string} repoRoot - 저장소 루트
+ * @param {string} dir - blueprint 디렉터리(저장소 상대)
+ * @returns {{found: boolean, raw: unknown}} 문서 존재 여부와 prerequisites 원값
+ */
+function readPrerequisites(repoRoot, dir) {
+    let data;
+    try {
+        data = readDoc(path.join(repoRoot, dir, 'index.md')).data;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT' || e.code === 'ENOTDIR')
+            return { found: false, raw: undefined };
+        // 흡수: frontmatter 부재·YAML 오류(해당 문서의 구조 검사가 별도로 거절). 나머지는 그대로 올린다.
+        if (e.name === 'YAMLException' || e.message === 'missing frontmatter block') {
+            return { found: true, raw: undefined };
+        }
+        throw err;
+    }
+    const bouncer = data?.bouncer;
+    const raw = bouncer && typeof bouncer === 'object'
+        ? bouncer.prerequisites : undefined;
+    return { found: true, raw };
+}
+/** 유효한 항목의 blueprint 경로만 뽑는다(순환 탐색용). 위반 항목은 간선으로 쓰지 않는다. */
+function wellFormedTargets(raw, selfDir) {
+    return classifyPrerequisites(raw, selfDir).valid.map((e) => e.blueprint);
+}
+/**
+ * 선행 선언 그래프에서 순환을 찾는다. 선언된 blueprint 문서만 따라가며 파일은 쓰지 않는다.
+ *
+ * @param {string} repoRoot - 저장소 루트
+ * @param {string} start - 탐색을 시작할 blueprint 디렉터리
+ * @returns {string[][]} 순환 경로 목록(첫 원소와 마지막 원소가 같다). 없으면 빈 배열
+ */
+function findCycles(repoRoot, start) {
+    const cycles = [];
+    const done = new Set();
+    const stack = [];
+    const visit = (dir) => {
+        const at = stack.indexOf(dir);
+        if (at >= 0) {
+            cycles.push([...stack.slice(at), dir]);
+            return;
+        }
+        if (done.has(dir))
+            return;
+        stack.push(dir);
+        for (const next of wellFormedTargets(readPrerequisites(repoRoot, dir).raw, dir))
+            visit(next);
+        stack.pop();
+        done.add(dir);
+    };
+    visit(start);
+    return cycles;
+}
+/**
+ * 한 병합 commit의 상태를 Git으로 판정한다. `rev-parse --verify --quiet`는 object 부재를 exit 1로,
+ * `merge-base --is-ancestor`는 비조상을 exit 1로 알려 주고 그 밖의 실패는 둘 다 조회 오류다.
+ * 어느 쪽도 통과로 접지 않는다. 기준은 현재 checkout HEAD이며 원격·저장된 base는 보지 않는다.
+ *
+ * @param {GitExec} exec - Git 실행 seam
+ * @param {string} sha - 선언된 병합 결과 commit
+ * @returns {CommitState} merged | unmerged | object-missing | lookup-error
+ */
+function commitStateOf(exec, sha) {
+    const found = exec(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]);
+    if (found.status === 1)
+        return 'object-missing';
+    if (found.status !== 0)
+        return 'lookup-error';
+    const anc = exec(['merge-base', '--is-ancestor', sha, 'HEAD']);
+    if (anc.status === 0)
+        return 'merged';
+    return anc.status === 1 ? 'unmerged' : 'lookup-error';
+}
+/**
+ * blueprint가 선언한 선행 병합 근거를 읽기 전용으로 판정한다. 파일을 쓰지 않고 승인·gate에 연결하지 않는다.
+ * 선언이 없으면 형식·항목·순환이 모두 비어 있는 보고를 돌려준다.
+ *
+ * @param {{repoRoot: string, blueprintDir: string, exec?: GitExec}} input - 저장소 루트, 대상 blueprint
+ *   디렉터리, 테스트용 Git seam(기본은 셸 없는 git spawnSync)
+ * @returns {PrerequisiteReport} formatIssues는 S39 후보, entries는 형식이 맞는 항목별 존재·병합 판정,
+ *   cycles는 선행 선언 순환 경로
+ */
+function checkPrerequisites({ repoRoot, blueprintDir, exec }) {
+    const run = exec || defaultExec(repoRoot);
+    const dir = normalizeRepoPath(blueprintDir);
+    const { raw } = readPrerequisites(repoRoot, dir);
+    const { issues: formatIssues, valid } = classifyPrerequisites(raw, dir);
+    // 형식이 틀린 항목은 S39가 이미 보고하므로 Git에 보내지 않는다(잘못된 문자열을 git 인자로 넘기지 않기 위함).
+    const entries = valid.map(({ blueprint, merged_commit: commit }) => ({
+        blueprint,
+        merged_commit: commit,
+        blueprintFound: fs.existsSync(path.join(repoRoot, blueprint, 'index.md')),
+        commitState: commitStateOf(run, commit),
+    }));
+    return { formatIssues, entries, cycles: raw === undefined ? [] : findCycles(repoRoot, dir) };
+}
+module.exports = { prerequisiteFormatIssues, checkPrerequisites };

package/dist/plan-snapshot-contract.js

@@ -0,0 +1,98 @@
+'use strict';
+const { createHash } = require('node:crypto');
+const paths = require("./paths");
+const { epicDirOf } = paths;
+const schema = require("./schema");
+const { executionKindOf, DEFAULT_DEPENDS_ON, DEFAULT_PARALLEL_SAFE, DEFAULT_DEPENDENCY_GATE, DEFAULT_EXCLUSIVE_RESOURCES, } = schema;
+// 본문 단독 hash에서 경로·본문·판단 구조 hash로 바뀐 계약 버전이다.
+const SNAPSHOT_VERSION = 2;
+/**
+ * 문서 경로가 판단 구조의 어느 종류인지 정한다.
+ *
+ * @param {string} rel - 저장소 상대 문서 경로
+ * @param {string} bp - blueprint 상대 경로(POSIX)
+ * @returns {StructureKind} 구조 종류
+ */
+function structureKindOf(rel, bp) {
+    if (rel === `${epicDirOf(bp)}/index.md`)
+        return 'epic';
+    if (rel === `${bp}/index.md`)
+        return 'blueprint';
+    return 'task';
+}
+/**
+ * 구조 필드 배열에서 문자열만 남겨 정렬한다. 중복은 draft gate가 판정한다.
+ *
+ * @param {unknown} value - 문서의 구조 배열 값
+ * @returns {string[]} 정렬된 문자열 배열
+ */
+function sortedStrings(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string').sort() : [];
+}
+/**
+ * 실행 판단 구조를 schema 기본값으로 정규화한다. 상태·제목·시각은 digest 대상이 아니다.
+ *
+ * @param {StructureKind} kind - epic | blueprint | task
+ * @param {unknown} bouncer - 문서 frontmatter의 bouncer 객체
+ * @returns {PlanStructure} 키 순서가 고정된 정규화 구조
+ */
+function normalizeStructure(kind, bouncer) {
+    const b = (bouncer !== null && typeof bouncer === 'object' && !Array.isArray(bouncer)
+        ? bouncer : {});
+    if (kind === 'epic')
+        return {};
+    if (kind === 'blueprint') {
+        return {
+            scale: b.scale === 'light' ? 'light' : 'full',
+            review_scope: b.review_scope === 'blueprint' ? 'blueprint' : null,
+        };
+    }
+    return {
+        affected_paths: sortedStrings(b.affected_paths),
+        depends_on: b.depends_on === undefined ? [...DEFAULT_DEPENDS_ON] : sortedStrings(b.depends_on),
+        parallel_safe: b.parallel_safe === undefined ? DEFAULT_PARALLEL_SAFE : b.parallel_safe === true,
+        dependency_gate: typeof b.dependency_gate === 'string' ? b.dependency_gate : DEFAULT_DEPENDENCY_GATE,
+        exclusive_resources: b.exclusive_resources === undefined
+            ? [...DEFAULT_EXCLUSIVE_RESOURCES] : sortedStrings(b.exclusive_resources),
+        execution_kind: executionKindOf(b) ?? 'commit',
+    };
+}
+/**
+ * 문서 본문의 SHA-256을 계산한다.
+ *
+ * @param {string} body - 문서 본문
+ * @returns {string} hex digest
+ */
+function hashBody(body) {
+    return createHash('sha256').update(body).digest('hex');
+}
+/**
+ * 정규화 구조의 SHA-256을 계산한다.
+ *
+ * @param {PlanStructure} structure - normalizeStructure 결과
+ * @returns {string} hex digest
+ */
+function hashStructure(structure) {
+    return createHash('sha256').update(JSON.stringify(structure)).digest('hex');
+}
+/**
+ * ordered 문서 입력을 경계가 보존되는 JSON으로 직렬화해 digest를 만든다.
+ *
+ * @param {string[]} documents - 문서 순서
+ * @param {Record<string, PlanDocContent>} content - 경로별 본문과 구조
+ * @returns {string} hex digest
+ */
+function digestPlanContent(documents, content) {
+    const ordered = documents.map((file) => ({
+        file, body: content[file].body, structure: content[file].structure,
+    }));
+    return createHash('sha256').update(JSON.stringify(ordered)).digest('hex');
+}
+module.exports = {
+    SNAPSHOT_VERSION,
+    digestPlanContent,
+    normalizeStructure,
+    structureKindOf,
+    hashBody,
+    hashStructure,
+};

package/dist/plan-snapshot.js

@@ -0,0 +1,138 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const tasksDocs = require("./tasks-docs");
+const { listTasksDocs } = tasksDocs;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const paths = require("./paths");
+const { toPosix, epicDirOf } = paths;
+const validateSections = require("./validate-sections");
+const { parseTasksSections } = validateSections;
+const snapshotContract = require("./plan-snapshot-contract");
+const { SNAPSHOT_VERSION, digestPlanContent, normalizeStructure, structureKindOf, hashBody, hashStructure, } = snapshotContract;
+/**
+ * epic·blueprint·tasks.md 상대 경로를 집계 digest와 같은 순서로 모은다.
+ * 문서 집합이 갈라지면 context review 기록과 follow_up 판정이 서로 다른 대상을 본다.
+ *
+ * @param {string} repoRoot - 저장소 루트 절대 경로
+ * @param {string} blueprintDir - blueprint 상대 경로(POSIX)
+ * @returns {string[]} hash·parts에 넣을 저장소 상대 경로 목록
+ */
+function planDocumentRels(repoRoot, blueprintDir) {
+    const bp = toPosix(blueprintDir);
+    const documents = [
+        `${epicDirOf(bp)}/index.md`,
+        `${bp}/index.md`,
+    ];
+    const listing = listTasksDocs({ repoRoot, blueprintDir: bp });
+    for (const entry of listing.entries) {
+        documents.push(entry.tasks.rel);
+    }
+    return documents;
+}
+/**
+ * plan 문서를 한 번 읽어 경로별 본문·정규화 구조와 관찰용 scope_parts를 만든다.
+ * digest·parts·structure_parts가 모두 이 한 번의 읽기에서 나와야 읽기 사이에
+ * 파일이 바뀌어도 서로 다른 내용을 가리키지 않는다.
+ *
+ * @param {string} repoRoot - 저장소 루트 절대 경로
+ * @param {string} blueprintDir - blueprint 상대 경로
+ * @returns {PlanContent} 성공 시 문서 순서·내용·scope_parts, 부재·파싱 실패 시 ok:false와 사유
+ */
+function readPlanContent(repoRoot, blueprintDir) {
+    const bp = toPosix(blueprintDir);
+    const documents = planDocumentRels(repoRoot, bp);
+    const content = {};
+    const scope_parts = {};
+    for (const rel of documents) {
+        const abs = path.join(repoRoot, rel);
+        if (!fs.existsSync(abs)) {
+            return { ok: false, error: `snapshot document missing: ${rel}` };
+        }
+        let body;
+        let data;
+        try {
+            const doc = readDoc(abs);
+            body = doc.body;
+            data = doc.data;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { ok: false, error: `snapshot document unreadable: ${rel}: ${message}` };
+        }
+        const bouncer = data?.bouncer;
+        const kind = structureKindOf(rel, bp);
+        content[rel] = { body, structure: normalizeStructure(kind, bouncer) };
+        // epic·blueprint index는 Interface/Touch가 없다. tasks.md만 관찰용 scope_parts에 넣는다.
+        if (kind !== 'task')
+            continue;
+        const sections = parseTasksSections(body);
+        const interfaceBody = typeof sections.interface === 'string' ? sections.interface : '';
+        const touchBody = typeof sections.touch === 'string' ? sections.touch : '';
+        const structure = content[rel].structure;
+        // 계약 문자열: 정렬 JSON + Interface 본문 + Touch 본문. v1 payload와 같은 공개 관찰
+        // 값이라 순서·구분자를 유지한다. v2에서는 full 판정에 쓰지 않고 보관만 한다.
+        const scopeMaterial = [
+            JSON.stringify(structure.affected_paths),
+            JSON.stringify(structure.depends_on),
+            interfaceBody,
+            touchBody,
+        ].join('\n');
+        scope_parts[rel] = createHash('sha256').update(scopeMaterial).digest('hex');
+    }
+    return { ok: true, documents, content, scope_parts };
+}
+/**
+ * epic·blueprint·tasks.md의 경로·본문·판단 구조로 v2 집계 digest를 만든다.
+ * context-review frozen snapshot과 같은 문서 집합·순서를 유지한다.
+ * frontmatter 중 status/title/timestamp와 commit evidence는 hash에 넣지 않는다 —
+ * status flip만으로 digest가 바뀌면 승인 직후 snapshot이 곧바로 stale 판정을 받는다.
+ * 반대로 affected_paths 등 실행 구조는 digest에 들어가므로 범위 변경은 stale이 된다.
+ *
+ * @param {{ repoRoot: string, blueprintDir: string }} opts - 저장소 루트와 blueprint 상대 경로
+ * @returns {{ ok: true, digest: string, documents: string[] } | { ok: false, error: string }}
+ *   성공 시 hex digest와 hash에 넣은 문서 상대 경로 목록, 문서 부재·파싱 실패 시 ok:false와 사유
+ */
+function computePlanSnapshot({ repoRoot, blueprintDir }) {
+    const read = readPlanContent(repoRoot, blueprintDir);
+    if (!read.ok)
+        return read;
+    return { ok: true, digest: digestPlanContent(read.documents, read.content), documents: read.documents };
+}
+/**
+ * 문서별 본문 digest(`parts`)·구조 digest(`structure_parts`)·관찰용 `scope_parts`와
+ * 이전/이후 비교에 쓰는 `documents_content`를 만든다. 문서마다 별도 sha256을 내어
+ * follow_up이 어느 문서가 어떻게 바뀌었는지 가리킬 수 있게 한다.
+ *
+ * @param {{ repoRoot: string, blueprintDir: string }} opts - 저장소 루트와 blueprint 상대 경로
+ * @returns {{ ok: true, parts: Record<string, string>, scope_parts: Record<string, string>,
+ *   structure_parts: Record<string, string>, documents_content: Record<string, PlanDocContent> }
+ *   | { ok: false, error: string }}
+ *   성공 시 경로→값 맵들, 문서 부재·파싱 실패 시 ok:false와 사유
+ */
+function computePlanParts({ repoRoot, blueprintDir }) {
+    const read = readPlanContent(repoRoot, blueprintDir);
+    if (!read.ok)
+        return read;
+    const parts = {};
+    const structure_parts = {};
+    for (const rel of read.documents) {
+        parts[rel] = hashBody(read.content[rel].body);
+        structure_parts[rel] = hashStructure(read.content[rel].structure);
+    }
+    return {
+        ok: true, parts, scope_parts: read.scope_parts, structure_parts, documents_content: read.content,
+    };
+}
+module.exports = {
+    SNAPSHOT_VERSION,
+    computePlanSnapshot,
+    computePlanParts,
+    digestPlanContent,
+    normalizeStructure,
+    structureKindOf,
+    hashBody,
+    hashStructure,
+};

package/dist/plugin-root.js

@@ -0,0 +1,237 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareSemverDesc = compareSemverDesc;
+exports.parseHost = parseHost;
+exports.findPluginCandidates = findPluginCandidates;
+exports.resolvePluginRoot = resolvePluginRoot;
+exports.assertPluginVersion = assertPluginVersion;
+exports.resolvePluginAssetRoot = resolvePluginAssetRoot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const HOSTS = ['claude', 'codex', 'antigravity'];
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function readDir(dir) {
+    try {
+        return node_fs_1.default.readdirSync(dir).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function candidatePaths(host, homeDir) {
+    if (host === 'antigravity')
+        return [node_path_1.default.join(homeDir, '.gemini', 'antigravity-ide', 'plugins', 'bouncer')];
+    const cache = node_path_1.default.join(homeDir, host === 'claude' ? '.claude' : '.codex', 'plugins', 'cache');
+    return readDir(cache).flatMap((marketplace) => readDir(node_path_1.default.join(cache, marketplace, 'bouncer')).map((version) => node_path_1.default.join(cache, marketplace, 'bouncer', version)));
+}
+function parseVersion(value) {
+    return typeof value === 'string' && SEMVER.test(value) ? value : null;
+}
+// 플러그인 자산 루트로 인정하려면 루트 바로 아래에 있어야 하는 디렉터리와 파일.
+// 메타데이터만 맞는 빈 디렉터리가 자산 루트로 뽑혀 역할 문서·카드를 못 찾는 일을 막는다.
+const REQUIRED_ASSET_DIRS = ['agents', 'skills', 'rules', 'references', 'hooks'];
+const REQUIRED_ASSET_FILES = ['AGENTS.md'];
+function readCandidate(host, root) {
+    const absolute = node_path_1.default.resolve(root);
+    try {
+        // 자산 배포판은 실행 파일을 포함하지 않을 수 있어, 자산과 manifest만 검증한다.
+        for (const dir of REQUIRED_ASSET_DIRS) {
+            if (!node_fs_1.default.statSync(node_path_1.default.join(absolute, dir)).isDirectory())
+                return null;
+        }
+        for (const file of REQUIRED_ASSET_FILES) {
+            if (!node_fs_1.default.statSync(node_path_1.default.join(absolute, file)).isFile())
+                return null;
+        }
+        // npm package.json은 runtime 설치본의 신원만 설명한다. host가 설치한 자산 루트의
+        // plugin manifest 또는 루트 manifest만 자산 버전의 출처로 인정한다.
+        for (const metadataFile of [
+            'plugin.json',
+            '.claude-plugin/plugin.json',
+            '.codex-plugin/plugin.json',
+            '.cursor-plugin/plugin.json',
+        ]) {
+            try {
+                const metadata = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(absolute, metadataFile), 'utf8'));
+                const version = parseVersion(metadata.version);
+                if ((metadata.name === 'bouncer' || metadata.name === '@cheongfish/bouncer') && version) {
+                    return {
+                        host, path: absolute, version,
+                        ...(typeof metadata.runtimeCompatibility === 'string'
+                            ? { runtimeCompatibility: metadata.runtimeCompatibility } : {}),
+                    };
+                }
+            }
+            catch {
+                // 다음 명시적 metadata 형식을 확인한다.
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function semverParts(version) {
+    const match = SEMVER.exec(version);
+    if (!match)
+        throw new Error(`invalid semver: ${version}`);
+    return [match[1], match[2], match[3], match[4]];
+}
+function compareNumericIdentifierDesc(left, right) {
+    if (left.length !== right.length)
+        return right.length - left.length;
+    if (left === right)
+        return 0;
+    return left < right ? 1 : -1;
+}
+// 외부 semver 의존성 없이 strict semver 순서를 보장한다. 버전이 같으면 호출자가
+// 절대 경로로 정렬해 설치 위치가 달라도 결과가 흔들리지 않게 한다.
+function compareSemverDesc(left, right) {
+    const a = semverParts(left);
+    const b = semverParts(right);
+    for (let index = 0; index < 3; index += 1) {
+        const difference = compareNumericIdentifierDesc(a[index], b[index]);
+        if (difference)
+            return difference;
+    }
+    if (a[3] === b[3])
+        return 0;
+    if (a[3] === undefined)
+        return -1;
+    if (b[3] === undefined)
+        return 1;
+    const aParts = a[3].split('.');
+    const bParts = b[3].split('.');
+    for (let index = 0; index < Math.max(aParts.length, bParts.length); index += 1) {
+        const av = aParts[index];
+        const bv = bParts[index];
+        if (av === undefined)
+            return -1;
+        if (bv === undefined)
+            return 1;
+        if (av === bv)
+            continue;
+        const an = /^\d+$/.test(av);
+        const bn = /^\d+$/.test(bv);
+        if (an && bn)
+            return compareNumericIdentifierDesc(av, bv);
+        if (an)
+            return -1;
+        if (bn)
+            return 1;
+        return av < bv ? 1 : -1;
+    }
+    return 0;
+}
+function parseHost(value) {
+    return value !== undefined && HOSTS.includes(value) ? value : null;
+}
+function findPluginCandidates(options = {}, host) {
+    const homeDir = options.homeDir ?? node_os_1.default.homedir();
+    const hosts = host ? [host] : HOSTS;
+    const seen = new Set();
+    const candidates = [];
+    for (const candidateHost of hosts) {
+        for (const root of candidatePaths(candidateHost, homeDir)) {
+            const candidate = readCandidate(candidateHost, root);
+            if (candidate && !seen.has(candidate.path)) {
+                seen.add(candidate.path);
+                candidates.push(candidate);
+            }
+        }
+    }
+    return candidates.sort((a, b) => compareSemverDesc(a.version, b.version) || a.path.localeCompare(b.path));
+}
+function resolvePluginRoot(options = {}, host) {
+    const env = options.env ?? process.env;
+    const runtimeVersion = options.runtimeVersion ?? readRuntimeVersion();
+    let candidate;
+    if (env.BOUNCER_HOME !== undefined) {
+        candidate = readCandidate(host ?? 'claude', env.BOUNCER_HOME) ?? undefined;
+        if (!candidate)
+            throw new Error('BOUNCER_HOME is not a valid Bouncer plugin root');
+    }
+    else {
+        candidate = findPluginCandidates(options, host)[0];
+        if (!candidate)
+            throw new Error('no valid Bouncer plugin roots found');
+    }
+    assertPluginVersion(candidate, runtimeVersion);
+    return candidate;
+}
+/**
+ * 선택된 자산 후보가 이 runtime과 같은 release인지 확인한다.
+ * 후보 정렬과 검증을 분리해 가장 최신 설치가 불일치하면 과거 후보로 우회하지 않는다.
+ *
+ * @param {PluginCandidate} candidate - 선택된 host plugin 후보
+ * @param {string} [runtimeVersion] - 테스트용 runtime version. 생략하면 package.json을 읽는다
+ * @returns {void} 일치하면 반환하고, 다르면 식별 가능한 Error를 던진다
+ */
+function assertPluginVersion(candidate, runtimeVersion = readRuntimeVersion()) {
+    const range = candidate.runtimeCompatibility;
+    const supported = range === undefined
+        ? candidate.version === runtimeVersion
+        : isRuntimeCompatible(runtimeVersion, range);
+    if (supported)
+        return;
+    const error = new Error(`Bouncer plugin version ${candidate.version} is incompatible with runtime version ${runtimeVersion}`
+        + `${range === undefined ? '' : ` (supported: ${range})`}; `
+        + 'install a compatible npm runtime version or repair BOUNCER_HOME to a compatible plugin install');
+    error.code = 'BOUNCER_PLUGIN_VERSION_MISMATCH';
+    throw error;
+}
+function isRuntimeCompatible(version, range) {
+    // Deliberately accept only explicit comparator sets to keep manifest parsing predictable.
+    const clauses = range.trim().split(/\s+/);
+    if (clauses.length === 0 || clauses.some((clause) => !/^(>=|>|<=|<|=)\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(clause))) {
+        return false;
+    }
+    return clauses.every((clause) => {
+        const match = /^(>=|>|<=|<|=)(.+)$/.exec(clause);
+        if (!match || !parseVersion(match[2]))
+            return false;
+        const order = compareSemverDesc(version, match[2]);
+        // compareSemverDesc returns positive when version sorts before the bound.
+        if (match[1] === '>=')
+            return order <= 0;
+        if (match[1] === '>')
+            return order < 0;
+        if (match[1] === '<=')
+            return order >= 0;
+        if (match[1] === '<')
+            return order > 0;
+        return order === 0;
+    });
+}
+/**
+ * 설치된 CLI package.json의 버전을 읽는다. 자산 manifest와 runtime의 비교 기준은
+ * 실제 실행 중인 npm package에 고정해 배포본 간 불일치를 선택 직후 드러낸다.
+ *
+ * @returns {string} 유효한 strict semver runtime version
+ */
+function readRuntimeVersion() {
+    const metadata = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(__dirname, '..', 'package.json'), 'utf8'));
+    const version = parseVersion(metadata.version);
+    if (!version)
+        throw new Error('Bouncer runtime package.json has an invalid version');
+    return version;
+}
+/**
+ * 플러그인 자산(`agents/`, `references/coordinator-cards/`)을 읽을 검증된 루트를 돌려준다.
+ * 순서는 `BOUNCER_HOME` → strict-semver가 가장 높은 host 후보이며, 선택된 설치의
+ * `runtimeCompatibility`가 있으면 runtime version이 범위에 포함되어야 한다. 오래된
+ * manifest는 plugin version과 runtime version이 일치해야 한다. runtime tree는 자산 설치 여부를
+ * 증명하지 않으므로 후보로 추론하지 않는다.
+ *
+ * @param {AssetRootOptions} [options] - `env`, `homeDir`, resolver 테스트용 `runtimeVersion`
+ * @returns {string} 자산 루트 절대 경로
+ * @throws 명시 root가 무효이거나 후보가 없거나 선택된 plugin/runtime version이 다르면 Error
+ */
+function resolvePluginAssetRoot(options = {}) {
+    return resolvePluginRoot(options).path;
+}

package/dist/posix-path.js

@@ -0,0 +1,14 @@
+'use strict';
+// toPosix의 단일 정의. 어떤 ./ 모듈도 import하지 않는다 — paths ↔ tasks-docs
+// 순환을 끊으려면 가장 아래 계층이어야 하고, cli lazy-load 단언도 지켜야 한다.
+/**
+ * 경로 문자열의 모든 백슬래시를 슬래시로 바꾼다.
+ * unknown을 받는 이유: 기존 호출부 일부가 비문자열 입력을 `String()`으로 넘긴다.
+ *
+ * @param {unknown} p - 변환할 경로 값
+ * @returns {string} 슬래시 구분 경로
+ */
+function toPosix(p) {
+    return String(p).split('\\').join('/');
+}
+module.exports = { toPosix };