@mux-magic/tools 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mux-magic/tools",
-  "version": "1.0.0",
+  "version": "1.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",

package/src/applyRenameRegex.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "vitest"
+
+import { applyRenameRegex } from "./applyRenameRegex.js"
+
+describe(applyRenameRegex.name, () => {
+  test("returns the input unchanged when renameRegex is undefined", () => {
+    expect(
+      applyRenameRegex("My Show - 01.mkv", undefined),
+    ).toBe("My Show - 01.mkv")
+  })
+
+  test("returns the input unchanged when the pattern does not match", () => {
+    expect(
+      applyRenameRegex("My Show - 01.mkv", {
+        pattern: "^\\[Group\\] ",
+        replacement: "",
+      }),
+    ).toBe("My Show - 01.mkv")
+  })
+
+  test("applies a simple replacement", () => {
+    expect(
+      applyRenameRegex("[Group] My Show - 01.mkv", {
+        pattern: "^\\[Group\\] ",
+        replacement: "",
+      }),
+    ).toBe("My Show - 01.mkv")
+  })
+
+  test("supports numbered capture groups", () => {
+    expect(
+      applyRenameRegex("[Group] My Show - 01 [1080p].mkv", {
+        pattern: "^\\[.*?\\] (.+?) \\[.*?\\](\\.\\w+)$",
+        replacement: "$1$2",
+      }),
+    ).toBe("My Show - 01.mkv")
+  })
+
+  test("supports named capture groups", () => {
+    expect(
+      applyRenameRegex("Show.s01e03.Episode.mkv", {
+        pattern:
+          "^(?<series>.+?)\\.(?<season>s\\d+)(?<episode>e\\d+)\\.(?<title>.+)\\.mkv$",
+        replacement:
+          "$<series> - $<season>$<episode> - $<title>.mkv",
+      }),
+    ).toBe("Show - s01e03 - Episode.mkv")
+  })
+})

package/src/applyRenameRegex.ts

@@ -0,0 +1,22 @@
+// Canonical rename-regex shape consumed by `copyFiles`, `moveFiles`,
+// and `renameFiles`. Worker 65 added optional `flags` (passed to the
+// `RegExp` ctor as the second arg) and `sample` (UI-only documentation
+// the runtime ignores). Pre-flags templates still satisfy this type
+// because both fields are optional.
+export type RenameRegex = {
+  pattern: string
+  replacement: string
+  flags?: string
+  sample?: string
+}
+
+export const applyRenameRegex = (
+  name: string,
+  renameRegex: RenameRegex | undefined,
+): string =>
+  renameRegex
+    ? name.replace(
+        new RegExp(renameRegex.pattern, renameRegex.flags),
+        renameRegex.replacement,
+      )
+    : name

package/src/index.ts

@@ -14,6 +14,10 @@ export {
   type CopyProgressEvent,
 } from "./aclSafeCopyFile.js"
 export { addFolderNameBeforeFilename } from "./addFolderNameBeforeFilename.js"
+export {
+  applyRenameRegex,
+  type RenameRegex,
+} from "./applyRenameRegex.js"
 export { captureConsoleMessage } from "./captureConsoleMessage.js"
 export { captureLogMessage } from "./captureLogMessage.js"
 export { cleanupFilename } from "./cleanupFilename.js"
@@ -42,6 +46,29 @@ export {
 } from "./listDirectoryEntries.js"
 export { logAndRethrowPipelineError } from "./logAndRethrowPipelineError.js"
 export { logAndSwallowPipelineError } from "./logAndSwallowPipelineError.js"
+export {
+  getLoggingContext,
+  type LoggerContext,
+  loggingContext,
+  withLoggingContext,
+} from "./logging/context.js"
+export { formatLogLine } from "./logging/lineSink.js"
+export {
+  __resetLogSinksForTests,
+  getLogger,
+  type Logger,
+  type LogLevel,
+  type LogRecord,
+  type LogSink,
+  registerLogSink,
+} from "./logging/logger.js"
+export {
+  __resetLoggingModeForTests,
+  getLoggingMode,
+  type LoggingMode,
+  setLoggingMode,
+} from "./logging/mode.js"
+export { startSpan } from "./logging/startSpan.js"
 export {
   createAddColorToChalk,
   createLogMessage,
@@ -53,6 +80,21 @@ export {
 export { makeDirectory } from "./makeDirectory.js"
 export { naturalSort } from "./naturalSort.js"
 export { replaceFileExtension } from "./replaceFileExtension.js"
+export {
+  SOURCE_PATH_FIELD_NAME,
+  SOURCE_PATH_LABEL,
+  type SourcePath,
+} from "./sourcePath.js"
+export {
+  __resetTaskSchedulerForTests,
+  initTaskScheduler,
+  mergeMapOrdered,
+  registerJobClaim,
+  runTask,
+  runTasks,
+  runTasksOrdered,
+  unregisterJobClaim,
+} from "./taskScheduler.js"
 export {
   getOperatorValue,
   runPromiseScheduler,

package/src/logMessage.test.ts

@@ -1,6 +1,15 @@
 import { Chalk } from "chalk"
 import { describe, expect, test } from "vitest"
 import { captureConsoleMessage } from "./captureConsoleMessage.js"
+import {
+  __resetLogSinksForTests,
+  type LogRecord,
+  registerLogSink,
+} from "./logging/logger.js"
+import {
+  __resetLoggingModeForTests,
+  setLoggingMode,
+} from "./logging/mode.js"
 import {
   createAddColorToChalk,
   createLogMessage,
@@ -118,9 +127,11 @@ describe(createLogMessage.name, () => {
       })("HELLO WORLD")
 
       expect(consoleSpy).toHaveBeenCalledOnce()
-
-      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
-        "HELLO WORLD",
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("HELLO WORLD"),
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
       )
     })
   })
@@ -175,8 +186,11 @@ describe(logError.name, () => {
     captureConsoleMessage("error", (consoleSpy) => {
       logError("ERROR")
 
-      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
-        "ERROR",
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("ERROR"),
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
       )
     })
   })
@@ -187,8 +201,11 @@ describe(logInfo.name, () => {
     captureConsoleMessage("info", (consoleSpy) => {
       logInfo("INFO")
 
-      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
-        "INFO",
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("INFO"),
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
       )
     })
   })
@@ -199,9 +216,95 @@ describe(logWarning.name, () => {
     captureConsoleMessage("warn", (consoleSpy) => {
       logWarning("WARNING")
 
-      expect(consoleSpy.mock.calls.at(0)?.at(0)).toContain(
-        "WARNING",
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("WARNING"),
+        expect.anything(),
+        expect.anything(),
+        expect.anything(),
       )
     })
   })
 })
+
+describe("logMessage mode-awareness", () => {
+  test('"api" mode emits a structured record AND skips chalk console', () => {
+    __resetLogSinksForTests()
+    let records: readonly LogRecord[] = []
+    registerLogSink((record) => {
+      records = records.concat(record)
+    })
+    setLoggingMode("api")
+
+    captureConsoleMessage("info", (consoleSpy) => {
+      logInfo("SEQUENCE", "Step step1 starting.")
+      expect(consoleSpy).not.toHaveBeenCalled()
+    })
+
+    __resetLoggingModeForTests()
+    __resetLogSinksForTests()
+
+    expect(records).toHaveLength(1)
+    expect(records[0]).toMatchObject({
+      level: "info",
+      tag: "SEQUENCE",
+      msg: "Step step1 starting.",
+    })
+  })
+
+  test('"cli" mode (default) emits NO structured record', () => {
+    __resetLogSinksForTests()
+    let records: readonly LogRecord[] = []
+    registerLogSink((record) => {
+      records = records.concat(record)
+    })
+
+    captureConsoleMessage("info", () => {
+      logInfo("SEQUENCE", "Step step1 starting.")
+    })
+
+    expect(records).toHaveLength(0)
+    __resetLogSinksForTests()
+  })
+
+  test('"cli-debug" mode emits BOTH a structured record AND the chalk console line', () => {
+    __resetLogSinksForTests()
+    let records: readonly LogRecord[] = []
+    registerLogSink((record) => {
+      records = records.concat(record)
+    })
+    setLoggingMode("cli-debug")
+
+    captureConsoleMessage("info", (consoleSpy) => {
+      logInfo("SEQUENCE", "Step step1 starting.")
+      expect(consoleSpy).toHaveBeenCalled()
+    })
+
+    __resetLoggingModeForTests()
+    __resetLogSinksForTests()
+
+    expect(records).toHaveLength(1)
+    expect(records[0]?.tag).toBe("SEQUENCE")
+  })
+
+  test('"api" mode for logError emits a structured "error" record', () => {
+    __resetLogSinksForTests()
+    let records: readonly LogRecord[] = []
+    registerLogSink((record) => {
+      records = records.concat(record)
+    })
+    setLoggingMode("api")
+
+    captureConsoleMessage("error", () => {
+      logError("SEQUENCE", "boom")
+    })
+
+    __resetLoggingModeForTests()
+    __resetLogSinksForTests()
+
+    expect(records[0]).toMatchObject({
+      level: "error",
+      tag: "SEQUENCE",
+      msg: "boom",
+    })
+  })
+})

package/src/logMessage.ts

@@ -6,6 +6,12 @@ import {
   type ForegroundColorName,
 } from "chalk"
 
+import {
+  getLogger,
+  type LogLevel,
+} from "./logging/logger.js"
+import { getLoggingMode } from "./logging/mode.js"
+
 export const createAddColorToChalk =
   (chalkColor?: ColorName) =>
   (chalkInstance: ChalkInstance) =>
@@ -92,6 +98,29 @@ export const createLogMessage =
             )
           : null
 
+    const mode = getLoggingMode()
+    const messageArray = message || content
+
+    if (mode === "api" || mode === "cli-debug") {
+      const structuredMsg = (
+        messageArray as readonly unknown[]
+      )
+        .map((part) =>
+          typeof part === "string" ? part : String(part),
+        )
+        .join(" ")
+        .trim()
+      const structuredLevel: LogLevel =
+        logType === "log" ? "info" : logType
+      getLogger()[structuredLevel](structuredMsg, {
+        tag: title,
+      })
+    }
+
+    if (mode === "api") {
+      return
+    }
+
     console[logType](
       optionallyColoredChalk(`[${title}]`),
       "\n",

package/src/logging/context.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "vitest"
+
+import {
+  getLoggingContext,
+  loggingContext,
+  withLoggingContext,
+} from "./context.js"
+
+describe(withLoggingContext.name, () => {
+  test("seeds the context for the duration of fn", () => {
+    const seen = withLoggingContext({ jobId: "j1" }, () =>
+      getLoggingContext(),
+    )
+
+    expect(seen).toEqual({ jobId: "j1" })
+  })
+
+  test("returns an empty context outside any run", () => {
+    expect(getLoggingContext()).toEqual({})
+  })
+
+  test("nested call merges parent bindings under the child", () => {
+    const seen = withLoggingContext(
+      { jobId: "j1", stepIndex: 0 },
+      () =>
+        withLoggingContext(
+          { stepIndex: 2, fileId: "f" },
+          () => getLoggingContext(),
+        ),
+    )
+
+    expect(seen).toEqual({
+      jobId: "j1",
+      stepIndex: 2,
+      fileId: "f",
+    })
+  })
+
+  test("propagates through awaited promises", async () => {
+    const seen = await withLoggingContext(
+      { jobId: "j-async" },
+      async () => {
+        await Promise.resolve()
+        await new Promise((resolve) =>
+          setTimeout(resolve, 0),
+        )
+        return getLoggingContext()
+      },
+    )
+
+    expect(seen.jobId).toBe("j-async")
+  })
+
+  test("`loggingContext` is a single AsyncLocalStorage instance", () => {
+    expect(loggingContext.getStore).toBeTypeOf("function")
+  })
+})

package/src/logging/context.ts

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+
+export type LoggerContext = {
+  jobId?: string
+  stepIndex?: number
+  fileId?: string
+  traceId?: string
+  spanId?: string
+}
+
+export const loggingContext =
+  new AsyncLocalStorage<LoggerContext>()
+
+export const getLoggingContext = (): LoggerContext =>
+  loggingContext.getStore() ?? {}
+
+export const withLoggingContext = <T>(
+  bindings: LoggerContext,
+  fn: () => T,
+): T => {
+  const merged = { ...getLoggingContext(), ...bindings }
+  return loggingContext.run(merged, fn)
+}

package/src/logging/lineSink.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "vitest"
+
+import { formatLogLine } from "./lineSink.js"
+
+describe(formatLogLine.name, () => {
+  test("uses bracketed local-time timestamp prefix matching legacy logCapture", () => {
+    const now = new Date()
+    now.setHours(8, 21, 33, 512)
+
+    const line = formatLogLine(
+      { level: "info", msg: "copy finished" },
+      now,
+    )
+
+    expect(line.startsWith("[08:21:33.512]")).toBe(true)
+  })
+
+  test("emits `<timestamp> <level> <msg>` for a record with no extra fields", () => {
+    const now = new Date()
+    now.setHours(0, 0, 0, 0)
+
+    const line = formatLogLine(
+      { level: "warn", msg: "be careful" },
+      now,
+    )
+
+    expect(line).toBe("[00:00:00.000] warn be careful")
+  })
+
+  test("renders extra fields inline as field=value before the msg", () => {
+    const now = new Date()
+    now.setHours(12, 0, 0, 0)
+
+    const line = formatLogLine(
+      {
+        level: "info",
+        msg: "step started",
+        stepIndex: 2,
+        fileId: "foo.mkv",
+      },
+      now,
+    )
+
+    expect(line).toBe(
+      "[12:00:00.000] info stepIndex=2 fileId=foo.mkv step started",
+    )
+  })
+
+  test("does not render undefined fields", () => {
+    const now = new Date()
+    now.setHours(0, 0, 0, 0)
+
+    const line = formatLogLine(
+      {
+        level: "info",
+        msg: "m",
+        jobId: undefined,
+        stepIndex: 1,
+      },
+      now,
+    )
+
+    expect(line).not.toContain("jobId")
+    expect(line).toContain("stepIndex=1")
+  })
+
+  test("quotes string values that contain whitespace", () => {
+    const now = new Date()
+    now.setHours(0, 0, 0, 0)
+
+    const line = formatLogLine(
+      {
+        level: "info",
+        msg: "named",
+        detail: "two words",
+      },
+      now,
+    )
+
+    expect(line).toContain(`detail="two words"`)
+  })
+
+  test("renders `[ts] [TAG] msg` when a `tag` field is present (preserves legacy chalk-stripped shape)", () => {
+    const now = new Date()
+    now.setHours(8, 21, 33, 512)
+
+    const line = formatLogLine(
+      {
+        level: "info",
+        msg: "Step step1 starting.",
+        tag: "SEQUENCE",
+      },
+      now,
+    )
+
+    expect(line).toBe(
+      "[08:21:33.512] [SEQUENCE] Step step1 starting.",
+    )
+  })
+
+  test("tag-mode line still appends remaining extra fields", () => {
+    const now = new Date()
+    now.setHours(0, 0, 0, 0)
+
+    const line = formatLogLine(
+      {
+        level: "info",
+        msg: "Step step1 starting.",
+        tag: "SEQUENCE",
+        stepIndex: 1,
+      },
+      now,
+    )
+
+    expect(line).toBe(
+      "[00:00:00.000] [SEQUENCE] stepIndex=1 Step step1 starting.",
+    )
+  })
+
+  test("serialises nested objects via JSON", () => {
+    const now = new Date()
+    now.setHours(0, 0, 0, 0)
+
+    const line = formatLogLine(
+      {
+        level: "error",
+        msg: "boom",
+        meta: { code: 42 },
+      },
+      now,
+    )
+
+    expect(line).toContain(`meta={"code":42}`)
+  })
+})

package/src/logging/lineSink.ts

@@ -0,0 +1,74 @@
+import type { LogRecord } from "./logger.js"
+
+const RESERVED_KEYS = new Set(["level", "msg"])
+
+const pad = (value: number, width: number): string =>
+  String(value).padStart(width, "0")
+
+const formatTimestamp = (date: Date): string =>
+  `[${pad(date.getHours(), 2)}:${pad(date.getMinutes(), 2)}:${pad(
+    date.getSeconds(),
+    2,
+  )}.${pad(date.getMilliseconds(), 3)}]`
+
+const formatValue = (value: unknown): string => {
+  if (value === null) {
+    return "null"
+  }
+  if (typeof value === "string") {
+    return /\s/.test(value) ? `"${value}"` : value
+  }
+  if (
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return String(value)
+  }
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+const renderField = ([key, value]: [
+  string,
+  unknown,
+]): string => `${key}=${formatValue(value)}`
+
+const isRenderableEntry =
+  (excludedKeys: ReadonlySet<string>) =>
+  ([key, value]: [string, unknown]): boolean =>
+    !excludedKeys.has(key) && value !== undefined
+
+const joinFields = (fields: readonly string[]): string =>
+  fields.length > 0 ? ` ${fields.join(" ")}` : ""
+
+const TAG_MODE_EXCLUDED_KEYS: ReadonlySet<string> = new Set(
+  [...RESERVED_KEYS, "tag"],
+)
+
+// When a record carries a `tag` field (set by the `logInfo/logError/logWarning`
+// bridge in api mode), render as `[ts] [TAG] msg` so the SSE feed stays byte-
+// identical to today's chalk-stripped console-patch output. Anything else
+// renders in the structured form `[ts] level field=value... msg`.
+export const formatLogLine = (
+  record: LogRecord,
+  now: Date = new Date(),
+): string => {
+  if (typeof record.tag === "string") {
+    const extraPart = joinFields(
+      Object.entries(record)
+        .filter(isRenderableEntry(TAG_MODE_EXCLUDED_KEYS))
+        .map(renderField),
+    )
+    return `${formatTimestamp(now)} [${record.tag}]${extraPart} ${record.msg}`
+  }
+
+  const fieldPart = joinFields(
+    Object.entries(record)
+      .filter(isRenderableEntry(RESERVED_KEYS))
+      .map(renderField),
+  )
+  return `${formatTimestamp(now)} ${record.level}${fieldPart} ${record.msg}`
+}