@lightnet/cli 4.4.0 → 4.4.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @lightnet/cli
 
+## 4.4.1
+
+### Patch Changes
+
+- [#431](https://github.com/LightNetDev/LightNet/pull/431) [`aa5968f`](https://github.com/LightNetDev/LightNet/commit/aa5968f26112f93121f03e7aafdfb04018186032) - Delete orphaned R2 objects from `check-files --fix --r2` in batches instead of spawning one rclone process per file.
+
+- [#431](https://github.com/LightNetDev/LightNet/pull/431) [`aa5968f`](https://github.com/LightNetDev/LightNet/commit/aa5968f26112f93121f03e7aafdfb04018186032) - Show progress feedback while `check-files` and `check-links` perform long-running checks.
+
+- [#431](https://github.com/LightNetDev/LightNet/pull/431) [`aa5968f`](https://github.com/LightNetDev/LightNet/commit/aa5968f26112f93121f03e7aafdfb04018186032) - Improve `check-files` performance by avoiding duplicate R2 listings and parallelizing independent filesystem work.
+
+- [#431](https://github.com/LightNetDev/LightNet/pull/431) [`aa5968f`](https://github.com/LightNetDev/LightNet/commit/aa5968f26112f93121f03e7aafdfb04018186032) - Protect R2 objects referenced by media content links from `check-files --fix --r2` cleanup and warn that they should use upload content.
+
+- [#431](https://github.com/LightNetDev/LightNet/pull/431) [`aa5968f`](https://github.com/LightNetDev/LightNet/commit/aa5968f26112f93121f03e7aafdfb04018186032) - Decode percent-encoded R2 public URLs when matching `check-files --r2` references against bucket objects.
+
 ## 4.4.0
 
 ### Minor Changes

package/package.json

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

package/src/check-files.js

@@ -3,7 +3,15 @@
 import { join, posix, resolve } from "node:path"
 import { cwd as processCwd, stdin, stdout } from "node:process"
 
-import { confirm, intro, isCancel, log, outro, text } from "@clack/prompts"
+import {
+  confirm,
+  intro,
+  isCancel,
+  log,
+  outro,
+  spinner,
+  text,
+} from "@clack/prompts"
 
 import { CliError } from "./support/cli-error.js"
 import { contentCollections } from "./support/content-collections.js"
@@ -48,6 +56,8 @@ const categoryImagesDir = "src/content/categories/images"
  * }} FileReference
  */
 
+/** @typedef {MissingReference} WrongTypeReference */
+
 /**
  * @typedef {{
  *   cwd?: string
@@ -79,14 +89,15 @@ export async function checkFiles(options, runtime = {}) {
   await assertLightNetSiteRoot(cwd)
 
   const collections = contentCollections(cwd)
-  const mediaItems = await collections.getMediaItems()
-  const categories = await collections.getCategories()
-  log.message(
-    `Checking ${mediaItems.length} media items and ${categories.length} categories.`,
-  )
+  const [mediaItems, categories] = await Promise.all([
+    collections.getMediaItems(),
+    collections.getCategories(),
+  ])
 
   /** @type {MissingReference[]} */
   let missingContentFiles = []
+  /** @type {WrongTypeReference[]} */
+  let wrongTypeR2ContentFiles = []
   /** @type {string[]} */
   let orphanedContentFiles = []
   /** @type {string[]} */
@@ -104,18 +115,40 @@ export async function checkFiles(options, runtime = {}) {
   const categoryThumbnailStorage = files(cwd, { rootDir: categoryImagesDir })
 
   if (includeContentFiles) {
+    contentFileStorage = options.r2
+      ? createR2FileStorage({
+          cwd,
+          interactive,
+          promptConfirm,
+          promptText,
+        })
+      : contentFiles(cwd)
+    contentFileStorage = await contentFileStorage.init()
+  }
+
+  log.message(
+    `Checking ${mediaItems.length} media items and ${categories.length} categories.`,
+  )
+
+  if (includeContentFiles) {
+    if (!contentFileStorage) {
+      throw new CliError("Missing file storage for content validation.")
+    }
+    const initializedContentFileStorage = contentFileStorage
     if (options.r2) {
-      contentFileStorage = createR2FileStorage({
-        cwd,
-        interactive,
-        promptConfirm,
-        promptText,
-      })
-      const r2Result = await validateContentFiles({
-        mediaItems,
-        storage: contentFileStorage,
+      const r2Result = await runSpinner({
+        error: "Content file check failed.",
+        start: "Listing R2 objects and checking content file references",
+        stop: (result) => formatContentCheckSummary(result),
+        task: () =>
+          validateContentFiles({
+            includeLinkReferences: true,
+            mediaItems,
+            storage: initializedContentFileStorage,
+          }),
       })
       missingContentFiles = r2Result.missingReferences
+      wrongTypeR2ContentFiles = r2Result.wrongTypeReferences
       orphanedContentFiles = r2Result.orphanedFiles
       if (r2Result.referenceCount === 0) {
         warnings.push(
@@ -123,10 +156,15 @@ export async function checkFiles(options, runtime = {}) {
         )
       }
     } else {
-      contentFileStorage = contentFiles(cwd)
-      const localContentResult = await validateContentFiles({
-        mediaItems,
-        storage: contentFileStorage,
+      const localContentResult = await runSpinner({
+        error: "Content file check failed.",
+        start: "Checking local content files",
+        stop: (result) => formatContentCheckSummary(result),
+        task: () =>
+          validateContentFiles({
+            mediaItems,
+            storage: initializedContentFileStorage,
+          }),
       })
       missingContentFiles = localContentResult.missingReferences
       orphanedContentFiles = localContentResult.orphanedFiles
@@ -139,12 +177,19 @@ export async function checkFiles(options, runtime = {}) {
   }
 
   if (includeThumbnails) {
-    const thumbnailsResult = await validateThumbnails(
-      mediaItems,
-      categories,
-      mediaThumbnailStorage,
-      categoryThumbnailStorage,
-    )
+    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.`,
+      task: () =>
+        validateThumbnails(
+          mediaItems,
+          categories,
+          mediaThumbnailStorage,
+          categoryThumbnailStorage,
+        ),
+    })
     orphanedMediaThumbnails = thumbnailsResult.orphanedMediaThumbnails
     orphanedCategoryThumbnails = thumbnailsResult.orphanedCategoryThumbnails
   }
@@ -199,25 +244,52 @@ export async function checkFiles(options, runtime = {}) {
         }))
 
       if (shouldDelete) {
-        const deletedContentTargets = contentFileStorage
-          ? await contentFileStorage.delete(
-              contentDeletions.map((deletion) => deletion.target),
-            )
-          : []
-        const deletedLocalTargets = [
-          ...(await mediaThumbnailStorage.delete(
-            localDeletions
-              .filter((deletion) => deletion.target.startsWith(mediaImagesDir))
-              .map((deletion) => deletion.target),
-          )),
-          ...(await categoryThumbnailStorage.delete(
-            localDeletions
-              .filter((deletion) =>
-                deletion.target.startsWith(categoryImagesDir),
-              )
-              .map((deletion) => deletion.target),
-          )),
-        ]
+        const { deletedContentTargets, deletedLocalTargets } = await runSpinner(
+          {
+            error: "File deletion failed.",
+            start: formatDeletionProgress("Deleting", deletions.length),
+            stop: (result) => {
+              const deletedCount =
+                result.deletedContentTargets.length +
+                result.deletedLocalTargets.length
+              return formatDeletionProgress("Deleted", deletedCount)
+            },
+            task: async () => {
+              const [
+                deletedContentTargets,
+                deletedMediaThumbnailTargets,
+                deletedCategoryThumbnailTargets,
+              ] = await Promise.all([
+                contentFileStorage
+                  ? contentFileStorage.delete(
+                      contentDeletions.map((deletion) => deletion.target),
+                    )
+                  : [],
+                mediaThumbnailStorage.delete(
+                  localDeletions
+                    .filter((deletion) =>
+                      deletion.target.startsWith(mediaImagesDir),
+                    )
+                    .map((deletion) => deletion.target),
+                ),
+                categoryThumbnailStorage.delete(
+                  localDeletions
+                    .filter((deletion) =>
+                      deletion.target.startsWith(categoryImagesDir),
+                    )
+                    .map((deletion) => deletion.target),
+                ),
+              ])
+              return {
+                deletedContentTargets,
+                deletedLocalTargets: [
+                  ...deletedMediaThumbnailTargets,
+                  ...deletedCategoryThumbnailTargets,
+                ],
+              }
+            },
+          },
+        )
         const deletedTargets = new Set([
           ...deletedContentTargets,
           ...deletedLocalTargets,
@@ -245,6 +317,7 @@ 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
@@ -262,6 +335,10 @@ export async function checkFiles(options, runtime = {}) {
     "Missing referenced content files",
     missingContentFiles,
   )
+  printWrongTypeReferenceSection(
+    "R2 objects referenced as links",
+    wrongTypeR2ContentFiles,
+  )
   printSection(
     options.r2 ? "Orphaned R2 objects" : "Orphaned local content files",
     orphanedContentFiles.map((filePath) =>
@@ -307,6 +384,64 @@ function printMissingReferenceSection(title, items) {
   }
 }
 
+/**
+ * @param {string} title
+ * @param {WrongTypeReference[]} items
+ */
+function printWrongTypeReferenceSection(title, items) {
+  if (items.length === 0) {
+    return
+  }
+  log.warn(`${title} (${items.length})`)
+  for (const item of items) {
+    log.message(
+      `• ${item.path} should use type "upload" (referenced by ${item.sources.toSorted().join(", ")})`,
+    )
+  }
+}
+
+/**
+ * @template T
+ * @param {{
+ *   error: string
+ *   start: string
+ *   stop: (result: T) => string
+ *   task: () => Promise<T>
+ * }} args
+ * @returns {Promise<T>}
+ */
+async function runSpinner({ error, start, stop, task }) {
+  const activeSpinner = spinner()
+  activeSpinner.start(start)
+  try {
+    const result = await task()
+    activeSpinner.stop(stop(result))
+    return result
+  } catch (caughtError) {
+    activeSpinner.error(error)
+    throw caughtError
+  }
+}
+
+/**
+ * @param {{
+ *   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.`
+}
+
+/**
+ * @param {string} action
+ * @param {number} count
+ */
+function formatDeletionProgress(action, count) {
+  return `${action} ${count} orphaned file${count === 1 ? "" : "s"}.`
+}
+
 /**
  * @param {string|undefined} rawScope
  */
@@ -369,10 +504,15 @@ async function validateThumbnails(
       .filter((value) => value !== undefined),
   )
 
-  const initializedMediaStorage = await mediaThumbnailStorage.init()
-  const initializedCategoryStorage = await categoryThumbnailStorage.init()
-  const mediaFiles = await initializedMediaStorage.list()
-  const categoryFiles = await initializedCategoryStorage.list()
+  const [initializedMediaStorage, initializedCategoryStorage] =
+    await Promise.all([
+      mediaThumbnailStorage.init(),
+      categoryThumbnailStorage.init(),
+    ])
+  const [mediaFiles, categoryFiles] = await Promise.all([
+    initializedMediaStorage.list(),
+    initializedCategoryStorage.list(),
+  ])
 
   return {
     orphanedMediaThumbnails: mediaFiles.filter(
@@ -386,18 +526,28 @@ async function validateThumbnails(
 
 /**
  * @param {{
+ *   includeLinkReferences?: boolean
  *   mediaItems: MediaItem[]
  *   storage: FileStorage
  * }} args
  */
-async function validateContentFiles({ mediaItems, storage }) {
+async function validateContentFiles({
+  includeLinkReferences = false,
+  mediaItems,
+  storage,
+}) {
   const initializedStorage = await storage.init()
-  const references = collectContentReferences(mediaItems, initializedStorage)
+  const { references, wrongTypeReferences } = collectContentReferences(
+    mediaItems,
+    initializedStorage,
+    { includeLinkReferences },
+  )
   if (references.size === 0) {
     return {
       missingReferences: /** @type {MissingReference[]} */ ([]),
       orphanedFiles: /** @type {string[]} */ ([]),
       referenceCount: 0,
+      wrongTypeReferences: /** @type {WrongTypeReference[]} */ ([]),
     }
   }
 
@@ -416,41 +566,74 @@ async function validateContentFiles({ mediaItems, storage }) {
     .filter((filePath) => !references.has(filePath))
     .sort()
 
+  const existingWrongTypeReferences = [...wrongTypeReferences.entries()]
+    .filter(([path]) => fileSet.has(path))
+    .map(([, reference]) => ({
+      path: reference.displayPath,
+      sources: [...reference.sources].toSorted(),
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path))
+
   return {
     missingReferences,
     orphanedFiles,
     referenceCount: references.size,
+    wrongTypeReferences: existingWrongTypeReferences,
   }
 }
 
 /**
  * @param {MediaItem[]} mediaItems
  * @param {FileStorage} storage
+ * @param {{includeLinkReferences:boolean}} options
  */
-function collectContentReferences(mediaItems, storage) {
+function collectContentReferences(mediaItems, storage, options) {
   const references = new Map()
+  const wrongTypeReferences = new Map()
   for (const item of mediaItems) {
     const sourceFileName = posix.basename(toPosixPath(item.path))
     for (const contentItem of item.content) {
-      if (contentItem.type !== "upload") {
+      const isLinkReference = contentItem.type === "link"
+      if (
+        contentItem.type !== "upload" &&
+        !(options.includeLinkReferences && isLinkReference)
+      ) {
         continue
       }
       const filePath = storage.toPath(contentItem.url)
       if (!filePath) {
         continue
       }
-      const current = references.get(filePath)
-      if (current) {
-        current.sources.add(sourceFileName)
-      } else {
-        references.set(filePath, {
-          displayPath: contentItem.url,
-          sources: new Set([sourceFileName]),
-        })
+      addFileReference(references, filePath, contentItem.url, sourceFileName)
+      if (isLinkReference) {
+        addFileReference(
+          wrongTypeReferences,
+          filePath,
+          contentItem.url,
+          sourceFileName,
+        )
       }
     }
   }
-  return references
+  return { references, wrongTypeReferences }
+}
+
+/**
+ * @param {Map<string, FileReference>} references
+ * @param {string} filePath
+ * @param {string} displayPath
+ * @param {string} sourceFileName
+ */
+function addFileReference(references, filePath, displayPath, sourceFileName) {
+  const current = references.get(filePath)
+  if (current) {
+    current.sources.add(sourceFileName)
+    return
+  }
+  references.set(filePath, {
+    displayPath,
+    sources: new Set([sourceFileName]),
+  })
 }
 
 /**

package/src/check-links.js

@@ -3,7 +3,7 @@
 import { posix, resolve } from "node:path"
 import { cwd as processCwd, stdin, stdout } from "node:process"
 
-import { intro, isCancel, log, outro, text } from "@clack/prompts"
+import { intro, isCancel, log, outro, progress, text } from "@clack/prompts"
 
 import {
   cliConfigFileName,
@@ -96,12 +96,10 @@ export async function checkLinks(options, runtime = {}) {
     return true
   }
 
-  const results = await mapConcurrent(
-    references,
-    defaultConcurrency,
-    (reference) =>
-      checkLink(reference.resolvedUrl, { fetch: runFetch, timeoutMs }),
-  )
+  const results = await checkReferencesWithProgress(references, {
+    fetch: runFetch,
+    timeoutMs,
+  })
   const checkedLinks = references
     .map((reference, index) => ({ reference, result: results[index] }))
     .sort((a, b) =>
@@ -141,6 +139,46 @@ export async function checkLinks(options, runtime = {}) {
   return false
 }
 
+/**
+ * @param {LinkReference[]} references
+ * @param {{fetch: typeof fetch, timeoutMs: number}} options
+ */
+async function checkReferencesWithProgress(references, options) {
+  const linkProgress = progress({ max: references.length })
+  let completed = 0
+  linkProgress.start(`Checking links (0/${references.length})`)
+
+  try {
+    const results = await mapConcurrent(
+      references,
+      defaultConcurrency,
+      async (reference) => {
+        const result = await checkLink(reference.resolvedUrl, options)
+        completed += 1
+        linkProgress.advance(
+          1,
+          `Checking links (${completed}/${references.length})`,
+        )
+        return result
+      },
+    )
+    const protectedCount = results.filter((result) =>
+      isProtectedLink(result),
+    ).length
+    const unavailableCount = results.filter(
+      (result) => !result.ok && !isProtectedLink(result),
+    ).length
+    const availableCount = results.length - protectedCount - unavailableCount
+    linkProgress.stop(
+      `Checked links: ${availableCount} available, ${protectedCount} protected, ${unavailableCount} unavailable.`,
+    )
+    return results
+  } catch (error) {
+    linkProgress.error("Link check failed.")
+    throw error
+  }
+}
+
 /**
  * @param {{
  *   cwd: string

package/src/support/filesystem.js

@@ -58,23 +58,24 @@ export function files(cwd, options) {
      * @param {string[]} paths
      */
     async delete(paths) {
-      /** @type {string[]} */
-      const removed = []
-      for (const path of paths) {
-        try {
-          await unlink(
-            resolve(
-              cwd,
-              options.toAbsolutePath?.(path) ??
-                toLocalFilePath(options.rootDir, path),
-            ),
-          )
-          removed.push(path)
-        } catch {
-          // The caller prints per-file failures based on the returned paths.
-        }
-      }
-      return removed
+      const removals = await Promise.all(
+        paths.map(async (path) => {
+          try {
+            await unlink(
+              resolve(
+                cwd,
+                options.toAbsolutePath?.(path) ??
+                  toLocalFilePath(options.rootDir, path),
+              ),
+            )
+            return path
+          } catch {
+            // The caller prints per-file failures based on the returned paths.
+            return undefined
+          }
+        }),
+      )
+      return removals.filter((path) => path !== undefined)
     },
     /**
      * @param {string} url
@@ -161,13 +162,17 @@ async function walkFiles(dirPath) {
   /** @type {string[]} */
   const files = []
   const entries = await readdir(dirPath, { withFileTypes: true })
-  for (const entry of entries) {
-    const entryPath = join(dirPath, entry.name)
-    if (entry.isDirectory()) {
-      files.push(...(await walkFiles(entryPath)))
-    } else if (entry.isFile()) {
-      files.push(entryPath)
-    }
+  const nestedFiles = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = join(dirPath, entry.name)
+      if (entry.isDirectory()) {
+        return walkFiles(entryPath)
+      }
+      return entry.isFile() ? [entryPath] : []
+    }),
+  )
+  for (const item of nestedFiles) {
+    files.push(...item)
   }
   return files
 }

package/src/support/r2.js

@@ -1,6 +1,9 @@
 // @ts-check
 
 import { execFile } from "node:child_process"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
 import { env as processEnv } from "node:process"
 import { promisify } from "node:util"
 
@@ -15,6 +18,7 @@ import { CliError } from "./cli-error.js"
 
 const execFileAsync = promisify(execFile)
 const sessionSecretEnvName = "LIGHTNET_R2_SECRET_ACCESS_KEY"
+const r2DeleteBatchSize = 1000
 
 /**
  * @typedef {{
@@ -117,18 +121,16 @@ export function createR2FileStorage({
   const storage = {
     async init() {
       await getConfig()
+      await getSecretAccessKey()
       return storage
     },
     async list() {
       return runWithRefresh(async (config) => {
-        const secretAccessKey = await getSecretAccessKey()
-        const sharedArgs = {
+        const bucketObjects = await listR2Objects({
           cwd,
           config,
-          secretAccessKey,
-        }
-        await assertR2Access(sharedArgs)
-        const bucketObjects = await listR2Objects(sharedArgs)
+          secretAccessKey: await getSecretAccessKey(),
+        })
         return bucketObjects.map((item) => item.key).sort()
       })
     },
@@ -138,22 +140,12 @@ export function createR2FileStorage({
     async delete(paths) {
       const r2Config = await getConfig()
       const secretAccessKey = await getSecretAccessKey()
-      /** @type {string[]} */
-      const removed = []
-      for (const path of paths) {
-        try {
-          await runConfiguredRclone({
-            args: ["deletefile", makeR2Path(r2Config, path)],
-            cwd,
-            config: r2Config,
-            secretAccessKey,
-          })
-          removed.push(path)
-        } catch {
-          // The caller prints per-file failures based on the returned paths.
-        }
-      }
-      return removed
+      return deleteR2Objects({
+        config: r2Config,
+        cwd,
+        paths,
+        secretAccessKey,
+      })
     },
     /**
      * @param {string} url
@@ -167,32 +159,134 @@ export function createR2FileStorage({
         return undefined
       }
       const path = url.slice(normalizedBase.length).replace(/^\/+/, "")
-      return path || undefined
+      return decodeR2ObjectPath(path) || undefined
     },
   }
   return storage
 }
 
+/**
+ * @param {string} path
+ */
+function decodeR2ObjectPath(path) {
+  try {
+    return decodeURIComponent(path)
+  } catch {
+    return path
+  }
+}
+
 /**
  * @param {{
+ *   config: R2Config
  *   cwd: string
+ *   paths: string[]
+ *   secretAccessKey: string
+ * }} args
+ */
+async function deleteR2Objects({ config, cwd, paths, secretAccessKey }) {
+  /** @type {string[]} */
+  const removed = []
+  const batchablePaths = paths.filter((path) => !path.includes("\n"))
+  const singleDeletePaths = paths.filter((path) => path.includes("\n"))
+
+  for (
+    let index = 0;
+    index < batchablePaths.length;
+    index += r2DeleteBatchSize
+  ) {
+    const batch = batchablePaths.slice(index, index + r2DeleteBatchSize)
+    try {
+      await deleteR2ObjectBatch({ config, cwd, paths: batch, secretAccessKey })
+      removed.push(...batch)
+    } catch {
+      removed.push(
+        ...(await deleteR2ObjectsIndividually({
+          config,
+          cwd,
+          paths: batch,
+          secretAccessKey,
+        })),
+      )
+    }
+  }
+
+  removed.push(
+    ...(await deleteR2ObjectsIndividually({
+      config,
+      cwd,
+      paths: singleDeletePaths,
+      secretAccessKey,
+    })),
+  )
+
+  return removed
+}
+
+/**
+ * @param {{
  *   config: R2Config
+ *   cwd: string
+ *   paths: string[]
  *   secretAccessKey: string
  * }} args
  */
-async function assertR2Access(args) {
+async function deleteR2ObjectBatch({ config, cwd, paths, secretAccessKey }) {
+  if (paths.length === 0) {
+    return
+  }
+
+  const tempDir = await mkdtemp(join(tmpdir(), "lightnet-r2-delete-"))
+  const fileListPath = join(tempDir, "files.txt")
   try {
+    await writeFile(fileListPath, `${paths.join("\n")}\n`, "utf8")
     await runConfiguredRclone({
-      args: ["lsjson", makeR2Path(args.config), "--files-only"],
-      ...args,
+      args: [
+        "delete",
+        makeR2Path(config),
+        "--files-from-raw",
+        fileListPath,
+        "--fast-list",
+      ],
+      cwd,
+      config,
+      secretAccessKey,
     })
-  } catch (error) {
-    throw new CliError(
-      error instanceof Error
-        ? `Unable to access R2 bucket "${args.config.bucket}": ${error.message}`
-        : `Unable to access R2 bucket "${args.config.bucket}".`,
-    )
+  } finally {
+    await rm(tempDir, { force: true, recursive: true })
+  }
+}
+
+/**
+ * @param {{
+ *   config: R2Config
+ *   cwd: string
+ *   paths: string[]
+ *   secretAccessKey: string
+ * }} args
+ */
+async function deleteR2ObjectsIndividually({
+  config,
+  cwd,
+  paths,
+  secretAccessKey,
+}) {
+  /** @type {string[]} */
+  const removed = []
+  for (const path of paths) {
+    try {
+      await runConfiguredRclone({
+        args: ["deletefile", makeR2Path(config, path)],
+        cwd,
+        config,
+        secretAccessKey,
+      })
+      removed.push(path)
+    } catch {
+      // The caller prints per-file failures based on the returned paths.
+    }
   }
+  return removed
 }
 
 /**
@@ -203,18 +297,28 @@ async function assertR2Access(args) {
  * }} args
  */
 async function listR2Objects(args) {
-  const { stdout: listJson } = await runConfiguredRclone({
-    args: [
-      "lsjson",
-      makeR2Path(args.config),
-      "--recursive",
-      "--files-only",
-      "--fast-list",
-      "--no-mimetype",
-      "--no-modtime",
-    ],
-    ...args,
-  })
+  let listJson
+  try {
+    const result = await runConfiguredRclone({
+      args: [
+        "lsjson",
+        makeR2Path(args.config),
+        "--recursive",
+        "--files-only",
+        "--fast-list",
+        "--no-mimetype",
+        "--no-modtime",
+      ],
+      ...args,
+    })
+    listJson = result.stdout
+  } catch (error) {
+    throw new CliError(
+      error instanceof Error
+        ? `Unable to access R2 bucket "${args.config.bucket}": ${error.message}`
+        : `Unable to access R2 bucket "${args.config.bucket}".`,
+    )
+  }
 
   let parsed
   try {