@graphlearning/shell 0.10.1 → 0.10.2

package/scripts/_paths.mjs

@@ -1,20 +1,9 @@
-// Where these scripts read and write, now that they live in a package rather than in each repo.
-//
-// They used to resolve everything relative to their own file (`here = dirname(import.meta.url)`),
-// which worked only because scripts/ sat inside the app. From node_modules that points at the
-// package, so the two roots are now explicit:
-//
-//   repoDir — the content repo being built. npm run <script> sets cwd to the package root, so
-//             process.cwd() IS the repo. Source, public/audio and the dev server live here.
-//   dataDir — repoDir/scripts: the repo's own script DATA (titles.json, audio-manifest.json) and
-//             every output (out/, segments/, .tmp/). Deliberately the same paths as before the
-//             extraction, so .gitignore entries and muscle memory still hold.
-//   pkgDir  — this package's scripts/: machinery that ships with the shell (thumb-template.html).
-import { createRequire } from 'node:module'
+import { execFile, spawn } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
-import { pathToFileURL } from 'node:url'
+import { createRequire } from 'node:module'
 import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { promisify } from 'node:util'
 
 export const pkgDir = dirname(fileURLToPath(import.meta.url))
 export const repoDir = process.cwd()
@@ -25,48 +14,127 @@ if (!existsSync(join(repoDir, 'package.json'))) {
   process.exit(1)
 }
 
-// scripts/concept.json — the per-repo publishing identity. These used to be hardcoded defaults in
-// each repo's copy of thumb.mjs / gen-descriptions.mjs, which is exactly why they drifted (aws's
-// panel gradient was still AWS-orange in sql's copy for a while). Env vars still override, as before.
 const CONFIG_PATH = join(dataDir, 'concept.json')
 const raw = existsSync(CONFIG_PATH) ? JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) : {}
 
 export const concept = {
-  // The concept name used in video DESCRIPTIONS ("Apache Spark"). Not necessarily the app's
-  // subject — databricks-data-engineer publishes as "Databricks".
   name: process.env.CONCEPT ?? raw.concept ?? 'GraphL',
-  // The THUMBNAIL kicker, which is not always the same string: apache-spark's descriptions say
-  // "Apache Spark" while its thumbnails say "SPARK" (a long name does not fit the panel). The two
-  // lived in separate script copies before the extraction, so the divergence was invisible —
-  // collapsing them into one field silently rebrands that concept's thumbnails.
   kicker: process.env.CONCEPT_KICKER ?? raw.kicker ?? process.env.CONCEPT ?? raw.concept ?? 'GraphL',
   site: process.env.SITE ?? raw.site ?? 'https://graphl.in',
-  // The catalog path the app deploys under — usually /<repo>, but aws deploys at /aws-content.
   appPath: (process.env.APP_PATH ?? raw.appPath ?? '/').replace(/\/$/, ''),
   hashtags: process.env.HASHTAGS ?? raw.hashtags ?? '#TechEducation',
-  // The thumbnail's right-hand panel gradient, anchored on the concept's --brand.
   panelBg: process.env.PANEL_BG ?? raw.panelBg ?? 'radial-gradient(118% 104% at 70% 34%, #5b8cff 0%, #2a4fb8 44%, #0b1330 100%)',
 }
 
-// Load a peer dependency (puppeteer, esbuild) from the CONTENT REPO, not from this package.
-//
-// A bare `import('puppeteer')` resolves by walking up from the importing FILE. These scripts live in
-// node_modules/@graphlearning/shell/scripts, and under a local `file:../ui-shell` install that path
-// is a symlink — node resolves it to the real ui-shell/ directory and walks up from there, never
-// reaching the repo's node_modules. Anchoring the resolution at repoDir works under both layouts,
-// and it is also the honest description of the dependency: these are the REPO's tools, which the
-// scripts borrow. (esbuild previously resolved only by accident, via ui-shell's own vite install —
-// that would have failed outright once this package was consumed from the registry.)
+export const run = promisify(execFile)
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+export const titleCase = (slug) => slug.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')
+
+export const FFMPEG =
+  process.env.FFMPEG ?? ['/opt/homebrew/bin/ffmpeg', '/usr/local/bin/ffmpeg'].find(existsSync) ?? 'ffmpeg'
+
+export async function ffprobeDuration(file) {
+  const { stdout } = await run('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', file])
+  return parseFloat(stdout.trim())
+}
+
 const requireFromRepo = createRequire(join(repoDir, 'package.json'))
 
 export async function loadPeer(name) {
   try {
     return await import(pathToFileURL(requireFromRepo.resolve(name)).href)
   } catch {
-    console.error(`Missing "${name}" in ${repoDir}. It is an optional peer of @graphlearning/shell, ` +
-                  `needed by the capture/record scripts — install it there: npm i -D ${name}`)
+    console.error(
+      `Missing "${name}" in ${repoDir}. It is an optional peer of @graphlearning/shell, ` +
+        `needed by the capture/record scripts — install it there: npm i -D ${name}`,
+    )
     process.exit(1)
   }
 }
 
-export { resolve }
+export async function loadRegistry() {
+  const { build } = await loadPeer('esbuild')
+  const result = await build({
+    entryPoints: [resolve(repoDir, 'src/content/index.ts')],
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    write: false,
+  })
+  return import('data:text/javascript;base64,' + Buffer.from(result.outputFiles[0].text).toString('base64'))
+}
+
+export function publishTitles() {
+  try {
+    const { _comment, ...titles } = JSON.parse(readFileSync(join(dataDir, 'titles.json'), 'utf8'))
+    return titles
+  } catch {
+    return {}
+  }
+}
+
+async function startDevServer() {
+  console.log(`Starting dev server: ${repoDir} …`)
+  const child = spawn('npm', ['run', 'dev'], { cwd: repoDir, env: process.env })
+  const url = await new Promise((res, rej) => {
+    const to = setTimeout(() => rej(new Error('dev server did not print a URL within 60s')), 60000)
+    const onData = (buf) => {
+      const m = String(buf).match(/https?:\/\/localhost:\d+\/?/)
+      if (m) {
+        clearTimeout(to)
+        child.stdout.off('data', onData)
+        res(m[0].replace(/\/?$/, '/'))
+      }
+    }
+    child.stdout.on('data', onData)
+    child.stderr.on('data', (b) => process.env.DEBUG && process.stderr.write(b))
+    child.on('exit', (code) => rej(new Error(`dev server exited early (code ${code})`)))
+  })
+  for (let i = 0; i < 40; i++) {
+    try {
+      if ((await fetch(url)).ok) break
+    } catch {}
+    await sleep(250)
+  }
+  console.log(`  dev server at ${url}`)
+  return { child, url }
+}
+
+export const openApp = async () =>
+  process.env.APP_URL
+    ? { child: null, url: process.env.APP_URL.replace(/\/?$/, '/') }
+    : startDevServer()
+
+export async function gotoSection(page, appBase, slug) {
+  await page.goto(`${appBase}?capture=1#/${slug}`, { waitUntil: 'networkidle2' })
+  await page.waitForSelector('.react-flow__node', { timeout: 15000 })
+  await page.evaluate(async () => {
+    if (document.fonts?.ready) await document.fonts.ready
+  })
+  await sleep(700)
+}
+
+export async function startKeepalive(page) {
+  await page.evaluate(() => {
+    const d = document.createElement('div')
+    d.id = '__cap_keepalive'
+    d.style.cssText =
+      'position:fixed;left:0;top:0;width:1px;height:1px;background:#888;opacity:0.01;' +
+      'pointer-events:none;z-index:2147483647;will-change:transform'
+    document.body.appendChild(d)
+    let x = 0
+    const loop = () => {
+      x = (x + 3) % 30
+      d.style.transform = `translate3d(${x}px,0,0)`
+      window.__cap_raf = requestAnimationFrame(loop)
+    }
+    loop()
+  })
+}
+
+export async function stopKeepalive(page) {
+  await page.evaluate(() => {
+    if (window.__cap_raf) cancelAnimationFrame(window.__cap_raf)
+    document.getElementById('__cap_keepalive')?.remove()
+  })
+}

package/scripts/capture-shots.mjs

@@ -1,17 +1,4 @@
 #!/usr/bin/env node
-// capture-shots.mjs — [STEP 2, not yet wired] screenshot every slug's scene + record node coords.
-//
-//   node scripts/capture-shots.mjs [--only <slug[,slug]>]
-//
-// Plan (blueprint: ../../graphl-studio/aws-lab/scripts/capture-shots.mjs):
-//   1. spawn `npm run dev`, open it headless at 4K (3840×2160) with ?capture=1.
-//   2. read window.__scene.plan() → the list of slugs (scene + focus node).
-//   3. for each slug: render its scene, wait for the painted frame, screenshot → images/<slug>.png
-//      (full-frame background), and MEASURE node bounding boxes (react-flow node rects) → coords,
-//      including the focus node's box. Coords are written to a sidecar so the compose step can float
-//      the text panel clear of the narrating node.
-//
-// The full-frame PNG is the video background; the coords drive dynamic panel placement.
 
-console.error('capture-shots.mjs is a step-2 stub — not wired yet. See the header for the plan.')
+console.error('capture-shots is not implemented — use graphl-shots-4k.')
 process.exit(1)

package/scripts/gen-audio-manifest.mjs

@@ -1,38 +1,11 @@
 #!/usr/bin/env node
-// gen-audio-manifest.mjs — flatten the typed course catalog into the audio manifest.
-//
-// The Colab/Chatterbox notebook can't parse our TypeScript course files, so this is the bridge:
-// it evaluates the REAL `COURSES` registry (esbuild strips the type-only `../types` imports, so the
-// content files have no runtime deps) and folds every SECTION into one flat JSON entry, keyed to the
-// audio contract path  `<courseId>/<section-id>.wav`.
-//
-// Unlike graphl-studio (one wav per BEAT → `<course>/<section>-<beat>.wav`), this repo's model is
-// one section = one unit = one narration, so there is NO beat index — just `<course>/<section>.wav`.
-//
-//   Output: scripts/audio-manifest.json   →  { count, entries: [{ course, section, file, narration }] }
-//
-// Run:  npm run gen:audio   (then commit the json so the notebook sees it)
 
 import { writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { loadRegistry, dataDir } from './_paths.mjs'
 
-import { loadPeer, repoDir, dataDir } from './_paths.mjs'
-const { build } = await loadPeer('esbuild')
-const entry = resolve(repoDir, 'src/content/index.ts')
 const outFile = resolve(dataDir, 'audio-manifest.json')
-
-// Bundle the content registry to an in-memory ESM string. The content files import ONLY `../types`
-// (`import type` → erased), so the bundle has zero runtime deps and imports cleanly in Node.
-const result = await build({
-  entryPoints: [entry],
-  bundle: true,
-  format: 'esm',
-  platform: 'node',
-  write: false,
-})
-const code = result.outputFiles[0].text
-const mod = await import('data:text/javascript;base64,' + Buffer.from(code).toString('base64'))
-const { COURSES } = mod
+const { COURSES } = await loadRegistry()
 
 const entries = []
 for (const course of Object.values(COURSES)) {
@@ -49,7 +22,6 @@ for (const course of Object.values(COURSES)) {
 const manifest = { count: entries.length, entries }
 writeFileSync(outFile, JSON.stringify(manifest, null, 2) + '\n', 'utf-8')
 
-// A short human summary — how many sections per course, so a bad fold is obvious at a glance.
 const perCourse = {}
 for (const e of entries) perCourse[e.course] = (perCourse[e.course] ?? 0) + 1
 console.log(`Wrote ${entries.length} section(s) -> scripts/audio-manifest.json`)

package/scripts/gen-descriptions.mjs

@@ -1,100 +1,34 @@
 #!/usr/bin/env node
-// gen-descriptions.mjs — write a YouTube description .txt per course.
-//
-//   node scripts/gen-descriptions.mjs            # all courses
-//   node scripts/gen-descriptions.mjs foundations   # just one
-//
-// Adapted from ../../graphl-studio/aws/scripts/gen-descriptions.mjs for this SECTION-based repo. The
-// reference was beat-based and read slide titles from the live DOM (driven in ?capture=1); here one
-// SECTION = one scene + one slide + one narration wav, and every section already carries its own
-// `title` in the typed registry — so we need NO browser at all. We evaluate the real COURSES registry
-// via esbuild (the same bridge scripts/gen-audio-manifest.mjs uses) and read chapter titles straight
-// off it; chapter TIMES are ffprobe'd off each section's wav and summed with record-course.mjs's own
-// per-section timing (bell STING lead + clip + TAIL), so they line up with the concatenated MP4.
-//
-// Each description carries: a title + intro, CHAPTER timestamps (one per section, so YouTube
-// auto-chapters the video), the full course series with deep links, and hashtags. Output lands at
-// scripts/out/<course>.txt, next to the course's .mp4 / .png.
-//
-// Prerequisites: ffprobe on PATH; the app's audio present under public/audio/<course>/.
 
-import { execFile } from 'node:child_process'
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
-import { promisify } from 'node:util'
-import { join, resolve } from 'node:path'
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
 
-const run = promisify(execFile)
-import { loadPeer, repoDir, dataDir, concept } from './_paths.mjs'
-const { build } = await loadPeer('esbuild')
+import { loadRegistry, publishTitles, titleCase, ffprobeDuration, repoDir, dataDir, concept } from './_paths.mjs'
 
-// Match record-course.mjs's timing so chapter marks align with the concatenated video.
 const STING_MS = process.env.NO_STING ? 0 : process.env.STING_MS ? +process.env.STING_MS : 2800
 const TAIL_MS = process.env.TAIL_MS ? +process.env.TAIL_MS : 500
 const CIRCLED = ['①', '②', '③', '④', '⑤', '⑥', '⑦', '⑧', '⑨', '⑩', '⑪', '⑫']
 
-// The concept + where the app deploys, from the repo's scripts/concept.json (env vars still
-// override — see _paths.mjs). Deep link is `${SITE}${APP_PATH}/#/<course>` (hash routing).
 const CONCEPT = concept.name
 const SITE = concept.site
 const APP_PATH = concept.appPath
 const HASHTAGS = concept.hashtags
 
-// Curated PUBLISH titles (scripts/titles.json), keyed by course id — the search-facing name a course
-// carries on YouTube ("SQL Queries"), deliberately distinct from the registry's narrative
-// in-app title ("Data Ingestion"). Used for this video's headline AND every series entry, so the
-// description names courses the same way the thumbnails and video titles do. Absent file → registry.
-const PUBLISH_TITLES = (() => {
-  const f = join(dataDir, 'titles.json')
-  if (!existsSync(f)) return {}
-  try {
-    const { _comment, ...titles } = JSON.parse(readFileSync(f, 'utf8'))
-    return titles
-  } catch {
-    return {}
-  }
-})()
+const PUBLISH_TITLES = publishTitles()
 const publishTitle = (course) => PUBLISH_TITLES[course.id] ?? course.title
 
-const titleCase = (slug) => slug.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')
-// m:ss (or h:mm:ss past an hour) — YouTube chapter format; first chapter must be 0:00.
 function stamp(sec) {
   const s = Math.floor(sec), h = Math.floor(s / 3600), m = Math.floor((s % 3600) / 60), ss = s % 60
   const p2 = (n) => String(n).padStart(2, '0')
   return h > 0 ? `${h}:${p2(m)}:${p2(ss)}` : `${m}:${p2(ss)}`
 }
 
-async function ffprobeDuration(file) {
-  const { stdout } = await run('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', file])
-  return parseFloat(stdout.trim())
-}
-
-// Evaluate the typed COURSES registry. The content files import ONLY `../types` (`import type` →
-// erased), so the bundle has zero runtime deps and imports cleanly from memory.
-async function loadRegistry() {
-  const result = await build({
-    entryPoints: [resolve(repoDir, 'src/content/index.ts')],
-    bundle: true, format: 'esm', platform: 'node', write: false,
-  })
-  const code = result.outputFiles[0].text
-  return import('data:text/javascript;base64,' + Buffer.from(code).toString('base64'))
-}
-
-// Build the description text for one course. Blocks are separated by a VISIBLE rule (not blank lines)
-// so grouping survives even if YouTube trims empty lines on paste; chapters stay one-per-line
-// (required for auto-chapters) and each series entry is a single line ending in its URL (clickable).
 const RULE = '━━━━━━━━━━━━━━━━'
 function compose({ course, chapters, series }) {
   const L = []
-  // Headline: "<title> · <concept>", but drop the suffix when the publish title already leads with the
-  // concept ("SQL Queries · SQL" stammers; the publish title is the whole name).
   const headline = publishTitle(course)
   L.push(headline.toLowerCase().startsWith(CONCEPT.toLowerCase()) ? headline : `${headline} · ${CONCEPT}`)
   L.push(RULE)
-  // NB: this used to claim "the diagram assembles top-to-bottom as the narration walks through each
-  // idea" — boilerplate inherited from the graphl-studio reveal-engine, where a camera really did
-  // build a scene up beat by beat. THIS engine draws each scene SOLID (see record-course.mjs: "no
-  // reveal fold, no seek/transition/pan machinery"), so nothing assembles and the sentence described
-  // a video that does not exist. Same wrong line is still in the other concept repos' copies.
   L.push(
     `Part of GraphL's ${CONCEPT} series — every section pairs one diagram with the idea it explains, ` +
     `so the picture and the words land together.`,
@@ -120,7 +54,7 @@ async function main() {
   const [oneCourse] = process.argv.slice(2)
 
   const reg = await loadRegistry()
-  const series = Object.values(reg.COURSES) // catalog order (registry insertion order)
+  const series = Object.values(reg.COURSES)
   const targets = oneCourse ? series.filter((c) => c.id === oneCourse) : series
   if (!targets.length) {
     console.error(`✗ no such course "${oneCourse}" (have: ${series.map((c) => c.id).join(', ')})`)
@@ -136,8 +70,6 @@ async function main() {
     let t = 0
     let missing = 0
     for (const section of course.sections) {
-      // Chapter starts at this section's bell lead-in (its first frame) — record-course.mjs holds the
-      // opening frame for STING_MS under the bell, then the narration clip, then a TAIL.
       chapters.push({ start: t, title: section.title || titleCase(section.id) })
       const wav = join(audioDir, `${section.id}.wav`)
       const dur = existsSync(wav) ? await ffprobeDuration(wav) : (missing++, 3)

package/scripts/record-all.mjs

@@ -1,31 +1,4 @@
 #!/usr/bin/env node
-// record-all.mjs — batch 4K capture across courses, pulling narration from GitHub as it lands.
-//
-//   npm run record:all                        # every course, in syllabus order
-//   npm run record:all -- --courses internals,performance
-//   npm run record:all -- --wait 0            # never wait; skip any course missing audio
-//   npm run record:all -- --no-pull           # use the working tree as-is
-//
-// WHY THIS EXISTS: the narration wavs are produced by a Colab + Chatterbox pass that commits them
-// to the repo's branch one section at a time, so the audio for a course arrives WHILE this is
-// running. A plain `for c in …; do npm run record -- $c; done` would reach `internals` before its
-// nine wavs existed and silently record six sections of 3s silence (record-course.mjs's documented
-// fallback — it keeps the pipeline from hanging, which is right for one missing clip and wrong for a
-// whole chapter). So before each course this does: git pull → count that course's wavs against
-// scripts/audio-manifest.json → if any are missing, keep pulling every --poll until they land or
-// --wait expires. A course is only recorded when it is COMPLETE; an incomplete one is skipped and
-// named in the summary, never half-recorded.
-//
-// Everything else is record-course.mjs's job, unchanged: the 2.4s pulse-period loop window, the
-// bell lead-in, the per-segment fingerprint cache (so a re-run after a skip costs nothing for the
-// courses already done) and the final concat into scripts/out/<course>.mp4.
-//
-// SLEEP: the repo's `record:all` script wraps this in `caffeinate -ims` so a multi-hour batch
-// survives the machine going idle — `"record:all": "caffeinate -ims graphl-record-all"`. -i no idle
-// sleep, -m no disk sleep, -s no system sleep (AC power only). -d is deliberately NOT set: capture
-// is headless, so forcing the display on all night buys nothing. The wrapper stays in the repo
-// rather than inside this script because `caffeinate` is macOS-only and re-exec'ing ourselves under
-// it would hide a process layer from anyone reading the batch's output.
 
 import { execFileSync, spawn } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
@@ -40,13 +13,8 @@ if (!existsSync(manifestPath)) {
 }
 const entries = JSON.parse(readFileSync(manifestPath, 'utf8')).entries ?? []
 
-// The recorder is PACKAGE-owned, so resolving it from this file is correct (see _paths.mjs: the rule
-// is never to resolve repo data that way). Spawned directly rather than through `npm run record` —
-// one less process between the batch and ffmpeg/puppeteer for signals to cross, and it does not
-// require the consuming repo to have declared a `record` script.
 const RECORDER = join(pkgDir, 'record-course.mjs')
 
-// ---- CLI ---------------------------------------------------------------------------------
 function parse(argv) {
   const o = { courses: [], waitMin: 240, pollS: 120, pull: true, force: false }
   for (let i = 0; i < argv.length; i++) {
@@ -65,7 +33,6 @@ function parse(argv) {
 }
 const opt = parse(process.argv.slice(2))
 
-// Syllabus order = the manifest's own order (it is generated from COURSES), not alphabetical.
 const allCourses = [...new Set(entries.map((e) => e.course))]
 const courses = opt.courses.length ? opt.courses : allCourses
 const unknown = courses.filter((c) => !allCourses.includes(c))
@@ -77,23 +44,14 @@ if (unknown.length) {
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 const hhmm = () => new Date().toTimeString().slice(0, 8)
 
-// ---- narration state ---------------------------------------------------------------------
-// A course is recordable when every section the manifest lists for it has a wav on disk.
 function audioState(course) {
   const want = entries.filter((e) => e.course === course)
   const missing = want.filter((e) => !existsSync(join(repoDir, 'public', 'audio', e.file)))
   return { total: want.length, have: want.length - missing.length, missing: missing.map((e) => e.section) }
 }
 
-// ---- git ----------------------------------------------------------------------------------
-// The branch is read rather than assumed: most repos record from `main`, but not all of them sit
-// there (aws-lab is on `rebuild/atom-library`), and pulling a branch the repo is not on would
-// either fail or quietly fetch the wrong wavs. A detached HEAD has nothing to track, so pulling is
-// skipped instead of guessed at.
 function currentBranch() {
   try {
-    // stderr ignored: outside a git repo this prints git's own "fatal: not a git repository" ahead
-    // of the note below, which reads like the batch broke when it is a supported case.
     const b = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'],
       { cwd: repoDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
     return b && b !== 'HEAD' ? b : null
@@ -103,8 +61,6 @@ function currentBranch() {
 }
 const branch = opt.pull ? currentBranch() : null
 
-// Fast-forward only: this repo's working tree is never the place Colab's commits get merged, so a
-// non-ff situation means something unexpected and the batch should say so rather than resolve it.
 function pull() {
   if (!opt.pull) return { ok: true, note: 'skipped (--no-pull)' }
   if (!branch) return { ok: true, note: 'skipped (detached HEAD or not a git repo)' }
@@ -114,13 +70,11 @@ function pull() {
     const after = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repoDir, encoding: 'utf8' }).trim()
     return { ok: true, note: before === after ? 'already current' : `${before.slice(0, 7)} → ${after.slice(0, 7)}` }
   } catch (e) {
-    // Network blips and transient GitHub errors are expected over a multi-hour run — report and
-    // carry on with whatever the working tree already has rather than aborting the batch.
     return { ok: false, note: (e.stderr?.toString() || e.message).trim().split('\n').pop() }
   }
 }
 
-// ---- record ---------------------------------------------------------------------------------
+let current = null
 function record(course) {
   return new Promise((done) => {
     const args = [RECORDER, course, ...(opt.force ? ['--force'] : [])]
@@ -131,13 +85,10 @@ function record(course) {
   })
 }
 
-// Forward Ctrl-C to the running recorder so ffmpeg/puppeteer/vite do not outlive the batch.
-let current = null
 for (const sig of ['SIGINT', 'SIGTERM']) {
   process.on(sig, () => { current?.kill(sig); console.log(`\n${sig} — stopping batch.`); process.exit(130) })
 }
 
-// ---- the batch --------------------------------------------------------------------------------
 const results = []
 console.log(`Batch 4K capture — ${courses.length} course(s): ${courses.join(', ')}`)
 console.log(`  pull=${opt.pull}${branch ? ` (origin/${branch})` : ''} wait=${opt.waitMin}min poll=${opt.pollS}s force=${opt.force}\n`)
@@ -149,8 +100,6 @@ for (const course of courses) {
   console.log(`  git pull: ${p.ok ? p.note : `FAILED — ${p.note} (continuing with local tree)`}`)
 
   let st = audioState(course)
-  // Colab commits one section at a time, so an incomplete course is usually just EARLY. Keep
-  // pulling until it completes or the budget runs out; --wait 0 turns this into a plain skip.
   const deadline = Date.now() + opt.waitMin * 60_000
   while (st.missing.length && Date.now() < deadline) {
     console.log(`  audio ${st.have}/${st.total} — waiting ${opt.pollS}s for: ${st.missing.join(', ')}`)
@@ -179,7 +128,6 @@ for (const course of courses) {
   }
 }
 
-// ---- summary ------------------------------------------------------------------------------------
 console.log(`\n${'═'.repeat(72)}\nSummary  [${hhmm()}]`)
 for (const r of results) {
   const mark = r.status === 'ok' ? '✅' : r.status === 'skipped' ? '⊘ ' : '✗ '