@blamejs/blamejs-shop 0.4.31 → 0.4.33

package/lib/vendor/blamejs/scripts/release.js

@@ -11,7 +11,8 @@
  *   node scripts/release.js regen      # re-regen CHANGELOG + api-snapshot (after release-notes edits)
  *   node scripts/release.js smoke      # SMOKE_PARALLEL=64 + (optional) wiki e2e
  *   node scripts/release.js commit     # release branch + signed commit
- *   node scripts/release.js push       # gitleaks + push + open PR
+ *   node scripts/release.js live-integration  # touched-backend live tests
+ *   node scripts/release.js push       # live-integration + gitleaks + push + open PR
  *   node scripts/release.js watch      # gh pr checks --watch + flag Codex threads
  *   node scripts/release.js merge      # squash-merge if CLEAN + zero unresolved threads
  *   node scripts/release.js tag        # signed tag + push tag + verify
@@ -30,6 +31,13 @@
  *   - Git signing config (SSH + allowed_signers + commit/tag.gpgsign)
  *     must be in place. See CLAUDE.md "Release workflow" — one-time
  *     signing setup.
+ *   - Docker must be running for `push` when the release touches a
+ *     backend-protocol lib file (S3/SigV4, MySQL, Postgres, Redis,
+ *     MinIO, SMTP, NTP, DoT, federation/Keycloak, OTel). `push` brings
+ *     up docker-compose.test.yml and runs the matching live integration
+ *     tests; an unavailable stack or a failing test refuses the push.
+ *     This is non-skippable except via an explicit, audited override
+ *     (--skip-live-integration --live-skip-reason="<why>").
  *
  * The judgment-requiring parts stay manual:
  *   - Writing `release-notes/v<next>.json` content.
@@ -249,6 +257,275 @@ function _verifyCommitSignature(label) {
   _ok(label + " commit signature verified");
 }
 
+// ---- Touched-backend live integration ------------------------------------
+//
+// A release that changes the lib code behind a network backend MUST prove
+// itself against a real instance of that backend before it reaches a PR.
+// The class this catches: a change validated only on the host smoke gate
+// (which runs against sqlite + in-memory fakes) that breaks against the
+// live protocol — e.g. a DDL/migration refactor that self-validates on
+// sqlite but emits casing the Postgres wire rejects. Host smoke is green;
+// the regression ships. The fix is to make the matching live test
+// non-skippable on the release path, not advisory.
+//
+// Each backend entry declares:
+//   match     — lib path substrings (matched against the forward-slashed
+//               repo-relative path of every changed file) that mean this
+//               backend's protocol surface was touched. A file under
+//               lib/object-store/ touches the S3 / Azure / GCS backends;
+//               a change to lib/external-db*.js or lib/db-query.js touches
+//               the Postgres + MySQL backends; etc.
+//   services  — the docker-compose.test.yml service names this backend's
+//               tests require (informational + used to scope the readiness
+//               check; the compose `up --wait` brings up the whole stack).
+//   tests     — the test/integration/*.test.js file(s) (basename) that
+//               exercise this backend live. `test-integration.js` accepts
+//               either the bare name or the `.test.js` form.
+//
+// Conservative by construction: when a changed file matches more than one
+// backend, every matching test runs. A shared file (lib/http-client.js,
+// lib/safe-url.js, lib/crypto.js) is referenced by multiple backends on
+// purpose — touching the SigV4 signer or the HTTP client is exactly the
+// kind of cross-cutting change a single-backend smoke can hide.
+var BACKEND_LIVE_MAP = [
+  {
+    backend:  "postgres",
+    match:    ["lib/external-db", "lib/db-query", "lib/db-schema.js",
+               "lib/db-declare", "lib/db-role-context", "lib/cluster-provider-db",
+               "lib/cluster-storage", "lib/safe-sql", "lib/db-collection.js"],
+    services: ["postgres", "postgres-replica"],
+    tests:    ["external-db-postgres", "audit-chain-external-db",
+               "audit-actor-binding-pg", "distributed-scheduler-fencing-pg"],
+  },
+  {
+    backend:  "mysql",
+    match:    ["lib/external-db", "lib/cluster-provider-db", "lib/cluster-storage",
+               "lib/safe-sql"],
+    services: ["mysql"],
+    tests:    ["cluster-provider-mysql"],
+  },
+  {
+    backend:  "redis",
+    match:    ["lib/redis-client", "lib/queue-redis", "lib/pubsub-redis",
+               "lib/cache-redis", "lib/queue.js", "lib/cache.js", "lib/pubsub.js",
+               "lib/crypto-field"],
+    services: ["redis", "redis-tls"],
+    tests:    ["redis-client-tls", "cache", "queue-redis", "pubsub",
+               "redis-reconnect-toxiproxy"],
+  },
+  {
+    backend:  "object-store-s3",
+    match:    ["lib/object-store/sigv4", "lib/object-store/http",
+               "lib/object-store/local", "lib/object-store/index.js",
+               "lib/queue-sqs", "lib/log-stream-cloudwatch", "lib/backup",
+               "lib/restore"],
+    services: ["minio", "minio-tls", "localstack", "localstack-tls"],
+    tests:    ["object-store-sigv4", "object-store-worm-lock",
+               "backup-restore-objectstore", "queue-sqs",
+               "log-stream-cloudwatch"],
+  },
+  {
+    backend:  "object-store-azure",
+    match:    ["lib/object-store/azure-blob", "lib/object-store/http",
+               "lib/object-store/index.js"],
+    services: ["azurite"],
+    tests:    ["object-store-azure"],
+  },
+  {
+    backend:  "object-store-gcs",
+    match:    ["lib/object-store/gcs", "lib/object-store/http",
+               "lib/object-store/index.js"],
+    services: ["fake-gcs"],
+    tests:    ["object-store-gcs"],
+  },
+  {
+    backend:  "smtp-mail",
+    match:    ["lib/mail-send", "lib/mail-smtp", "lib/mail-require-tls",
+               "lib/mail-server", "lib/network-smtp-policy", "lib/mail-dkim",
+               "lib/mail-crypto", "lib/mail-deploy", "lib/mail-auth",
+               "lib/mail.js"],
+    services: ["mailpit"],
+    tests:    ["mail-smtp", "mail-dkim", "mail-crypto-smime"],
+  },
+  {
+    backend:  "ntp",
+    match:    ["lib/ntp-check", "lib/network-nts", "lib/network-ntp"],
+    services: ["ntp"],
+    tests:    ["ntp-check"],
+  },
+  {
+    backend:  "dns-dot",
+    match:    ["lib/network-dns", "lib/network-dane", "lib/network-dnssec",
+               "lib/network-tsig"],
+    services: ["coredns"],
+    tests:    ["network-dns"],
+  },
+  {
+    backend:  "http-tls-outbound",
+    match:    ["lib/http-client", "lib/network-tls", "lib/network-heartbeat",
+               "lib/network-proxy", "lib/tls-exporter", "lib/safe-url"],
+    services: ["caddy", "haproxy", "squid"],
+    tests:    ["http-client", "tls-classical-downgrade-audit",
+               "network-heartbeat", "ssrf-guard"],
+  },
+  {
+    backend:  "federation-keycloak",
+    match:    ["lib/oauth", "lib/saml", "lib/openid", "lib/auth.js",
+               "lib/auth-header", "lib/ciba", "lib/oid4v", "lib/jar",
+               "lib/jarm", "lib/par", "lib/dcr", "lib/scim"],
+    services: ["keycloak"],
+    tests:    ["federation-auth"],
+  },
+  {
+    backend:  "log-stream-tls",
+    match:    ["lib/log-stream"],
+    services: ["syslog", "syslog-tls"],
+    tests:    ["log-stream"],
+  },
+  {
+    backend:  "otel-telemetry",
+    match:    ["lib/log-stream-otlp", "lib/observability"],
+    services: ["otel-collector"],
+    tests:    ["log-stream-cloudwatch"],
+  },
+];
+
+// The whole set of changed files relevant to backend detection: both what
+// the release branch already committed on top of main AND the uncommitted
+// working tree. The feature+release cut (CLAUDE.md "Release workflow")
+// stages the fix in the working tree and lets `commit`'s `git add -A`
+// capture it — so by the time `push` runs the change may be EITHER
+// committed (bump-only cut) or still uncommitted (feature+release cut). We
+// union both so the gate can't be slipped by running before the commit.
+function _changedFilesForBackendDetection() {
+  var seen = {};
+  function add(list) {
+    list.forEach(function (p) {
+      p = (p || "").replace(/\\/g, "/").trim();
+      if (p) seen[p] = true;
+    });
+  }
+  // Committed delta vs main. `origin/main` is the merge target; fall back
+  // to local `main` if the remote ref isn't fetched.
+  var base = "origin/main";
+  if (_capture("git", ["rev-parse", "--verify", "--quiet", base]).status !== 0) {
+    base = "main";
+  }
+  add(_capture("git", ["diff", "--name-only", base + "...HEAD"]).stdout.split(/\r?\n/));
+  // Uncommitted working-tree delta (staged + unstaged + untracked).
+  add(_capture("git", ["diff", "--name-only"]).stdout.split(/\r?\n/));
+  add(_capture("git", ["diff", "--name-only", "--cached"]).stdout.split(/\r?\n/));
+  add(_capture("git", ["ls-files", "--others", "--exclude-standard"]).stdout.split(/\r?\n/));
+  return Object.keys(seen);
+}
+
+// Map the changed-file set onto the backends whose protocol surface was
+// touched. Returns a de-duplicated, deterministic list of
+// { backend, services, tests, matchedBy } entries.
+function _detectTouchedBackends(changedFiles) {
+  var hits = [];
+  BACKEND_LIVE_MAP.forEach(function (entry) {
+    var matchedBy = changedFiles.filter(function (f) {
+      return entry.match.some(function (m) { return f.indexOf(m) !== -1; });
+    });
+    if (matchedBy.length > 0) {
+      hits.push({
+        backend:   entry.backend,
+        services:  entry.services,
+        tests:     entry.tests,
+        matchedBy: matchedBy,
+      });
+    }
+  });
+  return hits;
+}
+
+// Bring the docker-compose.test.yml stack up and block until every
+// service reports healthy. Docker being unavailable, or the stack failing
+// to converge, is a HARD STOP — never a skip. A release that touches a
+// backend it cannot prove against does not ship.
+function _bringUpDockerStack() {
+  var probe = _capture("docker", ["version", "--format", "{{.Server.Version}}"]);
+  if (probe.status !== 0) {
+    throw new Error(
+      "release: live integration requires Docker, but `docker version` failed.\n" +
+      (probe.stderr || probe.stdout || "(no docker daemon reachable)") + "\n" +
+      "Start Docker Desktop / the docker daemon and re-run. This is a hard stop, " +
+      "not a skip — a backend change that can't be proven live does not ship.");
+  }
+  console.log("docker server: " + (probe.stdout || "(version unknown)"));
+  // `up -d --wait` returns non-zero if any service's healthcheck doesn't
+  // reach healthy within its compose-declared timeout. _run throws on
+  // non-zero (allowFail defaults off), so a stack that won't converge
+  // stops the release here.
+  _run("docker", ["compose", "-f", "docker-compose.test.yml", "up", "-d", "--wait"]);
+  _ok("docker-compose.test.yml stack up + healthy");
+}
+
+function cmdLiveIntegration(opts) {
+  opts = opts || {};
+  _section("live integration");
+
+  var changed = _changedFilesForBackendDetection();
+  var touched = _detectTouchedBackends(changed);
+
+  if (touched.length === 0) {
+    _ok("no backend-protocol lib files changed — no live integration required");
+    return;
+  }
+
+  // Aggregate the matching test files across every touched backend.
+  var testSet = {};
+  touched.forEach(function (t) {
+    t.tests.forEach(function (name) { testSet[name] = true; });
+  });
+  var testFiles = Object.keys(testSet).sort();
+
+  console.log("touched backends (" + touched.length + "):");
+  touched.forEach(function (t) {
+    console.log("  - " + t.backend + "  [" + t.tests.join(", ") + "]");
+    t.matchedBy.slice(0, 6).forEach(function (f) { console.log("      via " + f); });
+    if (t.matchedBy.length > 6) {
+      console.log("      via (+" + (t.matchedBy.length - 6) + " more)");
+    }
+  });
+  console.log("live test files to run (" + testFiles.length + "): " + testFiles.join(", "));
+
+  // The skip path is deliberately heavy: an explicit flag AND a non-empty
+  // audited reason, both printed loudly so the bypass is never silent and
+  // is captured in the release-flow transcript. A flag with no reason is
+  // refused — "I'll explain later" is not an answer here.
+  if (opts.skip) {
+    if (!opts.skipReason) {
+      throw new Error(
+        "release: --skip-live-integration requires --live-skip-reason=\"<why>\".\n" +
+        "The live gate proves a touched backend against a real instance; skipping " +
+        "it needs an explicit, audited reason printed to the operator — not a silent " +
+        "bypass. Provide --live-skip-reason or run the live tests.");
+    }
+    console.log("");
+    console.log("!! LIVE INTEGRATION SKIPPED — operator override");
+    console.log("!! reason: " + opts.skipReason);
+    console.log("!! touched backends NOT proven live: " +
+                touched.map(function (t) { return t.backend; }).join(", "));
+    console.log("!! tests NOT run: " + testFiles.join(", "));
+    console.log("!! This override is recorded in the release-flow output above.");
+    return;
+  }
+
+  _bringUpDockerStack();
+
+  // `--skip-service-check` is intentionally NOT passed: the readiness gate
+  // inside test-integration.js is a second proof that the stack the tests
+  // need is actually reachable (the `up --wait` healthchecks and the
+  // framework's own TCP/TLS probes can disagree). We want both.
+  _section("run live integration tests");
+  _run("node", ["scripts/test-integration.js"].concat(testFiles));
+  _ok("live integration green for: " + touched.map(function (t) {
+    return t.backend;
+  }).join(", "));
+}
+
 // ---- Subcommands ---------------------------------------------------------
 
 function cmdPrepare(opts) {
@@ -405,13 +682,21 @@ function cmdCommit() {
   console.log("\nnext: node scripts/release.js push");
 }
 
-function cmdPush() {
+function cmdPush(opts) {
+  opts = opts || {};
   _section("push");
   if (!_gitOnRelease()) {
     throw new Error("release: push must run on a release/vX.Y.Z branch");
   }
   var next = _readPackageVersion();
 
+  // Touched-backend live integration runs BEFORE gitleaks + the PR opens.
+  // A backend change that only passed host smoke (sqlite + in-memory
+  // fakes) must prove itself against the real protocol here; a failure is
+  // a hard stop that refuses the push. Non-skippable except via an
+  // explicit, audited override (see cmdLiveIntegration).
+  cmdLiveIntegration({ skip: opts.skipLiveIntegration, skipReason: opts.liveSkipReason });
+
   _section("gitleaks");
   // Docker bind-mount path: Windows host paths look like
   // `C:\Users\Robert\Dropbox (Personal)\...`; Docker Desktop accepts
@@ -457,6 +742,56 @@ function cmdPush() {
   console.log("\nnext: node scripts/release.js watch");
 }
 
+// Fetch every UNRESOLVED review thread on the PR with enough context to act on
+// it: the file:line, the reviewer that raised it (CodeQL = github-advanced-
+// security, Codex = chatgpt-codex-connector, lint = github-code-quality), the
+// first line of the finding, the thread id, and the resolve mutation. Bot
+// reviews post ASYNCHRONOUSLY — often a minute or two AFTER the status checks
+// finish — so this is the authoritative check at merge time, not just watch.
+function _unresolvedThreads(prNum) {
+  var rv = _capture("gh", ["api", "graphql",
+    "-f", "query=query { repository(owner:\"blamejs\",name:\"blamejs\") { pullRequest(number:" + prNum +
+      ") { reviewThreads(first:100) { nodes { id isResolved path line " +
+      "comments(first:1) { nodes { author{login} body } } } } } } }",
+    "--jq", ".data.repository.pullRequest.reviewThreads.nodes"]);
+  var nodes;
+  try { nodes = JSON.parse(rv.stdout || "[]"); } catch (_e) { nodes = []; }
+  return (nodes || []).filter(function (t) { return t && t.isResolved === false; })
+    .map(function (t) {
+      var c = t.comments && t.comments.nodes && t.comments.nodes[0];
+      return {
+        id:     t.id,
+        path:   t.path || "(pr-level)",
+        line:   t.line,
+        author: (c && c.author && c.author.login) || "(unknown)",
+        body:   (c && c.body) || "",
+      };
+    });
+}
+
+// Surface each unresolved thread with the exact finding it raises + how to
+// clear it, so a BLOCKED merge names its cause instead of "state=BLOCKED".
+function _printUnresolvedThreads(unresolved) {
+  console.log("\n" + unresolved.length + " unresolved review thread(s) block the merge " +
+              "(main-protection requires every thread resolved):\n");
+  unresolved.forEach(function (t, i) {
+    var lines = (t.body || "").split("\n");
+    var firstLine = "(no text)";
+    for (var li = 0; li < lines.length; li++) {
+      if (lines[li].trim().length > 0) { firstLine = lines[li]; break; }
+    }
+    // Strip markdown badge images / formatting noise from Codex P1/P2 headers.
+    firstLine = firstLine.replace(/!\[[^\]]*\]\([^)]*\)/g, "").replace(/[*_`#>]/g, "").trim();
+    console.log("  " + (i + 1) + ". [" + t.author + "] " + t.path +
+                (t.line != null ? ":" + t.line : ""));
+    console.log("     " + firstLine.slice(0, 160));
+    console.log("     resolve: gh api graphql -f query='mutation { resolveReviewThread(" +
+                "input:{threadId:\"" + t.id + "\"}){ thread { isResolved } } }'");
+  });
+  console.log("\nFix each finding in a NEW commit on the branch (never dismiss), then run the");
+  console.log("resolve command above for its thread. Re-run: node scripts/release.js merge");
+}
+
 function cmdWatch() {
   _section("watch");
   var prNum = _capture("gh", ["pr", "list",
@@ -472,24 +807,16 @@ function cmdWatch() {
 
   _run("gh", ["pr", "checks", prNum, "--watch"], { allowFail: true });
 
-  var threadRv = _capture("gh", ["api", "graphql",
-                                  "-f", "query=query { repository(owner:\"blamejs\",name:\"blamejs\") { pullRequest(number:" + prNum +
-                                       ") { reviewThreads(first:50) { nodes { isResolved comments(first:1) { nodes { author{login} body } } } } } } }",
-                                  "--jq", ".data.repository.pullRequest.reviewThreads.nodes | map(select(.isResolved==false))"]);
-  var unresolved = JSON.parse(threadRv.stdout || "[]");
+  var unresolved = _unresolvedThreads(prNum);
   if (unresolved.length > 0) {
-    console.log("\nunresolved review threads (" + unresolved.length + "):");
-    unresolved.forEach(function (t) {
-      var c = t.comments && t.comments.nodes && t.comments.nodes[0];
-      if (c) {
-        console.log("  - by " + c.author.login + ": " + c.body.split("\n")[0]);
-      }
-    });
-    console.log("");
-    console.log("Resolve threads + push fixes, then re-run: node scripts/release.js watch");
+    _printUnresolvedThreads(unresolved);
     process.exit(3);
   }
-  _ok("zero unresolved threads");
+  // Zero here is NOT conclusive: bot reviews (CodeQL / Codex / code-quality)
+  // can post a minute or two after the checks finish. `merge` re-pulls and is
+  // the authoritative gate; treat a clean watch as "checks done", not "no
+  // findings".
+  _ok("zero unresolved threads at watch time (merge re-checks — bot reviews may still be posting)");
 
   console.log("\nnext: node scripts/release.js merge");
 }
@@ -505,27 +832,29 @@ function cmdMerge() {
   }
   var state = JSON.parse(_capture("gh", ["pr", "view", prNum,
     "--json", "mergeStateStatus,mergeable"]).stdout || "{}");
+  // Pull unresolved review threads FIRST, at merge time. A BLOCKED state is
+  // most often unresolved threads — the bot reviews (CodeQL = github-advanced-
+  // security, Codex = chatgpt-codex-connector, lint = github-code-quality) post
+  // asynchronously, AFTER the status checks finish, so `watch` can have seen
+  // zero while they were still landing. Surface exactly which findings block
+  // the merge instead of an opaque "state=BLOCKED", so the operator knows what
+  // to fix + resolve. (main-protection's require_review_thread_resolution makes
+  // any open thread BLOCK; this is the recovery path.)
+  var unresolved = _unresolvedThreads(prNum);
   if (state.mergeStateStatus !== "CLEAN" || state.mergeable !== "MERGEABLE") {
+    if (unresolved.length > 0) _printUnresolvedThreads(unresolved);
     throw new Error("release: PR #" + prNum + " not mergeable (state=" +
-                    state.mergeStateStatus + " mergeable=" + state.mergeable + ")");
-  }
-  // Re-check unresolved review threads RIGHT BEFORE the merge call.
-  // `watch` enforces zero unresolved at watch time, but a reviewer
-  // can open a new thread between watch + merge, or main-protection
-  // may not enforce `require_review_thread_resolution` on every repo
-  // — the merge gate stays robust either way.
-  var threadRv = _capture("gh", ["api", "graphql",
-                                  "-f", "query=query { repository(owner:\"blamejs\",name:\"blamejs\") { pullRequest(number:" + prNum +
-                                       ") { reviewThreads(first:50) { nodes { isResolved comments(first:1) { nodes { author{login} body } } } } } } }",
-                                  "--jq", ".data.repository.pullRequest.reviewThreads.nodes | map(select(.isResolved==false))"]);
-  var unresolved = JSON.parse(threadRv.stdout || "[]");
+                    state.mergeStateStatus + " mergeable=" + state.mergeable + ")" +
+                    (unresolved.length > 0
+                      ? " — " + unresolved.length + " unresolved review thread(s); see above"
+                      : " — no unresolved threads; check required status checks / signatures"));
+  }
+  // Belt-and-suspenders: even if the API reports CLEAN, refuse on any open
+  // thread (a thread can open in the window between the state read and merge).
   if (unresolved.length > 0) {
-    console.log("\nunresolved review threads opened since watch (" + unresolved.length + "):");
-    unresolved.forEach(function (t) {
-      var c = t.comments && t.comments.nodes && t.comments.nodes[0];
-      if (c) console.log("  - by " + c.author.login + ": " + c.body.split("\n")[0]);
-    });
-    throw new Error("release: refusing to merge PR #" + prNum + " — unresolved review threads");
+    _printUnresolvedThreads(unresolved);
+    throw new Error("release: refusing to merge PR #" + prNum + " — " +
+                    unresolved.length + " unresolved review thread(s)");
   }
   _run("gh", ["pr", "merge", prNum, "--squash", "--delete-branch"]);
   _ok("PR #" + prNum + " squash-merged");
@@ -609,7 +938,7 @@ function cmdAll(opts) {
   cmdPrepare(opts);
   cmdSmoke();
   cmdCommit();
-  cmdPush();
+  cmdPush(opts);
   cmdWatch();
   cmdMerge();
   cmdTag();
@@ -643,7 +972,8 @@ function cmdHelp() {
   console.log("  node scripts/release.js regen               # re-regen artifacts after release-notes edits");
   console.log("  node scripts/release.js smoke               # framework + wiki e2e if needed");
   console.log("  node scripts/release.js commit              # release branch + signed commit");
-  console.log("  node scripts/release.js push                # gitleaks + push + open PR");
+  console.log("  node scripts/release.js live-integration    # touched-backend live tests (docker stack)");
+  console.log("  node scripts/release.js push                # live-integration + gitleaks + push + open PR");
   console.log("  node scripts/release.js watch               # CI watch + flag Codex threads");
   console.log("  node scripts/release.js merge               # squash-merge if CLEAN");
   console.log("  node scripts/release.js tag                 # signed tag + push tag");
@@ -651,14 +981,39 @@ function cmdHelp() {
   console.log("  node scripts/release.js all [--minor]       # all eight in sequence");
   console.log("  node scripts/release.js status              # current branch + version state");
   console.log("  node scripts/release.js help                # this banner");
+  console.log("");
+  console.log("Live-integration gate (runs inside push):");
+  console.log("  Detects which backends the release touched (diffing changed lib");
+  console.log("  files against a backend->files map), brings up docker-compose.test.yml,");
+  console.log("  and runs the matching test/integration tests live. A failing test or an");
+  console.log("  unavailable docker stack is a HARD STOP — the push is refused. To override");
+  console.log("  (audited, never silent): --skip-live-integration --live-skip-reason=\"<why>\".");
 }
 
 // ---- Dispatch ------------------------------------------------------------
 
 var sub = process.argv[2] || "help";
 var args = process.argv.slice(3);
+
+// Parse a `--flag=value` form into its value; returns undefined if absent
+// or if the flag was passed without an `=value` (bare `--flag`).
+function _flagValue(name) {
+  var prefix = name + "=";
+  for (var i = 0; i < args.length; i++) {
+    if (args[i].indexOf(prefix) === 0) return args[i].slice(prefix.length);
+  }
+  return undefined;
+}
+
 var opts = {
   minor: args.indexOf("--minor") !== -1,
+  // The live-integration gate is on by default. `--skip-live-integration`
+  // opts out, but ONLY together with `--live-skip-reason="<why>"`; the
+  // reason is printed loudly and recorded in the release-flow transcript.
+  // A flag with no reason is refused inside cmdLiveIntegration — the gate
+  // is never silently skippable.
+  skipLiveIntegration: args.indexOf("--skip-live-integration") !== -1,
+  liveSkipReason:      _flagValue("--live-skip-reason"),
 };
 
 try {
@@ -667,7 +1022,12 @@ try {
     case "regen":   cmdRegen();       break;
     case "smoke":   cmdSmoke();       break;
     case "commit":  cmdCommit();      break;
-    case "push":    cmdPush();        break;
+    case "live-integration":
+    case "live":    cmdLiveIntegration({
+                      skip:       opts.skipLiveIntegration,
+                      skipReason: opts.liveSkipReason,
+                    });            break;
+    case "push":    cmdPush(opts);    break;
     case "watch":   cmdWatch();       break;
     case "merge":   cmdMerge();       break;
     case "tag":     cmdTag();         break;