veodl 1.8.1

package/src/tool-setup.js

@@ -0,0 +1,151 @@
+import { spawn } from 'node:child_process';
+import { access, chmod, mkdtemp, realpath, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { cleanText } from './utils.js';
+
+// Only fixed package names and arguments are passed to these installers.
+export function runSetup(command, args, {
+  signal, env = process.env, cwd, status = () => {}, timeoutMs = 600_000,
+} = {}) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      shell: false, windowsHide: true, detached: process.platform !== 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'], env, cwd,
+    });
+    let output = '';
+    let stopped;
+    const stop = error => {
+      if (stopped) return;
+      stopped = error;
+      if (process.platform === 'win32' && child.pid) {
+        const killer = spawn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { shell: false, windowsHide: true, stdio: 'ignore' });
+        killer.on('error', () => child.kill());
+      } else {
+        try { process.kill(-child.pid, 'SIGKILL'); } catch { child.kill('SIGKILL'); }
+      }
+    };
+    const abort = () => stop(signal.reason);
+    const timer = setTimeout(() => stop(new Error('Tool installation timed out. Retry with veo doctor fix.')), timeoutMs);
+    const receive = chunk => {
+      const text = cleanText(String(chunk));
+      output = (output + text).slice(-8192);
+      // Surface package-manager progress without taking over stdin or stdout.
+      for (const line of text.split(/[\r\n]+/)) if (line.trim()) status(line.slice(0, 500));
+    };
+    child.stdout.on('data', receive);
+    child.stderr.on('data', receive);
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); };
+    child.once('error', error => { cleanup(); reject(stopped || error); });
+    child.once('close', code => {
+      cleanup();
+      if (stopped) reject(stopped);
+      else if (code !== 0) reject(new Error(`${path.basename(command)} exited with code ${code}: ${output.trim()}`));
+      else resolve(output);
+    });
+  });
+}
+
+export async function hasTermuxEjs({ find, run = runSetup, signal }) {
+  const python = await find(['python', 'python3']);
+  if (!python) return false;
+  try {
+    await run(python, ['-B', '-c', 'import yt_dlp_ejs'], { signal, timeoutMs: 15_000 });
+    return true;
+  } catch {
+    signal?.throwIfAborted();
+    return false;
+  }
+}
+
+let termuxInstall;
+export async function installTermuxTools({ find, signal, status, run = runSetup, env = process.env }) {
+  if (termuxInstall) {
+    await termuxInstall;
+    signal?.throwIfAborted();
+    return;
+  }
+  termuxInstall = (async () => {
+    const pkg = await find(['pkg']);
+    if (!pkg) throw new Error('Automatic Android setup requires Termux with pkg on PATH. Install python-yt-dlp, yt-dlp-ejs and ffmpeg in Termux.');
+    signal?.throwIfAborted();
+    status('Installing yt-dlp, JavaScript support and FFmpeg with Termux pkg (first use)…');
+    // pkg refreshes mirrors/package lists itself. No full system upgrade or sudo.
+    await run(pkg, ['install', env.TERMUX_APP_PACKAGE_MANAGER === 'pacman' ? '--noconfirm' : '-y', 'python-yt-dlp', 'yt-dlp-ejs', 'ffmpeg'], {
+      signal, status, env: { ...env, DEBIAN_FRONTEND: 'noninteractive' },
+    });
+  })();
+  try { await termuxInstall; }
+  catch (cause) {
+    signal?.throwIfAborted();
+    throw new Error(`Automatic Termux setup failed: ${cause.message}. Retry with veo doctor fix; if the repository needs repair, run pkg update in Termux.`, { cause });
+  } finally { termuxInstall = undefined; }
+}
+
+export function mediaPackagePlan(platform = process.platform, arch = process.arch) {
+  // Windows 11 ARM runs the upstream x64 media tools via OS emulation.
+  const binaryArch = platform === 'win32' && arch === 'arm64' ? 'x64' : arch;
+  const versions = {
+    'win32-x64': '5.1.0', 'win32-ia32': '5.1.0',
+    'darwin-x64': '5.1.0', 'darwin-arm64': '5.0.1',
+    'linux-x64': '5.2.0', 'linux-ia32': '5.2.0', 'linux-arm64': '5.2.0', 'linux-arm': '5.2.0',
+  };
+  const target = `${platform}-${binaryArch}`;
+  if (!versions[target]) return undefined;
+  return { binaryArch, probePackage: `@ffprobe-installer/${target}`, probeVersion: versions[target] };
+}
+
+async function npmCli(find, env) {
+  const npm = await find(['npm']);
+  const candidates = [
+    env.npm_execpath,
+    npm && await realpath(npm).catch(() => undefined),
+    npm && path.join(path.dirname(npm), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.resolve(path.dirname(process.execPath), '../lib/node_modules/npm/bin/npm-cli.js'),
+  ];
+  for (const candidate of candidates) {
+    if (!candidate || path.basename(candidate) !== 'npm-cli.js') continue;
+    if (await stat(candidate).then(info => info.isFile(), () => false)) return candidate;
+  }
+  throw new Error('npm was not found. Install Node.js with npm, then run veo doctor fix.');
+}
+
+export async function installMediaTools({
+  directory, find, stage, signal, status, platform = process.platform, arch = process.arch,
+  env = process.env, run = runSetup, locateNpm = npmCli,
+}) {
+  const plan = mediaPackagePlan(platform, arch);
+  if (!plan) throw new Error(`Automatic FFmpeg setup is unavailable for ${platform}/${arch}. Set VEO_FFMPEG_PATH to a directory containing ffmpeg and ffprobe.`);
+  const cli = await locateNpm(find, env);
+  const temporary = await mkdtemp(path.join(directory, '.media-setup-'));
+  const suffix = platform === 'win32' ? '.exe' : '';
+  try {
+    status('Downloading FFmpeg and FFprobe into the veo cache (first use)…');
+    // This is a private throwaway project, never the global package or cwd.
+    // Ignore dependency scripts; invoke the pinned ffmpeg installer explicitly.
+    const args = [cli, 'install', '--prefix', temporary, '--no-save', '--package-lock=false', '--ignore-scripts', '--no-audit', '--no-fund', '--global=false', 'ffmpeg-static@5.3.0', `${plan.probePackage}@${plan.probeVersion}`];
+    if (platform === 'win32' && arch === 'arm64') args.push('--force');
+    await run(process.execPath, args, { signal, status, cwd: temporary, env });
+    const modules = path.join(temporary, 'node_modules');
+    await run(process.execPath, [path.join(modules, 'ffmpeg-static', 'install.js')], {
+      signal, status, cwd: temporary,
+      env: { ...env, npm_config_platform: platform, npm_config_arch: plan.binaryArch, FFMPEG_BIN: '', FFMPEG_BINARY_RELEASE: 'b6.1.1' },
+    });
+    const ffmpeg = path.join(modules, 'ffmpeg-static', `ffmpeg${suffix}`);
+    const ffprobe = path.join(modules, ...plan.probePackage.split('/'), `ffprobe${suffix}`);
+    for (const file of [ffmpeg, ffprobe]) {
+      await access(file);
+      if (process.platform !== 'win32') await chmod(file, 0o755);
+      await run(file, ['-version'], { signal, timeoutMs: 15_000 });
+    }
+    await stage(ffmpeg, path.join(directory, `ffmpeg${suffix}`), signal);
+    await stage(ffprobe, path.join(directory, `ffprobe${suffix}`), signal);
+    return directory;
+  } catch (cause) {
+    signal?.throwIfAborted();
+    throw new Error(`Automatic FFmpeg setup failed: ${cause.message}. Retry with veo doctor fix or set VEO_FFMPEG_PATH to installed tools.`, { cause });
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}

package/src/updater.js

@@ -0,0 +1,227 @@
+import { commandOutput } from './output.js';
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { RELEASE, readBackendOverride } from './backend.js';
+import { cacheBase } from './paths.js';
+import { compareVersions } from './version.js';
+import { readableError } from './utils.js';
+
+export { compareVersions };
+
+const PACKAGE = 'veodl';
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export const UPDATE_HELP = `veo update - keep veo current
+
+Usage:
+  veo update               Install the latest version with npm
+  veo update --check       Only check whether a newer version exists
+  veo upgrade              Alias for veo update
+  veo check update         Alias for veo update --check
+
+The registry can be overridden with VEO_REGISTRY (or npm_config_registry).
+Set VEO_NO_UPDATE_CHECK=1 to disable the automatic post-download check.
+`;
+
+export function defaultRegistry(env = process.env) {
+  const registry = env.VEO_REGISTRY || env.npm_config_registry;
+  if (typeof registry === 'string' && /^https?:\/\//.test(registry.trim())) return registry.trim().replace(/\/+$/, '');
+  return 'https://registry.npmjs.org';
+}
+
+export async function fetchLatestVersion({ registry = defaultRegistry(), fetchImpl = fetch, timeoutMs = 8000, signal } = {}) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const url = `${registry}/${encodeURIComponent(PACKAGE)}`;
+  const response = await fetchImpl(url, {
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+    headers: { accept: 'application/json' },
+  });
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(`Update check failed: HTTP ${response.status}.`);
+  }
+  const data = await response.json();
+  // Full packument: pick the highest version instead of trusting the "latest" tag.
+  const versions = data?.versions ? Object.keys(data.versions) : [data?.version].filter(Boolean);
+  if (!versions.length) throw new Error('Update check returned no versions.');
+  const [latest] = versions.sort((a, b) => compareVersions(b, a));
+  const version = typeof latest === 'string' ? latest : '';
+  if (!/^\d+\.\d+\.\d+/.test(version)) throw new Error('Update check returned an invalid version.');
+  return version;
+}
+
+// Same OS cache root as the yt-dlp backend cache (see src/paths.js).
+export function veoCacheBase(options) {
+  return cacheBase(options);
+}
+
+export async function readState(stateFile) {
+  try {
+    const state = JSON.parse(await readFile(stateFile, 'utf8'));
+    return Number.isFinite(state?.lastCheck) ? state : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeState(stateFile, state) {
+  await mkdir(path.dirname(stateFile), { recursive: true, mode: 0o700 });
+  await writeFile(stateFile, JSON.stringify(state), { mode: 0o600 });
+}
+
+// Throttled (once per day) post-download check. Purely informational; every
+// failure is silent so downloads are never delayed or marked as failed.
+export async function maybeUpdateNotice({
+  currentVersion,
+  env = process.env,
+  stateFile,
+  fetchImpl = fetch,
+  registry,
+  now = Date.now(),
+  ttlMs = DAY_MS,
+  timeoutMs = 4000,
+} = {}) {
+  if (env.VEO_NO_UPDATE_CHECK) return null;
+  try {
+    if (!stateFile) stateFile = path.join(veoCacheBase({ env }), 'update-check.json');
+    const state = await readState(stateFile);
+    if (state && now - state.lastCheck < ttlMs) return null;
+  } catch {
+    return null; // No usable cache location: never turn a notice into noise.
+  }
+  let latest = null;
+  let message = null;
+  try {
+    latest = await fetchLatestVersion({ fetchImpl, registry, timeoutMs });
+    if (compareVersions(latest, currentVersion) > 0) {
+      message = `Update available: veo ${latest} (you have ${currentVersion}). Run: veo update`;
+    }
+  } catch {
+    latest = null; // Unreachable registry still consumes the throttle interval.
+  }
+  await writeState(stateFile, { lastCheck: now, latest }).catch(() => {});
+  return message;
+}
+
+// Removes yt-dlp caches from older pinned releases; only the releases still in
+// use stay (the pinned one plus an explicitly installed newer backend).
+export async function pruneBackendCaches({ keep, extra = [], root, platform = process.platform, env = process.env } = {}) {
+  const retained = new Set([keep, ...extra].filter(Boolean));
+  const base = root || path.join(veoCacheBase({ platform, env }), 'backends');
+  let entries;
+  try {
+    entries = await readdir(base, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return 0;
+    throw error;
+  }
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || retained.has(entry.name)) continue;
+    await rm(path.join(base, entry.name), { recursive: true, force: true });
+    removed++;
+  }
+  return removed;
+}
+
+export function npmSpawnCommand({ platform = process.platform } = {}) {
+  const args = ['install', '-g', '--no-fund', '--no-audit', `${PACKAGE}@latest`];
+  // npm.cmd needs cmd.exe on Windows. Pass a fixed command explicitly instead
+  // of Node's deprecated shell:true + args combination (DEP0190).
+  // Never interpolate user input into this command string.
+  if (platform === 'win32') return {
+    command: 'cmd.exe',
+    args: ['/d', '/s', '/c', `npm ${args.join(' ')}`],
+    shell: false,
+    windowsVerbatimArguments: true,
+  };
+  return {
+    command: 'npm',
+    args,
+    shell: false,
+  };
+}
+
+export function runNpmUpdate({ spawnImpl = spawn, platform = process.platform, signal, timeoutMs = 600_000 } = {}) {
+  const { command, args, ...spawnOptions } = npmSpawnCommand({ platform });
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, { ...spawnOptions, stdio: 'inherit', windowsHide: true, signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs) });
+    child.once('error', reject);
+    child.once('close', resolve);
+  });
+}
+
+export async function packageVersion() {
+  const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  return pkg.version;
+}
+
+/**
+ * Implements `veo update [--check]`, `veo upgrade`, and `veo check update`.
+ * Returns the process exit code. Deps are injectable for tests.
+ */
+export async function updateMain(args, {
+  registry = defaultRegistry(),
+  fetchImpl = fetch,
+  spawnImpl = spawn,
+  platform = process.platform,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  current,
+  keep = RELEASE,
+  pruneRoot = undefined,
+  activeBackend,
+} = {}) {
+  [args, stdout, stderr] = commandOutput(args, stdout, stderr);
+  current = current ?? await packageVersion();
+  const isCheckCommand = args[0] === 'check';
+  const rest = isCheckCommand ? args.slice(2) : args.slice(1);
+  if (rest.includes('-h') || rest.includes('--help')) {
+    stdout.write(UPDATE_HELP);
+    return 0;
+  }
+  const checkOnly = isCheckCommand || rest.includes('--check') || (rest.length === 1 && rest[0] === 'check');
+  const unknown = rest.filter(token => token !== '--check' && !(checkOnly && token === 'check'));
+  if (unknown.length) throw new Error(`Unknown option for veo update: ${unknown.join(' ')}. Use: veo update [--check]`);
+  const currentText = `veo ${current}`;
+  let latest;
+  try {
+    latest = await fetchLatestVersion({ registry, fetchImpl, timeoutMs: 10_000 });
+  } catch (error) {
+    stderr.write(`veo: ${readableError(error)}\nUpdate manually with: npm install -g ${PACKAGE}@latest\n`);
+    return 1;
+  }
+  const newer = compareVersions(latest, current) > 0;
+  if (checkOnly) {
+    stdout.write(newer ? `Update available: veo ${latest} (you have ${current}). Run: veo update\n` : `${currentText} is up to date.\n`);
+    return 0;
+  }
+  if (newer) {
+    stdout.write(`Updating ${currentText} → ${latest} with npm…\n`);
+    let code;
+    try {
+      code = await runNpmUpdate({ spawnImpl, platform, signal: AbortSignal.timeout(600_000) });
+    } catch (error) {
+      const reason = error.code === 'ENOENT' ? 'npm was not found. Install Node.js/npm, or update manually.' : `Could not run npm: ${readableError(error)}`;
+      stderr.write(`veo: ${reason}\nManual command: npm install -g ${PACKAGE}@latest\n`);
+      return 1;
+    }
+    if (code !== 0) {
+      stderr.write(`veo: npm exited with code ${code}. Update manually with: npm install -g ${PACKAGE}@latest\n`);
+      return 1;
+    }
+    stdout.write(`veo updated to ${latest}. The next veo call uses the new version.\n`);
+  } else {
+    stdout.write(`${currentText} is up to date.\n`);
+  }
+  try {
+    // An explicitly installed backend release must survive the pruning.
+    const installed = activeBackend !== undefined ? activeBackend : (await readBackendOverride())?.release;
+    const removed = await pruneBackendCaches({ keep, extra: [installed], root: pruneRoot });
+    if (removed) stdout.write(`Removed ${removed} old backend cache${removed === 1 ? '' : 's'}.\n`);
+  } catch {
+    // Cosmetic housekeeping must never fail the update.
+  }
+  return 0;
+}

package/src/utils.js

@@ -0,0 +1,208 @@
+import path from 'node:path';
+import { copyFile, link, lstat, unlink } from 'node:fs/promises';
+import { accessSync, constants, statSync } from 'node:fs';
+
+export const QUALITIES = ['best', '2160p', '1440p', '1080p', '720p', '480p', '360p'];
+export const VIDEO_FORMATS = ['mp4', 'mkv', 'webm', 'mov'];
+export const AUDIO_FORMATS = ['mp3', 'm4a', 'aac', 'opus', 'flac', 'wav'];
+// Browsers yt-dlp can read cookies from. veo only forwards the choice; it never
+// decrypts or copies cookie stores itself.
+export const COOKIE_BROWSERS = ['brave', 'chrome', 'chromium', 'edge', 'firefox', 'opera', 'safari', 'vivaldi', 'whale'];
+const COOKIE_KEYRINGS = ['gnomekeyring', 'kwallet', 'basic'];
+
+export function validateUrl(input) {
+  try {
+    const url = new URL(input);
+    if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password) throw new Error();
+    return url.href;
+  } catch {
+    throw new Error('Invalid URL. Use a complete http:// or https:// video URL without embedded credentials.');
+  }
+}
+
+// Untrusted site titles must never become paths, terminal escapes, or device names.
+export function sanitizeTitle(title) {
+  let name = String(title || 'video').normalize('NFC')
+    .replace(/[<>:"/\\|?*\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, '_')
+    .trim().replace(/[. ]+$/g, '');
+  if (/^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(name)) name = `_${name}`;
+  let shortened = '';
+  for (const char of name) {
+    if (Buffer.byteLength(shortened + char) > 180) break;
+    shortened += char;
+  }
+  return shortened.replace(/[. ]+$/g, '') || 'video';
+}
+
+export function cleanText(value) {
+  return String(value).replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ').trim();
+}
+
+/** Locale-independent local timestamp for CLI output, e.g. "2026-02-03 14:22". */
+export function localStamp(value) {
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) return 'unknown';
+  const pad = number => String(number).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/**
+ * Validate a Netscape-format cookie file before any network work starts, so a
+ * typo fails immediately instead of after backend acquisition. The file is only
+ * read by the backend; veo never parses or stores its contents.
+ */
+export function validateCookieFile(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) throw new Error('--cookies requires the path to a Netscape-format cookie file.');
+  if (raw.includes('\0')) throw new Error('The cookie file path contains an invalid character.');
+  const file = path.resolve(raw);
+  let info;
+  try {
+    info = statSync(file);
+  } catch {
+    throw new Error(`The cookie file does not exist: ${file}`);
+  }
+  if (!info.isFile()) throw new Error(`The cookie file is not a regular file: ${file}`);
+  try {
+    accessSync(file, constants.R_OK);
+  } catch {
+    throw new Error(`The cookie file is not readable: ${file}`);
+  }
+  return file;
+}
+
+// yt-dlp syntax: BROWSER[+KEYRING][:PROFILE][::CONTAINER]
+export function validateBrowserSpec(input) {
+  const value = cleanText(input).trim();
+  if (!value) throw new Error('--cookies-from-browser requires a browser name.');
+  const [head, container, ...extraContainers] = value.split('::');
+  if (extraContainers.length) throw new Error('--cookies-from-browser accepts at most BROWSER[:PROFILE][::CONTAINER].');
+  const [browserPart, profile, ...extraProfiles] = head.split(':');
+  if (extraProfiles.length) throw new Error('--cookies-from-browser accepts at most BROWSER[:PROFILE][::CONTAINER].');
+  const [name, keyring, ...extraKeyrings] = browserPart.split('+');
+  if (!COOKIE_BROWSERS.includes(name.toLowerCase())) {
+    throw new Error(`Unsupported browser for --cookies-from-browser. Choose: ${COOKIE_BROWSERS.join(', ')}.`);
+  }
+  if (extraKeyrings.length) throw new Error('At most one keyring may follow "+" in --cookies-from-browser.');
+  if (keyring && !COOKIE_KEYRINGS.includes(keyring.toLowerCase())) {
+    throw new Error(`Unsupported keyring for --cookies-from-browser. Choose: ${COOKIE_KEYRINGS.join(', ')}.`);
+  }
+  for (const [label, part] of [['profile', profile], ['container', container]]) {
+    if (part === undefined) continue;
+    if (!part.trim() || cleanText(part) !== part.trim() || part.trim().startsWith('-')) {
+      throw new Error(`The --cookies-from-browser ${label} is empty or contains invalid characters.`);
+    }
+  }
+  return value;
+}
+
+// A cookie file readable by other accounts is a credential leak worth one line.
+export function cookieFileWarning(file, { platform = process.platform, stat = statSync } = {}) {
+  if (!file || platform === 'win32') return null;
+  try {
+    if ((stat(file).mode & 0o077) !== 0) return `Warning: ${file} is readable by other users. Restrict it with: chmod 600 "${file}"`;
+  } catch { /* The file was validated earlier; a race here is not worth reporting. */ }
+  return null;
+}
+
+// Video heights a site actually offers, ignoring audio-only and DRM entries.
+export function availableHeights(formats) {
+  return [...new Set((formats || [])
+    .filter(format => format && format.vcodec !== 'none' && !format.has_drm && Number.isFinite(format.height) && format.height > 0)
+    .map(format => format.height))];
+}
+
+export function closestHeight(formats, quality) {
+  if (quality === 'best') return null;
+  const target = Number.parseInt(quality, 10);
+  // Equidistant alternatives prefer the smaller download.
+  return availableHeights(formats).sort((a, b) => Math.abs(a - target) - Math.abs(b - target) || a - b)[0] ?? null;
+}
+
+/** The highest offered resolution at or below the request, or undefined. */
+export function cappedHeight(formats, quality) {
+  const target = Number.parseInt(quality, 10);
+  return availableHeights(formats).filter(height => height <= target).sort((a, b) => b - a)[0];
+}
+
+// Filesystems without hard links (FAT/exFAT, some SMB and container mounts)
+// report one of these; anything else is a real error and must surface.
+const NO_HARDLINK = new Set(['EXDEV', 'EPERM', 'EACCES', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EMLINK', 'EINVAL']);
+
+/**
+ * Occupy `destination` without ever replacing an existing file. Returns false
+ * when the name is taken. Local staging can be on another drive, so a hard
+ * link is an O(1) metadata operation when supported; cross-drive saves and
+ * filesystems that cannot link fall back to copying. Both paths are race-safe
+ * against concurrent veo processes.
+ */
+export async function allocate(source, destination, { linkImpl = link, copyImpl = copyFile } = {}) {
+  try {
+    await linkImpl(source, destination);
+    return true;
+  } catch (error) {
+    if (error.code === 'EEXIST') return false;
+    if (error.code === 'EISDIR') {
+      // Some virtual drives report EISDIR for unsupported hard links even when
+      // the source is a regular file. Do not mistake a real directory for media.
+      if (!(await lstat(source)).isFile()) throw error;
+      const existing = await lstat(destination).catch(problem => {
+        if (problem.code === 'ENOENT') return null;
+        throw problem;
+      });
+      if (existing) return false;
+    } else if (!NO_HARDLINK.has(error.code)) throw error;
+  }
+  try {
+    await copyImpl(source, destination, constants.COPYFILE_EXCL);
+    const [sourceInfo, destinationInfo] = await Promise.all([lstat(source), lstat(destination)]);
+    if (sourceInfo.size !== destinationInfo.size) {
+      await unlink(destination);
+      throw new Error('The saved copy has an unexpected size. The local original has been preserved.');
+    }
+    return true;
+  } catch (error) {
+    if (error.code === 'EEXIST') return false;
+    throw error;
+  }
+}
+
+export async function saveUnique(source, directory, title, { signal, keepSource = false } = {}) {
+  const extension = path.extname(source).toLowerCase();
+  if (!/^\.[a-z0-9]{1,8}$/.test(extension)) throw new Error('The backend returned an invalid output extension.');
+  const name = sanitizeTitle(title);
+  for (let number = 0; ; number++) {
+    signal?.throwIfAborted();
+    const destination = path.join(directory, `${name}${number ? ` (${number})` : ''}${extension}`);
+    if (!await allocate(source, destination)) continue;
+    // The destination keeps the content, so a failing unlink only leaves a
+    // second name that the caller's staging cleanup removes.
+    if (!keepSource) await unlink(source).catch(() => {});
+    return destination;
+  }
+}
+
+export function readableError(error) {
+  if (error.name === 'AbortError') return 'Cancelled.';
+  if (error.code === 'EACCES' || error.code === 'EPERM') return 'Permission denied. Choose a writable output directory or check executable permissions.';
+  if (error.code === 'ENOSPC') return 'Not enough disk space to save the download.';
+  const text = cleanText(error.message || error);
+  if (/did not get any data blocks/i.test(text)) return 'The media stream returned no data (yt-dlp: Did not get any data blocks). The download is not confirmed complete. Retry the download; if it persists, update the backend with veo backend update.';
+  if (/unsupported url|no suitable extractor/i.test(text)) return 'This URL or website is not supported by the downloading backend.';
+  if (/private|login required|sign in|log in|authentication|members.only|not a bot|cookies/i.test(text)) return 'This content is private or requires authentication. veo does not bypass access controls. If you are authorized to view it, pass your own session with --cookies <file> or --cookies-from-browser <browser>.';
+  if (/deleted|removed|no longer available|404|not found|does not exist/i.test(text)) return 'The content was deleted, removed, or could not be found.';
+  if (/could not write header|only vp8 or vp9 or av1|not supported in container|could not find tag/i.test(text)) return 'The selected codecs do not fit this container. Try --format mkv for lossless output, or add --recode to explicitly convert (may lose quality).';
+  if (/requested format|no video formats|no suitable formats|conversion failed|error opening encoder|could not find tag/i.test(text)) return 'The requested format is unavailable or could not be converted. Try -q best or another --format.';
+  if (/drm.protected|digital rights/i.test(text)) return 'This content is DRM-protected. veo does not remove DRM.';
+  const http = text.match(/HTTP(?: Error)?\s*:?\s*(403|429|5\d\d)\b/i)?.[1];
+  if (http === '403') return 'HTTP 403 Forbidden: the server refused the media download. The video page may still be accessible. Try veo backend update and retry.';
+  if (http === '429') return 'HTTP 429 Too Many Requests: the server is rate-limiting downloads. Wait before retrying.';
+  if (http) return `HTTP ${http}: the server failed to handle the download. Try again later.`;
+  if (/network|timed? ?out|connection|resolve|ENOTFOUND|ECONN|fetch failed/i.test(text)) {
+    const detail = text.match(/\b(?:ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ETIMEDOUT)\b/i)?.[0]
+      || (/timed? ?out/i.test(text) ? 'request timed out' : /connection reset/i.test(text) ? 'connection reset' : 'connection failed');
+    return `Network request failed (${detail}). Check your connection and try again later.`;
+  }
+  if (/not available|unavailable|geo.?restrict|country/i.test(text)) return 'This content is unavailable or restricted in your region.';
+  return text.slice(-1200) || 'Download failed. Please try again.';
+}

package/src/version.js

@@ -0,0 +1,38 @@
+// Shared semver-ish comparison for veo releases and yt-dlp release dates.
+export function compareVersions(a, b) {
+  const parse = value => {
+    const [core, pre = ''] = String(value).trim().replace(/^v/, '').split('-');
+    if (!/^\d+(\.\d+)*$/.test(core)) throw new Error(`Invalid version: ${value}`);
+    // Semver prerelease identifiers compare per segment, numerically when numeric.
+    return { parts: core.split('.').map(Number), pre: pre === '' ? [] : pre.split('.') };
+  };
+  const left = parse(a);
+  const right = parse(b);
+  for (let index = 0; index < Math.max(left.parts.length, right.parts.length); index++) {
+    const difference = (left.parts[index] || 0) - (right.parts[index] || 0);
+    if (difference) return Math.sign(difference);
+  }
+  // A release outranks any prerelease of the same core version.
+  if (!left.pre.length && !right.pre.length) return 0;
+  if (!left.pre.length) return 1;
+  if (!right.pre.length) return -1;
+  for (let index = 0; index < Math.max(left.pre.length, right.pre.length); index++) {
+    const l = left.pre[index];
+    const r = right.pre[index];
+    if (l === undefined) return -1;
+    if (r === undefined) return 1;
+    const lNumeric = /^\d+$/.test(l);
+    const rNumeric = /^\d+$/.test(r);
+    if (lNumeric && rNumeric) {
+      const difference = Number(l) - Number(r);
+      if (difference) return Math.sign(difference);
+    } else if (lNumeric) return -1; // Numeric identifiers rank below alphanumerics.
+    else if (rNumeric) return 1;
+    else if (l !== r) return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+export function isNewer(candidate, current) {
+  return compareVersions(candidate, current) > 0;
+}