veodl 1.8.1

package/src/run-archive.js

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { cacheBase } from './paths.js';
+import { readJson, writeJson } from './state.js';
+
+export const RUN_ARCHIVE_ID = /^[0-9a-z]{6}$/;
+const SAMPLE_BYTES = 64 * 1024;
+const MAX_SEARCH_FILES = 200_000;
+const MEDIA_EXTENSIONS = new Set(['.mp4', '.mkv', '.webm', '.mov', '.m4v', '.mp3', '.m4a', '.aac', '.opus', '.ogg', '.flac', '.wav', '.mka', '.ts']);
+
+export function runArchiveFile(id, root = cacheBase()) {
+  if (!RUN_ARCHIVE_ID.test(id)) throw new Error('Run ids have 6 letters or digits.');
+  return path.join(path.resolve(root), 'run-history', `${id}.json`);
+}
+
+export function isMediaFile(file) { return MEDIA_EXTENSIONS.has(path.extname(file).toLowerCase()); }
+
+async function regularFile(file) {
+  const info = await lstat(file).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  return info?.isFile() && !info.isSymbolicLink() ? info : null;
+}
+
+/** Sample three parts of a file so renames can be found without rereading a huge video. */
+export async function fileFingerprint(file, knownInfo) {
+  const info = knownInfo || await regularFile(file);
+  if (!info) return null;
+  const digest = createHash('sha256').update(`veo-file-v1:${info.size}:`);
+  const positions = [...new Set([0, Math.floor(Math.max(0, info.size - SAMPLE_BYTES) / 2), Math.max(0, info.size - SAMPLE_BYTES)])];
+  const handle = await open(file, 'r');
+  try {
+    for (const position of positions) {
+      const bytes = Math.min(SAMPLE_BYTES, info.size - position);
+      const buffer = Buffer.alloc(bytes);
+      const { bytesRead } = await handle.read(buffer, 0, bytes, position);
+      if (bytesRead !== bytes) throw new Error(`File changed while recording its identity: ${file}`);
+      digest.update(String(position)).update(':').update(buffer);
+    }
+  } finally { await handle.close(); }
+  return { size: info.size, sampleSha256: digest.digest('hex'),
+    device: info.dev, inode: info.ino };
+}
+
+export async function archiveRun(job, { root = cacheBase(), now = new Date() } = {}) {
+  const id = job.runId;
+  if (!RUN_ARCHIVE_ID.test(id || '')) return null;
+  const items = [];
+  for (const item of job.items || []) {
+    const files = [];
+    for (const file of item.files || []) {
+      const media = isMediaFile(file);
+      files.push({ originalPath: path.resolve(file), media,
+        fingerprint: media ? item.fingerprints?.[file] || await fileFingerprint(file).catch(() => null) : null });
+    }
+    items.push({ url: item.url, status: item.status, error: item.error || null,
+      output: path.resolve(item.options?.output || job.options?.output || process.cwd()), files });
+  }
+  const archived = { version: 1, id, startedAt: job.startedAt || null, finishedAt: now.toISOString(),
+    status: items.every(item => ['saved', 'skipped'].includes(item.status)) ? 'completed' : 'incomplete', items };
+  if (await lstat(runArchiveFile(id, root)).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; })) {
+    throw new Error(`Run archive ${id} already exists; refusing to overwrite it.`);
+  }
+  await writeJson(runArchiveFile(id, root), archived);
+  return archived;
+}
+
+export async function readRunArchive(id, root = cacheBase()) {
+  const archive = await readJson(runArchiveFile(id, root), null);
+  if (!archive) throw new Error(`No finished run with id ${id} was found. Active runs appear in veo runs --json.`);
+  if (archive.version !== 1 || archive.id !== id || !Array.isArray(archive.items)) throw new Error(`Invalid archived run: ${id}`);
+  return archive;
+}
+
+async function scan(root, wantedSizes, signal) {
+  const info = await regularFile(root);
+  if (info) throw new Error(`Search root is a file: ${root}`);
+  const directory = await lstat(root).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!directory) return [];
+  if (!directory.isDirectory() || directory.isSymbolicLink()) throw new Error(`Search root is not a plain directory: ${root}`);
+  const candidates = [];
+  const pending = [root];
+  let seen = 0;
+  while (pending.length) {
+    signal?.throwIfAborted();
+    const current = pending.pop();
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      const file = path.join(current, entry.name);
+      if (entry.isDirectory()) pending.push(file);
+      else if (entry.isFile()) {
+        if (++seen > MAX_SEARCH_FILES) throw new Error(`Too many files under ${root}; use --search with a narrower directory.`);
+        const details = await regularFile(file);
+        if (details && wantedSizes.has(details.size)) candidates.push({ file, details });
+      }
+    }
+  }
+  return candidates;
+}
+
+/** Resolve original paths first, then use fingerprints to find renamed media. */
+export async function locateRunFiles(archive, { searchRoot, signal } = {}) {
+  const items = [];
+  const missing = [];
+  for (const item of archive.items) {
+    signal?.throwIfAborted();
+    const files = [];
+    for (const entry of item.files || []) {
+      const details = await regularFile(entry.originalPath);
+      const fingerprint = details && entry.fingerprint ? await fileFingerprint(entry.originalPath, details).catch(error => { if (error.code === 'ENOENT') return null; throw error; }) : null;
+      const valid = details && (!entry.fingerprint || (fingerprint?.size === entry.fingerprint.size && fingerprint.sampleSha256 === entry.fingerprint.sampleSha256));
+      const resolved = { originalPath: entry.originalPath, path: valid ? entry.originalPath : null,
+        found: Boolean(valid), renamed: false, media: Boolean(entry.media) };
+      files.push(resolved);
+      if (!valid && entry.media && entry.fingerprint) missing.push({ resolved, entry, output: item.output });
+    }
+    items.push({ url: item.url, status: item.status, error: item.error || null, files });
+  }
+  if (missing.length) {
+    const roots = [...new Set(missing.map(item => item.output).concat(searchRoot ? [path.resolve(searchRoot)] : []))];
+    const wanted = new Set(missing.map(item => item.entry.fingerprint.size));
+    const matches = new Map();
+    for (const root of roots) for (const candidate of await scan(root, wanted, signal)) {
+      signal?.throwIfAborted();
+      const fingerprint = await fileFingerprint(candidate.file, candidate.details).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+      if (!fingerprint) continue;
+      const key = `${fingerprint.size}:${fingerprint.sampleSha256}`;
+      const paths = matches.get(key) || new Set();
+      paths.add(candidate.file);
+      matches.set(key, paths);
+    }
+    for (const { resolved, entry } of missing) {
+      const key = `${entry.fingerprint.size}:${entry.fingerprint.sampleSha256}`;
+      const paths = [...(matches.get(key) || [])];
+      let selected = paths.length === 1 ? paths[0] : null;
+      if (!selected && paths.length > 1 && entry.fingerprint.inode > 0) {
+        const sameFile = [];
+        for (const file of paths) {
+          const details = await regularFile(file);
+          if (details?.dev === entry.fingerprint.device && details.ino === entry.fingerprint.inode) sameFile.push(file);
+        }
+        if (sameFile.length === 1) selected = sameFile[0];
+      }
+      if (selected) {
+        resolved.path = selected; resolved.found = true; resolved.renamed = selected !== entry.originalPath;
+      } else if (paths.length > 1) resolved.candidates = paths;
+    }
+  }
+  return items;
+}

package/src/runs.js

@@ -0,0 +1,333 @@
+import { commandOutput } from './output.js';
+import { randomInt, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { cacheBase } from './paths.js';
+import { writeJson } from './state.js';
+import { runArchiveFile } from './run-archive.js';
+import { cleanText, localStamp } from './utils.js';
+
+/**
+ * Every veo run registers itself under the per-user cache's `runs` directory
+ * while it works, so another terminal can list it (`veo runs`), inspect it
+ * (`veo runs <id>`) or cancel it (`veo stop <id>`) without guessing at PIDs.
+ * Records hold an id, times, URLs, paths and settings — never credentials or
+ * cookie settings, and the record itself is always removed when the run ends.
+ */
+export const RUN_ID = /^[0-9a-z]{6}$/;
+export const STOP_TIMEOUT_MS = 15000;
+const RECORD = /^[a-f0-9-]{36}\.json$/;
+const ID_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+const ITEM_STATUSES = new Set(['pending', 'running', 'saved', 'skipped', 'failed', 'cancelled']);
+const SHOWN_ITEMS = 10;
+const OUTPUT_WIDTH = 42;
+
+export const RUNS_HELP = `veo runs [id] [--json]
+
+List active veo runs with their 6-character id, process id, start time and progress.
+With an id, show one run in detail: URLs, media settings, output directory, job file
+and the state of every item. A run appears while it works and disappears when it
+finishes. Records of crashed runs are kept but marked stale.
+Use --json for machine-readable run metadata and per-item progress.
+Use veo stop <id> to stop one run.
+`;
+
+export const STOP_HELP = `veo stop [id]
+
+Ask one run, or every run when no id is given, to stop, and wait until it exits.
+A stopped run keeps its partial data and its retry job, so the printed
+veo --retry-failed command still works; veo flush removes those later.
+Stale records of crashed runs are removed. Exit status is 1 when a run does not
+stop in time.
+`;
+
+export function runsDirectory(root = cacheBase()) {
+  return path.join(path.resolve(root), 'runs');
+}
+
+/**
+ * A run record is only trusted when it names a plausible process. Older veo
+ * versions wrote nothing but a pid, so a missing version is still accepted.
+ */
+function validRecord(run) {
+  if (!run || typeof run !== 'object' || Array.isArray(run)) return false;
+  return (run.version === undefined || run.version === 1) && Number.isInteger(run.pid) && run.pid > 0;
+}
+
+const exists = file => lstat(file).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; });
+const text = value => typeof value === 'string' ? cleanText(value) : '';
+const newRunId = () => Array.from({ length: 6 }, () => ID_ALPHABET[randomInt(ID_ALPHABET.length)]).join('');
+
+export function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; }
+}
+
+async function runFiles(root) {
+  const directory = runsDirectory(root);
+  const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!info) return [];
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`Invalid active run directory: ${directory}`);
+  return (await readdir(directory, { withFileTypes: true }))
+    .filter(entry => entry.isFile() && RECORD.test(entry.name)).map(entry => path.join(directory, entry.name));
+}
+
+// Cache files are machine-written: a missing, truncated or foreign file must
+// never take a veo command down, so unreadable JSON simply counts as unknown.
+async function readRecordFile(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); } catch { return null; }
+}
+
+async function readRecords(root) {
+  const records = [];
+  for (const file of await runFiles(root)) {
+    // Damaged or foreign files are ignored, never fatal: a single stray file
+    // must not block every later veo run. Downloads of a run that could not be
+    // recognized stay protected by the staging lock that run holds.
+    const run = await readRecordFile(file);
+    if (!validRecord(run)) continue;
+    records.push({ ...run, id: RUN_ID.test(run.id || '') ? run.id : null, file });
+  }
+  return records;
+}
+
+/** Every registered run, live ones first and then the most recently started. */
+export async function listRuns(root = cacheBase()) {
+  const runs = await readRecords(root);
+  for (const run of runs) run.alive = alive(run.pid);
+  return runs.sort((a, b) => Number(b.alive) - Number(a.alive) || String(b.startedAt || '').localeCompare(String(a.startedAt || '')));
+}
+
+/**
+ * Register this process as a run and poll for a stop request. The returned
+ * handle exposes the run's id, its resolved settings for `veo runs <id>`, and
+ * the cleanup that removes the record when the run ends.
+ */
+export async function registerRun(cancel, root = cacheBase()) {
+  const directory = runsDirectory(root);
+  await mkdir(directory, { recursive: true });
+  const gate = path.join(path.resolve(root), '.flush');
+  if (await exists(gate)) throw new Error('veo flush is in progress. Try again after cleanup finishes.');
+  const taken = new Set((await readRecords(root)).map(run => run.id).filter(Boolean));
+  let id = null;
+  for (let attempt = 0; attempt < 20 && !id; attempt++) {
+    const candidate = newRunId();
+    if (!taken.has(candidate) && !await exists(runArchiveFile(candidate, root))) id = candidate;
+  }
+  if (!id) throw new Error('Could not allocate a free run id. Remove stale run records with veo stop or veo flush.');
+  const file = path.join(directory, `${randomUUID()}.json`);
+  const request = `${file}.cancel`;
+  const record = { version: 1, id, pid: process.pid, startedAt: new Date().toISOString(),
+    urls: [], output: null, media: null, quality: null, format: null, playlist: false, job: null };
+  await writeJson(file, record);
+  // A flush that started while this run registered must still win.
+  if (await exists(gate)) {
+    await rm(file, { force: true });
+    throw new Error('veo flush is in progress. Try again after cleanup finishes.');
+  }
+  const timer = setInterval(() => { exists(request).then(found => { if (found) cancel(); }).catch(() => {}); }, 200);
+  timer.unref();
+  return {
+    id,
+    file,
+    /** Merge what this run resolved, so other terminals can inspect it. */
+    async describe(details = {}) {
+      Object.assign(record, {
+        urls: (Array.isArray(details.urls) ? details.urls : []).filter(url => typeof url === 'string').slice(0, 200).map(cleanText),
+        output: text(details.output) || null,
+        media: details.audio ? 'audio' : 'video',
+        quality: details.audio ? null : text(details.quality) || null,
+        format: text(details.format) || null,
+        playlist: Boolean(details.playlist),
+        job: text(details.job) || null,
+      });
+      await writeJson(file, record);
+    },
+    async unregister() {
+      clearInterval(timer);
+      await rm(file, { force: true });
+      await rm(request, { force: true });
+    },
+  };
+}
+
+/** Per-item progress of a run, read from the job file it writes as it works. */
+async function readProgress(jobFile) {
+  if (!jobFile) return null;
+  const job = await readRecordFile(jobFile);
+  if (job?.version !== 1 || !Array.isArray(job.items)) return null;
+  const items = job.items.map(item => ({
+    url: text(item?.url),
+    status: ITEM_STATUSES.has(item?.status) ? item.status : 'pending',
+    files: (Array.isArray(item?.files) ? item.files : []).map(text).filter(Boolean),
+    error: text(item?.error) || null,
+  }));
+  const counts = { total: items.length, pending: 0, running: 0, saved: 0, skipped: 0, failed: 0, cancelled: 0 };
+  for (const item of items) counts[item.status]++;
+  return { items, counts };
+}
+
+async function describeRuns(root) {
+  const runs = await listRuns(root);
+  return Promise.all(runs.map(async run => ({ ...run, progress: await readProgress(run.job) })));
+}
+
+export function summarizeProgress(progress) {
+  const counts = progress?.counts;
+  if (!counts?.total) return 'starting';
+  const parts = [];
+  const done = counts.saved + counts.skipped;
+  if (done) parts.push(`${done}/${counts.total} done`);
+  if (counts.running) parts.push(`${counts.running} running`);
+  if (counts.failed) parts.push(`${counts.failed} failed`);
+  if (counts.cancelled) parts.push(`${counts.cancelled} cancelled`);
+  if (counts.pending) parts.push(parts.length ? `${counts.pending} pending` : `${counts.total} pending`);
+  return parts.join(', ');
+}
+
+function shortDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return '0s';
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  return `${Math.floor(seconds / 3600)}h ${Math.floor(seconds % 3600 / 60)}m`;
+}
+
+const shorten = (value, width = OUTPUT_WIDTH) => value.length <= width ? value : `…${value.slice(-(width - 1))}`;
+const label = run => run.id || `PID ${run.pid}`;
+// Records of older versions have no start time, so no uptime can be shown.
+const uptime = run => Number.isFinite(Date.parse(run.startedAt)) ? shortDuration(Date.now() - Date.parse(run.startedAt)) : null;
+
+function describeMedia(run) {
+  const detail = run.media === 'audio' ? run.format : run.quality;
+  return `${run.media || 'not resolved yet'}${detail ? `, ${detail}` : ''}${run.playlist ? ', playlist' : ''}`;
+}
+
+export function formatRuns(runs) {
+  if (!runs.length) return 'veo runs\n\nNo veo runs are active. Start a download to see it here.\n';
+  const rows = runs.map(run => {
+    const running = uptime(run);
+    return [run.id || '-', String(run.pid), run.alive ? `running${running ? ` ${running}` : ''}` : 'stale',
+      localStamp(run.startedAt), summarizeProgress(run.progress), run.output ? shorten(text(run.output)) : '-'];
+  });
+  const header = ['ID', 'PID', 'STATE', 'STARTED', 'ITEMS', 'OUTPUT'];
+  const widths = header.map((title, index) => Math.max(title.length, ...rows.map(row => row[index].length)));
+  const line = cells => cells.map((cell, index) => cell.padEnd(widths[index])).join('  ').trimEnd();
+  return `${['veo runs', '', line(header), ...rows.map(line), '', 'Details: veo runs <id>    Stop: veo stop [id]'].join('\n')}\n`;
+}
+
+export function formatRunDetails(run) {
+  const lines = [`veo runs ${run.id || '-'}`, ''];
+  const running = uptime(run);
+  lines.push(`State:   ${run.alive ? `running (PID ${run.pid})` : `stale (PID ${run.pid} is gone)`}`);
+  lines.push(`Started: ${localStamp(run.startedAt)}${run.alive && running ? ` (${running} ago)` : ''}`);
+  lines.push(`Media:   ${describeMedia(run)}`);
+  lines.push(`Output:  ${text(run.output) || 'not resolved yet'}`);
+  lines.push(`Job:     ${text(run.job) || 'not created yet'}`);
+  const urls = (Array.isArray(run.urls) ? run.urls : []).map(text).filter(Boolean);
+  lines.push(`URLs:    ${urls.length ? `${urls.length}` : 'not resolved yet'}`);
+  urls.slice(0, SHOWN_ITEMS).forEach((url, index) => lines.push(`  ${index + 1}. ${url}`));
+  if (urls.length > SHOWN_ITEMS) lines.push(`  … and ${urls.length - SHOWN_ITEMS} more`);
+  const items = run.progress?.items || [];
+  if (items.length) {
+    lines.push(`Items:   ${summarizeProgress(run.progress)}`);
+    items.slice(0, SHOWN_ITEMS).forEach((item, index) => {
+      const files = item.files.length ? `  ${item.files[0]}${item.files.length > 1 ? ` (+${item.files.length - 1} file(s))` : ''}` : '';
+      lines.push(`  ${String(index + 1).padStart(2)}. ${item.status}${item.status === 'saved' ? files : `  ${item.url}`}`);
+      if (item.error) lines.push(`      ${item.error}`);
+    });
+    if (items.length > SHOWN_ITEMS) lines.push(`  … and ${items.length - SHOWN_ITEMS} more item(s)`);
+  }
+  lines.push('');
+  lines.push(run.alive && run.id ? `Stop:    veo stop ${run.id}` : 'Cleanup: veo stop  (removes stale records)');
+  return `${lines.join('\n')}\n`;
+}
+
+function normalizeId(value) {
+  const id = cleanText(value).toLowerCase();
+  if (!RUN_ID.test(id)) throw new Error(`Invalid run id "${cleanText(value)}". Run ids have 6 characters and are listed by veo runs.`);
+  return id;
+}
+
+export async function runsMain(args = [], { stdout = process.stdout, root = cacheBase() } = {}) {
+  [args, stdout] = commandOutput(args, stdout);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    stdout.write(RUNS_HELP);
+    return 0;
+  }
+  const json = args.includes('--json');
+  args = args.filter(arg => arg !== '--json');
+  if (args.length > 1) throw new Error('Usage: veo runs [id] [--json]');
+  const runs = await describeRuns(root);
+  if (!args.length) {
+    if (json) stdout.write(`${JSON.stringify({ count: runs.length, runs: runs.map(publicRun) })}\n`);
+    else stdout.write(formatRuns(runs));
+    return 0;
+  }
+  const id = normalizeId(args[0]);
+  const run = runs.find(item => item.id === id);
+  if (!run) throw new Error(`No veo run with id ${id} is active. List runs with veo runs.`);
+  if (json) stdout.write(`${JSON.stringify(publicRun(run))}\n`);
+  else stdout.write(formatRunDetails(run));
+  return 0;
+}
+
+function publicRun(run) {
+  return { id: run.id, pid: run.pid, state: run.alive ? 'running' : 'stale', startedAt: run.startedAt || null,
+    urls: Array.isArray(run.urls) ? run.urls : [], output: run.output || null, media: run.media || null,
+    quality: run.quality || null, format: run.format || null, playlist: Boolean(run.playlist), job: run.job || null,
+    progress: run.progress || null };
+}
+
+/**
+ * A run answers a stop request by cleaning up its own record, so a run counts as
+ * gone as soon as its record disappears — a live-looking process is not enough
+ * (the pid may already belong to something else).
+ */
+export async function waitForExit(runs, timeoutMs) {
+  const pending = async () => {
+    for (const run of runs) if (alive(run.pid) && await exists(run.file)) return true;
+    return false;
+  };
+  const deadline = Date.now() + timeoutMs;
+  while (await pending()) {
+    if (Date.now() >= deadline) return false;
+    await delay(100);
+  }
+  return true;
+}
+
+export async function stopMain(args = [], { stdout = process.stdout, root = cacheBase(), timeoutMs = STOP_TIMEOUT_MS } = {}) {
+  [args, stdout] = commandOutput(args, stdout);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    stdout.write(STOP_HELP);
+    return 0;
+  }
+  if (args.length > 1) throw new Error('Usage: veo stop [id]');
+  let targets = await listRuns(root);
+  if (args.length) {
+    const id = normalizeId(args[0]);
+    targets = targets.filter(run => run.id === id);
+    if (!targets.length) throw new Error(`No veo run with id ${id} is active. List runs with veo runs.`);
+  }
+  const stale = targets.filter(run => !run.alive);
+  const live = targets.filter(run => run.alive);
+  for (const run of live) await writeFile(`${run.file}.cancel`, 'stop');
+  if (live.length) await waitForExit(live, timeoutMs);
+  const remaining = [];
+  for (const run of live) if (await exists(run.file) && alive(run.pid)) remaining.push(run);
+  const stopped = live.filter(run => !remaining.includes(run));
+  for (const run of [...stale, ...stopped]) {
+    await rm(run.file, { force: true });
+    await rm(`${run.file}.cancel`, { force: true });
+  }
+  const lines = ['veo stop', ''];
+  if (stopped.length) lines.push(`Stopped: ${stopped.map(label).join(', ')}`);
+  if (stale.length) lines.push(`Removed ${stale.length} stale record(s): ${stale.map(label).join(', ')}`);
+  if (remaining.length) lines.push(`Still running: ${remaining.map(label).join(', ')}`);
+  if (!stopped.length && !stale.length && !remaining.length) lines.push('No veo runs were active.');
+  if (stopped.length) lines.push('', 'Partial data and retry jobs are kept; veo flush removes them.');
+  stdout.write(`${lines.join('\n')}\n`);
+  return remaining.length ? 1 : 0;
+}

package/src/state.js

@@ -0,0 +1,27 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export function digest(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 24);
+}
+
+export async function readJson(file, fallback) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return fallback; throw error; }
+}
+
+export async function writeJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    await rename(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+// Do not persist browser sessions or cookie paths in retry jobs.
+export function publicOptions(options) {
+  const { cookies, cookiesFromBrowser, profile, urls, url, retryFailed, batchFile, ...safe } = options;
+  return { ...safe, output: path.resolve(options.output) };
+}

package/src/stats.js

@@ -0,0 +1,63 @@
+import { commandOutput } from './output.js';
+import { randomUUID } from 'node:crypto';
+import { readdir, lstat, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { cacheBase } from './paths.js';
+import { readJson, writeJson } from './state.js';
+
+const fields = ['videos', 'audio', 'failed', 'skipped', 'cancelled', 'elapsedMs'];
+const pattern = /^[a-f0-9-]{36}\.json$/;
+const empty = () => Object.fromEntries(fields.map(key => [key, 0]));
+
+export function createStatsRecorder(root = cacheBase()) {
+  const file = path.join(root, 'stats', `${randomUUID()}.json`);
+  const totals = { version: 1, since: new Date().toISOString(), ...empty() };
+  return async delta => {
+    for (const key of fields) totals[key] += delta[key] || 0;
+    await writeJson(file, totals);
+  };
+}
+
+async function statFiles(root) {
+  const directory = path.resolve(root, 'stats');
+  const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!info) return [];
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`Invalid statistics directory: ${directory}`);
+  return (await readdir(directory, { withFileTypes: true }))
+    .filter(entry => entry.isFile() && pattern.test(entry.name)).map(entry => path.join(directory, entry.name));
+}
+
+export async function readStats(root = cacheBase()) {
+  const result = { since: null, ...empty() };
+  for (const file of await statFiles(root)) {
+    const value = await readJson(file, null);
+    if (!value) continue;
+    if (value.version !== 1 || !Number.isFinite(Date.parse(value.since)) || fields.some(key => !Number.isFinite(value[key]) || value[key] < 0)) {
+      throw new Error(`Invalid statistics file: ${file}`);
+    }
+    if (!result.since || value.since < result.since) result.since = value.since;
+    for (const key of fields) result[key] += value[key];
+  }
+  return result;
+}
+
+// Called by flush only after registered runs have stopped and while its gate is held.
+export async function resetStats(root = cacheBase()) {
+  for (const file of await statFiles(root)) await rm(file, { force: true });
+}
+
+export async function statsMain(args = [], { stdout = process.stdout, root = cacheBase() } = {}) {
+  [args, stdout] = commandOutput(args, stdout);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    stdout.write('veo stats [--json]\n\nShow recorded download totals. Time includes preparation, processing and saving,\nincluding failed attempts. Parallel run times are added together.\nStats start with this version; old downloads are not imported.\nUse veo flush --stats to clear temporary data and reset statistics.\n');
+    return 0;
+  }
+  if (args.length && (args.length !== 1 || args[0] !== '--json')) throw new Error('Usage: veo stats [--json]');
+  const stats = await readStats(root);
+  if (args[0] === '--json') stdout.write(`${JSON.stringify(stats)}\n`);
+  else {
+    const seconds = Math.floor(stats.elapsedMs / 1000);
+    stdout.write(`veo stats\n\nTracking since: ${stats.since || 'No downloads recorded yet'}\nVideos saved:   ${stats.videos}\nAudio saved:    ${stats.audio}\nTotal failures: ${stats.failed}\nSkipped:        ${stats.skipped}\nCancelled:      ${stats.cancelled}\nDownload time:  ${Math.floor(seconds / 3600)}h ${Math.floor(seconds / 60) % 60}m ${seconds % 60}s\n\nTime includes preparation, processing and saving. Active requests appear when finished.\n`);
+  }
+  return 0;
+}

package/src/terminal-title.js

@@ -0,0 +1,19 @@
+import { cleanText } from './utils.js';
+
+// PowerShell's console title API on Windows; OSC 0 on xterm-compatible Unix
+// terminals. Never put escape sequences into redirected output or dumb terminals.
+export function createTerminalTitle(stream, { platform = process.platform, env = process.env, processInfo = process } = {}) {
+  let previous;
+  return title => {
+    if (!stream.isTTY || env.TERM === 'dumb') return;
+    const safe = cleanText(title).slice(0, 240);
+    if (safe === previous) return;
+    try {
+      if (platform === 'win32') processInfo.title = safe;
+      else stream.write(`\x1b]0;${safe}\x07`);
+      previous = safe;
+    } catch {
+      // Cosmetic only: a terminal that rejects titles must not break downloads.
+    }
+  };
+}