brainblast 0.4.3 → 0.5.1

package/README.md

@@ -184,7 +184,7 @@ All types are exported: `Rule`, `CheckResult`, `CostReport`, `AccountFlow`,
 
 ```sh
 npm install
-npm test         # unit suite (180 tests)
+npm test         # unit suite (214 tests)
 npm run prove    # end-to-end: generated tests RED on vulnerable, GREEN on fixed
 npm run build    # produce dist/ (the published artifact)
 ```

package/dist/{chunk-XQUQOBXZ.js → chunk-LOPYKIXE.js}

@@ -662,6 +662,44 @@ var taintToSink = (c, p) => {
   return { result: "pass", detail: "No tracked source value flows to a sink within the analyzed call graph." };
 };
 
+// src/checkers/literalMultiplierWrongConstant.ts
+import { SyntaxKind as SyntaxKind8 } from "ts-morph";
+function callName4(call) {
+  const exp = call.getExpression();
+  if (exp.getKind() === SyntaxKind8.Identifier) return exp.getText();
+  if (exp.getKind() === SyntaxKind8.PropertyAccessExpression) {
+    return exp.asKind(SyntaxKind8.PropertyAccessExpression).getName();
+  }
+  return "";
+}
+function containsIdentifier(node, name) {
+  if (node.getKind() === SyntaxKind8.Identifier && node.getText() === name) return true;
+  return node.getDescendantsOfKind(SyntaxKind8.Identifier).some((id) => id.getText() === name);
+}
+var literalMultiplierWrongConstant = (c, p) => {
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind8.CallExpression).filter((x) => callName4(x) === p.call);
+  if (calls.length === 0) {
+    return { result: "cant_tell", detail: p.absentCallDetail };
+  }
+  const arg = calls[0].getArguments()[p.argIndex];
+  if (!arg) {
+    return { result: "cant_tell", detail: p.absentCallDetail };
+  }
+  const forbidden = Array.isArray(p.forbiddenIdentifiers) ? p.forbiddenIdentifiers : [];
+  for (const name of forbidden) {
+    if (containsIdentifier(arg, name)) {
+      return { result: "fail", detail: String(p.failDetail).replace("{got}", name) };
+    }
+  }
+  const expected = Array.isArray(p.expectedIdentifiers) ? p.expectedIdentifiers : [];
+  for (const name of expected) {
+    if (containsIdentifier(arg, name)) {
+      return { result: "pass", detail: String(p.passDetail) };
+    }
+  }
+  return { result: "cant_tell", detail: p.cantTellDetail };
+};
+
 // src/checkers/index.ts
 var registry = {
   "positional-arg-identity": positionalArgIdentity,
@@ -671,7 +709,8 @@ var registry = {
   "object-arg-property-literal-equals": objectArgPropertyLiteralEquals,
   "anchor-init-if-needed-guarded": anchorInitIfNeededGuarded,
   "env-secrets-committed": envSecretsCommitted,
-  "taint-to-sink": taintToSink
+  "taint-to-sink": taintToSink,
+  "literal-multiplier-wrong-constant": literalMultiplierWrongConstant
 };
 function runChecker(kind, c, params) {
   const fn = registry[kind];
@@ -887,7 +926,7 @@ function findRustCandidates(targetDir, rule) {
 }
 
 // src/fixers/positionalArgIdentity.ts
-import { SyntaxKind as SyntaxKind8 } from "ts-morph";
+import { SyntaxKind as SyntaxKind9 } from "ts-morph";
 
 // src/fixers/diffUtil.ts
 function buildDiff(node, replacement) {
@@ -912,9 +951,9 @@ function buildDiff(node, replacement) {
 // src/fixers/positionalArgIdentity.ts
 var fixPositionalArgIdentity = (c, p, outcome) => {
   if (outcome.result !== "fail") return void 0;
-  const calls = c.fn.getDescendantsOfKind(SyntaxKind8.CallExpression).filter((call) => {
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind9.CallExpression).filter((call) => {
     const exp = call.getExpression();
-    return exp.getKind() === SyntaxKind8.PropertyAccessExpression && exp.asKind(SyntaxKind8.PropertyAccessExpression).getName() === p.call;
+    return exp.getKind() === SyntaxKind9.PropertyAccessExpression && exp.asKind(SyntaxKind9.PropertyAccessExpression).getName() === p.call;
   });
   if (calls.length === 0) {
     const wantParam2 = c.params[p.paramIndex] ?? "<rawBodyParam>";
@@ -929,7 +968,7 @@ Do not call JSON.parse() on the body before this verification step.`
   }
   const arg = calls[0].getArguments()[p.argIndex];
   const wantParam = c.params[p.paramIndex];
-  if (arg && wantParam && arg.getKind() === SyntaxKind8.CallExpression) {
+  if (arg && wantParam && arg.getKind() === SyntaxKind9.CallExpression) {
     return {
       summary: `Pass the raw body parameter '${wantParam}' to ${p.call} instead of a parsed value`,
       diff: buildDiff(arg, wantParam)
@@ -939,12 +978,12 @@ Do not call JSON.parse() on the body before this verification step.`
 };
 
 // src/fixers/requiredCallWithOptions.ts
-import { SyntaxKind as SyntaxKind9 } from "ts-morph";
-function callName4(call) {
+import { SyntaxKind as SyntaxKind10 } from "ts-morph";
+function callName5(call) {
   const exp = call.getExpression();
-  if (exp.getKind() === SyntaxKind9.Identifier) return exp.getText();
-  if (exp.getKind() === SyntaxKind9.PropertyAccessExpression) {
-    return exp.asKind(SyntaxKind9.PropertyAccessExpression).getName();
+  if (exp.getKind() === SyntaxKind10.Identifier) return exp.getText();
+  if (exp.getKind() === SyntaxKind10.PropertyAccessExpression) {
+    return exp.asKind(SyntaxKind10.PropertyAccessExpression).getName();
   }
   return "";
 }
@@ -962,15 +1001,15 @@ function placeholderFor(propName) {
 }
 var fixRequiredCallWithOptions = (c, p, outcome) => {
   if (outcome.result !== "fail") return void 0;
-  const calls = c.fn.getDescendantsOfKind(SyntaxKind9.CallExpression);
-  const verify = calls.filter((x) => p.verifyCalls.includes(callName4(x)));
+  const calls = c.fn.getDescendantsOfKind(SyntaxKind10.CallExpression);
+  const verify = calls.filter((x) => p.verifyCalls.includes(callName5(x)));
   if (verify.length > 0) {
     const call = verify[0];
     const args = call.getArguments();
     const lastArg = args[args.length - 1];
-    const obj = lastArg?.asKind(SyntaxKind9.ObjectLiteralExpression);
+    const obj = lastArg?.asKind(SyntaxKind10.ObjectLiteralExpression);
     const presentNames = obj ? obj.getProperties().map((pr) => {
-      const pa = pr.asKind(SyntaxKind9.PropertyAssignment) ?? pr.asKind(SyntaxKind9.ShorthandPropertyAssignment);
+      const pa = pr.asKind(SyntaxKind10.PropertyAssignment) ?? pr.asKind(SyntaxKind10.ShorthandPropertyAssignment);
       return pa?.getName() ?? "";
     }) : [];
     const missingGroups = p.requiredProps.filter(
@@ -978,7 +1017,7 @@ var fixRequiredCallWithOptions = (c, p, outcome) => {
     );
     if (missingGroups.length === 0) return void 0;
     const newProps = missingGroups.map((g) => placeholderFor(g[0])).join(", ");
-    const summary = `Add ${missingGroups.map((g) => g[0]).join(" and ")} to the ${callName4(call)} call`;
+    const summary = `Add ${missingGroups.map((g) => g[0]).join(" and ")} to the ${callName5(call)} call`;
     if (obj) {
       const inner = obj.getText().slice(1, -1).trim();
       const newText = inner.length > 0 ? `{ ${inner}, ${newProps} }` : `{ ${newProps} }`;
@@ -990,7 +1029,7 @@ var fixRequiredCallWithOptions = (c, p, outcome) => {
     }
     return {
       summary,
-      suggestion: `Add an options object ({ ${newProps} }) as an argument to ${callName4(call)}.`
+      suggestion: `Add an options object ({ ${newProps} }) as an argument to ${callName5(call)}.`
     };
   }
   return {
@@ -1486,63 +1525,113 @@ function loadRules(dir) {
   return rules2;
 }
 
+// src/packs.ts
+import { existsSync, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
+import { join as join5 } from "path";
+import { parse as parse2 } from "yaml";
+var PACK_MANIFEST_FILE = "brainblast-pack.yaml";
+function validatePackManifest(m, file) {
+  const errs = [];
+  if (!m || typeof m !== "object") {
+    throw new Error(`invalid pack manifest in ${file}: not a mapping`);
+  }
+  if (!m.id || typeof m.id !== "string") errs.push("missing id");
+  if (!m.name || typeof m.name !== "string") errs.push("missing name");
+  if (!m.version || typeof m.version !== "string") errs.push("missing version");
+  if (!m.author || typeof m.author !== "string") errs.push("missing author");
+  if (errs.length) throw new Error(`invalid pack manifest in ${file}: ${errs.join("; ")}`);
+}
+function loadPack(dir) {
+  const manifestPath = join5(dir, PACK_MANIFEST_FILE);
+  const raw = parse2(readFileSync5(manifestPath, "utf8"));
+  validatePackManifest(raw, manifestPath);
+  const manifest = raw;
+  const rulesDir = join5(dir, "rules");
+  const rules2 = existsSync(rulesDir) ? loadRules(rulesDir).map((r) => ({
+    ...r,
+    pack: { id: manifest.id, version: manifest.version, author: manifest.author }
+  })) : [];
+  return { manifest, rules: rules2 };
+}
+function loadPacksFromDir(packsDir) {
+  if (!existsSync(packsDir)) return [];
+  const out = [];
+  for (const entry of readdirSync4(packsDir).sort()) {
+    const dir = join5(packsDir, entry);
+    if (!statSync3(dir).isDirectory()) continue;
+    if (!existsSync(join5(dir, PACK_MANIFEST_FILE))) continue;
+    out.push(loadPack(dir));
+  }
+  return out;
+}
+
 // rules/index.ts
-import { existsSync } from "fs";
-import { dirname, join as join5 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { dirname, join as join6 } from "path";
 import { fileURLToPath } from "url";
 function bundledRulesDir() {
   const here = dirname(fileURLToPath(import.meta.url));
-  if (existsSync(join5(here, "stripe-webhook-raw-body.yaml"))) return here;
-  const sub = join5(here, "rules");
-  if (existsSync(join5(sub, "stripe-webhook-raw-body.yaml"))) return sub;
+  if (existsSync2(join6(here, "stripe-webhook-raw-body.yaml"))) return here;
+  const sub = join6(here, "rules");
+  if (existsSync2(join6(sub, "stripe-webhook-raw-body.yaml"))) return sub;
   return here;
 }
 var rules = loadRules(bundledRulesDir());
 
 // src/resolveRules.ts
-import { existsSync as existsSync2 } from "fs";
-import { join as join6 } from "path";
-function resolveRules(targetDir) {
+import { existsSync as existsSync3 } from "fs";
+import { join as join7 } from "path";
+function resolveRules(targetDir, extraPackDirs = []) {
   const all = [...rules];
-  const projDir = join6(targetDir, ".agent-research", "rules");
-  if (existsSync2(projDir)) {
-    const seen = new Set(all.map((r) => r.id));
-    for (const r of loadRules(projDir)) {
+  const seen = new Set(all.map((r) => r.id));
+  const addRules = (rules2, sourceLabel) => {
+    for (const r of rules2) {
       if (seen.has(r.id)) {
-        console.warn(`brainblast: project rule '${r.id}' shadows a bundled rule; keeping bundled.`);
+        console.warn(`brainblast: rule '${r.id}' from ${sourceLabel} shadows an existing rule; keeping the first one loaded.`);
         continue;
       }
       all.push(r);
       seen.add(r.id);
     }
+  };
+  const projDir = join7(targetDir, ".agent-research", "rules");
+  if (existsSync3(projDir)) {
+    addRules(loadRules(projDir), "project rules");
+  }
+  for (const { manifest, rules: rules2 } of loadPacksFromDir(join7(targetDir, ".agent-research", "packs"))) {
+    addRules(rules2, `pack '${manifest.id}'`);
+  }
+  for (const dir of extraPackDirs) {
+    const { manifest, rules: rules2 } = loadPack(dir);
+    addRules(rules2, `pack '${manifest.id}' (${dir})`);
   }
   return all;
 }
 
 // src/trustGraph/directory.ts
-import { readFileSync as readFileSync5, existsSync as existsSync3 } from "fs";
+import { readFileSync as readFileSync6, existsSync as existsSync4 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join7 } from "path";
-import { parse as parse2 } from "yaml";
+import { join as join8 } from "path";
+import { parse as parse3 } from "yaml";
 var cache = null;
 function bundledPath() {
   const here = fileURLToPath2(new URL(".", import.meta.url));
   const candidates = [
-    join7(here, "programs", "directory.yaml"),
+    join8(here, "programs", "directory.yaml"),
     // dist/programs/directory.yaml
-    join7(here, "..", "..", "programs", "directory.yaml"),
+    join8(here, "..", "..", "programs", "directory.yaml"),
     // src/../../programs/
-    join7(here, "..", "programs", "directory.yaml")
+    join8(here, "..", "programs", "directory.yaml")
     // fallback
   ];
   for (const c of candidates) {
-    if (existsSync3(c)) return c;
+    if (existsSync4(c)) return c;
   }
   return candidates[0];
 }
 function loadDirectory(path = bundledPath()) {
   if (cache && path === bundledPath()) return cache;
-  const raw = parse2(readFileSync5(path, "utf8"));
+  const raw = parse3(readFileSync6(path, "utf8"));
   if (!raw || !Array.isArray(raw.programs)) {
     throw new Error(`invalid program directory at ${path}: missing 'programs' array`);
   }
@@ -1613,23 +1702,23 @@ function isValidSolanaAddress(s) {
 }
 
 // src/trustGraph/programCache.ts
-import { readFileSync as readFileSync6, writeFileSync, mkdirSync, existsSync as existsSync4 } from "fs";
-import { join as join8, dirname as dirname2 } from "path";
+import { readFileSync as readFileSync7, writeFileSync, mkdirSync, existsSync as existsSync5 } from "fs";
+import { join as join9, dirname as dirname2 } from "path";
 import { homedir } from "os";
 var DEFAULT_TTL_HOURS = 168;
 var SCHEMA_VERSION = "1.0";
 function defaultCachePath() {
   const envOverride = process.env["BRAINBLAST_CACHE_PATH"];
-  return envOverride ?? join8(homedir(), ".brainblast", "program-cache.json");
+  return envOverride ?? join9(homedir(), ".brainblast", "program-cache.json");
 }
 function emptyCache() {
   return { schemaVersion: SCHEMA_VERSION, entries: {} };
 }
 function loadProgramCache(cachePath) {
   const path = cachePath ?? defaultCachePath();
-  if (!existsSync4(path)) return emptyCache();
+  if (!existsSync5(path)) return emptyCache();
   try {
-    const raw = JSON.parse(readFileSync6(path, "utf8"));
+    const raw = JSON.parse(readFileSync7(path, "utf8"));
     if (raw?.schemaVersion !== SCHEMA_VERSION) {
       return emptyCache();
     }
@@ -1906,7 +1995,7 @@ function renderTrustGraphMd(g) {
 }
 
 // src/costAnalysis.ts
-import { Project as Project2, SyntaxKind as SyntaxKind10 } from "ts-morph";
+import { Project as Project2, SyntaxKind as SyntaxKind11 } from "ts-morph";
 var LAMPORTS_PER_BYTE_YEAR = 3480;
 var EXEMPTION_THRESHOLD = 2;
 var OVERHEAD_BYTES = 128;
@@ -1987,11 +2076,11 @@ var KNOWN_FLOWS = [
   }
 ];
 var LOOP_NODE_KINDS = /* @__PURE__ */ new Set([
-  SyntaxKind10.ForStatement,
-  SyntaxKind10.ForOfStatement,
-  SyntaxKind10.ForInStatement,
-  SyntaxKind10.WhileStatement,
-  SyntaxKind10.DoStatement
+  SyntaxKind11.ForStatement,
+  SyntaxKind11.ForOfStatement,
+  SyntaxKind11.ForInStatement,
+  SyntaxKind11.WhileStatement,
+  SyntaxKind11.DoStatement
 ]);
 var ARRAY_METHOD_LOOPS = /* @__PURE__ */ new Set(["map", "forEach", "flatMap", "reduce", "filter"]);
 function isInsideLoop(node) {
@@ -1999,12 +2088,12 @@ function isInsideLoop(node) {
   while (cur) {
     const k = cur.getKind?.();
     if (k !== void 0 && LOOP_NODE_KINDS.has(k)) {
-      return { scalable: true, note: `call is inside a ${SyntaxKind10[k]} \u2014 cost scales with loop iterations` };
+      return { scalable: true, note: `call is inside a ${SyntaxKind11[k]} \u2014 cost scales with loop iterations` };
     }
-    if (k === SyntaxKind10.CallExpression) {
+    if (k === SyntaxKind11.CallExpression) {
       const expr = cur.getExpression?.();
-      if (expr?.getKind?.() === SyntaxKind10.PropertyAccessExpression) {
-        const name = expr.asKind?.(SyntaxKind10.PropertyAccessExpression)?.getName?.();
+      if (expr?.getKind?.() === SyntaxKind11.PropertyAccessExpression) {
+        const name = expr.asKind?.(SyntaxKind11.PropertyAccessExpression)?.getName?.();
         if (name && ARRAY_METHOD_LOOPS.has(name)) {
           return { scalable: true, note: `call is inside .${name}() \u2014 cost scales with array length` };
         }
@@ -2018,7 +2107,7 @@ function detectPriorityFee(targetDir) {
   const project = new Project2({ skipAddingFilesFromTsConfig: true });
   for (const file of walk(targetDir)) {
     const sf = project.addSourceFileAtPath(file);
-    const calls = sf.getDescendantsOfKind(SyntaxKind10.CallExpression);
+    const calls = sf.getDescendantsOfKind(SyntaxKind11.CallExpression);
     for (const ce of calls) {
       const expr = ce.getExpression();
       const text = expr.getText();
@@ -2046,22 +2135,22 @@ function detectAccountFlows(targetDir) {
     const importedModules = new Set(
       sf.getImportDeclarations().map((d) => d.getModuleSpecifierValue())
     );
-    for (const ce of sf.getDescendantsOfKind(SyntaxKind10.CallExpression)) {
+    for (const ce of sf.getDescendantsOfKind(SyntaxKind11.CallExpression)) {
       const expr = ce.getExpression();
-      let callName5 = null;
-      if (expr.getKind() === SyntaxKind10.Identifier) {
-        callName5 = expr.getText();
-      } else if (expr.getKind() === SyntaxKind10.PropertyAccessExpression) {
-        callName5 = expr.asKind(SyntaxKind10.PropertyAccessExpression).getName();
+      let callName6 = null;
+      if (expr.getKind() === SyntaxKind11.Identifier) {
+        callName6 = expr.getText();
+      } else if (expr.getKind() === SyntaxKind11.PropertyAccessExpression) {
+        callName6 = expr.asKind(SyntaxKind11.PropertyAccessExpression).getName();
       }
-      if (!callName5) continue;
-      const known = callIndex.get(callName5);
+      if (!callName6) continue;
+      const known = callIndex.get(callName6);
       if (!known) continue;
       if (!importedModules.has(known.module)) continue;
       const lamports = rentExemptMinimum(known.dataLen);
       const { scalable, note } = isInsideLoop(ce);
       flows.push({
-        call: callName5,
+        call: callName6,
         module: known.module,
         accountType: known.accountType,
         file,
@@ -2206,7 +2295,7 @@ function startWatch(targetDir, opts = {}) {
 }
 
 // src/fixers/applyDiff.ts
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync2 } from "fs";
 function parseDiff(diff) {
   const lines = diff.split("\n");
   const fileLine = lines.find((l) => l.startsWith("+++ b"));
@@ -2223,7 +2312,7 @@ function parseDiff(diff) {
 }
 function applyDiffToFile(diff) {
   const { filePath, oldStart, oldCount, newLines } = parseDiff(diff);
-  const content = readFileSync7(filePath, "utf8");
+  const content = readFileSync8(filePath, "utf8");
   const fileLines = content.split("\n");
   const removedLines = diff.split("\n").filter((l) => l.startsWith("-") && !l.startsWith("---")).map((l) => l.slice(1));
   const actual = fileLines.slice(oldStart - 1, oldStart - 1 + oldCount);
@@ -2233,6 +2322,156 @@ function applyDiffToFile(diff) {
   return true;
 }
 
+// src/pack.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { join as join10 } from "path";
+function initPack(dir, opts) {
+  if (existsSync6(join10(dir, PACK_MANIFEST_FILE))) {
+    throw new Error(`${dir} already contains a ${PACK_MANIFEST_FILE}`);
+  }
+  const manifest = {
+    id: opts.id,
+    name: opts.name ?? opts.id,
+    version: opts.version ?? "0.1.0",
+    author: opts.author ?? "unknown",
+    ...opts.description ? { description: opts.description } : {}
+  };
+  mkdirSync2(dir, { recursive: true });
+  mkdirSync2(join10(dir, "rules"), { recursive: true });
+  mkdirSync2(join10(dir, "fixtures"), { recursive: true });
+  const manifestYaml = [
+    `id: ${manifest.id}`,
+    `name: ${manifest.name}`,
+    `version: ${manifest.version}`,
+    `author: ${manifest.author}`,
+    ...manifest.description ? [`description: ${manifest.description}`] : [],
+    ""
+  ].join("\n");
+  const manifestFile = join10(dir, PACK_MANIFEST_FILE);
+  writeFileSync3(manifestFile, manifestYaml, "utf8");
+  return manifestFile;
+}
+function validatePack(dir) {
+  const { manifest, rules: rules2 } = loadPack(dir);
+  const fixturesRoot = join10(dir, "fixtures");
+  const ruleResults = rules2.map((rule) => {
+    const ruleFixturesDir = join10(fixturesRoot, rule.id);
+    const vulnerableDir = join10(ruleFixturesDir, "vulnerable");
+    const fixedDir = join10(ruleFixturesDir, "fixed");
+    if (!existsSync6(vulnerableDir) || !existsSync6(fixedDir)) {
+      return {
+        ruleId: rule.id,
+        status: "missing-fixtures",
+        detail: `no fixtures/${rule.id}/{vulnerable,fixed}/ directory \u2014 prove gate skipped`
+      };
+    }
+    const redChecks = auditWithRule(vulnerableDir, rule);
+    const redFails = redChecks.filter((c) => c.result === "fail");
+    if (redFails.length === 0) {
+      return {
+        ruleId: rule.id,
+        status: "red-failed",
+        detail: `expected at least one FAIL against fixtures/${rule.id}/vulnerable/, got none`
+      };
+    }
+    const greenChecks = auditWithRule(fixedDir, rule);
+    const greenFails = greenChecks.filter((c) => c.result === "fail");
+    if (greenFails.length > 0) {
+      return {
+        ruleId: rule.id,
+        status: "green-failed",
+        detail: `expected no FAIL against fixtures/${rule.id}/fixed/, got ${greenFails.length}`
+      };
+    }
+    return { ruleId: rule.id, status: "ok", detail: "RED -> GREEN proven" };
+  });
+  const ok = ruleResults.every((r) => r.status === "ok" || r.status === "missing-fixtures");
+  return { manifest, rules: rules2, ruleResults, ok };
+}
+
+// src/telemetry.ts
+import { createHash, randomUUID } from "crypto";
+import { appendFileSync, existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
+import { execFileSync as execFileSync3 } from "child_process";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname3, join as join11, resolve } from "path";
+function sha256Hex(s) {
+  return createHash("sha256").update(s).digest("hex");
+}
+function isTelemetryEnabled(targetDir) {
+  const env = process.env.BRAINBLAST_TELEMETRY;
+  if (env === "1" || env === "true") return true;
+  if (env === "0" || env === "false") return false;
+  const configPath = join11(targetDir, ".agent-research", "config.json");
+  if (!existsSync7(configPath)) return false;
+  try {
+    const cfg = JSON.parse(readFileSync9(configPath, "utf8"));
+    return cfg?.telemetry === true;
+  } catch {
+    return false;
+  }
+}
+function getUserHash() {
+  const idPath = join11(homedir2(), ".brainblast", "telemetry-id");
+  let id;
+  if (existsSync7(idPath)) {
+    id = readFileSync9(idPath, "utf8").trim();
+  } else {
+    id = randomUUID();
+    mkdirSync3(dirname3(idPath), { recursive: true });
+    writeFileSync4(idPath, id, "utf8");
+  }
+  return sha256Hex(id).slice(0, 16);
+}
+function getRepoHash(targetDir) {
+  let key = "";
+  try {
+    key = execFileSync3("git", ["config", "--get", "remote.origin.url"], {
+      cwd: targetDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+  }
+  if (!key) key = resolve(targetDir);
+  return sha256Hex(key).slice(0, 16);
+}
+function telemetryFilePath(targetDir) {
+  return join11(targetDir, ".agent-research", "telemetry.ndjson");
+}
+var DEFAULT_REGISTRY_URL = "https://registry.brainblast.tech";
+async function submitTelemetry(targetDir, registryUrl = process.env.BRAINBLAST_REGISTRY_URL || DEFAULT_REGISTRY_URL) {
+  const file = telemetryFilePath(targetDir);
+  if (!existsSync7(file)) {
+    return { submitted: 0, accepted: 0, rejected: 0, graduations: [] };
+  }
+  const events = readFileSync9(file, "utf8").trim().split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  if (events.length === 0) {
+    return { submitted: 0, accepted: 0, rejected: 0, graduations: [] };
+  }
+  const res = await fetch(`${registryUrl.replace(/\/$/, "")}/api/telemetry`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ events })
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`telemetry submit failed: ${res.status} ${res.statusText} ${body}`.trim());
+  }
+  const json = await res.json();
+  return { submitted: events.length, ...json };
+}
+function recordGraduationEvents(targetDir, events) {
+  if (events.length === 0) return;
+  const file = telemetryFilePath(targetDir);
+  mkdirSync3(dirname3(file), { recursive: true });
+  const repo_hash = getRepoHash(targetDir);
+  const user_hash = getUserHash();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const lines = events.map((e) => JSON.stringify({ ...e, repo_hash, user_hash, timestamp })).join("\n");
+  appendFileSync(file, lines + "\n", "utf8");
+}
+
 export {
   findCandidates,
   findConfigCandidates,
@@ -2247,6 +2486,10 @@ export {
   renderTest,
   testKinds,
   loadRules,
+  PACK_MANIFEST_FILE,
+  validatePackManifest,
+  loadPack,
+  loadPacksFromDir,
   rules,
   resolveRules,
   loadDirectory,
@@ -2271,5 +2514,14 @@ export {
   runIncrementalScan,
   startWatch,
   parseDiff,
-  applyDiffToFile
+  applyDiffToFile,
+  initPack,
+  validatePack,
+  isTelemetryEnabled,
+  getUserHash,
+  getRepoHash,
+  telemetryFilePath,
+  DEFAULT_REGISTRY_URL,
+  submitTelemetry,
+  recordGraduationEvents
 };

package/dist/cli.js

@@ -7,14 +7,20 @@ import {
   cacheSize,
   defaultCachePath,
   getChangedRanges,
+  initPack,
+  isTelemetryEnabled,
   isValidSolanaAddress,
   loadProgramCache,
   parseDiff,
+  recordGraduationEvents,
   renderCostReportMd,
   renderTrustGraphMd,
   resolveRules,
-  startWatch
-} from "./chunk-XQUQOBXZ.js";
+  startWatch,
+  submitTelemetry,
+  telemetryFilePath,
+  validatePack
+} from "./chunk-LOPYKIXE.js";
 
 // src/cli.ts
 import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
@@ -94,10 +100,25 @@ function updateMemory(memory, checks2, now = /* @__PURE__ */ new Date()) {
 // src/cli.ts
 import { execFileSync } from "child_process";
 var args = process.argv.slice(2);
+function parsePackDirs(argv) {
+  const idx = argv.indexOf("--packs");
+  if (idx < 0) return [];
+  const value = argv[idx + 1];
+  if (!value || value.startsWith("--")) return [];
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
 if (args[0] === "trust-graph") {
   await runTrustGraph(args.slice(1));
   process.exit(0);
 }
+if (args[0] === "pack") {
+  runPack(args.slice(1));
+  process.exit(0);
+}
+if (args[0] === "telemetry") {
+  await runTelemetry(args.slice(1));
+  process.exit(0);
+}
 if (args[0] === "watch") {
   const watchDir = args.find((a, i) => i > 0 && !a.startsWith("--")) ?? process.cwd();
   startWatch(watchDir);
@@ -119,7 +140,7 @@ if (sinceIdx >= 0 && !since) {
   console.error("error: --since requires a <ref> argument, e.g. --since origin/main");
   process.exit(2);
 }
-var rules = resolveRules(targetDir);
+var rules = resolveRules(targetDir, parsePackDirs(args));
 var changedRanges;
 if (since) {
   try {
@@ -211,6 +232,75 @@ if (ci) {
   const gateFail = fails > 0 || strict && cantTell > 0;
   process.exit(gateFail ? 1 : 0);
 }
+function runPack(argv) {
+  const sub = argv[0];
+  if (sub === "init") {
+    const dir = argv.find((a, i) => i > 0 && !a.startsWith("--") && argv[i - 1] !== "--id" && argv[i - 1] !== "--name" && argv[i - 1] !== "--author" && argv[i - 1] !== "--version" && argv[i - 1] !== "--description");
+    const flag = (name) => {
+      const idx = argv.indexOf(`--${name}`);
+      return idx >= 0 ? argv[idx + 1] : void 0;
+    };
+    const id = flag("id");
+    if (!dir || !id) {
+      console.error("usage: brainblast pack init <dir> --id <pack-id> [--name <name>] [--author <author>] [--version <semver>] [--description <text>]");
+      process.exit(2);
+    }
+    const manifestFile = initPack(dir, {
+      id,
+      name: flag("name"),
+      author: flag("author"),
+      version: flag("version"),
+      description: flag("description")
+    });
+    console.log(`brainblast pack init: wrote ${manifestFile}`);
+    console.log(`  rules:    ${join2(dir, "rules")}/`);
+    console.log(`  fixtures: ${join2(dir, "fixtures")}/`);
+    return;
+  }
+  if (sub === "validate") {
+    const dir = argv.find((a, i) => i > 0 && !a.startsWith("--"));
+    if (!dir) {
+      console.error("usage: brainblast pack validate <dir>");
+      process.exit(2);
+    }
+    const result = validatePack(dir);
+    console.log(`pack: ${result.manifest.id} v${result.manifest.version} (${result.manifest.author})`);
+    console.log(`  ${result.rules.length} rule(s)`);
+    for (const r of result.ruleResults) {
+      const marker = r.status === "ok" ? "OK" : r.status === "missing-fixtures" ? "WARN" : "FAIL";
+      console.log(`  [${marker}] ${r.ruleId}: ${r.detail}`);
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+  console.error("usage: brainblast pack <init|validate> ...");
+  process.exit(2);
+}
+async function runTelemetry(argv) {
+  const sub = argv[0];
+  if (sub !== "submit") {
+    console.error("usage: brainblast telemetry submit [targetDir]");
+    process.exit(2);
+  }
+  const targetDir2 = argv.find((a, i) => i > 0 && !a.startsWith("--")) ?? process.cwd();
+  try {
+    const result = await submitTelemetry(targetDir2);
+    if (result.submitted === 0) {
+      console.log(`brainblast telemetry submit: no events to submit (${telemetryFilePath(targetDir2)} is empty or missing)`);
+      return;
+    }
+    console.log(`brainblast telemetry submit: sent ${result.submitted} event(s) \u2014 ${result.accepted} accepted, ${result.rejected} rate-limited`);
+    for (const g of result.graduations) {
+      if (g.graduated) {
+        console.log(`  [GRADUATED] ${g.pack_id}/${g.rule_id}  (${g.distinct_pairs} distinct repo/user pairs)`);
+      } else {
+        console.log(`  [PROGRESS]  ${g.pack_id}/${g.rule_id}  ${g.distinct_pairs}/5 distinct repo/user pairs`);
+      }
+    }
+  } catch (e) {
+    console.error(`brainblast telemetry submit: ${e.message ?? String(e)}`);
+    process.exit(1);
+  }
+}
 async function runTrustGraph(argv) {
   const rpcIdx = argv.indexOf("--rpc");
   const rpcUrl = rpcIdx >= 0 ? argv[rpcIdx + 1] : void 0;
@@ -248,7 +338,7 @@ async function runFix(argv) {
   const apply = argv.includes("--apply");
   const branch = argv.includes("--branch");
   const targetDir2 = argv.find((a) => !a.startsWith("--")) ?? process.cwd();
-  const rules2 = resolveRules(targetDir2);
+  const rules2 = resolveRules(targetDir2, parsePackDirs(argv));
   const { checks: before } = audit(targetDir2, rules2);
   const fixable = before.filter((c) => c.result === "fail" && c.fix?.diff);
   if (fixable.length === 0) {
@@ -300,6 +390,15 @@ Warning: ${stillFailing.length} fix(es) applied but the rule still fails:`);
   } else if (applied > 0) {
     console.log("All applied fixes now pass (or cant_tell) on re-audit. \u2713");
   }
+  if (isTelemetryEnabled(targetDir2)) {
+    const graduated = fixable.filter((c) => !stillFailing.includes(c));
+    const events = graduated.map((c) => rules2.find((r) => r.id === c.ruleId)).filter((r) => !!r?.pack).map((r) => ({ pack_id: r.pack.id, rule_id: r.id }));
+    if (events.length > 0) {
+      recordGraduationEvents(targetDir2, events);
+      console.log(`
+Telemetry: recorded ${events.length} graduation event(s) to ${telemetryFilePath(targetDir2)}`);
+    }
+  }
   if (branch && applied > 0) {
     const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     const branchName = `brainblast/auto-fix-${ts}`;

package/dist/index.d.ts

@@ -156,6 +156,23 @@ interface Rule {
         kind: string;
         params?: Record<string, any>;
     };
+    /**
+     * Provenance for rules loaded from a third-party rule pack (see
+     * src/packs.ts). Absent for bundled rules. Stamped by the pack loader from
+     * the pack's brainblast-pack.yaml manifest, not set by the rule author.
+     */
+    pack?: {
+        id: string;
+        version: string;
+        author?: string;
+    };
+}
+interface PackManifest {
+    id: string;
+    name: string;
+    version: string;
+    author: string;
+    description?: string;
 }
 type Checker = (candidate: Candidate, params: any) => CheckOutcome;
 type RustChecker = (candidate: RustCandidate, params: any) => CheckOutcome;
@@ -224,7 +241,7 @@ declare function audit(targetDir: string, rules: Rule[], changedRanges?: Changed
     };
 };
 
-declare function resolveRules(targetDir: string): Rule[];
+declare function resolveRules(targetDir: string, extraPackDirs?: string[]): Rule[];
 
 declare function loadRules(dir: string): Rule[];
 
@@ -285,6 +302,70 @@ interface ParsedDiff {
 declare function parseDiff(diff: string): ParsedDiff;
 declare function applyDiffToFile(diff: string): boolean;
 
+declare const PACK_MANIFEST_FILE = "brainblast-pack.yaml";
+declare function validatePackManifest(m: any, file: string): void;
+declare function loadPack(dir: string): {
+    manifest: PackManifest;
+    rules: Rule[];
+};
+declare function loadPacksFromDir(packsDir: string): {
+    manifest: PackManifest;
+    rules: Rule[];
+}[];
+
+interface PackInitOptions {
+    id: string;
+    name?: string;
+    author?: string;
+    version?: string;
+    description?: string;
+}
+declare function initPack(dir: string, opts: PackInitOptions): string;
+interface PackValidateResult {
+    manifest: PackManifest;
+    rules: Rule[];
+    /** Per-rule prove-gate results. */
+    ruleResults: PackRuleValidation[];
+    /** True if the manifest is valid, every rule loaded cleanly, and every rule with fixtures passed RED->GREEN. */
+    ok: boolean;
+}
+interface PackRuleValidation {
+    ruleId: string;
+    /** "ok" | "missing-fixtures" | "red-failed" | "green-failed" */
+    status: "ok" | "missing-fixtures" | "red-failed" | "green-failed";
+    detail: string;
+}
+declare function validatePack(dir: string): PackValidateResult;
+
+interface GraduationEvent {
+    pack_id: string;
+    rule_id: string;
+    repo_hash: string;
+    user_hash: string;
+    timestamp: string;
+}
+declare function isTelemetryEnabled(targetDir: string): boolean;
+declare function getUserHash(): string;
+declare function getRepoHash(targetDir: string): string;
+declare function telemetryFilePath(targetDir: string): string;
+declare const DEFAULT_REGISTRY_URL = "https://registry.brainblast.tech";
+interface TelemetrySubmitResult {
+    submitted: number;
+    accepted: number;
+    rejected: number;
+    graduations: {
+        pack_id: string;
+        rule_id: string;
+        distinct_pairs: number;
+        graduated: boolean;
+    }[];
+}
+declare function submitTelemetry(targetDir: string, registryUrl?: string): Promise<TelemetrySubmitResult>;
+declare function recordGraduationEvents(targetDir: string, events: {
+    pack_id: string;
+    rule_id: string;
+}[]): void;
+
 type UpgradeAuthorityKind = "renounced" | "single-key" | "multisig" | "dao" | "unknown";
 type UpgradeAuthoritySource = "directory" | "rpc" | "research";
 interface UpgradeAuthority {
@@ -414,4 +495,4 @@ declare function isEntryExpired(entry: ProgramCacheEntry, ttlHoursOverride?: num
  */
 declare function cacheSize(cache: ProgramCache, ttlHoursOverride?: number): number;
 
-export { type AccountFlow, type AuditRef, type BuildOpts, type Candidate, type ChangedRanges, type CheckOutcome, type CheckResult, type CheckResultKind, type Checker, type ConfigCandidate, type ConfigChecker, type CostReport, DEFAULT_TTL_HOURS, type OnChainProgram, type ParityNote, type ParsedDiff, type PriorityFeePosture, type ProgramCache, type ProgramCacheEntry, type Recoverability, type Rule, type RustAccountField, type RustCandidate, type RustChecker, type Severity, type TrustGraph, type UpgradeAuthority, type UpgradeAuthorityKind, type UpgradeAuthoritySource, type VerifiedBuildState, type WatchEvent, type WatchOptions, analyzeCosts, applyDiffToFile, audit, auditWithRule, base58Decode, base58Encode, buildTrustGraph, rules as bundledRules, cacheSize, checkerKinds, defaultCachePath, fileChanged, findCandidates, findConfigCandidates, generateTestForResult, getCacheEntry, getCacheEntryMeta, getChangedRanges, getWorkingTreeChanges, isEntryExpired, isValidSolanaAddress, lamportsToSol, loadDirectory, loadProgramCache, loadRules, parseDiff, putCacheEntry, rangeChanged, renderCostReportMd, renderTest, renderTrustGraphMd, rentExemptMinimum, resolveRules, runChecker, runIncrementalScan, saveProgramCache, startWatch, testKinds };
+export { type AccountFlow, type AuditRef, type BuildOpts, type Candidate, type ChangedRanges, type CheckOutcome, type CheckResult, type CheckResultKind, type Checker, type ConfigCandidate, type ConfigChecker, type CostReport, DEFAULT_REGISTRY_URL, DEFAULT_TTL_HOURS, type GraduationEvent, type OnChainProgram, PACK_MANIFEST_FILE, type PackInitOptions, type PackManifest, type PackRuleValidation, type PackValidateResult, type ParityNote, type ParsedDiff, type PriorityFeePosture, type ProgramCache, type ProgramCacheEntry, type Recoverability, type Rule, type RustAccountField, type RustCandidate, type RustChecker, type Severity, type TelemetrySubmitResult, type TrustGraph, type UpgradeAuthority, type UpgradeAuthorityKind, type UpgradeAuthoritySource, type VerifiedBuildState, type WatchEvent, type WatchOptions, analyzeCosts, applyDiffToFile, audit, auditWithRule, base58Decode, base58Encode, buildTrustGraph, rules as bundledRules, cacheSize, checkerKinds, defaultCachePath, fileChanged, findCandidates, findConfigCandidates, generateTestForResult, getCacheEntry, getCacheEntryMeta, getChangedRanges, getRepoHash, getUserHash, getWorkingTreeChanges, initPack, isEntryExpired, isTelemetryEnabled, isValidSolanaAddress, lamportsToSol, loadDirectory, loadPack, loadPacksFromDir, loadProgramCache, loadRules, parseDiff, putCacheEntry, rangeChanged, recordGraduationEvents, renderCostReportMd, renderTest, renderTrustGraphMd, rentExemptMinimum, resolveRules, runChecker, runIncrementalScan, saveProgramCache, startWatch, submitTelemetry, telemetryFilePath, testKinds, validatePack, validatePackManifest };

package/dist/index.js

@@ -1,5 +1,7 @@
 import {
+  DEFAULT_REGISTRY_URL,
   DEFAULT_TTL_HOURS,
+  PACK_MANIFEST_FILE,
   analyzeCosts,
   applyDiffToFile,
   audit,
@@ -16,16 +18,23 @@ import {
   getCacheEntry,
   getCacheEntryMeta,
   getChangedRanges,
+  getRepoHash,
+  getUserHash,
   getWorkingTreeChanges,
+  initPack,
   isEntryExpired,
+  isTelemetryEnabled,
   isValidSolanaAddress,
   lamportsToSol,
   loadDirectory,
+  loadPack,
+  loadPacksFromDir,
   loadProgramCache,
   loadRules,
   parseDiff,
   putCacheEntry,
   rangeChanged,
+  recordGraduationEvents,
   renderCostReportMd,
   renderTest,
   renderTrustGraphMd,
@@ -36,8 +45,12 @@ import {
   runIncrementalScan,
   saveProgramCache,
   startWatch,
-  testKinds
-} from "./chunk-XQUQOBXZ.js";
+  submitTelemetry,
+  telemetryFilePath,
+  testKinds,
+  validatePack,
+  validatePackManifest
+} from "./chunk-LOPYKIXE.js";
 
 // src/generate.ts
 import { writeFileSync, mkdirSync } from "fs";
@@ -53,7 +66,9 @@ function generateTestForResult(result, rule, outPath) {
   return outPath;
 }
 export {
+  DEFAULT_REGISTRY_URL,
   DEFAULT_TTL_HOURS,
+  PACK_MANIFEST_FILE,
   analyzeCosts,
   applyDiffToFile,
   audit,
@@ -72,16 +87,23 @@ export {
   getCacheEntry,
   getCacheEntryMeta,
   getChangedRanges,
+  getRepoHash,
+  getUserHash,
   getWorkingTreeChanges,
+  initPack,
   isEntryExpired,
+  isTelemetryEnabled,
   isValidSolanaAddress,
   lamportsToSol,
   loadDirectory,
+  loadPack,
+  loadPacksFromDir,
   loadProgramCache,
   loadRules,
   parseDiff,
   putCacheEntry,
   rangeChanged,
+  recordGraduationEvents,
   renderCostReportMd,
   renderTest,
   renderTrustGraphMd,
@@ -91,5 +113,9 @@ export {
   runIncrementalScan,
   saveProgramCache,
   startWatch,
-  testKinds
+  submitTelemetry,
+  telemetryFilePath,
+  testKinds,
+  validatePack,
+  validatePackManifest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainblast",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "type": "module",
   "description": "Deterministic auditor for catastrophic AI-integration bugs: scan a repo, find the silent money/auth traps, and generate the behavioral test that proves they're fixed.",
   "keywords": [