@mailo037/veo 1.0.0 → 1.0.1

package/README.md

@@ -40,6 +40,8 @@ veo <url> [options]
 
 -q, --quality <quality>   best, 2160p, 1440p, 1080p, 720p, 480p, 360p
 -o, --output <path>       Output directory (default: current working directory)
+-r, --rename <name>       Custom filename without extension (also used in tab title)
+--open                   Open the saved file with your default app
 --audio                  Audio only (MP3 by default)
 --format <format>        Video: mp4, mkv, webm, mov
                          Audio: mp3, m4a, aac, opus, flac, wav
@@ -53,6 +55,8 @@ veo "https://x.com/USER/status/STATUS_ID" -q best
 veo "https://example.com/video.mp4" --audio
 veo "https://example.com/video.mp4" --audio --format flac
 veo "https://example.com/video.mp4" --format webm -o ./videos
+veo "https://example.com/video.mp4" -r "Mein Video" --format mp4 --open
+veo "https://example.com/video.mp4" --audio -r "Meine Musik"
 npx @mailo037/veo "https://example.com/video.mp4" --output ./downloads
 ```
 
@@ -60,11 +64,26 @@ npx @mailo037/veo "https://example.com/video.mp4" --output ./downloads
 - Numeric quality selects the nearest **available video height**, not just a maximum. Ties choose the lower height. Unknown heights fall back to best. `--quality` does not apply to audio.
 - MP4-compatible codecs are preferred at the selected resolution; merged video prefers MP4 with MKV fallback. A single-file source may retain its original container. Use `--format mp4` to explicitly require MP4 (conversion may be slow or lossy).
 - `--format` on video enables conversion when necessary. Audio formats require `--audio`.
-- Original titles are preserved, with invalid filename characters sanitized and overly long names shortened. Existing files are never intentionally overwritten: duplicates get ` (1)`, ` (2)`, etc.
+- Original titles are preserved by default. Use `-r "My Video"` or `--rename "My Video"` to choose a filename for video or audio. Supply the name **without an extension**; the actual media extension is appended automatically. Use `-o` for the directory. Invalid filename characters are sanitized and overly long names shortened. Existing files are never intentionally overwritten: duplicates get ` (1)`, ` (2)`, etc.
+- During a download, the terminal/tab title shows `veo | 50% | My Video` (original title or your `-r` name), plus setup/processing status. It ends with `Done`, `Failed`, or `Cancelled`; the shell may replace it at the next prompt. This uses the native console title on Windows (including PowerShell/Windows Terminal) and OSC title sequences on compatible Linux/macOS terminals. Titles are not changed when stderr is redirected or `TERM=dumb`. Terminal settings that enforce a fixed tab title can override this feature.
 - Downloads and conversion use a private temporary directory inside the output directory. The completed file is copied to a collision-safe final name, so allow extra disk space. Temporary files are removed on ordinary failure or Ctrl+C; force-killing the process may leave `.veo-*` directories to remove manually. Partial downloads are not resumed between invocations.
 - Progress shows percentage, speed, downloaded/total size and ETA on stderr; unknown values appear as `?`. Separate audio/video streams each have their own progress. Non-interactive output is throttled. The final path is printed on stdout as `Saved: ...`.
+- `--open` launches the completed file in your default app, including renamed files and audio. Uses `explorer.exe` on Windows, `open` on macOS, and `xdg-open` on Linux (requires a graphical desktop, xdg-utils and a file association). The CLI does not wait for the player to close. If the opener cannot be launched, a warning is printed and the successful download still exits with `0`; later errors inside the detached opener/player are not monitored.
+- After each successful download, veo checks the npm registry at most once per day for a newer version and prints a one-line notice on stderr (never on failure). Disable it with `VEO_NO_UPDATE_CHECK=1`; `VEO_REGISTRY`/`npm_config_registry` are respected.
 - Exit status is `0` on success, `1` on errors, and `130` on cancellation.
 
+## Updating veo
+
+```bash
+veo update            # install the latest version with npm (global)
+veo update --check    # only check for a newer version
+veo upgrade           # alias for veo update
+veo check update      # alias for veo update --check
+veo update --help     # update usage
+```
+
+`veo update` runs `npm install -g @mailo037/veo@latest` and then removes yt-dlp backend caches from older pinned releases. It never uses a shell on Linux/macOS, passes fixed arguments only, and prints the manual npm command on any failure. The registry can be overridden with `VEO_REGISTRY` (or npm's `npm_config_registry`) for mirrors and proxies.
+
 ## Supported sites and backend
 
 YouTube, X/Twitter, TikTok, Vimeo, Reddit, Instagram, and [many other yt-dlp sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) are supported **when publicly accessible and technically available**. Support changes with websites, regions, rate limits, and backend versions; it is not a guarantee that every URL will work. Authentication/cookie flags are not exposed in this initial version.
@@ -85,6 +104,7 @@ Automatic yt-dlp acquisition covers mainstream Windows, macOS and Linux architec
 ```bash
 npm install
 npm test
+npm run test:open
 npm run test:smoke
 npm pack --dry-run
 npm link

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailo037/veo",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A clean, simple video downloader powered by yt-dlp.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   "scripts": {
     "test": "node --test",
     "test:smoke": "node scripts/smoke.js",
+    "test:open": "node scripts/smoke-open.js",
     "prepublishOnly": "npm test"
   },
   "keywords": [

package/src/cli.js

@@ -1,6 +1,8 @@
 import { parseArgs } from 'node:util';
 import { readFile } from 'node:fs/promises';
 import { createReporter } from './progress.js';
+import { openFile } from './open-file.js';
+import { maybeUpdateNotice, updateMain, UPDATE_HELP, defaultRegistry, packageVersion } from './updater.js';
 import { QUALITIES, VIDEO_FORMATS, AUDIO_FORMATS, validateUrl, readableError, cleanText } from './utils.js';
 
 export const HELP = `veo - simple video downloader
@@ -11,6 +13,8 @@ Usage:
 Options:
   -q, --quality <quality>   Video quality (best, 2160p, 1440p, 1080p, 720p, 480p, 360p)
   -o, --output <path>       Output directory (default: current directory)
+  -r, --rename <name>       Custom filename without extension (also used in tab title)
+  --open                   Open the saved file with your default app
   --audio                  Download audio only (default: mp3)
   --format <format>        Video: mp4, mkv, webm, mov; audio: mp3, m4a, aac, opus, flac, wav
   --version                Show version
@@ -21,6 +25,8 @@ Examples:
   veo <url> -q 1080p
   veo <url> --audio
   veo <url> -o ./downloads
+  veo <url> -r "My Video" --open
+  veo update --check
 
 Only download content you are authorized or legally permitted to download.
 `;
@@ -29,6 +35,8 @@ export function parseCli(args) {
   const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
     quality: { type: 'string', short: 'q', default: 'best' },
     output: { type: 'string', short: 'o', default: process.cwd() },
+    rename: { type: 'string', short: 'r' },
+    open: { type: 'boolean' },
     audio: { type: 'boolean', default: false },
     format: { type: 'string' },
     help: { type: 'boolean', short: 'h' },
@@ -38,6 +46,7 @@ export function parseCli(args) {
   if (positionals.length !== 1) throw new Error('Provide exactly one video URL. Run veo --help for usage.');
   if (!QUALITIES.includes(values.quality)) throw new Error(`Invalid quality. Choose: ${QUALITIES.join(', ')}.`);
   if (!values.output.trim()) throw new Error('The output directory cannot be empty.');
+  if (values.rename !== undefined && !cleanText(values.rename)) throw new Error('The custom filename cannot be empty.');
   if (values.audio && values.quality !== 'best') throw new Error('--quality is for video; omit it when using --audio.');
   const formats = values.audio ? AUDIO_FORMATS : VIDEO_FORMATS;
   if (values.format && !formats.includes(values.format)) throw new Error(`Invalid ${values.audio ? 'audio' : 'video'} format. Choose: ${formats.join(', ')}.${!values.audio && AUDIO_FORMATS.includes(values.format) ? ' Use --audio for audio formats.' : ''}`);
@@ -45,6 +54,14 @@ export function parseCli(args) {
 }
 
 export async function main(args = process.argv.slice(2)) {
+  // update/upgrade/check subcommands are handled before URL validation.
+  if (['update', 'upgrade', 'check'].includes(args[0])) {
+    if (args[0] === 'check' && args[1] !== 'update') {
+      process.stdout.write(UPDATE_HELP);
+      return 0;
+    }
+    return updateMain(args, { registry: defaultRegistry() });
+  }
   const reporter = createReporter();
   const controller = new AbortController();
   const cancel = () => controller.abort();
@@ -58,12 +75,22 @@ export async function main(args = process.argv.slice(2)) {
       process.stdout.write(`${pkg.version}\n`);
       return 0;
     }
+    reporter.start(options.rename);
     const { download } = await import('./downloader.js');
     const saved = await download(options, { signal: controller.signal, reporter });
+    reporter.complete();
     process.stdout.write(`Saved: ${cleanText(saved)}\n`);
+    if (options.open) {
+      try { await openFile(saved); }
+      catch (error) {
+        process.stderr.write(`veo: File saved, but could not launch the default app: ${readableError(error)}\n`);
+      }
+    }
+    const notice = await maybeUpdateNotice({ currentVersion: await packageVersion() });
+    if (notice) process.stderr.write(`${notice}\n`);
     return 0;
   } catch (error) {
-    reporter.finish();
+    reporter.fail(controller.signal.aborted);
     process.stderr.write(`veo: ${readableError(error)}\n`);
     return controller.signal.aborted ? 130 : 1;
   } finally {

package/src/downloader.js

@@ -49,6 +49,8 @@ export async function download(options, { signal, reporter, backendResolver = re
   if (metadata._type === 'playlist' || metadata.entries) throw new Error('This URL is a collection. Please provide a single video URL.');
   if (metadata.is_live) throw new Error('Live streams are not supported. Please use a finished video.');
   if (metadata.has_drm) throw new Error('This content is DRM-protected.');
+  const title = options.rename ?? (metadata.title || metadata.id || 'video');
+  reporter?.name?.(title);
   const height = options.audio ? null : closestHeight(metadata.formats || [metadata], options.quality);
   if (!options.audio && options.quality !== 'best') {
     reporter?.status(height ? `Quality: ${height}p${height !== parseInt(options.quality, 10) ? ` (closest to ${options.quality})` : ''}` : 'Resolution unknown; using the best available stream.');
@@ -79,7 +81,7 @@ export async function download(options, { signal, reporter, backendResolver = re
     saved = path.resolve(saved);
     if (path.dirname(saved) !== temporary || !(await stat(saved)).isFile()) throw new Error('The backend returned an invalid saved file path.');
     signal?.throwIfAborted();
-    return await saveUnique(saved, directory, metadata.title || metadata.id || 'video');
+    return await saveUnique(saved, directory, title);
   } finally {
     reporter?.finish();
     await rm(temporary, { recursive: true, force: true });

package/src/open-file.js

@@ -0,0 +1,14 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+// Pass the absolute filename as one argument, never through a shell. Detach so
+// a media player that stays running does not keep the CLI alive.
+export function openFile(filename, { platform = process.platform, spawnProcess = spawn } = {}) {
+  const command = platform === 'win32' ? 'explorer.exe' : platform === 'darwin' ? 'open' : 'xdg-open';
+  const absolute = path.resolve(filename);
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(command, [absolute], { shell: false, detached: true, stdio: 'ignore', windowsHide: true });
+    child.once('error', reject);
+    child.once('spawn', () => { child.unref(); resolve(); });
+  });
+}

package/src/progress.js

@@ -1,4 +1,5 @@
 import { cleanText } from './utils.js';
+import { createTerminalTitle } from './terminal-title.js';
 
 function bytes(value) {
   if (!Number.isFinite(value) || value < 0) return '?';
@@ -17,16 +18,34 @@ export function formatProgress(data) {
   return `[${'='.repeat(filled)}${'-'.repeat(20 - filled)}] ${percent === null ? '  ?' : percent.toFixed(0).padStart(3)}%  ${bytes(data.speed)}/s  ${bytes(done)} / ${bytes(total)}  ETA ${eta}`;
 }
 
-export function createReporter(stream = process.stderr) {
+export function createReporter(stream = process.stderr, { setTitle = createTerminalTitle(stream) } = {}) {
   let active = false;
   let lastLog = 0;
+  let name = '';
+  let phase = 'Starting…';
+  let started = false;
+  const updateTitle = () => setTitle(`veo | ${phase}${name ? ` | ${name}` : ''}`);
   function clear() {
     if (active && stream.isTTY) stream.write('\r\x1b[2K');
     active = false;
   }
   return {
-    status(message) { clear(); stream.write(`${cleanText(message)}\n`); },
+    start(title = '') { started = true; name = cleanText(title); phase = 'Starting…'; updateTitle(); },
+    name(title) { name = cleanText(title); if (started) updateTitle(); },
+    status(message) {
+      clear();
+      phase = cleanText(message);
+      if (started) updateTitle();
+      stream.write(`${phase}\n`);
+    },
+    complete() { clear(); phase = 'Done'; if (started) updateTitle(); },
+    fail(cancelled = false) { clear(); phase = cancelled ? 'Cancelled' : 'Failed'; if (started) updateTitle(); },
     progress(data) {
+      const total = data.total_bytes || data.total_bytes_estimate;
+      const percent = Number.isFinite(total) && total > 0 && Number.isFinite(data.downloaded_bytes)
+        ? Math.max(0, Math.min(100, Math.round(data.downloaded_bytes / total * 100))) : null;
+      phase = data.status === 'finished' ? 'Processing…' : percent === null ? 'Downloading…' : `${percent}%`;
+      if (started) updateTitle();
       if (stream.isTTY) {
         stream.write(`\r\x1b[2K${formatProgress(data)}`);
         active = true;

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.
+    }
+  };
+}

package/src/updater.js

@@ -0,0 +1,247 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { RELEASE } from './backend.js';
+import { readableError } from './utils.js';
+
+const PACKAGE = '@mailo037/veo';
+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 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 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 base as the yt-dlp backend cache (see src/backend.js).
+export function veoCacheBase({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  let base;
+  if (platform === 'win32') base = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  else if (platform === 'darwin') base = path.join(home, 'Library', 'Caches');
+  else base = env.XDG_CACHE_HOME || path.join(home, '.cache');
+  if (!path.isAbsolute(base)) base = path.join(home, '.cache');
+  return path.join(base, 'veo');
+}
+
+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 current one stays.
+export async function pruneBackendCaches({ keep, root, platform = process.platform, env = process.env } = {}) {
+  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() || entry.name === keep) continue;
+    await rm(path.join(base, entry.name), { recursive: true, force: true });
+    removed++;
+  }
+  return removed;
+}
+
+export function npmSpawnCommand({ platform = process.platform } = {}) {
+  // Fixed arguments only (no user input), so cmd.exe on Windows is safe here.
+  return {
+    command: 'npm',
+    args: ['install', '-g', '--no-fund', '--no-audit', `${PACKAGE}@latest`],
+    shell: platform === 'win32',
+  };
+}
+
+export function runNpmUpdate({ spawnImpl = spawn, platform = process.platform, signal, timeoutMs = 600_000 } = {}) {
+  const { command, args, shell } = npmSpawnCommand({ platform });
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, { shell, 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,
+} = {}) {
+  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 {
+    const removed = await pruneBackendCaches({ keep, 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;
+}