@mux-magic/tools 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mux-magic/tools",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Reusable utilities (file system, logging, rxjs operators) shared between @mux-magic/server and sibling tools like Gallery-Downloader.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./src/*": "./src/*"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "fast-sort": "^3.4.1",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "memfs": "^4.57.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}

package/src/__fixtures__/badBooleanName.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/naming-convention -- intentional: test fixture for the is/has ESLint rule
+export const wrongBool: boolean = true

package/src/aclSafeCopyFile.test.ts

@@ -0,0 +1,136 @@
+import { vol } from "memfs"
+import { describe, expect, test, vi } from "vitest"
+
+import {
+  aclSafeCopyFile,
+  type CopyProgressEvent,
+} from "./aclSafeCopyFile.js"
+
+describe(aclSafeCopyFile.name, () => {
+  test("copies file contents to a new destination", async () => {
+    vol.fromJSON({
+      "/cache/source.mkv": "anime episode bytes",
+      "/anime": null,
+    })
+
+    await expect(
+      aclSafeCopyFile(
+        "/cache/source.mkv",
+        "/anime/target.mkv",
+      ),
+    ).resolves.toBeUndefined()
+
+    expect(
+      vol.readFileSync("/anime/target.mkv", "utf8"),
+    ).toBe("anime episode bytes")
+  })
+
+  test("overwrites an existing destination", async () => {
+    vol.fromJSON({
+      "/cache/source.mkv": "fresh bytes",
+      "/anime/target.mkv": "stale bytes",
+    })
+
+    await expect(
+      aclSafeCopyFile(
+        "/cache/source.mkv",
+        "/anime/target.mkv",
+      ),
+    ).resolves.toBeUndefined()
+
+    expect(
+      vol.readFileSync("/anime/target.mkv", "utf8"),
+    ).toBe("fresh bytes")
+  })
+
+  test("rejects when the source is missing", async () => {
+    await expect(
+      aclSafeCopyFile(
+        "/cache/missing.mkv",
+        "/anime/target.mkv",
+      ),
+    ).rejects.toThrow("no such file or directory")
+  })
+
+  test("leaves the source untouched", async () => {
+    vol.fromJSON({
+      "/cache/source.mkv": "original bytes",
+      "/anime": null,
+    })
+
+    await aclSafeCopyFile(
+      "/cache/source.mkv",
+      "/anime/target.mkv",
+    )
+
+    expect(
+      vol.readFileSync("/cache/source.mkv", "utf8"),
+    ).toBe("original bytes")
+  })
+
+  test("reports progress when onProgress is supplied", async () => {
+    vol.fromJSON({
+      "/cache/source.mkv": "twelve bytes",
+      "/anime": null,
+    })
+
+    const progressEvents: CopyProgressEvent[] = []
+
+    await aclSafeCopyFile(
+      "/cache/source.mkv",
+      "/anime/target.mkv",
+      {
+        onProgress: (event) => {
+          progressEvents.push(event)
+        },
+      },
+    )
+
+    expect(progressEvents.length).toBeGreaterThan(0)
+
+    const finalEvent = progressEvents.at(-1)
+    if (finalEvent == null)
+      throw new Error("no progress events")
+
+    expect(finalEvent.source).toBe("/cache/source.mkv")
+    expect(finalEvent.destination).toBe("/anime/target.mkv")
+    expect(finalEvent.totalBytes).toBe(12)
+    expect(finalEvent.bytesWritten).toBe(12)
+  })
+
+  test("does not call onProgress when options are omitted", async () => {
+    vol.fromJSON({
+      "/cache/source.mkv": "anything",
+      "/anime": null,
+    })
+
+    const onProgress = vi.fn()
+
+    await aclSafeCopyFile(
+      "/cache/source.mkv",
+      "/anime/target.mkv",
+    )
+
+    expect(onProgress).not.toHaveBeenCalled()
+  })
+
+  test("aborts via signal and unlinks the partial destination", async () => {
+    vol.fromJSON({
+      "/cache/source.mkv": "x".repeat(1024 * 64),
+      "/anime": null,
+    })
+
+    const abortController = new AbortController()
+    abortController.abort()
+
+    await expect(
+      aclSafeCopyFile(
+        "/cache/source.mkv",
+        "/anime/target.mkv",
+        { signal: abortController.signal },
+      ),
+    ).rejects.toBeDefined()
+
+    expect(vol.existsSync("/anime/target.mkv")).toBe(false)
+  })
+})

package/src/aclSafeCopyFile.ts

@@ -0,0 +1,136 @@
+import {
+  createReadStream,
+  createWriteStream,
+} from "node:fs"
+import { stat, unlink } from "node:fs/promises"
+import { Transform } from "node:stream"
+import { pipeline } from "node:stream/promises"
+
+/**
+ * Per-chunk progress notification fired while a single file is being
+ * copied. `bytesWritten` accumulates monotonically up to `totalBytes`
+ * across the lifetime of one file copy. `source`/`destination`
+ * identify which file the event belongs to.
+ */
+export type CopyProgressEvent = {
+  source: string
+  destination: string
+  bytesWritten: number
+  totalBytes: number
+}
+
+/**
+ * Optional behavior toggles for `aclSafeCopyFile`. Pass `onProgress`
+ * to receive byte-level updates as the copy streams through; omit
+ * the options object entirely (the common case) to skip the progress
+ * instrumentation and the upfront `stat` call it requires.
+ *
+ * Pass `signal` to make the copy abortable mid-stream — `pipeline`
+ * destroys the read/write streams when the signal fires and the
+ * returned promise rejects with an AbortError. Callers (e.g.
+ * `copyFiles`, `flattenOutput`) wire this into a per-job
+ * `AbortController` whose lifetime tracks the outer Observable, so
+ * an unsubscribe (sequence cancel / sibling-fail cascade) interrupts
+ * the in-flight copy instead of letting it finish.
+ */
+export type CopyOptions = {
+  onProgress?: (event: CopyProgressEvent) => void
+  signal?: AbortSignal
+}
+
+/**
+ * Copies a single file's bytes from `source` to `destination` via a
+ * stream pipeline. Equivalent to GNU `cp` without flags: data only,
+ * no mode preservation, no timestamp preservation, no ownership
+ * preservation.
+ *
+ * Built to work around an EPERM that `node:fs.copyFile` and
+ * `node:fs.cp` hit on TrueNAS ZFS datasets configured with
+ * `aclmode=restricted`. libuv's internal copyfile path calls
+ * `fchmod()` on the destination after the data copy to preserve the
+ * source's mode bits, and that chmod fails against NFSv4 ACLs even
+ * when the mode is unchanged. Streaming the bytes never invokes
+ * chmod, so the copy goes through.
+ *
+ * Files only — does not handle directory copies. The destination's
+ * parent directory must already exist; callers are expected to
+ * `mkdir`-recursive first (the underlying `createWriteStream` rejects
+ * with ENOENT otherwise). Callers needing recursive copy should
+ * compose with `readFilesAtDepth` and RxJS `mergeAll(cpus().length)`
+ * the same way `syncAnimeDownloads` and `syncMangaFolders` already
+ * do — that gives per-file concurrency control, observable progress,
+ * and cancellation that a sequential walker cannot.
+ *
+ * Pass `options.onProgress` to receive per-chunk byte updates. When
+ * omitted, the function takes a fast path that skips the upfront
+ * `stat` call and the in-pipeline counting transform.
+ */
+// On abort, the destination is left as a half-written partial. The
+// next run would either skip it (if same size by accident) or worse,
+// be inspected by the user as if the copy had succeeded. Best-effort
+// unlink of the partial: ignore ENOENT (file never opened) and any
+// other unlink error — abort cleanup must not mask the original
+// AbortError that the caller is about to receive.
+const removePartialOnAbort = async (
+  signal: AbortSignal | undefined,
+  destination: string,
+): Promise<void> => {
+  if (signal === undefined || !signal.aborted) return
+  try {
+    await unlink(destination)
+  } catch {
+    // partial may not exist (createWriteStream lazy-opens) — ignore
+  }
+}
+
+export const aclSafeCopyFile = async (
+  source: string,
+  destination: string,
+  options?: CopyOptions,
+): Promise<void> => {
+  const signal = options?.signal
+
+  if (!options?.onProgress) {
+    try {
+      await pipeline(
+        createReadStream(source),
+        createWriteStream(destination),
+        signal === undefined ? {} : { signal },
+      )
+      return
+    } catch (error) {
+      await removePartialOnAbort(signal, destination)
+      throw error
+    }
+  }
+
+  const onProgress = options.onProgress
+
+  const { size: totalBytes } = await stat(source)
+
+  let bytesWritten = 0
+  const progressTransform = new Transform({
+    transform(chunk, _encoding, callback) {
+      bytesWritten += chunk.length
+      onProgress({
+        source,
+        destination,
+        bytesWritten,
+        totalBytes,
+      })
+      callback(null, chunk)
+    },
+  })
+
+  try {
+    await pipeline(
+      createReadStream(source),
+      progressTransform,
+      createWriteStream(destination),
+      signal === undefined ? {} : { signal },
+    )
+  } catch (error) {
+    await removePartialOnAbort(signal, destination)
+    throw error
+  }
+}

package/src/addFolderNameBeforeFilename.ts

@@ -0,0 +1,13 @@
+import { dirname, join } from "node:path"
+
+export const addFolderNameBeforeFilename = ({
+  filePath,
+  folderName,
+}: {
+  filePath: string
+  folderName: string
+}) =>
+  filePath.replace(
+    dirname(filePath),
+    join(dirname(filePath), folderName),
+  )

package/src/captureConsoleMessage.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from "vitest"
+
+import { captureConsoleMessage } from "./captureConsoleMessage.js"
+
+describe(captureConsoleMessage.name, () => {
+  test("captures a console log message", async () => {
+    const testMessage = "test message"
+
+    captureConsoleMessage("log", (consoleSpy) => {
+      console.log(testMessage)
+
+      expect(consoleSpy).toHaveBeenCalledOnce()
+
+      expect(consoleSpy).toHaveBeenCalledWith(testMessage)
+    })
+  })
+
+  test("captures multiple console log args", async () => {
+    const testMessages = [
+      "test message 1",
+      "test message 2",
+      "test message 3",
+    ]
+
+    captureConsoleMessage("log", (consoleSpy) => {
+      console.log(
+        testMessages[0],
+        testMessages[1],
+        testMessages[2],
+      )
+
+      expect(consoleSpy).toHaveBeenCalledOnce()
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        testMessages[0],
+        testMessages[1],
+        testMessages[2],
+      )
+    })
+  })
+
+  test("captures multiple console log messages", async () => {
+    const testMessages = [
+      "test message 1",
+      "test message 2",
+      "test message 3",
+    ]
+
+    captureConsoleMessage("log", (consoleSpy) => {
+      console.log(testMessages[0])
+
+      console.log(testMessages[1])
+
+      console.log(testMessages[2])
+
+      expect(consoleSpy).toHaveBeenCalledTimes(3)
+
+      expect(consoleSpy).toHaveBeenNthCalledWith(
+        1,
+        testMessages[0],
+      )
+
+      expect(consoleSpy).toHaveBeenNthCalledWith(
+        2,
+        testMessages[1],
+      )
+
+      expect(consoleSpy).toHaveBeenNthCalledWith(
+        3,
+        testMessages[2],
+      )
+    })
+  })
+
+  test("clears mock after task complete", async () => {
+    const testMessage = "test message"
+
+    const capturedConsoleSpy = captureConsoleMessage(
+      "log",
+      (consoleSpy) => {
+        console.log(testMessage)
+
+        return consoleSpy
+      },
+    )
+
+    expect(capturedConsoleSpy).not.toHaveBeenCalled()
+  })
+
+  test("captures async console log messages", async () => {
+    const testMessage = "test message"
+
+    await captureConsoleMessage(
+      "log",
+      async (consoleSpy) => {
+        console.log(testMessage)
+
+        await Promise.resolve(consoleSpy)
+
+        expect(consoleSpy).toHaveBeenCalledOnce()
+
+        expect(consoleSpy).toHaveBeenCalledWith(testMessage)
+      },
+    )
+  })
+
+  test("clears mock after async task complete", async () => {
+    const testMessage = "test message"
+
+    const capturedConsoleSpy = await captureConsoleMessage(
+      "log",
+      async (consoleSpy) => {
+        console.log(testMessage)
+
+        return Promise.resolve(consoleSpy)
+      },
+    )
+
+    expect(capturedConsoleSpy).not.toHaveBeenCalled()
+  })
+
+  test("doesn't capture a message when no message logged", async () => {
+    captureConsoleMessage("log", (consoleSpy) => {
+      expect(consoleSpy).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/captureConsoleMessage.ts

@@ -0,0 +1,22 @@
+import { type MockInstance, vi } from "vitest"
+
+export const captureConsoleMessage = <TaskResponse>(
+  logType: "error" | "info" | "log" | "warn",
+  task: (consoleSpy: MockInstance) => TaskResponse,
+) => {
+  const consoleSpy = vi
+    .spyOn(console, logType)
+    .mockImplementation(() => {})
+
+  const taskResponse = task(consoleSpy)
+
+  if (taskResponse instanceof Promise) {
+    taskResponse.finally(() => {
+      consoleSpy.mockClear()
+    })
+  } else {
+    consoleSpy.mockClear()
+  }
+
+  return taskResponse
+}

package/src/captureLogMessage.ts

@@ -0,0 +1,11 @@
+import { captureConsoleMessage } from "./captureConsoleMessage.js"
+import type { createLogMessage } from "./logMessage.js"
+
+export const captureLogMessage = <TaskResponse>(
+  logType: Parameters<
+    typeof createLogMessage
+  >[0]["logType"],
+  task: Parameters<
+    typeof captureConsoleMessage<TaskResponse>
+  >[1],
+) => captureConsoleMessage(logType, task)

package/src/cleanupFilename.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "vitest"
+
+import { cleanupFilename } from "./cleanupFilename.js"
+
+describe(cleanupFilename.name, () => {
+  ;[
+    {
+      input:
+        "Super String: Marco Polo’s Travel to the Multiverse",
+      expected:
+        "Super String - Marco Polo’s Travel to the Multiverse",
+    },
+    {
+      input: "Some Title:Marco",
+      expected: "Some Title-Marco",
+    },
+    {
+      input: "Some Title : Marco",
+      expected: "Some Title - Marco",
+    },
+  ].forEach(({ input, expected }) => {
+    test(`from "${input}"`, () => {
+      expect(cleanupFilename(input)).toBe(expected)
+    })
+  })
+})

package/src/cleanupFilename.ts

@@ -0,0 +1,14 @@
+export const cleanupFilename = (filename: string) =>
+  filename
+    .replaceAll("\n", " ")
+    .replaceAll(/(\w): /g, "$1 - ")
+    .replaceAll(/:/g, "-")
+    .replaceAll("?", "_")
+    .replaceAll('"', "")
+    .replaceAll("/", "-")
+    .replaceAll("<", "[")
+    .replaceAll(">", "]")
+    .replaceAll("*", "@")
+    .replaceAll("...", "--")
+    .replaceAll(" | ", " - ")
+    .trim()