avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/avorelo-session-collision-guard.js

@@ -0,0 +1,540 @@
+"use strict";
+
+// Avorelo Session Collision Guard v1
+// ---------------------------------------------------------------------------
+// Internal-only operational safety check. Before an AI coding session edits,
+// commits, pushes, force-pushes, or opens a PR, this guard returns a
+// deterministic decision about whether the session is safe to continue, should
+// adopt an existing branch, should stop and report, or risks duplicate work.
+//
+// Motivation: a real coordination incident where two sessions reasoned about
+// the same PR/branch state and one session had local changes not yet visible
+// on GitHub. This guard makes that hazard observable and deterministic.
+//
+// Architecture boundary (hard):
+//   - deterministic-first, local-first
+//   - read-only git only (never changes branch, never mutates the repo)
+//   - NO model calls, NO network in core mode, NO GitHub API in core mode
+//   - optional, opt-in `--with-gh` PR awareness that fails open if gh is absent
+//   - NO runtime / hook / dashboard / redaction / routing / verify imports
+//   - compact text output by default; stable JSON with --json
+//
+// This is NOT Workstream Preflight. It does not decide product/roadmap
+// priority, does not read or change runtime behavior, and does not enforce
+// GitHub policy. It is a local session-safety check only.
+//
+// The ONLY runtime dependency beyond Node core is the `git` binary, invoked
+// read-only through a subcommand allowlist (see READONLY_GIT / READONLY_GH).
+
+const { execFileSync } = require("child_process");
+
+const SCHEMA_VERSION = "avorelo.sessionCollisionGuard.v1";
+
+const DECISIONS = Object.freeze({
+  SAFE_TO_CONTINUE: "safe_to_continue",
+  ADOPT_EXISTING_BRANCH: "adopt_existing_branch",
+  STOP_AND_REPORT: "stop_and_report",
+  DUPLICATE_PR_RISK: "duplicate_pr_risk",
+  DIRTY_TREE_BLOCKED: "dirty_tree_blocked",
+  BRANCH_DIVERGED: "branch_diverged",
+  NO_GIT_REPO: "no_git_repo",
+  UNKNOWN_NEEDS_USER_DECISION: "unknown_needs_user_decision",
+});
+
+// Read-only command allowlists. Any attempt to run a git/gh subcommand outside
+// these sets throws — the guard structurally cannot push/reset/clean/checkout/
+// merge/rebase/commit or merge a PR.
+const READONLY_GIT = Object.freeze(
+  new Set(["rev-parse", "status", "branch", "rev-list", "log", "for-each-ref", "symbolic-ref"])
+);
+const READONLY_GH = Object.freeze(new Set(["pr", "--version"]));
+const READONLY_GH_PR_ACTIONS = Object.freeze(new Set(["list", "status", "view"]));
+
+// ---------------------------------------------------------------------------
+// Command runners (read-only, allowlist-guarded).
+// ---------------------------------------------------------------------------
+
+function defaultGitRunner(cwd, args) {
+  if (!Array.isArray(args) || args.length === 0 || !READONLY_GIT.has(args[0])) {
+    throw new Error(`blocked non-read-only git invocation: ${(args || []).join(" ")}`);
+  }
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+}
+
+function defaultGhRunner(cwd, args) {
+  if (!Array.isArray(args) || args.length === 0 || !READONLY_GH.has(args[0])) {
+    throw new Error(`blocked non-read-only gh invocation: ${(args || []).join(" ")}`);
+  }
+  if (args[0] === "pr" && !READONLY_GH_PR_ACTIONS.has(args[1])) {
+    throw new Error(`blocked non-read-only gh pr action: ${args[1]}`);
+  }
+  return execFileSync("gh", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+}
+
+// Safe wrapper: returns { ok, out } and never throws for expected git failures
+// (e.g. "no upstream configured", "not a git repository").
+function tryGit(gitRunner, cwd, args) {
+  try {
+    return { ok: true, out: String(gitRunner(cwd, args) || "").trim() };
+  } catch (_err) {
+    return { ok: false, out: "" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Repo inspection (pure given a gitRunner).
+// ---------------------------------------------------------------------------
+
+function inspectRepo(gitRunner, cwd) {
+  const insideWorkTree = tryGit(gitRunner, cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (!insideWorkTree.ok || insideWorkTree.out !== "true") {
+    return { isGitRepo: false };
+  }
+
+  const rootRes = tryGit(gitRunner, cwd, ["rev-parse", "--show-toplevel"]);
+  const root = rootRes.ok ? rootRes.out : null;
+
+  // Current branch ("" when in detached HEAD).
+  const branchRes = tryGit(gitRunner, cwd, ["branch", "--show-current"]);
+  const currentBranch = branchRes.ok && branchRes.out ? branchRes.out : null;
+
+  // Dirty tree: any porcelain entry (tracked modification, staged, or untracked).
+  const statusRes = tryGit(gitRunner, cwd, ["status", "--porcelain"]);
+  const statusLines = statusRes.out ? statusRes.out.split(/\r?\n/).filter(Boolean) : [];
+  const dirty = statusLines.length > 0;
+
+  // Upstream (@{u}); absent => no tracking branch configured.
+  const upstreamRes = tryGit(gitRunner, cwd, [
+    "rev-parse",
+    "--abbrev-ref",
+    "--symbolic-full-name",
+    "@{u}",
+  ]);
+  const upstream = upstreamRes.ok && upstreamRes.out ? upstreamRes.out : null;
+
+  let ahead = 0;
+  let behind = 0;
+  if (upstream) {
+    const counts = tryGit(gitRunner, cwd, ["rev-list", "--left-right", "--count", "HEAD...@{u}"]);
+    if (counts.ok) {
+      const parts = counts.out.split(/\s+/).filter(Boolean);
+      ahead = Number.parseInt(parts[0], 10) || 0;
+      behind = Number.parseInt(parts[1], 10) || 0;
+    }
+  }
+
+  // Local-only detection of a same-named remote-tracking branch (no network).
+  let sameNamedRemoteBranchExists = null;
+  if (currentBranch) {
+    const remoteRefs = tryGit(gitRunner, cwd, [
+      "for-each-ref",
+      "--format=%(refname:short)",
+      `refs/remotes/*/${currentBranch}`,
+    ]);
+    if (remoteRefs.ok) {
+      sameNamedRemoteBranchExists = remoteRefs.out.split(/\r?\n/).filter(Boolean).length > 0;
+    }
+  }
+
+  return {
+    isGitRepo: true,
+    root,
+    currentBranch,
+    upstream,
+    ahead,
+    behind,
+    dirty,
+    dirtyCount: statusLines.length,
+    sameNamedRemoteBranchExists,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Optional, opt-in GitHub PR awareness (fails open).
+// ---------------------------------------------------------------------------
+
+function probeGh(ghRunner, cwd, branch) {
+  // Availability probe first; if gh is missing, fail open (no PR signal).
+  try {
+    ghRunner(cwd, ["--version"]);
+  } catch (_err) {
+    return { checked: true, available: false, openPr: null };
+  }
+
+  if (!branch) {
+    return { checked: true, available: true, openPr: null };
+  }
+
+  try {
+    const out = ghRunner(cwd, [
+      "pr",
+      "list",
+      "--state",
+      "open",
+      "--head",
+      branch,
+      "--json",
+      "number,title,url,headRefName",
+    ]);
+    const arr = JSON.parse(String(out || "[]"));
+    if (Array.isArray(arr) && arr.length > 0) {
+      const pr = arr[0];
+      return {
+        checked: true,
+        available: true,
+        openPr: {
+          number: pr.number,
+          title: pr.title,
+          url: pr.url,
+          headRefName: pr.headRefName,
+        },
+      };
+    }
+    return { checked: true, available: true, openPr: null };
+  } catch (_err) {
+    // gh present but the call failed (no remote, not authed, offline): fail open.
+    return { checked: true, available: true, openPr: null };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core decision (deterministic, precedence-ordered).
+// ---------------------------------------------------------------------------
+
+function baseResult() {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    decision: DECISIONS.UNKNOWN_NEEDS_USER_DECISION,
+    reason: "",
+    safeNextAction: "",
+    sessionOwnershipAcknowledged: false,
+    repo: {
+      isGitRepo: false,
+      root: null,
+      currentBranch: null,
+      upstream: null,
+      ahead: 0,
+      behind: 0,
+      dirty: false,
+    },
+    risk: {
+      dirtyTree: false,
+      noUpstream: false,
+      diverged: false,
+      aheadOnly: false,
+      behindOnly: false,
+      sameNamedRemoteBranchExists: null,
+      openPrForBranch: null,
+      forcePushRisk: "unknown",
+    },
+    gh: {
+      checked: false,
+      available: false,
+      openPr: null,
+    },
+    evidence: [],
+  };
+}
+
+function finalize(result, decision, reason, safeNextAction) {
+  result.decision = decision;
+  result.reason = reason;
+  result.safeNextAction = safeNextAction;
+  return result;
+}
+
+function evaluate(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const targetBranch = options.branch || null;
+  const withGh = !!options.withGh;
+  const allowOwnedSession = !!options.allowOwnedSession;
+  const strict = !!options.strict;
+  const gitRunner = options.gitRunner || defaultGitRunner;
+  const ghRunner = options.ghRunner || defaultGhRunner;
+  // Optional injected gh probe (for tests / alternate transports).
+  const ghProbe = options.ghProbe || ((c, b) => probeGh(ghRunner, c, b));
+
+  const result = baseResult();
+  result.sessionOwnershipAcknowledged = allowOwnedSession;
+
+  const repo = inspectRepo(gitRunner, cwd);
+
+  // Rule 1: not a git repository.
+  if (!repo.isGitRepo) {
+    result.evidence.push("git rev-parse --is-inside-work-tree: not a work tree");
+    return finalize(
+      result,
+      DECISIONS.NO_GIT_REPO,
+      "current working directory is not inside a git work tree.",
+      "Run inside the intended repository before editing, committing, or pushing."
+    );
+  }
+
+  // Populate repo + risk snapshot.
+  result.repo = {
+    isGitRepo: true,
+    root: repo.root,
+    currentBranch: repo.currentBranch,
+    upstream: repo.upstream,
+    ahead: repo.ahead,
+    behind: repo.behind,
+    dirty: repo.dirty,
+  };
+  const aheadOnly = repo.ahead > 0 && repo.behind === 0;
+  const behindOnly = repo.behind > 0 && repo.ahead === 0;
+  const diverged = repo.ahead > 0 && repo.behind > 0;
+  result.risk.dirtyTree = repo.dirty;
+  result.risk.noUpstream = !repo.upstream;
+  result.risk.diverged = diverged;
+  result.risk.aheadOnly = aheadOnly;
+  result.risk.behindOnly = behindOnly;
+  result.risk.sameNamedRemoteBranchExists = repo.sameNamedRemoteBranchExists;
+  result.risk.forcePushRisk = computeForcePushRisk(repo, diverged, aheadOnly, behindOnly);
+
+  result.evidence.push(`currentBranch: ${repo.currentBranch || "(detached)"}`);
+  result.evidence.push(`git status --porcelain: ${repo.dirty ? `dirty (${repo.dirtyCount})` : "clean"}`);
+  result.evidence.push(`upstream: ${repo.upstream || "(none)"}`);
+  result.evidence.push(`ahead/behind: ${repo.ahead}/${repo.behind}`);
+
+  // Optional PR awareness (opt-in, fail-open). Recorded before decisions so it
+  // is visible regardless of which branch state wins.
+  let ghOpenPr = null;
+  if (withGh) {
+    const gh = ghProbe(cwd, repo.currentBranch);
+    result.gh = { checked: !!gh.checked, available: !!gh.available, openPr: gh.openPr || null };
+    ghOpenPr = gh.openPr || null;
+    result.risk.openPrForBranch = ghOpenPr ? ghOpenPr.number : null;
+    result.evidence.push(
+      `gh: ${result.gh.available ? "available" : "unavailable"}${ghOpenPr ? `, openPR #${ghOpenPr.number}` : ", no open PR for branch"}`
+    );
+  }
+
+  // Rule 2: dirty working tree (highest local blocker).
+  if (repo.dirty) {
+    return finalize(
+      result,
+      DECISIONS.DIRTY_TREE_BLOCKED,
+      `uncommitted changes exist (${repo.dirtyCount} entr${repo.dirtyCount === 1 ? "y" : "ies"}).`,
+      "Stop and report before editing or pushing; commit, stash, or hand off the dirty tree first."
+    );
+  }
+
+  // Rule 3: detached HEAD / no current branch.
+  if (!repo.currentBranch) {
+    return finalize(
+      result,
+      DECISIONS.STOP_AND_REPORT,
+      "HEAD is detached; there is no current branch to own.",
+      "Stop and report; check out an intended branch before doing branch-scoped work."
+    );
+  }
+
+  // Rules 9 & 10: explicit --branch target differs from the current branch.
+  if (targetBranch && targetBranch !== repo.currentBranch) {
+    result.evidence.push(`targetBranch: ${targetBranch} (current: ${repo.currentBranch})`);
+    return finalize(
+      result,
+      DECISIONS.STOP_AND_REPORT,
+      `expected branch "${targetBranch}" but the session is on "${repo.currentBranch}".`,
+      "Stop and report; do not act on a different branch than the one you intend to own."
+    );
+  }
+
+  // Rule 4: no upstream configured.
+  if (!repo.upstream) {
+    return finalize(
+      result,
+      DECISIONS.UNKNOWN_NEEDS_USER_DECISION,
+      "branch has no upstream; remote ownership state cannot be determined locally.",
+      "Decide explicitly: set an upstream and re-check, or confirm this is a brand-new local branch before pushing."
+    );
+  }
+
+  // Rule 5: diverged (ahead AND behind).
+  if (diverged) {
+    return finalize(
+      result,
+      DECISIONS.BRANCH_DIVERGED,
+      `branch diverged from ${repo.upstream} (ahead ${repo.ahead}, behind ${repo.behind}).`,
+      "Stop and report; do not force-push. Reconcile by integrating upstream first, then push without --force."
+    );
+  }
+
+  // Rules 8 & 12: an open PR already exists for this branch.
+  if (ghOpenPr) {
+    if (!allowOwnedSession) {
+      return finalize(
+        result,
+        DECISIONS.DUPLICATE_PR_RISK,
+        `an open PR (#${ghOpenPr.number}) already targets this branch and ownership is not acknowledged.`,
+        "Confirm whether this session owns that PR. If it does, re-run with --allow-owned-session; otherwise stop to avoid duplicate work."
+      );
+    }
+    result.evidence.push("sessionOwnershipAcknowledged: true (open PR adopted by this session)");
+  }
+
+  // Rule 6: behind only.
+  if (behindOnly) {
+    if (strict) {
+      return finalize(
+        result,
+        DECISIONS.STOP_AND_REPORT,
+        `branch is behind ${repo.upstream} by ${repo.behind} (strict mode).`,
+        "Stop and report; another session advanced this branch. Adopt their work deliberately before continuing."
+      );
+    }
+    return finalize(
+      result,
+      DECISIONS.ADOPT_EXISTING_BRANCH,
+      `branch is behind ${repo.upstream} by ${repo.behind} with no local commits.`,
+      "Adopt the existing branch: integrate the upstream commits (no force needed) before adding new work."
+    );
+  }
+
+  // Rule 7: ahead only.
+  if (aheadOnly) {
+    return finalize(
+      result,
+      DECISIONS.SAFE_TO_CONTINUE,
+      `branch is ahead of ${repo.upstream} by ${repo.ahead} with no upstream divergence.`,
+      "Safe to continue. A normal push works; only use force-with-lease (never plain force) if you intentionally amended or rebased."
+    );
+  }
+
+  // In sync (ahead 0, behind 0).
+  return finalize(
+    result,
+    DECISIONS.SAFE_TO_CONTINUE,
+    `branch is in sync with ${repo.upstream}.`,
+    "Safe to continue. Push normally when ready; no force-push is warranted."
+  );
+}
+
+function computeForcePushRisk(repo, diverged, aheadOnly, behindOnly) {
+  if (!repo.upstream) return "unknown";
+  if (diverged) return "high";
+  if (behindOnly) return "medium";
+  if (aheadOnly) return "low";
+  return "low";
+}
+
+// ---------------------------------------------------------------------------
+// Rendering.
+// ---------------------------------------------------------------------------
+
+function formatText(result) {
+  const lines = [];
+  lines.push(`Session Guard: ${result.decision}`);
+  lines.push(`Reason: ${result.reason}`);
+  lines.push(`Safe next action: ${result.safeNextAction}`);
+  const detail = [];
+  if (result.repo.currentBranch) detail.push(`branch=${result.repo.currentBranch}`);
+  if (result.repo.upstream) detail.push(`upstream=${result.repo.upstream}`);
+  detail.push(`ahead/behind=${result.repo.ahead}/${result.repo.behind}`);
+  detail.push(`dirty=${result.repo.dirty}`);
+  detail.push(`forcePushRisk=${result.risk.forcePushRisk}`);
+  if (result.gh.checked) detail.push(`gh=${result.gh.available ? (result.gh.openPr ? `PR#${result.gh.openPr.number}` : "noPR") : "unavailable"}`);
+  lines.push(detail.join("  "));
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI.
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = { json: false, branch: null, withGh: false, allowOwnedSession: false, strict: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "--with-gh") opts.withGh = true;
+    else if (a === "--allow-owned-session") opts.allowOwnedSession = true;
+    else if (a === "--strict") opts.strict = true;
+    else if (a === "--branch") opts.branch = argv[++i] || null;
+    else if (a.startsWith("--branch=")) opts.branch = a.slice("--branch=".length) || null;
+    else if (a === "--help" || a === "-h") opts.help = true;
+  }
+  return opts;
+}
+
+function helpText() {
+  return [
+    "Avorelo Session Collision Guard v1 (internal)",
+    "",
+    "Before you edit, commit, push, force-push, or open a PR, ask whether this",
+    "session is safe to continue, should adopt an existing branch, or should stop.",
+    "",
+    "Usage:",
+    "  node scripts/avorelo-session-collision-guard.js",
+    "  node scripts/avorelo-session-collision-guard.js --json",
+    "  node scripts/avorelo-session-collision-guard.js --branch <name>",
+    "  node scripts/avorelo-session-collision-guard.js --json --with-gh",
+    "  node scripts/avorelo-session-collision-guard.js --allow-owned-session",
+    "",
+    "Flags:",
+    "  --json                  emit stable JSON instead of compact text",
+    "  --branch <name>         assert the session is on <name>; mismatch => stop_and_report",
+    "  --with-gh               opt-in read-only PR awareness (fails open if gh absent)",
+    "  --allow-owned-session   acknowledge this session owns the open PR for the branch",
+    "  --strict                treat behind-only as stop_and_report instead of adopt",
+    "",
+    "Decisions: safe_to_continue | adopt_existing_branch | stop_and_report |",
+    "           duplicate_pr_risk | dirty_tree_blocked | branch_diverged |",
+    "           no_git_repo | unknown_needs_user_decision",
+    "",
+    "Read-only git only. No network/model/GitHub API in core mode.",
+  ].join("\n");
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    process.stdout.write(helpText() + "\n");
+    return 0;
+  }
+  let result;
+  try {
+    result = evaluate(opts);
+  } catch (err) {
+    // Only genuine execution errors (e.g. git binary missing) reach here.
+    process.stderr.write(`session-collision-guard: execution error: ${err && err.message}\n`);
+    return 2;
+  }
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    process.stdout.write(formatText(result) + "\n");
+  }
+  // Normal decisions (including stop/blocked) exit 0; only real errors are non-zero.
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  DECISIONS,
+  READONLY_GIT,
+  READONLY_GH,
+  READONLY_GH_PR_ACTIONS,
+  defaultGitRunner,
+  defaultGhRunner,
+  evaluate,
+  inspectRepo,
+  probeGh,
+  formatText,
+  parseArgs,
+  helpText,
+  main,
+  computeForcePushRisk,
+};