permaweb-deploy 3.4.3 → 3.4.5

package/README.md

@@ -1,13 +1,13 @@
 # Permaweb Deploy
 
-Inspired by the [cookbook github action deployment guide](https://cookbook.arweave.dev/guides/deployment/github-action.html), `permaweb-deploy` is a Node.js command-line tool designed to streamline the deployment of web applications to the permaweb using Arweave. It uploads your build folder or a single file, creates Arweave manifests, and updates ArNS (Arweave Name Service) records via ANT (Arweave Name Token) with the transaction ID.
+Inspired by the [cookbook github action deployment guide](https://cookbook.arweave.dev/guides/deployment/github-action.html), `permaweb-deploy` is a Node.js command-line tool designed to streamline the deployment of web applications to the permaweb using Arweave. It uploads your build folder or a single file, creates Arweave manifests, and can optionally update ArNS (Arweave Name Service) records via ANT (Arweave Name Token) with the transaction ID.
 
 ## Features
 
 - **Turbo SDK Integration:** Uses Turbo SDK for fast, reliable file uploads to Arweave
 - **On-Demand Payment:** Pay with ARIO or Base-ETH tokens on-demand during upload
 - **Arweave Manifest v0.2.0:** Creates manifests with fallback support for SPAs
-- **ArNS Updates:** Updates ArNS records via ANT with new transaction IDs and metadata
+- **Optional ArNS Updates:** Updates ArNS records via ANT with new transaction IDs and metadata
 - **Automated Workflow:** Integrates with GitHub Actions for continuous deployment
 - **Git Hash Tagging:** Automatically tags deployments with Git commit hashes
 - **404 Fallback Detection:** Automatically detects and sets 404.html as fallback
@@ -77,7 +77,7 @@ Run the deploy command without arguments to be guided through all deployment opt
 permaweb-deploy deploy
 ```
 
-This will prompt you for:
+This uploads to the permaweb by default. Use `--use-arns` or `--arns-name` to run the guided ArNS update flow, which will prompt you for:
 
 - ArNS name
 - Wallet method (file, string, or environment variable)
@@ -91,7 +91,10 @@ Use flags for faster, scriptable deployments:
 
 ```bash
 # Basic deployment with wallet file
-permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json
+permaweb-deploy deploy --wallet ./wallet.json
+
+# Deployment with ArNS update
+permaweb-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json
 ```
 
 Deploy using private key directly:
@@ -118,11 +121,12 @@ Deploy a single file:
 permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --deploy-file ./path/to/file.txt
 ```
 
-### Upload only (no ArNS)
+### Upload/deploy without ArNS
 
-To upload a folder or file to Arweave **without** updating an ArNS name, use the `upload` command (same Turbo upload, dedupe cache, and payment options as deploy, minus ArNS flags):
+`deploy` uploads without updating ArNS by default. You can also use the `upload` command explicitly for the same Turbo upload, dedupe cache, and payment options as deploy, minus ArNS flags:
 
 ```bash
+permaweb-deploy deploy --wallet ./wallet.json --deploy-folder ./dist
 permaweb-deploy upload --wallet ./wallet.json --deploy-folder ./dist
 permaweb-deploy upload --wallet ./wallet.json --deploy-file ./dist/index.html
 DEPLOY_KEY=$(base64 -i wallet.json) permaweb-deploy upload --deploy-folder ./dist
@@ -217,14 +221,13 @@ permaweb-deploy upload \
   --uploader https://hyperbeam.example.com
 
 permaweb-deploy deploy \
-  --arns-name my-app \
   --wallet ./wallet.json \
   --deploy-folder ./dist \
   --uploader-type hyperbeam \
   --uploader https://hyperbeam.example.com
 ```
 
-If the node follows the standard AO-paid HyperBEAM bundler flow, the CLI can fund the uploader wallet before uploading:
+If the node follows the standard AO-paid HyperBEAM bundler flow, either command can fund the uploader wallet before uploading:
 
 ```bash
 permaweb-deploy upload \
@@ -238,15 +241,16 @@ permaweb-deploy upload \
 **Notes:**
 
 - Turbo billing and signer behavior follow Turbo.
-- HyperBEAM uploads require an Arweave JWK signer. With `--hyperbeam-auto-fund`, the CLI signs each data item, asks the node's `metering@1.0` device for a byte quote, sends AO to the node address from `/~meta@1.0/info/address`, imports that deposit through `/~ao-payment@1.0/ingest`, and waits for the uploader's balance at `/ledger~node-process@1.0/now/balance/<address>` before uploading. The default route is `/~bundler@1.0/item?codec-device=ans104@1.0`; override it with `--hyperbeam-upload-path` if your node exposes a different bundler route.
-- `--hyperbeam-fund-amount` is an optional override for the minimum local ledger balance to ensure, in AO base units. Without it, `--hyperbeam-auto-fund` uses the node's `metering@1.0` quote for the signed byte count. Use `--hyperbeam-token-id` only for a non-default AO token process, and `--hyperbeam-ledger-id` only for a non-default local ledger profile.
+- HyperBEAM uploads require an Arweave JWK signer. Before uploading, the CLI checks the node address from `/~meta@1.0/info/address` against `https://arweave.net/wallet/<address>/balance` and aborts if the bundler wallet has 0 AR. With `--hyperbeam-auto-fund`, the CLI signs each data item, asks the node's byte-pricing profile for a quote, sends AO to the node deposit address, imports that deposit through `/~ao-payment@1.0/ingest`, and waits for the uploader's balance at `/ledger~node-process@1.0/now/balance/<address>` before uploading. The default route is `/~bundler@1.0/item?codec-device=ans104@1.0`; override it with `--hyperbeam-upload-path` if your node exposes a different bundler route.
+- `--hyperbeam-fund-amount` is an optional override for the minimum local ledger balance to ensure, in AO base units. Without it, `--hyperbeam-auto-fund` uses the node's byte-pricing quote for the signed byte count. Use `--hyperbeam-token-id` only for a non-default AO token process, and `--hyperbeam-ledger-id` only for a non-default local ledger profile.
 - Use a **base URL only** (e.g. `https://up.arweave.net` or `https://hyperbeam.example.com`), not a path to a specific file or route.
 
 ### Command Options
 
-**`deploy`** (ArNS update):
+**`deploy`** (upload by default, optional ArNS update):
 
-- `--arns-name, -n` (required): The ArNS name to update
+- `--use-arns`: Update an ArNS/ANT record after upload
+- `--arns-name, -n`: The ArNS name to update. Required when using `--use-arns`; also implies ArNS mode for backwards compatibility.
 - `--ario-process, -p`: ARIO process to use (`mainnet`, `testnet`, or a custom process ID). Default: `mainnet`
 - `--deploy-folder, -d`: Folder to deploy. Default: `./dist`
 - `--deploy-file, -f`: Deploy a single file instead of a folder
@@ -268,7 +272,7 @@ permaweb-deploy upload \
 - `--hyperbeam-ledger-id`: Advanced local HyperBEAM ledger ID override
 - `--hyperbeam-ao-state-url`: AO state endpoint used while waiting for auto-fund transfer assignment. Default: `https://state.forward.computer`
 
-**`upload`** (no ArNS): accepts `--deploy-folder`, `--deploy-file`, wallet/signer flags, uploader flags, `--on-demand` / `--max-token-amount`, and dedupe flags only.
+**`upload`** (explicit upload without ArNS): accepts `--deploy-folder`, `--deploy-file`, wallet/signer flags, uploader flags, `--on-demand` / `--max-token-amount`, and dedupe flags only.
 
 ### Deduplication
 
@@ -617,7 +621,7 @@ permaweb-deploy/
 
 - **Dedicated Wallet:** Always use a dedicated wallet for deployments to minimize security risks
 - **Wallet Encoding:** Arweave wallets must be base64 encoded to be used in the deployment script
-- **ArNS Name:** The ArNS Name must be passed so that the ANT Process can be resolved to update the target undername or root record
+- **ArNS Name:** Required only when updating an ANT/ArNS target undername or root record
 - **Turbo Credits:** Ensure your wallet has sufficient Turbo Credits, or use on-demand payment for automatic funding
 - **On-Demand Limits:** Set reasonable `--max-token-amount` limits to prevent unexpected costs
 - **Secret Management:** Keep your `DEPLOY_KEY` secret secure and never commit it to your repository

package/dist/chunks/display-CyJXNtkl.js

@@ -0,0 +1,53 @@
+import { c as chalk } from './upload-workflow-CcYev67_.js';
+
+const AO_BASE_UNITS = 1000000000000n;
+function formatUploadSize(size) {
+  return `${(size.signedBytes ?? size.payloadBytes).toLocaleString()} bytes`;
+}
+function formatUploadCost(cost) {
+  if (cost.token !== "AO") {
+    return `${cost.amount.toString()}`;
+  }
+  const whole = cost.amount / AO_BASE_UNITS;
+  const fraction = cost.amount % AO_BASE_UNITS;
+  const decimal = fraction === 0n ? whole.toString() : `${whole.toString()}.${fraction.toString().padStart(12, "0").replaceAll(/0+$/g, "")}`;
+  return `${decimal} AO`;
+}
+function formatDisplayRows(rows) {
+  return rows.map(([label, value]) => `${label}: ${value}`).join("\n");
+}
+function fundingDisplay(section) {
+  const fundingLine = section.split("\n").map((line) => line.trim()).find((line) => line.startsWith("- "))?.replace(/^- /, "");
+  if (!fundingLine) {
+    return section;
+  }
+  return fundingLine.replace(/^AO: send funds to /, "Sending AO to ").replace(/\. Local ledger:.*$/, "");
+}
+function formatUploadError(message, title = "Upload failed") {
+  const rows = [];
+  const sections = message.split(/\n{2,}/).map((section) => section.trim()).filter(Boolean);
+  for (const [index, section] of sections.entries()) {
+    if (index === 0) {
+      rows.push(["Error", chalk.red(section)]);
+      continue;
+    }
+    if (section.startsWith("Required upload credit:")) {
+      rows.push([
+        "Required upload credit",
+        chalk.blue(section.replace(/^Required upload credit:\s*/, ""))
+      ]);
+      continue;
+    }
+    if (section.startsWith("The HyperBEAM node requires AO")) {
+      rows.push(["Funding", fundingDisplay(section)]);
+      continue;
+    }
+    rows.push(["Note", section]);
+  }
+  return `${chalk.bold(chalk.red(title))}
+
+${formatDisplayRows(rows)}`;
+}
+
+export { formatUploadError as a, formatUploadSize as b, formatUploadCost as c, formatDisplayRows as f };
+//# sourceMappingURL=display-CyJXNtkl.js.map

package/dist/chunks/display-CyJXNtkl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-CyJXNtkl.js","sources":["../../src/utils/display.ts"],"sourcesContent":["import { chalk } from './chalk.js'\nimport type { UploadCost, UploadSize } from './hyperbeam-uploader.js'\n\nconst AO_BASE_UNITS = 1_000_000_000_000n\n\nexport type DisplayRow = [label: string, value: string]\n\nexport function formatUploadSize(size: UploadSize): string {\n  return `${(size.signedBytes ?? size.payloadBytes).toLocaleString()} bytes`\n}\n\nexport function formatUploadCost(cost: UploadCost): string {\n  if (cost.token !== 'AO') {\n    return `${cost.amount.toString()}`\n  }\n\n  const whole = cost.amount / AO_BASE_UNITS\n  const fraction = cost.amount % AO_BASE_UNITS\n  const decimal =\n    fraction === 0n\n      ? whole.toString()\n      : `${whole.toString()}.${fraction.toString().padStart(12, '0').replaceAll(/0+$/g, '')}`\n\n  return `${decimal} AO`\n}\n\nexport function formatDisplayRows(rows: DisplayRow[]): string {\n  return rows.map(([label, value]) => `${label}: ${value}`).join('\\n')\n}\n\nfunction fundingDisplay(section: string): string {\n  const fundingLine = section\n    .split('\\n')\n    .map((line) => line.trim())\n    .find((line) => line.startsWith('- '))\n    ?.replace(/^- /, '')\n\n  if (!fundingLine) {\n    return section\n  }\n\n  return fundingLine\n    .replace(/^AO: send funds to /, 'Sending AO to ')\n    .replace(/\\. Local ledger:.*$/, '')\n}\n\nexport function formatUploadError(message: string, title = 'Upload failed'): string {\n  const rows: DisplayRow[] = []\n  const sections = message\n    .split(/\\n{2,}/)\n    .map((section) => section.trim())\n    .filter(Boolean)\n\n  for (const [index, section] of sections.entries()) {\n    if (index === 0) {\n      rows.push(['Error', chalk.red(section)])\n      continue\n    }\n\n    if (section.startsWith('Required upload credit:')) {\n      rows.push([\n        'Required upload credit',\n        chalk.blue(section.replace(/^Required upload credit:\\s*/, '')),\n      ])\n      continue\n    }\n\n    if (section.startsWith('The HyperBEAM node requires AO')) {\n      rows.push(['Funding', fundingDisplay(section)])\n      continue\n    }\n\n    rows.push(['Note', section])\n  }\n\n  return `${chalk.bold(chalk.red(title))}\\n\\n${formatDisplayRows(rows)}`\n}\n"],"names":[],"mappings":"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"}

package/dist/chunks/{upload-workflow-zlELdPNp.js → upload-workflow-CcYev67_.js}

@@ -1,9 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { TurboFactory, ETHToTokenAmount, ARIOToTokenAmount, OnDemandFunding } from '@ardrive/turbo-sdk';
-import chalk from 'chalk';
 import ora from 'ora';
-import { l as loadCache, u as uploadFile, c as cleanupCache, s as saveCache, a as uploadFolder } from './uploader-DDS_d-O_.js';
+import { l as loadCache, u as uploadFile, c as cleanupCache, s as saveCache, a as uploadFolder } from './uploader-CIHu22Fw.js';
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { Readable } from 'node:stream';
@@ -11,6 +10,53 @@ import { createDataItemSigner, message } from '@permaweb/aoconnect';
 import { expandPath } from '../utils/path.js';
 import { createSigner } from '../utils/signer.js';
 
+const RESET = "\x1B[0m";
+const WHITE = "\x1B[37m";
+const BG_BLACK = "\x1B[40m";
+const colorCodes = [
+  ["bold", "\x1B[1m"],
+  ["dim", "\x1B[2m"],
+  ["italic", "\x1B[3m"],
+  ["underline", "\x1B[4m"],
+  ["inverse", "\x1B[7m"],
+  ["strikethrough", "\x1B[9m"],
+  ["black", "\x1B[30m"],
+  ["red", "\x1B[31m"],
+  ["green", "\x1B[32m"],
+  ["yellow", "\x1B[33m"],
+  ["blue", "\x1B[34m"],
+  ["magenta", "\x1B[35m"],
+  ["cyan", "\x1B[36m"],
+  ["white", WHITE],
+  ["gray", "\x1B[90m"],
+  ["grey", "\x1B[90m"],
+  ["blackBright", "\x1B[90m"],
+  ["redBright", "\x1B[91m"],
+  ["greenBright", "\x1B[92m"],
+  ["yellowBright", "\x1B[93m"],
+  ["blueBright", "\x1B[94m"],
+  ["magentaBright", "\x1B[95m"],
+  ["cyanBright", "\x1B[96m"],
+  ["whiteBright", "\x1B[97m"],
+  ["bgBlack", BG_BLACK],
+  ["bgRed", "\x1B[41m"],
+  ["bgGreen", "\x1B[42m"],
+  ["bgYellow", "\x1B[43m"],
+  ["bgBlue", "\x1B[44m"],
+  ["bgMagenta", "\x1B[45m"],
+  ["bgCyan", "\x1B[46m"],
+  ["bgWhite", "\x1B[47m"],
+  ["bgBlackBright", "\x1B[100m"]
+];
+const createColorFunction = (code) => (text) => `${code}${String(text)}${RESET}`;
+const colorFunctions = {};
+for (const [name, code] of colorCodes) {
+  colorFunctions[name] = createColorFunction(code);
+}
+const chalk = Object.assign(colorFunctions, {
+  highlight: (text) => `${BG_BLACK}${WHITE}${String(text)} ${RESET}`
+});
+
 class HyperbalanceError extends Error {
     cause;
     constructor(message, cause) {
@@ -548,6 +594,8 @@ async function fetchHyperbeamOperatorAddress(fetcher, nodeUrl) {
 
 const require$1 = createRequire(import.meta.url);
 const { ArweaveSigner, DataItem, createData } = require$1("@dha-team/arbundles");
+const AO_BASE_UNITS = 1000000000000n;
+const ARWEAVE_GATEWAY = "https://arweave.net";
 async function readableToBuffer(stream) {
   const chunks = [];
   for await (const chunk of stream) {
@@ -593,6 +641,24 @@ function parseHyperbeamFundAmount(value) {
   }
   return BigInt(value);
 }
+function formatAoAmount(amount) {
+  const whole = amount / AO_BASE_UNITS;
+  const fraction = amount % AO_BASE_UNITS;
+  if (fraction === 0n) {
+    return `${whole.toString()} AO`;
+  }
+  return `${whole.toString()}.${fraction.toString().padStart(12, "0").replaceAll(/0+$/g, "")} AO`;
+}
+function responsePreview(body) {
+  const preview = body.replaceAll(/\s+/g, " ").trim();
+  if (!preview) {
+    return void 0;
+  }
+  if (/^(<!doctype html\b|<html\b)/i.test(preview)) {
+    return "HTML error response";
+  }
+  return preview.slice(0, 300);
+}
 async function ensureHyperbeamCredit(options, profile) {
   const jwk = JSON.parse(Buffer.from(options.deployKey, "base64").toString("utf8"));
   const recipient = arweaveAddressFromJwk(jwk);
@@ -663,9 +729,46 @@ async function autoFundQuotedHyperbeamLedger(options) {
     profile
   );
 }
-function hyperbeamBundlerLink(uploader, id) {
+async function quoteHyperbeamUpload(options) {
+  const profile = await discoverHyperbeamAoBundlerProfile({
+    ledgerId: options.ledgerId,
+    nodeUrl: options.uploader,
+    tokenId: options.tokenId
+  });
+  const quote = await new HyperbalanceClient({ nodeUrl: options.uploader }).quoteAuto({
+    action: options.quoteAction ?? "hyperbeam-upload",
+    params: { bytes: options.signedBytes },
+    profile
+  });
+  return { amount: quote.amount, ledgerId: quote.ledgerId, tokenId: quote.tokenId };
+}
+function hyperbeamBundlerLink(uploader, id, isManifest = false) {
   const normalizedBase = uploader.endsWith("/") ? uploader : `${uploader}/`;
-  return new URL(`~arweave@2.9/raw=${encodeURIComponent(id)}`, normalizedBase).toString();
+  return new URL(`${encodeURIComponent(id)}${isManifest ? "/" : ""}`, normalizedBase).toString();
+}
+async function preflightHyperbeamBundlerArBalance(uploader) {
+  const nodeUrl = uploader.replace(/\/+$/, "");
+  const addressRes = await fetch(`${nodeUrl}/~meta@1.0/info/address`);
+  if (!addressRes.ok) {
+    throw new Error(`HyperBEAM bundler address check failed with HTTP ${addressRes.status}`);
+  }
+  const address = (await addressRes.text()).trim();
+  if (!address) {
+    throw new Error("HyperBEAM bundler address check returned an empty address");
+  }
+  const balanceRes = await fetch(`${ARWEAVE_GATEWAY}/wallet/${encodeURIComponent(address)}/balance`);
+  if (!balanceRes.ok) {
+    throw new Error(`HyperBEAM bundler AR balance check failed with HTTP ${balanceRes.status}`);
+  }
+  const balance = (await balanceRes.text()).trim();
+  if (!/^\d+$/.test(balance)) {
+    throw new Error("HyperBEAM bundler AR balance check returned an invalid balance");
+  }
+  if (BigInt(balance) === 0n) {
+    throw new Error(
+      `HyperBEAM bundler wallet ${address} has 0 AR; upload aborted because the node cannot seed data to Arweave.`
+    );
+  }
 }
 function responseId(headers, body) {
   const headerId = headers.get("id");
@@ -679,30 +782,82 @@ function responseId(headers, body) {
     return void 0;
   }
 }
+function cleanAutoFundErrorMessage(message) {
+  const jsonStart = message.indexOf("{");
+  if (jsonStart >= 0) {
+    try {
+      const parsed = JSON.parse(message.slice(jsonStart));
+      if (parsed.error) {
+        return parsed.error.replace(/^Error:\s*/, "");
+      }
+    } catch {
+    }
+  }
+  return message;
+}
+function autoFundFailureNote(message) {
+  if (/rate limit exceeded/i.test(message)) {
+    return "AO token transfer was rate limited. Check that the wallet has enough spendable AO before retrying auto-fund.";
+  }
+  return "Check the wallet or node ledger before retrying auto-fund; the AO transfer may already have been submitted.";
+}
 class HyperbeamBundlerClient {
   autoFund;
+  quote;
+  seedPreflight;
   signer;
   uploader;
   uploadUrl;
-  constructor({ autoFund, deployKey, uploadPath, uploader }) {
+  constructor({ autoFund, deployKey, quote, uploadPath, uploader }) {
     const jwk = JSON.parse(Buffer.from(deployKey, "base64").toString("utf8"));
     this.autoFund = autoFund;
+    this.quote = quote ?? { uploader };
     this.signer = new ArweaveSigner(jwk);
     this.uploader = uploader;
     this.uploadUrl = normalizeUploadUrl(uploader, uploadPath);
   }
   async uploadFile(args) {
+    this.seedPreflight ??= preflightHyperbeamBundlerArBalance(this.uploader);
+    await this.seedPreflight;
     const data = args.file ? typeof args.file === "string" ? fs.readFileSync(args.file) : args.file : await streamToBuffer(args.fileStreamFactory?.() ?? Readable.from([]));
     const tags = args.dataItemOpts?.tags ?? [];
     const item = createData(data, this.signer, { tags });
     await item.sign(this.signer);
     const raw = Buffer.from(item.getRaw());
     const localId = item.id || toBase64Url(new DataItem(raw).id);
+    const size = { payloadBytes: data.length, signedBytes: raw.length };
+    let cost;
     if (this.autoFund) {
-      await autoFundQuotedHyperbeamLedger({
-        ...this.autoFund,
-        signedBytes: raw.length
-      });
+      const quote = await quoteHyperbeamUpload({ ...this.quote, signedBytes: raw.length });
+      cost = { amount: quote.amount, token: "AO" };
+      try {
+        await autoFundQuotedHyperbeamLedger({
+          ...this.autoFund,
+          ledgerId: this.autoFund.ledgerId ?? quote.ledgerId,
+          minimumBalance: this.autoFund.minimumBalance ?? quote.amount,
+          signedBytes: raw.length,
+          tokenId: this.autoFund.tokenId ?? quote.tokenId
+        });
+      } catch (error) {
+        const message = cleanAutoFundErrorMessage(
+          error instanceof Error ? error.message : String(error)
+        );
+        throw new Error(
+          [
+            `HyperBEAM auto-fund failed: ${message}`,
+            `Required upload credit: ${formatAoAmount(cost.amount)}`,
+            autoFundFailureNote(message),
+            await this.paymentHint(false)
+          ].filter(Boolean).join("\n\n")
+        );
+      }
+    } else {
+      try {
+        const quote = await quoteHyperbeamUpload({ ...this.quote, signedBytes: raw.length });
+        cost = { amount: quote.amount, token: "AO" };
+      } catch {
+        cost = void 0;
+      }
     }
     const res = await fetch(this.uploadUrl, {
       body: raw,
@@ -714,7 +869,7 @@ class HyperbeamBundlerClient {
     });
     const body = await res.text();
     if (!res.ok) {
-      const preview = body.replaceAll(/\s+/g, " ").trim().slice(0, 300);
+      const preview = responsePreview(body);
       const paymentHint = res.status === 402 ? await this.paymentHint() : void 0;
       throw new Error(
         [
@@ -723,23 +878,36 @@ class HyperbeamBundlerClient {
         ].filter(Boolean).join("\n\n")
       );
     }
-    return { id: responseId(res.headers, body) || localId };
+    return { cost, id: responseId(res.headers, body) || localId, size };
   }
-  async paymentHint() {
+  async paymentHint(includeAutoFundInstruction = true) {
     try {
       return hyperbeamAoFundingHint(
-        await discoverHyperbeamAoBundlerProfile({ nodeUrl: this.uploader })
+        await discoverHyperbeamAoBundlerProfile({ nodeUrl: this.uploader }),
+        { includeAutoFundInstruction }
       );
     } catch {
-      return void 0;
+      try {
+        const operator = await fetch(
+          `${this.uploader.replace(/\/+$/, "")}/~meta@1.0/info/address`
+        ).then((res) => res.ok ? res.text() : void 0);
+        if (!operator?.trim()) return void 0;
+        return [
+          "The HyperBEAM node requires AO in its local ledger:",
+          `- AO: send funds to ${operator.trim()}. Local ledger: ${HYPERBEAM_DEFAULT_LEDGER_ID} at ${HYPERBEAM_DEFAULT_LEDGER_ROUTE}.`,
+          includeAutoFundInstruction ? "Use --hyperbeam-auto-fund to transfer AO and import the credit automatically before upload." : void 0
+        ].filter(Boolean).join("\n");
+      } catch {
+        return void 0;
+      }
     }
   }
 }
-function hyperbeamAoFundingHint(profile) {
+function hyperbeamAoFundingHint(profile, options = {}) {
   const lines = profile.tokens.map((token) => {
     const depositAddress = token.depositAddress ?? profile.node?.operator;
     if (!depositAddress) return;
-    const label = token.ticker ? `${token.ticker} (${token.id})` : token.id;
+    const label = token.ticker === "AO" ? "AO" : token.ticker ? `${token.ticker} (${token.id})` : token.id;
     const ledger = token.ledgerId ? profile.ledgers.find((candidate) => candidate.id === token.ledgerId) : void 0;
     const ledgerInfo = ledger ? ` Local ledger: ${ledger.id}${ledger.route ? ` at ${ledger.route}` : ""}.` : "";
     return `- ${label}: send funds to ${depositAddress}.${ledgerInfo}`;
@@ -748,8 +916,8 @@ function hyperbeamAoFundingHint(profile) {
   return [
     "The HyperBEAM node requires AO in its local ledger:",
     ...lines,
-    "Use --hyperbeam-auto-fund to transfer AO and import the credit automatically before upload."
-  ].join("\n");
+    options.includeAutoFundInstruction === false ? void 0 : "Use --hyperbeam-auto-fund to transfer AO and import the credit automatically before upload."
+  ].filter(Boolean).join("\n");
 }
 
 function getFolderSize(folderPath) {
@@ -793,6 +961,11 @@ async function runUploadWorkflow(deployKey, config, io) {
     uploadClient = new HyperbeamBundlerClient({
       autoFund,
       deployKey,
+      quote: {
+        ledgerId: config["hyperbeam-ledger-id"],
+        tokenId: config["hyperbeam-token-id"],
+        uploader: config.uploader
+      },
       uploadPath: config["hyperbeam-upload-path"] ?? "/~bundler@1.0/item?codec-device=ans104@1.0",
       uploader: config.uploader
     });
@@ -869,6 +1042,8 @@ async function runUploadWorkflow(deployKey, config, io) {
     }
   }
   let txOrManifestId;
+  let cost;
+  let size;
   try {
     if (config["deploy-file"]) {
       const filePath = expandPath(config["deploy-file"]);
@@ -880,6 +1055,8 @@ async function runUploadWorkflow(deployKey, config, io) {
         io.error("File upload failed: no transaction ID returned");
       }
       txOrManifestId = uploadResult.transactionId;
+      cost = uploadResult.cost;
+      size = uploadResult.size;
       if (uploadResult.updatedCache && config["dedupe-cache-max-entries"] > 0) {
         cache = cleanupCache(uploadResult.updatedCache, config["dedupe-cache-max-entries"]);
         saveCache(cache);
@@ -905,6 +1082,8 @@ async function runUploadWorkflow(deployKey, config, io) {
         io.error("Folder upload failed: no transaction ID returned");
       }
       txOrManifestId = uploadResult.transactionId;
+      cost = uploadResult.cost;
+      size = uploadResult.size;
       if (uploadResult.updatedCache && config["dedupe-cache-max-entries"] > 0) {
         cache = cleanupCache(uploadResult.updatedCache, config["dedupe-cache-max-entries"]);
         saveCache(cache);
@@ -923,8 +1102,12 @@ async function runUploadWorkflow(deployKey, config, io) {
     const errorMessage = uploadError instanceof Error ? uploadError.message : String(uploadError);
     io.error(`Upload failed: ${errorMessage}`);
   }
-  return txOrManifestId;
+  return {
+    cost,
+    size,
+    transactionId: txOrManifestId
+  };
 }
 
-export { hyperbeamBundlerLink as h, runUploadWorkflow as r };
-//# sourceMappingURL=upload-workflow-zlELdPNp.js.map
+export { chalk as c, hyperbeamBundlerLink as h, runUploadWorkflow as r };
+//# sourceMappingURL=upload-workflow-CcYev67_.js.map