avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/guard-suite-common.js

@@ -0,0 +1,412 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const DEFAULT_SKIP_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".wasp",
+  "build",
+  "coverage",
+  "dist",
+  ".cache",
+]);
+
+const TEXT_FILE_RE = /\.(cjs|conf|config|css|cts|env|ini|js|json|jsx|md|mjs|mts|prisma|ps1|sql|svg|toml|ts|tsx|txt|xml|yaml|yml)$/i;
+const WINDOWS_PATH_RE = /\b[A-Za-z]:\\[^\s"']+/g;
+const UNIX_PATH_RE = /(?:^|[\s(])\/(?:Users|home|root|tmp|var|etc|opt|usr|mnt)\/[^\s"')]+/g;
+const SECRET_ASSIGNMENT_RE = /((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig;
+const TOKEN_RE = /(?:sk-[A-Za-z0-9_-]{16,}|gh[ps]_[A-Za-z0-9]{12,}|npm_[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{16})/g;
+const ARTIFACT_DIR_RE = /^(?:\.claude\/cco|artifacts)\//i;
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function sanitizeText(value, max = 220) {
+  const text = String(value || "")
+    .replace(/\s+/g, " ")
+    .replace(WINDOWS_PATH_RE, "<redacted-path>")
+    .replace(UNIX_PATH_RE, " <redacted-path>")
+    .replace(SECRET_ASSIGNMENT_RE, "$1[redacted]")
+    .replace(TOKEN_RE, "[redacted-token]")
+    .trim();
+  if (!text) return null;
+  return text.length > max ? `${text.slice(0, max - 3).trimEnd()}...` : text;
+}
+
+function sanitizeRef(value) {
+  const text = toPosix(String(value || "").trim()).replace(/^\.\/+/, "");
+  if (!text || text.startsWith("..")) return null;
+  return text;
+}
+
+function sanitizeSelector(value) {
+  return sanitizeText(value, 120);
+}
+
+function severityRank(severity) {
+  if (severity === "block") return 3;
+  if (severity === "warn") return 2;
+  return 1;
+}
+
+function fileExists(cwd, relPath) {
+  try {
+    return fs.existsSync(path.join(cwd, relPath));
+  } catch {
+    return false;
+  }
+}
+
+function readChangedFiles(cwd, provided) {
+  if (Array.isArray(provided)) {
+    return unique(provided.map(sanitizeRef).filter(Boolean));
+  }
+
+  try {
+    const staged = spawnSync("git", ["diff", "--cached", "--name-only"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 10000,
+      windowsHide: true,
+    });
+    const unstaged = spawnSync("git", ["diff", "--name-only"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 10000,
+      windowsHide: true,
+    });
+    const combined = `${staged.stdout || ""}\n${unstaged.stdout || ""}`;
+    return unique(
+      combined
+        .split(/\r?\n/)
+        .map((line) => sanitizeRef(line))
+        .filter(Boolean)
+    );
+  } catch {
+    return [];
+  }
+}
+
+function isTextCandidate(relPath) {
+  return TEXT_FILE_RE.test(String(relPath || ""));
+}
+
+function isArtifactPath(relPath) {
+  return ARTIFACT_DIR_RE.test(toPosix(relPath));
+}
+
+function makeEvidenceRef(relPath, kind, selector) {
+  const safePath = sanitizeRef(relPath);
+  if (!safePath) return null;
+  return {
+    path: safePath,
+    kind: sanitizeText(kind, 80) || "file",
+    selector: sanitizeSelector(selector) || "redacted",
+    redacted: true,
+  };
+}
+
+function makeFinding(id, severity, reasonCode, title, message, evidenceRefs, safeNextAction) {
+  return {
+    id: sanitizeText(id, 80) || `${reasonCode.toLowerCase()}-finding`,
+    severity,
+    reasonCode,
+    title: sanitizeText(title, 120) || reasonCode,
+    message: sanitizeText(message, 220) || title,
+    evidenceRefs: unique((evidenceRefs || []).filter(Boolean)).slice(0, 5),
+    safeNextAction: sanitizeText(safeNextAction, 220) || "Review the local evidence before proceeding.",
+  };
+}
+
+function createScanState(options = {}) {
+  return {
+    maxFiles: Number.isFinite(Number(options.maxFiles)) ? Math.max(50, Number(options.maxFiles)) : 700,
+    maxDepth: Number.isFinite(Number(options.maxDepth)) ? Math.max(3, Number(options.maxDepth)) : 8,
+    maxFileBytes: Number.isFinite(Number(options.maxFileBytes)) ? Math.max(4096, Number(options.maxFileBytes)) : 128 * 1024,
+    files: [],
+    filesInspected: 0,
+    artifactsInspected: 0,
+    bytesInspected: 0,
+    limitsApplied: [],
+  };
+}
+
+function scanWorkspace(cwd, options = {}) {
+  const state = createScanState(options);
+  const skipDirs = new Set([...(options.skipDirs || []), ...DEFAULT_SKIP_DIRS]);
+
+  function visit(absDir, depth) {
+    if (depth > state.maxDepth || state.files.length >= state.maxFiles) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (state.files.length >= state.maxFiles) {
+        if (!state.limitsApplied.includes("SCAN_LIMIT_APPLIED")) state.limitsApplied.push("SCAN_LIMIT_APPLIED");
+        return;
+      }
+
+      const absPath = path.join(absDir, entry.name);
+      const relPath = toPosix(path.relative(cwd, absPath));
+
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        visit(absPath, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      let size = 0;
+      try {
+        size = fs.statSync(absPath).size;
+      } catch {}
+
+      const file = {
+        absPath,
+        relPath,
+        size,
+        isArtifact: isArtifactPath(relPath),
+        text: undefined,
+        countedBytes: false,
+      };
+      state.files.push(file);
+      state.filesInspected += 1;
+      if (file.isArtifact) state.artifactsInspected += 1;
+    }
+  }
+
+  visit(cwd, 0);
+  return state;
+}
+
+function readText(file, scanState) {
+  if (file.text !== undefined) return file.text;
+  if (!isTextCandidate(file.relPath)) {
+    file.text = null;
+    return file.text;
+  }
+  if (file.size > scanState.maxFileBytes) {
+    if (!scanState.limitsApplied.includes("SCAN_SKIPPED_TOO_LARGE")) scanState.limitsApplied.push("SCAN_SKIPPED_TOO_LARGE");
+    file.text = null;
+    return file.text;
+  }
+  try {
+    file.text = fs.readFileSync(file.absPath, "utf8");
+    if (!file.countedBytes) {
+      scanState.bytesInspected += file.size || Buffer.byteLength(file.text, "utf8");
+      file.countedBytes = true;
+    }
+    return file.text;
+  } catch {
+    file.text = null;
+    return file.text;
+  }
+}
+
+function findPathMatches(files, regex, limit = 8) {
+  const refs = [];
+  for (const file of files) {
+    if (!regex.test(file.relPath)) continue;
+    refs.push(makeEvidenceRef(file.relPath, file.isArtifact ? "artifact" : "file", "path-match"));
+    if (refs.length >= limit) break;
+  }
+  return refs.filter(Boolean);
+}
+
+function findContentMatches(files, scanState, regex, kind, selector, limit = 8) {
+  const refs = [];
+  const matcher = regex.global ? regex : new RegExp(regex.source, `${regex.flags}g`);
+  for (const file of files) {
+    const text = readText(file, scanState);
+    if (!text) continue;
+    matcher.lastIndex = 0;
+    const match = matcher.exec(text);
+    if (!match) continue;
+    refs.push(makeEvidenceRef(file.relPath, kind || (file.isArtifact ? "artifact" : "file"), selector || match[0]));
+    if (refs.length >= limit) break;
+  }
+  return refs.filter(Boolean);
+}
+
+function loadJsonArtifact(cwd, relPath) {
+  return safeReadJson(cwd, relPath, null);
+}
+
+function collectCorruptJsonArtifacts(cwd, scanState, predicate, limit = 6) {
+  const findings = [];
+  const files = scanState.files.filter((file) =>
+    file.isArtifact
+    && /\.json$/i.test(file.relPath)
+    && (!predicate || predicate(file.relPath))
+  );
+
+  for (const file of files) {
+    try {
+      JSON.parse(fs.readFileSync(file.absPath, "utf8").replace(/^\uFEFF/, ""));
+    } catch {
+      findings.push(file.relPath);
+      if (findings.length >= limit) break;
+    }
+  }
+  return findings;
+}
+
+function artifactAgeDays(absPath) {
+  try {
+    const stat = fs.statSync(absPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    return ageMs / (24 * 60 * 60 * 1000);
+  } catch {
+    return null;
+  }
+}
+
+function buildGuardReportSkeleton(schemaVersion, title) {
+  return {
+    schemaVersion,
+    generatedAt: nowIso(),
+    status: "no_data",
+    summary: {
+      title,
+      text: "No relevant local evidence found.",
+      findingCounts: {
+        info: 0,
+        warn: 0,
+        block: 0,
+      },
+      safeNextAction: "Add local evidence and rerun the guard.",
+    },
+    surfaceEvidence: {
+      filesInspected: 0,
+      artifactsInspected: 0,
+      changedFilesConsidered: 0,
+      surfacesDetected: [],
+      limitsApplied: [],
+    },
+    findings: [],
+    productHome: {
+      cardSource: "guard",
+      status: "no_data",
+      found: [],
+      fixedOrPrepared: [],
+      savedOrProved: [],
+      forReview: [],
+      safeNextAction: "Add local evidence and rerun the guard.",
+    },
+    valueProof: {
+      implemented: true,
+      dogfooded: false,
+      measured: false,
+      measurementType: "heuristic",
+      publicClaimAllowed: false,
+      evidenceRefs: [],
+      caveat: "Local deterministic evidence only. No external verification or public claim is implied.",
+    },
+    performance: {
+      durationMs: 0,
+      filesInspected: 0,
+      artifactsInspected: 0,
+      bytesInspected: 0,
+      limitsApplied: [],
+    },
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      registryCalls: false,
+      rawLogDump: false,
+      rawPromptDump: false,
+      rawCodeDump: false,
+      secretDump: false,
+      autoFix: false,
+    },
+  };
+}
+
+function finalizeGuardReport(report, scanState, options = {}) {
+  const infoCount = report.findings.filter((finding) => finding.severity === "info").length;
+  const warnCount = report.findings.filter((finding) => finding.severity === "warn").length;
+  const blockCount = report.findings.filter((finding) => finding.severity === "block").length;
+  const hasSurface = report.surfaceEvidence.surfacesDetected.length > 0;
+
+  report.summary.findingCounts = {
+    info: infoCount,
+    warn: warnCount,
+    block: blockCount,
+  };
+
+  if (!hasSurface) {
+    report.status = "no_data";
+  } else if (blockCount > 0) {
+    report.status = "blocked";
+  } else if (warnCount > 0) {
+    report.status = "warn";
+  } else {
+    report.status = "pass";
+  }
+
+  report.surfaceEvidence.filesInspected = scanState.filesInspected;
+  report.surfaceEvidence.artifactsInspected = scanState.artifactsInspected;
+  report.surfaceEvidence.changedFilesConsidered = (options.changedFiles || []).length;
+  report.surfaceEvidence.limitsApplied = unique(scanState.limitsApplied);
+  report.surfaceEvidence.surfacesDetected = unique(report.surfaceEvidence.surfacesDetected);
+
+  report.performance.durationMs = Number(options.durationMs || 0);
+  report.performance.filesInspected = scanState.filesInspected;
+  report.performance.artifactsInspected = scanState.artifactsInspected;
+  report.performance.bytesInspected = scanState.bytesInspected;
+  report.performance.limitsApplied = unique(scanState.limitsApplied);
+
+  report.productHome.status = report.status;
+  report.productHome.safeNextAction = report.summary.safeNextAction;
+  report.valueProof.dogfooded = options.packageName === "avorelo";
+  report.valueProof.evidenceRefs = unique(report.valueProof.evidenceRefs).slice(0, 4);
+}
+
+function writeGuardReport(cwd, relPath, report, options = {}) {
+  if (options.write === false) return { written: false, reportPath: relPath };
+  safeWriteJson(cwd, relPath, report);
+  return { written: true, reportPath: relPath };
+}
+
+module.exports = {
+  artifactAgeDays,
+  buildGuardReportSkeleton,
+  collectCorruptJsonArtifacts,
+  fileExists,
+  finalizeGuardReport,
+  findContentMatches,
+  findPathMatches,
+  loadJsonArtifact,
+  makeEvidenceRef,
+  makeFinding,
+  readChangedFiles,
+  readText,
+  sanitizeRef,
+  sanitizeSelector,
+  sanitizeText,
+  scanWorkspace,
+  severityRank,
+  toPosix,
+  unique,
+  writeGuardReport,
+};

package/scripts/lib/guidance-builder.js

@@ -0,0 +1,174 @@
+"use strict";
+
+const { formatNextBoundedAction } = require("./proof-canonical");
+
+function extractContinueField(text, label) {
+  const pattern = new RegExp(`^${label}:\\s*(.+)$`, "mi");
+  const match = String(text || "").match(pattern);
+  return match ? String(match[1]).trim() : "";
+}
+
+function parseContinueNote(text) {
+  if (!String(text || "").trim()) return null;
+
+  const whatHappened = extractContinueField(text, "What happened");
+  const nextAction = extractContinueField(text, "Next");
+  const preservedState = extractContinueField(text, "Preserved");
+  const artifactPath = extractContinueField(text, "Artifact");
+
+  if (!whatHappened && !nextAction && !preservedState && !artifactPath) {
+    return null;
+  }
+
+  return {
+    whatHappened,
+    nextAction,
+    preservedState,
+    artifactPath: artifactPath || null,
+  };
+}
+
+function buildFreshStartGuidance(onboardingReady) {
+  const lines = ["## Avorelo Session Guidance", ""];
+
+  if (onboardingReady) {
+    lines.push("Fresh start.");
+    lines.push("");
+    lines.push("Run /avorelo-init, then avorelo status.");
+    lines.push("Avorelo should stay quiet unless it needs to intervene or guide recovery.");
+    return { text: lines.join("\n"), hasResume: false };
+  }
+
+  lines.push("Fresh start.");
+  lines.push("");
+  lines.push("Continue working normally.");
+  lines.push("Use avorelo status if you want a quick check before the next step.");
+  lines.push("Avorelo should stay quiet unless it needs to intervene or guide recovery.");
+  return { text: lines.join("\n"), hasResume: false };
+}
+
+function buildCanonicalReentryGuidance(input = {}, parsedContinueNote = null) {
+  const canonicalReentry =
+    input.canonicalReentry && input.canonicalReentry.is_canonical_truth_available
+      ? input.canonicalReentry
+      : null;
+  if (!canonicalReentry) return null;
+
+  const carryForward = input.carryForward || null;
+  const reentryState = input.reentryState || null;
+  const lines = ["## Avorelo Session Guidance", "", "**Current bounded state**"];
+  const nextAction =
+    canonicalReentry.next_bounded_action_text ||
+    formatNextBoundedAction(canonicalReentry.next_bounded_action) ||
+    parsedContinueNote?.nextAction ||
+    reentryState?.nextAction ||
+    "Run avorelo status to inspect the current bounded state.";
+  const preservedState =
+    parsedContinueNote?.preservedState ||
+    (carryForward?.toolHistory?.toolNames?.length
+      ? `Recent tool context was preserved: ${carryForward.toolHistory.toolNames.join(", ")}.`
+      : null);
+  const artifactPath =
+    canonicalReentry.state_source ||
+    parsedContinueNote?.artifactPath ||
+    reentryState?.primaryArtifactPath ||
+    null;
+
+  if (canonicalReentry.where_am_i_now) {
+    lines.push(`- Where am I now: ${canonicalReentry.where_am_i_now}`);
+  }
+  if (canonicalReentry.what_can_i_honestly_claim) {
+    lines.push(`- Honest claim: ${canonicalReentry.what_can_i_honestly_claim}`);
+  }
+  if (canonicalReentry.reentry_status) {
+    lines.push(`- Re-entry: ${canonicalReentry.reentry_status}`);
+  }
+  lines.push(`- Next: ${nextAction}`);
+  if (canonicalReentry.latest_trustworthy_run_id) {
+    lines.push(`- Trustworthy run: ${canonicalReentry.latest_trustworthy_run_id}`);
+  }
+  if (canonicalReentry.readiness_state) {
+    lines.push(`- Readiness: ${canonicalReentry.readiness_state}`);
+  }
+  if (canonicalReentry.rollback_available === true) {
+    const rollbackSuffix = canonicalReentry.rollback_trigger ? ` (${canonicalReentry.rollback_trigger})` : "";
+    lines.push(`- Rollback: available${rollbackSuffix}.`);
+  }
+  if (preservedState) {
+    lines.push(`- Preserved: ${preservedState}`);
+  }
+  if (artifactPath) {
+    lines.push(`- Artifact: ${artifactPath}`);
+  }
+  if (reentryState?.unresolvedRisk) {
+    lines.push("- Risk: unresolved review still needs attention before the next unsafe step.");
+  }
+  lines.push("");
+  lines.push("Avorelo is active. Continue with the next bounded step.");
+
+  return {
+    text: lines.join("\n"),
+    hasResume: true,
+    usedCanonicalTruth: true,
+  };
+}
+
+function buildStartGuidance(input = {}) {
+  const carryForward = input.carryForward || null;
+  const reentryState = input.reentryState || null;
+  const continueNote = parseContinueNote(input.continueNoteText || "");
+  const onboardingReady = input.onboardingReady === true;
+  const canonicalGuidance = buildCanonicalReentryGuidance(input, continueNote);
+  if (canonicalGuidance) {
+    return canonicalGuidance;
+  }
+
+  const lines = ["## Avorelo Session Guidance", ""];
+
+  const hasResume = Boolean(continueNote || reentryState || carryForward);
+  if (!hasResume) {
+    return buildFreshStartGuidance(onboardingReady);
+  }
+
+  const whatHappened =
+    continueNote?.whatHappened ||
+    (reentryState?.lastInterventionType && reentryState.lastInterventionType !== "none"
+      ? `The last session ended after ${reentryState.lastInterventionType.replace(/_/g, " ")}.`
+      : "The last session left a bounded continuation cue.");
+  const nextAction =
+    continueNote?.nextAction ||
+    reentryState?.nextAction ||
+    "Run avorelo status to continue.";
+  const preservedState =
+    continueNote?.preservedState ||
+    (carryForward?.toolHistory?.toolNames?.length
+      ? `Recent tool context was preserved: ${carryForward.toolHistory.toolNames.join(", ")}.`
+      : "Bounded local evidence from the last session was preserved.");
+  const artifactPath =
+    continueNote?.artifactPath ||
+    reentryState?.primaryArtifactPath ||
+    null;
+
+  lines.push("**Resume cue**");
+  lines.push(`- What happened: ${whatHappened}`);
+  lines.push(`- Next: ${nextAction}`);
+  lines.push(`- Preserved: ${preservedState}`);
+  if (artifactPath) {
+    lines.push(`- Artifact: ${artifactPath}`);
+  }
+  if (reentryState?.unresolvedRisk) {
+    lines.push("- Risk: unresolved risk still needs review before the next unsafe step.");
+  }
+  lines.push("");
+  lines.push("Avorelo is active. Continue with the next bounded step.");
+
+  return {
+    text: lines.join("\n"),
+    hasResume: true,
+  };
+}
+
+module.exports = {
+  buildStartGuidance,
+  parseContinueNote,
+};