@lightnet/cli 4.7.0 → 4.8.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @lightnet/cli
 
+## 4.8.0
+
+### Minor Changes
+
+- [#449](https://github.com/LightNetDev/LightNet/pull/449) [`b4b1ba9`](https://github.com/LightNetDev/LightNet/commit/b4b1ba9e591af8f6870f2b3eb04029820a008393) - Add repeatable `--exclude` glob exclusions to `check-links` for explicitly exempt media URLs.
+
+### Patch Changes
+
+- [#449](https://github.com/LightNetDev/LightNet/pull/449) [`b4b1ba9`](https://github.com/LightNetDev/LightNet/commit/b4b1ba9e591af8f6870f2b3eb04029820a008393) - Update dependencies
+
+- [#449](https://github.com/LightNetDev/LightNet/pull/449) [`b4b1ba9`](https://github.com/LightNetDev/LightNet/commit/b4b1ba9e591af8f6870f2b3eb04029820a008393) - Support non interactive usage of check-translations cli script.
+
+- [#449](https://github.com/LightNetDev/LightNet/pull/449) [`b4b1ba9`](https://github.com/LightNetDev/LightNet/commit/b4b1ba9e591af8f6870f2b3eb04029820a008393) - Internal fix typings after dependency update.
+
+## 4.7.1
+
+### Patch Changes
+
+- [#447](https://github.com/LightNetDev/LightNet/pull/447) [`0d8fece`](https://github.com/LightNetDev/LightNet/commit/0d8fece3527a67a21c6272b422c62152948b32a1) - Only prompt for `lightnet r2 cp` and `lightnet r2 mv` when files would actually be overwritten, and list the destination files before confirmation.
+
 ## 4.7.0
 
 ### Minor Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "CLI for managing LightNet projects",
   "type": "module",
   "license": "MIT",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -25,10 +25,16 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
+    "@clack/prompts": "^1.8.0",
     "commander": "^15.0.0"
   },
+  "devDependencies": {
+    "vitest": "^5.0.0"
+  },
   "engines": {
     "node": ">=22"
+  },
+  "scripts": {
+    "test": "vitest"
   }
 }

package/src/check-files.js

@@ -772,5 +772,5 @@ async function defaultPromptConfirm(message) {
   if (isCancel(answer)) {
     cancelPrompt()
   }
-  return answer
+  return Boolean(answer)
 }

package/src/check-links.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { posix, resolve } from "node:path"
+import { matchesGlob, posix, resolve } from "node:path"
 import { cwd as processCwd, stdin, stdout } from "node:process"
 
 import { intro, isCancel, log, outro, progress, text } from "@clack/prompts"
@@ -28,6 +28,7 @@ const requestHeaders = {
 
 /**
  * @typedef {{
+ *   exclude?: string[]
  *   timeout?: string
  * }} CheckLinksOptions
  */
@@ -49,6 +50,14 @@ const requestHeaders = {
  * }} LinkReference
  */
 
+/**
+ * @typedef {{
+ *   displayUrl: string
+ *   patterns: Set<string>
+ *   sources: Set<string>
+ * }} ExcludedLinkReference
+ */
+
 /**
  * @typedef {{
  *   ok: boolean
@@ -73,6 +82,7 @@ export async function checkLinks(options, runtime = {}) {
     "--timeout",
     defaultTimeoutMs,
   )
+  const excludePatterns = parseExcludePatterns(options.exclude)
 
   intro("check-links")
 
@@ -82,17 +92,28 @@ export async function checkLinks(options, runtime = {}) {
   const mediaItems = await collections.getMediaItems()
   const siteUrl = await initSiteUrl({
     cwd,
+    excludePatterns,
     interactive,
     mediaItems,
     promptText,
   })
-  const references = collectLinkReferences(mediaItems, siteUrl)
+  const { excludedReferences, references } = collectLinkReferences(
+    mediaItems,
+    siteUrl,
+    excludePatterns,
+  )
   log.message(
     `Checking ${references.length} unique links from ${mediaItems.length} media items.`,
   )
 
+  printExcludedLinks(excludedReferences)
+
   if (references.length === 0) {
-    log.warn("No media content URLs found.")
+    log.warn(
+      excludedReferences.length > 0
+        ? "No media content URLs require checking."
+        : "No media content URLs found.",
+    )
     outro("No issues found. 🎉")
     return true
   }
@@ -179,14 +200,25 @@ async function checkReferencesWithProgress(references, options) {
 /**
  * @param {{
  *   cwd: string
+ *   excludePatterns: string[]
  *   interactive: boolean
  *   mediaItems: MediaItem[]
  *   promptText: (message: string) => Promise<string>
  * }} args
  */
-async function initSiteUrl({ cwd, interactive, mediaItems, promptText }) {
+async function initSiteUrl({
+  cwd,
+  excludePatterns,
+  interactive,
+  mediaItems,
+  promptText,
+}) {
   const needsSiteUrl = mediaItems.some((item) =>
-    item.content.some((contentItem) => isRootRelativeUrl(contentItem.url)),
+    item.content.some(
+      (contentItem) =>
+        isRootRelativeUrl(contentItem.url) &&
+        findMatchingPatterns(contentItem.url, excludePatterns).length === 0,
+    ),
   )
   if (!needsSiteUrl) {
     return undefined
@@ -236,13 +268,36 @@ function parseSiteUrl(config) {
 /**
  * @param {MediaItem[]} mediaItems
  * @param {string|undefined} siteUrl
+ * @param {string[]} excludePatterns
  */
-function collectLinkReferences(mediaItems, siteUrl) {
+function collectLinkReferences(mediaItems, siteUrl, excludePatterns) {
   /** @type {Map<string, LinkReference>} */
   const references = new Map()
+  /** @type {Map<string, ExcludedLinkReference>} */
+  const excludedReferences = new Map()
   for (const item of mediaItems) {
     const sourceFileName = posix.basename(toPosixPath(item.path))
     for (const contentItem of item.content) {
+      const matchingPatterns = findMatchingPatterns(
+        contentItem.url,
+        excludePatterns,
+      )
+      if (matchingPatterns.length > 0) {
+        const current = excludedReferences.get(contentItem.url)
+        if (current) {
+          current.sources.add(sourceFileName)
+          for (const pattern of matchingPatterns) {
+            current.patterns.add(pattern)
+          }
+        } else {
+          excludedReferences.set(contentItem.url, {
+            displayUrl: contentItem.url,
+            patterns: new Set(matchingPatterns),
+            sources: new Set([sourceFileName]),
+          })
+        }
+        continue
+      }
       const resolvedUrl = resolveUrl(contentItem.url, siteUrl)
       const current = references.get(resolvedUrl)
       if (current) {
@@ -259,9 +314,14 @@ function collectLinkReferences(mediaItems, siteUrl) {
       }
     }
   }
-  return [...references.values()].sort((a, b) =>
-    a.displayUrl.localeCompare(b.displayUrl),
-  )
+  return {
+    excludedReferences: [...excludedReferences.values()].sort((a, b) =>
+      a.displayUrl.localeCompare(b.displayUrl),
+    ),
+    references: [...references.values()].sort((a, b) =>
+      a.displayUrl.localeCompare(b.displayUrl),
+    ),
+  }
 }
 
 /**
@@ -334,6 +394,25 @@ function printProtectedLinks(links) {
   }
 }
 
+/**
+ * @param {ExcludedLinkReference[]} links
+ */
+function printExcludedLinks(links) {
+  if (links.length === 0) {
+    return
+  }
+
+  log.info(`Excluded links (${links.length})`)
+  for (const link of links) {
+    const patterns = [...link.patterns]
+      .toSorted()
+      .map((pattern) => `"${pattern}"`)
+    log.message(
+      `• ${link.displayUrl}\n  Excluded by: ${patterns.join(", ")}\n${formatReferenceSources(link.sources)}`,
+    )
+  }
+}
+
 /**
  * @param {Set<string>} sources
  */
@@ -426,6 +505,63 @@ function parsePositiveInteger(rawValue, optionName, defaultValue) {
   return value
 }
 
+/**
+ * @param {string[]|undefined} patterns
+ */
+function parseExcludePatterns(patterns) {
+  return (patterns ?? []).map((pattern) => {
+    if (!isValidGlobPattern(pattern)) {
+      throw new CliError(`Invalid "--exclude" glob pattern "${pattern}".`)
+    }
+    return pattern
+  })
+}
+
+/**
+ * @param {string} url
+ * @param {string[]} patterns
+ */
+function findMatchingPatterns(url, patterns) {
+  return patterns.filter((pattern) => matchesGlob(url, pattern))
+}
+
+/**
+ * Node's glob matcher treats unclosed groups as non-matches, so validate them
+ * explicitly to turn common malformed patterns into actionable CLI errors.
+ *
+ * @param {string} pattern
+ */
+function isValidGlobPattern(pattern) {
+  /** @type {Partial<Record<string, string>>} */
+  const pairs = { "[": "]", "{": "}", "(": ")" }
+  /** @type {string[]} */
+  const expectedClosers = []
+  let escaped = false
+
+  for (const character of pattern) {
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (character === "\\") {
+      escaped = true
+      continue
+    }
+    const closer = pairs[character]
+    if (closer) {
+      expectedClosers.push(closer)
+      continue
+    }
+    if (character === "]" || character === "}" || character === ")") {
+      if (expectedClosers.pop() !== character) {
+        return false
+      }
+    }
+  }
+
+  return !escaped && expectedClosers.length === 0
+}
+
 /**
  * @param {string} value
  * @param {string} label

package/src/check-translations.js

@@ -3,7 +3,7 @@
 import { spawn } from "node:child_process"
 import { readFile } from "node:fs/promises"
 import { resolve } from "node:path"
-import { cwd } from "node:process"
+import { cwd, stdin, stdout } from "node:process"
 
 import { confirm, intro, isCancel, log, outro, taskLog } from "@clack/prompts"
 
@@ -30,7 +30,14 @@ import { cancelPrompt } from "./support/prompt-cancel.js"
  * }} CheckTranslationsOptions
  */
 
-const lightnetCachePath = resolve(cwd(), "node_modules", ".cache", "lightnet")
+/**
+ * @typedef {{
+ *   cwd?: string
+ *   isInteractive?: boolean
+ *   promptRunBuild?: () => Promise<boolean>
+ *   write?: (message: string) => void
+ * }} CheckTranslationsRuntime
+ */
 
 /** @type {{type:Translation["type"], title:string, action:string}[]} */
 const translationSources = [
@@ -54,18 +61,33 @@ const translationSources = [
 
 /**
  * @param {CheckTranslationsOptions} [options]
+ * @param {CheckTranslationsRuntime} [runtime]
  */
-export async function checkTranslations(options = {}) {
-  intro("check-translations")
+export async function checkTranslations(options = {}, runtime = {}) {
+  const lightnetCachePath = resolve(
+    runtime.cwd ?? cwd(),
+    "node_modules",
+    ".cache",
+    "lightnet",
+  )
+  const interactive =
+    runtime.isInteractive ?? Boolean(stdin.isTTY && stdout.isTTY)
+  const output = createOutput(interactive, runtime.write)
+
+  output.intro("check-translations")
 
-  const buildAvailable = await runBuild(options.build)
+  const buildAvailable = await runBuild(options.build, {
+    interactive,
+    output,
+    promptRunBuild: runtime.promptRunBuild,
+  })
   if (!buildAvailable) {
-    outro("Build failed. 🚧")
+    output.outro("Build failed. 🚧")
     return false
   }
 
-  const translations = await readTranslations()
-  const languages = await readLanguages()
+  const translations = await readTranslations(lightnetCachePath, output)
+  const languages = await readLanguages(lightnetCachePath, output)
   if (!translations || !languages || translations.length === 0) {
     return false
   }
@@ -77,7 +99,7 @@ export async function checkTranslations(options = {}) {
     .filter((translation) => translation.missingLocales.length > 0)
 
   if (incompleteTranslations.length === 0) {
-    outro("No issues found. 🎉")
+    output.outro("No issues found. 🎉")
     return true
   }
 
@@ -86,29 +108,42 @@ export async function checkTranslations(options = {}) {
     (translation) => translation.type,
   )
 
-  log.error("Translation check failed")
+  output.error("Translation check failed")
   for (const source of translationSources) {
-    printMissingTranslations(source, grouped[source.type])
+    printMissingTranslations(source, grouped[source.type], output)
   }
 
-  outro("Issues found. 🚧")
+  output.outro("Issues found. 🚧")
 
   return false
 }
 
 /**
- *
  * @param {boolean|undefined} build
- * @returns
+ * @param {{
+ *   interactive: boolean
+ *   output: ReturnType<typeof createOutput>
+ *   promptRunBuild?: () => Promise<boolean>
+ * }} runtime
  */
-async function runBuild(build) {
-  const shouldRunBuild = build ?? (await promptRunBuild())
+async function runBuild(build, { interactive, output, promptRunBuild }) {
+  const shouldRunBuild =
+    build ??
+    (interactive ? await (promptRunBuild ?? defaultPromptRunBuild)() : false)
   if (!shouldRunBuild) {
     return true
   }
-  const buildLog = taskLog({
-    title: "Running pnpm build",
-  })
+  const buildLog = interactive
+    ? taskLog({ title: "Running pnpm build" })
+    : {
+        error: output.error,
+        message: output.message,
+        success: output.message,
+      }
+
+  if (!interactive) {
+    output.message("Running pnpm build")
+  }
 
   const child = spawn("pnpm", ["build"], {
     shell: process.platform === "win32",
@@ -154,7 +189,7 @@ async function runBuild(build) {
   }
 }
 
-async function promptRunBuild() {
+async function defaultPromptRunBuild() {
   const answer = await confirm({
     message:
       "Run pnpm build now? Command requires an up-to-date dist/ directory.",
@@ -170,13 +205,14 @@ async function promptRunBuild() {
  *
  * @param {{title:string, action:string}} source
  * @param {(Translation & {missingLocales:string[]})[]|undefined} translations
+ * @param {ReturnType<typeof createOutput>} output
  */
-function printMissingTranslations(source, translations) {
+function printMissingTranslations(source, translations, output) {
   if (!translations || translations.length === 0) {
     return
   }
 
-  log.warn(source.title)
+  output.warn(source.title)
   translations
     .toSorted(
       (t1, t2) =>
@@ -184,10 +220,10 @@ function printMissingTranslations(source, translations) {
         t1.key.localeCompare(t2.key),
     )
     .forEach(({ key, missingLocales }) => {
-      log.message(`• ${key} > Missing: ${missingLocales.join(", ")}`)
+      output.message(`• ${key} > Missing: ${missingLocales.join(", ")}`)
     })
 
-  log.message(`Action: ${source.action}`)
+  output.message(`Action: ${source.action}`)
 }
 
 /**
@@ -201,9 +237,11 @@ function getMissingLocales(translation, languages) {
 }
 
 /**
+ * @param {string} lightnetCachePath
+ * @param {ReturnType<typeof createOutput>} output
  * @returns {Promise<Translation[]|undefined>}
  */
-async function readTranslations() {
+async function readTranslations(lightnetCachePath, output) {
   try {
     const translationsText = await readFile(
       resolve(lightnetCachePath, "translations.jsonl"),
@@ -214,16 +252,18 @@ async function readTranslations() {
       .filter((line) => line.trim())
       .map((line) => JSON.parse(line))
   } catch {
-    log.error("No translation build cache found.")
-    log.error("Action: Run build and try lightnet check-translations again.")
+    output.error("No translation build cache found.")
+    output.error("Action: Run build and try lightnet check-translations again.")
     return undefined
   }
 }
 
 /**
+ * @param {string} lightnetCachePath
+ * @param {ReturnType<typeof createOutput>} output
  * @returns {Promise<Languages|undefined>}
  */
-async function readLanguages() {
+async function readLanguages(lightnetCachePath, output) {
   try {
     const languagesText = await readFile(
       resolve(lightnetCachePath, "languages.json"),
@@ -231,8 +271,37 @@ async function readLanguages() {
     )
     return JSON.parse(languagesText)
   } catch {
-    log.error("No language manifest found from the last build.")
-    log.error("Action: Run build and try lightnet check-translations again.")
+    output.error("No language manifest found from the last build.")
+    output.error("Action: Run build and try lightnet check-translations again.")
     return undefined
   }
 }
+
+/**
+ * @param {boolean} interactive
+ * @param {(message: string) => void | undefined} write
+ */
+function createOutput(
+  interactive,
+  write = (message) => {
+    stdout.write(`${message}\n`)
+  },
+) {
+  if (interactive) {
+    return {
+      error: log.error,
+      intro,
+      message: log.message,
+      outro,
+      warn: log.warn,
+    }
+  }
+
+  return {
+    error: write,
+    intro: write,
+    message: write,
+    outro: write,
+    warn: write,
+  }
+}

package/src/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // @ts-check
 
-import { Command } from "commander"
+import { Command, Option } from "commander"
 
 import pkg from "../package.json" with { type: "json" }
 import { checkFiles } from "./check-files.js"
@@ -62,6 +62,14 @@ program
   .command("check-links")
   .description("check media content links in a LightNet site")
   .option("--timeout <ms>", "request timeout per link in milliseconds")
+  .addOption(
+    new Option(
+      "--exclude <pattern>",
+      "exclude media content URLs matching a glob pattern (repeatable)",
+    )
+      .default([])
+      .argParser((pattern, patterns) => [...patterns, pattern]),
+  )
   .action(async (options) => {
     try {
       const checkSuccessful = await checkLinks(options)

package/src/r2.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { stat } from "node:fs/promises"
+import { readdir, stat } from "node:fs/promises"
 import { basename, join, posix, resolve } from "node:path"
 import {
   cwd as processCwd,
@@ -78,6 +78,7 @@ const defaultRcloneOptions = {
  *   isInteractive?: boolean
  *   promptConfirm?: (message: string) => Promise<boolean>
  *   promptText?: (message: string) => Promise<string>
+ *   createR2Client?: typeof createR2Client
  *   writeStdout?: (message: string) => void
  * }} R2Runtime
  */
@@ -285,10 +286,12 @@ export async function copyR2(paths, options = {}, runtime = {}) {
       (targetType !== "directory" || isDirectoryLikeCopyPath(destinationPath))
 
     await confirmCopyOverwrite({
+      client,
       destination,
       force: options.force === true,
       noClobber: options.noClobber === true,
       runtime,
+      sourcePath,
       sourceType,
       targetPath,
       targetType,
@@ -383,10 +386,12 @@ export async function moveR2(paths, options = {}, runtime = {}) {
       (targetType !== "directory" || isDirectoryLikeCopyPath(destinationPath))
 
     await confirmCopyOverwrite({
+      client,
       destination,
       force: options.force === true,
       noClobber: options.noClobber === true,
       runtime,
+      sourcePath,
       sourceType,
       targetPath,
       targetType,
@@ -426,7 +431,7 @@ export async function moveR2(paths, options = {}, runtime = {}) {
  * @param {R2Runtime} runtime
  */
 function createR2CommandClient(runtime) {
-  return createR2Client({
+  return (runtime.createR2Client ?? createR2Client)({
     cwd: runtime.cwd ?? processCwd(),
     interactive: getInteractive(runtime),
     promptText: getPromptText(runtime),
@@ -580,20 +585,24 @@ function getCopyTargetPath({
 
 /**
  * @param {{
+ *   client: ReturnType<typeof createR2CommandClient>,
  *   destination: string,
  *   force: boolean,
  *   noClobber: boolean,
  *   runtime: R2Runtime,
+ *   sourcePath: CopyPath,
  *   sourceType: CopyPathType,
  *   targetPath: CopyPath,
  *   targetType: CopyPathType
  * }} args
  */
 async function confirmCopyOverwrite({
+  client,
   destination,
   force,
   noClobber,
   runtime,
+  sourcePath,
   sourceType,
   targetPath,
   targetType,
@@ -617,11 +626,27 @@ async function confirmCopyOverwrite({
   if (noClobber) {
     return
   }
+  const overwrittenPaths =
+    sourceType === "directory"
+      ? await getDirectoryOverwritePaths({
+          client,
+          runtime,
+          sourcePath,
+          targetPath,
+        })
+      : [formatCopyPath(targetPath)]
+  if (overwrittenPaths.length === 0) {
+    return
+  }
   if (!getInteractive(runtime)) {
     throw new CliError(
       'Transfer would overwrite existing files. Re-run with "--force" in non-interactive environments.',
     )
   }
+  log.warn(`Files to overwrite (${overwrittenPaths.length})`)
+  for (const overwrittenPath of overwrittenPaths) {
+    log.message(`• ${overwrittenPath}`)
+  }
   const message =
     sourceType === "directory"
       ? `Overwrite any existing files under destination "${destination}"? [y/N] `
@@ -632,6 +657,94 @@ async function confirmCopyOverwrite({
   }
 }
 
+/**
+ * @param {{
+ *   client: ReturnType<typeof createR2CommandClient>
+ *   runtime: R2Runtime
+ *   sourcePath: CopyPath
+ *   targetPath: CopyPath
+ * }} args
+ */
+async function getDirectoryOverwritePaths({
+  client,
+  runtime,
+  sourcePath,
+  targetPath,
+}) {
+  const sourceFiles = await listCopyFiles(sourcePath, client, runtime)
+  if (sourceFiles.length === 0) {
+    return []
+  }
+  const targetFiles = new Set(await listCopyFiles(targetPath, client, runtime))
+  return sourceFiles
+    .filter((relativePath) => targetFiles.has(relativePath))
+    .map((relativePath) =>
+      formatCopyPath({
+        ...targetPath,
+        path: joinCopyPath(targetPath, relativePath),
+      }),
+    )
+}
+
+/**
+ * @param {CopyPath} copyPath
+ * @param {ReturnType<typeof createR2CommandClient>} client
+ * @param {R2Runtime} runtime
+ */
+async function listCopyFiles(copyPath, client, runtime) {
+  if (copyPath.remote) {
+    return parseRcloneFileList(await client.list(copyPath.path))
+  }
+  return listLocalFiles(resolveLocalPath(copyPath.path, runtime))
+}
+
+/**
+ * @param {string} root
+ * @param {string} [prefix]
+ * @returns {Promise<string[]>}
+ */
+async function listLocalFiles(root, prefix = "") {
+  const entries = await readdir(root, { withFileTypes: true })
+  const files = []
+  for (const entry of entries) {
+    const relativePath = prefix
+      ? joinRelativePath(prefix, entry.name)
+      : entry.name
+    const absolutePath = join(root, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...(await listLocalFiles(absolutePath, relativePath)))
+    } else if (entry.isFile()) {
+      files.push(relativePath)
+    }
+  }
+  return files
+}
+
+/**
+ * @param {string} output
+ */
+function parseRcloneFileList(output) {
+  return output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+}
+
+/**
+ * @param {string} parent
+ * @param {string} child
+ */
+function joinRelativePath(parent, child) {
+  return parent ? posix.join(parent, child) : child
+}
+
+/**
+ * @param {CopyPath} copyPath
+ */
+function formatCopyPath(copyPath) {
+  return copyPath.remote ? `${remotePathPrefix}${copyPath.path}` : copyPath.path
+}
+
 /**
  * @param {CopyPath} copyPath
  * @param {ReturnType<typeof createR2CommandClient>} client

package/src/support/r2.js

@@ -617,9 +617,10 @@ async function promptRequiredSecret({ interactive = true } = {}) {
     if (isCancel(value)) {
       cancelPrompt()
     }
-    if (value.trim()) {
-      processEnv[sessionSecretEnvName] = value
-      return value
+    const secret = typeof value === "string" ? value : ""
+    if (secret.trim()) {
+      processEnv[sessionSecretEnvName] = secret
+      return secret
     }
   }
 }