@mux-magic/tools 1.0.0 → 1.1.0

package/src/logging/logger.test.ts

@@ -0,0 +1,154 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+  vi,
+} from "vitest"
+
+import { withLoggingContext } from "./context.js"
+import {
+  __resetLogSinksForTests,
+  getLogger,
+  type LogRecord,
+  registerLogSink,
+} from "./logger.js"
+
+describe(getLogger.name, () => {
+  let records: readonly LogRecord[]
+
+  beforeEach(() => {
+    __resetLogSinksForTests()
+    records = []
+    registerLogSink((record) => {
+      records = records.concat(record)
+    })
+  })
+
+  afterEach(() => {
+    __resetLogSinksForTests()
+  })
+
+  test("emits one record per .info call", () => {
+    getLogger().info("hello")
+
+    expect(records).toHaveLength(1)
+    expect(records[0]).toMatchObject({
+      level: "info",
+      msg: "hello",
+    })
+  })
+
+  test("emits one record per .debug / .warn / .error call", () => {
+    const logger = getLogger()
+
+    logger.debug("d")
+    logger.warn("w")
+    logger.error("e")
+
+    expect(records.map((record) => record.level)).toEqual([
+      "debug",
+      "warn",
+      "error",
+    ])
+  })
+
+  test("attaches caller-provided extra fields to the record", () => {
+    getLogger().info("step done", {
+      stepIndex: 2,
+      detail: "copy",
+    })
+
+    expect(records[0]).toMatchObject({
+      level: "info",
+      msg: "step done",
+      stepIndex: 2,
+      detail: "copy",
+    })
+  })
+
+  test("reads jobId / stepIndex / fileId from AsyncLocalStorage context", () => {
+    withLoggingContext(
+      { jobId: "j1", stepIndex: 4, fileId: "f.mkv" },
+      () => {
+        getLogger().info("hi")
+      },
+    )
+
+    expect(records[0]).toMatchObject({
+      jobId: "j1",
+      stepIndex: 4,
+      fileId: "f.mkv",
+      level: "info",
+      msg: "hi",
+    })
+  })
+
+  test("explicit fields override context-derived fields", () => {
+    withLoggingContext({ jobId: "from-ctx" }, () => {
+      getLogger().info("override", { jobId: "explicit" })
+    })
+
+    expect(records[0]).toMatchObject({
+      jobId: "explicit",
+      msg: "override",
+    })
+  })
+
+  test("child(bindings) merges bindings into every emitted record", () => {
+    const childLogger = getLogger().child({
+      component: "renamer",
+    })
+
+    childLogger.info("named")
+    childLogger.warn("careful")
+
+    expect(records[0]).toMatchObject({
+      component: "renamer",
+      msg: "named",
+    })
+    expect(records[1]).toMatchObject({
+      component: "renamer",
+      msg: "careful",
+    })
+  })
+
+  test("child bindings override context, explicit extras override child", () => {
+    withLoggingContext({ stepIndex: 1 }, () => {
+      const child = getLogger().child({ stepIndex: 2 })
+
+      child.info("first")
+      child.info("second", { stepIndex: 3 })
+    })
+
+    expect(records[0]?.stepIndex).toBe(2)
+    expect(records[1]?.stepIndex).toBe(3)
+  })
+
+  test("registerLogSink returns an unsubscribe handle", () => {
+    const sink = vi.fn()
+    const unsubscribe = registerLogSink(sink)
+
+    getLogger().info("first")
+    unsubscribe()
+    getLogger().info("second")
+
+    expect(sink).toHaveBeenCalledTimes(1)
+    expect(sink).toHaveBeenCalledWith(
+      expect.objectContaining({ msg: "first" }),
+    )
+  })
+
+  test("multiple sinks each receive every record", () => {
+    const sinkA = vi.fn()
+    const sinkB = vi.fn()
+    registerLogSink(sinkA)
+    registerLogSink(sinkB)
+
+    getLogger().info("broadcast")
+
+    expect(sinkA).toHaveBeenCalledTimes(1)
+    expect(sinkB).toHaveBeenCalledTimes(1)
+  })
+})

package/src/logging/logger.ts

@@ -0,0 +1,96 @@
+import { getLoggingContext } from "./context.js"
+import { startSpan } from "./startSpan.js"
+
+export type LogLevel = "debug" | "info" | "warn" | "error"
+
+export type LogRecord = {
+  level: LogLevel
+  msg: string
+  jobId?: string
+  stepIndex?: number
+  fileId?: string
+  traceId?: string
+  spanId?: string
+  [extraKey: string]: unknown
+}
+
+export type LogSink = (record: LogRecord) => void
+
+export type Logger = {
+  debug: (
+    msg: string,
+    extra?: Record<string, unknown>,
+  ) => void
+  info: (
+    msg: string,
+    extra?: Record<string, unknown>,
+  ) => void
+  warn: (
+    msg: string,
+    extra?: Record<string, unknown>,
+  ) => void
+  error: (
+    msg: string,
+    extra?: Record<string, unknown>,
+  ) => void
+  child: (bindings: Record<string, unknown>) => Logger
+  startSpan: <T>(
+    name: string,
+    fn: () => Promise<T> | T,
+  ) => Promise<T>
+}
+
+const sinks: Set<LogSink> = new Set()
+
+export const registerLogSink = (
+  sink: LogSink,
+): (() => void) => {
+  sinks.add(sink)
+  return () => {
+    sinks.delete(sink)
+  }
+}
+
+export const __resetLogSinksForTests = (): void => {
+  sinks.clear()
+}
+
+const emit = (record: LogRecord): void => {
+  for (const sink of sinks) {
+    sink(record)
+  }
+}
+
+const buildRecord = (
+  bindings: Record<string, unknown>,
+  level: LogLevel,
+  msg: string,
+  extra: Record<string, unknown> | undefined,
+): LogRecord => ({
+  ...getLoggingContext(),
+  ...bindings,
+  ...extra,
+  level,
+  msg,
+})
+
+const createLogger = (
+  bindings: Record<string, unknown>,
+): Logger => {
+  const logger: Logger = {
+    debug: (msg, extra) =>
+      emit(buildRecord(bindings, "debug", msg, extra)),
+    info: (msg, extra) =>
+      emit(buildRecord(bindings, "info", msg, extra)),
+    warn: (msg, extra) =>
+      emit(buildRecord(bindings, "warn", msg, extra)),
+    error: (msg, extra) =>
+      emit(buildRecord(bindings, "error", msg, extra)),
+    child: (childBindings) =>
+      createLogger({ ...bindings, ...childBindings }),
+    startSpan: (name, fn) => startSpan(logger, name, fn),
+  }
+  return logger
+}
+
+export const getLogger = (): Logger => createLogger({})

package/src/logging/mode.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, test } from "vitest"
+
+import {
+  __resetLoggingModeForTests,
+  getLoggingMode,
+  setLoggingMode,
+} from "./mode.js"
+
+afterEach(() => {
+  __resetLoggingModeForTests()
+})
+
+describe(getLoggingMode.name, () => {
+  test('defaults to "cli"', () => {
+    expect(getLoggingMode()).toBe("cli")
+  })
+
+  test('returns "api" after setLoggingMode("api")', () => {
+    setLoggingMode("api")
+
+    expect(getLoggingMode()).toBe("api")
+  })
+
+  test('returns "cli-debug" after setLoggingMode("cli-debug")', () => {
+    setLoggingMode("cli-debug")
+
+    expect(getLoggingMode()).toBe("cli-debug")
+  })
+
+  test("reset helper returns to the default", () => {
+    setLoggingMode("api")
+    __resetLoggingModeForTests()
+
+    expect(getLoggingMode()).toBe("cli")
+  })
+})

package/src/logging/mode.ts

@@ -0,0 +1,29 @@
+// Logging mode controls how the user-friendly helpers
+// (`logInfo` / `logError` / `logWarning` in ./logMessage.ts) deliver their
+// output. The structured logger (`getLogger`) is always available regardless
+// of mode — the mode only governs the legacy helpers' delivery path.
+//
+//   "cli"        — chalk-coloured `[TAG] message` console output. No
+//                  structured emission. Default; preserves historical
+//                  behaviour for any consumer that does not opt in.
+//   "api"        — emit a structured `LogRecord` (with a `tag` field) to
+//                  the registered sinks. No chalk console output. Used by
+//                  the API server, where the log surface is the web UI's
+//                  job-log SSE feed, not a human terminal.
+//   "cli-debug"  — both. Lets a CLI run capture structured records (for
+//                  debug logging to a file, for example) without losing
+//                  the user-facing console output.
+
+export type LoggingMode = "cli" | "api" | "cli-debug"
+
+let currentMode: LoggingMode = "cli"
+
+export const setLoggingMode = (mode: LoggingMode): void => {
+  currentMode = mode
+}
+
+export const getLoggingMode = (): LoggingMode => currentMode
+
+export const __resetLoggingModeForTests = (): void => {
+  currentMode = "cli"
+}

package/src/logging/startSpan.test.ts

@@ -0,0 +1,150 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "vitest"
+
+import { getLoggingContext } from "./context.js"
+import {
+  __resetLogSinksForTests,
+  getLogger,
+  type LogRecord,
+  registerLogSink,
+} from "./logger.js"
+
+describe("startSpan", () => {
+  let records: readonly LogRecord[]
+
+  beforeEach(() => {
+    __resetLogSinksForTests()
+    records = []
+    registerLogSink((record) => {
+      records = records.concat(record)
+    })
+  })
+
+  afterEach(() => {
+    __resetLogSinksForTests()
+  })
+
+  test("returns the value the wrapped fn returned", async () => {
+    const result = await getLogger().startSpan(
+      "work",
+      () => 7,
+    )
+
+    expect(result).toBe(7)
+  })
+
+  test("awaits async fn results", async () => {
+    const result = await getLogger().startSpan(
+      "work",
+      async () => {
+        await Promise.resolve()
+        return "done"
+      },
+    )
+
+    expect(result).toBe("done")
+  })
+
+  test("emits an enter and an exit debug record sharing traceId/spanId", async () => {
+    await getLogger().startSpan("work", () => undefined)
+
+    const enter = records.find((record) =>
+      record.msg.startsWith("span enter:"),
+    )
+    const exit = records.find((record) =>
+      record.msg.startsWith("span exit:"),
+    )
+
+    expect(enter).toBeDefined()
+    expect(exit).toBeDefined()
+    expect(enter?.traceId).toBeTypeOf("string")
+    expect(enter?.spanId).toBeTypeOf("string")
+    expect(exit?.traceId).toBe(enter?.traceId)
+    expect(exit?.spanId).toBe(enter?.spanId)
+    expect(exit?.spanName).toBe("work")
+  })
+
+  test("exit record carries elapsedMs >= 0", async () => {
+    await getLogger().startSpan("work", () => undefined)
+
+    const exit = records.find((record) =>
+      record.msg.startsWith("span exit:"),
+    )
+
+    expect(typeof exit?.elapsedMs).toBe("number")
+    expect(
+      exit?.elapsedMs as number,
+    ).toBeGreaterThanOrEqual(0)
+  })
+
+  test("propagates traceId/spanId into the AsyncLocalStorage context", async () => {
+    let innerContext = {} as ReturnType<
+      typeof getLoggingContext
+    >
+
+    await getLogger().startSpan("work", () => {
+      innerContext = getLoggingContext()
+    })
+
+    expect(innerContext.traceId).toBeTypeOf("string")
+    expect(innerContext.spanId).toBeTypeOf("string")
+  })
+
+  test("logger.info inside fn carries the span's traceId/spanId", async () => {
+    await getLogger().startSpan("work", () => {
+      getLogger().info("inner")
+    })
+
+    const inner = records.find(
+      (record) => record.msg === "inner",
+    )
+
+    expect(inner?.traceId).toBeTypeOf("string")
+    expect(inner?.spanId).toBeTypeOf("string")
+  })
+
+  test("nested span inherits the outer traceId but gets a fresh spanId", async () => {
+    let outerTraceId = ""
+    let outerSpanId = ""
+    let innerTraceId = ""
+    let innerSpanId = ""
+
+    await getLogger().startSpan("outer", async () => {
+      const outerCtx = getLoggingContext()
+      outerTraceId = outerCtx.traceId ?? ""
+      outerSpanId = outerCtx.spanId ?? ""
+
+      await getLogger().startSpan("inner", () => {
+        const innerCtx = getLoggingContext()
+        innerTraceId = innerCtx.traceId ?? ""
+        innerSpanId = innerCtx.spanId ?? ""
+      })
+    })
+
+    expect(outerTraceId).not.toBe("")
+    expect(innerTraceId).toBe(outerTraceId)
+    expect(innerSpanId).not.toBe("")
+    expect(innerSpanId).not.toBe(outerSpanId)
+  })
+
+  test("emits an error record with elapsedMs/errorName and re-throws on throw", async () => {
+    await expect(
+      getLogger().startSpan("work", () => {
+        throw new TypeError("nope")
+      }),
+    ).rejects.toBeInstanceOf(TypeError)
+
+    const errRecord = records.find((record) =>
+      record.msg.startsWith("span error:"),
+    )
+
+    expect(errRecord?.level).toBe("error")
+    expect(errRecord?.errorName).toBe("TypeError")
+    expect(typeof errRecord?.elapsedMs).toBe("number")
+  })
+})

package/src/logging/startSpan.ts

@@ -0,0 +1,51 @@
+import { randomUUID } from "node:crypto"
+import { performance } from "node:perf_hooks"
+
+import {
+  getLoggingContext,
+  loggingContext,
+} from "./context.js"
+import type { Logger } from "./logger.js"
+
+export const startSpan = async <T>(
+  logger: Logger,
+  name: string,
+  fn: () => Promise<T> | T,
+): Promise<T> => {
+  const parentContext = getLoggingContext()
+  const traceId = parentContext.traceId ?? randomUUID()
+  const spanId = randomUUID()
+  const startedAt = performance.now()
+
+  logger.debug(`span enter: ${name}`, {
+    traceId,
+    spanId,
+    spanName: name,
+  })
+
+  return loggingContext.run(
+    { ...parentContext, traceId, spanId },
+    async () => {
+      try {
+        const result = await fn()
+        logger.debug(`span exit: ${name}`, {
+          traceId,
+          spanId,
+          spanName: name,
+          elapsedMs: performance.now() - startedAt,
+        })
+        return result
+      } catch (error) {
+        logger.error(`span error: ${name}`, {
+          traceId,
+          spanId,
+          spanName: name,
+          elapsedMs: performance.now() - startedAt,
+          errorName:
+            error instanceof Error ? error.name : "unknown",
+        })
+        throw error
+      }
+    },
+  )
+}

package/src/sourcePath.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "vitest"
+
+import {
+  SOURCE_PATH_FIELD_NAME,
+  SOURCE_PATH_LABEL,
+} from "./sourcePath.js"
+
+describe("sourcePath constants", () => {
+  test("SOURCE_PATH_FIELD_NAME is the canonical internal field name", () => {
+    expect(SOURCE_PATH_FIELD_NAME).toBe("sourcePath")
+  })
+
+  test("SOURCE_PATH_LABEL is the canonical user-facing label", () => {
+    expect(SOURCE_PATH_LABEL).toBe("Source Path")
+  })
+})

package/src/sourcePath.ts

@@ -0,0 +1,17 @@
+// Canonical "Source Path" concept.
+//
+// Every command that takes a primary input directory exposes its value as a
+// field named `sourcePath` (via this constant) and renders it under the label
+// "Source Path". Centralising the spelling here keeps server schemas, the
+// CLI's option name, the web field-builder, and the YAML codec's legacy-rename
+// map all in agreement — a single rename here would still ripple if any
+// caller hardcoded the string.
+
+export const SOURCE_PATH_FIELD_NAME = "sourcePath" as const
+export const SOURCE_PATH_LABEL = "Source Path" as const
+
+// Canonical: an absolute filesystem path. Today the validation layer is
+// nominal — every string is a SourcePath. The alias documents intent at
+// callsites and gives a single place to tighten later (e.g. brand the type)
+// without a codebase-wide replace.
+export type SourcePath = string

package/src/taskScheduler.injection.test.ts

@@ -0,0 +1,72 @@
+import { defer, of } from "rxjs"
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "vitest"
+
+import {
+  __resetTaskSchedulerForTests,
+  initTaskScheduler,
+  runTask,
+} from "./taskScheduler.js"
+
+// These tests pin worker 21's design contract:
+//   1. The scheduler now lives in @mux-magic/tools (this file's location
+//      proves the file moved).
+//   2. The scheduler no longer hard-imports server-only modules; the
+//      server-specific job-id provider is injected at init.
+
+beforeEach(() => {
+  __resetTaskSchedulerForTests()
+})
+
+afterEach(() => {
+  __resetTaskSchedulerForTests()
+})
+
+describe("initTaskScheduler — injected getActiveJobId", () => {
+  test("uses the injected provider when explicitJobId is omitted", () => {
+    let observedJobId: string | null = "unset"
+    let injectedReadCount = 0
+
+    initTaskScheduler(1, {
+      getActiveJobId: () => {
+        injectedReadCount += 1
+        return "injected-job"
+      },
+    })
+
+    runTask(
+      defer(() => {
+        observedJobId = "did-run"
+        return of(undefined)
+      }),
+    ).subscribe()
+
+    // The injected provider must have been consulted at subscribe time
+    // (the scheduler reads jobId via the injected fn, not via a
+    // server-only import).
+    expect(injectedReadCount).toBeGreaterThan(0)
+    expect(observedJobId).toBe("did-run")
+  })
+
+  test("defaults to a null provider when no injection is supplied", () => {
+    initTaskScheduler(1)
+
+    let hasRun = false
+
+    runTask(
+      defer(() => {
+        hasRun = true
+        return of(undefined)
+      }),
+    ).subscribe()
+
+    // CLI passes no provider; scheduler must still function and treat
+    // the active job id as null (no per-job claim consulted).
+    expect(hasRun).toBe(true)
+  })
+})