bulletin-deploy 0.7.27 → 0.7.28-rc.1

package/README.md

@@ -215,6 +215,16 @@ await deploy("./dist", "my-app00.dot", { jsMerkle: true });
 | `IPFS CLI not installed` | Install Kubo or switch to `--js-merkle`. |
 | Previous deploy did not exit cleanly / OOM hint | Retry with a larger Node heap, for example `NODE_OPTIONS='--max-old-space-size=8192'`. |
 
+## Contributing
+
+New to the codebase? Start with **[ONBOARDING.md](ONBOARDING.md)** — it covers install, the mental model, the first task, and the working conventions for this repo (worktree-per-branch, squash-merge policy, never-delete-tests, where the per-directory rules live).
+
+The team uses Claude Code as a primary tool. The repo ships team-shared Claude configuration: `.claude/skills/` (project-specific commands like `/e2e-local`, `/dotns-diagnose`, `/sentry-query`), `.claude/settings.json` (Bash allowlist), and per-directory `CLAUDE.md` files in `src/`, `sentry/`, `test/`, `tools/` that load on demand. Running `claude` inside this repo picks all of that up automatically.
+
+Already have Claude Code installed? Clone, `npm install`, open `ONBOARDING.md`. New to Claude Code itself? The same doc covers install.
+
+For maintainers and engineers familiar with the release flow, the canonical procedures live in the root [`CLAUDE.md`](CLAUDE.md): change workflow, dual-stage RC → stable release, post-release Sentry monitoring, and the squash-merge convention that satisfies branch protection without per-commit GPG signing.
+
 ## More Docs
 
 - [Bootstrap and operator setup](docs/bootstrap.md)

package/assets/environments.json

@@ -80,7 +80,8 @@
         "POP_RULES": "0x2002C1c15b88632Ad01c7770f6EbE1Ca05c8472E",
         "STORE_FACTORY": "0x0DE5De70d61cc6b44B45d6595afDe8dB9b55bc31",
         "LABEL_STORE_BEACON": "0xD033F7Ada687E8BC776928AB239505F9f0479Ce7",
-        "USER_STORE_BEACON": "0x7eD9b7D137Fa535965048F93b3B0248fEd2fcd32"
+        "USER_STORE_BEACON": "0x7eD9b7D137Fa535965048F93b3B0248fEd2fcd32",
+        "PUBLISHER": "0x1307fc02d308f879a16b1ae3a49b4927aed53649"
       }
     },
     {

package/bin/bulletin-deploy

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { deploy, DEFAULT_BULLETIN_RPC, DEFAULT_POOL_SIZE, NonRetryableError, EXIT_CODE_NO_RETRY, isConnectionError } from "../dist/deploy.js";
+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";
@@ -36,19 +36,26 @@ for (let i = 0; i < args.length; 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] === "--name") { flags.name = args[++i]; }
-  else if (args[i] === "--description") { flags.description = 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);
@@ -72,7 +79,74 @@ if (flags.listEnvironments) {
   }
 }
 
+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}
@@ -97,10 +171,23 @@ Options:
   --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
-  --name "..."             Optional. Sets the "name" text record on the domain.
-  --description "..."      Optional. Sets the "description" text record (≤100 chars recommended).
+  --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);
@@ -269,11 +356,11 @@ try {
     inputCar: flags.inputCar,
     tag: flags.tag,
     ghPagesMirror: flags.ghPagesMirror,
-    name: flags.name,
-    description: flags.description,
     allowLargeDeploy: flags.allowLargeDeploy,
     reproducibleSource: flags.reproducibleSource,
     dumpCar: flags.dumpCar,
+    publish: flags.publish,
+    failOnPublishError: flags.failOnPublishError,
   });
 
   const output = process.env.GITHUB_OUTPUT;
@@ -285,6 +372,48 @@ try {
   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 {}
   }

package/dist/bug-report.js

@@ -9,10 +9,10 @@ import {
   offerBugReport,
   scrubSecrets,
   setDeployContext
-} from "./chunk-I7YT2IAO.js";
-import "./chunk-AXIJLJZK.js";
-import "./chunk-FW4HEUMH.js";
-import "./chunk-6TIWKKDS.js";
+} from "./chunk-5DKLSM7C.js";
+import "./chunk-FOPTSHK2.js";
+import "./chunk-SJKPP7KA.js";
+import "./chunk-PJCHSHMU.js";
 export {
   buildCliFlagsSummary,
   buildLabels,

package/dist/{chunk-I7YT2IAO.js → chunk-5DKLSM7C.js}

@@ -2,11 +2,11 @@ import {
   classifyErrorArea,
   isInteractive,
   promptYesNo
-} from "./chunk-AXIJLJZK.js";
+} from "./chunk-FOPTSHK2.js";
 import {
   VERSION,
   getCurrentSentryTraceId
-} from "./chunk-FW4HEUMH.js";
+} from "./chunk-SJKPP7KA.js";
 
 // src/bug-report.ts
 import { execSync, execFileSync } from "child_process";
@@ -76,6 +76,9 @@ function buildCliFlagsSummary(flags) {
   const parts = [];
   if (flags.jsMerkle) parts.push("--js-merkle");
   if (flags.ghPagesMirror) parts.push("--gh-pages-mirror");
+  if (flags.publish) parts.push("--publish");
+  if (flags.unpublish) parts.push("--unpublish");
+  if (flags.failOnPublishError) parts.push("--fail-on-publish-error");
   if (flags.poolSize != null) parts.push(`--pool-size ${String(flags.poolSize)}`);
   if (typeof flags.tag === "string" && flags.tag) parts.push(`--tag ${flags.tag}`);
   if (flags.mnemonic) parts.push("--mnemonic <set>");

package/dist/{chunk-AXIJLJZK.js → chunk-FOPTSHK2.js}

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

package/dist/chunk-GQAKFSMZ.js

@@ -0,0 +1,164 @@
+import {
+  pessimisticSizePreflight
+} from "./chunk-RI3ZLNPN.js";
+import {
+  encodeContenthash,
+  resolveDotnsConnectOptions,
+  storeDirectory,
+  storeFile
+} from "./chunk-VUHKPUWQ.js";
+import {
+  DotNS
+} from "./chunk-KP64NWAS.js";
+import {
+  getPopSelfServeConfig,
+  loadEnvironments,
+  resolveEndpoints
+} from "./chunk-OITUIM2E.js";
+import {
+  NonRetryableError
+} from "./chunk-ZOC4GITL.js";
+
+// src/manifest/publish.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+async function publishManifest(opts) {
+  const { config, sourcePath } = opts.loaded;
+  if (config.domain !== opts.domain) {
+    throw new NonRetryableError(
+      `Config domain '${config.domain}' (in ${sourcePath}) does not match deploy domain '${opts.domain}'. Either update the config or pass the matching <domain> argument.`
+    );
+  }
+  const sizeReport = pessimisticSizePreflight(config);
+  if (!sizeReport.ok) {
+    const failing = sizeReport.checks.filter((c) => !c.ok).map((c) => `${c.key}: ${c.bytes}/${c.budget} B`).join(", ");
+    throw new NonRetryableError(
+      `Manifest size preflight failed: ${failing}. Shrink displayName / description / paths or override BULLETIN_TEXT_BUDGET.`
+    );
+  }
+  const configDir = path.dirname(sourcePath);
+  const iconAbs = path.resolve(configDir, config.icon.path);
+  const iconBytes = await readFileOrThrow(iconAbs, "icon");
+  console.log(`
+Manifest publish \u2014 ${config.domain}`);
+  console.log(`  Loaded config: ${sourcePath}`);
+  console.log(`  Uploading icon (${iconBytes.length} B)\u2026`);
+  const iconCid = await storeFile(iconBytes);
+  console.log(`  Icon CID: ${iconCid}`);
+  const executableCids = {};
+  for (const exec of config.executables) {
+    const execAbs = path.resolve(configDir, exec.path);
+    if (opts.buildDirCid && path.resolve(opts.buildDirCid.absPath) === execAbs) {
+      console.log(`  Executable [${exec.kind}] reused build-dir CID: ${opts.buildDirCid.cid}`);
+      executableCids[exec.kind] = opts.buildDirCid.cid;
+      continue;
+    }
+    console.log(`  Uploading executable [${exec.kind}] from ${execAbs}\u2026`);
+    const { storageCid } = await storeDirectory(execAbs, {}, void 0, true);
+    console.log(`  Executable [${exec.kind}] CID: ${storageCid}`);
+    executableCids[exec.kind] = storageCid;
+  }
+  const dotns = await connectDotNS(opts);
+  try {
+    const baseLabel = stripDotSuffix(config.domain);
+    await dotns.ensureContentResolver(baseLabel);
+    const rootManifest = composeRoot(config, iconCid);
+    const rootJson = JSON.stringify(rootManifest);
+    console.log(`  Writing root manifest text record on ${config.domain} (${Buffer.byteLength(rootJson, "utf8")} B)\u2026`);
+    await dotns.setTextRecord(baseLabel, "manifest", rootJson);
+    let textRecordsWritten = 1;
+    for (const exec of config.executables) {
+      const cid = executableCids[exec.kind];
+      if (!cid) throw new NonRetryableError(`Internal: missing CID for executable kind '${exec.kind}'`);
+      const ownership = await dotns.checkSubdomainOwnership(exec.kind, baseLabel);
+      if (!ownership.owned) {
+        if (ownership.owner) {
+          throw new NonRetryableError(
+            `Subname ${exec.kind}.${config.domain} is owned by ${ownership.owner}, not the publisher. Aborting.`
+          );
+        }
+        console.log(`  Registering subname ${exec.kind}.${config.domain}\u2026`);
+        await dotns.registerSubdomain(exec.kind, baseLabel);
+      }
+      await dotns.ensureContentResolver(`${exec.kind}.${baseLabel}`);
+      const subContenthash = `0x${encodeContenthash(cid)}`;
+      console.log(`  Setting contenthash on ${exec.kind}.${config.domain} \u2192 ${cid}\u2026`);
+      await dotns.setContenthash(`${exec.kind}.${baseLabel}`, subContenthash);
+      const execManifest = composeExecutable(exec);
+      const execJson = JSON.stringify(execManifest);
+      console.log(`  Writing executable manifest on ${exec.kind}.${config.domain} (${Buffer.byteLength(execJson, "utf8")} B)\u2026`);
+      await dotns.setTextRecord(`${exec.kind}.${baseLabel}`, "executable", execJson);
+      textRecordsWritten++;
+    }
+    console.log(`  \u2713 ${textRecordsWritten} text record${textRecordsWritten === 1 ? "" : "s"} written.`);
+    return { iconCid, executableCids, textRecordsWritten };
+  } finally {
+    dotns.disconnect();
+  }
+}
+async function readFileOrThrow(p, label) {
+  try {
+    return await fs.readFile(p);
+  } catch (err) {
+    throw new NonRetryableError(`Cannot read ${label} at ${p}: ${err.message}`);
+  }
+}
+async function connectDotNS(opts) {
+  const envId = opts.env ?? "paseo-next-v2";
+  const { doc } = await loadEnvironments();
+  const resolved = resolveEndpoints(doc, envId);
+  const popSelfServe = getPopSelfServeConfig(doc, envId);
+  const deployOptsShim = {
+    mnemonic: opts.mnemonic,
+    derivationPath: opts.derivationPath
+  };
+  const connectOpts = resolveDotnsConnectOptions(
+    deployOptsShim,
+    resolved.assetHub,
+    resolved.autoAccountMapping,
+    resolved.contracts,
+    resolved.nativeToEthRatio,
+    envId,
+    popSelfServe,
+    resolved.registerStorageDeposit
+  );
+  const dotns = new DotNS();
+  await dotns.connect(connectOpts);
+  return dotns;
+}
+function composeRoot(config, iconCid) {
+  return {
+    $v: 1,
+    displayName: config.displayName,
+    description: config.description,
+    icon: { cid: iconCid, format: config.icon.format }
+  };
+}
+function composeExecutable(exec) {
+  if (exec.kind === "app") {
+    return { $v: 1, kind: "app", appVersion: exec.appVersion };
+  }
+  if (exec.kind === "widget") {
+    return {
+      $v: 1,
+      kind: "widget",
+      appVersion: exec.appVersion,
+      dimensions: exec.dimensions,
+      ...exec.description !== void 0 ? { description: exec.description } : {}
+    };
+  }
+  return {
+    $v: 1,
+    kind: "worker",
+    appVersion: exec.appVersion,
+    entrypoint: exec.entrypoint,
+    includes: exec.includes
+  };
+}
+function stripDotSuffix(domain) {
+  return domain.replace(/\.dot$/i, "");
+}
+
+export {
+  publishManifest
+};

package/dist/chunk-GZD2UFLR.js

@@ -0,0 +1,8 @@
+// src/manifest/types.ts
+function defineConfig(config) {
+  return config;
+}
+
+export {
+  defineConfig
+};