@lightnet/cli 4.4.2 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @lightnet/cli
 
+## 4.6.0
+
+### Minor Changes
+
+- [#439](https://github.com/LightNetDev/LightNet/pull/439) [`2572437`](https://github.com/LightNetDev/LightNet/commit/25724372a47ac8fcac1fd5959c442d6619f5b758) - Update `lightnet r2 cp` to support Unix-like file overwrite behavior and prompt before overwriting unless `-f` is provided.
+
+- [#439](https://github.com/LightNetDev/LightNet/pull/439) [`2572437`](https://github.com/LightNetDev/LightNet/commit/25724372a47ac8fcac1fd5959c442d6619f5b758) - Allow `lightnet r2 cp` to copy files and prefixes inside the configured R2 bucket with `r2:` source and destination paths.
+
+- [#439](https://github.com/LightNetDev/LightNet/pull/439) [`2572437`](https://github.com/LightNetDev/LightNet/commit/25724372a47ac8fcac1fd5959c442d6619f5b758) - Add `lightnet r2 mv` for moving and renaming files and prefixes inside the configured R2 bucket.
+
+- [#439](https://github.com/LightNetDev/LightNet/pull/439) [`2572437`](https://github.com/LightNetDev/LightNet/commit/25724372a47ac8fcac1fd5959c442d6619f5b758) - Update `lightnet r2 rm` to use OS-style deletion flags with `-r` for recursive prefix removal and `-f` for skipping confirmation.
+
+## 4.5.0
+
+### Minor Changes
+
+- [#437](https://github.com/LightNetDev/LightNet/pull/437) [`91446d3`](https://github.com/LightNetDev/LightNet/commit/91446d3102da0383dfffa836578c02286d0258c9) - Add `lightnet r2` commands for listing, deleting, and copying Cloudflare R2 files through the project R2 configuration.
+
 ## 4.4.2
 
 ### Patch Changes

package/package.json

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

package/src/index.js

@@ -7,6 +7,7 @@ import pkg from "../package.json" with { type: "json" }
 import { checkFiles } from "./check-files.js"
 import { checkLinks } from "./check-links.js"
 import { checkTranslations } from "./check-translations.js"
+import { copyR2, listR2, moveR2, removeR2 } from "./r2.js"
 import { CliError } from "./support/cli-error.js"
 import { PromptCancelled } from "./support/prompt-cancel.js"
 const { version } = pkg
@@ -70,6 +71,71 @@ program
     }
   })
 
+const r2Command = program
+  .command("r2")
+  .description("manage Cloudflare R2 files with rclone")
+
+r2Command
+  .command("ls")
+  .description("list R2 objects")
+  .argument("[path]", "R2 path or prefix")
+  .action(async (path) => {
+    try {
+      await listR2(path)
+    } catch (error) {
+      handleCommandError(error)
+    }
+  })
+
+r2Command
+  .command("rm")
+  .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')
+  .option("-r, --recursive", "delete a directory/prefix recursively")
+  .option(
+    "-f, --force",
+    "delete without confirmation, except when cleaning the bucket root",
+  )
+  .action(async (path, options) => {
+    try {
+      await removeR2(path, options)
+    } catch (error) {
+      handleCommandError(error)
+    }
+  })
+
+r2Command
+  .command("cp")
+  .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 existing files without confirmation")
+  .action(async (source, destination, options) => {
+    try {
+      await copyR2(source, destination, options)
+    } catch (error) {
+      handleCommandError(error)
+    }
+  })
+
+r2Command
+  .command("mv")
+  .description("move or rename an R2 file or directory/prefix")
+  .argument("<source>", "R2 source path")
+  .argument("<destination>", "R2 destination path")
+  .option("-f, --force", "overwrite existing destination without confirmation")
+  .action(async (source, destination, options) => {
+    try {
+      await moveR2(source, destination, options)
+    } catch (error) {
+      handleCommandError(error)
+    }
+  })
+
 await program.parseAsync()
 process.exitCode = commandExitCode
 

package/src/r2.js

@@ -0,0 +1,536 @@
+// @ts-check
+
+import { rm, stat } from "node:fs/promises"
+import { basename, join, posix, resolve } from "node:path"
+import {
+  cwd as processCwd,
+  env as processEnv,
+  stdin,
+  stdout,
+} from "node:process"
+
+import { confirm, isCancel, log, 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:"
+
+/**
+ * @typedef {{
+ *   force?: boolean
+ * }} R2CopyOptions
+ */
+
+/**
+ * @typedef {{
+ *   force?: boolean
+ * }} R2MoveOptions
+ */
+
+/**
+ * @typedef {{
+ *   remote: boolean
+ *   path: string
+ * }} CopyPath
+ */
+
+/** @typedef {"file"|"directory"|"missing"} CopyPathType */
+
+/**
+ * @typedef {{
+ *   force?: boolean
+ *   recursive?: boolean
+ * }} R2RemoveOptions
+ */
+
+/**
+ * @typedef {{
+ *   cwd?: string
+ *   invocationCwd?: string
+ *   isInteractive?: boolean
+ *   promptConfirm?: (message: string) => Promise<boolean>
+ *   promptText?: (message: string) => Promise<string>
+ *   writeStdout?: (message: string) => void
+ * }} R2Runtime
+ */
+
+/**
+ * @param {string|undefined} path
+ * @param {R2Runtime} [runtime]
+ */
+export async function listR2(path, runtime = {}) {
+  const client = createR2CommandClient(runtime)
+  const output = await client.list(path)
+  const writeStdout =
+    runtime.writeStdout ??
+    ((message) => {
+      stdout.write(message)
+    })
+  writeStdout(output)
+}
+
+/**
+ * @param {string} path
+ * @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) {
+    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 interactive = getInteractive(runtime)
+  if (isBucketRoot && !interactive) {
+    throw new CliError(
+      "Cleaning the R2 bucket root requires interactive confirmation.",
+    )
+  }
+  if (!options.force && !interactive) {
+    throw new CliError(
+      'R2 deletion requires confirmation. Re-run with "--force" in non-interactive environments.',
+    )
+  }
+
+  if (isBucketRoot) {
+    log.warn(
+      "This will delete ALL files in the configured R2 bucket. This cannot be undone.",
+    )
+  }
+
+  const shouldDelete = isBucketRoot
+    ? await getPromptConfirm(runtime)(
+        "Delete all files in the R2 bucket? [y/N] ",
+      )
+    : options.force ||
+      (await getPromptConfirm(runtime)(`Delete R2 path "${r2Path}"? [y/N] `))
+
+  if (!shouldDelete) {
+    return
+  }
+
+  const client = createR2CommandClient(runtime)
+  await client.remove(r2Path, {
+    recursive: options.recursive === true,
+  })
+}
+
+/**
+ * @param {string} source
+ * @param {string} destination
+ * @param {R2CopyOptions} [options]
+ * @param {R2Runtime} [runtime]
+ */
+export async function copyR2(source, destination, options = {}, runtime = {}) {
+  const sourcePath = parseCopyPath(source)
+  const destinationPath = parseCopyPath(destination)
+  if (!sourcePath.remote && !destinationPath.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))
+
+  await confirmCopyOverwrite({
+    destination,
+    force: options.force === true,
+    runtime,
+    sourceType,
+    targetPath,
+    targetType,
+  })
+  await replaceCopyTargetBeforeCopy({
+    client,
+    runtime,
+    sourceType,
+    targetPath,
+    targetType,
+  })
+
+  await client.copy(
+    await toRcloneCopyPath(sourcePath, client, runtime),
+    await toRcloneCopyPath(targetPath, client, runtime),
+    { to: shouldUseCopyTo },
+  )
+}
+
+/**
+ * @param {string} source
+ * @param {string} destination
+ * @param {R2MoveOptions} options
+ * @param {R2Runtime} [runtime]
+ */
+export async function moveR2(source, destination, options, runtime = {}) {
+  const sourcePath = parseR2OnlyPath(source, "Move source")
+  const destinationPath = parseR2OnlyPath(destination, "Move destination")
+  if (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))
+
+  await confirmCopyOverwrite({
+    destination,
+    force: options.force === true,
+    runtime,
+    sourceType,
+    targetPath,
+    targetType,
+  })
+  await replaceCopyTargetBeforeCopy({
+    client,
+    runtime,
+    sourceType,
+    targetPath,
+    targetType,
+  })
+
+  await client.move(
+    await toRcloneCopyPath(sourcePath, client, runtime),
+    await toRcloneCopyPath(targetPath, client, runtime),
+    { to: shouldUseMoveTo },
+  )
+}
+
+/**
+ * @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,
+  })
+}
+
+/**
+ * @param {R2Runtime} runtime
+ */
+function createR2CommandClient(runtime) {
+  return createR2Client({
+    cwd: runtime.cwd ?? processCwd(),
+    interactive: getInteractive(runtime),
+    promptText: getPromptText(runtime),
+  })
+}
+
+/**
+ * @param {R2Runtime} runtime
+ */
+function getInteractive(runtime) {
+  return runtime.isInteractive ?? Boolean(stdin.isTTY && stdout.isTTY)
+}
+
+/**
+ * @param {R2Runtime} runtime
+ */
+function getPromptText(runtime) {
+  return runtime.promptText ?? defaultPromptText
+}
+
+/**
+ * @param {R2Runtime} runtime
+ */
+function getPromptConfirm(runtime) {
+  return runtime.promptConfirm ?? defaultPromptConfirm
+}
+
+/**
+ * @param {string} value
+ */
+function parseCopyPath(value) {
+  if (!value.startsWith(remotePathPrefix)) {
+    return { remote: false, path: value }
+  }
+  return { remote: true, path: normalizeR2Path(value) }
+}
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {CopyPath}
+ */
+function parseR2OnlyPath(value, label) {
+  if (value.startsWith(remotePathPrefix)) {
+    return { remote: true, path: normalizeR2Path(value) }
+  }
+  if (value.startsWith("/") || value.startsWith("./") || value === ".") {
+    throw new CliError(`${label} must be an R2 path, not a local path.`)
+  }
+  return { remote: true, path: normalizeR2Path(value) }
+}
+
+/**
+ * @param {{
+ *   destination: CopyPath,
+ *   destinationType: CopyPathType,
+ *   runtime: R2Runtime,
+ *   source: CopyPath,
+ *   sourceType: CopyPathType
+ * }} args
+ * @returns {CopyPath}
+ */
+function getCopyTargetPath({
+  destination,
+  destinationType,
+  runtime,
+  source,
+  sourceType,
+}) {
+  if (sourceType === "directory") {
+    if (destinationType === "file") {
+      throw new CliError("Cannot copy a directory to an existing file.")
+    }
+    return destination
+  }
+
+  if (
+    destinationType === "directory" ||
+    (destinationType === "missing" && isDirectoryLikeCopyPath(destination))
+  ) {
+    return {
+      ...destination,
+      path: joinCopyPath(destination, getCopyPathName(source, runtime)),
+    }
+  }
+
+  return destination
+}
+
+/**
+ * @param {{
+ *   destination: string,
+ *   force: boolean,
+ *   runtime: R2Runtime,
+ *   sourceType: CopyPathType,
+ *   targetPath: CopyPath,
+ *   targetType: CopyPathType
+ * }} args
+ */
+async function confirmCopyOverwrite({
+  destination,
+  force,
+  runtime,
+  sourceType,
+  targetPath,
+  targetType,
+}) {
+  if (targetType === "missing") {
+    return
+  }
+  if (
+    sourceType === "file" &&
+    targetType === "directory" &&
+    !isDirectoryLikeCopyPath(targetPath)
+  ) {
+    throw new CliError("Cannot overwrite an existing directory with a file.")
+  }
+  if (force) {
+    return
+  }
+  if (!getInteractive(runtime)) {
+    throw new CliError(
+      'Copy would overwrite existing files. Re-run with "--force" in non-interactive environments.',
+    )
+  }
+  const shouldOverwrite = await getPromptConfirm(runtime)(
+    `Overwrite existing destination "${destination}"? [y/N] `,
+  )
+  if (!shouldOverwrite) {
+    cancelPrompt()
+  }
+}
+
+/**
+ * @param {CopyPath} copyPath
+ * @param {ReturnType<typeof createR2CommandClient>} client
+ * @param {R2Runtime} runtime
+ * @returns {Promise<CopyPathType>}
+ */
+async function getCopyPathType(copyPath, client, runtime) {
+  if (copyPath.remote) {
+    return client.getPathType(copyPath.path)
+  }
+  try {
+    const stats = await stat(resolveLocalPath(copyPath.path, runtime))
+    return stats.isDirectory() ? "directory" : "file"
+  } catch (error) {
+    if (isLocalNotFoundError(error)) {
+      return "missing"
+    }
+    throw error
+  }
+}
+
+/**
+ * @param {CopyPath} copyPath
+ * @param {ReturnType<typeof createR2CommandClient>} client
+ * @param {R2Runtime} runtime
+ */
+async function toRcloneCopyPath(copyPath, client, runtime) {
+  return copyPath.remote
+    ? await client.toRemotePath(copyPath.path)
+    : resolveLocalPath(copyPath.path, runtime)
+}
+
+/**
+ * @param {CopyPath} copyPath
+ */
+function isDirectoryLikeCopyPath(copyPath) {
+  return copyPath.path === "." || copyPath.path.endsWith("/")
+}
+
+/**
+ * @param {CopyPath} parent
+ * @param {string} child
+ */
+function joinCopyPath(parent, child) {
+  if (parent.remote) {
+    return parent.path ? posix.join(parent.path, child) : child
+  }
+  return join(parent.path, child)
+}
+
+/**
+ * @param {CopyPath} copyPath
+ * @param {R2Runtime} runtime
+ */
+function getCopyPathName(copyPath, runtime) {
+  return copyPath.remote
+    ? posix.basename(copyPath.path.replace(/\/+$/, ""))
+    : basename(resolveLocalPath(copyPath.path, runtime))
+}
+
+/**
+ * @param {string} path
+ * @param {R2Runtime} runtime
+ */
+function resolveLocalPath(path, runtime) {
+  return resolve(getInvocationCwd(runtime), path)
+}
+
+/**
+ * @param {R2Runtime} runtime
+ */
+function getInvocationCwd(runtime) {
+  return runtime.invocationCwd ?? processEnv.INIT_CWD ?? processCwd()
+}
+
+/**
+ * @param {string|undefined} path
+ */
+function normalizeR2Path(path) {
+  return path?.replace(/^r2:/, "").replace(/^\/+/, "") ?? ""
+}
+
+/**
+ * @param {string} path
+ */
+function isR2BucketRootPath(path) {
+  return path.trim() === "/"
+}
+
+/**
+ * @param {unknown} error
+ */
+function isLocalNotFoundError(error) {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  )
+}
+
+/**
+ * @param {string} message
+ */
+async function defaultPromptText(message) {
+  const answer = await text({ message })
+  if (isCancel(answer)) {
+    cancelPrompt()
+  }
+  return String(answer)
+}
+
+/**
+ * @param {string} message
+ */
+async function defaultPromptConfirm(message) {
+  const answer = await confirm({
+    message,
+    initialValue: false,
+  })
+  if (isCancel(answer)) {
+    cancelPrompt()
+  }
+  return answer
+}

package/src/support/r2.js

@@ -90,7 +90,7 @@ export function createR2FileStorage({
   /** @returns {Promise<string>} */
   const getSecretAccessKey = async () => {
     if (!secretAccessKey) {
-      secretAccessKey = await promptRequiredSecret()
+      secretAccessKey = await promptRequiredSecret({ interactive })
     }
     return secretAccessKey
   }
@@ -166,6 +166,157 @@ export function createR2FileStorage({
   return storage
 }
 
+/**
+ * @param {{
+ *   cwd: string
+ *   interactive: boolean
+ *   promptText: (message: string) => Promise<string>
+ * }} args
+ */
+export function createR2Client({ cwd, interactive, promptText }) {
+  /** @type {R2Config|undefined} */
+  let config
+  /** @type {string|undefined} */
+  let secretAccessKey
+
+  /** @returns {Promise<R2Config>} */
+  const getConfig = async () => {
+    if (config) {
+      return config
+    }
+    const initializedConfig = await initR2Config({
+      cwd,
+      interactive,
+      promptText,
+    })
+    config = initializedConfig
+    return initializedConfig
+  }
+
+  /** @returns {Promise<string>} */
+  const getSecretAccessKey = async () => {
+    if (!secretAccessKey) {
+      secretAccessKey = await promptRequiredSecret({ interactive })
+    }
+    return secretAccessKey
+  }
+
+  return {
+    /**
+     * @param {string} [path]
+     */
+    async list(path) {
+      const r2Config = await getConfig()
+      const result = await runConfiguredRclone({
+        args: [
+          "lsf",
+          makeR2Path(r2Config, normalizeR2ObjectPath(path)),
+          "--recursive",
+          "--files-only",
+        ],
+        cwd,
+        config: r2Config,
+        secretAccessKey: await getSecretAccessKey(),
+      })
+      return result.stdout
+    },
+    /**
+     * @param {string} path
+     * @param {{recursive?: boolean}} [options]
+     */
+    async remove(path, options = {}) {
+      const r2Config = await getConfig()
+      const secretAccessKey = await getSecretAccessKey()
+      const r2Path = makeR2Path(r2Config, normalizeR2ObjectPath(path))
+      await runConfiguredRclone({
+        args: options.recursive
+          ? ["delete", r2Path, "--rmdirs"]
+          : ["deletefile", r2Path],
+        cwd,
+        config: r2Config,
+        secretAccessKey,
+      })
+    },
+    /**
+     * @param {string} source
+     * @param {string} destination
+     * @param {{to?: boolean}} [options]
+     */
+    async copy(source, destination, options = {}) {
+      const r2Config = await getConfig()
+      await runConfiguredRclone({
+        args: [options.to ? "copyto" : "copy", source, destination],
+        cwd,
+        config: r2Config,
+        secretAccessKey: await getSecretAccessKey(),
+      })
+    },
+    /**
+     * @param {string} source
+     * @param {string} destination
+     * @param {{to?: boolean}} [options]
+     */
+    async move(source, destination, options = {}) {
+      const r2Config = await getConfig()
+      await runConfiguredRclone({
+        args: [options.to ? "moveto" : "move", source, destination],
+        cwd,
+        config: r2Config,
+        secretAccessKey: await getSecretAccessKey(),
+      })
+    },
+    /**
+     * @param {string} path
+     * @returns {Promise<"file"|"directory"|"missing">}
+     */
+    async getPathType(path) {
+      const normalizedPath = normalizeR2ObjectPath(path)
+      if (!normalizedPath) {
+        return "directory"
+      }
+      const r2Config = await getConfig()
+      try {
+        const result = await runConfiguredRclone({
+          args: [
+            "lsjson",
+            makeR2Path(r2Config, normalizedPath),
+            "--max-depth",
+            "1",
+            "--no-mimetype",
+            "--no-modtime",
+          ],
+          cwd,
+          config: r2Config,
+          secretAccessKey: await getSecretAccessKey(),
+        })
+        const entries = parseRcloneJsonList(result.stdout)
+        if (entries.length === 0) {
+          return "missing"
+        }
+        if (
+          entries.length === 1 &&
+          !entries[0].isDir &&
+          entries[0].name === getR2PathName(normalizedPath)
+        ) {
+          return "file"
+        }
+        return "directory"
+      } catch (error) {
+        if (isRcloneNotFoundError(error)) {
+          return "missing"
+        }
+        throw error
+      }
+    },
+    /**
+     * @param {string} path
+     */
+    async toRemotePath(path) {
+      return makeR2Path(await getConfig(), normalizeR2ObjectPath(path))
+    },
+  }
+}
+
 /**
  * @param {string} path
  */
@@ -366,6 +517,7 @@ async function runConfiguredRclone({ args, cwd, config, secretAccessKey }) {
         "auto",
         "--s3-endpoint",
         getR2Endpoint(config.accountId),
+        "--s3-no-check-bucket",
       ],
       cwd,
       env,
@@ -400,14 +552,21 @@ async function promptForR2Config({ cwd, promptText }) {
 }
 
 /**
+ * @param {{interactive?: boolean}} [args]
  * @returns {Promise<string>}
  */
-async function promptRequiredSecret() {
+async function promptRequiredSecret({ interactive = true } = {}) {
   const sessionSecret = processEnv[sessionSecretEnvName]
   if (typeof sessionSecret === "string" && sessionSecret.trim()) {
     return sessionSecret
   }
 
+  if (!interactive) {
+    throw new CliError(
+      `Missing R2 secret access key. Set ${sessionSecretEnvName} in non-interactive environments.`,
+    )
+  }
+
   while (true) {
     const value = await password({
       message: "R2 secretAccessKey:",
@@ -422,6 +581,47 @@ async function promptRequiredSecret() {
   }
 }
 
+/**
+ * @param {string} [path]
+ */
+function normalizeR2ObjectPath(path) {
+  return path?.replace(/^r2:/, "").replace(/^\/+/, "") ?? ""
+}
+
+/**
+ * @param {string} output
+ * @returns {{name:string, isDir:boolean}[]}
+ */
+function parseRcloneJsonList(output) {
+  const parsed = JSON.parse(output)
+  if (!Array.isArray(parsed)) {
+    throw new CliError("Unexpected rclone JSON listing output.")
+  }
+  return parsed
+    .filter((item) => isPlainObject(item) && typeof item.Name === "string")
+    .map((item) => ({
+      name: String(item.Name),
+      isDir: item.IsDir === true,
+    }))
+}
+
+/**
+ * @param {string} path
+ */
+function getR2PathName(path) {
+  return path.replace(/\/+$/, "").split("/").at(-1) ?? ""
+}
+
+/**
+ * @param {unknown} error
+ */
+function isRcloneNotFoundError(error) {
+  return (
+    error instanceof Error &&
+    /not found|directory not found|object not found/i.test(error.message)
+  )
+}
+
 /**
  * @param {(message:string)=>Promise<string>} promptText
  * @param {string} message