@nodaro/shared 1.4.1

package/src/__tests__/settled-with-limit.test.ts

@@ -0,0 +1,214 @@
+import { settledWithLimit } from "../settled-with-limit.js"
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+describe("settledWithLimit", () => {
+  // ── 1. Basic execution ──────────────────────────────────────────────
+  it("resolves all tasks in order with concurrency limit respected", async () => {
+    const tasks = [0, 1, 2, 3, 4].map(
+      (i) => () => delay(10).then(() => `result-${i}`),
+    )
+
+    const results = await settledWithLimit(tasks, 2)
+
+    expect(results).toHaveLength(5)
+    for (let i = 0; i < 5; i++) {
+      expect(results[i]).toEqual({ status: "fulfilled", value: `result-${i}` })
+    }
+  })
+
+  // ── 2. Empty tasks ─────────────────────────────────────────────────
+  it("returns an empty array when given no tasks", async () => {
+    const results = await settledWithLimit([], 5)
+    expect(results).toEqual([])
+  })
+
+  // ── 3. Single task ─────────────────────────────────────────────────
+  it("works with a single task and limit 1", async () => {
+    const results = await settledWithLimit(
+      [() => Promise.resolve(42)],
+      1,
+    )
+
+    expect(results).toHaveLength(1)
+    expect(results[0]).toEqual({ status: "fulfilled", value: 42 })
+  })
+
+  // ── 4. Limit greater than task count ───────────────────────────────
+  it("works when limit exceeds the number of tasks", async () => {
+    const tasks = [
+      () => Promise.resolve("a"),
+      () => Promise.resolve("b"),
+      () => Promise.resolve("c"),
+    ]
+
+    const results = await settledWithLimit(tasks, 10)
+
+    expect(results).toHaveLength(3)
+    expect(results[0]).toEqual({ status: "fulfilled", value: "a" })
+    expect(results[1]).toEqual({ status: "fulfilled", value: "b" })
+    expect(results[2]).toEqual({ status: "fulfilled", value: "c" })
+  })
+
+  // ── 5. Error handling ──────────────────────────────────────────────
+  it("returns rejected entries for tasks that throw, without aborting others", async () => {
+    const err = new Error("boom")
+    const tasks = [
+      () => Promise.resolve("ok"),
+      () => Promise.reject(err),
+      () => Promise.resolve("also ok"),
+    ]
+
+    const results = await settledWithLimit(tasks, 2)
+
+    expect(results).toHaveLength(3)
+    expect(results[0]).toEqual({ status: "fulfilled", value: "ok" })
+    expect(results[1]).toEqual({ status: "rejected", reason: err })
+    expect(results[2]).toEqual({ status: "fulfilled", value: "also ok" })
+  })
+
+  // ── 6. Concurrency enforcement ─────────────────────────────────────
+  it("never exceeds the concurrency limit", async () => {
+    const limit = 2
+    let running = 0
+    let maxRunning = 0
+
+    const tasks = Array.from({ length: 8 }, (_, i) => async () => {
+      running++
+      maxRunning = Math.max(maxRunning, running)
+      await delay(20)
+      running--
+      return i
+    })
+
+    const results = await settledWithLimit(tasks, limit)
+
+    expect(maxRunning).toBeLessThanOrEqual(limit)
+    expect(results).toHaveLength(8)
+    results.forEach((r) => expect(r.status).toBe("fulfilled"))
+  })
+
+  // ── 7. Cancellation skips remaining tasks ──────────────────────────
+  it("rejects un-started tasks with 'Execution cancelled' when cancelled mid-run", async () => {
+    const cancelledRef = { cancelled: false }
+    const started: number[] = []
+
+    // 6 tasks with limit 2.  After the first two complete (~30ms),
+    // we cancel so the remaining 4 should never start.
+    const tasks = Array.from({ length: 6 }, (_, i) => async () => {
+      started.push(i)
+      await delay(30)
+      return i
+    })
+
+    // Cancel after the first batch has started but before the rest begin
+    setTimeout(() => {
+      cancelledRef.cancelled = true
+    }, 15)
+
+    const results = await settledWithLimit(tasks, 2, cancelledRef)
+
+    expect(results).toHaveLength(6)
+
+    // First two tasks were already running and should complete
+    expect(results[0]).toEqual({ status: "fulfilled", value: 0 })
+    expect(results[1]).toEqual({ status: "fulfilled", value: 1 })
+
+    // Remaining tasks that never started should be rejected
+    const cancelledResults = results.filter(
+      (r) => r.status === "rejected" && (r.reason as Error).message === "Execution cancelled",
+    )
+    expect(cancelledResults.length).toBeGreaterThan(0)
+
+    // No more than limit tasks should have actually started
+    // (the first 2 plus possibly 1-2 more depending on timing)
+    expect(started.length).toBeLessThan(6)
+  })
+
+  // ── 8. Cancellation does not stop already-running tasks ────────────
+  it("lets already-running tasks finish even after cancellation", async () => {
+    const cancelledRef = { cancelled: false }
+    const completed: number[] = []
+
+    const tasks = [
+      // Task 0: slow, already running before cancel
+      async () => {
+        await delay(50)
+        completed.push(0)
+        return "done-0"
+      },
+      // Task 1: slow, already running before cancel
+      async () => {
+        await delay(50)
+        completed.push(1)
+        return "done-1"
+      },
+      // Task 2: should never start
+      async () => {
+        completed.push(2)
+        return "done-2"
+      },
+    ]
+
+    // Cancel while the first two are still in-flight
+    setTimeout(() => {
+      cancelledRef.cancelled = true
+    }, 10)
+
+    const results = await settledWithLimit(tasks, 2, cancelledRef)
+
+    // Both in-flight tasks should have completed
+    expect(completed).toContain(0)
+    expect(completed).toContain(1)
+    expect(results[0]).toEqual({ status: "fulfilled", value: "done-0" })
+    expect(results[1]).toEqual({ status: "fulfilled", value: "done-1" })
+
+    // Third task should be cancelled, not started
+    expect(completed).not.toContain(2)
+    expect(results[2].status).toBe("rejected")
+    expect((results[2] as PromiseRejectedResult).reason.message).toBe(
+      "Execution cancelled",
+    )
+  })
+
+  // ── 9. Results array indices match task indices ────────────────────
+  it("preserves the index mapping between tasks and results", async () => {
+    const tasks = [10, 20, 30, 40, 50].map(
+      (v) => () => delay(Math.random() * 20).then(() => v),
+    )
+
+    const results = await settledWithLimit(tasks, 3)
+
+    expect(results).toHaveLength(5)
+    const values = results.map((r) => {
+      expect(r.status).toBe("fulfilled")
+      return (r as PromiseFulfilledResult<number>).value
+    })
+    expect(values).toEqual([10, 20, 30, 40, 50])
+  })
+
+  // ── 10. Mix of fulfilled and rejected ──────────────────────────────
+  it("handles a mix of resolved and rejected tasks at specific indices", async () => {
+    const err1 = new Error("fail-1")
+    const err3 = new Error("fail-3")
+
+    const tasks = [
+      () => Promise.resolve("ok-0"),
+      () => Promise.reject(err1),
+      () => Promise.resolve("ok-2"),
+      () => Promise.reject(err3),
+      () => Promise.resolve("ok-4"),
+    ]
+
+    const results = await settledWithLimit(tasks, 2)
+
+    expect(results).toHaveLength(5)
+    expect(results[0]).toEqual({ status: "fulfilled", value: "ok-0" })
+    expect(results[1]).toEqual({ status: "rejected", reason: err1 })
+    expect(results[2]).toEqual({ status: "fulfilled", value: "ok-2" })
+    expect(results[3]).toEqual({ status: "rejected", reason: err3 })
+    expect(results[4]).toEqual({ status: "fulfilled", value: "ok-4" })
+  })
+})

package/src/__tests__/social-media-specs.test.ts

@@ -0,0 +1,129 @@
+import {
+  PLATFORM_SPECS,
+  CONTENT_TYPES_BY_PLATFORM,
+  PLATFORM_LABELS,
+} from "../social-media-specs.js"
+import type { SocialMediaPlatform } from "../social-media-specs.js"
+
+const ALL_PLATFORMS: SocialMediaPlatform[] = [
+  "instagram",
+  "tiktok",
+  "x",
+  "youtube",
+  "facebook",
+  "linkedin",
+  "telegram",
+]
+
+// ---------------------------------------------------------------------------
+// PLATFORM_SPECS
+// ---------------------------------------------------------------------------
+describe("PLATFORM_SPECS", () => {
+  const entries = Object.entries(PLATFORM_SPECS)
+
+  it("contains exactly 14 entries", () => {
+    expect(entries).toHaveLength(14)
+  })
+
+  it("all entries have valid dimensions (width > 0 and height > 0)", () => {
+    for (const [key, spec] of entries) {
+      expect(spec.width, `${key} width`).toBeGreaterThan(0)
+      expect(spec.height, `${key} height`).toBeGreaterThan(0)
+    }
+  })
+
+  it("all keys match 'platform:contentType' format", () => {
+    for (const key of Object.keys(PLATFORM_SPECS)) {
+      expect(key).toMatch(/^[a-z]+:[a-z0-9-]+$/)
+    }
+  })
+
+  it("every spec's platform matches its key prefix", () => {
+    for (const [key, spec] of entries) {
+      const prefix = key.split(":")[0]
+      expect(spec.platform).toBe(prefix)
+    }
+  })
+
+  it("image specs (isVideo=false) have maxDurationSeconds=null", () => {
+    for (const [key, spec] of entries) {
+      if (!spec.isVideo) {
+        expect(spec.maxDurationSeconds, `${key}`).toBeNull()
+      }
+    }
+  })
+
+  it("video specs (isVideo=true) have maxDurationSeconds > 0", () => {
+    for (const [key, spec] of entries) {
+      if (spec.isVideo) {
+        expect(spec.maxDurationSeconds, `${key}`).toBeGreaterThan(0)
+      }
+    }
+  })
+
+  it("all textLimits are positive", () => {
+    for (const [key, spec] of entries) {
+      expect(spec.textLimit, `${key}`).toBeGreaterThan(0)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// CONTENT_TYPES_BY_PLATFORM
+// ---------------------------------------------------------------------------
+describe("CONTENT_TYPES_BY_PLATFORM", () => {
+  it("keys cover all 7 platforms", () => {
+    for (const platform of ALL_PLATFORMS) {
+      expect(CONTENT_TYPES_BY_PLATFORM).toHaveProperty(platform)
+    }
+  })
+
+  it("every entry's key (except telegram) exists in PLATFORM_SPECS", () => {
+    for (const [platform, contentTypes] of Object.entries(CONTENT_TYPES_BY_PLATFORM)) {
+      // Telegram has a "telegram:message" entry that is not in PLATFORM_SPECS
+      if (platform === "telegram") continue
+      for (const ct of contentTypes) {
+        expect(
+          PLATFORM_SPECS,
+          `${ct.key} referenced by ${platform} not found in PLATFORM_SPECS`,
+        ).toHaveProperty(ct.key)
+      }
+    }
+  })
+
+  it("each platform has at least one content type", () => {
+    for (const platform of ALL_PLATFORMS) {
+      expect(CONTENT_TYPES_BY_PLATFORM[platform].length).toBeGreaterThanOrEqual(1)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// PLATFORM_LABELS
+// ---------------------------------------------------------------------------
+describe("PLATFORM_LABELS", () => {
+  it("covers all 7 platforms", () => {
+    for (const platform of ALL_PLATFORMS) {
+      expect(PLATFORM_LABELS).toHaveProperty(platform)
+      expect(PLATFORM_LABELS[platform]).toBeTruthy()
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Spot checks
+// ---------------------------------------------------------------------------
+describe("spot checks", () => {
+  it("instagram:story-reel is 1080x1920", () => {
+    const spec = PLATFORM_SPECS["instagram:story-reel"]
+    expect(spec).toBeDefined()
+    expect(spec.width).toBe(1080)
+    expect(spec.height).toBe(1920)
+  })
+
+  it("x:image-landscape has textLimit=280", () => {
+    const spec = PLATFORM_SPECS["x:image-landscape"]
+    expect(spec).toBeDefined()
+    expect(spec.textLimit).toBe(280)
+  })
+})

package/src/__tests__/sub-workflow-validation.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest"
+import { validateSubWorkflowRoutes } from "../sub-workflow-validation.js"
+
+const port = (id: string, mediaType: "any" | "text" | "image" | "video" | "audio" = "any") =>
+  ({ id, name: id, mediaType })
+
+describe("validateSubWorkflowRoutes", () => {
+  it("returns ok when there are no boundary nodes", () => {
+    expect(validateSubWorkflowRoutes([])).toEqual({ ok: true })
+  })
+
+  it("returns ok when every input has a matching output with at least one outputPort", () => {
+    const nodes = [
+      { id: "i1", type: "sub-workflow-input",  data: { routeId: "r1", ports: [port("a")] } },
+      { id: "o1", type: "sub-workflow-output", data: { routeId: "r1", ports: [port("b")] } },
+    ]
+    expect(validateSubWorkflowRoutes(nodes as any)).toEqual({ ok: true })
+  })
+
+  it("fails when an input has no matching output for its routeId", () => {
+    const nodes = [
+      { id: "i1", type: "sub-workflow-input",  data: { routeId: "r1", ports: [port("a")] } },
+    ]
+    const result = validateSubWorkflowRoutes(nodes as any)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors[0]).toMatchObject({
+        code: "missing_output_for_route",
+        routeId: "r1",
+      })
+    }
+  })
+
+  it("fails when an output has no matching input for its routeId", () => {
+    const nodes = [
+      { id: "o1", type: "sub-workflow-output", data: { routeId: "r1", ports: [port("b")] } },
+    ]
+    const result = validateSubWorkflowRoutes(nodes as any)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors[0].code).toBe("missing_input_for_route")
+    }
+  })
+
+  it("fails when an output exists but has zero outputPorts", () => {
+    const nodes = [
+      { id: "i1", type: "sub-workflow-input",  data: { routeId: "r1", ports: [port("a")] } },
+      { id: "o1", type: "sub-workflow-output", data: { routeId: "r1", ports: [] } },
+    ]
+    const result = validateSubWorkflowRoutes(nodes as any)
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.errors[0].code).toBe("route_has_no_output_ports")
+  })
+
+  it("fails when two input nodes share the same routeId", () => {
+    const nodes = [
+      { id: "i1", type: "sub-workflow-input",  data: { routeId: "r1", ports: [port("a")] } },
+      { id: "i2", type: "sub-workflow-input",  data: { routeId: "r1", ports: [port("c")] } },
+      { id: "o1", type: "sub-workflow-output", data: { routeId: "r1", ports: [port("b")] } },
+    ]
+    const result = validateSubWorkflowRoutes(nodes as any)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors.some((e) => e.code === "duplicate_route_id")).toBe(true)
+    }
+  })
+
+  it("fails when two output nodes share the same routeId", () => {
+    const nodes = [
+      { id: "i1", type: "sub-workflow-input",  data: { routeId: "r1", ports: [port("a")] } },
+      { id: "o1", type: "sub-workflow-output", data: { routeId: "r1", ports: [port("b")] } },
+      { id: "o2", type: "sub-workflow-output", data: { routeId: "r1", ports: [port("c")] } },
+    ]
+    const result = validateSubWorkflowRoutes(nodes as any)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors.some((e) => e.code === "duplicate_route_id")).toBe(true)
+    }
+  })
+
+  it("ignores boundary nodes without a routeId (treats as not-yet-configured)", () => {
+    const nodes = [
+      { id: "i1", type: "sub-workflow-input",  data: { ports: [port("a")] } },
+      { id: "o1", type: "sub-workflow-output", data: { ports: [port("b")] } },
+    ]
+    expect(validateSubWorkflowRoutes(nodes as any)).toEqual({ ok: true })
+  })
+})

package/src/__tests__/switchx-pricing.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest"
+import { pickSwitchXFrameTier, resolveSwitchXCreditId, VIDEO_PRODUCER_TYPES } from "../index.js"
+
+// switchXHoldCredits (the $-derived credits formula) moved to
+// backend/src/lib/pricing/switchx-cost.ts (S5) — its test lives in
+// backend/src/lib/pricing/__tests__/switchx-cost.test.ts. This file covers
+// only the NON-monetary tier-bucketing + credit-id-construction logic that
+// stays in the published package.
+
+describe("switchx pricing", () => {
+  it("snaps frames up to the next 30-frame block tier; undefined/over → 240", () => {
+    expect(pickSwitchXFrameTier(1)).toBe(30)
+    expect(pickSwitchXFrameTier(30)).toBe(30)
+    expect(pickSwitchXFrameTier(45)).toBe(60)
+    expect(pickSwitchXFrameTier(96)).toBe(120)
+    expect(pickSwitchXFrameTier(150)).toBe(150)
+    expect(pickSwitchXFrameTier(999)).toBe(240)
+    expect(pickSwitchXFrameTier(undefined)).toBe(240)
+  })
+  it("composes the credit id from frames + resolution", () => {
+    expect(resolveSwitchXCreditId({ __probedFrameCount: 90, maxResolution: 1080 })).toBe("beeble-switchx:90f:1080p")
+    expect(resolveSwitchXCreditId({ __probedFrameCount: 200, maxResolution: 720 })).toBe("beeble-switchx:210f:720p")
+    expect(resolveSwitchXCreditId({})).toBe("beeble-switchx:240f:1080p") // bare/worst-case
+  })
+  it("registers switchx as a video producer", () => {
+    expect(VIDEO_PRODUCER_TYPES.has("switchx")).toBe(true)
+  })
+})

package/src/__tests__/to-connected-references.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest"
+
+import { characterMentionSlug } from "../character-mention-slug.js"
+import { locationMentionSlug } from "../location-mention-slug.js"
+import {
+  toConnectedReference,
+  toConnectedReferences,
+  type EntityReferenceInput,
+} from "../to-connected-references.js"
+
+/**
+ * `toConnectedReference` is the contract seam between an app's binding UX and
+ * Nodaro's reference resolver: a generic `{ id, kind, name, url, variant }`
+ * binding must map to the platform `ConnectedReference` with the slug DERIVED
+ * from `name`. These assertions are pinned to the consuming app's previous
+ * hand-rolled output (studio `chipAttrsToConnectedReference`) so adopting the
+ * shared helper can't change the wire shape, and any `@nodaro/shared` schema
+ * drift (renamed field, changed `wired-*` handling, slug-helper change) fails
+ * loudly here.
+ */
+describe("toConnectedReference", () => {
+  it("maps a character binding to a wired-character reference with a derived slug", () => {
+    const input: EntityReferenceInput = {
+      id: "char-1",
+      kind: "character",
+      name: "Kira",
+      url: "https://r2.example/kira.png",
+    }
+    expect(toConnectedReference(input)).toEqual({
+      id: "char-1",
+      defaultName: "Kira",
+      source: "wired-character",
+      url: "https://r2.example/kira.png",
+      characterSlug: characterMentionSlug("Kira"),
+      variantSlug: undefined,
+      characterCanonicalDescription: null,
+      variantDescription: null,
+      variantDisplayName: "canonical",
+    })
+  })
+
+  it("maps a location binding to a wired-location reference with a derived slug", () => {
+    const ref = toConnectedReference({
+      id: "loc-1",
+      kind: "location",
+      name: "Old Library",
+      url: "https://r2.example/lib.png",
+    })
+    expect(ref.source).toBe("wired-location")
+    expect(ref.locationSlug).toBe(locationMentionSlug("Old Library"))
+    expect(ref.locationSlug).toBe("old-library")
+    expect(ref.url).toBe("https://r2.example/lib.png")
+    expect(ref.locationVariantDisplayName).toBe("canonical")
+  })
+
+  it("rides a present variant onto the character variant slug + display name", () => {
+    const ref = toConnectedReference({
+      id: "char-1",
+      kind: "character",
+      name: "Kira",
+      url: "https://r2.example/kira.png",
+      variant: "smile",
+    })
+    expect(ref.variantSlug).toBe("smile")
+    expect(ref.variantDisplayName).toBe("smile")
+  })
+
+  it("rides a present variant onto the location variant slug + display name", () => {
+    const ref = toConnectedReference({
+      id: "loc-1",
+      kind: "location",
+      name: "Old Library",
+      url: "https://r2.example/lib.png",
+      variant: "rain",
+    })
+    expect(ref.locationVariantSlug).toBe("rain")
+    expect(ref.locationVariantDisplayName).toBe("rain")
+  })
+
+  it("maps a creature binding to a wired-creature reference (auto-attach, no slug machinery)", () => {
+    expect(
+      toConnectedReference({
+        id: "cre-1",
+        kind: "creature",
+        name: "Ember",
+        url: "https://r2.example/ember.png",
+      }),
+    ).toEqual({
+      id: "cre-1",
+      defaultName: "Ember",
+      source: "wired-creature",
+      url: "https://r2.example/ember.png",
+    })
+  })
+
+  it("folds a creature description into the reference (drives the directive subject)", () => {
+    const ref = toConnectedReference({
+      id: "cre-1",
+      kind: "creature",
+      name: "Ember",
+      url: "https://r2.example/ember.png",
+      description: "a small red dragon with golden eyes",
+    })
+    expect(ref.source).toBe("wired-creature")
+    expect(ref.description).toBe("a small red dragon with golden eyes")
+    // Empty/missing description must NOT add the key (exact wire-shape pin).
+    expect(
+      "description" in toConnectedReference({ id: "cre-2", kind: "creature", name: "Rex" }),
+    ).toBe(false)
+  })
+
+  it("falls back to a placeholder-safe empty url when the entity has no thumbnail", () => {
+    expect(
+      toConnectedReference({
+        id: "char-2",
+        kind: "character",
+        name: "Nyx",
+        url: null,
+      }).url,
+    ).toBe("")
+    expect(
+      toConnectedReference({ id: "char-3", kind: "character", name: "Vex" }).url,
+    ).toBe("")
+  })
+
+  it("does not mutate its input", () => {
+    const input: EntityReferenceInput = {
+      id: "char-1",
+      kind: "character",
+      name: "Kira",
+      url: "https://r2.example/kira.png",
+      variant: "smile",
+    }
+    const frozen = Object.freeze({ ...input })
+    expect(() => toConnectedReference(frozen)).not.toThrow()
+    expect(frozen).toEqual(input)
+  })
+})
+
+describe("toConnectedReferences", () => {
+  it("batch maps in order, preserving indices", () => {
+    const inputs: EntityReferenceInput[] = [
+      { id: "char-1", kind: "character", name: "Kira", url: "https://r2.example/kira.png" },
+      { id: "loc-1", kind: "location", name: "Old Library", url: "https://r2.example/lib.png" },
+    ]
+    const refs = toConnectedReferences(inputs)
+    expect(refs).toHaveLength(2)
+    expect(refs[0]).toEqual(toConnectedReference(inputs[0]))
+    expect(refs[0].source).toBe("wired-character")
+    expect(refs[1]).toEqual(toConnectedReference(inputs[1]))
+    expect(refs[1].source).toBe("wired-location")
+  })
+})