@bolloon/bolloon-agent 0.1.0 → 0.1.2

package/dist/bollharness/src/scripts/context_router.js

@@ -0,0 +1,67 @@
+import * as fs from "fs";
+import * as path from "path";
+export const FRAGMENTS_DIR = path.join(__dirname, "..", "context-fragments");
+export const CONTEXT_MAP = {
+    "bridge_agent/": ["bridge-constitution"],
+    "backend/product/bridge/": ["bridge-constitution"],
+    "mcp-server/": ["mcp-parity"],
+    "mcp-server-node/": ["mcp-parity"],
+    "backend/product/routes/protocol.py": ["protocol-consumers", "contract-consumers"],
+    "backend/product/protocol/": ["protocol-consumers"],
+    "backend/product/routes/": ["contract-consumers"],
+    "backend/product/db/crud_events.py": ["run-events-consumers"],
+    "backend/product/auth/": ["auth-consumers"],
+    "backend/product/db/": ["db-shared-structures"],
+    "backend/product/catalyst/": ["catalyst-distributed"],
+    "docs/issues/": ["fixed-three-layers", "closure-checklist"],
+    "scenes/": ["scene-fidelity", "two-language"],
+    "website/app/[scene]/": ["scene-fidelity", "two-language"],
+    "website/components/scene/": ["scene-fidelity", "two-language"],
+    "CLAUDE.md": ["truth-source-hierarchy"],
+    "MEMORY.md": ["truth-source-hierarchy"],
+    "docs/INDEX.md": ["truth-source-hierarchy"],
+    "mcp-server/pyproject.toml": ["version-sources"],
+    "mcp-server-node/package.json": ["version-sources"],
+    "website/": ["two-language"],
+    "docs/decisions/": ["artifact-linkage"],
+    "backend/product/": ["issue-first"],
+    "backend/server.py": ["issue-first"],
+    "mcp-server/boll_mcp/": ["issue-first"],
+    "mcp-server-node/src/": ["issue-first"],
+    "website/app/": ["issue-first"],
+};
+export const FALLBACK_FRAGMENTS = ["general-dev-principles"];
+export function match(filePath) {
+    if (!filePath)
+        return [];
+    if (path.isAbsolute(filePath))
+        return [];
+    const normalized = path.normalize(filePath).replace(/\\/g, "/");
+    if (normalized.startsWith("../") || normalized === ".." || normalized.includes("/../")) {
+        return [];
+    }
+    const matched = [];
+    const sortedPatterns = Object.keys(CONTEXT_MAP).sort((a, b) => b.length - a.length);
+    for (const pattern of sortedPatterns) {
+        if (normalized.startsWith(pattern) || normalized.endsWith(pattern)) {
+            matched.push(...CONTEXT_MAP[pattern]);
+        }
+    }
+    return [...new Set(matched)];
+}
+export function loadFragment(name) {
+    if (!name)
+        return "";
+    const candidate = path.join(FRAGMENTS_DIR, `${name}.md`);
+    try {
+        const resolved = path.resolve(candidate);
+        const fragmentsDirResolved = path.resolve(FRAGMENTS_DIR);
+        if (!resolved.startsWith(fragmentsDirResolved))
+            return "";
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+            return fs.readFileSync(resolved, "utf-8").trim();
+        }
+    }
+    catch { }
+    return "";
+}

package/dist/bollharness/src/scripts/deploy-guard.js

@@ -0,0 +1,157 @@
+import * as fs from "fs";
+const PROD_IP = "47.118.31.230";
+const BRIDGE_VPS_HOSTS = ["46.250.229.84"];
+const GUARDED_HOSTS = [PROD_IP, ...BRIDGE_VPS_HOSTS];
+const DEPLOY_SH_PATTERN = /^bash\s+scripts\/deploy\.sh(\s+--(dry-run|yes))*\s*$/;
+const SSH_READONLY_CMDS = new Set([
+    "journalctl", "cat", "ls", "head", "tail", "grep",
+    "ss", "curl", "dig", "status", "git", "file", "stat",
+]);
+const SYSTEMCTL_WRITE_OPS = new Set(["restart", "stop", "start"]);
+function getCommand() {
+    try {
+        const input = JSON.parse(fs.readFileSync(0, "utf-8"));
+        return input.tool_input?.command ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function isDeploySh(cmd) {
+    return DEPLOY_SH_PATTERN.test(cmd.trim());
+}
+function hasGuardedHost(cmd) {
+    return GUARDED_HOSTS.some(host => cmd.includes(host));
+}
+function whichGuardedHost(cmd) {
+    for (const host of GUARDED_HOSTS) {
+        if (cmd.includes(host))
+            return host;
+    }
+    return null;
+}
+function isCompoundCommand(cmd) {
+    let stripped = cmd.replace(/"[^"]*"/g, "");
+    stripped = stripped.replace(/'[^']*'/g, "");
+    return /[;&|]{1,2}/.test(stripped);
+}
+function checkScpDirection(cmd) {
+    const parts = cmd.split(/\s+/);
+    if (!parts.length || parts[0] !== "scp")
+        return "none";
+    const args = parts.slice(1).filter(p => !p.startsWith("-"));
+    if (args.length < 2)
+        return "none";
+    const lastArg = args[args.length - 1];
+    if (GUARDED_HOSTS.some(host => lastArg.includes(host))) {
+        return "upload";
+    }
+    for (const arg of args.slice(0, -1)) {
+        if (GUARDED_HOSTS.some(host => arg.includes(host))) {
+            return "download";
+        }
+    }
+    return "none";
+}
+function checkSshCommand(cmd) {
+    if (!cmd.includes("ssh") || !hasGuardedHost(cmd))
+        return "none";
+    const quoted = cmd.match(/"([^"]*)"/)?.[1] ?? cmd.match(/'([^']*)'/)?.[1];
+    if (!quoted)
+        return "none";
+    const remoteCmd = quoted.trim();
+    const parts = remoteCmd.split(/\s+/);
+    if (!parts.length)
+        return "none";
+    let idx = 0;
+    if (parts[0] === "sudo") {
+        idx = 1;
+        while (idx < parts.length && parts[idx].startsWith("-")) {
+            if (parts[idx] === "-u" && idx + 1 < parts.length) {
+                idx += 2;
+            }
+            else {
+                idx += 1;
+            }
+        }
+    }
+    const firstWord = parts[idx] ?? "";
+    if (firstWord === "systemctl") {
+        if (idx + 1 < parts.length && SYSTEMCTL_WRITE_OPS.has(parts[idx + 1])) {
+            return "write";
+        }
+        return "readonly";
+    }
+    if (SSH_READONLY_CMDS.has(firstWord)) {
+        return "readonly";
+    }
+    return "write";
+}
+function checkRsync(cmd) {
+    if (!cmd.includes("rsync") || !hasGuardedHost(cmd))
+        return "none";
+    const parts = cmd.split(/\s+/);
+    if (parts.includes("-n") || cmd.includes("--dry-run")) {
+        return "dryrun";
+    }
+    for (const p of parts) {
+        if (p.startsWith("-") && !p.startsWith("--") && p.includes("n")) {
+            return "dryrun";
+        }
+    }
+    return "write";
+}
+function block(reason, host = null) {
+    let guidance;
+    if (host === PROD_IP) {
+        guidance = `请使用标准部署流程：
+  后端: bash scripts/deploy.sh --yes
+  Demo 正式: bash scripts/deploy-demo.sh <name> --channel prod --yes
+  Demo 内测: bash scripts/deploy-demo.sh <name> --channel preview --yes
+  Edge/Nginx: bash scripts/deploy-edge.sh --yes
+详见 CLAUDE.md Development Commands。`;
+    }
+    else if (BRIDGE_VPS_HOSTS.includes(host ?? "")) {
+        guidance = `Bridge VPS 必须走 git pull 更新路径：
+  ssh root@${host} 'sudo -u boll git -C /opt/boll pull --ff-only'
+  scp/rsync 直传会重新制造 orphan worktree。
+  详见 docs/issues/guard-20260408-0445-bridge-vps-orphan-worktree.md。`;
+    }
+    else {
+        guidance = "未识别的受保护服务器目标，请确认 deploy 路径。";
+    }
+    process.stderr.write(`BLOCKED: ${reason}\n${guidance}\n`);
+    process.exit(1);
+}
+export function main() {
+    const cmd = getCommand();
+    if (!cmd)
+        process.exit(0);
+    if (!hasGuardedHost(cmd))
+        process.exit(0);
+    const host = whichGuardedHost(cmd);
+    if (isCompoundCommand(cmd)) {
+        block("检测到复合命令中包含受保护服务器操作，禁止绕过标准部署路径", host);
+    }
+    if (isDeploySh(cmd))
+        process.exit(0);
+    const scpDir = checkScpDirection(cmd);
+    if (scpDir === "upload")
+        block("禁止手动 scp 上传到受保护服务器", host);
+    if (scpDir === "download")
+        process.exit(0);
+    const sshType = checkSshCommand(cmd);
+    if (sshType === "write")
+        block("禁止手动对受保护服务器执行写操作", host);
+    if (sshType === "readonly")
+        process.exit(0);
+    const rsyncType = checkRsync(cmd);
+    if (rsyncType === "write")
+        block("禁止手动 rsync 写入受保护服务器", host);
+    if (rsyncType === "dryrun")
+        process.exit(0);
+    block("检测到未识别的受保护服务器操作", host);
+}
+if (require.main === module) {
+    main();
+}

package/dist/bollharness/src/scripts/guard-feedback.js

@@ -0,0 +1,192 @@
+import * as fs from "fs";
+import * as path from "path";
+import { match, loadFragment, FALLBACK_FRAGMENTS } from "./context_router";
+import { readAllSignals, runGuards, writeSessionSignal } from "./guard_router";
+const INJECTED_TTL = 3600;
+const INJECTED_FILE = path.join(process.cwd(), ".boll", "guard", "injected.json");
+const METRICS_DIR = path.join(process.cwd(), ".boll", "metrics");
+const METRICS_FILE = path.join(METRICS_DIR, "guard-events.jsonl");
+function emitMetric(event, data = {}) {
+    try {
+        if (!fs.existsSync(METRICS_DIR)) {
+            fs.mkdirSync(METRICS_DIR, { recursive: true });
+        }
+        const record = {
+            ts: new Date().toISOString(),
+            session_pid: process.ppid,
+            event,
+            ...data,
+        };
+        fs.appendFileSync(METRICS_FILE, JSON.stringify(record) + "\n", "utf-8");
+    }
+    catch { }
+}
+function readInjected() {
+    if (!fs.existsSync(INJECTED_FILE))
+        return new Set();
+    try {
+        const data = JSON.parse(fs.readFileSync(INJECTED_FILE, "utf-8"));
+        if (Date.now() / 1000 - data.timestamp > INJECTED_TTL)
+            return new Set();
+        return new Set(data.fragments || []);
+    }
+    catch {
+        return new Set();
+    }
+}
+function writeInjected(fragments) {
+    const guardDir = path.join(process.cwd(), ".boll", "guard");
+    if (!fs.existsSync(guardDir)) {
+        fs.mkdirSync(guardDir, { recursive: true });
+    }
+    const data = { timestamp: Date.now() / 1000, fragments: Array.from(fragments).sort() };
+    fs.writeFileSync(INJECTED_FILE, JSON.stringify(data, null, 2), "utf-8");
+}
+function getFilePath() {
+    if (process.argv.includes("--dry-run")) {
+        const idx = process.argv.indexOf("--dry-run");
+        if (idx + 1 < process.argv.length) {
+            return process.argv[idx + 1];
+        }
+        return null;
+    }
+    try {
+        const input = JSON.parse(fs.readFileSync(0, "utf-8"));
+        return input.tool_input?.file_path ?? input.tool_input?.path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function makeRelative(filePath, repoRoot) {
+    try {
+        const resolved = path.resolve(filePath);
+        return path.relative(repoRoot, resolved);
+    }
+    catch {
+        return null;
+    }
+}
+function appendFindings(outputParts, findings) {
+    outputParts.push("\n\n## Guard Findings\n");
+    for (const raw of findings) {
+        const f = raw;
+        const blockingTag = f.blocking ? " [blocking]" : "";
+        const skills = f.required_skills.join(", ");
+        const skillsLine = skills ? `\n  required_skills: ${skills}` : "";
+        outputParts.push(`- ${f.severity}${blockingTag} ${f.category}: ${f.message}${skillsLine}`);
+    }
+}
+const REPO_ROOT = process.cwd();
+const checksDir = path.join(REPO_ROOT, "src", "scripts", "checks");
+export async function main() {
+    const startMs = Date.now();
+    const checkOnly = process.argv.includes("--check-only");
+    const once = process.argv.includes("--once");
+    const dryRun = process.argv.includes("--dry-run");
+    emitMetric("hook_trigger", {
+        mode: checkOnly ? "check_only" : "post_tool_use",
+        once,
+        dry_run: dryRun,
+    });
+    if (once) {
+        const guardDir = path.join(process.cwd(), ".boll", "guard");
+        const sessionFile = path.join(guardDir, `once-${process.pid}.flag`);
+        if (fs.existsSync(sessionFile)) {
+            try {
+                const ts = parseFloat(fs.readFileSync(sessionFile, "utf-8").trim());
+                if (Date.now() / 1000 - ts < 3600) {
+                    process.exit(0);
+                }
+            }
+            catch { }
+        }
+        if (!fs.existsSync(guardDir)) {
+            fs.mkdirSync(guardDir, { recursive: true });
+        }
+        fs.writeFileSync(sessionFile, String(Date.now() / 1000), "utf-8");
+    }
+    const outputParts = [];
+    if (checkOnly) {
+        const signal = readAllSignals(process.pid);
+        const findings = signal.findings;
+        if (findings.length) {
+            appendFindings(outputParts, findings);
+            process.stderr.write(outputParts.join("\n") + "\n");
+            emitMetric("check_only_findings", {
+                findings_count: findings.length,
+                elapsed_ms: Date.now() - startMs,
+            });
+            process.exit(0);
+        }
+        process.exit(0);
+    }
+    let filePath = getFilePath();
+    if (!filePath)
+        process.exit(0);
+    filePath = makeRelative(filePath, REPO_ROOT);
+    if (!filePath) {
+        emitMetric("path_rejected", { reason: "outside_repo_or_unresolvable" });
+        process.exit(0);
+    }
+    const alreadyInjected = readInjected();
+    let fragments = match(filePath);
+    if (!fragments.length) {
+        fragments = Array.isArray(FALLBACK_FRAGMENTS) ? FALLBACK_FRAGMENTS : [FALLBACK_FRAGMENTS];
+    }
+    const newFragments = fragments.filter(f => !alreadyInjected.has(f));
+    const contentParts = [];
+    for (const name of newFragments) {
+        const text = loadFragment(name);
+        if (text)
+            contentParts.push(text);
+    }
+    if (newFragments.length) {
+        const totalBytes = contentParts.reduce((sum, p) => sum + Buffer.byteLength(p, "utf-8"), 0);
+        emitMetric("fragment_inject", {
+            file_path: filePath,
+            fragments: newFragments,
+            count: newFragments.length,
+            bytes: totalBytes,
+            est_tokens: Math.ceil(totalBytes / 4),
+        });
+    }
+    if (contentParts.length) {
+        outputParts.push("## Context\n");
+        outputParts.push(contentParts.join("\n\n---\n\n"));
+        newFragments.forEach(f => alreadyInjected.add(f));
+        writeInjected(alreadyInjected);
+    }
+    const findings = await runGuards(filePath, checksDir);
+    if (findings.length) {
+        const blockingCount = findings.filter(f => f.blocking).length;
+        const categories = {};
+        const severities = {};
+        for (const f of findings) {
+            categories[f.category] = (categories[f.category] || 0) + 1;
+            severities[f.severity] = (severities[f.severity] || 0) + 1;
+        }
+        emitMetric("guard_findings", {
+            file_path: filePath,
+            findings_count: findings.length,
+            blocking_count: blockingCount,
+            categories,
+            severities,
+        });
+        writeSessionSignal(findings);
+        appendFindings(outputParts, findings);
+    }
+    emitMetric("hook_done", {
+        file_path: filePath,
+        had_output: outputParts.length > 0,
+        elapsed_ms: Date.now() - startMs,
+    });
+    if (outputParts.length) {
+        process.stderr.write(outputParts.join("\n") + "\n");
+        process.exit(2);
+    }
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}

package/dist/bollharness/src/scripts/guard_router.js

@@ -0,0 +1,158 @@
+import * as fs from "fs";
+import * as path from "path";
+export const GUARD_MAP = {
+    "bridge_agent/": ["check_bridge_deps"],
+    "backend/product/bridge/": ["check_bridge_deps"],
+    "mcp-server/": ["check_mcp_parity"],
+    "mcp-server-node/": ["check_mcp_parity"],
+    "docs/issues/": ["check_issue_closure"],
+    "backend/product/routes/": ["check_doc_freshness"],
+    "docs/ROADMAP.md": ["check_doc_freshness"],
+    "CLAUDE.md": ["check_doc_freshness"],
+    "docs/magic/": ["check_doc_freshness"],
+    ".boll/rules/backend-routes.md": ["check_doc_freshness"],
+    ".boll/settings.json": ["check_hook_installed"],
+    ".githooks/": ["check_hook_installed"],
+    "scripts/context_router.ts": ["check_fragment_integrity"],
+    "scripts/context-fragments/": ["check_fragment_integrity"],
+};
+export const DEFAULT_GUARDS = [];
+export const CATEGORY_TO_SKILLS = {
+    closure_semantics: ["lead", "boll-ops"],
+    contract_drift: ["boll-dev", "boll-eng-test"],
+    bridge_boundary: ["boll-bridge", "boll-ops"],
+    policy_freeze: ["lead", "arch", "plan-lock"],
+    doc_integrity: ["boll-ops"],
+    version_drift: ["boll-ops"],
+    artifact_linkage: ["lead"],
+    governance_bootstrap: ["boll-ops"],
+};
+const SESSION_TTL_SECONDS = 3600;
+export function route(filePath) {
+    const matched = [];
+    const sortedPatterns = Object.keys(GUARD_MAP).sort((a, b) => b.length - a.length);
+    for (const pattern of sortedPatterns) {
+        if (filePath.startsWith(pattern) || filePath === pattern.replace(/\/$/, "")) {
+            matched.push(...GUARD_MAP[pattern]);
+        }
+    }
+    if (matched.length === 0) {
+        return [...DEFAULT_GUARDS];
+    }
+    return [...new Set(matched)];
+}
+export async function runGuards(filePath, checksDir) {
+    const guardNames = route(filePath);
+    const findings = [];
+    for (const name of guardNames) {
+        try {
+            const checkModule = await import(path.join(checksDir, `${name}.js`));
+            if (!checkModule.run) {
+                findings.push({
+                    severity: "P1",
+                    message: `${name} has no run() function`,
+                    file: `scripts/checks/${name}.ts`,
+                    blocking: false,
+                    category: "governance_bootstrap",
+                    problem_class: "unknown",
+                    required_skills: [],
+                    required_reads: [],
+                });
+                continue;
+            }
+            const result = checkModule.run(checksDir, { mode: "full" });
+            if (Array.isArray(result)) {
+                findings.push(...result);
+            }
+            else {
+                findings.push(result);
+            }
+        }
+        catch (exc) {
+            findings.push({
+                severity: "P0",
+                message: `Failed to import guard ${name}: ${exc}`,
+                file: `scripts/checks/${name}.ts`,
+                blocking: true,
+                category: "governance_bootstrap",
+                problem_class: "unknown",
+                required_skills: [],
+                required_reads: [],
+            });
+        }
+    }
+    return findings;
+}
+function getGuardDir() {
+    return path.join(process.cwd(), ".boll", "guard");
+}
+export function writeSessionSignal(findings) {
+    const guardDir = getGuardDir();
+    if (!fs.existsSync(guardDir)) {
+        fs.mkdirSync(guardDir, { recursive: true });
+    }
+    const pid = process.pid;
+    const target = path.join(guardDir, `session-${pid}.json`);
+    const tmp = path.join(guardDir, `session-${pid}.tmp`);
+    const data = {
+        pid,
+        timestamp: Date.now() / 1000,
+        findings,
+    };
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+    fs.renameSync(tmp, target);
+    return target;
+}
+export function readAllSignals(pid) {
+    const guardDir = getGuardDir();
+    if (!fs.existsSync(guardDir)) {
+        return { severity: null, blocking: false, required_skills: [], findings: [] };
+    }
+    const severityOrder = { P0: 0, P1: 1, P2: 2 };
+    const now = Date.now() / 1000;
+    const allFindings = [];
+    let maxSeverity = null;
+    let blocking = false;
+    const skills = new Set();
+    let paths;
+    if (pid !== undefined) {
+        paths = [path.join(guardDir, `session-${pid}.json`)];
+    }
+    else {
+        paths = fs.readdirSync(guardDir)
+            .filter(f => f.startsWith("session-") && f.endsWith(".json"))
+            .map(f => path.join(guardDir, f));
+    }
+    for (const p of paths) {
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            const data = JSON.parse(fs.readFileSync(p, "utf-8"));
+            const ts = data.timestamp;
+            if (now - ts > SESSION_TTL_SECONDS) {
+                try {
+                    fs.unlinkSync(p);
+                }
+                catch { }
+                continue;
+            }
+            for (const f of data.findings) {
+                allFindings.push(f);
+                const sev = f.severity;
+                if (maxSeverity === null || severityOrder[sev] < severityOrder[maxSeverity]) {
+                    maxSeverity = sev;
+                }
+                if (f.blocking)
+                    blocking = true;
+                f.required_skills.forEach(s => skills.add(s));
+            }
+        }
+        catch { }
+    }
+    return {
+        severity: maxSeverity,
+        blocking,
+        required_skills: Array.from(skills).sort(),
+        findings: allFindings,
+    };
+}

package/dist/bollharness/src/scripts/hooks/_hook_output.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+process.stdout.write(`\n\n## Bollharness Context\n\n` +
+    `bollharness is an AI Agent Session Governance Framework.\n\n` +
+    `For more information, see CLAUDE.md in the project root.\n`);
+process.exit(0);
+export {};

package/dist/bollharness/src/scripts/hooks/auto-python3.js

@@ -0,0 +1,6 @@
+export function main() {
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}

package/dist/bollharness/src/scripts/hooks/deploy-progress-on-session-end.js

@@ -0,0 +1,6 @@
+export function main() {
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}

package/dist/bollharness/src/scripts/hooks/failure-analyzer.js

@@ -0,0 +1,6 @@
+export function main() {
+    process.exit(0);
+}
+if (require.main === module) {
+    main();
+}