permaweb-deploy 3.4.2 → 3.4.4

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
@@ -189,14 +193,14 @@ permaweb-deploy deploy --arns-name my-app --sig-type ethereum --private-key "0x.
 
 ### Bundler service
 
-Uploads go through a [Turbo](https://docs.ardrive.io/docs/turbo/) **bundler service** (HTTP API that bundles data for Arweave). By default, permaweb-deploy uses ArDrive’s production bundler (`https://upload.ardrive.io`). **`--uploader`** sets the **base URL** of the bundler service to use (scheme + host; typically no path).
+Uploads go through a bundler service that accepts signed data items and posts them to Arweave. By default, permaweb-deploy uses the [Turbo](https://docs.ardrive.io/docs/turbo/) API and ArDrive’s production bundler (`https://upload.ardrive.io`). **`--uploader`** sets the **base URL** of the bundler service to use (scheme + host; typically no path).
 
-| When to use               | Example value                                                 |
-| ------------------------- | ------------------------------------------------------------- |
-| **Default** (omit flag)   | ArDrive production bundler — same as Turbo CLI defaults       |
-| **Arweave bundler**       | `https://up.arweave.net`                                      |
-| **Development / staging** | `https://upload.ardrive.dev`                                  |
-| **Custom or self-hosted** | Your own base URL if it implements the Turbo bundler protocol |
+| When to use               | Example value                                                     |
+| ------------------------- | ----------------------------------------------------------------- |
+| **Default** (omit flag)   | ArDrive production bundler — same as Turbo CLI defaults           |
+| **Arweave bundler**       | `https://up.arweave.net`                                          |
+| **Development / staging** | `https://upload.ardrive.dev`                                      |
+| **Custom or self-hosted** | Your own base URL if it implements the selected uploader protocol |
 
 **Examples:**
 
@@ -207,16 +211,46 @@ permaweb-deploy deploy --arns-name my-app --wallet ./wallet.json --uploader http
 permaweb-deploy upload --wallet ./wallet.json --deploy-folder ./dist --uploader https://up.arweave.net
 ```
 
+To upload through a HyperBEAM bundler, set `--uploader-type hyperbeam` and pass the node URL:
+
+```bash
+permaweb-deploy upload \
+  --wallet ./wallet.json \
+  --deploy-folder ./dist \
+  --uploader-type hyperbeam \
+  --uploader https://hyperbeam.example.com
+
+permaweb-deploy deploy \
+  --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, either command can fund the uploader wallet before uploading:
+
+```bash
+permaweb-deploy upload \
+  --wallet ./wallet.json \
+  --deploy-folder ./dist \
+  --uploader-type hyperbeam \
+  --uploader https://hyperbeam.example.com \
+  --hyperbeam-auto-fund
+```
+
 **Notes:**
 
-- Billing and signer behavior still follow Turbo; if an alternate bundler has different rules, check that provider’s docs.
-- Use a **base URL only** (e.g. `https://up.arweave.net`), not a path to a specific file or route.
+- Turbo billing and signer behavior follow Turbo.
+- 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
@@ -229,9 +263,16 @@ permaweb-deploy upload --wallet ./wallet.json --deploy-folder ./dist --uploader
 - `--max-token-amount`: Maximum token amount for on-demand payment (used with `--on-demand`)
 - `--no-dedupe`: Disable deduplication (do not cache or reuse previous uploads)
 - `--dedupe-cache-max-entries`: Maximum number of entries to keep in the dedupe cache (LRU). Default: `10000`
-- `--uploader`: Base URL of the Turbo **bundler service** to use (default: `https://upload.ardrive.io`). See [Bundler service](#bundler-service) above.
+- `--uploader`: Base URL of the bundler service to use. See [Bundler service](#bundler-service) above.
+- `--uploader-type`: Upload protocol to use (`turbo` or `hyperbeam`). Default: `turbo`
+- `--hyperbeam-upload-path`: HyperBEAM bundler route. Default: `/~bundler@1.0/item?codec-device=ans104@1.0`
+- `--hyperbeam-auto-fund`: Automatically fund the HyperBEAM local ledger before upload
+- `--hyperbeam-fund-amount`: Optional minimum HyperBEAM local ledger balance override, in token base units
+- `--hyperbeam-token-id`: Advanced AO token process ID override
+- `--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`, `--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
 
@@ -405,6 +446,20 @@ jobs:
     max-token-amount: '2.0'
 ```
 
+### With HyperBEAM
+
+```yaml
+- name: Deploy through a HyperBEAM bundler
+  uses: permaweb/permaweb-deploy@v1
+  with:
+    deploy-key: ${{ secrets.DEPLOY_KEY }}
+    arns-name: myapp
+    deploy-folder: ./dist
+    uploader-type: hyperbeam
+    uploader: https://hyperbeam.example.com
+    hyperbeam-auto-fund: 'true'
+```
+
 ### Disabling Deduplication
 
 By default, the action caches transaction IDs to avoid re-uploading unchanged files. To disable this:
@@ -566,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-BgIiyBIu.js

@@ -0,0 +1,60 @@
+import boxen from 'boxen';
+import chalk from 'chalk';
+import Table from 'cli-table3';
+
+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 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 uploadErrorTable(message, title = "Upload failed") {
+  const table = new Table({
+    style: { head: [] }
+  });
+  const sections = message.split(/\n{2,}/).map((section) => section.trim()).filter(Boolean);
+  for (const [index, section] of sections.entries()) {
+    if (index === 0) {
+      table.push(["Error", chalk.red(section)]);
+      continue;
+    }
+    if (section.startsWith("Required upload credit:")) {
+      table.push([
+        "Required upload credit",
+        chalk.blue(section.replace(/^Required upload credit:\s*/, ""))
+      ]);
+      continue;
+    }
+    if (section.startsWith("The HyperBEAM node requires AO")) {
+      table.push(["Funding", fundingDisplay(section)]);
+      continue;
+    }
+    table.push(["Note", section]);
+  }
+  return boxen(`${chalk.red.bold(title)}
+
+${table.toString()}`, {
+    borderColor: "red",
+    borderStyle: "round",
+    padding: 1,
+    title: chalk.bold("Permaweb Deploy"),
+    titleAlignment: "center"
+  });
+}
+
+export { formatUploadCost as a, formatUploadSize as f, uploadErrorTable as u };
+//# sourceMappingURL=display-BgIiyBIu.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"display-BgIiyBIu.js","sources":["../../src/utils/display.ts"],"sourcesContent":["import boxen from 'boxen'\nimport chalk from 'chalk'\n// eslint-disable-next-line import/no-named-as-default\nimport Table from 'cli-table3'\n\nimport type { UploadCost, UploadSize } from './hyperbeam-uploader.js'\n\nconst AO_BASE_UNITS = 1_000_000_000_000n\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\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 uploadErrorTable(message: string, title = 'Upload failed'): string {\n  const table = new Table({\n    style: { head: [] },\n  })\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      table.push(['Error', chalk.red(section)])\n      continue\n    }\n\n    if (section.startsWith('Required upload credit:')) {\n      table.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      table.push(['Funding', fundingDisplay(section)])\n      continue\n    }\n\n    table.push(['Note', section])\n  }\n\n  return boxen(`${chalk.red.bold(title)}\\n\\n${table.toString()}`, {\n    borderColor: 'red',\n    borderStyle: 'round',\n    padding: 1,\n    title: chalk.bold('Permaweb Deploy'),\n    titleAlignment: 'center',\n  })\n}\n"],"names":[],"mappings":"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"}