@mux-magic/tools 0.1.0

package/src/getFolder.test.ts

@@ -0,0 +1,90 @@
+import { join } from "node:path"
+import { vol } from "memfs"
+import { EmptyError, firstValueFrom, toArray } from "rxjs"
+import { beforeEach, describe, expect, test } from "vitest"
+import { captureLogMessage } from "./captureLogMessage.js"
+import {
+  type FolderInfo,
+  filterFolderAtPath,
+  getFolder,
+} from "./getFolder.js"
+import { getOperatorValue } from "./test-runners.js"
+
+describe(filterFolderAtPath.name, () => {
+  beforeEach(() => {
+    vol.fromJSON({
+      "/movies/Super Mario Bros (1993)/Super Mario Bros (1993).mkv":
+        "",
+    })
+  })
+
+  test("emits if path is a directory", async () => {
+    const inputValue = "/movies/Super Mario Bros (1993)"
+
+    await expect(
+      getOperatorValue(
+        filterFolderAtPath((filePath) => filePath),
+        inputValue,
+      ),
+    ).resolves.toBe(inputValue)
+  })
+
+  test("throws an error if path is a file", async () => {
+    const inputValue =
+      "/movies/Super Mario Bros (1993)/Super Mario Bros (1993).mkv"
+
+    await expect(
+      getOperatorValue(
+        filterFolderAtPath((filePath) => filePath),
+        inputValue,
+      ),
+    ).rejects.toThrow(EmptyError)
+  })
+})
+
+describe(getFolder.name, () => {
+  test("errors if source path can't be found", async () => {
+    await captureLogMessage("error", async () => {
+      await expect(
+        firstValueFrom(
+          getFolder({
+            sourcePath: "non-existent-path",
+          }),
+        ),
+      ).rejects.toThrow("ENOENT")
+    })
+  })
+
+  test("emits folders from source path", async () => {
+    vol.fromJSON({
+      "/movies/Star Wars (1977)/Star Wars (1977).mkv": "",
+      "/movies/Star Wars (1977)/Star Wars (1977) {edition-4K77}.mkv":
+        "",
+      "/movies/Super Mario Bros (1993)/Super Mario Bros (1993).mkv":
+        "",
+    })
+
+    const expected: FolderInfo[] = [
+      {
+        folderName: "Star Wars (1977)",
+        fullPath: join("/movies", "Star Wars (1977)"),
+        renameFolder: expect.any(Function),
+      },
+      {
+        folderName: "Super Mario Bros (1993)",
+        fullPath: join(
+          "/movies",
+          "Super Mario Bros (1993)",
+        ),
+        renameFolder: expect.any(Function),
+      },
+    ]
+    const actual = await firstValueFrom(
+      getFolder({
+        sourcePath: "/movies",
+      }).pipe(toArray()),
+    )
+    expect(actual).toEqual(expect.arrayContaining(expected))
+    expect(actual).toHaveLength(expected.length)
+  })
+})

package/src/getFolder.ts

@@ -0,0 +1,74 @@
+import { readdir, stat } from "node:fs/promises"
+import { join } from "node:path"
+import {
+  catchError,
+  concatAll,
+  concatMap,
+  defer,
+  EMPTY,
+  filter,
+  from,
+  map,
+  type Observable,
+  type OperatorFunction,
+} from "rxjs"
+
+import { createRenameFileOrFolderObservable } from "./createRenameFileOrFolder.js"
+import { logAndRethrowPipelineError } from "./logAndRethrowPipelineError.js"
+
+export type FolderInfo = {
+  folderName: string
+  fullPath: string
+  renameFolder: (newFolderName: string) => Observable<{
+    newPath: string
+    oldPath: string
+  }>
+}
+
+export const getIsFolder = (folderPath: string) =>
+  from(stat(folderPath)).pipe(
+    filter((stats) => stats.isDirectory()),
+  )
+
+export const filterFolderAtPath = <PipelineValue>(
+  getFullPath: (pipelineValue: PipelineValue) => string,
+): OperatorFunction<PipelineValue, PipelineValue> =>
+  concatMap((pipelineValue) =>
+    from(stat(getFullPath(pipelineValue))).pipe(
+      filter((stats) => stats.isDirectory()),
+      map(() => pipelineValue),
+      catchError((error) => {
+        if (error.code === "ENOENT") {
+          return EMPTY
+        }
+
+        throw error
+      }),
+    ),
+  )
+
+export const getFolder = ({
+  sourcePath,
+}: {
+  sourcePath: string
+}): Observable<FolderInfo> =>
+  defer(() => readdir(sourcePath)).pipe(
+    concatAll(),
+    map((folderName) => ({
+      folderName,
+      fullPath: join(sourcePath, folderName),
+    })),
+    filterFolderAtPath(({ fullPath }) => fullPath),
+    map(
+      ({ folderName, fullPath }) =>
+        ({
+          folderName,
+          fullPath,
+          renameFolder: createRenameFileOrFolderObservable({
+            fullPath,
+            sourcePath,
+          }),
+        }) satisfies FolderInfo as FolderInfo,
+    ),
+    logAndRethrowPipelineError(getFolder),
+  )

package/src/index.ts

@@ -0,0 +1,60 @@
+// Public entry for @mux-magic/tools. THIS IS THE ONLY ALLOWED BARREL FILE
+// in the entire repository — see AGENTS.md "Module exports — no barrel files".
+// It exists because external consumers (the Gallery-Downloader sibling repo,
+// plus any future npm consumers) need a single stable import path; without it
+// every release would re-publish the package's internal file layout into
+// consumer code.
+//
+// Inside this monorepo, never import from "@mux-magic/tools" — import the
+// individual file directly (e.g. "@mux-magic/tools/src/naturalSort").
+
+export {
+  aclSafeCopyFile,
+  type CopyOptions,
+  type CopyProgressEvent,
+} from "./aclSafeCopyFile.js"
+export { addFolderNameBeforeFilename } from "./addFolderNameBeforeFilename.js"
+export { captureConsoleMessage } from "./captureConsoleMessage.js"
+export { captureLogMessage } from "./captureLogMessage.js"
+export { cleanupFilename } from "./cleanupFilename.js"
+export {
+  createRenameFileOrFolderObservable,
+  getLastItemInFilePath,
+  renameFileOrFolder,
+} from "./createRenameFileOrFolder.js"
+export {
+  type FileInfo,
+  filterFileAtPath,
+  getFiles,
+} from "./getFiles.js"
+export { getFilesAtDepth } from "./getFilesAtDepth.js"
+export {
+  type FolderInfo,
+  filterFolderAtPath,
+  getFolder,
+  getIsFolder,
+} from "./getFolder.js"
+export { insertIntoArray } from "./insertIntoArray.js"
+export {
+  type DirectoryEntry,
+  type ListDirectoryEntriesResult,
+  listDirectoryEntries,
+} from "./listDirectoryEntries.js"
+export { logAndRethrowPipelineError } from "./logAndRethrowPipelineError.js"
+export { logAndSwallowPipelineError } from "./logAndSwallowPipelineError.js"
+export {
+  createAddColorToChalk,
+  createLogMessage,
+  logError,
+  logInfo,
+  logWarning,
+  messageTemplate,
+} from "./logMessage.js"
+export { makeDirectory } from "./makeDirectory.js"
+export { naturalSort } from "./naturalSort.js"
+export { replaceFileExtension } from "./replaceFileExtension.js"
+export {
+  getOperatorValue,
+  runPromiseScheduler,
+  runTestScheduler,
+} from "./test-runners.js"

package/src/insertIntoArray.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "vitest"
+
+import { insertIntoArray } from "./insertIntoArray.js"
+
+describe(insertIntoArray.name, () => {
+  test("inserts at the beginning", async () => {
+    expect(
+      insertIntoArray({
+        array: [1, 2, 3],
+        index: 0,
+        value: 0,
+      }),
+    ).toEqual([0, 1, 2, 3])
+  })
+
+  test("inserts after the first value", async () => {
+    expect(
+      insertIntoArray({
+        array: [1, 2, 3],
+        index: 1,
+        value: 0,
+      }),
+    ).toEqual([1, 0, 2, 3])
+  })
+
+  test("inserts at the end", async () => {
+    expect(
+      insertIntoArray({
+        array: [1, 2, 3],
+        index: 3,
+        value: 0,
+      }),
+    ).toEqual([1, 2, 3, 0])
+  })
+})

package/src/insertIntoArray.ts

@@ -0,0 +1,10 @@
+export const insertIntoArray = <Value>({
+  array,
+  index,
+  value,
+}: {
+  array: Value[]
+  index: number
+  value: Value
+}) =>
+  array.slice(0, index).concat(value, array.slice(index))

package/src/listDirectoryEntries.ts

@@ -0,0 +1,56 @@
+import { readdir, stat } from "node:fs/promises"
+import {
+  dirname,
+  sep as nativePathSeparator,
+} from "node:path"
+import { from, type Observable } from "rxjs"
+
+export type DirectoryEntry = {
+  isDirectory: boolean
+  name: string
+}
+
+export type ListDirectoryEntriesResult = {
+  entries: DirectoryEntry[]
+  separator: string
+}
+
+// One-shot directory listing for the path-field typeahead.
+//
+// Returns both the entries and the OS-native path separator ("\\" on Windows,
+// "/" on Linux/macOS) so the client can join paths with the right separator
+// regardless of what the user has typed so far.
+//
+// If `path` is a file, lists its parent directory instead — the typeahead
+// flow expects siblings of a partially-typed file path to surface.
+// Errors (path missing, permission denied, etc.) propagate so the calling
+// route can package them into the response's optional `error` field.
+export const listDirectoryEntries = (
+  path: string,
+): Observable<ListDirectoryEntriesResult> =>
+  from(
+    (async () => {
+      let lookupPath = path
+      try {
+        const stats = await stat(path)
+        if (!stats.isDirectory()) {
+          lookupPath = dirname(path)
+        }
+      } catch {
+        // Path doesn't exist as-is; let readdir below decide whether the
+        // parent works (and surface the actual error message if not).
+        lookupPath = dirname(path)
+      }
+
+      const entries = await readdir(lookupPath, {
+        withFileTypes: true,
+      })
+      return {
+        entries: entries.map((entry) => ({
+          isDirectory: entry.isDirectory(),
+          name: entry.name,
+        })),
+        separator: nativePathSeparator,
+      }
+    })(),
+  )

package/src/logAndRethrowPipelineError.test.ts

@@ -0,0 +1,53 @@
+import { throwError } from "rxjs"
+import { describe, expect, test } from "vitest"
+
+import { captureLogMessage } from "./captureLogMessage.js"
+import { logAndRethrowPipelineError } from "./logAndRethrowPipelineError.js"
+import { runTestScheduler } from "./test-runners.js"
+
+describe(logAndRethrowPipelineError.name, () => {
+  test("logs the error and re-emits it so downstream catchError handlers fire", async () => {
+    captureLogMessage("error", (logMessageSpy) => {
+      runTestScheduler(({ expectObservable }) => {
+        // "#" = error notification (vs. "|" for clean complete).
+        // logAndSwallowPipelineError returns "|";
+        // logAndRethrowPipelineError must return "#" with the original
+        // error preserved.
+        expectObservable(
+          throwError(() => "test error").pipe(
+            logAndRethrowPipelineError("testFunction"),
+          ),
+        ).toBe("#", undefined, "test error")
+      })
+
+      expect(logMessageSpy).toHaveBeenCalledOnce()
+
+      expect(
+        logMessageSpy.mock.calls[0].find((text) =>
+          text.includes("testFunction"),
+        ),
+      ).toContain("testFunction")
+    })
+  })
+
+  test("logs an error buffer and re-emits the original error", async () => {
+    captureLogMessage("error", (logMessageSpy) => {
+      runTestScheduler(({ expectObservable }) => {
+        const errorBuffer = Buffer.from("test error")
+        expectObservable(
+          throwError(() => errorBuffer).pipe(
+            logAndRethrowPipelineError("testFunction"),
+          ),
+        ).toBe("#", undefined, errorBuffer)
+      })
+
+      expect(logMessageSpy).toHaveBeenCalledOnce()
+
+      expect(
+        logMessageSpy.mock.calls[0].find((text) =>
+          text.includes("test error"),
+        ),
+      ).toBe("test error")
+    })
+  })
+})

package/src/logAndRethrowPipelineError.ts

@@ -0,0 +1,26 @@
+import {
+  catchError,
+  type OperatorFunction,
+  throwError,
+} from "rxjs"
+import { logError } from "./logMessage.js"
+
+// Logs the error under `func`'s name (or the provided string label) and
+// re-emits it as an observable error so the downstream catchError handlers
+// in jobRunner / sequenceRunner can flip the job's status to "failed".
+// Use this at the OUTER terminal pipe of an app-command. For INNER pipes
+// that should skip a broken item and continue the batch, use
+// `logAndSwallowPipelineError` instead.
+export const logAndRethrowPipelineError = <PipelineValue>(
+  func: { name: string } | string,
+): OperatorFunction<PipelineValue, PipelineValue> =>
+  catchError((error) => {
+    logError(
+      typeof func === "string" ? func : func.name,
+      Buffer.isBuffer(error)
+        ? error.toString("utf8")
+        : error,
+    )
+
+    return throwError(() => error)
+  })

package/src/logAndSwallowPipelineError.test.ts

@@ -0,0 +1,60 @@
+import { throwError } from "rxjs"
+import { describe, expect, test } from "vitest"
+
+import { captureLogMessage } from "./captureLogMessage.js"
+import { logAndSwallowPipelineError } from "./logAndSwallowPipelineError.js"
+import { runTestScheduler } from "./test-runners.js"
+
+describe(logAndSwallowPipelineError.name, () => {
+  test("catches a pipeline error and completes cleanly", async () => {
+    captureLogMessage("error", (logMessageSpy) => {
+      runTestScheduler(({ expectObservable }) => {
+        expectObservable(
+          throwError(() => "test error").pipe(
+            logAndSwallowPipelineError("testFunction"),
+          ),
+        ).toBe("|")
+      })
+
+      expect(logMessageSpy).toHaveBeenCalledOnce()
+
+      expect(
+        logMessageSpy.mock.calls[0].find((text) =>
+          text.includes("testFunction"),
+        ),
+      ).toContain("testFunction")
+
+      expect(
+        logMessageSpy.mock.calls[0].find((text) =>
+          text.includes("test error"),
+        ),
+      ).toContain("test error")
+    })
+  })
+
+  test("logs an error buffer", async () => {
+    captureLogMessage("error", (logMessageSpy) => {
+      runTestScheduler(({ expectObservable }) => {
+        expectObservable(
+          throwError(() => Buffer.from("test error")).pipe(
+            logAndSwallowPipelineError("testFunction"),
+          ),
+        ).toBe("|")
+      })
+
+      expect(logMessageSpy).toHaveBeenCalledOnce()
+
+      expect(
+        logMessageSpy.mock.calls[0].find((text) =>
+          text.includes("testFunction"),
+        ),
+      ).toContain("testFunction")
+
+      expect(
+        logMessageSpy.mock.calls[0].find((text) =>
+          text.includes("test error"),
+        ),
+      ).toBe("test error")
+    })
+  })
+})

package/src/logAndSwallowPipelineError.ts

@@ -0,0 +1,26 @@
+import {
+  catchError,
+  EMPTY,
+  type OperatorFunction,
+} from "rxjs"
+import { logError } from "./logMessage.js"
+
+// Logs the error under `func`'s name (or the provided string label) and
+// completes the observable with no emissions. Use this in INNER pipes —
+// per-file `mergeMap`/`concatMap` callbacks where one bad item shouldn't
+// abort the rest of the batch (e.g. spawn-op wrappers, per-file fetch
+// helpers). For OUTER terminal pipes that need the error to reach the
+// runner, use `logAndRethrowPipelineError` instead.
+export const logAndSwallowPipelineError = <PipelineValue>(
+  func: { name: string } | string,
+): OperatorFunction<PipelineValue, PipelineValue> =>
+  catchError((error) => {
+    logError(
+      typeof func === "string" ? func : func.name,
+      Buffer.isBuffer(error)
+        ? error.toString("utf8")
+        : error,
+    )
+
+    return EMPTY
+  })

package/src/logMessage.test.ts

@@ -0,0 +1,207 @@
+import { Chalk } from "chalk"
+import { describe, expect, test } from "vitest"
+import { captureConsoleMessage } from "./captureConsoleMessage.js"
+import {
+  createAddColorToChalk,
+  createLogMessage,
+  logError,
+  logInfo,
+  logWarning,
+  messageTemplate,
+} from "./logMessage.js"
+
+describe(createAddColorToChalk.name, () => {
+  test("adds no colors when none passed", async () => {
+    const chalk = new Chalk()
+
+    const modifiedChalk = createAddColorToChalk()(chalk)
+
+    expect(modifiedChalk("Hello World!")).toBe(
+      "Hello World!",
+    )
+  })
+
+  test("adds text color", async () => {
+    const chalk = new Chalk()
+
+    const modifiedChalk =
+      createAddColorToChalk("white")(chalk)
+
+    expect(modifiedChalk("Hello World!")).toBe(
+      chalk.white("Hello World!"),
+    )
+  })
+
+  test("adds a background color", async () => {
+    const chalk = new Chalk()
+
+    const modifiedChalk =
+      createAddColorToChalk("bgWhite")(chalk)
+
+    expect(modifiedChalk("Hello World!")).toBe(
+      chalk.bgWhite("Hello World!"),
+    )
+  })
+
+  test("adds both text and background colors", async () => {
+    const chalk = new Chalk()
+
+    const modifiedChalk = createAddColorToChalk("bgWhite")(
+      createAddColorToChalk("black")(chalk),
+    )
+
+    expect(modifiedChalk("Hello World!")).toBe(
+      chalk.black.bgWhite("Hello World!"),
+    )
+  })
+})
+
+describe("messageTemplate", () => {
+  test(messageTemplate.comparison.name, () => {
+    expect(
+      messageTemplate.comparison("old.mkv", "new.mkv"),
+    ).toEqual(["old.mkv", "\n", "new.mkv"])
+  })
+
+  test(messageTemplate.descriptiveComparison.name, () => {
+    expect(
+      messageTemplate.descriptiveComparison(
+        12345,
+        "old.mkv",
+        "new.mkv",
+      ),
+    ).toEqual([
+      12345,
+      "\n",
+      "\n",
+      "old.mkv",
+      "\n",
+      "new.mkv",
+    ])
+  })
+
+  test(messageTemplate.noItems.name, () => {
+    expect(messageTemplate.noItems()).toEqual([])
+  })
+
+  test(messageTemplate.singleItem.name, () => {
+    expect(messageTemplate.singleItem("new.mkv")).toEqual([
+      "new.mkv",
+    ])
+  })
+
+  test(messageTemplate.multipleItems.name, () => {
+    expect(
+      messageTemplate.multipleItems("DOWNLOADED", [
+        "a.mkv",
+        "b.mkv",
+        "c.mkv",
+      ]),
+    ).toEqual([
+      "DOWNLOADED",
+      "\n",
+      "a.mkv",
+      "\n",
+      "b.mkv",
+      "\n",
+      "c.mkv",
+      "\n",
+    ])
+  })
+})
+
+describe(createLogMessage.name, () => {
+  test("logs only once", async () => {
+    captureConsoleMessage("info", (consoleSpy) => {
+      createLogMessage({
+        logType: "info",
+      })("HELLO WORLD")
+
+      expect(consoleSpy).toHaveBeenCalledOnce()
+
+      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
+        "HELLO WORLD",
+      )
+    })
+  })
+
+  test("logs an informational message", async () => {
+    captureConsoleMessage("info", (consoleSpy) => {
+      createLogMessage({
+        logType: "info",
+      })("RENAMED", "old.mkv", "new.mkv")
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[RENAMED]",
+        "\n",
+        "old.mkv",
+        "\n",
+        "new.mkv",
+        "\n",
+        "\n",
+      )
+    })
+
+    // TODO: TEST COLORS
+  })
+
+  test("dispatches to the multipleItems template when content arg 1 is an array", async () => {
+    captureConsoleMessage("info", (consoleSpy) => {
+      createLogMessage({
+        logType: "info",
+      })("DOWNLOADED", "Files downloaded:", [
+        "a.mkv",
+        "b.mkv",
+      ])
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[DOWNLOADED]",
+        "\n",
+        "Files downloaded:",
+        "\n",
+        "a.mkv",
+        "\n",
+        "b.mkv",
+        "\n",
+        "\n",
+        "\n",
+      )
+    })
+  })
+})
+
+describe(logError.name, () => {
+  test("logs an error message", async () => {
+    captureConsoleMessage("error", (consoleSpy) => {
+      logError("ERROR")
+
+      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
+        "ERROR",
+      )
+    })
+  })
+})
+
+describe(logInfo.name, () => {
+  test("logs an info message", async () => {
+    captureConsoleMessage("info", (consoleSpy) => {
+      logInfo("INFO")
+
+      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
+        "INFO",
+      )
+    })
+  })
+})
+
+describe(logWarning.name, () => {
+  test("logs a warning message", async () => {
+    captureConsoleMessage("warn", (consoleSpy) => {
+      logWarning("WARNING")
+
+      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
+        "WARNING",
+      )
+    })
+  })
+})