@parity/product-deploy 0.7.28-rc.0

package/bin/bulletin-deploy

@@ -0,0 +1,429 @@
+#!/usr/bin/env node
+
+import { deploy, DEFAULT_BULLETIN_RPC, DEFAULT_POOL_SIZE, NonRetryableError, EXIT_CODE_NO_RETRY, isConnectionError, unpublish } from "../dist/deploy.js";
+import { VERSION, setDeployAttribute, captureWarning, closeTelemetry, setRunStateActive, markRelaunchOomHintShown } from "../dist/telemetry.js";
+import { handleFailedDeploy, handlePreflightVersionCheck, fetchVersionInfo, preReleaseWarning, checkNodeVersion } 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 { loadEnvironments, listEnvironments, formatEnvironmentTable, DEFAULT_ENV_ID } from "../dist/environments.js";
+import * as fs from "fs";
+
+// Install early so anything printed during flag parsing / preflight is
+// available to the bug-report log tail.
+installLogCapture();
+
+// Preflight: fail fast on unsupported Node.js versions.
+{
+  const pkgPath = new URL("../package.json", import.meta.url);
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const nodeErr = checkNodeVersion(pkg.engines?.node ?? ">=22", process.version);
+  if (nodeErr) { console.error(`Error: ${nodeErr}`); process.exit(1); }
+}
+
+const args = process.argv.slice(2);
+
+const flags = {};
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--bootstrap") { flags.removedBootstrap = true; }
+  else if (args[i] === "--pool-size") { flags.poolSize = parseInt(args[++i], 10); }
+  else if (args[i] === "--mnemonic") { flags.mnemonic = args[++i]; }
+  else if (args[i] === "--derivation-path") { flags.derivationPath = args[++i]; }
+  else if (args[i] === "--rpc") { flags.rpc = args[++i]; }
+  else if (args[i] === "--env") { flags.env = args[++i]; }
+  else if (args[i] === "--list-environments") { flags.listEnvironments = true; }
+  else if (args[i] === "--password") { flags.password = args[++i]; }
+  else if (args[i] === "--js-merkle") { flags.jsMerkle = true; }
+  else if (args[i] === "--input-car") { flags.inputCar = args[++i]; }
+  else if (args[i] === "--tag") { flags.tag = args[++i]; }
+  else if (args[i] === "--config") { flags.config = args[++i]; }
+  else if (args[i] === "--gh-pages-mirror") { flags.ghPagesMirror = true; }
+  else if (args[i] === "--allow-large-deploy") { flags.allowLargeDeploy = true; }
+  else if (args[i] === "--reproducible") { flags.reproducibleSource = "commit"; }
+  else if (args[i].startsWith("--reproducible=")) { flags.reproducibleSource = args[i].slice("--reproducible=".length); }
+  else if (args[i] === "--dump-car") { flags.dumpCar = true; }
+  else if (args[i].startsWith("--dump-car=")) { flags.dumpCar = args[i].slice("--dump-car=".length); }
+  else if (args[i] === "--publish") { flags.publish = true; }
+  else if (args[i] === "--unpublish") { flags.unpublish = true; }
+  else if (args[i] === "--fail-on-publish-error") { flags.failOnPublishError = true; }
+  else if (args[i] === "--version" || args[i] === "-V") { flags.version = true; }
+  else if (args[i] === "--help" || args[i] === "-h") { flags.help = true; }
+  else { positional.push(args[i]); }
+}
+
+if (flags.publish && flags.unpublish) {
+  console.error("Error: --publish and --unpublish are mutually exclusive.");
+  process.exit(1);
+}
+
+if (flags.version) {
+  console.log(`bulletin-deploy v${VERSION}`);
+  process.exit(0);
+}
+
+if (flags.removedBootstrap) {
+  console.error("Error: --bootstrap was removed from bulletin-deploy. Use bulletin-bootstrap instead.");
+  process.exit(1);
+}
+
+// --list-environments: print the environments table and exit. Composes with
+// nothing else (deploy positional args are ignored).
+if (flags.listEnvironments) {
+  try {
+    const { doc } = await loadEnvironments();
+    console.log(formatEnvironmentTable(listEnvironments(doc)));
+    process.exit(0);
+  } catch (e) {
+    console.error(`Error: failed to load environments: ${e?.message ?? e}`);
+    process.exit(1);
+  }
+}
+
+if (flags.unpublish) {
+  if (!flags.mnemonic && !process.env.MNEMONIC) {
+    console.error("Error: --unpublish requires --mnemonic (or MNEMONIC env var).");
+    process.exit(1);
+  }
+  const [domain] = positional;
+  if (!domain) {
+    console.error("Error: --unpublish requires a domain (e.g. my-app.dot)");
+    process.exit(1);
+  }
+  try {
+    const result = await unpublish(domain, {
+      mnemonic: flags.mnemonic,
+      derivationPath: flags.derivationPath,
+      rpc: flags.rpc,
+      env: flags.env,
+    });
+    console.log(`Domain: ${result.domainName}`);
+    console.log(`Status: ${result.status}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Unpublish failed:`, e?.message ?? e);
+    process.exit(1);
+  }
+}
+
+// `product` subcommand. Only `validate` is wired today. `publish` and `resolve` arrive in later phases.
+if (positional[0] === "product") {
+  const verb = positional[1];
+  if (verb === "validate") {
+    try {
+      const { loadProductConfig, pessimisticSizePreflight, getTextRecordBudgetBytes } =
+        await import("../dist/index.js");
+      const explicitPath = positional[2];
+      const { config, sourcePath } = explicitPath
+        ? await loadProductConfig({ path: explicitPath })
+        : await loadProductConfig();
+      console.log(`✓ Loaded   ${sourcePath}`);
+      console.log(`✓ Schema   ${config.domain} (${config.executables.length} executable${config.executables.length === 1 ? "" : "s"})`);
+      const budget = getTextRecordBudgetBytes();
+      const report = pessimisticSizePreflight(config, budget);
+      for (const check of report.checks) {
+        const tag = check.ok ? "✓" : "✗";
+        console.log(`${tag} ${check.key.padEnd(40)} ${check.bytes} B / ${check.budget} B`);
+      }
+      if (!report.ok) {
+        console.error("Pessimistic size preflight failed — at least one manifest exceeds the dotNS text-record budget.");
+        process.exit(EXIT_CODE_NO_RETRY);
+      }
+      console.log("Validate complete.");
+      process.exit(0);
+    } catch (err) {
+      console.error(`Error: ${err?.message ?? err}`);
+      process.exit(err instanceof NonRetryableError ? EXIT_CODE_NO_RETRY : 1);
+    }
+  }
+  if (verb === "publish" || verb === "resolve") {
+    console.error(`'product ${verb}' is not implemented yet (planned for a later phase).`);
+    process.exit(2);
+  }
+  console.error(`Unknown product subcommand: ${verb ?? "(none)"}. Try: bulletin-deploy product validate [<config-path>]`);
+  process.exit(2);
+}
+
+if (flags.publish && !flags.mnemonic && !process.env.MNEMONIC) {
+  console.error("Error: --publish requires --mnemonic (or MNEMONIC env var).");
+  process.exit(1);
+}
+
+if (flags.help || positional.length === 0) {
+  console.log(`bulletin-deploy v${VERSION}
+
+Usage:
+  bulletin-deploy <build-dir> <domain.dot>  Deploy an app
+
+Options:
+  --env <id>               Target environment from environments.json (default: paseo-next-v2).
+                           Drives both the bulletin RPC and the asset-hub RPC used
+                           by DotNS. See --list-environments for valid ids.
+  --list-environments      Print the environments table and exit.
+  --mnemonic "..."         DotNS owner mnemonic (or set MNEMONIC env var)
+  --derivation-path "..."  Optional Substrate-style path applied to --mnemonic (e.g. //deploy/3)
+  --rpc wss://...          Override the bulletin RPC for the chosen --env (or set BULLETIN_RPC).
+                           Precedence: --rpc > BULLETIN_RPC > --env's bulletin endpoint.
+  --pool-size N       Number of pool accounts (default: 10)
+  --password "..."    Encrypt SPA content (users will be prompted to decrypt)
+  --js-merkle         Use pure-JS merkleization (no IPFS Kubo binary required)
+  --input-car <path>  Deploy a pre-built CAR file; skips directory scan and merkleization.
+                      Usage: bulletin-deploy --input-car <file.car> <domain.dot>
+  --dump-car[=<path>] Save the pre-upload CAR file to disk. Default path: <buildDir>.bulletin.car.
+                      Override path with =<path>. Also settable via BULLETIN_DEPLOY_DUMP_CAR env var.
+  --tag "..."         Label deploy in telemetry (or set DEPLOY_TAG env var); see Telemetry in README
+  --config <path>     Explicit path to a bulletin-deploy.config.ts (default: walk up from
+                      <build-dir> looking for bulletin-deploy.config.{ts,js,mjs}). When a
+                      config is found, deploy ALSO writes the manifest + executable text
+                      records on <domain> and its app/widget/worker subnames.
+  --gh-pages-mirror   After deploy, push the CAR to the current repo's gh-pages branch
+                      at bulletin/<domain>.dot.car (opt-in; also set GH_PAGES_MIRROR=1)
+  --publish           After deploy, list <domain> in the on-chain Publisher
+                      registry (Publisher.publish). Only takes effect on envs
+                      with a deployed Publisher (currently: paseo-next-v2).
+                      Requires --mnemonic (the signer must own the label).
+  --unpublish         Standalone mode: removes <domain> from the Publisher
+                      registry (Publisher.unpublish). Skips the deploy.
+                      Usage: bulletin-deploy --unpublish <domain.dot>
+                      Requires --mnemonic. Mutually exclusive with --publish.
+  --fail-on-publish-error
+                      Exit non-zero if --publish fails after a successful deploy.
+                      Default: non-fatal (warning logged, exit 0).
+  --version           Show version
+  --help              Show this help`);
+  process.exit(0);
+}
+
+const rcWarning = preReleaseWarning(VERSION);
+if (rcWarning) console.error(rcWarning);
+
+// Fire in background immediately; await just before deploy() to stay non-blocking during flag-parse.
+const _versionCheckPromise = process.env.BULLETIN_DEPLOY_UPDATE_CHECK !== "0"
+  ? fetchVersionInfo()
+  : Promise.resolve(null);
+
+// ── Crash capture (issue #154) ───────────────────────────────────
+// Only wire crash capture for actual deploy runs — skip for --help / --version
+// (which exit above).
+if (!flags.help && !flags.version) {
+  // 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.status", "killed");
+      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);
+  };
+
+  // Connection errors propagate from polkadot-api's internal subscriptions
+  // (chainHead etc.) when the WS halts mid-call. They're recoverable via
+  // storeChunkedContent's reconnect path; don't exit. The retry-budget
+  // circuit breaker (#271) bounds repeat occurrences — if too many fire in
+  // 30s, the deploy bails cleanly with "Retry budget exhausted" instead of
+  // looping forever. Issue #278 has the full diagnosis.
+  const handleUnhandled = (e, kind) => {
+    const msgStr = e instanceof Error ? (e.message ?? "") : String(e);
+    // Debug breadcrumb — gated by env so it doesn't add stderr noise in
+    // production but helps when running E2E fault-injection scenarios.
+    if (process.env.BULLETIN_DEPLOY_DEBUG_HANDLERS === "1") {
+      console.error(`[handleUnhandled ${kind}] match=${isConnectionError(e)} type=${e?.constructor?.name ?? typeof e} msg=${msgStr.slice(0, 200)}`);
+    }
+    if (isConnectionError(e)) {
+      try {
+        captureWarning(`Suppressed ${kind} connection error`, { msg: msgStr.slice(0, 200) });
+      } catch { /* telemetry best-effort */ }
+      return;
+    }
+    try { setDeployAttribute("deploy.error", msgStr.slice(0, 200)); } catch {}
+    finalize(kind, 2);
+  };
+  process.on("uncaughtException", (e) => handleUnhandled(e, "uncaught"));
+  process.on("unhandledRejection", (e) => handleUnhandled(e, "unhandled"));
+  // POSIX exit codes: 128 + signal number. Signal exits (130/SIGINT,
+  // 143/SIGTERM, 129/SIGHUP) indicate cancellation or environment teardown
+  // and are retryable from the consumer's perspective. Contrast with
+  // NonRetryableError exits (code 78, POSIX EX_CONFIG) which callers must
+  // NOT retry — see EXIT_CODE_NO_RETRY in src/errors.ts.
+  process.on("SIGINT", () => finalize("SIGINT", 130));
+  process.on("SIGTERM", () => finalize("SIGTERM", 143));
+  process.on("SIGHUP", () => finalize("SIGHUP", 129));
+}
+
+try {
+  let buildDir, domain;
+  if (flags.inputCar) {
+    // --input-car mode: positional[0] is the domain; no build directory needed.
+    [domain] = positional;
+    if (!flags.inputCar) { console.error("Error: --input-car requires a path argument"); process.exit(1); }
+    if (!domain) { console.error("Error: domain required (e.g. my-app.dot)"); process.exit(1); }
+    if (!fs.existsSync(flags.inputCar)) { console.error(`Error: ${flags.inputCar} does not exist`); process.exit(1); }
+    buildDir = flags.inputCar; // passed as `content` to deploy(); inputCar branch handles it
+  } else {
+    [buildDir, domain] = positional;
+    if (!buildDir) { console.error("Error: build directory required"); process.exit(1); }
+    if (!domain) { console.error("Error: domain required (e.g. my-app.dot)"); process.exit(1); }
+    if (!fs.existsSync(buildDir)) { console.error(`Error: ${buildDir} does not exist`); process.exit(1); }
+  }
+
+  const effectiveRpc = flags.rpc ?? process.env.BULLETIN_RPC ?? DEFAULT_BULLETIN_RPC;
+  const deployTag = flags.tag ?? process.env.DEPLOY_TAG;
+  const ci = process.env.GITHUB_ACTIONS === "true" ? {
+    runUrl: process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
+      ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}${process.env.GITHUB_RUN_ATTEMPT ? `/attempts/${process.env.GITHUB_RUN_ATTEMPT}` : ""}`
+      : undefined,
+    workflow: process.env.GITHUB_WORKFLOW,
+    job: process.env.GITHUB_JOB,
+    sha: process.env.GITHUB_SHA,
+  } : undefined;
+  setDeployContext({
+    domain,
+    rpc: effectiveRpc,
+    repo: process.env.GITHUB_REPOSITORY,
+    branch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+    signerMode: flags.mnemonic ? "direct" : "pool",
+    deployTag,
+    cliFlags: buildCliFlagsSummary(flags),
+    ci,
+  });
+
+  // Await the background version check started at startup.
+  const _versionInfo = await _versionCheckPromise;
+  if (handlePreflightVersionCheck(_versionInfo) === "abort") process.exit(1);
+
+  const result = await deploy(buildDir, domain, {
+    mnemonic: flags.mnemonic,
+    derivationPath: flags.derivationPath,
+    rpc: flags.rpc,
+    env: flags.env,
+    poolSize: flags.poolSize,
+    password: flags.password,
+    jsMerkle: flags.jsMerkle,
+    inputCar: flags.inputCar,
+    tag: flags.tag,
+    ghPagesMirror: flags.ghPagesMirror,
+    allowLargeDeploy: flags.allowLargeDeploy,
+    reproducibleSource: flags.reproducibleSource,
+    dumpCar: flags.dumpCar,
+    publish: flags.publish,
+    failOnPublishError: flags.failOnPublishError,
+  });
+
+  const output = process.env.GITHUB_OUTPUT;
+  if (output) {
+    fs.appendFileSync(output, `cid=${result.cid}\n`);
+    fs.appendFileSync(output, `domain=${result.domainName}\n`);
+  }
+
+  console.log(`CID: ${result.cid}`);
+  console.log(`Domain: ${result.domainName}`);
+
+  // Opt-in manifest publish on top of the legacy contenthash deploy.
+  //
+  // Walks up from <build-dir> (or honours --config) looking for
+  // bulletin-deploy.config.{ts,js,mjs}. When found, writes the root + per-
+  // executable text records, otherwise the legacy flow returns unchanged.
+  {
+    const { tryLoadProductConfig, publishManifest } = await import("../dist/index.js");
+    const path = await import("node:path");
+    const buildDirAbs = path.resolve(buildDir);
+    const loaded = await tryLoadProductConfig(
+      flags.config ? { path: flags.config } : { cwd: buildDirAbs, walkUp: true },
+    );
+    if (loaded) {
+      try {
+        await publishManifest({
+          loaded,
+          domain,
+          buildDirCid: { absPath: buildDirAbs, cid: result.cid },
+          env: flags.env,
+          rpc: flags.rpc,
+          mnemonic: flags.mnemonic,
+          derivationPath: flags.derivationPath,
+        });
+      } catch (err) {
+        console.error(`Manifest publish failed: ${err?.message ?? err}`);
+        process.exit(err instanceof NonRetryableError ? EXIT_CODE_NO_RETRY : 1);
+      }
+    } else {
+      const where = flags.config
+        ? `--config ${flags.config}`
+        : `bulletin-deploy.config.{ts,js,mjs} via walking up from ${buildDirAbs}`;
+      console.log("");
+      console.log(`⚠  No bulletin-deploy.config.ts found (${where}).`);
+      console.log(`   ${domain} was published as legacy contenthash only.`);
+      console.log("   Add a bulletin-deploy.config.ts to enable the product manifest:");
+      console.log("     • product icon, displayName, description on the base name");
+      console.log("     • per-modality subnames (app.<id>.dot, widget.<id>.dot, worker.<id>.dot)");
+      console.log("     • each modality’s archive CID on its subname contenthash");
+      console.log("   See: https://github.com/paritytech/triangle-js-sdks (Product Manifest RFC)");
+    }
+  }
+
+  if (!flags.help && !flags.version) {
+    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) {
+    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.d.ts

@@ -0,0 +1,29 @@
+interface DeployContext {
+    domain?: string;
+    repo?: string;
+    branch?: string;
+    signerMode?: string;
+    chunkCount?: number;
+    totalSize?: string;
+    rpc?: string;
+    deployTag?: string;
+    cliFlags?: string;
+    ci?: {
+        runUrl?: string;
+        workflow?: string;
+        job?: string;
+        sha?: string;
+    };
+}
+declare function setDeployContext(ctx: Partial<DeployContext>): void;
+declare function installLogCapture(): void;
+declare function getCapturedTail(): string;
+declare function scrubSecrets(text: string): string;
+declare function buildCliFlagsSummary(flags: Record<string, unknown>): string;
+declare function buildReportBody(error: Error): string;
+declare function buildTitle(error: Error): string;
+declare function buildLabels(error: Error): string[];
+declare function createGhIssue(title: string, body: string, labels: string[]): string;
+declare function offerBugReport(error: Error): Promise<void>;
+
+export { buildCliFlagsSummary, buildLabels, buildReportBody, buildTitle, createGhIssue, getCapturedTail, installLogCapture, offerBugReport, scrubSecrets, setDeployContext };

package/dist/bug-report.js

@@ -0,0 +1,27 @@
+import {
+  buildCliFlagsSummary,
+  buildLabels,
+  buildReportBody,
+  buildTitle,
+  createGhIssue,
+  getCapturedTail,
+  installLogCapture,
+  offerBugReport,
+  scrubSecrets,
+  setDeployContext
+} from "./chunk-ADNBLFDP.js";
+import "./chunk-43HLT335.js";
+import "./chunk-MFTODIIT.js";
+import "./chunk-KJH2T5TQ.js";
+export {
+  buildCliFlagsSummary,
+  buildLabels,
+  buildReportBody,
+  buildTitle,
+  createGhIssue,
+  getCapturedTail,
+  installLogCapture,
+  offerBugReport,
+  scrubSecrets,
+  setDeployContext
+};