bulletin-deploy 0.6.9 → 0.6.10

package/README.md

@@ -66,6 +66,10 @@ Options:
   --playground             Publish to the Playground remix registry
   --js-merkle              Use pure-JS merkleization (no IPFS Kubo binary required)
   --pool-size N            Number of pool accounts (default: 10)
+  --tag "..."              Free-form label attached to the deploy span as deploy.tag
+                           (see Telemetry section). Use to isolate test/benchmark/canary
+                           runs from real-user traffic in Sentry dashboards. Also readable
+                           from DEPLOY_TAG env var.
   --help                   Show help
 ```
 
@@ -247,9 +251,97 @@ What's tracked:
 - Source metadata (repo, branch, PR number, CI vs local)
 - Tool version (`deploy.tool_version`)
 
-Dashboard:
-- Bulletin Deploy Health: https://paritytech.sentry.io/dashboard/1669817/?project=4511093597405264
-- Deploy Failures Detail: https://paritytech.sentry.io/dashboard/1669818/?project=4511093597405264
+### 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:
+
+```bash
+bulletin-deploy --tag e2e-ci-pr ./build my-app.dot
+DEPLOY_TAG=load-test bulletin-deploy ./build my-app.dot
+```
+
+The `tag` value is attached to the deploy span as `deploy.tag` (plus propagated through every child span).
+
+Convention used in this repo:
+- `e2e-ci-pr` / `e2e-ci-nightly` — CI-driven E2E runs (per-PR and nightly matrices).
+- `e2e-local-smoke` / `e2e-local-pr` / `e2e-local-nightly` — maintainer-invoked E2E via `scripts/e2e-pass.sh`.
+- Untagged — real-user deploys.
+
+Sentry filter examples:
+- Exclude all test traffic from a dashboard: `!has:deploy.tag`
+- Only CI E2E: `deploy.tag:e2e-ci-*`
+- Only nightly runs (local or CI): `deploy.tag:e2e-ci-nightly OR deploy.tag:e2e-local-nightly`
+
+The shipped reusable workflow (`.github/workflows/deploy.yml`) exposes a `tag` input that feeds through to the CLI — pass it from caller workflows that do non-production deploys.
+
+Dashboards:
+- **Bulletin Deploy Health**: https://paritytech.sentry.io/dashboard/1669817/?project=4511093597405264 — overall deploy health across all consumer repos
+- **Deploy Failures Detail**: https://paritytech.sentry.io/dashboard/1669818/?project=4511093597405264 — error drill-down
+- **E2E Health (bulletin-deploy)**: https://paritytech.sentry.io/dashboard/1732713/?project=4511093597405264 — E2E suite pass rate, duration, and per-signer failure distribution (filtered by `deploy.tag:e2e-*`)
+
+## Testing
+
+Three layers of coverage: offline unit tests for pure helpers, live-testnet end-to-end tests that exercise the shipped reusable workflow, and CI matrices that run both per-PR and nightly.
+
+### Offline unit tests
+
+```bash
+npm test
+```
+
+Runs `test/test.js` + `test/pool.test.js` + `test/helpers/e2e-helpers.test.js` via `node --test`. No network. ~5 seconds. Always runs on every PR via GitHub Actions.
+
+### Live-testnet E2E
+
+Three scenarios land on Paseo Bulletin:
+
+- **S1** — happy path on a stable label (`e2epool.dot` / `e2edirect.dot`)
+- **S2** — fresh registration via commit-reveal (nightly only)
+- **S3** — deploy to `e2eowned.dot` (owned by a different account), expects `EXIT_CODE_NO_RETRY` (78) and the "owned by a different account" error message
+
+**Prerequisites** (one-time per testnet lifetime): see [`docs/e2e-bootstrap.md`](docs/e2e-bootstrap.md). Grants Alice PoP Full, funds+maps Bob, pre-registers `e2eowned.dot` to Bob via `dotns-cli`.
+
+**Local launchers:**
+
+```bash
+npm run test:e2e:smoke      # 1 scenario  (S1 pool/js)           ~5 min
+npm run test:e2e:pr         # 3 scenarios (matches per-PR CI)    ~15 min
+npm run test:e2e:nightly    # 7 scenarios (matches nightly CI)   ~30–45 min
+```
+
+All three run through to completion even if one fails; a colored summary prints at the end with per-scenario pass/fail, timing, JUnit report paths, and a pre-filtered Sentry trace link.
+
+**Agent-friendly / quiet mode** — `E2E_QUIET=1` suppresses the live streaming output (`node:test` spec reporter + bulletin-deploy stdio + build logs) while still printing the summary and writing structured reports. Works with every mode:
+
+```bash
+E2E_QUIET=1 npm run test:e2e:smoke
+E2E_QUIET=1 npm run test:e2e:pr
+E2E_QUIET=1 npm run test:e2e:nightly
+```
+
+Equivalent flag form: `bash scripts/e2e-pass.sh --quiet <mode>`.
+
+**JUnit reports** — every scenario writes one to `e2e-reports/<scenario>-<signer>-<merkle>.xml` regardless of quiet mode. Consume via any JUnit-compatible tool, or just `cat` the XML — `<failure>` blocks carry the assertion message and stack.
+
+### CI matrices (`.github/workflows/e2e.yml`)
+
+The CI workflow **calls the shipped reusable `.github/workflows/deploy.yml`** for every scenario — so each E2E job runs exactly the code path real consumers hit. Per-PR tests HEAD via `bulletin-deploy-version: "git+https://...#<sha>"` (the `prepare` npm script builds `dist/` during install). Nightly leaves the version empty so it tests the latest published release.
+
+- **Per-PR** (3 jobs): on `pull_request` and `push` to `main`. S1 pool/js + S1 direct/kubo + S3 negative. Posts a sticky comment on the PR with results and updates in place on re-runs.
+- **Nightly** (11 jobs): scheduled `0 3 * * *` UTC. Full S1 signer×merkle×runner cube + S2 pool/direct fresh-registration + S3. Failures auto-open a GitHub issue.
+
+Every deploy job passes `tag: e2e-ci-pr` or `tag: e2e-ci-nightly` through to the CLI, so the E2E traffic is tagged in Sentry and can be filtered out of real-user dashboards (see Telemetry → Tagging test and benchmark runs above).
+
+### Tag convention in this repo
+
+| Trigger | `deploy.tag` |
+|---|---|
+| `npm run test:e2e:smoke` | `e2e-local-smoke` |
+| `npm run test:e2e:pr` | `e2e-local-pr` |
+| `npm run test:e2e:nightly` | `e2e-local-nightly` |
+| E2E workflow per-PR | `e2e-ci-pr` |
+| E2E workflow nightly | `e2e-ci-nightly` |
+| Real-user deploys | _none_ (`!has:deploy.tag`) |
 
 ## Troubleshooting
 

package/bin/bulletin-deploy

@@ -20,6 +20,7 @@ for (let i = 0; i < args.length; i++) {
   else if (args[i] === "--password") { flags.password = args[++i]; }
   else if (args[i] === "--playground") { flags.playground = true; }
   else if (args[i] === "--js-merkle") { flags.jsMerkle = true; }
+  else if (args[i] === "--tag") { flags.tag = args[++i]; }
   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]); }
@@ -45,6 +46,7 @@ Options:
   --password "..."    Encrypt SPA content (users will be prompted to decrypt)
   --playground        Publish to the playground remix registry
   --js-merkle         Use pure-JS merkleization (no IPFS Kubo binary required)
+  --tag "..."         Label deploy in telemetry (or set DEPLOY_TAG env var); see Telemetry in README
   --version           Show version
   --help              Show this help`);
   process.exit(0);
@@ -80,6 +82,7 @@ try {
       poolSize: flags.poolSize,
       password: flags.password,
       jsMerkle: flags.jsMerkle,
+      tag: flags.tag,
     });
 
     const output = process.env.GITHUB_OUTPUT;

package/dist/bug-report.js

@@ -2,10 +2,10 @@ import {
   classifyErrorArea,
   isInteractive,
   promptYesNo
-} from "./chunk-TF4MTBZF.js";
+} from "./chunk-PRT3B52H.js";
 import {
   VERSION
-} from "./chunk-BUAELY3G.js";
+} from "./chunk-2FXONN6K.js";
 import "./chunk-QGM4M3NI.js";
 
 // src/bug-report.ts

package/dist/{chunk-BUAELY3G.js → chunk-2FXONN6K.js}

@@ -7,7 +7,7 @@ import * as path from "path";
 // package.json
 var package_default = {
   name: "bulletin-deploy",
-  version: "0.6.9",
+  version: "0.6.10",
   private: false,
   repository: {
     type: "git",
@@ -36,7 +36,12 @@ var package_default = {
   ],
   scripts: {
     build: "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts src/merkle.ts src/version-check.ts src/bug-report.ts --format esm --dts --clean --target node22",
-    test: "npm run build && node --test test/test.js",
+    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: {

package/dist/{chunk-INDAKTSG.js → chunk-6QG2QJV4.js}

@@ -5,7 +5,7 @@ import {
   fetchNonce,
   popStatusName,
   validateDomainLabel
-} from "./chunk-CE67XAQY.js";
+} from "./chunk-H4HN4RRK.js";
 import {
   merkleizeJS
 } from "./chunk-GZ5UUECB.js";
@@ -27,7 +27,7 @@ import {
   truncateAddress,
   withDeploySpan,
   withSpan
-} from "./chunk-BUAELY3G.js";
+} from "./chunk-2FXONN6K.js";
 
 // src/deploy.ts
 import { Buffer } from "buffer";
@@ -884,12 +884,15 @@ async function deploy(content, domainName = null, options = {}) {
   const rawName = domainName ? domainName.replace(".dot", "") : `test-domain-${Date.now().toString(36)}${randomSuffix}`;
   const name = validateDomainLabel(rawName);
   return withDeploySpan(name, async () => {
+    const deployTag = options.tag ?? process.env.DEPLOY_TAG;
+    if (deployTag) setDeployAttribute("deploy.tag", deployTag);
     let cid;
     let ipfsCid;
     console.log("\n" + "=".repeat(60));
     console.log(`DEPLOYING TO TESTNET                    v${VERSION}`);
     console.log("=".repeat(60));
     console.log(`   Domain: ${name}.dot`);
+    if (deployTag) console.log(`   Tag: ${deployTag}`);
     if (typeof content === "string") console.log(`   Build dir: ${path.resolve(content)}`);
     if (process.env.CI) console.log(`   Runner: ${resolveRunner()} (${resolveRunnerType()})`);
     if (options.password) console.log(`   Encrypted: yes`);

package/dist/{chunk-CE67XAQY.js → chunk-H4HN4RRK.js}

@@ -4,7 +4,7 @@ import {
 import {
   captureWarning,
   withSpan
-} from "./chunk-BUAELY3G.js";
+} from "./chunk-2FXONN6K.js";
 
 // src/dotns.ts
 import crypto from "crypto";

package/dist/{chunk-TF4MTBZF.js → chunk-PRT3B52H.js}

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

package/dist/deploy.d.ts

@@ -68,6 +68,12 @@ interface DeployOptions {
     password?: string;
     /** Use pure-JS merkleization instead of Kubo CLI. Required for WebContainer environments. */
     jsMerkle?: boolean;
+    /**
+     * Free-form label attached to the deploy span as `deploy.tag`. Used to separate
+     * test/benchmark/canary runs from real-user traffic in Sentry dashboards
+     * (e.g. "e2e-ci-pr", "load-test-a"). Falls back to DEPLOY_TAG env var.
+     */
+    tag?: string;
     /** Custom telemetry attributes, merged into the deploy span. Overrides auto-detected values. */
     attributes?: Record<string, string>;
 }

package/dist/deploy.js

@@ -23,11 +23,11 @@ import {
   storeChunkedContent,
   storeDirectory,
   storeFile
-} from "./chunk-INDAKTSG.js";
-import "./chunk-CE67XAQY.js";
+} from "./chunk-6QG2QJV4.js";
+import "./chunk-H4HN4RRK.js";
 import "./chunk-GZ5UUECB.js";
 import "./chunk-JHNW2EKY.js";
-import "./chunk-BUAELY3G.js";
+import "./chunk-2FXONN6K.js";
 import "./chunk-QGM4M3NI.js";
 export {
   DEFAULT_BULLETIN_RPC,

package/dist/dotns.js

@@ -24,9 +24,9 @@ import {
   simulateUserStatus,
   stripTrailingDigits,
   validateDomainLabel
-} from "./chunk-CE67XAQY.js";
+} from "./chunk-H4HN4RRK.js";
 import "./chunk-JHNW2EKY.js";
-import "./chunk-BUAELY3G.js";
+import "./chunk-2FXONN6K.js";
 import "./chunk-QGM4M3NI.js";
 export {
   CONNECTION_TIMEOUT_MS,

package/dist/index.js

@@ -1,9 +1,9 @@
 import {
   deploy
-} from "./chunk-INDAKTSG.js";
+} from "./chunk-6QG2QJV4.js";
 import {
   DotNS
-} from "./chunk-CE67XAQY.js";
+} from "./chunk-H4HN4RRK.js";
 import {
   merkleizeJS
 } from "./chunk-GZ5UUECB.js";
@@ -14,7 +14,7 @@ import {
   fetchPoolAuthorizations,
   selectAccount
 } from "./chunk-JHNW2EKY.js";
-import "./chunk-BUAELY3G.js";
+import "./chunk-2FXONN6K.js";
 import "./chunk-QGM4M3NI.js";
 export {
   DotNS,

package/dist/telemetry.js

@@ -17,7 +17,7 @@ import {
   truncateAddress,
   withDeploySpan,
   withSpan
-} from "./chunk-BUAELY3G.js";
+} from "./chunk-2FXONN6K.js";
 import "./chunk-QGM4M3NI.js";
 export {
   VERSION,

package/dist/version-check.js

@@ -8,8 +8,8 @@ import {
   isPreReleaseVersion,
   preReleaseWarning,
   promptYesNo
-} from "./chunk-TF4MTBZF.js";
-import "./chunk-BUAELY3G.js";
+} from "./chunk-PRT3B52H.js";
+import "./chunk-2FXONN6K.js";
 import "./chunk-QGM4M3NI.js";
 export {
   assessVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulletin-deploy",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "private": false,
   "repository": {
     "type": "git",
@@ -29,7 +29,12 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts src/merkle.ts src/version-check.ts src/bug-report.ts --format esm --dts --clean --target node22",
-    "test": "npm run build && node --test test/test.js",
+    "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": {