avorelo 0.1.0

package/scripts/lib/attribution.js

@@ -0,0 +1,180 @@
+"use strict";
+
+function numberOrNull(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function preferred(value, fallback = null) {
+  if (value === undefined || value === null || value === "") return fallback;
+  return value;
+}
+
+function inferExecutionPath(input = {}) {
+  const existing = objectOrNull(input.attribution) || {};
+  const explicit = preferred(input.executionPath ?? existing.executionPath ?? input.meta?.executionPath, null);
+  if (explicit) return String(explicit);
+
+  const tool = String(input.tool || "");
+  const event = String(input.event || "");
+  const meta = input.meta || {};
+  const hasModelEvidence =
+    preferred(input.provider ?? existing.provider ?? meta.provider, null)
+    || preferred(input.model ?? existing.model ?? meta.model, null)
+    || numberOrNull(input.tokenUsage ?? existing.tokenUsage ?? meta.totalTokens ?? meta.tokenUsage) !== null
+    || numberOrNull(input.cost ?? existing.cost ?? meta.totalCost ?? meta.cost) !== null;
+  if (tool === "ccusage" || event === "CcusageSync" || event === "CloudSync") return "deterministic";
+  if (tool === "Bash" || tool === "Read" || tool === "Grep" || tool === "Glob" || tool === "Write" || tool === "Edit") return "deterministic";
+  if (event === "BatchJob") return "llm";
+  if (tool === "Agent" || hasModelEvidence) return "llm";
+  return null;
+}
+
+function objectOrNull(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+function pickFromCandidates(candidates, keys, transform = (value) => value) {
+  for (const candidate of candidates) {
+    const obj = objectOrNull(candidate);
+    if (!obj) continue;
+    for (const key of keys) {
+      if (!(key in obj)) continue;
+      const transformed = transform(obj[key]);
+      if (transformed !== null && transformed !== undefined && transformed !== "") return transformed;
+    }
+  }
+  return null;
+}
+
+function sumTokenParts(candidates) {
+  let sawAny = false;
+  let total = 0;
+  for (const candidate of candidates) {
+    const obj = objectOrNull(candidate);
+    if (!obj) continue;
+    const inputTokens = numberOrNull(obj.inputTokens ?? obj.input_tokens ?? obj.promptTokens ?? obj.prompt_tokens);
+    const outputTokens = numberOrNull(obj.outputTokens ?? obj.output_tokens ?? obj.completionTokens ?? obj.completion_tokens);
+    if (inputTokens !== null) {
+      sawAny = true;
+      total += inputTokens;
+    }
+    if (outputTokens !== null) {
+      sawAny = true;
+      total += outputTokens;
+    }
+  }
+  return sawAny ? total : null;
+}
+
+function extractRuntimeEvidence(params = {}) {
+  const toolInput = objectOrNull(params.toolInput) || {};
+  const toolResponse = objectOrNull(params.toolResponse) || {};
+  const candidates = [
+    params,
+    toolInput,
+    toolInput.metadata,
+    toolInput.usage,
+    toolResponse,
+    toolResponse.metadata,
+    toolResponse.metrics,
+    toolResponse.usage,
+    toolResponse.result,
+    objectOrNull(toolResponse.result)?.metadata,
+    objectOrNull(toolResponse.result)?.metrics,
+    objectOrNull(toolResponse.result)?.usage,
+    toolResponse.response,
+    objectOrNull(toolResponse.response)?.metadata,
+    objectOrNull(toolResponse.response)?.metrics,
+    objectOrNull(toolResponse.response)?.usage,
+    toolResponse.data,
+    objectOrNull(toolResponse.data)?.metadata,
+    objectOrNull(toolResponse.data)?.metrics,
+    objectOrNull(toolResponse.data)?.usage,
+  ].filter(Boolean);
+
+  const provider = pickFromCandidates(candidates, ["provider", "providerName", "provider_name"], (value) => preferred(value, null));
+  const model = pickFromCandidates(candidates, ["model", "modelName", "model_name"], (value) => preferred(value, null));
+  const tokenUsage =
+    pickFromCandidates(
+      candidates,
+      ["tokenUsage", "token_usage", "totalTokens", "total_tokens", "tokens"],
+      (value) => numberOrNull(value)
+    ) ?? sumTokenParts(candidates);
+  const cost = pickFromCandidates(
+    candidates,
+    ["cost", "totalCost", "total_cost", "measuredCost", "measured_cost"],
+    (value) => numberOrNull(value)
+  );
+  const latencyMs = pickFromCandidates(
+    candidates,
+    ["latencyMs", "latency_ms", "durationMs", "duration_ms", "elapsedMs", "elapsed_ms"],
+    (value) => numberOrNull(value)
+  );
+
+  if ([provider, model, tokenUsage, cost, latencyMs].every((value) => value === null)) return null;
+
+  return {
+    provider: provider ? String(provider) : null,
+    model: model ? String(model) : null,
+    tokenUsage,
+    cost,
+    costSource: cost !== null && cost > 0 ? "measured" : "unavailable",
+    latencyMs,
+  };
+}
+
+function normalizeAttribution(input = {}) {
+  const existing = objectOrNull(input.attribution) || {};
+  const meta = input.meta || {};
+  const provider = preferred(input.provider ?? existing.provider ?? meta.provider, null);
+  const model = preferred(input.model ?? existing.model ?? meta.model, null);
+  const tokenUsage = numberOrNull(input.tokenUsage ?? existing.tokenUsage ?? meta.totalTokens ?? meta.tokenUsage);
+  const cost = numberOrNull(input.cost ?? existing.cost ?? meta.totalCost ?? meta.cost);
+  const latencyMs = numberOrNull(input.latencyMs ?? existing.latencyMs ?? meta.latencyMs);
+
+  const attribution = {
+    sessionId: preferred(input.sessionId ?? existing.sessionId, "unknown"),
+    featureId: preferred(input.featureId ?? existing.featureId ?? meta.featureId, null),
+    componentId: preferred(input.componentId ?? existing.componentId ?? meta.componentId ?? input.event, null),
+    workerId: preferred(input.workerId ?? existing.workerId ?? meta.workerId, null),
+    routeId: preferred(input.routeId ?? existing.routeId ?? meta.routeId, null),
+    stepId: preferred(input.stepId ?? existing.stepId ?? meta.stepId, null),
+    actionType: preferred(input.actionType ?? existing.actionType ?? meta.actionType ?? input.action, null),
+    executionPath: inferExecutionPath(input),
+    provider: provider ? String(provider) : null,
+    model: model ? String(model) : null,
+    tokenUsage,
+    cost,
+    costSource: cost !== null && cost > 0 ? "measured" : preferred(input.costSource ?? existing.costSource ?? meta.costSource, "unavailable"),
+    latencyMs,
+    status: preferred(input.status ?? existing.status ?? meta.status ?? input.action, null),
+    timestamp: preferred(input.timestamp ?? existing.timestamp ?? input.ts, null),
+  };
+
+  return Object.values(attribution).some((value) => value !== null && value !== undefined && value !== "")
+    ? attribution
+    : null;
+}
+
+function inferValueUnit(metric = {}, attribution = null, measured, counterfactual) {
+  if (attribution?.cost !== null && attribution?.cost !== undefined) return "currency";
+  if (attribution?.tokenUsage !== null && attribution?.tokenUsage !== undefined) return "tokens";
+
+  const meta = metric.meta || {};
+  if (numberOrNull(meta.totalCost) !== null) return "currency";
+  if (numberOrNull(meta.totalTokens) !== null) return "tokens";
+  if (numberOrNull(meta.bytes) !== null) return "bytes";
+
+  const numericMeasured = numberOrNull(measured);
+  const numericCounterfactual = numberOrNull(counterfactual);
+  if (metric.category === "loop_detected" && (numericMeasured !== null || numericCounterfactual !== null)) return "minutes";
+  if (numericMeasured !== null || numericCounterfactual !== null) return "count";
+  return "unknown";
+}
+
+module.exports = {
+  normalizeAttribution,
+  inferValueUnit,
+  extractRuntimeEvidence,
+};

package/scripts/lib/audit.js

@@ -0,0 +1,289 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const SEVERITY_WEIGHT = {
+  high: 3,
+  medium: 2,
+  low: 1,
+};
+
+const REASON_MAP = {
+  SEC_PRIVATE_KEY: {
+    title: "Remove embedded private key material",
+    suggestedFix: "Delete key material from repository files, rotate the key, and move secrets to secure storage.",
+    actionPath: "security -> secret rotation -> /cco-audit",
+  },
+  SEC_GH_TOKEN: {
+    title: "Rotate exposed GitHub token",
+    suggestedFix: "Remove token-like values, rotate credentials, and enforce local secret scanning before commit.",
+    actionPath: "security -> credential hygiene -> /cco-audit",
+  },
+  SEC_CURL_PIPE_SH: {
+    title: "Eliminate remote shell piping",
+    suggestedFix: "Download scripts first, verify checksum/signature, then run from reviewed local files.",
+    actionPath: "security -> safe execution defaults -> /cco-remediate",
+  },
+  SEC_REMOTE_FETCH: {
+    title: "Pin and verify remote fetch sources",
+    suggestedFix: "Restrict remote fetches to trusted pinned sources and verify checksums before use.",
+    actionPath: "security -> fetch controls -> /cco-remediate",
+  },
+  SEC_REMOTE_INCLUDE: {
+    title: "Replace remote includes with local pinned artifacts",
+    suggestedFix: "Vendor includes locally or pin immutable references and require explicit review.",
+    actionPath: "security -> include controls -> /cco-remediate",
+  },
+  SEC_UNPINNED_GIT_DEP: {
+    title: "Pin git dependencies",
+    suggestedFix: "Use immutable commit SHAs instead of floating refs (main/master/latest).",
+    actionPath: "security -> dependency pinning -> /cco-remediate",
+  },
+  SEC_OVERBROAD_PERMISSION: {
+    title: "Tighten permission budget",
+    suggestedFix: "Replace broad permissions with least-privilege scope for skills and agents.",
+    actionPath: "security -> permission budget -> /cco-settings scope=team",
+  },
+  SEC_BIDI_UNICODE: {
+    title: "Remove bidirectional unicode control characters",
+    suggestedFix: "Replace hidden directional characters and review suspicious text blocks.",
+    actionPath: "security -> content integrity -> /cco-audit",
+  },
+};
+
+function clamp(n, min, max) {
+  return Math.max(min, Math.min(max, n));
+}
+
+function severityRank(sev) {
+  if (sev === "high") return 3;
+  if (sev === "medium") return 2;
+  return 1;
+}
+
+function scoreFinding(finding, recencyWeight) {
+  const sevWeight = SEVERITY_WEIGHT[finding.severity] || 1;
+  const confidence = Number.isFinite(Number(finding.confidence)) ? Number(finding.confidence) : 0.5;
+  const recency = Number.isFinite(Number(recencyWeight)) ? Number(recencyWeight) : 1;
+  return Number((sevWeight * confidence * recency).toFixed(6));
+}
+
+function loadJson(absPath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function listJsonArtifacts(absDir, filterFn = null) {
+  try {
+    return fs
+      .readdirSync(absDir)
+      .filter((name) => name.endsWith(".json"))
+      .filter((name) => (typeof filterFn === "function" ? filterFn(name) : true))
+      .map((name) => {
+        const absPath = path.join(absDir, name);
+        const st = fs.statSync(absPath);
+        return {
+          name,
+          absPath,
+          relPath: path.posix.join(path.relative(process.cwd(), absDir).replace(/\\/g, "/"), name),
+          mtimeMs: st.mtimeMs,
+          data: loadJson(absPath, {}),
+        };
+      })
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+  } catch {
+    return [];
+  }
+}
+
+function reasonDetails(reasonCode) {
+  return (
+    REASON_MAP[reasonCode] || {
+      title: `Review finding ${reasonCode}`,
+      suggestedFix: "Review the highlighted line, apply least-privilege changes, and re-run /cco-audit.",
+      actionPath: "security -> /cco-audit",
+    }
+  );
+}
+
+function remediationJobByReason(cwd) {
+  const jobsDir = path.join(cwd, ".claude", "cco", "patches", "jobs");
+  const jobs = listJsonArtifacts(jobsDir);
+  const map = new Map();
+
+  jobs.forEach((jobArt) => {
+    const patches = Array.isArray(jobArt.data?.patches) ? jobArt.data.patches : [];
+    patches.forEach((patch) => {
+      const reasonCode = String(patch.reasonCode || "");
+      if (!reasonCode) return;
+      if (!map.has(reasonCode)) {
+        map.set(reasonCode, patch.path || jobArt.relPath);
+      }
+    });
+  });
+
+  return map;
+}
+
+function normalizeHighlightsFromArtifacts(artifacts, cwd) {
+  const jobMap = remediationJobByReason(cwd);
+  const normalized = [];
+
+  artifacts.forEach((artifact, idx) => {
+    const highlights = Array.isArray(artifact.data?.highlights) ? artifact.data.highlights : [];
+    const artifactRecencyWeight = clamp(1 - idx * 0.03, 0.7, 1);
+
+    highlights.forEach((h, hIdx) => {
+      const reasonCode = String(h.id || "SEC_UNKNOWN");
+      const severity = ["high", "medium", "low"].includes(String(h.severity || "")) ? String(h.severity) : "low";
+      const confidence = Number.isFinite(Number(h.confidence)) ? Number(h.confidence) : 0.5;
+      const suppressed = h.suppressed === true;
+      const details = reasonDetails(reasonCode);
+      const normalizedFinding = {
+        findingId: `${artifact.name}:${hIdx + 1}:${reasonCode}`,
+        reasonCode,
+        severity,
+        confidence,
+        rationale: String(h.rationale || "No rationale provided."),
+        path: String(h.path || artifact.relPath),
+        line: Number.isFinite(Number(h.line)) ? Number(h.line) : 1,
+        snippet: String(h.snippet || ""),
+        suppressed,
+        sourceArtifact: artifact.relPath,
+        suggestedFix: details.suggestedFix,
+        actionPath: details.actionPath,
+        jobPath: jobMap.get(reasonCode) || null,
+        recencyWeight: artifactRecencyWeight,
+      };
+      normalizedFinding.rankScore = scoreFinding(normalizedFinding, artifactRecencyWeight);
+      normalized.push(normalizedFinding);
+    });
+  });
+
+  return normalized;
+}
+
+function compareFindings(a, b) {
+  if (b.rankScore !== a.rankScore) return b.rankScore - a.rankScore;
+  if (severityRank(b.severity) !== severityRank(a.severity)) return severityRank(b.severity) - severityRank(a.severity);
+  if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+  if (a.reasonCode !== b.reasonCode) return a.reasonCode.localeCompare(b.reasonCode);
+  if (a.path !== b.path) return a.path.localeCompare(b.path);
+  return a.line - b.line;
+}
+
+function topReasonCodesFromFindings(findings, limit = 5) {
+  const counts = {};
+  findings.forEach((f) => {
+    counts[f.reasonCode] = (counts[f.reasonCode] || 0) + 1;
+  });
+
+  return Object.keys(counts)
+    .sort((a, b) => {
+      if (counts[b] !== counts[a]) return counts[b] - counts[a];
+      return a.localeCompare(b);
+    })
+    .slice(0, limit);
+}
+
+function riskLevelFromFindings(activeFindings) {
+  if (!activeFindings.length) return "low";
+  if (activeFindings.some((f) => f.severity === "high")) return "high";
+  if (activeFindings.some((f) => f.severity === "medium")) return "medium";
+  return "low";
+}
+
+function toTopFindingView(finding) {
+  return {
+    reasonCode: finding.reasonCode,
+    severity: finding.severity,
+    confidence: finding.confidence,
+    rationale: finding.rationale,
+    path: finding.path,
+    line: finding.line,
+    suggestedFix: finding.suggestedFix,
+    actionPath: finding.actionPath,
+    jobPath: finding.jobPath,
+  };
+}
+
+function toTopRecommendedFixes(activeFindings, limit = 5) {
+  const seen = new Set();
+  const out = [];
+
+  activeFindings.forEach((f) => {
+    if (seen.has(f.reasonCode)) return;
+    seen.add(f.reasonCode);
+    out.push({
+      reasonCode: f.reasonCode,
+      title: reasonDetails(f.reasonCode).title,
+      text: f.suggestedFix,
+      confidence: f.confidence,
+      actionPath: f.actionPath,
+      jobPath: f.jobPath,
+    });
+  });
+
+  return out.slice(0, limit);
+}
+
+function computeNextBestAction(activeFindings) {
+  if (!activeFindings.length) {
+    return "No active security findings. Keep current defaults and run /cco-audit after meaningful code or skill changes.";
+  }
+
+  const top = activeFindings[0];
+  if (top.severity === "high") {
+    return `Address high-risk finding ${top.reasonCode} first, apply manual remediation, then re-run /cco-audit.`;
+  }
+  return `Address ${top.reasonCode} next, then run /cco-audit to verify reduced risk.`;
+}
+
+function buildAuditSummary(cwd) {
+  const securityDir = path.join(cwd, ".claude", "cco", "security");
+  const securityArtifacts = listJsonArtifacts(
+    securityDir,
+    (name) => name.endsWith("-file-scan.json") || name.endsWith("-prerun-scan.json") || name.endsWith("-scan.json")
+  );
+
+  const normalized = normalizeHighlightsFromArtifacts(securityArtifacts, cwd).sort(compareFindings);
+  const activeFindings = normalized.filter((f) => !f.suppressed);
+  const suppressedFindings = normalized.filter((f) => f.suppressed);
+
+  const topFindings = activeFindings.slice(0, 5).map(toTopFindingView);
+  const topRecommendedFixes = toTopRecommendedFixes(activeFindings, 5);
+  const topReasonCodes = topReasonCodesFromFindings(activeFindings, 5);
+
+  const summary = {
+    riskLevel: riskLevelFromFindings(activeFindings),
+    activeFindings: activeFindings.length,
+    suppressedFindings: suppressedFindings.length,
+    topReasonCodes,
+  };
+
+  return {
+    auditVersion: 1,
+    what: "Security audit completed.",
+    why: "Shows deterministic high-signal security findings and manual remediation suggestions for this repo.",
+    summary,
+    topFindings,
+    topRecommendedFixes,
+    nextBestAction: computeNextBestAction(activeFindings),
+    attribution: {
+      foundBy: "Skill Security Scout",
+      builtBy: "Security Engineer",
+      designedBy: "UX Lead",
+    },
+  };
+}
+
+module.exports = {
+  buildAuditSummary,
+  topReasonCodesFromFindings,
+  riskLevelFromFindings,
+  compareFindings,
+};