@bolloon/bolloon-agent 0.1.0

package/src/bollharness/src/scripts/checks/next_decision_number.ts

@@ -0,0 +1,24 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+
+const REPO_ROOT = process.cwd();
+
+export function main(): void {
+  const args = process.argv.slice(2);
+  if (args[0] === "next") {
+    try {
+      const result = execSync("git log --oneline -1", { cwd: REPO_ROOT, encoding: "utf-8" });
+      const match = result.match(/ADR-(\d+)/);
+      if (match) {
+        const nextNum = parseInt(match[1], 10) + 1;
+        console.log(`ADR-${nextNum}`);
+      }
+    } catch {}
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}

package/src/bollharness/src/scripts/checks/regenerate_magic_docs.ts

@@ -0,0 +1,11 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Finding } from "./finding";
+
+export function run(repoRoot: string, mode: string = "full"): Finding[] {
+  const findings: Finding[] = [];
+
+  if (mode !== "full" && mode !== "ci") return findings;
+
+  return findings;
+}

package/src/bollharness/src/scripts/ci/detect_rebaseline_triggers.ts

@@ -0,0 +1,14 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+
+const REPO_ROOT = process.cwd();
+
+export function main(): void {
+  console.log("Detecting rebase triggers...");
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}

package/src/bollharness/src/scripts/ci/scan_subprocess_cfg.ts

@@ -0,0 +1,14 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+
+const REPO_ROOT = process.cwd();
+
+export function main(): void {
+  console.log("Scanning subprocess configurations...");
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}

package/src/bollharness/src/scripts/ci/scan_verify_artifacts.ts

@@ -0,0 +1,14 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+
+const REPO_ROOT = process.cwd();
+
+export function main(): void {
+  console.log("Scanning for artifact verification...");
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}

package/src/bollharness/src/scripts/ci/scan_yaml_schema.ts

@@ -0,0 +1,14 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+
+const REPO_ROOT = process.cwd();
+
+export function main(): void {
+  console.log("Scanning YAML schemas...");
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}

package/src/bollharness/src/scripts/context_router.ts

@@ -0,0 +1,76 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+export const FRAGMENTS_DIR = path.join(__dirname, "..", "context-fragments");
+
+export const CONTEXT_MAP: Record<string, string[]> = {
+  "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: string): string[] {
+  if (!filePath) return [];
+  if (path.isAbsolute(filePath)) return [];
+
+  const normalized = path.normalize(filePath).replace(/\\/g, "/");
+  if (normalized.startsWith("../") || normalized === ".." || normalized.includes("/../")) {
+    return [];
+  }
+
+  const matched: string[] = [];
+  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: string): string {
+  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/src/bollharness/src/scripts/deploy-guard.ts

@@ -0,0 +1,182 @@
+import * as fs from "fs";
+import * as path from "path";
+
+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"]);
+
+interface GuardInput {
+  tool_name: string;
+  tool_input: {
+    command?: string;
+  };
+}
+
+function getCommand(): string | null {
+  try {
+    const input: GuardInput = JSON.parse(fs.readFileSync(0, "utf-8"));
+    return input.tool_input?.command ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isDeploySh(cmd: string): boolean {
+  return DEPLOY_SH_PATTERN.test(cmd.trim());
+}
+
+function hasGuardedHost(cmd: string): boolean {
+  return GUARDED_HOSTS.some(host => cmd.includes(host));
+}
+
+function whichGuardedHost(cmd: string): string | null {
+  for (const host of GUARDED_HOSTS) {
+    if (cmd.includes(host)) return host;
+  }
+  return null;
+}
+
+function isCompoundCommand(cmd: string): boolean {
+  let stripped = cmd.replace(/"[^"]*"/g, "");
+  stripped = stripped.replace(/'[^']*'/g, "");
+  return /[;&|]{1,2}/.test(stripped);
+}
+
+function checkScpDirection(cmd: string): "upload" | "download" | "none" {
+  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: string): "write" | "readonly" | "none" {
+  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: string): "write" | "dryrun" | "none" {
+  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: string, host: string | null = null): void {
+  let guidance: string;
+  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(): void {
+  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/src/bollharness/src/scripts/guard-feedback.ts

@@ -0,0 +1,215 @@
+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";
+import { Finding } from "./checks/finding";
+
+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: string, data: Record<string, unknown> = {}): void {
+  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(): Set<string> {
+  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: Set<string>): void {
+  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(): string | null {
+  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: string, repoRoot: string): string | null {
+  try {
+    const resolved = path.resolve(filePath);
+    return path.relative(repoRoot, resolved);
+  } catch {
+    return null;
+  }
+}
+
+function appendFindings(outputParts: string[], findings: Finding[]): void {
+  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(): Promise<void> {
+  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: string[] = [];
+
+  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: string[] = [];
+  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: Record<string, number> = {};
+    const severities: Record<string, number> = {};
+    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();
+}