bulletin-deploy 0.7.12 → 0.7.13-rc.2

package/README.md

@@ -53,21 +53,49 @@ bulletin-deploy <build-dir> <domain.dot>
 Examples:
 
 ```bash
-# Basic deploy
+# Basic deploy (defaults to --env paseo-next)
 bulletin-deploy ./dist my-app00.dot
 
+# Pick a different environment
+bulletin-deploy ./dist my-app00.dot --env paseo-review
+
+# List supported environments
+bulletin-deploy --list-environments
+
+# Refresh the environments cache before deploying
+bulletin-deploy ./dist my-app00.dot --refresh-environments --env paseo-next
+
 # Direct signer deploy
 bulletin-deploy ./dist my-app00.dot --mnemonic "..."
 
-# Custom Bulletin RPC
+# Custom Bulletin RPC override (asset-hub still comes from --env)
 bulletin-deploy ./dist my-app00.dot --rpc wss://custom-bulletin.example.com
 ```
 
+### Selecting an environment
+
+`--env <id>` selects a target environment by id. The list of environments and their RPC endpoints is sourced dynamically from [`paritytech/bulletin-deploy/assets/environments.json`](./assets/environments.json), which mirrors [`paritytech/triangle-status/environments.json`](https://github.com/paritytech/triangle-status/blob/main/environments.json) (the latter is private; bulletin-deploy serves as the public mirror).
+
+| Env id | Network | Bulletin available? |
+|---|---|---|
+| `paseo-next` (default) | testnet | yes |
+| `paseo-review` | testnet | yes |
+| `preview` | testnet | yes |
+| `polkadot` | mainnet | not yet |
+| `kusama` | mainnet | not yet |
+
+A single env id drives both the bulletin RPC and the asset-hub RPC used internally for DotNS, so they cannot drift. When you pass `--rpc`, it overrides only the bulletin endpoint within the chosen env; the asset-hub endpoint still comes from `--env`.
+
+The runtime uses a 24-hour cache at `${XDG_CACHE_HOME:-~/.cache}/bulletin-deploy/environments.json`; `--refresh-environments` busts it and re-fetches. The npm tarball ships a bundled snapshot that is used when the live URL is unreachable.
+
 ### Options
 
 | Flag | What it does |
 |---|---|
-| `--rpc wss://...` | Override the Bulletin RPC endpoint. Also readable from `BULLETIN_RPC`. |
+| `--env <id>` | Target environment. Default: `paseo-next`. See `--list-environments` for valid ids. |
+| `--list-environments` | Print the environments table and exit. |
+| `--refresh-environments` | Bust the cache and re-fetch environments.json. Composes with `--env` (refresh-then-deploy) or runs solo. |
+| `--rpc wss://...` | Override the Bulletin RPC endpoint within the chosen `--env`. Also readable from `BULLETIN_RPC`. |
 | `--mnemonic "..."` | Use a specific mnemonic as the direct signer for Bulletin uploads and DotNS updates. Also readable from `MNEMONIC`. |
 | `--derivation-path "..."` | Apply a Substrate derivation path to `--mnemonic`, for example `//deploy/3`. |
 | `--pool-size N` | Change the number of derived pool accounts available for pool-mode Bulletin uploads. Default: `10`. |
@@ -138,9 +166,11 @@ await deploy("./dist", "my-app00.dot", { jsMerkle: true });
 
 | Variable | Default | Description |
 |---|---|---|
-| `BULLETIN_RPC` | `wss://paseo-bulletin-rpc.polkadot.io` | Bulletin chain WebSocket RPC |
+| `BULLETIN_RPC` | `wss://paseo-bulletin-rpc.polkadot.io` | Override the Bulletin chain WebSocket RPC for the chosen `--env`. |
+| `BULLETIN_ENVIRONMENTS_URL` | bulletin-deploy public mirror | Override the runtime URL for environments.json. Internal teams point this at a fork or local proxy. |
 | `BULLETIN_DEPLOY_TELEMETRY` | off for external users, on for internal users | `1` to opt in, `0` to force off |
 | `BULLETIN_DEPLOY_UPDATE_CHECK` | `1` | Set to `0` to disable version checks on failure |
+| `BULLETIN_DEPLOY_DOTNS_CLI` | bundled `@parity/dotns-cli`, then host dispatch | Set to `host` for `process.execPath dotns ...` dispatch in bundled host CLIs, or to a `dotns` command/path |
 | `DOTNS_STATUS` | `full` on testnet, `none` on mainnet | PoP level to self-grant before registration: `none`, `lite`, or `full` |
 | `IPFS_CID` | unset | Skip storage and reuse an existing CID |
 | `DEPLOY_TAG` | unset | Telemetry label equivalent to `--tag` |

package/assets/environments.json

@@ -0,0 +1,238 @@
+{
+  "environments": [
+    {
+      "id": "preview",
+      "name": "Preview",
+      "network": "testnet",
+      "description": "Product Preview net, used by Product Teams",
+      "backend": "https://polkadot-app-stg.parity.io/",
+      "ipfs": "https://previewnet.substrate.dev/ipfs/"
+    },
+    {
+      "id": "paseo-next",
+      "name": "Paseo Next",
+      "network": "testnet",
+      "badge": "Testflight",
+      "description": "Production testnet for Polkadot App Testflight",
+      "backend": "https://identity-backend.parity-testnet.parity.io",
+      "ipfs": "https://paseo-ipfs.polkadot.io/ipfs",
+      "uptimeUrl": "https://stats.uptimerobot.com/LISM1LRA8m"
+    },
+    {
+      "id": "paseo-review",
+      "name": "Paseo Review",
+      "network": "testnet",
+      "description": "Used for App Store review builds",
+      "backend": "https://identity-backend-review.parity-testnet.parity.io",
+      "ipfs": "https://paseo-bulletin-review-ipfs.polkadot.io",
+      "uptimeUrl": "https://stats.uptimerobot.com/bckl1cu0AO"
+    },
+    {
+      "id": "polkadot",
+      "name": "Polkadot",
+      "network": "mainnet",
+      "description": "Polkadot mainnet"
+    },
+    {
+      "id": "kusama",
+      "name": "Kusama",
+      "network": "mainnet",
+      "description": "Kusama canary network"
+    }
+  ],
+  "chains": [
+    {
+      "id": "relay",
+      "name": "Relay",
+      "endpoints": {
+        "preview": {
+          "wss": "wss://previewnet.substrate.dev/relay/alice"
+        },
+        "paseo-next": {
+          "wss": "wss://paseo-rpc.n.dwellir.com",
+          "uptimeUrl": "https://stats.uptimerobot.com/UrEXbl6Xyt"
+        },
+        "paseo-review": {
+          "wss": "wss://paseo-rpc.n.dwellir.com",
+          "uptimeUrl": "https://stats.uptimerobot.com/UrEXbl6Xyt"
+        },
+        "polkadot": {
+          "wss": [
+            "wss://polkadot-rpc.n.dwellir.com",
+            "wss://polkadot.ibp.network",
+            "wss://polkadot.dotters.network",
+            "wss://rpc.polkadot.io"
+          ]
+        },
+        "kusama": {
+          "wss": [
+            "wss://kusama-rpc.n.dwellir.com",
+            "wss://kusama.ibp.network",
+            "wss://kusama.dotters.network",
+            "wss://kusama-rpc.polkadot.io"
+          ]
+        }
+      }
+    },
+    {
+      "id": "asset-hub",
+      "name": "Asset Hub",
+      "endpoints": {
+        "preview": {
+          "wss": "wss://previewnet.substrate.dev/asset-hub",
+          "parachainId": 1000
+        },
+        "paseo-next": {
+          "wss": "wss://asset-hub-paseo-rpc.n.dwellir.com",
+          "parachainId": 1000,
+          "uptimeUrl": "https://stats.uptimerobot.com/UrEXbl6Xyt"
+        },
+        "paseo-review": {
+          "wss": "wss://asset-hub-paseo-rpc.n.dwellir.com",
+          "parachainId": 1000,
+          "uptimeUrl": "https://stats.uptimerobot.com/UrEXbl6Xyt"
+        },
+        "polkadot": {
+          "wss": [
+            "wss://asset-hub-polkadot-rpc.n.dwellir.com",
+            "wss://asset-hub-polkadot.ibp.network",
+            "wss://asset-hub-polkadot.dotters.network",
+            "wss://polkadot-asset-hub-rpc.polkadot.io"
+          ],
+          "parachainId": 1000
+        },
+        "kusama": {
+          "wss": [
+            "wss://asset-hub-kusama-rpc.n.dwellir.com",
+            "wss://asset-hub-kusama.ibp.network",
+            "wss://asset-hub-kusama.dotters.network",
+            "wss://kusama-asset-hub-rpc.polkadot.io"
+          ],
+          "parachainId": 1000
+        }
+      }
+    },
+    {
+      "id": "bridge-hub",
+      "name": "Bridge Hub",
+      "endpoints": {
+        "polkadot": {
+          "wss": [
+            "wss://bridge-hub-polkadot-rpc.n.dwellir.com",
+            "wss://bridge-hub-polkadot.ibp.network",
+            "wss://bridge-hub-polkadot.dotters.network",
+            "wss://polkadot-bridge-hub-rpc.polkadot.io"
+          ],
+          "parachainId": 1002
+        },
+        "kusama": {
+          "wss": [
+            "wss://bridge-hub-kusama-rpc.n.dwellir.com",
+            "wss://bridge-hub-kusama.ibp.network",
+            "wss://bridge-hub-kusama.dotters.network",
+            "wss://kusama-bridge-hub-rpc.polkadot.io"
+          ],
+          "parachainId": 1002
+        }
+      }
+    },
+    {
+      "id": "collectives",
+      "name": "Collectives",
+      "endpoints": {
+        "polkadot": {
+          "wss": [
+            "wss://collectives-polkadot-rpc.n.dwellir.com",
+            "wss://collectives-polkadot.ibp.network",
+            "wss://collectives-polkadot.dotters.network",
+            "wss://polkadot-collectives-rpc.polkadot.io"
+          ],
+          "parachainId": 1001
+        }
+      }
+    },
+    {
+      "id": "coretime",
+      "name": "Coretime",
+      "endpoints": {
+        "polkadot": {
+          "wss": [
+            "wss://coretime-polkadot-rpc.n.dwellir.com",
+            "wss://coretime-polkadot.ibp.network",
+            "wss://coretime-polkadot.dotters.network",
+            "wss://polkadot-coretime-rpc.polkadot.io"
+          ],
+          "parachainId": 1005
+        },
+        "kusama": {
+          "wss": [
+            "wss://coretime-kusama-rpc.n.dwellir.com",
+            "wss://coretime-kusama.ibp.network",
+            "wss://coretime-kusama.dotters.network",
+            "wss://kusama-coretime-rpc.polkadot.io"
+          ],
+          "parachainId": 1005
+        }
+      }
+    },
+    {
+      "id": "people",
+      "name": "People",
+      "endpoints": {
+        "preview": {
+          "wss": "wss://previewnet.substrate.dev/people",
+          "parachainId": 1004
+        },
+        "paseo-next": {
+          "wss": "wss://paseo-people-next-rpc.polkadot.io",
+          "parachainId": 5140,
+          "uptimeUrl": "https://stats.uptimerobot.com/LISM1LRA8m"
+        },
+        "paseo-review": {
+          "wss": "wss://paseo-people-review-rpc.polkadot.io",
+          "parachainId": 5167,
+          "uptimeUrl": "https://stats.uptimerobot.com/bckl1cu0AO"
+        },
+        "polkadot": {
+          "wss": [
+            "wss://people-polkadot-rpc.n.dwellir.com",
+            "wss://people-polkadot.ibp.network",
+            "wss://people-polkadot.dotters.network",
+            "wss://polkadot-people-rpc.polkadot.io"
+          ],
+          "parachainId": 1004
+        },
+        "kusama": {
+          "wss": [
+            "wss://people-kusama-rpc.n.dwellir.com",
+            "wss://people-kusama.ibp.network",
+            "wss://people-kusama.dotters.network",
+            "wss://kusama-people-rpc.polkadot.io"
+          ],
+          "parachainId": 1004
+        }
+      }
+    },
+    {
+      "id": "bulletin",
+      "name": "Bulletin",
+      "endpoints": {
+        "preview": {
+          "wss": "wss://previewnet.substrate.dev/bulletin",
+          "parachainId": 2487
+        },
+        "paseo-next": {
+          "wss": "wss://paseo-bulletin-rpc.polkadot.io",
+          "parachainId": 5118,
+          "uptimeUrl": "https://stats.uptimerobot.com/LISM1LRA8m"
+        },
+        "paseo-review": {
+          "wss": "wss://paseo-bulletin-review-rpc.polkadot.io",
+          "parachainId": 5168,
+          "uptimeUrl": "https://stats.uptimerobot.com/bckl1cu0AO"
+        }
+      }
+    }
+  ],
+  "source": "https://docs.google.com/document/d/1xQoAmWDpbjhuXKT79DTNKFzv7ZkFr5npjo0BvrxXDIw"
+}

package/bin/bulletin-deploy

@@ -5,6 +5,7 @@ import { VERSION, setDeployAttribute, captureWarning, closeTelemetry, setRunStat
 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 { loadEnvironments, listEnvironments, formatEnvironmentTable, DEFAULT_ENV_ID, DEFAULT_ENVIRONMENTS_URL } from "../dist/environments.js";
 import * as fs from "fs";
 
 // Install early so anything printed during flag parsing / preflight is
@@ -21,6 +22,9 @@ for (let i = 0; i < args.length; i++) {
   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] === "--refresh-environments") { flags.refreshEnvironments = true; }
   else if (args[i] === "--password") { flags.password = args[++i]; }
   else if (args[i] === "--js-merkle") { flags.jsMerkle = true; }
   else if (args[i] === "--tag") { flags.tag = args[++i]; }
@@ -42,6 +46,32 @@ if (flags.removedBootstrap) {
   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);
+  }
+}
+
+// --refresh-environments alone (no positional args): refresh and exit. With
+// positional args, refresh first, then deploy.
+if (flags.refreshEnvironments && positional.length === 0) {
+  try {
+    const { doc } = await loadEnvironments({ forceRefresh: true });
+    console.log(`Refreshed ${doc.environments.length} environments from ${process.env.BULLETIN_ENVIRONMENTS_URL ?? DEFAULT_ENVIRONMENTS_URL}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Error: failed to refresh environments: ${e?.message ?? e}`);
+    process.exit(1);
+  }
+}
+
 if (flags.help || positional.length === 0) {
   console.log(`bulletin-deploy v${VERSION}
 
@@ -49,9 +79,16 @@ Usage:
   bulletin-deploy <build-dir> <domain.dot>  Deploy an app
 
 Options:
+  --env <id>               Target environment from environments.json (default: paseo-next).
+                           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.
+  --refresh-environments   Bust the cache and re-fetch environments.json. Composes
+                           with --env (refresh-then-deploy) or runs solo.
   --mnemonic "..."         DotNS owner mnemonic (or set MNEMONIC env var)
   --derivation-path "..."  Optional Substrate-style path applied to --mnemonic (e.g. //deploy/3)
-  --rpc wss://...          Bulletin RPC (or set BULLETIN_RPC env var)
+  --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)
@@ -159,6 +196,16 @@ try {
   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); }
 
+  // --refresh-environments composed with a deploy: bust the cache before
+  // deploy() loads it, so deploy() picks up fresh data on the next loadEnvironments().
+  if (flags.refreshEnvironments) {
+    try {
+      await loadEnvironments({ forceRefresh: true });
+    } catch (e) {
+      console.error(`Error: failed to refresh environments: ${e?.message ?? e}`);
+      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" ? {
@@ -184,6 +231,7 @@ try {
     mnemonic: flags.mnemonic,
     derivationPath: flags.derivationPath,
     rpc: flags.rpc,
+    env: flags.env,
     poolSize: flags.poolSize,
     password: flags.password,
     jsMerkle: flags.jsMerkle,

package/dist/bug-report.js

@@ -9,10 +9,10 @@ import {
   offerBugReport,
   scrubSecrets,
   setDeployContext
-} from "./chunk-N2OZLFJA.js";
-import "./chunk-RVCY2VEY.js";
-import "./chunk-LOZ5PSD3.js";
-import "./chunk-VQJLGE5J.js";
+} from "./chunk-R6OJVSKS.js";
+import "./chunk-C7TSB3W6.js";
+import "./chunk-QCJSRJRK.js";
+import "./chunk-HA3QKMVJ.js";
 import "./chunk-QGM4M3NI.js";
 export {
   buildCliFlagsSummary,

package/dist/chunk-2VYG7NXN.js

@@ -0,0 +1,266 @@
+import {
+  NonRetryableError
+} from "./chunk-ZOC4GITL.js";
+
+// src/environments.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+import { fileURLToPath } from "url";
+var DEFAULT_ENVIRONMENTS_URL = "https://raw.githubusercontent.com/paritytech/bulletin-deploy/main/assets/environments.json";
+var DEFAULT_ENV_ID = "paseo-next";
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 5e3;
+var HARDCODED_FALLBACK = {
+  environments: [
+    {
+      id: "paseo-next",
+      name: "Paseo Next",
+      network: "testnet",
+      description: "Production testnet for Polkadot App Testflight (hardcoded fallback)"
+    }
+  ],
+  chains: [
+    {
+      id: "bulletin",
+      name: "Bulletin",
+      endpoints: {
+        "paseo-next": {
+          wss: "wss://paseo-bulletin-rpc.polkadot.io",
+          parachainId: 5118
+        }
+      }
+    },
+    {
+      id: "asset-hub",
+      name: "Asset Hub",
+      endpoints: {
+        "paseo-next": {
+          wss: [
+            "wss://asset-hub-paseo.dotters.network",
+            "wss://sys.ibp.network/asset-hub-paseo",
+            "wss://pas-rpc.stakeworld.io/assethub"
+          ],
+          parachainId: 1e3
+        }
+      }
+    }
+  ]
+};
+function defaultCacheDir() {
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), ".cache");
+  return path.join(base, "bulletin-deploy");
+}
+function defaultCachePath() {
+  return path.join(defaultCacheDir(), "environments.json");
+}
+function defaultBundledPath() {
+  return fileURLToPath(new URL("../assets/environments.json", import.meta.url));
+}
+function isValidDoc(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return Array.isArray(v.environments) && Array.isArray(v.chains);
+}
+async function readCache(cachePath) {
+  try {
+    const raw = await fs.readFile(cachePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.fetchedAt === "string" && isValidDoc(parsed.doc)) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function writeCache(cachePath, doc, now) {
+  try {
+    await fs.mkdir(path.dirname(cachePath), { recursive: true });
+    const payload = {
+      fetchedAt: new Date(now).toISOString(),
+      doc
+    };
+    await fs.writeFile(cachePath, JSON.stringify(payload, null, 2), "utf8");
+  } catch {
+  }
+}
+function isFresh(cache, now) {
+  const fetched = Date.parse(cache.fetchedAt);
+  if (Number.isNaN(fetched)) return false;
+  return now - fetched < CACHE_TTL_MS;
+}
+async function fetchLive(url, fetchImpl) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal });
+    if (!res.ok) {
+      throw new Error(`fetch ${url} returned HTTP ${res.status}`);
+    }
+    const json = await res.json();
+    if (!isValidDoc(json)) {
+      throw new Error(`fetch ${url} returned malformed environments doc`);
+    }
+    return json;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function readBundled(bundledPath) {
+  try {
+    const raw = await fs.readFile(bundledPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return isValidDoc(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function loadEnvironments(opts = {}) {
+  const url = opts.url ?? process.env.BULLETIN_ENVIRONMENTS_URL ?? DEFAULT_ENVIRONMENTS_URL;
+  const cachePath = path.join(opts.cacheDir ?? defaultCacheDir(), "environments.json");
+  const bundledPath = opts.bundledPath ?? defaultBundledPath();
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const nowFn = opts.now ?? Date.now;
+  const warn = opts.warn ?? ((msg) => console.error(msg));
+  const capture = opts.capture ?? (() => {
+  });
+  const now = nowFn();
+  if (opts.forceRefresh) {
+    const doc = await fetchLive(url, fetchImpl);
+    await writeCache(cachePath, doc, now);
+    return { doc, source: "live" };
+  }
+  const cache = await readCache(cachePath);
+  if (cache && isFresh(cache, now)) {
+    return { doc: cache.doc, source: "cache-fresh" };
+  }
+  try {
+    const doc = await fetchLive(url, fetchImpl);
+    await writeCache(cachePath, doc, now);
+    return { doc, source: "live" };
+  } catch (err) {
+    if (cache) {
+      warn(
+        `bulletin-deploy: live environments.json fetch failed; using cached copy from ${cache.fetchedAt} (${err.message ?? err})`
+      );
+      return { doc: cache.doc, source: "cache-stale" };
+    }
+    const bundled = await readBundled(bundledPath);
+    if (bundled) {
+      warn(
+        `bulletin-deploy: live environments.json fetch failed and no cache; using bundled snapshot (${err.message ?? err})`
+      );
+      return { doc: bundled, source: "bundled" };
+    }
+    capture(err);
+    warn(
+      `bulletin-deploy: live and bundled environments.json both unavailable; using hardcoded paseo-next fallback`
+    );
+    return { doc: HARDCODED_FALLBACK, source: "hardcoded-fallback" };
+  }
+}
+function normalizeWss(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value.slice() : [value];
+}
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const m = a.length, n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+function suggestEnv(envId, doc) {
+  let best = null;
+  for (const env of doc.environments) {
+    const d = levenshtein(envId.toLowerCase(), env.id.toLowerCase());
+    if (best === null || d < best.dist) best = { id: env.id, dist: d };
+  }
+  if (best && best.dist <= Math.max(2, Math.floor(envId.length / 3))) {
+    return best.id;
+  }
+  return null;
+}
+function resolveEndpoints(doc, envId) {
+  const env = doc.environments.find((e) => e.id === envId);
+  if (!env) {
+    const valid = doc.environments.map((e) => e.id).join(", ");
+    const hint = suggestEnv(envId, doc);
+    const suffix = hint ? ` Did you mean '${hint}'?` : "";
+    throw new NonRetryableError(
+      `Unknown environment '${envId}'. Valid: ${valid}.${suffix}`
+    );
+  }
+  const bulletinChain = doc.chains.find((c) => c.id === "bulletin");
+  const assetHubChain = doc.chains.find((c) => c.id === "asset-hub");
+  const bulletin = normalizeWss(bulletinChain?.endpoints?.[envId]?.wss);
+  const assetHub = normalizeWss(assetHubChain?.endpoints?.[envId]?.wss);
+  if (bulletin.length === 0) {
+    throw new NonRetryableError(
+      `Bulletin chain not yet available on environment '${envId}'. The selected environment has no bulletin endpoint in https://github.com/paritytech/triangle-status/blob/main/environments.json. Pick a testnet (paseo-next, paseo-review, preview) or wait for the mainnet rollout.`
+    );
+  }
+  if (assetHub.length === 0) {
+    throw new NonRetryableError(
+      `Asset Hub endpoint missing for environment '${envId}'. Check https://github.com/paritytech/triangle-status/blob/main/environments.json.`
+    );
+  }
+  return { bulletin, assetHub, network: env.network, envName: env.name };
+}
+function listEnvironments(doc) {
+  const bulletinChain = doc.chains.find((c) => c.id === "bulletin");
+  return doc.environments.map((env) => {
+    const ep = bulletinChain?.endpoints?.[env.id];
+    const hasBulletin = !!ep && normalizeWss(ep.wss).length > 0;
+    return {
+      id: env.id,
+      name: env.name,
+      network: env.network,
+      hasBulletin,
+      description: env.description ?? ""
+    };
+  });
+}
+function formatEnvironmentTable(rows) {
+  const headers = ["ID", "Name", "Network", "Bulletin?", "Description"];
+  const data = rows.map((r) => [
+    r.id,
+    r.name,
+    r.network,
+    r.hasBulletin ? "yes" : "no",
+    r.description
+  ]);
+  const widths = headers.map(
+    (h, i) => Math.max(h.length, ...data.map((row) => row[i].length))
+  );
+  const fmtRow = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  return [fmtRow(headers), sep, ...data.map(fmtRow)].join("\n");
+}
+
+export {
+  DEFAULT_ENVIRONMENTS_URL,
+  DEFAULT_ENV_ID,
+  CACHE_TTL_MS,
+  FETCH_TIMEOUT_MS,
+  defaultCacheDir,
+  defaultCachePath,
+  defaultBundledPath,
+  loadEnvironments,
+  resolveEndpoints,
+  listEnvironments,
+  formatEnvironmentTable
+};