@lightnet/cli 4.4.1 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @lightnet/cli
 
+## 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
+
+- [#433](https://github.com/LightNetDev/LightNet/pull/433) [`dbde36e`](https://github.com/LightNetDev/LightNet/commit/dbde36e7a25bf6470783e9594260b666e09c2783) - Make `check-files` summaries clearer by explaining what was compared and what needs attention.
+
+- [#433](https://github.com/LightNetDev/LightNet/pull/433) [`dbde36e`](https://github.com/LightNetDev/LightNet/commit/dbde36e7a25bf6470783e9594260b666e09c2783) - Handle Ctrl+C cancellation consistently for interactive `check-*` command prompts.
+
+- [#433](https://github.com/LightNetDev/LightNet/pull/433) [`dbde36e`](https://github.com/LightNetDev/LightNet/commit/dbde36e7a25bf6470783e9594260b666e09c2783) - Replace `check-files --fix --no-confirm` with `check-files --fix-without-confirm` for non-interactive cleanup.
+
+- [#433](https://github.com/LightNetDev/LightNet/pull/433) [`dbde36e`](https://github.com/LightNetDev/LightNet/commit/dbde36e7a25bf6470783e9594260b666e09c2783) - Treat warning-only `check-files` runs as successful when no local content file references are found.
+
+- [#433](https://github.com/LightNetDev/LightNet/pull/433) [`dbde36e`](https://github.com/LightNetDev/LightNet/commit/dbde36e7a25bf6470783e9594260b666e09c2783) - Improve `check-files` and `check-links` output for long referenced paths and URLs.
+
 ## 4.4.1
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "CLI for managing LightNet projects",
   "type": "module",
   "license": "MIT",
-  "version": "4.4.1",
+  "version": "4.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -25,8 +25,8 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "commander": "^15.0.0",
-    "@clack/prompts": "^1.6.0"
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0"
   },
   "engines": {
     "node": ">=22"

package/src/check-files.js

@@ -21,6 +21,7 @@ import {
   pathExists,
   toLocalContentDisplayPath,
 } from "./support/filesystem.js"
+import { cancelPrompt } from "./support/prompt-cancel.js"
 import { createR2FileStorage } from "./support/r2.js"
 
 const supportedScopes = new Set(["content-files", "thumbnails"])
@@ -33,7 +34,7 @@ const categoryImagesDir = "src/content/categories/images"
  * @typedef {{
  *   scope?: string
  *   fix?: boolean
- *   confirm?: boolean
+ *   fixWithoutConfirm?: boolean
  *   r2?: boolean
  * }} CheckFilesOptions
  */
@@ -170,7 +171,7 @@ export async function checkFiles(options, runtime = {}) {
       orphanedContentFiles = localContentResult.orphanedFiles
       if (localContentResult.referenceCount === 0) {
         warnings.push(
-          'No local "/files" content file references found. Use "--scope=thumbnails" or run with "--r2".',
+          'No local "/files" content file references found. If your content files are stored in R2, consider re-running with "--r2".',
         )
       }
     }
@@ -180,8 +181,7 @@ export async function checkFiles(options, runtime = {}) {
     const thumbnailsResult = await runSpinner({
       error: "Thumbnail check failed.",
       start: "Checking thumbnails",
-      stop: (result) =>
-        `Checked thumbnails: ${result.orphanedMediaThumbnails.length} orphaned media, ${result.orphanedCategoryThumbnails.length} orphaned categories.`,
+      stop: (result) => formatThumbnailCheckSummary(result),
       task: () =>
         validateThumbnails(
           mediaItems,
@@ -194,7 +194,7 @@ export async function checkFiles(options, runtime = {}) {
     orphanedCategoryThumbnails = thumbnailsResult.orphanedCategoryThumbnails
   }
 
-  if (options.fix) {
+  if (options.fix || options.fixWithoutConfirm) {
     /** @type {{displayPath:string, target:string}[]} */
     const deletions = []
     /** @type {{displayPath:string, target:string}[]} */
@@ -230,10 +230,10 @@ export async function checkFiles(options, runtime = {}) {
     }
 
     if (deletions.length > 0) {
-      const shouldSkipConfirmation = options.confirm === false
+      const shouldSkipConfirmation = options.fixWithoutConfirm === true
       if (!shouldSkipConfirmation && !interactive) {
         throw new CliError(
-          'Deletion requires confirmation. Re-run with "--fix --no-confirm" in non-interactive environments.',
+          'Deletion requires confirmation. Re-run with "--fix-without-confirm" in non-interactive environments.',
         )
       }
       const shouldDelete =
@@ -315,22 +315,21 @@ export async function checkFiles(options, runtime = {}) {
   }
 
   const hasIssues =
-    warnings.length > 0 ||
     missingContentFiles.length > 0 ||
     wrongTypeR2ContentFiles.length > 0 ||
     orphanedContentFiles.length > 0 ||
     orphanedMediaThumbnails.length > 0 ||
     orphanedCategoryThumbnails.length > 0
 
+  for (const warning of warnings) {
+    log.warn(warning)
+  }
+
   if (!hasIssues && removedItems.length === 0) {
     outro("No issues found. 🎉")
     return true
   }
 
-  for (const warning of warnings) {
-    log.warn(warning)
-  }
-
   printMissingReferenceSection(
     "Missing referenced content files",
     missingContentFiles,
@@ -378,9 +377,7 @@ function printMissingReferenceSection(title, items) {
   }
   log.error(`${title} (${items.length})`)
   for (const item of items) {
-    log.message(
-      `• ${item.path} (referenced by ${item.sources.toSorted().join(", ")})`,
-    )
+    log.message(`• ${item.path}\n${formatReferenceSources(item.sources)}`)
   }
 }
 
@@ -395,11 +392,25 @@ function printWrongTypeReferenceSection(title, items) {
   log.warn(`${title} (${items.length})`)
   for (const item of items) {
     log.message(
-      `• ${item.path} should use type "upload" (referenced by ${item.sources.toSorted().join(", ")})`,
+      `• ${item.path}\n  Expected type: "upload"\n${formatReferenceSources(item.sources)}`,
     )
   }
 }
 
+/**
+ * @param {string[]} sources
+ */
+function formatReferenceSources(sources) {
+  const sortedSources = sources.toSorted()
+  if (sortedSources.length === 1) {
+    return `  Referenced by: ${sortedSources[0]}`
+  }
+  return [
+    "  Referenced by:",
+    ...sortedSources.map((source) => `  - ${source}`),
+  ].join("\n")
+}
+
 /**
  * @template T
  * @param {{
@@ -425,13 +436,58 @@ async function runSpinner({ error, start, stop, task }) {
 
 /**
  * @param {{
+ *   fileCount: number
  *   missingReferences: MissingReference[]
  *   orphanedFiles: string[]
  *   referenceCount: number
  * }} result
  */
 function formatContentCheckSummary(result) {
-  return `Checked content files: ${result.referenceCount} references, ${result.missingReferences.length} missing, ${result.orphanedFiles.length} orphaned.`
+  const issues = [
+    formatFindingCount(result.missingReferences.length, "missing reference"),
+    formatFindingCount(result.orphanedFiles.length, "orphaned file"),
+  ]
+
+  if (result.referenceCount === 0 && result.fileCount === 0) {
+    return `Content files: none found.`
+  }
+
+  return `Content files: ${formatCount(result.referenceCount, "reference")}, ${formatCount(result.fileCount, "file")}; ${issues.join(", ")}.`
+}
+
+/**
+ * @param {{
+ *   fileCount: number
+ *   orphanedCategoryThumbnails: string[]
+ *   orphanedMediaThumbnails: string[]
+ *   referenceCount: number
+ * }} result
+ */
+function formatThumbnailCheckSummary(result) {
+  const orphanedThumbnails =
+    result.orphanedMediaThumbnails.length +
+    result.orphanedCategoryThumbnails.length
+
+  return `Thumbnails: ${formatCount(result.referenceCount, "reference")}, ${formatCount(result.fileCount, "file")}; orphaned: ${orphanedThumbnails} (${result.orphanedMediaThumbnails.length} media, ${result.orphanedCategoryThumbnails.length} categories).`
+}
+
+/**
+ * @param {number} count
+ * @param {string} singular
+ */
+function formatFindingCount(count, singular) {
+  if (count === 0) {
+    return `no ${singular}s`
+  }
+  return formatCount(count, singular)
+}
+
+/**
+ * @param {number} count
+ * @param {string} singular
+ */
+function formatCount(count, singular) {
+  return `${count} ${singular}${count === 1 ? "" : "s"}`
 }
 
 /**
@@ -515,12 +571,14 @@ async function validateThumbnails(
   ])
 
   return {
+    fileCount: mediaFiles.length + categoryFiles.length,
     orphanedMediaThumbnails: mediaFiles.filter(
       (file) => !mediaReferences.has(file),
     ),
     orphanedCategoryThumbnails: categoryFiles.filter(
       (file) => !categoryReferences.has(file),
     ),
+    referenceCount: mediaReferences.size + categoryReferences.size,
   }
 }
 
@@ -542,8 +600,10 @@ async function validateContentFiles({
     initializedStorage,
     { includeLinkReferences },
   )
+  const files = await initializedStorage.list()
   if (references.size === 0) {
     return {
+      fileCount: files.length,
       missingReferences: /** @type {MissingReference[]} */ ([]),
       orphanedFiles: /** @type {string[]} */ ([]),
       referenceCount: 0,
@@ -551,7 +611,6 @@ async function validateContentFiles({
     }
   }
 
-  const files = await initializedStorage.list()
   const fileSet = new Set(files)
 
   const missingReferences = [...references.entries()]
@@ -575,6 +634,7 @@ async function validateContentFiles({
     .sort((a, b) => a.path.localeCompare(b.path))
 
   return {
+    fileCount: files.length,
     missingReferences,
     orphanedFiles,
     referenceCount: references.size,
@@ -695,7 +755,10 @@ function toPosixPath(filePath) {
  */
 async function defaultPromptText(message) {
   const answer = await text({ message })
-  return isCancel(answer) ? "" : String(answer)
+  if (isCancel(answer)) {
+    cancelPrompt()
+  }
+  return String(answer)
 }
 
 /**
@@ -706,5 +769,8 @@ async function defaultPromptConfirm(message) {
     message,
     initialValue: false,
   })
-  return isCancel(answer) ? false : answer
+  if (isCancel(answer)) {
+    cancelPrompt()
+  }
+  return answer
 }

package/src/check-links.js

@@ -13,6 +13,7 @@ import {
 import { CliError } from "./support/cli-error.js"
 import { contentCollections } from "./support/content-collections.js"
 import { pathExists } from "./support/filesystem.js"
+import { cancelPrompt } from "./support/prompt-cancel.js"
 
 const mediaDir = "src/content/media"
 const defaultConcurrency = 24
@@ -126,11 +127,7 @@ export async function checkLinks(options, runtime = {}) {
   log.error(`Unavailable links (${unavailableLinks.length})`)
   for (const { reference, result } of unavailableLinks) {
     log.message(
-      `· ${reference.displayUrl} (${formatFailure(result)}, referenced by ${[
-        ...reference.sources,
-      ]
-        .toSorted()
-        .join(", ")})`,
+      `• ${reference.displayUrl}\n  Result: ${formatFailure(result)}\n${formatReferenceSources(reference.sources)}`,
     )
   }
 
@@ -332,15 +329,25 @@ function printProtectedLinks(links) {
   log.warn(`Protected or forbidden links (${links.length})`)
   for (const { reference, result } of links) {
     log.message(
-      `· ${reference.displayUrl} (${formatFailure(result)}, referenced by ${[
-        ...reference.sources,
-      ]
-        .toSorted()
-        .join(", ")})`,
+      `• ${reference.displayUrl}\n  Result: ${formatFailure(result)}\n${formatReferenceSources(reference.sources)}`,
     )
   }
 }
 
+/**
+ * @param {Set<string>} sources
+ */
+function formatReferenceSources(sources) {
+  const sortedSources = [...sources].toSorted()
+  if (sortedSources.length === 1) {
+    return `  Referenced by: ${sortedSources[0]}`
+  }
+  return [
+    "  Referenced by:",
+    ...sortedSources.map((source) => `  - ${source}`),
+  ].join("\n")
+}
+
 /**
  * @param {string} url
  * @param {{
@@ -483,7 +490,10 @@ function toPosixPath(filePath) {
  */
 async function defaultPromptText(message) {
   const answer = await text({ message })
-  return isCancel(answer) ? "" : String(answer)
+  if (isCancel(answer)) {
+    cancelPrompt()
+  }
+  return String(answer)
 }
 
 /**

package/src/check-translations.js

@@ -5,7 +5,9 @@ import { readFile } from "node:fs/promises"
 import { resolve } from "node:path"
 import { cwd } from "node:process"
 
-import { confirm, intro, log, outro, taskLog } from "@clack/prompts"
+import { confirm, intro, isCancel, log, outro, taskLog } from "@clack/prompts"
+
+import { cancelPrompt } from "./support/prompt-cancel.js"
 
 /**
  * @typedef {{
@@ -100,13 +102,7 @@ export async function checkTranslations(options = {}) {
  * @returns
  */
 async function runBuild(build) {
-  const shouldRunBuild =
-    build ??
-    (await confirm({
-      message:
-        "Run pnpm build now? Command requires an up-to-date dist/ directory.",
-      initialValue: false,
-    }))
+  const shouldRunBuild = build ?? (await promptRunBuild())
   if (!shouldRunBuild) {
     return true
   }
@@ -158,6 +154,18 @@ async function runBuild(build) {
   }
 }
 
+async function promptRunBuild() {
+  const answer = await confirm({
+    message:
+      "Run pnpm build now? Command requires an up-to-date dist/ directory.",
+    initialValue: false,
+  })
+  if (isCancel(answer)) {
+    cancelPrompt()
+  }
+  return answer
+}
+
 /**
  *
  * @param {{title:string, action:string}} source

package/src/index.js

@@ -7,7 +7,9 @@ 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, removeR2 } from "./r2.js"
 import { CliError } from "./support/cli-error.js"
+import { PromptCancelled } from "./support/prompt-cancel.js"
 const { version } = pkg
 
 const program = new Command()
@@ -24,8 +26,12 @@ program
   .option("--build", "run pnpm build before checking translations")
   .option("--no-build", "skip the build prompt and use the latest dist/ output")
   .action(async (options) => {
-    const checkSuccessful = await checkTranslations(options)
-    commandExitCode = checkSuccessful ? 0 : 1
+    try {
+      const checkSuccessful = await checkTranslations(options)
+      commandExitCode = checkSuccessful ? 0 : 1
+    } catch (error) {
+      handleCommandError(error)
+    }
   })
 
 program
@@ -34,7 +40,7 @@ program
     "check for missing and orphaned content files and thumbnails in a LightNet site",
   )
   .option("--fix", "remove orphaned files")
-  .option("--no-confirm", "skip deletion confirmation when used with --fix")
+  .option("--fix-without-confirm", "remove orphaned files without confirmation")
   .option(
     "--r2",
     "validate remote content files in Cloudflare R2 instead of public/files",
@@ -48,12 +54,7 @@ program
       const checkSuccessful = await checkFiles(options)
       commandExitCode = checkSuccessful ? 0 : 1
     } catch (error) {
-      if (error instanceof CliError) {
-        console.error(error.message)
-        commandExitCode = 1
-        return
-      }
-      throw error
+      handleCommandError(error)
     }
   })
 
@@ -66,14 +67,70 @@ program
       const checkSuccessful = await checkLinks(options)
       commandExitCode = checkSuccessful ? 0 : 1
     } catch (error) {
-      if (error instanceof CliError) {
-        console.error(error.message)
-        commandExitCode = 1
-        return
-      }
-      throw error
+      handleCommandError(error)
+    }
+  })
+
+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")
+  .argument("<path>", "R2 file path, or directory/prefix with -r")
+  .option("-r, --recursive", "delete a directory/prefix recursively")
+  .option("-f, --force", "delete without confirmation")
+  .action(async (path, options) => {
+    try {
+      await removeR2(path, options)
+    } catch (error) {
+      handleCommandError(error)
+    }
+  })
+
+r2Command
+  .command("cp")
+  .description(
+    'copy files between R2 and the local filesystem; prefix the R2 side with "r2:"',
+  )
+  .argument("<source>", 'source path; use "r2:<path>" for R2')
+  .argument("<destination>", 'destination path; use "r2:<path>" for R2')
+  .action(async (source, destination) => {
+    try {
+      await copyR2(source, destination)
+    } catch (error) {
+      handleCommandError(error)
     }
   })
 
 await program.parseAsync()
 process.exitCode = commandExitCode
+
+/**
+ * @param {unknown} error
+ */
+function handleCommandError(error) {
+  if (error instanceof PromptCancelled) {
+    commandExitCode = 0
+    return
+  }
+  if (error instanceof CliError) {
+    console.error(error.message)
+    commandExitCode = 1
+    return
+  }
+  throw error
+}

package/src/r2.js

@@ -0,0 +1,196 @@
+// @ts-check
+
+import { resolve } from "node:path"
+import {
+  cwd as processCwd,
+  env as processEnv,
+  stdin,
+  stdout,
+} from "node:process"
+
+import { confirm, isCancel, 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
+ *   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)
+  if (!r2Path) {
+    throw new CliError("Refusing to delete the R2 bucket root.")
+  }
+
+  const interactive = getInteractive(runtime)
+  if (!options.force && !interactive) {
+    throw new CliError(
+      'R2 deletion requires confirmation. Re-run with "--force" in non-interactive environments.',
+    )
+  }
+
+  const shouldDelete =
+    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 {R2Runtime} [runtime]
+ */
+export async function copyR2(source, destination, runtime = {}) {
+  const sourcePath = parseCopyPath(source)
+  const destinationPath = parseCopyPath(destination)
+  if (sourcePath.remote === destinationPath.remote) {
+    throw new CliError(
+      `R2 copy requires exactly one R2 path. Prefix the remote side with "${remotePathPrefix}".`,
+    )
+  }
+
+  const client = createR2CommandClient(runtime)
+  const rcloneSource = sourcePath.remote
+    ? await client.toRemotePath(sourcePath.path)
+    : resolveLocalPath(sourcePath.path, runtime)
+  const rcloneDestination = destinationPath.remote
+    ? await client.toRemotePath(destinationPath.path)
+    : resolveLocalPath(destinationPath.path, runtime)
+
+  await client.copy(rcloneSource, rcloneDestination)
+}
+
+/**
+ * @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} 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} 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/prompt-cancel.js

@@ -0,0 +1,13 @@
+// @ts-check
+
+import { cancel } from "@clack/prompts"
+
+export class PromptCancelled extends Error {}
+
+/**
+ * @returns {never}
+ */
+export function cancelPrompt() {
+  cancel("Operation cancelled.")
+  throw new PromptCancelled()
+}

package/src/support/r2.js

@@ -15,6 +15,7 @@ import {
   writeCliConfig,
 } from "./cli-config.js"
 import { CliError } from "./cli-error.js"
+import { cancelPrompt } from "./prompt-cancel.js"
 
 const execFileAsync = promisify(execFile)
 const sessionSecretEnvName = "LIGHTNET_R2_SECRET_ACCESS_KEY"
@@ -89,7 +90,7 @@ export function createR2FileStorage({
   /** @returns {Promise<string>} */
   const getSecretAccessKey = async () => {
     if (!secretAccessKey) {
-      secretAccessKey = await promptRequiredSecret()
+      secretAccessKey = await promptRequiredSecret({ interactive })
     }
     return secretAccessKey
   }
@@ -165,6 +166,99 @@ 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
+     */
+    async copy(source, destination) {
+      const r2Config = await getConfig()
+      await runConfiguredRclone({
+        args: ["copy", source, destination],
+        cwd,
+        config: r2Config,
+        secretAccessKey: await getSecretAccessKey(),
+      })
+    },
+    /**
+     * @param {string} path
+     */
+    async toRemotePath(path) {
+      return makeR2Path(await getConfig(), normalizeR2ObjectPath(path))
+    },
+  }
+}
+
 /**
  * @param {string} path
  */
@@ -365,6 +459,7 @@ async function runConfiguredRclone({ args, cwd, config, secretAccessKey }) {
         "auto",
         "--s3-endpoint",
         getR2Endpoint(config.accountId),
+        "--s3-no-check-bucket",
       ],
       cwd,
       env,
@@ -399,20 +494,27 @@ 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:",
     })
     if (isCancel(value)) {
-      throw new CliError("Secret access key prompt cancelled.")
+      cancelPrompt()
     }
     if (value.trim()) {
       processEnv[sessionSecretEnvName] = value
@@ -421,6 +523,13 @@ async function promptRequiredSecret() {
   }
 }
 
+/**
+ * @param {string} [path]
+ */
+function normalizeR2ObjectPath(path) {
+  return path?.replace(/^r2:/, "").replace(/^\/+/, "") ?? ""
+}
+
 /**
  * @param {(message:string)=>Promise<string>} promptText
  * @param {string} message