veodl 1.12.0 → 1.12.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to veo. This project follows [Semantic Versioning](https://semver.org/).
 
+## 1.12.1
+
+### Fixed
+
+- Remove the optional FFmpeg npm dependency tree and its installation scripts.
+- Download desktop FFmpeg and FFprobe from fixed upstream releases and verify compressed and executable SHA-256 hashes before either program runs. Preserve upstream license and build information alongside the tools.
+- Verify managed media caches on reuse and reject legacy, corrupt or symlinked binaries. Preserve trusted system tools and explicit overrides.
+- Prevent rejected managed-cache binaries from being accepted again through PATH or a symlink alias; continue searching for external system tools.
+- Keep Smolish cookie environment variables out of media-tool probe processes.
+- Retry completed local transfers without contacting the original source, including selected-source retries, while retaining cache expiry and path validation.
+- Allow up to 30 seconds for Chromium's debugging connection on cold starts, while retaining the source scan's overall deadline and cancellation.
+
 ## 1.12.0
 
 ### Added

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 veo contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 veo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -770,12 +770,15 @@ A missing system FFmpeg is not a warning when the selected media tools work.
 
 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.
 
-Official standalone yt-dlp is acquired on first download and cached outside the package directory; help, version and plain doctor never download the backend. The release is pinned and SHA-256 verified against hashes shipped with this package. FFmpeg and FFprobe are normally supplied by the optional `ffmpeg-static` and `ffprobe-static` dependencies during npm installation. If these are absent and no local pair is available, veo installs `ffmpeg-static@5.3.0` and a platform-specific `@ffprobe-installer` package in a temporary cache project, checks that both programs run, and saves them in its backend cache. Media packages use npm/upstream HTTPS distribution, not the yt-dlp pinned-hash guarantee. These binaries have their own licenses; see their upstream packages. No Python installation is needed on supported standalone platforms.
+Official standalone yt-dlp is acquired on first download and cached outside the package directory; help, version and plain doctor never download the backend. The release is pinned and SHA-256 verified against hashes shipped with this package. The npm package has no runtime dependencies and runs no installation scripts.
+
+When no trusted local FFmpeg/FFprobe pair is available, veo downloads both tools directly from the upstream [ffmpeg-static binary releases](https://github.com/eugeneware/ffmpeg-static/releases/tag/b6.1.1). Release URLs, compressed and executable SHA-256 hashes, and byte counts are pinned in the package. The complete pair and its license and README must pass verification before either executable is started. Later uses verify the cached pair again; legacy or damaged cached binaries are not accepted merely because they are executable. Most targets use FFmpeg 6.1.1; Windows ia32 uses the last available pair, FFmpeg 6.0. Old `FFMPEG_BINARIES_URL`, `FFMPEG_BINARY_RELEASE` and `FFMPEG_BIN` variables do not change these downloads. Use `VEO_FFMPEG_PATH` to choose a trusted installed pair explicitly.
+
+The downloaded binaries retain their separate upstream licenses. `FFmpeg.LICENSE` and `FFmpeg.README` are saved next to the cached tools, including upstream source and build information. The JavaScript CLI remains MIT licensed. No Python installation is needed on supported standalone platforms.
 
 The existing Node executable is explicitly enabled as yt-dlp's JavaScript runtime for YouTube. Local yt-dlp configuration and plugins are disabled for predictable execution. Arguments are passed without a shell.
 
-`ffmpeg-static` and `ffprobe-static` publish no Windows ARM64 binaries. veo no longer refuses
-that platform: it uses an FFmpeg/FFprobe pair found on `PATH`, including the usual
+Windows ARM64 uses an FFmpeg/FFprobe pair found on `PATH`, including the usual
 WinGet, Chocolatey and `C:\ffmpeg\bin` locations, or automatically downloads x64
 media tools for Windows 11's x64 emulation.
 
@@ -796,8 +799,7 @@ installed as a dependency. Termux with the pacman package manager uses
 `--noconfirm` instead. This needs a working Termux repository and internet access.
 No root access is needed. Later runs reuse the installed tools.
 
-Static FFmpeg dependencies are optional; `--omit=optional` can be added to the
-npm install command to skip attempting those desktop packages entirely.
+The npm installation does not pull in desktop FFmpeg packages.
 The system yt-dlp is maintained by Termux and is
 not pinned or hash-verified by veo. Explicit `VEO_YT_DLP_PATH` and
 `VEO_FFMPEG_PATH` overrides still take precedence.
@@ -880,7 +882,7 @@ finished download whose destination was unavailable is retried from the local ca
 without contacting the source again. It also confirms that real runs leave `veo history`
 entries, that finished runs clean up their record, and that `veo runs`/`veo stop` report
 nothing left behind. It needs network access once for yt-dlp acquisition; it downloads no
-third-party video. Unit tests require no network.
+third-party video. Prepare media tools with `veo doctor fix` before `npm test` on a fresh checkout; the tests themselves use local fixtures and require no network. CI explicitly prepares and verifies the native binary pair before testing.
 
 The published tarball only includes `bin/`, `src/`, package metadata, README and LICENSE.
 The lockfile is kept for reproducible development. There is no build step. npm makes the

package/docs/AGENT_GUIDE.md

@@ -116,6 +116,7 @@ The run record is stored in veo's per-user cache on the device that ran the down
 - Example profile: `"experimental": { "concurrentFragments": 32, "experimentalFragments": true }`. Run with `veo <URL> --profile experimental`; use `--no-experimental-fragments` to revoke a stored opt-in.
 
 - Run `veo doctor --offline` to check the local setup without network repair. `veo doctor fix` may install missing tools.
+- Desktop media downloads use fixed release URLs and shipped SHA-256 hashes; both FFmpeg and FFprobe are verified before execution and on cache reuse. A rejected legacy cache requires `veo doctor fix`. Trusted PATH tools and `VEO_FFMPEG_PATH` remain explicit alternatives. The npm package has no runtime dependencies or install scripts.
 - 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

@@ -1,6 +1,6 @@
 {
   "name": "veodl",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "description": "A clean, simple video downloader powered by yt-dlp.",
   "type": "module",
   "bin": {
@@ -51,10 +51,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "optionalDependencies": {
-    "ffmpeg-static": "5.3.0",
-    "ffprobe-static": "3.1.0"
-  },
   "devDependencies": {
     "@xterm/headless": "6.0.0"
   }

package/src/alias.js

@@ -1,258 +1,258 @@
-import path from 'node:path';
-import { chmod, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { commandOutput } from './output.js';
-import { findOnPath } from './backend.js';
-import { cleanText, readableError } from './utils.js';
-
-export const BUILTIN_ALIASES = ['veo', 'veodl'];
-export const ALIAS_MARKER = 'veo-alias';
-
-export const ALIAS_HELP = `veo alias - manage extra command names for veo
-
-Usage:
-  veo alias                    List command names (same as: veo alias list)
-  veo alias list [--json]      Show veo, veodl plus custom wrappers
-  veo alias add <name> [--force] [--json]
-                               Create <name> as a wrapper that calls veo
-  veo alias remove <name> [--json]   Delete a wrapper (also: veo alias rm)
-  veo alias --help             Show this help
-
-Names use 2-31 lowercase letters, digits or hyphens and start with a letter,
-e.g. veo-dl. The wrapper is created next to the veo command found on PATH and
-simply forwards to veo, so it survives veo updates. Removing veodl only
-removes that shortcut; veo update recreates the shipped names. veo itself can
-never be removed. Use --bin-dir <path> to override the target directory.
-`;
-
-export function validateAliasName(input) {
-  const raw = String(input ?? '').trim();
-  if (!raw) throw new Error('An alias name is required. Use: veo alias add <name>');
-  if (cleanText(raw) !== raw) throw new Error(`Invalid alias name: ${raw}. Use plain text without escapes.`);
-  if (!/^[a-z][a-z0-9-]{1,30}$/.test(raw)) {
-    throw new Error(`Invalid alias name "${raw}". Use 2-31 lowercase letters, digits or hyphens, starting with a letter (e.g. veo-dl).`);
-  }
-  return raw;
-}
-
-export function aliasFiles(binDir, name, platform = process.platform) {
-  if (platform === 'win32') {
-    return [path.join(binDir, name), path.join(binDir, `${name}.cmd`), path.join(binDir, `${name}.ps1`)];
-  }
-  return [path.join(binDir, name)];
-}
-
-function posixWrapper(name) {
-  return `#!/bin/sh\n# ${ALIAS_MARKER}: ${name}\nexec veo "$@"\n`;
-}
-
-function windowsCmdWrapper(name) {
-  return `@echo off\r\nREM ${ALIAS_MARKER}: ${name}\r\nveo %*\r\n`;
-}
-
-function windowsShWrapper(name) {
-  return `#!/bin/sh\n# ${ALIAS_MARKER}: ${name}\nexec veo "$@"\n`;
-}
-
-function windowsPsWrapper(name) {
-  return `# ${ALIAS_MARKER}: ${name}\nveo @args\n`;
-}
-
-async function exists(file, { statImpl = stat } = {}) {
-  try {
-    const info = await statImpl(file);
-    return info.isFile();
-  } catch (error) {
-    if (error?.code === 'ENOENT') return false;
-    throw error;
-  }
-}
-
-async function isManaged(file, { readFileImpl = readFile } = {}) {
-  try {
-    const text = await readFileImpl(file, 'utf8');
-    return text.slice(0, 4096).includes(ALIAS_MARKER);
-  } catch {
-    return false;
-  }
-}
-
-export async function resolveBinDir({ binDir, platform = process.platform, env = process.env, find = findOnPath } = {}) {
-  if (binDir) return path.resolve(binDir);
-  const found = await find(['veo'], { platform, env });
-  if (!found) {
-    throw new Error('Could not locate the veo command on PATH. Install veo globally (npm install -g veodl) or pass --bin-dir <path>.');
-  }
-  return path.dirname(found);
-}
-
-export async function aliasStatus(name, { binDir, platform = process.platform, ...fs } = {}) {
-  const files = aliasFiles(binDir, name, platform);
-  const present = [];
-  let managed = false;
-  for (const file of files) {
-    if (await exists(file, fs)) {
-      present.push(file);
-      if (await isManaged(file, fs)) managed = true;
-    }
-  }
-  return { name, builtin: BUILTIN_ALIASES.includes(name), present: present.length > 0, managed, paths: present };
-}
-
-function baseNameOf(file, platform) {
-  const base = path.basename(file);
-  if (platform === 'win32') {
-    if (base.toLowerCase().endsWith('.cmd')) return base.slice(0, -4);
-    if (base.toLowerCase().endsWith('.ps1')) return base.slice(0, -4);
-  }
-  return base;
-}
-
-export async function listAliases({ binDir, platform = process.platform, builtins = BUILTIN_ALIASES, readdirImpl = readdir, readFileImpl = readFile, statImpl = stat } = {}) {
-  const resolved = await resolveBinDir({ binDir, platform });
-  const entries = [];
-  for (const name of builtins) {
-    entries.push(await aliasStatus(name, { binDir: resolved, platform, readFileImpl, statImpl }));
-  }
-  const known = new Set(entries.map(entry => entry.name));
-  let files = [];
-  try {
-    files = await readdirImpl(resolved, { withFileTypes: true });
-  } catch (error) {
-    throw new Error(`Cannot list the command directory ${resolved}: ${readableError(error)}`);
-  }
-  for (const entry of files) {
-    if (!entry.isFile()) continue;
-    const full = path.join(resolved, entry.name);
-    let text = '';
-    try {
-      text = String(await readFileImpl(full, 'utf8')).slice(0, 4096);
-    } catch {
-      continue;
-    }
-    if (!text.includes(ALIAS_MARKER)) continue;
-    const base = baseNameOf(entry.name, platform);
-    try {
-      validateAliasName(base);
-    } catch {
-      continue;
-    }
-    if (known.has(base)) {
-      const existing = entries.find(item => item.name === base);
-      if (existing) existing.managed = true;
-      continue;
-    }
-    known.add(base);
-    entries.push({ name: base, builtin: false, present: true, managed: true, paths: [full] });
-  }
-  return { binDir: resolved, aliases: entries.sort((a, b) => a.name.localeCompare(b.name)) };
-}
-
-export async function addAlias(name, { binDir, platform = process.platform, force = false, writeFileImpl = writeFile, statImpl = stat, chmodImpl = chmod, mkdirImpl = mkdir } = {}) {
-  const valid = validateAliasName(name);
-  if (valid === 'veo') throw new Error('veo is already the main command.');
-  const resolved = await resolveBinDir({ binDir, platform });
-  await mkdirImpl(resolved, { recursive: true });
-  const files = aliasFiles(resolved, valid, platform);
-  const present = [];
-  for (const file of files) {
-    if (await exists(file, { statImpl })) present.push(file);
-  }
-  if (present.length && !force) {
-    throw new Error(`${valid} already exists (${present.map(file => path.basename(file)).join(', ')}). Use --force to replace it.`);
-  }
-  for (const file of present) await rm(file, { force: true });
-  if (platform === 'win32') {
-    await writeFileImpl(files[0], windowsShWrapper(valid), { mode: 0o755 });
-    await writeFileImpl(files[1], windowsCmdWrapper(valid));
-    await writeFileImpl(files[2], windowsPsWrapper(valid));
-  } else {
-    await writeFileImpl(files[0], posixWrapper(valid), { mode: 0o755 });
-    try {
-      await chmodImpl(files[0], 0o755);
-    } catch {
-      // Non-POSIX filesystems may ignore modes; the shebang still works.
-    }
-  }
-  return { name: valid, binDir: resolved, paths: aliasFiles(resolved, valid, platform) };
-}
-
-export async function removeAlias(name, { binDir, platform = process.platform, statImpl = stat, rmImpl = rm } = {}) {
-  const valid = validateAliasName(name);
-  if (valid === 'veo') throw new Error('Refusing to remove veo itself. Remove veodl or a custom wrapper instead.');
-  const resolved = await resolveBinDir({ binDir, platform });
-  const status = await aliasStatus(valid, { binDir: resolved, platform, statImpl });
-  if (!status.present) throw new Error(`${valid} is not installed in ${resolved}.`);
-  for (const file of status.paths) await rmImpl(file, { force: true });
-  return { name: valid, binDir: resolved, removed: status.paths, builtin: status.builtin };
-}
-
-function parseAliasArgs(args) {
-  let binDir;
-  let force = false;
-  let json = false;
-  const rest = [];
-  for (let index = 0; index < args.length; index++) {
-    const token = args[index];
-    if (token === '--force') force = true;
-    else if (token === '--json') json = true;
-    else if (token === '--bin-dir') {
-      binDir = args[++index];
-      if (!binDir) throw new Error('--bin-dir requires a directory. Run veo alias --help for usage.');
-    } else if (token.startsWith('--bin-dir=')) {
-      binDir = token.slice(10) || undefined;
-      if (!binDir) throw new Error('--bin-dir requires a directory. Run veo alias --help for usage.');
-    } else rest.push(token);
-  }
-  return { binDir, force, json, rest };
-}
-
-export async function aliasMain(args = [], { stdout = process.stdout, stderr = process.stderr, ...options } = {}) {
-  [args, stdout, stderr] = commandOutput(args, stdout, stderr);
-  const { binDir, force, json, rest } = parseAliasArgs(args);
-  const [command, name, ...extra] = rest;
-  if (!command || command === 'list') {
-    if (name || extra.length) throw new Error('Usage: veo alias list [--json] (or veo alias --help)');
-    if (command === 'list' && extra.length) throw new Error('Usage: veo alias list [--json] (or veo alias --help)');
-    const result = await listAliases({ ...options, binDir });
-    if (json) {
-      stdout.write(`${JSON.stringify(result)}\n`);
-      return 0;
-    }
-    stdout.write(`Command directory: ${result.binDir}\n`);
-    for (const entry of result.aliases) {
-      const kind = entry.builtin ? 'shipped' : 'custom';
-      const state = entry.present ? (entry.managed ? 'wrapper -> veo' : 'installed') : 'missing';
-      stdout.write(`  ${entry.name} (${kind}, ${state})\n`);
-    }
-    const missing = result.aliases.filter(entry => !entry.present).map(entry => entry.name);
-    if (missing.length) stdout.write(`Missing: ${missing.join(', ')} (veo update recreates shipped names).\n`);
-    return 0;
-  }
-  if (command === '-h' || command === '--help') {
-    stdout.write(ALIAS_HELP);
-    return 0;
-  }
-  if (command === 'add') {
-    if (!name || extra.length) throw new Error('Usage: veo alias add <name> [--force] (or veo alias --help)');
-    const created = await addAlias(name, { ...options, binDir, force });
-    if (json) {
-      stdout.write(`${JSON.stringify({ status: 'added', ...created })}\n`);
-      return 0;
-    }
-    stdout.write(`Alias installed: ${created.name} -> veo (${created.binDir})\n`);
-    stdout.write(`Run "${created.name} --help" to use it. Remove it with: veo alias remove ${created.name}\n`);
-    return 0;
-  }
-  if (command === 'remove' || command === 'rm' || command === 'uninstall') {
-    if (!name || extra.length) throw new Error('Usage: veo alias remove <name> (or veo alias --help)');
-    const removed = await removeAlias(name, { ...options, binDir });
-    if (json) {
-      stdout.write(`${JSON.stringify({ status: 'removed', ...removed })}\n`);
-      return 0;
-    }
-    stdout.write(`Alias removed: ${removed.name} (${removed.removed.length} file(s) in ${removed.binDir})\n`);
-    if (removed.builtin) stdout.write('Note: veo update recreates the shipped veodl name.\n');
-    return 0;
-  }
-  throw new Error(`Unknown alias command: ${cleanText(command)}. Use: veo alias list | veo alias add <name> | veo alias remove <name>`);
-}
+import path from 'node:path';
+import { chmod, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { commandOutput } from './output.js';
+import { findOnPath } from './backend.js';
+import { cleanText, readableError } from './utils.js';
+
+export const BUILTIN_ALIASES = ['veo', 'veodl'];
+export const ALIAS_MARKER = 'veo-alias';
+
+export const ALIAS_HELP = `veo alias - manage extra command names for veo
+
+Usage:
+  veo alias                    List command names (same as: veo alias list)
+  veo alias list [--json]      Show veo, veodl plus custom wrappers
+  veo alias add <name> [--force] [--json]
+                               Create <name> as a wrapper that calls veo
+  veo alias remove <name> [--json]   Delete a wrapper (also: veo alias rm)
+  veo alias --help             Show this help
+
+Names use 2-31 lowercase letters, digits or hyphens and start with a letter,
+e.g. veo-dl. The wrapper is created next to the veo command found on PATH and
+simply forwards to veo, so it survives veo updates. Removing veodl only
+removes that shortcut; veo update recreates the shipped names. veo itself can
+never be removed. Use --bin-dir <path> to override the target directory.
+`;
+
+export function validateAliasName(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) throw new Error('An alias name is required. Use: veo alias add <name>');
+  if (cleanText(raw) !== raw) throw new Error(`Invalid alias name: ${raw}. Use plain text without escapes.`);
+  if (!/^[a-z][a-z0-9-]{1,30}$/.test(raw)) {
+    throw new Error(`Invalid alias name "${raw}". Use 2-31 lowercase letters, digits or hyphens, starting with a letter (e.g. veo-dl).`);
+  }
+  return raw;
+}
+
+export function aliasFiles(binDir, name, platform = process.platform) {
+  if (platform === 'win32') {
+    return [path.join(binDir, name), path.join(binDir, `${name}.cmd`), path.join(binDir, `${name}.ps1`)];
+  }
+  return [path.join(binDir, name)];
+}
+
+function posixWrapper(name) {
+  return `#!/bin/sh\n# ${ALIAS_MARKER}: ${name}\nexec veo "$@"\n`;
+}
+
+function windowsCmdWrapper(name) {
+  return `@echo off\r\nREM ${ALIAS_MARKER}: ${name}\r\nveo %*\r\n`;
+}
+
+function windowsShWrapper(name) {
+  return `#!/bin/sh\n# ${ALIAS_MARKER}: ${name}\nexec veo "$@"\n`;
+}
+
+function windowsPsWrapper(name) {
+  return `# ${ALIAS_MARKER}: ${name}\nveo @args\n`;
+}
+
+async function exists(file, { statImpl = stat } = {}) {
+  try {
+    const info = await statImpl(file);
+    return info.isFile();
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function isManaged(file, { readFileImpl = readFile } = {}) {
+  try {
+    const text = await readFileImpl(file, 'utf8');
+    return text.slice(0, 4096).includes(ALIAS_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveBinDir({ binDir, platform = process.platform, env = process.env, find = findOnPath } = {}) {
+  if (binDir) return path.resolve(binDir);
+  const found = await find(['veo'], { platform, env });
+  if (!found) {
+    throw new Error('Could not locate the veo command on PATH. Install veo globally (npm install -g veodl) or pass --bin-dir <path>.');
+  }
+  return path.dirname(found);
+}
+
+export async function aliasStatus(name, { binDir, platform = process.platform, ...fs } = {}) {
+  const files = aliasFiles(binDir, name, platform);
+  const present = [];
+  let managed = false;
+  for (const file of files) {
+    if (await exists(file, fs)) {
+      present.push(file);
+      if (await isManaged(file, fs)) managed = true;
+    }
+  }
+  return { name, builtin: BUILTIN_ALIASES.includes(name), present: present.length > 0, managed, paths: present };
+}
+
+function baseNameOf(file, platform) {
+  const base = path.basename(file);
+  if (platform === 'win32') {
+    if (base.toLowerCase().endsWith('.cmd')) return base.slice(0, -4);
+    if (base.toLowerCase().endsWith('.ps1')) return base.slice(0, -4);
+  }
+  return base;
+}
+
+export async function listAliases({ binDir, platform = process.platform, builtins = BUILTIN_ALIASES, readdirImpl = readdir, readFileImpl = readFile, statImpl = stat } = {}) {
+  const resolved = await resolveBinDir({ binDir, platform });
+  const entries = [];
+  for (const name of builtins) {
+    entries.push(await aliasStatus(name, { binDir: resolved, platform, readFileImpl, statImpl }));
+  }
+  const known = new Set(entries.map(entry => entry.name));
+  let files = [];
+  try {
+    files = await readdirImpl(resolved, { withFileTypes: true });
+  } catch (error) {
+    throw new Error(`Cannot list the command directory ${resolved}: ${readableError(error)}`);
+  }
+  for (const entry of files) {
+    if (!entry.isFile()) continue;
+    const full = path.join(resolved, entry.name);
+    let text = '';
+    try {
+      text = String(await readFileImpl(full, 'utf8')).slice(0, 4096);
+    } catch {
+      continue;
+    }
+    if (!text.includes(ALIAS_MARKER)) continue;
+    const base = baseNameOf(entry.name, platform);
+    try {
+      validateAliasName(base);
+    } catch {
+      continue;
+    }
+    if (known.has(base)) {
+      const existing = entries.find(item => item.name === base);
+      if (existing) existing.managed = true;
+      continue;
+    }
+    known.add(base);
+    entries.push({ name: base, builtin: false, present: true, managed: true, paths: [full] });
+  }
+  return { binDir: resolved, aliases: entries.sort((a, b) => a.name.localeCompare(b.name)) };
+}
+
+export async function addAlias(name, { binDir, platform = process.platform, force = false, writeFileImpl = writeFile, statImpl = stat, chmodImpl = chmod, mkdirImpl = mkdir } = {}) {
+  const valid = validateAliasName(name);
+  if (valid === 'veo') throw new Error('veo is already the main command.');
+  const resolved = await resolveBinDir({ binDir, platform });
+  await mkdirImpl(resolved, { recursive: true });
+  const files = aliasFiles(resolved, valid, platform);
+  const present = [];
+  for (const file of files) {
+    if (await exists(file, { statImpl })) present.push(file);
+  }
+  if (present.length && !force) {
+    throw new Error(`${valid} already exists (${present.map(file => path.basename(file)).join(', ')}). Use --force to replace it.`);
+  }
+  for (const file of present) await rm(file, { force: true });
+  if (platform === 'win32') {
+    await writeFileImpl(files[0], windowsShWrapper(valid), { mode: 0o755 });
+    await writeFileImpl(files[1], windowsCmdWrapper(valid));
+    await writeFileImpl(files[2], windowsPsWrapper(valid));
+  } else {
+    await writeFileImpl(files[0], posixWrapper(valid), { mode: 0o755 });
+    try {
+      await chmodImpl(files[0], 0o755);
+    } catch {
+      // Non-POSIX filesystems may ignore modes; the shebang still works.
+    }
+  }
+  return { name: valid, binDir: resolved, paths: aliasFiles(resolved, valid, platform) };
+}
+
+export async function removeAlias(name, { binDir, platform = process.platform, statImpl = stat, rmImpl = rm } = {}) {
+  const valid = validateAliasName(name);
+  if (valid === 'veo') throw new Error('Refusing to remove veo itself. Remove veodl or a custom wrapper instead.');
+  const resolved = await resolveBinDir({ binDir, platform });
+  const status = await aliasStatus(valid, { binDir: resolved, platform, statImpl });
+  if (!status.present) throw new Error(`${valid} is not installed in ${resolved}.`);
+  for (const file of status.paths) await rmImpl(file, { force: true });
+  return { name: valid, binDir: resolved, removed: status.paths, builtin: status.builtin };
+}
+
+function parseAliasArgs(args) {
+  let binDir;
+  let force = false;
+  let json = false;
+  const rest = [];
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index];
+    if (token === '--force') force = true;
+    else if (token === '--json') json = true;
+    else if (token === '--bin-dir') {
+      binDir = args[++index];
+      if (!binDir) throw new Error('--bin-dir requires a directory. Run veo alias --help for usage.');
+    } else if (token.startsWith('--bin-dir=')) {
+      binDir = token.slice(10) || undefined;
+      if (!binDir) throw new Error('--bin-dir requires a directory. Run veo alias --help for usage.');
+    } else rest.push(token);
+  }
+  return { binDir, force, json, rest };
+}
+
+export async function aliasMain(args = [], { stdout = process.stdout, stderr = process.stderr, ...options } = {}) {
+  [args, stdout, stderr] = commandOutput(args, stdout, stderr);
+  const { binDir, force, json, rest } = parseAliasArgs(args);
+  const [command, name, ...extra] = rest;
+  if (!command || command === 'list') {
+    if (name || extra.length) throw new Error('Usage: veo alias list [--json] (or veo alias --help)');
+    if (command === 'list' && extra.length) throw new Error('Usage: veo alias list [--json] (or veo alias --help)');
+    const result = await listAliases({ ...options, binDir });
+    if (json) {
+      stdout.write(`${JSON.stringify(result)}\n`);
+      return 0;
+    }
+    stdout.write(`Command directory: ${result.binDir}\n`);
+    for (const entry of result.aliases) {
+      const kind = entry.builtin ? 'shipped' : 'custom';
+      const state = entry.present ? (entry.managed ? 'wrapper -> veo' : 'installed') : 'missing';
+      stdout.write(`  ${entry.name} (${kind}, ${state})\n`);
+    }
+    const missing = result.aliases.filter(entry => !entry.present).map(entry => entry.name);
+    if (missing.length) stdout.write(`Missing: ${missing.join(', ')} (veo update recreates shipped names).\n`);
+    return 0;
+  }
+  if (command === '-h' || command === '--help') {
+    stdout.write(ALIAS_HELP);
+    return 0;
+  }
+  if (command === 'add') {
+    if (!name || extra.length) throw new Error('Usage: veo alias add <name> [--force] (or veo alias --help)');
+    const created = await addAlias(name, { ...options, binDir, force });
+    if (json) {
+      stdout.write(`${JSON.stringify({ status: 'added', ...created })}\n`);
+      return 0;
+    }
+    stdout.write(`Alias installed: ${created.name} -> veo (${created.binDir})\n`);
+    stdout.write(`Run "${created.name} --help" to use it. Remove it with: veo alias remove ${created.name}\n`);
+    return 0;
+  }
+  if (command === 'remove' || command === 'rm' || command === 'uninstall') {
+    if (!name || extra.length) throw new Error('Usage: veo alias remove <name> (or veo alias --help)');
+    const removed = await removeAlias(name, { ...options, binDir });
+    if (json) {
+      stdout.write(`${JSON.stringify({ status: 'removed', ...removed })}\n`);
+      return 0;
+    }
+    stdout.write(`Alias removed: ${removed.name} (${removed.removed.length} file(s) in ${removed.binDir})\n`);
+    if (removed.builtin) stdout.write('Note: veo update recreates the shipped veodl name.\n');
+    return 0;
+  }
+  throw new Error(`Unknown alias command: ${cleanText(command)}. Use: veo alias list | veo alias add <name> | veo alias remove <name>`);
+}