@erclx/canon 5.77.0 → 5.79.0

package/src/take/screencast.ts

@@ -1,8 +1,8 @@
-import { mkdtempSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import { chromium } from 'playwright-core'
-import { lastFrame, probeFrames, transcode } from '@/take/encode'
+import { lastFrame, openFrameEncoder, probeFrames } from '@/take/encode'
+import { frameStamp, slotFrames } from '@/take/frame-clock'
 import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
 import {
   type PointerInput,
@@ -11,7 +11,7 @@ import {
   performSteps,
 } from '@/take/perform'
 import type { Beat } from '@/take/plan'
-import { HOLD_MS } from '@/take/stepper'
+import { HOLD_MS, withinCap } from '@/take/stepper'
 
 /**
  * Films a beat in real time through Playwright's screencast, for a page frame
@@ -27,9 +27,21 @@ const SETTLE_MS = 2500
 /** How long a refusal waits on the screenshot it shows. */
 const STILL_CAP_MS = 2000
 
+/**
+ * How long a move waits on the page's next animation frame before it goes
+ * anyway, since a page whose frames stall is the stepper's case and this route
+ * must still film.
+ */
+const ALIGN_CAP_MS = 100
+
+/** How long the calibration waits on the page to paint its move. */
+const CALIBRATE_CAP_MS = 500
+
 export interface ScreencastTake {
   readonly frames: number
   readonly events: readonly LogEvent[]
+  /** What `events` were shifted by, absent when the page gave no frame to read. */
+  readonly lag?: number
   /** The clip's closing frame as a JPEG. */
   readonly still: Buffer
 }
@@ -39,8 +51,13 @@ export async function filmScreencast(request: {
   readonly beat: Beat
   readonly clip: string
 }): Promise<ScreencastTake> {
-  const scratch = mkdtempSync(join(tmpdir(), 'canon-take-cast-'))
-  const browser = await chromium.launch()
+  // Ahead of the launch, so a folder that refuses leaves no browser holding the
+  // process open past its refusal.
+  const scratch = openSpool(request.clip)
+  const browser = await chromium.launch().catch((error: unknown) => {
+    scratch.remove()
+    throw error
+  })
   let still: (() => Promise<Buffer | undefined>) | undefined
   try {
     const page = await browser.newPage({ viewport: VIEWPORT })
@@ -56,7 +73,11 @@ export async function filmScreencast(request: {
     const stageOn = (clock: () => number): Stage => ({
       now: clock,
       hold: (ms) => page.waitForTimeout(ms),
+      align: () => nextFrame(page, ALIGN_CAP_MS).then(() => undefined),
       pointer: async (input) => {
+        // A move waited on its frame already, so padding it would land the
+        // next one a frame late.
+        if (input.type === 'move') return send(page.mouse, input)
         const sent = clock()
         await send(page.mouse, input)
         const spent = clock() - sent
@@ -79,11 +100,35 @@ export async function filmScreencast(request: {
     const live = stageOn(() => performance.now())
     await performSteps(live, request.beat.setup, { pointer: START })
     if (request.beat.setup.length > 0) await live.hold(1000)
-    await page.mouse.move(START.x, START.y)
+    const lag = await calibrate(page)
 
-    const webm = join(scratch, 'take.webm')
     const events: LogEvent[] = []
-    await page.screencast.start({ path: webm, size: VIEWPORT, fps: FPS })
+    const spool: SpooledFrame[] = []
+    let spoolFailure: unknown
+    await page.screencast.start({
+      size: VIEWPORT,
+      // The docs tie this to `path`, but 1.64.1 still reads it here, where it
+      // doubles the frames Chromium may hold unacknowledged.
+      fps: FPS,
+      // Spooled rather than held, since a busy page sends about 19 MB a second.
+      // The write stays synchronous, so the acknowledgement Chromium paces its
+      // frames on waits for no encoder. Playwright calls this from a listener
+      // nothing awaits, so a throw here would surface as an unhandled rejection.
+      onFrame: ({ data, timestamp }) => {
+        const stamp = frameStamp({
+          presentedWall: timestamp,
+          wallNow: Date.now(),
+          monoNow: performance.now(),
+        })
+        const path = join(scratch.folder, `${spool.length}.jpg`)
+        try {
+          writeFileSync(path, data)
+          spool.push({ path, stamp })
+        } catch (error) {
+          spoolFailure ??= error
+        }
+      },
+    })
     const started = performance.now()
     const recording = stageOn(() => performance.now() - started)
     await recording.hold(HOLD_MS)
@@ -94,21 +139,186 @@ export async function filmScreencast(request: {
     await recording.hold(HOLD_MS)
     const filmedMs = recording.now()
     await page.screencast.stop()
+    if (spoolFailure !== undefined) throw spoolFailure
 
-    await transcode(webm, request.clip, FPS, filmedMs)
+    await encodeSpool(spool, request.clip, started, filmedMs)
     const frames = await probeFrames(request.clip)
-    return { frames, events, still: await lastFrame(request.clip, frames) }
+    const closing = await lastFrame(request.clip, frames)
+    if (lag === undefined) return { frames, events, still: closing }
+    return {
+      frames,
+      events: events.map((event) => shifted(event, lag)),
+      lag: Number(lag.toFixed(1)),
+      still: closing,
+    }
   } catch (error) {
     if (error instanceof TargetRefused && still) error.still = await still()
     throw error
   } finally {
     await browser.close()
-    rmSync(scratch, { recursive: true, force: true })
+    scratch.remove()
   }
 }
 
+type Page = import('playwright-core').Page
 type Mouse = import('playwright-core').Mouse
 
+interface SpooledFrame {
+  readonly path: string
+  /** When the frame was presented, on the monotonic clock. */
+  readonly stamp: number
+}
+
+/**
+ * Opens the folder holding one take's frames, beside its clip rather than in a
+ * temp folder nothing sweeps, since a 34 s beat on a busy page spools about
+ * 650 MB. A take killed outright runs no handler, so it leaves the folder where
+ * its owner looks, and the next take of that beat clears it.
+ */
+function openSpool(clip: string): { folder: string; remove: () => void } {
+  const folder = join(dirname(clip), 'spool')
+  rmSync(folder, { recursive: true, force: true })
+  mkdirSync(folder, { recursive: true })
+  const remove = (): void => {
+    process.off('exit', remove)
+    process.off('SIGINT', interrupt)
+    process.off('SIGTERM', interrupt)
+    rmSync(folder, { recursive: true, force: true })
+  }
+  // A signal skips the exit event, so it removes the folder and then re-raises
+  // itself with this handler gone, ending the process as it would have.
+  const interrupt = (signal: NodeJS.Signals): void => {
+    remove()
+    process.kill(process.pid, signal)
+  }
+  process.on('exit', remove)
+  process.once('SIGINT', interrupt)
+  process.once('SIGTERM', interrupt)
+  return { folder, remove }
+}
+
+/**
+ * Writes the clip from the spool, one frame per slot of the stage clock, so its
+ * length is the take's rather than whatever the frames span. Refuses when no
+ * frame arrived, since there is nothing true to show.
+ */
+async function encodeSpool(
+  spool: readonly SpooledFrame[],
+  clip: string,
+  startMs: number,
+  lengthMs: number,
+): Promise<void> {
+  const slots = slotFrames(
+    spool.map((frame) => frame.stamp),
+    { startMs, lengthMs, frameMs: FRAME_MS },
+  )
+  if (slots.length === 0) {
+    throw new Error(
+      `the screencast delivered no frame in ${(lengthMs / 1000).toFixed(2)} s of filming`,
+    )
+  }
+  const encoder = openFrameEncoder(clip, FPS)
+  try {
+    let shown = -1
+    let jpeg = Buffer.alloc(0)
+    for (const index of slots) {
+      const frame = spool[index]
+      if (frame && index !== shown) {
+        jpeg = readFileSync(frame.path)
+        shown = index
+      }
+      await encoder.write(jpeg)
+    }
+    await encoder.close()
+  } catch (error) {
+    encoder.abort()
+    throw error
+  }
+}
+
+/**
+ * The page time of its next animation frame, or undefined when none comes
+ * within `capMs`, as on a hidden page, or the page closed first.
+ */
+function nextFrame(page: Page, capMs: number): Promise<number | undefined> {
+  return withinCap(
+    page
+      .evaluate(
+        () => new Promise<number>((done) => requestAnimationFrame(done)),
+      )
+      .catch(() => undefined),
+    capMs,
+  )
+}
+
+/** Where the calibration's armed listener hands back the frame it painted in. */
+const PAINTED = '__canonTakePainted'
+
+/**
+ * How long a move takes to show in the clip, measured by sending one aligned
+ * move to `START` and reading the animation frame after its handler against
+ * the frame it was aligned to. Both readings are page time, so no clock mapping
+ * is needed. The screencast captures a frame once it is presented, one page
+ * frame after that frame begins, so the lag counts one page frame past the
+ * readings, read off two consecutive animation frames rather than assumed from
+ * the clip's rate. That held a dragged box within 7 px on every run where the
+ * readings alone left 10 to 15. Undefined when the page gives no frame to read,
+ * and the pointer rests on `START` either way.
+ */
+async function calibrate(page: Page): Promise<number | undefined> {
+  await page.mouse.move(START.x - 1, START.y)
+  const interval = await withinCap(
+    page
+      .evaluate(
+        () =>
+          new Promise<number>((done) =>
+            requestAnimationFrame((first) =>
+              requestAnimationFrame((second) => done(second - first)),
+            ),
+          ),
+      )
+      .catch(() => undefined),
+    2 * ALIGN_CAP_MS,
+  )
+  await page.evaluate((key) => {
+    const slot = window as unknown as Record<string, unknown>
+    slot[key] = new Promise<number>((done) => {
+      addEventListener('pointermove', () => requestAnimationFrame(done), {
+        once: true,
+        capture: true,
+      })
+    })
+  }, PAINTED)
+  const aligned = await nextFrame(page, ALIGN_CAP_MS)
+  await page.mouse.move(START.x, START.y)
+  const painted = await withinCap(
+    page
+      .evaluate((key) => {
+        const slot = window as unknown as Record<string, unknown>
+        const armed = slot[key] as Promise<number>
+        delete slot[key]
+        return armed
+      }, PAINTED)
+      .catch(() => undefined),
+    CALIBRATE_CAP_MS,
+  )
+  if (interval === undefined || aligned === undefined) return undefined
+  if (painted === undefined) return undefined
+  return Math.max(0, painted - aligned) + interval
+}
+
+/** An event moved `lag` later on the clip, with every point it sent. */
+function shifted(event: LogEvent, lag: number): LogEvent {
+  if (event.kind === 'move' && event.points) {
+    return {
+      ...event,
+      t: event.t + lag,
+      points: event.points.map((point) => ({ ...point, t: point.t + lag })),
+    }
+  }
+  return { ...event, t: event.t + lag }
+}
+
 async function send(mouse: Mouse, input: PointerInput): Promise<void> {
   switch (input.type) {
     case 'move':

package/src/take/stepper.ts

@@ -187,10 +187,10 @@ export async function filmStepped(
 async function frameStill(
   beginFrame: (screenshot: boolean) => Promise<{ screenshotData?: string }>,
 ): Promise<Buffer | undefined> {
-  const reply = await Promise.race([
+  const reply = await withinCap(
     beginFrame(true).catch(() => undefined),
-    sleep(STILL_CAP_MS),
-  ])
+    STILL_CAP_MS,
+  )
   return reply?.screenshotData
     ? Buffer.from(reply.screenshotData, 'base64')
     : undefined
@@ -214,7 +214,7 @@ async function load(page: ShellPage, url: string): Promise<number> {
   if (navigated.errorText) {
     throw new Error(`${navigated.errorText} at ${url}`)
   }
-  const timestamp = await Promise.race([loaded, sleep(LOAD_CAP_MS)])
+  const timestamp = await withinCap(loaded, LOAD_CAP_MS)
   if (typeof timestamp !== 'number') {
     throw new Error(
       `${url} fired no load event within ${LOAD_CAP_MS / 1000} s, so no frame clock could be read`,
@@ -381,6 +381,26 @@ async function withinStall<T>(
   }
 }
 
+/**
+ * Races `work` against a cap and resolves empty when the cap wins. The timer
+ * is cleared once the race settles, since a pending one keeps the process alive
+ * for the whole cap after filming ends.
+ */
+export async function withinCap<T>(
+  work: Promise<T>,
+  ms: number,
+): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const capped = new Promise<undefined>((done) => {
+    timer = setTimeout(() => done(undefined), ms)
+  })
+  try {
+    return await Promise.race([work, capped])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((done) => setTimeout(done, ms))
 }

package/src/tasks/holders.ts

@@ -0,0 +1,198 @@
+import { execa } from 'execa'
+import { gitEnv } from '@/git/env'
+import {
+  repositoryOf,
+  resolveSessions,
+  type SessionReport,
+} from '@/sessions/resolve'
+
+/**
+ * Bounds the one network read `canon tasks validate --live` takes, shorter than
+ * the archive's own, since the sweep waits on it and a slow answer reads the
+ * same as no answer.
+ */
+const GH_TIMEOUT_MS = 5_000
+
+/** `gh pr list` caps at 30 by default, and a truncated list would read as clean. */
+const PULL_LIMIT = 1_000
+
+/**
+ * Who holds each branch, named for a person reading the report. `undefined`
+ * means the source could not be read, which has to stay apart from an empty map:
+ * an unreachable source that degraded to "nobody holds it" would report a held
+ * row as clean.
+ */
+export type HolderReader = () => Promise<
+  ReadonlyMap<string, string> | undefined
+>
+
+/** Whether a merged pull request names a branch, `undefined` when GitHub could not say. */
+export type MergedReader = (branch: string) => Promise<boolean | undefined>
+
+export interface LiveReaders {
+  readonly sessions: HolderReader
+  readonly pulls: HolderReader
+  readonly merged: MergedReader
+}
+
+export interface SessionHolderOptions {
+  readonly resolve?: () => Promise<SessionReport>
+  readonly repository?: (root: string) => Promise<string | null>
+}
+
+/**
+ * Reads the roster scoped to `root`'s repository, since a branch name says
+ * nothing across a machine and another project's worker on the same name holds
+ * nothing here. Two rows leave the liveness undecided, a foreign record whose
+ * socket is gone and a row resting only on a socket file a crash can leave, so
+ * either reads the whole roster as unread rather than as a hold or as clear.
+ */
+export function sessionHolders(
+  root: string,
+  opts: SessionHolderOptions = {},
+): HolderReader {
+  const resolve = opts.resolve ?? resolveSessions
+  const repository = opts.repository ?? repositoryOf
+
+  return async () => {
+    try {
+      const [report, repo] = await Promise.all([resolve(), repository(root)])
+      if (
+        report.kind !== 'resolved' ||
+        report.foreignDead > 0 ||
+        report.sessions.some((session) => session.via === 'socket') ||
+        !repo
+      ) {
+        return undefined
+      }
+
+      return new Map(
+        report.sessions.flatMap((session) =>
+          session.repository === repo && session.branch
+            ? [[session.branch, `session ${session.name}`] as const]
+            : [],
+        ),
+      )
+    } catch {
+      return undefined
+    }
+  }
+}
+
+export type GhRunner = (
+  cwd: string,
+  args: readonly string[],
+) => Promise<string | undefined>
+
+const runGh: GhRunner = async (cwd, args) => {
+  if (Bun.which('gh') === null) return undefined
+
+  try {
+    // `gh` resolves its repository through git, so a hook's resolution
+    // variables would point it at another repository than `cwd`.
+    const result = await execa('gh', [...args], {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    return result.stdout
+  } catch {
+    return undefined
+  }
+}
+
+interface ListedPull {
+  readonly number: number
+  readonly headRefName: string
+  readonly isCrossRepository: boolean
+}
+
+function isListedPull(value: unknown): value is ListedPull {
+  if (typeof value !== 'object' || value === null) return false
+  const pull = value as Record<string, unknown>
+
+  return (
+    typeof pull.number === 'number' &&
+    typeof pull.headRefName === 'string' &&
+    typeof pull.isCrossRepository === 'boolean'
+  )
+}
+
+function parsePulls(stdout: string): readonly ListedPull[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(stdout)
+    return Array.isArray(parsed) && parsed.every(isListedPull)
+      ? parsed
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reads open pull requests off GitHub. A list reaching the limit may have cut
+ * off the one that holds a row, so it reads as unread. A fork's head names a
+ * branch in another repository, which holds nothing here however it is spelled.
+ */
+export function pullHolders(root: string, run: GhRunner = runGh): HolderReader {
+  return async () => {
+    const stdout = await run(root, [
+      'pr',
+      'list',
+      '--state',
+      'open',
+      '--limit',
+      String(PULL_LIMIT),
+      '--json',
+      'number,headRefName,isCrossRepository',
+    ])
+    if (stdout === undefined) return undefined
+
+    const pulls = parsePulls(stdout)
+    if (!pulls || pulls.length >= PULL_LIMIT) return undefined
+
+    return new Map(
+      pulls
+        .filter((pull) => !pull.isCrossRepository)
+        .map((pull) => [pull.headRefName, `pull request #${pull.number}`]),
+    )
+  }
+}
+
+/**
+ * Asks about one branch at a time rather than listing merged pull requests,
+ * since a list long enough to reach an old merge costs every run, and only a
+ * branch a session already holds against a row takes this read.
+ */
+export function mergedBranches(
+  root: string,
+  run: GhRunner = runGh,
+): MergedReader {
+  return async (branch) => {
+    const stdout = await run(root, [
+      'pr',
+      'list',
+      '--state',
+      'merged',
+      '--head',
+      branch,
+      '--limit',
+      String(PULL_LIMIT),
+      '--json',
+      'number,headRefName,isCrossRepository',
+    ])
+    if (stdout === undefined) return undefined
+
+    const pulls = parsePulls(stdout)
+    return pulls?.some((pull) => !pull.isCrossRepository)
+  }
+}
+
+export function liveReaders(root: string): LiveReaders {
+  return {
+    sessions: sessionHolders(root),
+    pulls: pullHolders(root),
+    merged: mergedBranches(root),
+  }
+}