@lightnet/cli 4.6.1 → 4.7.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @lightnet/cli
 
+## 4.7.0
+
+### Minor Changes
+
+- [#445](https://github.com/LightNetDev/LightNet/pull/445) [`53b6a0d`](https://github.com/LightNetDev/LightNet/commit/53b6a0db8d9e6dca38c808d925007cb2ae343076) - Add a `--progress` option to `lightnet r2 cp`, `lightnet r2 mv`, and `lightnet r2 rm`.
+
+- [#445](https://github.com/LightNetDev/LightNet/pull/445) [`53b6a0d`](https://github.com/LightNetDev/LightNet/commit/53b6a0db8d9e6dca38c808d925007cb2ae343076) - Update `lightnet r2 cp` to follow Unix-style copy semantics for files and directories.
+
+- [#445](https://github.com/LightNetDev/LightNet/pull/445) [`53b6a0d`](https://github.com/LightNetDev/LightNet/commit/53b6a0db8d9e6dca38c808d925007cb2ae343076) - Update `lightnet r2 mv` to use safer Unix-like move semantics inside the configured R2 bucket.
+
+- [#445](https://github.com/LightNetDev/LightNet/pull/445) [`53b6a0d`](https://github.com/LightNetDev/LightNet/commit/53b6a0db8d9e6dca38c808d925007cb2ae343076) - Update `lightnet r2 rm` to follow safer Unix-like delete semantics inside the configured R2 bucket.
+
+## 4.6.2
+
+### Patch Changes
+
+- [#443](https://github.com/LightNetDev/LightNet/pull/443) [`6593139`](https://github.com/LightNetDev/LightNet/commit/65931398471107c03bca6bf4de675599b11db5e5) - Add Clack intro and completion messages to mutating `lightnet r2` commands while keeping `lightnet r2 ls` pipe-friendly.
+
+- [#443](https://github.com/LightNetDev/LightNet/pull/443) [`6593139`](https://github.com/LightNetDev/LightNet/commit/65931398471107c03bca6bf4de675599b11db5e5) - Improve `lightnet r2 cp`, `lightnet r2 mv`, and recursive `lightnet r2 rm` performance by passing tuned rclone concurrency settings internally.
+
+- [#443](https://github.com/LightNetDev/LightNet/pull/443) [`6593139`](https://github.com/LightNetDev/LightNet/commit/65931398471107c03bca6bf4de675599b11db5e5) - Show a clear install message when `lightnet r2` commands cannot find `rclone` on PATH.
+
 ## 4.6.1
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "CLI for managing LightNet projects",
   "type": "module",
   "license": "MIT",
-  "version": "4.6.1",
+  "version": "4.7.0",
   "publishConfig": {
     "access": "public"
   },

package/src/index.js

@@ -92,16 +92,20 @@ r2Command
   .description(
     'delete an R2 file; use -r to delete a directory/prefix or "/" to clean the bucket',
   )
-  .argument("<path>", 'R2 file path, directory/prefix with -r, or "/" with -r')
+  .argument(
+    "<paths...>",
+    'R2 file path(s), directory/prefix paths with -r, or "/" with -r',
+  )
   .option("-r, --recursive", "delete a directory/prefix recursively")
+  .option("--progress", "show operation progress")
   .option(
     "-f, --force",
     'delete without confirmation; use "--force" to clean the bucket root without confirmation',
   )
-  .action(async (path, options) => {
+  .action(async (paths, options) => {
     try {
       options.longForce = hasLongForceFlag()
-      await removeR2(path, options)
+      await removeR2(paths, options)
     } catch (error) {
       handleCommandError(error)
     }
@@ -112,16 +116,20 @@ r2Command
   .description(
     'copy files between R2 and local paths, or inside R2; prefix R2 paths with "r2:"',
   )
-  .argument("<source>", 'source path; use "r2:<path>" for R2')
-  .argument("<destination>", 'destination path; use "r2:<path>" for R2')
-  .option(
-    "-f, --force",
-    'overwrite without confirmation; use "--force" to replace the bucket root without confirmation',
+  .argument(
+    "<paths...>",
+    'source path(s) followed by a destination path; use "r2:<path>" for R2',
   )
-  .action(async (source, destination, options) => {
+  .option("-r, --recursive", "copy directories recursively")
+  .option("-R", "copy directories recursively")
+  .option("-a, --archive", "copy directories recursively")
+  .option("-f, --force", "overwrite existing files without confirmation")
+  .option("-n, --no-clobber", "skip existing destination files")
+  .option("--progress", "show operation progress")
+  .action(async (paths, options) => {
     try {
-      options.longForce = hasLongForceFlag()
-      await copyR2(source, destination, options)
+      options.recursive = options.recursive || options.R || options.archive
+      await copyR2(paths, options)
     } catch (error) {
       handleCommandError(error)
     }
@@ -130,12 +138,13 @@ r2Command
 r2Command
   .command("mv")
   .description("move or rename an R2 file or directory/prefix")
-  .argument("<source>", "R2 source path")
-  .argument("<destination>", "R2 destination path")
+  .argument("<paths...>", "R2 source path(s) followed by a destination path")
   .option("-f, --force", "overwrite existing destination without confirmation")
-  .action(async (source, destination, options) => {
+  .option("-n, --no-clobber", "skip existing destination files")
+  .option("--progress", "show operation progress")
+  .action(async (paths, options) => {
     try {
-      await moveR2(source, destination, options)
+      await moveR2(paths, options)
     } catch (error) {
       handleCommandError(error)
     }

package/src/r2.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { rm, stat } from "node:fs/promises"
+import { stat } from "node:fs/promises"
 import { basename, join, posix, resolve } from "node:path"
 import {
   cwd as processCwd,
@@ -9,24 +9,47 @@ import {
   stdout,
 } from "node:process"
 
-import { confirm, isCancel, log, text } from "@clack/prompts"
+import {
+  confirm,
+  intro,
+  isCancel,
+  log,
+  outro,
+  progress,
+  text,
+} from "@clack/prompts"
 
 import { CliError } from "./support/cli-error.js"
 import { cancelPrompt } from "./support/prompt-cancel.js"
 import { createR2Client } from "./support/r2.js"
 
 const remotePathPrefix = "r2:"
+const defaultRcloneOptions = {
+  checkers: 16,
+  transfers: 8,
+}
+
+/**
+ * @typedef {{
+ *   transfers?: number
+ *   checkers?: number
+ * }} RcloneOptions
+ */
 
 /**
  * @typedef {{
  *   force?: boolean
- *   longForce?: boolean
+ *   noClobber?: boolean
+ *   progress?: boolean
+ *   recursive?: boolean
  * }} R2CopyOptions
  */
 
 /**
  * @typedef {{
  *   force?: boolean
+ *   noClobber?: boolean
+ *   progress?: boolean
  * }} R2MoveOptions
  */
 
@@ -44,6 +67,7 @@ const remotePathPrefix = "r2:"
  *   force?: boolean
  *   recursive?: boolean
  *   longForce?: boolean
+ *   progress?: boolean
  * }} R2RemoveOptions
  */
 
@@ -74,272 +98,328 @@ export async function listR2(path, runtime = {}) {
 }
 
 /**
- * @param {string} path
+ * @param {string|string[]} paths
  * @param {R2RemoveOptions} options
  * @param {R2Runtime} [runtime]
  */
-export async function removeR2(path, options, runtime = {}) {
-  const r2Path = normalizeR2Path(path)
-  const isBucketRoot = isR2BucketRootPath(path)
-  if (isBucketRoot && !options.recursive) {
+export async function removeR2(paths, options, runtime = {}) {
+  intro("r2 rm")
+  const removePaths = Array.isArray(paths) ? paths : [paths]
+  const rootPaths = removePaths.filter((path) => isR2BucketRootPath(path))
+  const hasBucketRoot = rootPaths.length > 0
+  if (removePaths.length === 0) {
+    throw new CliError("R2 deletion requires at least one path.")
+  }
+  if (hasBucketRoot && removePaths.length > 1) {
+    throw new CliError(
+      "Refusing to delete the R2 bucket root with other paths.",
+    )
+  }
+  if (hasBucketRoot && !options.recursive) {
     throw new CliError(
       'Refusing to delete the R2 bucket root without "--recursive".',
     )
   }
-  if (!r2Path && !isBucketRoot) {
-    throw new CliError("Refusing to delete the R2 bucket root.")
+
+  const r2Paths = removePaths.map((path) => normalizeR2Path(path))
+  for (const [index, r2Path] of r2Paths.entries()) {
+    if (!r2Path && !isR2BucketRootPath(removePaths[index])) {
+      throw new CliError("Refusing to delete the R2 bucket root.")
+    }
   }
 
   const interactive = getInteractive(runtime)
-  if (isBucketRoot && options.force && !options.longForce && !interactive) {
+  if (hasBucketRoot && options.force && !options.longForce && !interactive) {
     throw new CliError(
       'Ignoring "-f" for R2 bucket-root cleanup. If you are sure you want to delete the entire R2 bucket, use "--force".',
     )
   }
-  if (isBucketRoot && !interactive && !options.longForce) {
+  if (hasBucketRoot && !interactive && !options.longForce) {
     throw new CliError(
       'Cleaning the R2 bucket root requires interactive confirmation. If you are sure you want to delete the entire R2 bucket, use "--force".',
     )
   }
-  if (isBucketRoot && options.force && !options.longForce) {
+  if (hasBucketRoot && options.force && !options.longForce) {
     log.warn(
       'Ignoring "-f" for R2 bucket-root cleanup. Use "--force" if you are sure you want to delete the entire R2 bucket.',
     )
   }
-  if (!options.force && !interactive) {
-    throw new CliError(
-      'R2 deletion requires confirmation. Re-run with "--force" in non-interactive environments.',
+  if (hasBucketRoot) {
+    log.warn(
+      "This will delete ALL files in the configured R2 bucket. This cannot be undone.",
     )
   }
 
-  if (isBucketRoot) {
-    log.warn(
-      "This will delete ALL files in the configured R2 bucket. This cannot be undone.",
+  const client = createR2CommandClient(runtime)
+  const targets = []
+  for (const [index, r2Path] of r2Paths.entries()) {
+    const originalPath = removePaths[index]
+    const isBucketRoot = isR2BucketRootPath(originalPath)
+    const pathType = isBucketRoot
+      ? "directory"
+      : await getCopyPathType({ remote: true, path: r2Path }, client, runtime)
+
+    if (pathType === "missing") {
+      if (options.force) {
+        continue
+      }
+      throw new CliError(`R2 path "${r2Path}" does not exist.`)
+    }
+    if (pathType === "directory" && !options.recursive) {
+      throw new CliError(
+        `R2 path "${r2Path}" is a directory. Re-run with "--recursive" to delete directories.`,
+      )
+    }
+    targets.push({
+      isBucketRoot,
+      path: r2Path,
+      recursive: pathType === "directory",
+    })
+  }
+
+  if (targets.length > 0 && !options.force && !interactive) {
+    throw new CliError(
+      'R2 deletion requires confirmation. Re-run with "--force" in non-interactive environments.',
     )
   }
 
-  const shouldDelete = isBucketRoot
-    ? options.longForce ||
-      (await getPromptConfirm(runtime)(
-        "Delete all files in the R2 bucket? [y/N] ",
-      ))
-    : options.force ||
-      (await getPromptConfirm(runtime)(`Delete R2 path "${r2Path}"? [y/N] `))
+  for (const target of targets) {
+    const shouldDelete = target.isBucketRoot
+      ? options.longForce ||
+        (await getPromptConfirm(runtime)(
+          "Delete all files in the R2 bucket? [y/N] ",
+        ))
+      : options.force ||
+        (await getPromptConfirm(runtime)(
+          `Delete R2 path "${target.path}"? [y/N] `,
+        ))
 
-  if (!shouldDelete) {
-    cancelPrompt()
+    if (!shouldDelete) {
+      cancelPrompt()
+    }
   }
 
-  const client = createR2CommandClient(runtime)
-  await client.remove(r2Path, {
-    recursive: options.recursive === true,
+  const removeProgress = createR2Progress({
+    enabled: options.progress === true && targets.length > 0,
+    label: "Deleting R2 paths",
+    max: targets.length,
+    success: "R2 delete complete.",
   })
+  try {
+    for (const target of targets) {
+      await client.remove(target.path, {
+        recursive: target.recursive,
+        rcloneOptions: target.recursive ? defaultRcloneOptions : undefined,
+      })
+      removeProgress.advance()
+    }
+    removeProgress.stop()
+  } catch (error) {
+    removeProgress.error("R2 delete failed.")
+    throw error
+  }
+  outro("R2 delete complete.")
 }
 
 /**
- * @param {string} source
- * @param {string} destination
+ * @param {string|string[]} paths
  * @param {R2CopyOptions} [options]
  * @param {R2Runtime} [runtime]
  */
-export async function copyR2(source, destination, options = {}, runtime = {}) {
-  const sourcePath = parseCopyPath(source)
+export async function copyR2(paths, options = {}, runtime = {}) {
+  intro("r2 cp")
+  const { sources, destination } = parseCopyArguments(paths)
+  if (options.force && options.noClobber) {
+    throw new CliError('Cannot use "--force" with "--no-clobber".')
+  }
+  const sourcePaths = sources.map((source) => parseCopyPath(source))
   const destinationPath = parseCopyPath(destination)
-  if (!sourcePath.remote && !destinationPath.remote) {
+  if (
+    !destinationPath.remote &&
+    sourcePaths.every((sourcePath) => !sourcePath.remote)
+  ) {
     throw new CliError(
       `R2 copy requires at least one R2 path. Prefix R2 paths with "${remotePathPrefix}".`,
     )
   }
 
   const client = createR2CommandClient(runtime)
-  const sourceType = await getCopyPathType(sourcePath, client, runtime)
-  if (sourceType === "missing") {
-    throw new CliError(`Copy source "${source}" does not exist.`)
-  }
-
   const destinationType = await getCopyPathType(
     destinationPath,
     client,
     runtime,
   )
-  const targetPath = getCopyTargetPath({
-    destination: destinationPath,
-    destinationType,
-    runtime,
-    source: sourcePath,
-    sourceType,
-  })
-  const targetType = await getCopyPathType(targetPath, client, runtime)
-  const shouldUseCopyTo =
-    sourceType === "file" &&
-    (targetType !== "directory" || isDirectoryLikeCopyPath(destinationPath))
+  if (
+    sourcePaths.length > 1 &&
+    destinationType !== "directory" &&
+    !isDirectoryLikeCopyPath(destinationPath)
+  ) {
+    throw new CliError(
+      "Copying multiple sources requires a directory destination.",
+    )
+  }
+
+  const operations = []
+  for (const [index, sourcePath] of sourcePaths.entries()) {
+    const source = sources[index]
+    const sourceType = await getCopyPathType(sourcePath, client, runtime)
+    if (sourceType === "missing") {
+      throw new CliError(`Copy source "${source}" does not exist.`)
+    }
+    if (sourceType === "directory" && !options.recursive) {
+      throw new CliError(
+        `Copy source "${source}" is a directory. Re-run with "--recursive" to copy directories.`,
+      )
+    }
+
+    const targetPath = getCopyTargetPath({
+      destination: destinationPath,
+      destinationType,
+      runtime,
+      source: sourcePath,
+      sourceType,
+    })
+    const targetType = await getCopyPathType(targetPath, client, runtime)
+    const shouldUseCopyTo =
+      sourceType === "file" &&
+      (targetType !== "directory" || isDirectoryLikeCopyPath(destinationPath))
 
-  const confirmedRootOverwrite = await confirmCopyRootOverwrite({
-    force: options.force === true,
-    longForce: options.longForce === true,
-    runtime,
-    targetPath,
-    targetType,
-  })
-  if (!confirmedRootOverwrite) {
     await confirmCopyOverwrite({
       destination,
       force: options.force === true,
+      noClobber: options.noClobber === true,
       runtime,
       sourceType,
       targetPath,
       targetType,
     })
+
+    operations.push({ shouldUseCopyTo, sourcePath, targetPath })
   }
-  await replaceCopyTargetBeforeCopy({
-    client,
-    runtime,
-    sourceType,
-    targetPath,
-    targetType,
-  })
 
-  await client.copy(
-    await toRcloneCopyPath(sourcePath, client, runtime),
-    await toRcloneCopyPath(targetPath, client, runtime),
-    { to: shouldUseCopyTo },
-  )
+  const copyProgress = createR2Progress({
+    enabled: options.progress === true,
+    label: "Copying R2 paths",
+    max: operations.length,
+    success: "R2 copy complete.",
+  })
+  try {
+    for (const operation of operations) {
+      await client.copy(
+        await toRcloneCopyPath(operation.sourcePath, client, runtime),
+        await toRcloneCopyPath(operation.targetPath, client, runtime),
+        {
+          ignoreExisting: options.noClobber === true,
+          rcloneOptions: defaultRcloneOptions,
+          to: operation.shouldUseCopyTo,
+        },
+      )
+      copyProgress.advance()
+    }
+    copyProgress.stop()
+  } catch (error) {
+    copyProgress.error("R2 copy failed.")
+    throw error
+  }
+  outro("R2 copy complete.")
 }
 
 /**
- * @param {string} source
- * @param {string} destination
+ * @param {string|string[]} paths
  * @param {R2MoveOptions} options
  * @param {R2Runtime} [runtime]
  */
-export async function moveR2(source, destination, options, runtime = {}) {
-  const sourcePath = parseR2OnlyPath(source, "Move source")
+export async function moveR2(paths, options = {}, runtime = {}) {
+  intro("r2 mv")
+  const { sources, destination } = parseCopyArguments(paths)
+  if (options.force && options.noClobber) {
+    throw new CliError('Cannot use "--force" with "--no-clobber".')
+  }
+  const sourcePaths = sources.map((source) =>
+    parseR2OnlyPath(source, "Move source"),
+  )
   const destinationPath = parseR2OnlyPath(destination, "Move destination")
-  if (isR2BucketRootPath(source) || isR2BucketRootPath(destination)) {
+  if (
+    sources.some((source) => isR2BucketRootPath(source)) ||
+    isR2BucketRootPath(destination)
+  ) {
     throw new CliError("Refusing to move the R2 bucket root.")
   }
 
   const client = createR2CommandClient(runtime)
-  const sourceType = await getCopyPathType(sourcePath, client, runtime)
-  if (sourceType === "missing") {
-    throw new CliError(`Move source "${source}" does not exist.`)
-  }
   const destinationType = await getCopyPathType(
     destinationPath,
     client,
     runtime,
   )
-  const targetPath = getCopyTargetPath({
-    destination: destinationPath,
-    destinationType,
-    runtime,
-    source: sourcePath,
-    sourceType,
-  })
-  const targetType = await getCopyPathType(targetPath, client, runtime)
-  const shouldUseMoveTo =
-    sourceType === "file" &&
-    (targetType !== "directory" || isDirectoryLikeCopyPath(destinationPath))
+  if (
+    sourcePaths.length > 1 &&
+    destinationType !== "directory" &&
+    !isDirectoryLikeCopyPath(destinationPath)
+  ) {
+    throw new CliError(
+      "Moving multiple sources requires a directory destination.",
+    )
+  }
 
-  await confirmCopyOverwrite({
-    destination,
-    force: options.force === true,
-    runtime,
-    sourceType,
-    targetPath,
-    targetType,
-  })
-  await replaceCopyTargetBeforeCopy({
-    client,
-    runtime,
-    sourceType,
-    targetPath,
-    targetType,
-  })
+  const operations = []
+  for (const [index, sourcePath] of sourcePaths.entries()) {
+    const source = sources[index]
+    const sourceType = await getCopyPathType(sourcePath, client, runtime)
+    if (sourceType === "missing") {
+      throw new CliError(`Move source "${source}" does not exist.`)
+    }
 
-  await client.move(
-    await toRcloneCopyPath(sourcePath, client, runtime),
-    await toRcloneCopyPath(targetPath, client, runtime),
-    { to: shouldUseMoveTo },
-  )
-}
+    const targetPath = getCopyTargetPath({
+      destination: destinationPath,
+      destinationType,
+      runtime,
+      source: sourcePath,
+      sourceType,
+    })
+    const targetType = await getCopyPathType(targetPath, client, runtime)
+    const shouldUseMoveTo =
+      sourceType === "file" &&
+      (targetType !== "directory" || isDirectoryLikeCopyPath(destinationPath))
 
-/**
- * @param {{
- *   client: ReturnType<typeof createR2CommandClient>,
- *   runtime: R2Runtime,
- *   sourceType: CopyPathType,
- *   targetPath: CopyPath,
- *   targetType: CopyPathType
- * }} args
- */
-async function replaceCopyTargetBeforeCopy({
-  client,
-  runtime,
-  sourceType,
-  targetPath,
-  targetType,
-}) {
-  if (sourceType !== "directory" || targetType !== "directory") {
-    return
-  }
-  if (targetPath.remote) {
-    await client.remove(targetPath.path, { recursive: true })
-    return
-  }
-  await rm(resolveLocalPath(targetPath.path, runtime), {
-    force: true,
-    recursive: true,
-  })
-}
+    await confirmCopyOverwrite({
+      destination,
+      force: options.force === true,
+      noClobber: options.noClobber === true,
+      runtime,
+      sourceType,
+      targetPath,
+      targetType,
+    })
 
-/**
- * @param {{
- *   force: boolean,
- *   longForce: boolean,
- *   runtime: R2Runtime,
- *   targetPath: CopyPath,
- *   targetType: CopyPathType
- * }} args
- */
-async function confirmCopyRootOverwrite({
-  force,
-  longForce,
-  runtime,
-  targetPath,
-  targetType,
-}) {
-  if (!isR2BucketRootCopyPath(targetPath) || targetType === "missing") {
-    return false
-  }
-  log.warn(
-    "This will replace ALL files in the configured R2 bucket. This cannot be undone.",
-  )
-  if (longForce) {
-    return true
-  }
-  if (force && !getInteractive(runtime)) {
-    throw new CliError(
-      'Ignoring "-f" for R2 bucket-root replacement. If you are sure you want to replace the entire R2 bucket, use "--force".',
-    )
-  }
-  if (!getInteractive(runtime)) {
-    throw new CliError(
-      'Replacing the R2 bucket root requires interactive confirmation. If you are sure you want to replace the entire R2 bucket, use "--force".',
-    )
-  }
-  if (force) {
-    log.warn(
-      'Ignoring "-f" for R2 bucket-root replacement. Use "--force" if you are sure you want to replace the entire R2 bucket.',
-    )
+    operations.push({ shouldUseMoveTo, sourcePath, targetPath })
   }
-  const shouldOverwrite = await getPromptConfirm(runtime)(
-    "Replace all files in the R2 bucket? [y/N] ",
-  )
-  if (!shouldOverwrite) {
-    cancelPrompt()
+
+  const moveProgress = createR2Progress({
+    enabled: options.progress === true,
+    label: "Moving R2 paths",
+    max: operations.length,
+    success: "R2 move complete.",
+  })
+  try {
+    for (const operation of operations) {
+      await client.move(
+        await toRcloneCopyPath(operation.sourcePath, client, runtime),
+        await toRcloneCopyPath(operation.targetPath, client, runtime),
+        {
+          ignoreExisting: options.noClobber === true,
+          rcloneOptions: defaultRcloneOptions,
+          to: operation.shouldUseMoveTo,
+        },
+      )
+      moveProgress.advance()
+    }
+    moveProgress.stop()
+  } catch (error) {
+    moveProgress.error("R2 move failed.")
+    throw error
   }
-  return true
+  outro("R2 move complete.")
 }
 
 /**
@@ -353,6 +433,39 @@ function createR2CommandClient(runtime) {
   })
 }
 
+/**
+ * @param {{enabled: boolean, label: string, max: number, success: string}} options
+ */
+function createR2Progress({ enabled, label, max, success }) {
+  if (!enabled || max === 0) {
+    return {
+      advance() {},
+      error() {},
+      stop() {},
+    }
+  }
+
+  const operationProgress = progress({ max })
+  let completed = 0
+  operationProgress.start(`${label} (0/${max})`)
+
+  return {
+    advance() {
+      completed += 1
+      operationProgress.advance(1, `${label} (${completed}/${max})`)
+    },
+    /**
+     * @param {string} message
+     */
+    error(message) {
+      operationProgress.error(message)
+    },
+    stop() {
+      operationProgress.stop(success)
+    },
+  }
+}
+
 /**
  * @param {R2Runtime} runtime
  */
@@ -384,6 +497,23 @@ function parseCopyPath(value) {
   return { remote: true, path: normalizeR2Path(value) }
 }
 
+/**
+ * @param {string|string[]} paths
+ * @returns {{sources: string[], destination: string}}
+ */
+function parseCopyArguments(paths) {
+  const copyPaths = Array.isArray(paths) ? paths : [paths]
+  if (copyPaths.length < 2) {
+    throw new CliError(
+      "R2 copy requires at least one source and a destination.",
+    )
+  }
+  return {
+    sources: copyPaths.slice(0, -1),
+    destination: copyPaths[copyPaths.length - 1],
+  }
+}
+
 /**
  * @param {string} value
  * @param {string} label
@@ -420,6 +550,18 @@ function getCopyTargetPath({
     if (destinationType === "file") {
       throw new CliError("Cannot copy a directory to an existing file.")
     }
+    if (isCopyPathContentsOnly(source)) {
+      return destination
+    }
+    if (
+      destinationType === "directory" ||
+      isDirectoryLikeCopyPath(destination)
+    ) {
+      return {
+        ...destination,
+        path: joinCopyPath(destination, getCopyPathName(source, runtime)),
+      }
+    }
     return destination
   }
 
@@ -440,6 +582,7 @@ function getCopyTargetPath({
  * @param {{
  *   destination: string,
  *   force: boolean,
+ *   noClobber: boolean,
  *   runtime: R2Runtime,
  *   sourceType: CopyPathType,
  *   targetPath: CopyPath,
@@ -449,6 +592,7 @@ function getCopyTargetPath({
 async function confirmCopyOverwrite({
   destination,
   force,
+  noClobber,
   runtime,
   sourceType,
   targetPath,
@@ -457,6 +601,9 @@ async function confirmCopyOverwrite({
   if (targetType === "missing") {
     return
   }
+  if (sourceType === "directory" && targetType === "file") {
+    throw new CliError("Cannot transfer a directory to an existing file.")
+  }
   if (
     sourceType === "file" &&
     targetType === "directory" &&
@@ -467,14 +614,19 @@ async function confirmCopyOverwrite({
   if (force) {
     return
   }
+  if (noClobber) {
+    return
+  }
   if (!getInteractive(runtime)) {
     throw new CliError(
-      'Copy would overwrite existing files. Re-run with "--force" in non-interactive environments.',
+      'Transfer would overwrite existing files. Re-run with "--force" in non-interactive environments.',
     )
   }
-  const shouldOverwrite = await getPromptConfirm(runtime)(
-    `Overwrite existing destination "${destination}"? [y/N] `,
-  )
+  const message =
+    sourceType === "directory"
+      ? `Overwrite any existing files under destination "${destination}"? [y/N] `
+      : `Overwrite existing destination "${destination}"? [y/N] `
+  const shouldOverwrite = await getPromptConfirm(runtime)(message)
   if (!shouldOverwrite) {
     cancelPrompt()
   }
@@ -519,6 +671,16 @@ function isDirectoryLikeCopyPath(copyPath) {
   return copyPath.path === "." || copyPath.path.endsWith("/")
 }
 
+/**
+ * @param {CopyPath} copyPath
+ */
+function isCopyPathContentsOnly(copyPath) {
+  const path = copyPath.remote
+    ? copyPath.path
+    : copyPath.path.replaceAll("\\", "/")
+  return path === "." || path.endsWith("/.")
+}
+
 /**
  * @param {CopyPath} parent
  * @param {string} child
@@ -569,13 +731,6 @@ function isR2BucketRootPath(path) {
   return path.trim() === "/"
 }
 
-/**
- * @param {CopyPath} path
- */
-function isR2BucketRootCopyPath(path) {
-  return path.remote && path.path === ""
-}
-
 /**
  * @param {unknown} error
  */

package/src/support/r2.js

@@ -21,6 +21,13 @@ const execFileAsync = promisify(execFile)
 const sessionSecretEnvName = "LIGHTNET_R2_SECRET_ACCESS_KEY"
 const r2DeleteBatchSize = 1000
 
+/**
+ * @typedef {{
+ *   transfers?: number
+ *   checkers?: number
+ * }} RcloneOptions
+ */
+
 /**
  * @typedef {{
  *   publicUrl: string
@@ -222,7 +229,7 @@ export function createR2Client({ cwd, interactive, promptText }) {
     },
     /**
      * @param {string} path
-     * @param {{recursive?: boolean}} [options]
+     * @param {{recursive?: boolean, rcloneOptions?: RcloneOptions}} [options]
      */
     async remove(path, options = {}) {
       const r2Config = await getConfig()
@@ -234,34 +241,47 @@ export function createR2Client({ cwd, interactive, promptText }) {
           : ["deletefile", r2Path],
         cwd,
         config: r2Config,
+        rcloneOptions: options.rcloneOptions,
         secretAccessKey,
       })
     },
     /**
      * @param {string} source
      * @param {string} destination
-     * @param {{to?: boolean}} [options]
+     * @param {{ignoreExisting?: boolean, to?: boolean, rcloneOptions?: RcloneOptions}} [options]
      */
     async copy(source, destination, options = {}) {
       const r2Config = await getConfig()
       await runConfiguredRclone({
-        args: [options.to ? "copyto" : "copy", source, destination],
+        args: [
+          options.to ? "copyto" : "copy",
+          source,
+          destination,
+          ...(options.ignoreExisting ? ["--ignore-existing"] : []),
+        ],
         cwd,
         config: r2Config,
+        rcloneOptions: options.rcloneOptions,
         secretAccessKey: await getSecretAccessKey(),
       })
     },
     /**
      * @param {string} source
      * @param {string} destination
-     * @param {{to?: boolean}} [options]
+     * @param {{ignoreExisting?: boolean, to?: boolean, rcloneOptions?: RcloneOptions}} [options]
      */
     async move(source, destination, options = {}) {
       const r2Config = await getConfig()
       await runConfiguredRclone({
-        args: [options.to ? "moveto" : "move", source, destination],
+        args: [
+          options.to ? "moveto" : "move",
+          source,
+          destination,
+          ...(options.ignoreExisting ? ["--ignore-existing"] : []),
+        ],
         cwd,
         config: r2Config,
+        rcloneOptions: options.rcloneOptions,
         secretAccessKey: await getSecretAccessKey(),
       })
     },
@@ -496,10 +516,17 @@ async function listR2Objects(args) {
  *   args: string[]
  *   cwd: string
  *   config: R2Config
+ *   rcloneOptions?: RcloneOptions
  *   secretAccessKey: string
  * }} args
  */
-async function runConfiguredRclone({ args, cwd, config, secretAccessKey }) {
+async function runConfiguredRclone({
+  args,
+  cwd,
+  config,
+  rcloneOptions,
+  secretAccessKey,
+}) {
   const env = {
     ...processEnv,
     RCLONE_S3_SECRET_ACCESS_KEY: secretAccessKey,
@@ -518,6 +545,7 @@ async function runConfiguredRclone({ args, cwd, config, secretAccessKey }) {
         "--s3-endpoint",
         getR2Endpoint(config.accountId),
         "--s3-no-check-bucket",
+        ...formatRcloneOptions(rcloneOptions),
       ],
       cwd,
       env,
@@ -527,6 +555,21 @@ async function runConfiguredRclone({ args, cwd, config, secretAccessKey }) {
   }
 }
 
+/**
+ * @param {RcloneOptions|undefined} options
+ */
+function formatRcloneOptions(options) {
+  /** @type {string[]} */
+  const args = []
+  if (options?.transfers !== undefined) {
+    args.push("--transfers", String(options.transfers))
+  }
+  if (options?.checkers !== undefined) {
+    args.push("--checkers", String(options.checkers))
+  }
+  return args
+}
+
 /**
  * @param {{cwd:string, promptText:(message:string)=>Promise<string>}} args
  */
@@ -698,9 +741,16 @@ async function defaultRunRclone(args, cwd, env) {
  */
 function getSanitizedRcloneError(error) {
   if (isPlainObject(error)) {
-    const processError = /** @type {{stderr?: unknown, stdout?: unknown}} */ (
-      error
-    )
+    const processError =
+      /** @type {{code?: unknown, stderr?: unknown, stdout?: unknown}} */ (
+        error
+      )
+    if (processError.code === "ENOENT") {
+      return [
+        "rclone is required for lightnet r2 commands but was not found on PATH.",
+        "Install rclone: https://rclone.org/install/",
+      ].join("\n")
+    }
     if (typeof processError.stderr === "string" && processError.stderr.trim()) {
       return processError.stderr.trim()
     }