bulletin-deploy 0.6.6 → 0.6.7

package/README.md

@@ -15,7 +15,7 @@ Your site is live at `https://my-app00.dot.li`
 ## Prerequisites
 
 - **Node.js 22+**
-- **IPFS Kubo** (for merkleizing directories)
+- **IPFS Kubo** (for merkleizing directories — not needed with `--js-merkle`)
 
 ```bash
 # macOS
@@ -29,6 +29,8 @@ sudo bash kubo/install.sh
 ipfs init
 ```
 
+> **No Kubo?** Use `--js-merkle` to skip the Kubo requirement entirely. See [Merkleization modes](#merkleization-modes) below.
+
 ## CLI Usage
 
 ```bash
@@ -55,6 +57,7 @@ Options:
   --rpc wss://...     Bulletin RPC (or set BULLETIN_RPC env var)
   --mnemonic "..."    DotNS owner mnemonic (or set MNEMONIC env var)
   --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)
   --help              Show help
 ```
@@ -92,6 +95,20 @@ const result = await deploy("./dist", "my-app00.dot");
 console.log(result.cid, result.domainName);
 ```
 
+### JS merkleization and custom telemetry
+
+For environments without Kubo (WebContainers, serverless), use `jsMerkle`. The optional `attributes` field lets you inject telemetry context when git is unavailable:
+
+```javascript
+const result = await deploy("./dist", "my-app00.dot", {
+  jsMerkle: true,
+  attributes: {
+    "deploy.source": "revx",
+    "deploy.repo": "user/project",
+  },
+});
+```
+
 ## Domain Names and Proof of Personhood
 
 DotNS domain names are classified by the PopOracle contract on Asset Hub. The classification determines what level of **Proof of Personhood (PoP)** is required to register:
@@ -124,18 +141,53 @@ If you see **"Requires Full Personhood verification"**, the deploy will fail ear
 ## How It Works
 
 ```
-Build output ──> IPFS merkleize ──> CAR file ──> Chunk upload ──> DotNS
-    ./dist          ipfs add        .car         Bulletin        Asset Hub
-                                                 Storage         Registry
+Build output ──> Merkleize ──> CAR file ──> Chunk upload ──> DotNS
+    ./dist       (Kubo or JS)   .car         Bulletin        Asset Hub
+                                             Storage         Registry
 ```
 
-1. **Merkleize** your build directory with IPFS to produce a content-addressed CAR file
+1. **Merkleize** your build directory to produce a content-addressed CAR file
 2. **Chunk and upload** the CAR file to Bulletin's TransactionStorage (1MB chunks, 2 per batch)
 3. **Store the DAG root** that links all chunks together under a single CID
 4. **Register or update** your `.dot` domain on Asset Hub with the new contenthash
 
 Your site is immediately accessible at `https://your-domain.dot.li`
 
+## Merkleization modes
+
+bulletin-deploy supports two ways to merkleize your build directory into a CAR file:
+
+| Mode | Flag | Requires | Best for |
+|---|---|---|---|
+| **Kubo** (default) | _(none)_ | IPFS Kubo binary installed | CI pipelines, local development |
+| **JS** | `--js-merkle` | Nothing beyond Node.js | WebContainers, serverless, environments without system binaries |
+
+Both modes produce valid IPFS UnixFS DAGs. The CIDs may differ between modes for the same input (different chunking implementations), but this is fine — each deploy sets a fresh contenthash on DotNS regardless.
+
+### CLI
+
+```bash
+# Default (Kubo)
+bulletin-deploy ./dist my-app00.dot
+
+# JS merkleization
+bulletin-deploy --js-merkle ./dist my-app00.dot
+```
+
+### Programmatic
+
+```javascript
+import { deploy } from "bulletin-deploy";
+
+// Default (Kubo)
+await deploy("./dist", "my-app00.dot");
+
+// JS merkleization
+await deploy("./dist", "my-app00.dot", { jsMerkle: true });
+```
+
+The JS mode uses `ipfs-unixfs-importer` (the same chunker Kubo uses internally) and `@ipld/car` for CAR serialization. It runs entirely in-memory with no temp files.
+
 ## Resilience Features
 
 ### Chunk-level retry
@@ -161,7 +213,9 @@ What's tracked:
 - Pool account selection
 - Source metadata (repo, branch, PR number, CI vs local)
 
-Dashboard: https://polkadot-community-foundation.sentry.io/dashboards/92523/
+Dashboard:
+- Bulletin Deploy Health: https://paritytech.sentry.io/dashboard/1669817/
+- Deploy Failures Detail: https://paritytech.sentry.io/dashboard/1669818/
 
 ## Troubleshooting
 

package/bin/bulletin-deploy

@@ -16,6 +16,7 @@ for (let i = 0; i < args.length; i++) {
   else if (args[i] === "--rpc") { flags.rpc = args[++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] === "--version" || args[i] === "-V") { flags.version = true; }
   else if (args[i] === "--help" || args[i] === "-h") { flags.help = true; }
   else { positional.push(args[i]); }
@@ -39,6 +40,7 @@ Options:
   --pool-size N       Number of pool accounts (default: 10)
   --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)
   --version           Show version
   --help              Show this help`);
   process.exit(0);
@@ -61,6 +63,7 @@ try {
       rpc: flags.rpc,
       poolSize: flags.poolSize,
       password: flags.password,
+      jsMerkle: flags.jsMerkle,
     });
 
     const output = process.env.GITHUB_OUTPUT;

package/dist/{chunk-7FNQBFFQ.js → chunk-FBXG7YMT.js}

@@ -1,7 +1,7 @@
 import {
   captureWarning,
   withSpan
-} from "./chunk-BYYVSN7E.js";
+} from "./chunk-ZGP4DMFK.js";
 
 // src/dotns.ts
 import crypto from "crypto";

package/dist/chunk-GZ5UUECB.js

@@ -0,0 +1,77 @@
+// src/merkle.ts
+import * as fs from "fs";
+import * as path from "path";
+import { importer } from "ipfs-unixfs-importer";
+import { MemoryBlockstore } from "blockstore-core/memory";
+import { CarWriter } from "@ipld/car/writer";
+function walkDirectory(dirPath, prefix = "") {
+  let dirents;
+  try {
+    dirents = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") throw new Error(`Directory not found: ${dirPath}`);
+    if (code === "ENOTDIR") throw new Error(`Not a directory: ${dirPath}`);
+    throw err;
+  }
+  const entries = [];
+  for (const entry of dirents) {
+    const fullPath = path.join(dirPath, entry.name);
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      entries.push(...walkDirectory(fullPath, relativePath));
+    } else if (entry.isFile()) {
+      entries.push({ path: relativePath, content: fs.readFileSync(fullPath) });
+    }
+  }
+  return entries;
+}
+async function collectBytes(iter) {
+  const parts = [];
+  for await (const chunk of iter) {
+    parts.push(chunk);
+  }
+  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+async function merkleizeJS(directoryPath) {
+  console.log(`   Merkleizing (JS): ${directoryPath}`);
+  const files = walkDirectory(directoryPath);
+  const blockstore = new MemoryBlockstore();
+  const source = files.map((file) => ({
+    path: file.path,
+    content: (async function* () {
+      yield file.content;
+    })()
+  }));
+  let rootCid;
+  for await (const entry of importer(source, blockstore, {
+    cidVersion: 1,
+    rawLeaves: true,
+    wrapWithDirectory: true
+  })) {
+    rootCid = entry.cid;
+  }
+  if (!rootCid) {
+    throw new Error("Merkleization produced no root CID");
+  }
+  const { writer, out } = CarWriter.create([rootCid]);
+  const collectPromise = collectBytes(out);
+  for await (const { cid, bytes } of blockstore.getAll()) {
+    await writer.put({ cid, bytes: await collectBytes(bytes) });
+  }
+  await writer.close();
+  const carBytes = await collectPromise;
+  console.log(`   CAR (JS): ${(carBytes.length / 1024 / 1024).toFixed(2)} MB`);
+  return { carBytes, cid: rootCid.toString() };
+}
+
+export {
+  merkleizeJS
+};

package/dist/{chunk-YB4HKYPR.js → chunk-TD73EZ5I.js}

@@ -4,7 +4,10 @@ import {
   TX_TIMEOUT_MS,
   fetchNonce,
   validateDomainLabel
-} from "./chunk-7FNQBFFQ.js";
+} from "./chunk-FBXG7YMT.js";
+import {
+  merkleizeJS
+} from "./chunk-GZ5UUECB.js";
 import {
   derivePoolAccounts,
   ensureAuthorized,
@@ -18,7 +21,7 @@ import {
   setDeployAttribute,
   withDeploySpan,
   withSpan
-} from "./chunk-BYYVSN7E.js";
+} from "./chunk-ZGP4DMFK.js";
 
 // src/deploy.ts
 import { Buffer } from "buffer";
@@ -778,12 +781,23 @@ async function merkleize(directoryPath, outputCarPath) {
   console.log(`   CAR: ${(size / 1024 / 1024).toFixed(2)} MB`);
   return { carPath: outputCarPath, cid };
 }
-async function storeDirectory(directoryPath, provider = {}, password) {
-  const carPath = path.join(path.dirname(directoryPath), `${path.basename(directoryPath)}.car`);
-  const { cid: ipfsCid } = await withSpan("deploy.merkleize", "1a. merkleize", { "deploy.directory": directoryPath }, async () => {
-    return merkleize(directoryPath, carPath);
-  });
-  let carContent = new Uint8Array(fs.readFileSync(carPath));
+async function storeDirectory(directoryPath, provider = {}, password, jsMerkle) {
+  let carContent;
+  let ipfsCid;
+  if (jsMerkle) {
+    const result = await withSpan("deploy.merkleize", "1a. merkleize (js)", { "deploy.directory": directoryPath }, async () => {
+      return merkleizeJS(directoryPath);
+    });
+    carContent = result.carBytes;
+    ipfsCid = result.cid;
+  } else {
+    const carPath = path.join(path.dirname(directoryPath), `${path.basename(directoryPath)}.car`);
+    const { cid } = await withSpan("deploy.merkleize", "1a. merkleize", { "deploy.directory": directoryPath }, async () => {
+      return merkleize(directoryPath, carPath);
+    });
+    ipfsCid = cid;
+    carContent = new Uint8Array(fs.readFileSync(carPath));
+  }
   if (password) {
     console.log(`   Encrypting CAR file...`);
     carContent = await encryptContent(carContent, password);
@@ -867,7 +881,7 @@ Or deploy with the original account, or use a different domain name.`);
             console.log(`
    Mode: Directory`);
             console.log(`   Path: ${contentPath}`);
-            const dirResult = await storeDirectory(contentPath, providerWithReconnect, options.password);
+            const dirResult = await storeDirectory(contentPath, providerWithReconnect, options.password, options.jsMerkle);
             cid = dirResult.storageCid;
             ipfsCid = dirResult.ipfsCid;
           } else {
@@ -907,6 +921,11 @@ Or deploy with the original account, or use a different domain name.`);
         }
       });
       setDeployAttribute("deploy.cid", cid);
+      if (options.attributes) {
+        for (const [key, value] of Object.entries(options.attributes)) {
+          setDeployAttribute(key, value);
+        }
+      }
       console.log("\n" + "=".repeat(60));
       console.log("DotNS");
       console.log("=".repeat(60));

package/dist/{chunk-BYYVSN7E.js → chunk-ZGP4DMFK.js}

@@ -6,7 +6,7 @@ import * as path from "path";
 // package.json
 var package_default = {
   name: "bulletin-deploy",
-  version: "0.6.6",
+  version: "0.6.7",
   private: false,
   repository: {
     type: "git",
@@ -34,12 +34,13 @@ var package_default = {
     "cdm.json"
   ],
   scripts: {
-    build: "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts --format esm --dts --clean --target node22",
+    build: "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts src/merkle.ts --format esm --dts --clean --target node22",
     test: "npm run build && node --test test/test.js",
     benchmark: "npm run build && node benchmark.js"
   },
   dependencies: {
     "@dotdm/cdm": "^0.5.1",
+    "@ipld/car": "^5.4.3",
     "@ipld/dag-pb": "^4.1.3",
     "@noble/hashes": "^1.7.2",
     "@polkadot-api/substrate-bindings": "^0.16.5",
@@ -48,7 +49,9 @@ var package_default = {
     "@polkadot/keyring": "^13.0.0",
     "@polkadot/util-crypto": "^13.0.0",
     "@sentry/node": "^9.14.0",
+    "blockstore-core": "^6.1.3",
     "ipfs-unixfs": "^11.2.0",
+    "ipfs-unixfs-importer": "^16.1.4",
     multiformats: "^13.4.1",
     "polkadot-api": "^1.23.1",
     viem: "^2.30.5"
@@ -172,6 +175,8 @@ function captureWarning(message, context) {
   try {
     Sentry.addBreadcrumb({ level: "warning", message, data: context });
     Sentry.captureMessage(message, { level: "warning", extra: context });
+    const root = Sentry.getRootSpan(Sentry.getActiveSpan());
+    if (root) root.setAttribute("deploy.sad", true);
   } catch {
   }
 }

package/dist/deploy.d.ts

@@ -49,7 +49,7 @@ declare function merkleize(directoryPath: string, outputCarPath: string): Promis
     carPath: string;
     cid: string;
 }>;
-declare function storeDirectory(directoryPath: string, provider?: ExistingProvider, password?: string): Promise<{
+declare function storeDirectory(directoryPath: string, provider?: ExistingProvider, password?: string, jsMerkle?: boolean): Promise<{
     storageCid: string;
     ipfsCid: string;
 }>;
@@ -63,6 +63,10 @@ interface DeployOptions {
     rpc?: string;
     poolSize?: number;
     password?: string;
+    /** Use pure-JS merkleization instead of Kubo CLI. Required for WebContainer environments. */
+    jsMerkle?: boolean;
+    /** Custom telemetry attributes, merged into the deploy span. Overrides auto-detected values. */
+    attributes?: Record<string, string>;
 }
 declare function deploy(content: DeployContent, domainName?: string | null, options?: DeployOptions): Promise<DeployResult>;
 

package/dist/deploy.js

@@ -21,10 +21,11 @@ import {
   storeChunkedContent,
   storeDirectory,
   storeFile
-} from "./chunk-YB4HKYPR.js";
-import "./chunk-7FNQBFFQ.js";
+} from "./chunk-TD73EZ5I.js";
+import "./chunk-FBXG7YMT.js";
+import "./chunk-GZ5UUECB.js";
 import "./chunk-LGPTJYA3.js";
-import "./chunk-BYYVSN7E.js";
+import "./chunk-ZGP4DMFK.js";
 import "./chunk-QGM4M3NI.js";
 export {
   DEFAULT_BULLETIN_RPC,

package/dist/dotns.js

@@ -19,8 +19,8 @@ import {
   sanitizeDomainLabel,
   stripTrailingDigits,
   validateDomainLabel
-} from "./chunk-7FNQBFFQ.js";
-import "./chunk-BYYVSN7E.js";
+} from "./chunk-FBXG7YMT.js";
+import "./chunk-ZGP4DMFK.js";
 import "./chunk-QGM4M3NI.js";
 export {
   CONNECTION_TIMEOUT_MS,

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { DeployContent, DeployOptions, DeployResult, deploy } from './deploy.js';
 export { PoolAccount, PoolAuthorization, bootstrapPool, derivePoolAccounts, ensureAuthorized, fetchPoolAuthorizations, selectAccount } from './pool.js';
 export { DotNS, DotNSConnectOptions, OwnershipResult, PriceValidationResult } from './dotns.js';
+export { MerkleizeResult, merkleizeJS } from './merkle.js';
 import 'multiformats/cid';
 import 'polkadot-api';

package/dist/index.js

@@ -1,9 +1,12 @@
 import {
   deploy
-} from "./chunk-YB4HKYPR.js";
+} from "./chunk-TD73EZ5I.js";
 import {
   DotNS
-} from "./chunk-7FNQBFFQ.js";
+} from "./chunk-FBXG7YMT.js";
+import {
+  merkleizeJS
+} from "./chunk-GZ5UUECB.js";
 import {
   bootstrapPool,
   derivePoolAccounts,
@@ -11,7 +14,7 @@ import {
   fetchPoolAuthorizations,
   selectAccount
 } from "./chunk-LGPTJYA3.js";
-import "./chunk-BYYVSN7E.js";
+import "./chunk-ZGP4DMFK.js";
 import "./chunk-QGM4M3NI.js";
 export {
   DotNS,
@@ -20,5 +23,6 @@ export {
   derivePoolAccounts,
   ensureAuthorized,
   fetchPoolAuthorizations,
+  merkleizeJS,
   selectAccount
 };

package/dist/merkle.d.ts

@@ -0,0 +1,7 @@
+interface MerkleizeResult {
+    carBytes: Uint8Array;
+    cid: string;
+}
+declare function merkleizeJS(directoryPath: string): Promise<MerkleizeResult>;
+
+export { type MerkleizeResult, merkleizeJS };

package/dist/merkle.js

@@ -0,0 +1,7 @@
+import {
+  merkleizeJS
+} from "./chunk-GZ5UUECB.js";
+import "./chunk-QGM4M3NI.js";
+export {
+  merkleizeJS
+};

package/dist/telemetry.js

@@ -8,7 +8,7 @@ import {
   setDeployAttribute,
   withDeploySpan,
   withSpan
-} from "./chunk-BYYVSN7E.js";
+} from "./chunk-ZGP4DMFK.js";
 import "./chunk-QGM4M3NI.js";
 export {
   VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulletin-deploy",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "private": false,
   "repository": {
     "type": "git",
@@ -28,12 +28,13 @@
     "cdm.json"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts --format esm --dts --clean --target node22",
+    "build": "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts src/merkle.ts --format esm --dts --clean --target node22",
     "test": "npm run build && node --test test/test.js",
     "benchmark": "npm run build && node benchmark.js"
   },
   "dependencies": {
     "@dotdm/cdm": "^0.5.1",
+    "@ipld/car": "^5.4.3",
     "@ipld/dag-pb": "^4.1.3",
     "@noble/hashes": "^1.7.2",
     "@polkadot-api/substrate-bindings": "^0.16.5",
@@ -42,7 +43,9 @@
     "@polkadot/keyring": "^13.0.0",
     "@polkadot/util-crypto": "^13.0.0",
     "@sentry/node": "^9.14.0",
+    "blockstore-core": "^6.1.3",
     "ipfs-unixfs": "^11.2.0",
+    "ipfs-unixfs-importer": "^16.1.4",
     "multiformats": "^13.4.1",
     "polkadot-api": "^1.23.1",
     "viem": "^2.30.5"