bulletin-deploy 0.7.3 → 0.7.5

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-UXKC7JAM.js";
+import "./chunk-XOKNNK6E.js";
+import "./chunk-WOJRQCQV.js";
+import "./chunk-GQFH2NRB.js";
 import "./chunk-QGM4M3NI.js";
 export {
   buildCliFlagsSummary,

package/dist/chunk-GQFH2NRB.js

@@ -0,0 +1,155 @@
+// src/run-state.ts
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+// package.json
+var package_default = {
+  name: "bulletin-deploy",
+  version: "0.7.5",
+  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 src/run-state.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",
+    "@parity/dotns-cli": "0.5.6",
+    "@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/run-state.ts
+var VERSION = package_default.version;
+function resolveStateDir() {
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "bulletin-deploy");
+  }
+  if (process.platform === "win32") {
+    const base2 = process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local");
+    return path.join(base2, "bulletin-deploy");
+  }
+  const base = process.env.XDG_STATE_HOME && process.env.XDG_STATE_HOME.length > 0 ? process.env.XDG_STATE_HOME : path.join(os.homedir(), ".local", "state");
+  return path.join(base, "bulletin-deploy");
+}
+function stateFilePath() {
+  return path.join(resolveStateDir(), "last-run.json");
+}
+function loadRunState() {
+  try {
+    const raw = fs.readFileSync(stateFilePath(), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function writeRunState(patch) {
+  try {
+    const dir = resolveStateDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const file = stateFilePath();
+    let existing = {};
+    try {
+      const raw = fs.readFileSync(file, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") existing = parsed;
+    } catch {
+    }
+    const merged = { ...existing, ...patch };
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(merged), { encoding: "utf-8" });
+    fs.renameSync(tmp, file);
+  } catch {
+  }
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+function shouldSkipStaleWarning(prev) {
+  if (prev.pid && isPidAlive(prev.pid)) return true;
+  if (prev.toolVersion !== VERSION) return true;
+  return false;
+}
+function probablyOomRssMb(override) {
+  if (typeof override === "number" && Number.isFinite(override)) return override;
+  const env = process.env.BULLETIN_DEPLOY_OOM_HINT_RSS_MB;
+  const parsed = env != null ? Number(env) : NaN;
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return 1800;
+}
+function shouldShowOomHint(prev) {
+  if (prev.lastPeakRssMb == null) return false;
+  return prev.lastPeakRssMb >= probablyOomRssMb();
+}
+
+export {
+  package_default,
+  VERSION,
+  resolveStateDir,
+  stateFilePath,
+  loadRunState,
+  writeRunState,
+  shouldSkipStaleWarning,
+  probablyOomRssMb,
+  shouldShowOomHint
+};