bulletin-deploy 0.7.3 → 0.7.4

package/README.md

@@ -274,6 +274,32 @@ What's tracked:
 - Source metadata (repo, branch, PR number, CI vs local)
 - Tool version (`deploy.tool_version`)
 
+### Using bulletin-deploy as a library under your own Sentry
+
+If your tool embeds bulletin-deploy as a library and already runs its own Sentry SDK (for example, Parity's `playground-cli`), you can route bulletin-deploy's deploy spans, tags, and diagnostics through your existing Sentry client rather than clobbering it with ours. Set two env vars **before** importing or invoking bulletin-deploy:
+
+```sh
+BULLETIN_DEPLOY_USE_AMBIENT_SENTRY=1
+BULLETIN_DEPLOY_HOST_APP=<your-app-name>
+```
+
+What happens:
+
+- `BULLETIN_DEPLOY_USE_AMBIENT_SENTRY=1` makes `initTelemetry()` skip its own `Sentry.init()` call. bulletin-deploy reuses the global Sentry client your app already configured. All deploy spans, breadcrumbs, `captureWarning`/`captureMessage` calls route to your DSN.
+- `BULLETIN_DEPLOY_HOST_APP=<name>` attaches `deploy.host_app: <name>` to every deploy span **and** as a Sentry scope tag, so downstream events in the same process carry it too. Use it to facet dashboards by host.
+
+**Requirements:**
+
+- Your app must call its own `Sentry.init()` **before** importing or spawning bulletin-deploy; otherwise there is no ambient client to reuse and telemetry is effectively off.
+- Your Sentry project should live in the same Sentry organisation as `bulletin-deploy` (`o4511059872841728.ingest.de.sentry.io`) if you want our cross-project dashboards to aggregate your traffic. Different org = different world; no cross-aggregation is possible.
+- If your consumer app is maintained by Parity, we can add its name to the `PARITY_HOST_APPS` allowlist in `src/telemetry.ts` so end-user installs of the compiled binary qualify for the same diagnostics as our internal CI. Today: `playground-cli`.
+
+**Gotchas:**
+
+- Quotas are per-project. A traffic spike in your project will eat your quota and can drop bulletin-deploy spans routing through it without any signal in our dashboards.
+- Issue-feed fingerprints don't dedupe across projects: the same error in your project and ours surfaces as two separate Sentry issues.
+- `@sentry/node` major version must be compatible with ours (currently v8.x). Skew risks runtime errors on the first span call.
+
 ### Tagging test and benchmark runs
 
 Real-user deploys and automated test/benchmark deploys share the same telemetry pipeline. Use `--tag` (or the `DEPLOY_TAG` env var) to label non-production runs so Sentry dashboards can filter them out:

package/bin/bulletin-deploy

@@ -2,9 +2,10 @@
 
 import { deploy, DEFAULT_BULLETIN_RPC, DEFAULT_POOL_SIZE, NonRetryableError, EXIT_CODE_NO_RETRY } from "../dist/deploy.js";
 import { bootstrapPool } from "../dist/pool.js";
-import { VERSION } from "../dist/telemetry.js";
+import { VERSION, setDeployAttribute, captureWarning, closeTelemetry, setRunStateActive, markRelaunchOomHintShown } from "../dist/telemetry.js";
 import { handleFailedDeploy, preReleaseWarning } from "../dist/version-check.js";
 import { setDeployContext, installLogCapture, buildCliFlagsSummary } from "../dist/bug-report.js";
+import { loadRunState, writeRunState, shouldSkipStaleWarning, shouldShowOomHint, probablyOomRssMb } from "../dist/run-state.js";
 import * as fs from "fs";
 
 // Install early so anything printed during flag parsing / preflight is
@@ -60,6 +61,92 @@ Options:
 const rcWarning = preReleaseWarning(VERSION);
 if (rcWarning) console.error(rcWarning);
 
+// ── Crash capture (issue #154) ───────────────────────────────────
+// Only wire crash capture for actual deploy / bootstrap runs — skip for
+// --help / --version (which exit above) and --bootstrap (one-off ops op,
+// no background work worth hinting OOM for).
+if (!flags.help && !flags.version && !flags.bootstrap) {
+  // Sanitised argv — positional args + presence-only flag summary. Never
+  // puts a mnemonic/password/RPC/derivation-path on disk, even if the user
+  // passes one on the command line.
+  const sanitizedArgv = [
+    ...positional,
+    ...buildCliFlagsSummary(flags).split(" ").filter(Boolean),
+  ];
+
+  // Check if the previous run left a stale "running" or "crashed" marker
+  // (i.e. this process is a relaunch after a SIGKILL/OOM). Print a hint
+  // BEFORE resetting state so the user sees what happened.
+  const prev = loadRunState();
+  if (prev && (prev.status === "running" || prev.status === "crashed") && !shouldSkipStaleWarning(prev)) {
+    if (shouldShowOomHint(prev)) {
+      const peak = prev.lastPeakRssMb ?? "unknown";
+      const stage = prev.lastStage ?? "unknown";
+      const threshold = probablyOomRssMb();
+      console.error("");
+      console.error(`   Warning: previous deploy did not exit cleanly (peak RSS ${peak} MB at stage "${stage}", threshold ${threshold} MB).`);
+      console.error(`   This looks like an out-of-memory kill. Retry with a larger heap:`);
+      console.error(`     NODE_OPTIONS='--max-old-space-size=8192' bulletin-deploy ...`);
+      console.error("");
+      markRelaunchOomHintShown();
+    } else if (prev.status === "crashed" && prev.reason) {
+      console.error(`   Previous deploy exited via ${prev.reason}. Continuing.`);
+    } else if (prev.status === "running") {
+      console.error(`   Previous deploy did not exit cleanly. Continuing.`);
+    }
+  }
+
+  // Reset the state file to reflect THIS run. Any previous status (crashed,
+  // succeeded, etc.) is overwritten — we already surfaced the warning above.
+  writeRunState({
+    status: "running",
+    pid: process.pid,
+    startedAt: Date.now(),
+    endedAt: undefined,
+    toolVersion: VERSION,
+    argv: sanitizedArgv,
+    lastPeakRssMb: null,
+    lastStage: null,
+    reason: undefined,
+  });
+  setRunStateActive(true);
+
+  // ── Signal / uncaught handlers ──────────────────────────────
+  // Guard against re-entry: if a handler itself throws (e.g. Sentry close
+  // rejects), unhandledRejection must not recursively call finalize.
+  let finalizing = false;
+  const finalize = async (reason, exitCode) => {
+    if (finalizing) return;
+    finalizing = true;
+    try {
+      setDeployAttribute("deploy.killed", reason);
+      setDeployAttribute("deploy.sad", "true");
+      captureWarning(`deploy process terminated: ${reason}`);
+    } catch { /* telemetry best-effort */ }
+    try { await closeTelemetry(1000); } catch { /* ignore */ }
+    try {
+      writeRunState({ status: "crashed", endedAt: Date.now(), reason });
+    } catch { /* fs best-effort */ }
+    process.exit(exitCode);
+  };
+
+  process.on("uncaughtException", (e) => {
+    try { setDeployAttribute("deploy.error", (e?.message ?? String(e)).slice(0, 200)); } catch {}
+    finalize("uncaught", 2);
+  });
+  process.on("unhandledRejection", (e) => {
+    const msg = e instanceof Error ? e.message : String(e);
+    try { setDeployAttribute("deploy.error", msg.slice(0, 200)); } catch {}
+    finalize("unhandled", 2);
+  });
+  // POSIX exit codes: 128 + signal number. Matches shell conventions so
+  // callers (e.g. consumer CI with EXIT_CODE_NO_RETRY=75) treat them as
+  // retryable.
+  process.on("SIGINT", () => finalize("SIGINT", 130));
+  process.on("SIGTERM", () => finalize("SIGTERM", 143));
+  process.on("SIGHUP", () => finalize("SIGHUP", 129));
+}
+
 try {
   if (flags.bootstrap) {
     const rpc = flags.rpc ?? process.env.BULLETIN_RPC ?? DEFAULT_BULLETIN_RPC;
@@ -112,10 +199,16 @@ try {
     console.log(`CID: ${result.cid}`);
     console.log(`Domain: ${result.domainName}`);
   }
+  if (!flags.help && !flags.version && !flags.bootstrap) {
+    try { writeRunState({ status: "succeeded", endedAt: Date.now() }); } catch {}
+  }
   process.exit(0);
 } catch (error) {
   const noRetry = error instanceof NonRetryableError;
   console.error(`Deployment failed${noRetry ? " (not retryable)" : ""}:`, error.message);
   await handleFailedDeploy(error);
+  if (!flags.help && !flags.version && !flags.bootstrap) {
+    try { writeRunState({ status: "failed", endedAt: Date.now(), reason: (error?.message ?? String(error)).slice(0, 200) }); } catch {}
+  }
   process.exit(noRetry ? EXIT_CODE_NO_RETRY : 1);
 }

package/dist/bug-report.js

@@ -9,9 +9,10 @@ import {
   offerBugReport,
   scrubSecrets,
   setDeployContext
-} from "./chunk-4EQERQRG.js";
-import "./chunk-MDYSENTW.js";
-import "./chunk-BYIVK52G.js";
+} from "./chunk-YYULF2JX.js";
+import "./chunk-CQ753LDA.js";
+import "./chunk-DHQ3JGF4.js";
+import "./chunk-UJP2PZGU.js";
 import "./chunk-QGM4M3NI.js";
 export {
   buildCliFlagsSummary,

package/dist/{chunk-MDYSENTW.js → chunk-CQ753LDA.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-BYIVK52G.js";
+} from "./chunk-DHQ3JGF4.js";
 
 // src/version-check.ts
 import { execSync, execFileSync } from "child_process";

package/dist/{chunk-BYIVK52G.js → chunk-DHQ3JGF4.js}

@@ -1,3 +1,8 @@
+import {
+  package_default,
+  writeRunState
+} from "./chunk-UJP2PZGU.js";
+
 // src/memory-report.ts
 import * as fs2 from "fs";
 import * as os from "os";
@@ -9,77 +14,10 @@ import { execSync } from "child_process";
 import { createHash } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
-
-// package.json
-var package_default = {
-  name: "bulletin-deploy",
-  version: "0.7.3",
-  private: false,
-  repository: {
-    type: "git",
-    url: "https://github.com/paritytech/bulletin-deploy.git"
-  },
-  publishConfig: {
-    registry: "https://registry.npmjs.org",
-    access: "public"
-  },
-  type: "module",
-  main: "./dist/index.js",
-  types: "./dist/index.d.ts",
-  bin: {
-    "bulletin-deploy": "./bin/bulletin-deploy"
-  },
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      import: "./dist/index.js"
-    }
-  },
-  files: [
-    "dist",
-    "bin"
-  ],
-  scripts: {
-    build: "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts src/memory-report.ts src/merkle.ts src/gh-pages-mirror.ts src/version-check.ts src/bug-report.ts --format esm --dts --clean --target node22",
-    prepare: "npm run build",
-    test: "npm run build && node --test test/test.js test/pool.test.js test/helpers/e2e-helpers.test.js",
-    "test:e2e": "npm run build && node --test test/e2e.test.js",
-    "test:e2e:smoke": "bash scripts/e2e-pass.sh smoke",
-    "test:e2e:pr": "bash scripts/e2e-pass.sh pr",
-    "test:e2e:nightly": "bash scripts/e2e-pass.sh nightly",
-    benchmark: "npm run build && node benchmark.js"
-  },
-  dependencies: {
-    "@ipld/car": "^5.4.3",
-    "@ipld/dag-pb": "^4.1.3",
-    "@noble/hashes": "^1.7.2",
-    "@polkadot-api/substrate-bindings": "^0.16.5",
-    "@polkadot-labs/hdkd": "^0.0.25",
-    "@polkadot-labs/hdkd-helpers": "^0.0.26",
-    "@polkadot/keyring": "^13.0.0",
-    "@polkadot/util-crypto": "^13.0.0",
-    "@sentry/node": "^9.14.0",
-    "ipfs-unixfs": "^11.2.0",
-    "ipfs-unixfs-importer": "^16.1.4",
-    multiformats: "^13.4.1",
-    "polkadot-api": "^1.23.1",
-    viem: "^2.30.5"
-  },
-  devDependencies: {
-    "@types/node": "^22.0.0",
-    tsup: "^8.5.0",
-    typescript: "^5.9.3"
-  },
-  minimumVersion: "0.5.6",
-  engines: {
-    node: ">=22"
-  }
-};
-
-// src/telemetry.ts
 var VERSION = package_default.version;
 var DEFAULT_DSN = "https://e021c025d79c4c3ade2862a11f13c40b@o4511059872841728.ingest.de.sentry.io/4511093597405264";
 var INTERNAL_ORG_RE = /^(paritytech|w3f|polkadot-fellows)\//i;
+var PARITY_HOST_APPS = /* @__PURE__ */ new Set(["playground-cli"]);
 function extractRepoSlug(url) {
   return url.replace(/.*github\.com[:/]/, "").replace(/\.git$/, "");
 }
@@ -94,13 +32,15 @@ function isInternalContextFromSignals(signals) {
   if (INTERNAL_ORG_RE.test(signals.githubRepository ?? "")) return true;
   if (signals.runnerName?.startsWith("parity-")) return true;
   if (signals.gitRemote && INTERNAL_ORG_RE.test(signals.gitRemote)) return true;
+  if (signals.hostApp && PARITY_HOST_APPS.has(signals.hostApp)) return true;
   return false;
 }
 function isInternalContext() {
   return isInternalContextFromSignals({
     githubRepository: process.env.GITHUB_REPOSITORY,
     runnerName: process.env.RUNNER_NAME,
-    gitRemote: tryGitRemote()
+    gitRemote: tryGitRemote(),
+    hostApp: process.env.BULLETIN_DEPLOY_HOST_APP
   });
 }
 var OPT_OUT = process.env.BULLETIN_DEPLOY_TELEMETRY === "0";
@@ -155,8 +95,26 @@ if (!DISABLED) {
   } catch {
   }
 }
+var runStateActive = false;
+var relaunchOomHintShown = false;
+function setRunStateActive(v) {
+  runStateActive = v;
+}
+function markRelaunchOomHintShown() {
+  relaunchOomHintShown = true;
+}
+async function closeTelemetry(timeoutMs) {
+  if (!Sentry) return;
+  try {
+    await Sentry.close(timeoutMs);
+  } catch {
+  }
+}
 function initTelemetry() {
   if (!Sentry) return;
+  if (process.env.BULLETIN_DEPLOY_USE_AMBIENT_SENTRY === "1") {
+    return;
+  }
   Sentry.init({
     dsn: process.env.SENTRY_DSN || DEFAULT_DSN,
     release: `${package_default.name}@${VERSION}`,
@@ -189,6 +147,12 @@ function initTelemetry() {
       return event;
     }
   });
+  Sentry.setTag("bulletin-deploy.version", VERSION);
+  Sentry.setContext("bulletin-deploy", {
+    version: VERSION,
+    release: `${package_default.name}@${VERSION}`,
+    node: process.version
+  });
 }
 function tryPackageJsonRepo() {
   try {
@@ -220,7 +184,8 @@ function resolveRunnerType() {
   return "github-hosted";
 }
 function getDeployAttributes(domain) {
-  return {
+  const hostApp = process.env.BULLETIN_DEPLOY_HOST_APP;
+  const attrs = {
     "deploy.repo": sanitizeRepo(resolveRepo(domain)),
     "deploy.branch": sanitizeBranch(process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || tryGitBranch()),
     "deploy.source": process.env.CI ? "ci" : "local",
@@ -230,8 +195,18 @@ function getDeployAttributes(domain) {
     "deploy.runner_type": resolveRunnerType(),
     // Seed "false" so successful spans form the %SAD denominator; the catch block and
     // captureWarning flip it to "true" on friction.
-    "deploy.sad": "false"
+    "deploy.sad": "false",
+    // Same ratio-denominator reasoning as deploy.sad above, but for the
+    // %EXPECTED-refusal metric: catch block flips to "true" when the error
+    // matches isExpectedError (user-facing product rule, not tool friction).
+    "deploy.expected": "false",
+    // Seed "false" so every span carries the attribute (boolean-both-values rule).
+    // Flipped to "true" by getWsProvider's onStatusChanged when papi connects to a
+    // non-primary endpoint, and flushed again in deploy()'s finally block.
+    "deploy.rpc.failed_over": "false"
   };
+  if (hostApp) attrs["deploy.host_app"] = hostApp;
+  return attrs;
 }
 function isExpectedError(msg) {
   return /personhood|owned by|owner mismatch|reserved for original|invalid domain label|not authorized for bulletin|insufficient balance|quota exhausted|insufficient .* authorization/i.test(msg);
@@ -281,6 +256,12 @@ function sampleMemory(stage) {
       deployRootSpan.setAttribute("deploy.mem.peak_array_buffers_mb", String(toMb(memoryPeak.arrayBuffers)));
     }
   }
+  if (runStateActive && memoryPeak) {
+    try {
+      writeRunState({ lastPeakRssMb: toMb(memoryPeak.rss), lastStage: stage });
+    } catch {
+    }
+  }
 }
 async function withDeploySpan(domain, fn) {
   if (!Sentry) return fn();
@@ -293,22 +274,30 @@ async function withDeploySpan(domain, fn) {
   try {
     return await Sentry.startSpan({ op: "deploy", name: `deploy ${domain}`, attributes: attrs }, async (span) => {
       deployRootSpan = span;
-      Sentry.setTags({
+      span.setAttribute("deploy.tool_version", VERSION);
+      if (relaunchOomHintShown) {
+        span.setAttribute("deploy.relaunch.oom_hint_shown", "true");
+      }
+      const tagsToSet = {
         "deploy.repo": attrs["deploy.repo"],
         "deploy.branch": attrs["deploy.branch"],
         "deploy.domain": domain,
         "deploy.source": attrs["deploy.source"],
         "deploy.tool_version": VERSION,
-        "deploy.runner_type": resolveRunnerType()
-      });
+        "deploy.runner_type": resolveRunnerType(),
+        "deploy.host_app": attrs["deploy.host_app"] ?? ""
+      };
+      if (!tagsToSet["deploy.host_app"]) delete tagsToSet["deploy.host_app"];
+      Sentry.setTags(tagsToSet);
       try {
         return await fn();
       } catch (error) {
         const msg = error.message;
         span.setAttribute("deploy.status", "error");
         span.setAttribute("deploy.error", msg.slice(0, 200));
-        span.setAttribute("deploy.sad", "true");
         const isExpected = isExpectedError(msg);
+        span.setAttribute("deploy.expected", isExpected ? "true" : "false");
+        span.setAttribute("deploy.sad", isExpected ? "false" : "true");
         if (!isExpected) {
           span.setStatus({ code: 2, message: "internal_error" });
         }
@@ -524,6 +513,9 @@ export {
   truncateAddress,
   sanitizeBranch,
   sanitizeRepo,
+  setRunStateActive,
+  markRelaunchOomHintShown,
+  closeTelemetry,
   initTelemetry,
   resolveRepo,
   resolveRunner,