veodl 1.8.1

package/bin/veo.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+process.exitCode = await main();

package/docs/AGENT_GUIDE.md

@@ -0,0 +1,66 @@
+# veo for agents
+
+veo is a command-line video downloader. Use it only for content the user is authorized to download. This guide covers the stable command flow and the difference between download state, media tracks and measured audio signal.
+
+## Fast path
+
+```sh
+veo "https://example.com/video" --dry-run --json
+veo "https://example.com/video" --json --output ./downloads
+veo inspect "./downloads/video.mp4" --check-audio --json
+```
+
+Set `VEO_NO_UPDATE_CHECK=1` when a background update notice would distract a script. Use an explicit output directory to avoid depending on the agent's current working directory. `--dry-run` plans the download without saving media. It can still inspect the source and prepare backend tools on first use.
+
+## Output and failures
+
+Download commands write **one JSON object per URL** to stdout with `--json`. Several URLs produce newline-delimited JSON, not a JSON array. Progress, summaries and errors go to stderr. A failed item can still contain saved files, especially within a playlist.
+
+Example success:
+
+```json
+{"url":"https://example.com/video","status":"saved","title":"Example","files":["/downloads/Example.mp4"],"runId":"abc123"}
+```
+
+Example failure:
+
+```json
+{"url":"https://example.com/video","status":"failed","error":"HTTP Error 429","files":[]}
+```
+
+These are abbreviated examples; fields such as timing and playlist counts may also be present. Exit code `0` means the command succeeded, `1` means at least one item failed, and `130` means cancellation. Validate both the exit code and each result's `status`; a command can fail before producing any stdout JSON. Never infer success from the presence of a file path alone.
+
+## Inspect runs and results
+
+```sh
+veo runs --json
+veo runs k3f9qa --json
+veo history --failed --limit 20 --json
+veo retry --last --json
+```
+
+`runs` reports **active** runs, including their ID, state, options, job path and per-item progress. Completed runs disappear from this list. Download JSON and `history` retain the `runId`. `history` reports finished attempts with their outcome and saved file paths. A failed history entry may contain a `job` path, which can be passed to `veo --retry-failed "<job-path>"`; `veo retry --last` finds the newest retryable job automatically. Running jobs are excluded from `retry --last`.
+
+## Inspect saved media and audio
+
+```sh
+veo inspect "/downloads/Example.mp4" --json
+veo inspect "/downloads/Example.mp4" --check-audio --json
+veo inspect run abc123 --check-audio --json
+veo inspect run abc123 --search "/moved/videos" --json
+```
+
+`inspect` uses local FFprobe/FFmpeg and never downloads a URL. Its JSON contains `format`, `durationSeconds`, `sizeBytes`, `streams`, `hasAudioTrack` and `hasVideoTrack`. Without `--check-audio`, `audioCheck` is `null`.
+
+With `--check-audio`, veo decodes every audio track from start to end. `audioCheck.hasSignal` is true when at least one track's peak exceeds **−60 dBFS**. `audioCheck.tracks` lists each track's `streamIndex`, `maxDbfs` and `hasSignal`; digital silence may have `maxDbfs: null` or a very low level after conversion. A present audio track does not prove audible content. This is a signal-level check, not a listening or speech-quality test. Decoding long media can take time; if FFmpeg fails, the command exits nonzero instead of reporting silence.
+
+`inspect run` reads the saved run record even after the download finishes. It checks whether each file still exists **before** probing it. If a media file was renamed, veo searches the original output tree using file identity, size and a three-part SHA-256 fingerprint. `--search` adds one more directory after a move. Missing or ambiguous matches are reported without probing a different file; missing files make the command exit with code `1`. The fingerprint lives in veo's run history, so this works across media formats without rewriting the media. Runs created before this feature do not have a persistent run record.
+
+The run record is stored in veo's per-user cache on the device that ran the download. `inspect` works on Windows, macOS, Linux and Termux with locally available FFmpeg/FFprobe; set `VEO_FFMPEG_PATH` to their directory when they are not on the normal search path. Moving only the media to another device does not transfer the run record.
+
+## Operational notes
+
+- Run `veo doctor --offline` to check the local setup without network repair. `veo doctor fix` may install missing tools.
+- Use `--resume` for interrupted downloads and `--skip-existing` when repeated saves should be avoided.
+- `veo flush` removes temporary downloads and retry jobs; do not run it as routine maintenance in an agent workflow.
+- Do not call bare `veo` in an interactive terminal from automation: it opens a wizard. Use explicit URLs and flags.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "veodl",
+  "version": "1.8.1",
+  "description": "A clean, simple video downloader powered by yt-dlp.",
+  "type": "module",
+  "bin": {
+    "veo": "bin/veo.js",
+    "veod": "bin/veo.js",
+    "veodl": "bin/veo.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:smoke": "node scripts/smoke.js",
+    "test:open": "node scripts/smoke-open.js",
+    "check:package": "node scripts/check-package.js",
+    "prepublishOnly": "npm test",
+    "test:workflows": "node scripts/smoke-workflows.js"
+  },
+  "keywords": [
+    "cli",
+    "video",
+    "downloader",
+    "yt-dlp",
+    "audio",
+    "youtube",
+    "playlist",
+    "subtitles"
+  ],
+  "license": "MIT",
+  "author": "Mailo037",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mailo037/veo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mailo037/veo/issues"
+  },
+  "homepage": "https://github.com/Mailo037/veo#readme",
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "ffmpeg-static": "5.3.0",
+    "ffprobe-static": "3.1.0"
+  }
+}

package/src/backend-update.js

@@ -0,0 +1,191 @@
+import { commandOutput } from './output.js';
+import path from 'node:path';
+import { rm } from 'node:fs/promises';
+import {
+  RELEASE, activeOverride, backendCacheDirectory, clearBackendOverride, installBackend,
+  isValidRelease, readBackendOverride, releaseUrl, selectAsset, writeBackendOverride,
+} from './backend.js';
+import { compareVersions } from './version.js';
+import { readableError, cleanText } from './utils.js';
+
+const API_LATEST = 'https://api.github.com/repos/yt-dlp/yt-dlp/releases/latest';
+const CHECKSUMS = 'SHA2-256SUMS';
+
+export const BACKEND_HELP = `veo backend - manage the yt-dlp backend
+
+Usage:
+  veo backend update          Install the newest yt-dlp release
+  veo backend update --check  Only report whether a newer release exists
+  veo backend reset           Forget the installed release and use the pinned one
+  veo backend reset --keep-files
+                              Remove the pointer but keep the downloaded files
+  veo backend --help          Show this help
+
+veo ships a pinned, hash-verified yt-dlp release. \`veo backend update\` is an
+opt-in escape hatch for when a website changed and the pinned release is too old:
+it installs the newest official release after verifying its SHA-256 against that
+release's own SHA2-256SUMS file over HTTPS.
+
+That checksum does not ship with veo, so this weakens the pinned-hash guarantee:
+it then rests on HTTPS and GitHub alone. \`veo backend reset\` returns to the
+release veo was built and tested against. VEO_YT_DLP_PATH always wins over both.
+`;
+
+export async function fetchLatestBackendRelease({ fetchImpl = fetch, timeoutMs = 10_000, signal } = {}) {
+  const response = await fetchImpl(API_LATEST, {
+    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+    headers: { accept: 'application/vnd.github+json', 'user-agent': 'veo' },
+  });
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(`Could not query the latest yt-dlp release: HTTP ${response.status}.`);
+  }
+  const data = await response.json();
+  const tag = data?.tag_name;
+  if (!isValidRelease(tag)) throw new Error(`The release host returned an unexpected version: ${cleanText(String(tag))}`);
+  return tag;
+}
+
+/** Parse an official SHA2-256SUMS file into a name -> hash map. */
+export function parseChecksums(text) {
+  const hashes = new Map();
+  for (const line of String(text).split('\n')) {
+    const match = /^([a-f0-9]{64})\s+\*?(.+?)\s*$/i.exec(line.trim());
+    if (match) hashes.set(path.basename(match[2]), match[1].toLowerCase());
+  }
+  if (!hashes.size) throw new Error('The release checksum list could not be parsed.');
+  return hashes;
+}
+
+export async function fetchReleaseChecksum({ release, asset, fetchImpl = fetch, timeoutMs = 15_000, signal }) {
+  if (!isValidRelease(release)) throw new Error(`Invalid yt-dlp release: ${release}`);
+  const response = await fetchImpl(releaseUrl(release, CHECKSUMS), {
+    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(`Could not download ${CHECKSUMS} for yt-dlp ${release}: HTTP ${response.status}.`);
+  }
+  const hash = parseChecksums(await response.text()).get(asset);
+  if (!hash) throw new Error(`yt-dlp ${release} does not publish a checksum for ${asset}.`);
+  return hash;
+}
+
+export function muslDetected() {
+  return process.platform === 'linux' && !process.report.getReport().header.glibcVersionRuntime;
+}
+
+export async function checkBackend({
+  platform = process.platform,
+  arch = process.arch,
+  musl = muslDetected(),
+  signal,
+  stateFile,
+  fetchImpl = fetch,
+  installed,
+  latest,
+} = {}) {
+  const asset = selectAsset(platform, arch, musl);
+  const active = installed !== undefined ? installed : await activeOverride(asset, { signal, stateFile });
+  return {
+    asset,
+    active,
+    current: active?.release ?? RELEASE,
+    latest: latest ?? await fetchLatestBackendRelease({ fetchImpl, signal }),
+  };
+}
+
+export async function backendUpdateMain(args = [], {
+  stdout = process.stdout,
+  stderr = process.stderr,
+  env = process.env,
+  signal,
+  stateFile,
+  platform = process.platform,
+  arch = process.arch,
+  fetchImpl = fetch,
+  check = checkBackend,
+  install = installBackend,
+  reset = clearBackendOverride,
+  removeFiles = directory => rm(directory, { recursive: true, force: true }),
+} = {}) {
+  [args, stdout, stderr] = commandOutput(args, stdout, stderr);
+  const [command, ...rest] = args;
+  if (command === undefined || command === '-h' || command === '--help' || rest.includes('-h') || rest.includes('--help')) {
+    stdout.write(BACKEND_HELP);
+    return 0;
+  }
+  if (command === 'reset') {
+    const unknown = rest.filter(token => token !== '--keep-files');
+    if (unknown.length) throw new Error(`Unknown option for veo backend reset: ${unknown.join(' ')}. Use: veo backend reset [--keep-files]`);
+    if (platform === 'android') {
+      stdout.write('Android/Termux uses system yt-dlp or VEO_YT_DLP_PATH. There is no managed backend to reset.\n');
+      return 0;
+    }
+    const state = await readBackendOverride(stateFile);
+    if (!await reset(stateFile)) {
+      stdout.write(`No installed backend to remove. veo uses the pinned release ${RELEASE}.\n`);
+      return 0;
+    }
+    if (state?.release && !rest.includes('--keep-files')) await removeFiles(backendCacheDirectory(state.release)).catch(() => {});
+    const removed = state?.release ? ` yt-dlp ${state.release}` : ' the installed backend';
+    stdout.write(`Removed${removed}. veo uses the pinned release ${RELEASE} again.\n`);
+    return 0;
+  }
+  if (command !== 'update') {
+    throw new Error(`Unknown backend command: ${cleanText(command)}. Use: veo backend update [--check] | veo backend reset`);
+  }
+  const checkOnly = rest.includes('--check');
+  const unknown = rest.filter(token => token !== '--check');
+  if (unknown.length) throw new Error(`Unknown option for veo backend update: ${unknown.join(' ')}. Use: veo backend update [--check]`);
+  if (platform === 'android') {
+    stdout.write('Android/Termux uses system yt-dlp or VEO_YT_DLP_PATH, not a pinned release. Update the Termux package with: pkg upgrade python-yt-dlp yt-dlp-ejs\n');
+    return 0;
+  }
+  if (env.VEO_YT_DLP_PATH) stderr.write('veo: VEO_YT_DLP_PATH is set and always takes precedence over the managed backend.\n');
+
+  let info;
+  try {
+    info = await check({ platform, arch, signal, stateFile, fetchImpl });
+  } catch (error) {
+    stderr.write(`veo: ${readableError(error)}\n`);
+    return 1;
+  }
+  const { asset, current, latest } = info;
+  if (!asset) {
+    stderr.write(`veo: no standalone yt-dlp is published for ${platform}/${arch}. Set VEO_YT_DLP_PATH to a trusted executable.\n`);
+    return 1;
+  }
+  if (compareVersions(latest, current) <= 0) {
+    stdout.write(`yt-dlp ${current} is up to date${current === RELEASE ? ' (pinned release, hash verified at build time)' : ' (installed release)'}.\n`);
+    return 0;
+  }
+  if (checkOnly) {
+    stdout.write(`Newer yt-dlp release available: ${latest} (using ${current}). Run: veo backend update\n`);
+    return 0;
+  }
+
+  let sha256;
+  try {
+    sha256 = await fetchReleaseChecksum({ release: latest, asset, fetchImpl, signal });
+  } catch (error) {
+    stderr.write(`veo: ${readableError(error)}\nNothing was installed. The pinned release ${RELEASE} is still in use.\n`);
+    return 1;
+  }
+  stdout.write(`Installing yt-dlp ${latest} for ${platform}/${asset}…\n`);
+  try {
+    await install({ release: latest, asset, sha256, signal, status: message => stdout.write(`${message}\n`) });
+  } catch (error) {
+    stderr.write(`veo: ${readableError(error)}\nThe pinned release ${RELEASE} is still in use.\n`);
+    return 1;
+  }
+  try {
+    await writeBackendOverride({ release: latest, asset, sha256, platform, arch, installed: new Date().toISOString() }, stateFile);
+  } catch (error) {
+    stderr.write(`veo: ${readableError(error)}\nThe download succeeded, but veo could not record it; the pinned release stays in use.\n`);
+    return 1;
+  }
+  stdout.write(`yt-dlp ${latest} installed and will be used for the next download.\n`);
+  stderr.write(`veo: note: yt-dlp ${latest} was verified against the checksum published with that release over HTTPS, not against a hash shipped with veo. Run "veo backend reset" to return to the pinned release.\n`);
+  return 0;
+}