bulletin-deploy 0.5.1 → 0.6.0-rc.1

package/README.md

@@ -6,11 +6,17 @@ Deploy static sites and apps to the Polkadot Triangle network with decentralized
 
 ```bash
 npm install -g bulletin-deploy
-# Build your app (e.g. npm run build)
-bulletin-deploy ./dist my-app00.dot
+bulletin-deploy my-app00.dot
 ```
 
-Your site is live at `https://my-app00.dot.li`
+bulletin-deploy auto-detects your framework, runs the build, and deploys. Your site is live at `https://my-app00.dot.li`
+
+You can also deploy a pre-built directory:
+
+```bash
+npm run build
+bulletin-deploy ./dist my-app00.dot
+```
 
 ## Prerequisites
 
@@ -32,35 +38,58 @@ ipfs init
 ## CLI Usage
 
 ```bash
-bulletin-deploy <build-dir> <domain.dot>
+bulletin-deploy <domain.dot>              # Auto-detect, build, deploy
+bulletin-deploy <build-dir> <domain.dot>  # Deploy pre-built directory
+bulletin-deploy --build-only              # Build only, print output dir
+bulletin-deploy --dry-run <domain.dot>    # Show upload plan without deploying
 ```
 
-Examples:
+### Options
 
-```bash
-# Basic deploy
-bulletin-deploy ./dist my-app00.dot
-
-# Custom RPC endpoint
-bulletin-deploy --rpc wss://custom-bulletin.example.com ./dist my-app00.dot
+```
+Build:
+  --build-cmd "..."    Override detected build command
+  --build-dir ./out    Override detected output directory
+  --no-build           Skip build (require build dir as first arg)
+  --build-only         Build only, print output dir to stdout
+  --dry-run            Show what would be uploaded without deploying
+  --print-cache-paths  Print detected cache paths for CI caching
+
+Deploy:
+  --rpc wss://...      Bulletin RPC (or set BULLETIN_RPC env var)
+  --help               Show help
 ```
 
-### All options
+### Build detection order
 
-```
-Options:
-  --rpc wss://...     Bulletin RPC (or set BULLETIN_RPC env var)
-  --help              Show help
-```
+bulletin-deploy auto-detects your project setup:
+
+1. **Package manager**: `pnpm-lock.yaml` → pnpm, `bun.lockb`/`bun.lock` → bun, `yarn.lock` → yarn, `package-lock.json` → npm
+2. **Build command**: `Makefile` with `build` target → `make build`, otherwise `package.json` `build` script → `<pm> run build`
+3. **Output directory**: framework config (`vite.config.*` → `dist/`, `next.config.*` → `out/`), or probes `dist/`, `out/`, `build/`
+
+### Exit codes
+
+| Code | Meaning | Retryable |
+|------|---------|-----------|
+| 0 | Success | — |
+| 1 | Deploy failure (transient) | Yes |
+| 2 | Build failure | No |
+| 3 | Configuration error | No |
 
 ## GitHub Actions
 
 1. Copy `workflows/deploy-on-pr.yml` to your repo's `.github/workflows/` directory
-2. Customize the **Build** step for your framework (Vite, Next.js, etc.)
-3. Push and watch the deploy
+2. Add your `DOTNS_MNEMONIC` secret in repo settings
+3. Push and watch the deploy — no other configuration needed
 
 The template workflow:
-- Deploys on push to main and on PRs
+- Deploys on push to main and on PRs, with `workflow_dispatch` support
+- Auto-detects your framework, package manager, and build output directory
+- Uses three cache layers to speed up repeat deploys:
+  - **Node modules cache** via `actions/setup-node` with `cache: 'npm'`
+  - **Build artifacts cache** keyed on lockfile hash (paths detected by `--print-cache-paths`)
+  - **Deploy manifest cache** (`.bulletin-deploy-cache`) keyed on branch + SHA for incremental uploads
 - Uses `nick-fields/retry@v3` for automatic retries on transient failures
 - Posts a comment on PRs with the live URL
 - Generates domain names as `<repo>-<branch>00.dot`
@@ -85,9 +114,9 @@ console.log(result.cid, result.domainName);
 ## How It Works
 
 ```
-Build output ──> IPFS merkleize ──> CAR file ──> Chunk upload ──> DotNS
-    ./dist          ipfs add        .car         Bulletin        Asset Hub
-                                                 Storage         Registry
+Source ──> Build ──> Build output ──> IPFS merkleize ──> Classify ──> Upload delta ──> DotNS ──> Registry
+  code     auto       ./dist          ipfs add          manifest      Bulletin        Asset Hub   CDM
+           detect                                       compare       Storage         Registry
 ```
 
 1. **Merkleize** your build directory with IPFS to produce a content-addressed CAR file
@@ -111,6 +140,16 @@ Instead of using a single account for all storage transactions, bulletin-deploy
 
 When a pool account's authorization drops below thresholds (50 transactions or 50MB), bulletin-deploy automatically tops it up by submitting an `authorize_account` transaction from Alice.
 
+## Incremental Upload
+
+On repeat deploys, bulletin-deploy only uploads content that changed. A deploy manifest (`.bulletin-deploy-cache`) tracks which files and chunks are already on-chain.
+
+- **First deploy**: uploads everything, writes the manifest
+- **Subsequent deploys**: compares file CIDs against the manifest, uploads only new/changed files
+- **Typical savings**: 80-95% reduction in upload size and transactions
+
+Use `--dry-run` to preview what would be uploaded before deploying.
+
 ## Telemetry
 
 Sentry telemetry is enabled by default for deploy observability. Set `BULLETIN_DEPLOY_TELEMETRY=0` to disable.

package/bin/bulletin-deploy

@@ -1,28 +1,48 @@
 #!/usr/bin/env node
 
-import { deploy } from "../src/deploy.js";
-import { bootstrapPool } from "../src/pool.js";
+// build.js and manifest.js are lightweight (no @dotdm/cdm dependency),
+// so we can import them eagerly. deploy.js and pool.js are loaded lazily
+// so that --help and --print-cache-paths work without @dotdm/cdm installed.
+import { detectFramework, detectCachePaths } from "../dist/build.js";
 import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
 
 const args = process.argv.slice(2);
 
 const flags = {};
 const positional = [];
 for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--bootstrap") { flags.bootstrap = 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] === "--rpc") { flags.rpc = args[++i]; }
-  else if (args[i] === "--help" || args[i] === "-h") { flags.help = true; }
-  else { positional.push(args[i]); }
+  const arg = args[i];
+  if (arg === "--bootstrap")            { flags.bootstrap = true; }
+  else if (arg === "--pool-size")       { flags.poolSize = parseInt(args[++i], 10); }
+  else if (arg === "--mnemonic")        { flags.mnemonic = args[++i]; }
+  else if (arg === "--rpc")             { flags.rpc = args[++i]; }
+  else if (arg === "--build-cmd")       { flags.buildCmd = args[++i]; }
+  else if (arg === "--build-dir")       { flags.buildDir = args[++i]; }
+  else if (arg === "--no-build")        { flags.noBuild = true; }
+  else if (arg === "--build-only")      { flags.buildOnly = true; }
+  else if (arg === "--print-cache-paths") { flags.printCachePaths = true; }
+  else if (arg === "--dry-run")         { flags.dryRun = true; }
+  else if (arg === "--registry")        { flags.registry = true; }
+  else if (arg === "--help" || arg === "-h") { flags.help = true; }
+  else { positional.push(arg); }
 }
 
-if (flags.help || (positional.length === 0 && !flags.bootstrap)) {
+if (flags.help || (positional.length === 0 && !flags.bootstrap && !flags.printCachePaths && !flags.buildOnly)) {
   console.log(`Usage:
-  bulletin-deploy <build-dir> <domain.dot>  Deploy an app
+  bulletin-deploy <domain.dot>              Auto-build and deploy
+  bulletin-deploy <build-dir> <domain.dot>  Deploy a pre-built directory
   bulletin-deploy --bootstrap               Initialize pool accounts
 
 Options:
+  --build-cmd "..."   Override build command
+  --build-dir ./out   Override output directory
+  --no-build          Skip the build step (use positional arg as build dir)
+  --build-only        Build only, print output dir to stdout, then exit
+  --print-cache-paths Print detected cache paths and exit
+  --dry-run           Show upload plan without deploying
+  --registry          Publish to playground registry (only needed on metadata change)
   --mnemonic "..."    DotNS owner mnemonic (or set MNEMONIC env var)
   --rpc wss://...     Bulletin RPC (or set BULLETIN_RPC env var)
   --pool-size N       Number of pool accounts (default: 10)
@@ -30,33 +50,161 @@ Options:
   process.exit(0);
 }
 
-if (flags.rpc) process.env.BULLETIN_RPC = flags.rpc;
+if (flags.rpc)      process.env.BULLETIN_RPC = flags.rpc;
 if (flags.poolSize) process.env.BULLETIN_POOL_SIZE = String(flags.poolSize);
+if (flags.mnemonic) process.env.MNEMONIC = flags.mnemonic;
+
+const projectDir = process.cwd();
+
+// --print-cache-paths: detect and print, then exit (no heavy deps needed)
+if (flags.printCachePaths) {
+  const framework = detectFramework(projectDir);
+  const cachePaths = detectCachePaths(framework);
+  for (const p of cachePaths) {
+    console.log(p);
+  }
+  process.exit(0);
+}
+
+// Lazy-load heavy modules that require @dotdm/cdm; run in parallel
+const [
+  { deploy, merkleize, chunk, measureBuildOutput },
+  { runBuild },
+  { readManifest, classifyWithManifest, classifyFile, formatDryRunReport },
+  { bootstrapPool },
+] = await Promise.all([
+  import("../dist/deploy.js"),
+  import("../dist/build.js"),
+  import("../dist/manifest.js"),
+  import("../dist/pool.js"),
+]);
 
 try {
   if (flags.bootstrap) {
     const rpc = process.env.BULLETIN_RPC || "wss://paseo-bulletin-rpc.polkadot.io";
     const poolSize = parseInt(process.env.BULLETIN_POOL_SIZE || "10", 10);
     await bootstrapPool(rpc, poolSize);
+    process.exit(0);
+  }
+
+  // --build-only: run build, print output dir, exit
+  if (flags.buildOnly) {
+    const result = await runBuild(projectDir, {
+      buildCmd: flags.buildCmd,
+      buildDir: flags.buildDir,
+    });
+    console.log(path.resolve(projectDir, result.outputDir));
+    process.exit(0);
+  }
+
+  // Determine build dir and domain from positional args
+  let buildDir;
+  let domain;
+
+  const [firstArg, secondArg] = positional;
+
+  if (firstArg && fs.existsSync(firstArg)) {
+    // Backward-compat: first arg is an existing path — treat as build dir
+    buildDir = firstArg;
+    domain = secondArg;
   } else {
-    const [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); }
+    domain = firstArg;
+    buildDir = null;
+  }
+
+  if (!domain) {
+    console.error("Error: domain required (e.g. my-app.dot)");
+    process.exit(3);
+  }
+
+  // Build step (unless --no-build or buildDir already provided from positional)
+  if (!buildDir && !flags.noBuild) {
+    console.log("\nBuilding...");
+    const buildResult = await runBuild(projectDir, {
+      buildCmd: flags.buildCmd,
+      buildDir: flags.buildDir,
+    });
+    buildDir = path.resolve(projectDir, buildResult.outputDir);
+    console.log(`  Output: ${buildDir} (${buildResult.durationMs}ms)`);
+  } else if (flags.noBuild && !buildDir) {
+    if (flags.buildDir) {
+      buildDir = flags.buildDir;
+    } else {
+      console.error("Error: --no-build requires a build directory (pass as first arg or --build-dir)");
+      process.exit(3);
+    }
+  }
+
+  if (!fs.existsSync(buildDir)) {
+    console.error(`Error: build directory not found: ${buildDir}`);
+    process.exit(3);
+  }
+
+  // --dry-run: show upload plan without deploying
+  if (flags.dryRun) {
+    const tmpDir = os.tmpdir();
+    const carPath = path.join(tmpDir, `bulletin-dry-run-${Date.now()}.car`);
+
+    try {
+      const { cid } = await merkleize(buildDir, carPath);
+
+      const outputInfo = measureBuildOutput(buildDir);
+      const currentFiles = outputInfo.files.map(f => ({ path: f.path, cid: `${cid}:${f.path}`, size: f.size }));
+
+      const manifestPath = path.join(projectDir, ".bulletin-manifest.json");
+      const manifest = readManifest(manifestPath);
 
-    const result = await deploy(buildDir, domain);
+      let classification;
+      if (manifest) {
+        classification = classifyWithManifest(currentFiles, manifest);
+      } else {
+        const stable = currentFiles.filter(f => classifyFile(f.path) === "stable");
+        const volatile = currentFiles
+          .filter(f => classifyFile(f.path) === "volatile")
+          .map(f => ({ ...f, previousCid: null }));
+        classification = { stable, volatile, hitRate: stable.length / (currentFiles.length || 1), source: "heuristic" };
+      }
 
-    const output = process.env.GITHUB_OUTPUT;
-    if (output) {
-      fs.appendFileSync(output, `cid=${result.cid}\n`);
-      fs.appendFileSync(output, `domain=${result.domainName}\n`);
+      const carBuffer = fs.readFileSync(carPath);
+      const carChunks = chunk(carBuffer);
+      const totalChunks = carChunks.length;
+      const newChunks = classification.volatile.length > 0 ? carChunks.length : 0;
+
+      const meta = {
+        manifestPath: manifest ? manifestPath : null,
+        lastDeploy: manifest ? manifest.deployed_at : null,
+        totalChunks,
+        newChunks,
+      };
+
+      const report = formatDryRunReport(classification, meta);
+      console.log(report);
+    } finally {
+      try { fs.unlinkSync(carPath); } catch { /* ignore */ }
     }
+    process.exit(0);
+  }
+
+  const result = await deploy(buildDir, domain, { registry: flags.registry ?? false });
 
-    console.log(`CID: ${result.cid}`);
-    console.log(`Domain: ${result.domainName}`);
+  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}`);
   process.exit(0);
+
 } catch (error) {
-  console.error("Deployment failed:", error.message);
-  process.exit(1);
+  const exitCode = error.exitCode ?? 1;
+  if (exitCode === 2) {
+    console.error("Build failed:", error.message);
+  } else if (exitCode === 3) {
+    console.error("Config error:", error.message);
+  } else {
+    console.error("Deployment failed:", error.message);
+  }
+  process.exit(exitCode);
 }

package/cdm.json

@@ -0,0 +1,118 @@
+{
+  "targets": {
+    "acc2c3b5e912b762": {
+      "asset-hub": "wss://asset-hub-paseo-rpc.n.dwellir.com",
+      "bulletin": "https://paseo-ipfs.polkadot.io/ipfs"
+    }
+  },
+  "dependencies": {
+    "acc2c3b5e912b762": {
+      "@example/playground-registry": "latest"
+    }
+  },
+  "contracts": {
+    "acc2c3b5e912b762": {
+      "@example/playground-registry": {
+        "version": 2,
+        "address": "0x7D97a3E87c0C2fe921E471D076b95975886CEAA8",
+        "abi": [
+          {
+            "type": "constructor",
+            "inputs": [],
+            "stateMutability": "nonpayable"
+          },
+          {
+            "type": "function",
+            "name": "publish",
+            "inputs": [
+              {
+                "name": "domain",
+                "type": "string"
+              },
+              {
+                "name": "metadata_uri",
+                "type": "string"
+              }
+            ],
+            "outputs": [],
+            "stateMutability": "nonpayable"
+          },
+          {
+            "type": "function",
+            "name": "getMetadataUri",
+            "inputs": [
+              {
+                "name": "domain",
+                "type": "string"
+              }
+            ],
+            "outputs": [
+              {
+                "name": "",
+                "type": "tuple",
+                "components": [
+                  {
+                    "name": "isSome",
+                    "type": "bool"
+                  },
+                  {
+                    "name": "value",
+                    "type": "string"
+                  }
+                ]
+              }
+            ],
+            "stateMutability": "view"
+          },
+          {
+            "type": "function",
+            "name": "getDomainAt",
+            "inputs": [
+              {
+                "name": "index",
+                "type": "uint32"
+              }
+            ],
+            "outputs": [
+              {
+                "name": "",
+                "type": "string"
+              }
+            ],
+            "stateMutability": "view"
+          },
+          {
+            "type": "function",
+            "name": "getOwner",
+            "inputs": [
+              {
+                "name": "domain",
+                "type": "string"
+              }
+            ],
+            "outputs": [
+              {
+                "name": "",
+                "type": "address"
+              }
+            ],
+            "stateMutability": "view"
+          },
+          {
+            "type": "function",
+            "name": "getAppCount",
+            "inputs": [],
+            "outputs": [
+              {
+                "name": "",
+                "type": "uint32"
+              }
+            ],
+            "stateMutability": "view"
+          }
+        ],
+        "metadataCid": "bafk2bzacecrjrmrgumcww7oc23rllfscbxpd2lxc6p2svb26c6e5tjvmr565s"
+      }
+    }
+  }
+}

package/dist/build.js

@@ -0,0 +1,25 @@
+import {
+  BuildError,
+  ConfigError,
+  detectBuildCommand,
+  detectCachePaths,
+  detectFramework,
+  detectPackageManager,
+  probeOutputDir,
+  runBuild,
+  scanMakefilesForOutputDir,
+  scanWorkflowsForOutputDir
+} from "./chunk-RRQB6BPV.js";
+import "./chunk-QGM4M3NI.js";
+export {
+  BuildError,
+  ConfigError,
+  detectBuildCommand,
+  detectCachePaths,
+  detectFramework,
+  detectPackageManager,
+  probeOutputDir,
+  runBuild,
+  scanMakefilesForOutputDir,
+  scanWorkflowsForOutputDir
+};