veodl 1.11.0 → 1.12.0

package/README.md

@@ -586,6 +586,10 @@ veo doctor --offline  # skip the network checks
 veo stats             # persistent download totals; --json for scripting
 veo history           # the last 5 downloads; --json for scripting
 veo history --failed --limit 20  # recent failed/cancelled attempts
+veo changes           # released versions, newest first; the installed one is marked
+veo changes 1.10.1    # notes of one release (also: --version 1.10.1)
+veo changes --since 1.10.1  # everything newer than a version
+veo changes --latest --json  # newest release as JSON
 veo retry --last       # retry the newest failed or unfinished job
 veo runs              # active runs with their id; veo runs <id> for details
 veo runs --json       # machine-readable active run metadata
@@ -689,6 +693,33 @@ directory keeps one file per attempt and contains URLs, titles and local file pa
 delete it to remove those records. `veo flush` keeps the list (only `veo flush --stats`
 resets statistics, not history).
 
+### `veo changes`
+
+Lists every **released version**, newest first, and marks the installed one. `veo changelog`
+is an alias. The notes are parsed from the `CHANGELOG.md` that ships inside the package, so
+they always belong to the installed code and the command needs no network access.
+
+```bash
+veo changes                       # all versions with their Added/Changed/Fixed counts
+veo changes 1.10.1                # the notes of one release
+veo changes --version 1.10.1      # the same, spelled out
+veo changes 1.10                  # newest release starting with 1.10
+veo changes --latest              # only the newest release
+veo changes --since 1.10.0        # everything newer than 1.10.0, up to the newest release
+veo changes --range 1.9.0..1.11.0 # a closed range, newest first
+veo changes --json                # machine-readable
+```
+
+An unknown version fails with the known versions listed. Long entries wrap to the terminal
+width, and `--json` returns the complete text. Because the list already names the released
+versions, `veo changes` prints no automatic update hint.
+
+`veo changes --json` prints `{"current":…,"count":N,"versions":[…]}`, where each entry has
+`version`, `date` (currently `null`, since the changelog headings carry no date), `installed`,
+`counts` and `summary`. One version adds `"version"`, `"installed"` and `"sections"`; a range
+adds `"from"` and `"to"` and keeps the per-release `sections`. Sections are
+`{"type":"Added","items":[{"text":"…","items":[…]}]}`, and nested items are preserved.
+
 ### `veo runs` and `veo stop`
 
 Every run registers itself while it works, under a **6-character id**, and removes that

package/docs/AGENT_GUIDE.md

@@ -66,6 +66,28 @@ 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. Use `veo --retry-failed <runId>` to retry a failed or unfinished run; a saved `job` path is also accepted as `veo --retry-failed "<job-path>"`. The original retry job must still be present, and retrying an active run by ID is rejected. `veo retry --last` finds the newest retryable job automatically. Running jobs are excluded from `retry --last`.
 
+## Release notes
+
+```sh
+veo changes --json
+veo changes 1.10.1 --json
+veo changes --since 1.9.0 --json
+```
+
+`veo changes` (alias `veo changelog`) parses the `CHANGELOG.md` shipped inside the installed
+package, so it never touches the network and never prints an update hint. Bare, it lists every
+released version, newest first, with the installed one marked as `installed`; a version argument
+(or `--version`, also a partial version such as `1.10`) selects one release, `--latest` the newest,
+and `--since <version>` with `--to <version>` or `--range <from>..<to>` everything between two
+versions, newest first. An unknown version exits nonzero and lists the known ones.
+
+The list form returns `{"current":…,"count":N,"versions":[{"version","date","installed","counts","summary"}]}`.
+One version returns `{"current","version","date","installed","sections"}`, a range
+`{"current","from","to","count","versions":[…]}`. `sections` is
+`[{"type":"Added","items":[{"text":"…","items":[…]}]}]`; nested items are preserved and the text
+is complete, so do not re-wrap it yourself. `date` is currently `null` because the changelog
+headings carry no release date.
+
 ## Inspect saved media and audio
 
 `veo subs <URL> --json` lists manual and automatic subtitle languages and formats without saving media. Select manual subtitles with `--subs --sub-langs de,en`, generated subtitles with `--auto-subs --sub-langs de,en`, and prefer a source format with `--sub-format srt/vtt/best`. `--verify` optionally probes saved media files before recording success; it is off by default and does not decode the full track.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veodl",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "A clean, simple video downloader powered by yt-dlp.",
   "type": "module",
   "bin": {

package/src/changes.js

@@ -0,0 +1,278 @@
+import { commandOutput } from './output.js';
+import { readFile } from 'node:fs/promises';
+import { terminalColumns } from './terminal-size.js';
+import { wrap } from './progress.js';
+import { compareVersions } from './version.js';
+import { packageVersion } from './updater.js';
+import { suggestOption } from './option-suggestions.js';
+import { cleanText } from './utils.js';
+
+/**
+ * `veo changes` reads the CHANGELOG.md that ships inside this package, so the
+ * notes always belong to the installed code and work without network access. The
+ * file is parsed into data instead of being printed: sections, bullets, nested
+ * bullets and wrapped lines survive, and `--json` returns the same structure.
+ */
+const RELEASE = /^##\s+v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)(?:\s+[-–—]\s+(\d{4}-\d{2}-\d{2}))?\s*$/;
+const SECTION = /^###\s+(.+?)\s*$/;
+const BULLET = /^(\s*)-\s+(.*)$/;
+const VERSION = /^\d+(\.\d+)*$/;
+const MARKER = '(installed)';
+const SHOWN = 5;
+const USAGE = 'Usage: veo changes [<version>] [--json] [--latest] [--since <version>] [--to <version>] [--range <from>..<to>]';
+
+export const CHANGES_HELP = `veo changes [<version>] [--json] [--latest] [--since <version>]
+                          [--to <version>] [--range <from>..<to>]
+
+List every released version, newest first, and mark the installed one. With a version
+(or --version) show that release's notes; a partial version such as 1.10 selects the
+newest match. --since shows everything newer than a version, --to and --range set both
+ends of a range, and --latest shows only the newest release. Notes come from the
+CHANGELOG.md shipped with this veo version, so the command needs no network access and
+prints no automatic update hint. Use --json for scripting.
+`;
+
+/**
+ * Keep a Changelog style document becomes releases, newest first. A heading of
+ * second level that is not a version ends the notes, so an appended file list or
+ * a second document cannot leak into the last release.
+ */
+export function parseChangelog(markdown) {
+  const releases = [];
+  let release = null;
+  let section = null;
+  let item = null; // Current top-level bullet and parent of any nested ones.
+  let last = null; // Most recent bullet, which a wrapped line continues.
+  for (const raw of String(markdown).split(/\r?\n/)) {
+    const line = raw.replace(/\s+$/, '');
+    if (!line.trim()) { last = null; continue; }
+    const heading = RELEASE.exec(line);
+    if (heading) {
+      release = { version: heading[1], date: heading[2] || null, sections: [] };
+      releases.push(release);
+      section = null; item = null; last = null;
+      continue;
+    }
+    // A second-level heading that is not a version ends the notes; the document
+    // title above the first release is preamble and ignored.
+    if (/^##\s/.test(line)) break;
+    if (!release) continue;
+    const type = SECTION.exec(line);
+    if (type) {
+      section = { type: cleanText(type[1]), items: [] };
+      release.sections.push(section);
+      item = null; last = null;
+      continue;
+    }
+    if (!section) continue;
+    const bullet = BULLET.exec(line);
+    if (bullet) {
+      const text = cleanText(bullet[2]);
+      if (!text) continue;
+      if (!bullet[1].length || !item) {
+        item = { text, items: [] };
+        section.items.push(item);
+        last = item;
+      } else {
+        last = { text, items: [] };
+        item.items.push(last);
+      }
+      continue;
+    }
+    // Without a bullet the line continues the previous one; the changelog wraps prose.
+    if (last) last.text = cleanText(`${last.text} ${line.trim()}`);
+  }
+  return releases.sort((left, right) => compareVersions(right.version, left.version));
+}
+
+/** Entry counts per section type, in the order the changelog lists them. */
+export function releaseCounts(release) {
+  return Object.fromEntries(release.sections.filter(section => section.items.length)
+    .map(section => [section.type, section.items.length]));
+}
+
+const summary = counts => Object.entries(counts).map(([type, count]) => `${type} ${count}`).join(', ');
+
+/** Exact match first, then the newest release starting with the given prefix. */
+export function resolveVersion(releases, requested, label = 'version') {
+  const wanted = String(requested ?? '').trim().replace(/^v/i, '');
+  if (!VERSION.test(wanted)) throw new Error(`${label} must be a version number such as 1.11.0.`);
+  const exact = releases.find(release => release.version === wanted);
+  if (exact) return exact;
+  const partial = releases.filter(release => release.version.startsWith(`${wanted}.`) || release.version.startsWith(`${wanted}-`));
+  if (partial.length) return partial.reduce((best, release) => compareVersions(release.version, best.version) > 0 ? release : best);
+  const known = releases.map(release => release.version);
+  if (!known.length) throw new Error(`${label} "${cleanText(requested)}" cannot be resolved: the changelog lists no releases.`);
+  const guess = suggestOption(wanted, known);
+  const list = known.slice(0, SHOWN).join(', ');
+  throw new Error(`Unknown ${label} "${cleanText(requested)}".${guess ? ` Did you mean "${guess}"?` : ''} Known versions: ${list}${known.length > SHOWN ? ', …' : ''}.`);
+}
+
+/** Which releases a request selects, and under which heading they are shown. */
+export function selectReleases(releases, { version = null, latest = false, since = null, to = null } = {}) {
+  const sorted = [...releases].sort((left, right) => compareVersions(right.version, left.version));
+  const newest = sorted[0]?.version ?? null;
+  if (version) {
+    const release = resolveVersion(sorted, version);
+    return { mode: 'version', from: release.version, to: release.version, versions: [release] };
+  }
+  if (latest) return { mode: 'latest', from: newest, to: newest, versions: sorted.slice(0, 1) };
+  if (since || to) {
+    const from = since ? resolveVersion(sorted, since, '--since').version : null;
+    const upper = to ? resolveVersion(sorted, to, '--to').version : null;
+    if (from && upper && compareVersions(upper, from) < 0) throw new Error(`--to ${upper} is older than --since ${from}.`);
+    const versions = sorted.filter(release => (!from || compareVersions(release.version, from) > 0)
+      && (!upper || compareVersions(release.version, upper) <= 0));
+    if (!versions.length) {
+      if (from && !upper) throw new Error(`This veo is already at ${from}; no newer changes are listed.`);
+      throw new Error(`No changes listed between ${from ?? 'the first release'} and ${upper ?? newest}.`);
+    }
+    return { mode: 'range', from, to: upper ?? newest, versions };
+  }
+  return { mode: 'list', from: null, to: null, versions: sorted };
+}
+
+/** The shipped changelog, or a clear error when an installation lost the file. */
+export async function readChangelog(file = new URL('../CHANGELOG.md', import.meta.url)) {
+  let markdown;
+  try {
+    markdown = await readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'EISDIR') throw new Error(`No CHANGELOG.md found at ${file}.`);
+    throw error;
+  }
+  return parseChangelog(markdown);
+}
+
+function bulletLines(entry, stream, depth) {
+  const prefix = `${'  '.repeat(depth)}- `;
+  const hanging = ' '.repeat(prefix.length);
+  // Notes are wrapped instead of shortened: a release note that loses its tail
+  // because the terminal is narrow would be worse than useless.
+  const columns = stream?.isTTY ? Math.max(24, terminalColumns(stream) - prefix.length - 1) : Infinity;
+  return wrap(entry.text, columns).split('\n').map((line, index) => (index ? hanging : prefix) + line);
+}
+
+function releaseLines(release, stream, installed, header) {
+  const lines = [];
+  if (header) lines.push(release.version + (installed ? `  ${MARKER}` : ''));
+  for (const section of release.sections) {
+    if (!section.items.length) continue;
+    lines.push(section.type);
+    for (const entry of section.items) {
+      lines.push(...bulletLines(entry, stream, 1));
+      for (const nested of entry.items) lines.push(...bulletLines(nested, stream, 2));
+    }
+    lines.push('');
+  }
+  if (lines.at(-1) === '') lines.pop();
+  return lines;
+}
+
+const plural = count => `${count} version${count === 1 ? '' : 's'}`;
+
+export function formatChanges(selection, { current, stream } = {}) {
+  const { mode, versions } = selection;
+  if (!versions.length) return 'veo changes\n\nNo release notes found in CHANGELOG.md.\n';
+  if (mode === 'list') {
+    const width = Math.max(...versions.map(release => release.version.length));
+    const lines = [`veo changes (${plural(versions.length)}, newest first)`, ''];
+    for (const release of versions) {
+      const installed = release.version === current ? MARKER : '';
+      const row = `  ${release.version.padEnd(width)}  ${installed.padEnd(MARKER.length)}`;
+      const counts = summary(releaseCounts(release));
+      // A release without entries must not leave trailing spaces in the column.
+      lines.push(counts ? `${row}  ${counts}` : row);
+    }
+    lines.push('');
+    lines.push('Use veo changes <version> for one version, veo changes --since <version> for');
+    lines.push('everything newer than a given version, or --json for scripting.');
+    return `${lines.join('\n')}\n`;
+  }
+  const title = mode === 'range'
+    ? `veo changes ${selection.from ? `${selection.from} to ${selection.to}` : `up to ${selection.to}`} (${plural(versions.length)}, newest first)`
+    : `veo changes ${selection.from}`;
+  const lines = [title, ''];
+  for (const release of versions) {
+    lines.push(...releaseLines(release, stream, release.version === current, mode === 'range'));
+    lines.push('');
+  }
+  lines.pop();
+  return `${lines.join('\n')}\n`;
+}
+
+const sectionsJson = release => release.sections.filter(section => section.items.length)
+  .map(section => ({ type: section.type, items: section.items }));
+
+function changesJson(selection, current) {
+  if (selection.mode === 'list') {
+    return {
+      current,
+      count: selection.versions.length,
+      versions: selection.versions.map(release => {
+        const counts = releaseCounts(release);
+        return { version: release.version, date: release.date, installed: release.version === current, counts, summary: summary(counts) };
+      }),
+    };
+  }
+  if (selection.mode === 'range') {
+    return {
+      current,
+      from: selection.from,
+      to: selection.to,
+      count: selection.versions.length,
+      versions: selection.versions.map(release => ({
+        version: release.version, date: release.date, installed: release.version === current, sections: sectionsJson(release),
+      })),
+    };
+  }
+  const [release] = selection.versions;
+  return { current, version: release.version, date: release.date, installed: release.version === current, sections: sectionsJson(release) };
+}
+
+function versionValue(value, flag) {
+  if (!value || value.startsWith('-')) throw new Error(`${flag} requires a version number such as 1.11.0.`);
+  return value;
+}
+
+export function parseChangesArgs(args) {
+  const options = { json: false, latest: false, version: null, since: null, to: null };
+  for (let index = 0; index < args.length; index++) {
+    let arg = args[index];
+    let inline = null;
+    const equals = arg.indexOf('=');
+    if (arg.startsWith('--') && equals > 2) { inline = arg.slice(equals + 1); arg = arg.slice(0, equals); }
+    const value = () => versionValue(inline ?? args[++index], arg);
+    if (arg === '--json') options.json = true;
+    else if (arg === '--latest') options.latest = true;
+    else if (arg === '--version') options.version = value();
+    else if (arg === '--since') options.since = value();
+    else if (arg === '--to') options.to = value();
+    else if (arg === '--range') {
+      const [from, to] = value().split('..');
+      if (!from || !to) throw new Error(`--range must look like 1.9.0..1.11.0. ${USAGE}`);
+      options.since ??= from;
+      options.to ??= to;
+    } else if (arg.startsWith('-')) throw new Error(`Unknown option "${arg}". ${USAGE}`);
+    else if (!options.version) options.version = arg;
+    else throw new Error(USAGE);
+  }
+  const ranged = options.since || options.to;
+  if (options.version && (ranged || options.latest)) throw new Error(`Use either a version or --latest/--since/--to, not both. ${USAGE}`);
+  if (options.latest && ranged) throw new Error(`Use --latest on its own. ${USAGE}`);
+  return options;
+}
+
+export async function changesMain(args = [], { stdout = process.stdout, current = null, file } = {}) {
+  [args, stdout] = commandOutput(args, stdout);
+  if (args.some(arg => ['--help', '-h'].includes(arg))) {
+    stdout.write(CHANGES_HELP);
+    return 0;
+  }
+  const options = parseChangesArgs(args);
+  const installed = current ?? await packageVersion();
+  const selection = selectReleases(await readChangelog(file), options);
+  if (options.json) stdout.write(`${JSON.stringify(changesJson(selection, installed))}\n`);
+  else stdout.write(formatChanges(selection, { current: installed, stream: stdout }));
+  return 0;
+}

package/src/cli.js

@@ -93,6 +93,7 @@ Commands:
   veo history              Show the last 5 downloads (--json for scripting)
   veo retry --last         Retry the newest failed or unfinished job
   veo history --failed --limit 20  Filter and extend download history
+  veo changes [<version>]   List release notes; --since <version> for newer changes
   veo runs [id]            List active runs; add --json for metadata and progress
   veo inspect <file>        Read media metadata; --check-audio measures audio signal
   veo subs <url>            List available manual and automatic subtitles
@@ -246,6 +247,7 @@ export function cliOptions(config = {}) {
 
 const COMMAND_FLAGS = {
   stats: ['--json'], history: ['--json', '--limit', '--failed'],
+  changes: ['--json', '--version', '--since', '--to', '--range', '--latest'],
   runs: ['--json'], stop: [], flush: ['--stats'],
   inspect: ['--json', '--check-audio', '--search'],
   doctor: ['--offline', '--output', '-o'],
@@ -256,7 +258,9 @@ const COMMAND_FLAGS = {
   config: ['--profile', '--external', '--terminal'],
   profile: [],
 };
-const COMMAND_NAMES = [...Object.keys(COMMAND_FLAGS), 'retry', 'subs', 'help', 'version'];
+// `changelog` is an alias, so it shares the flags of the command it stands for.
+const ALIASES = { changelog: 'changes' };
+const COMMAND_NAMES = [...Object.keys(COMMAND_FLAGS), ...Object.keys(ALIASES), 'retry', 'subs', 'help', 'version'];
 
 function mistypedCommandOption(args) {
   const command = args[0];
@@ -264,8 +268,10 @@ function mistypedCommandOption(args) {
     const suggestion = suggestOption(command, COMMAND_NAMES);
     if (suggestion) return `Unknown command "${command}". Did you mean "${suggestion}"?`;
   }
-  const options = Object.hasOwn(COMMAND_FLAGS, command)
-    ? [...COMMAND_FLAGS[command], '--help', '-h', '--no-color', '--color', '--profile']
+  const flags = Object.hasOwn(COMMAND_FLAGS, command) ? COMMAND_FLAGS[command]
+    : ALIASES[command] ? COMMAND_FLAGS[ALIASES[command]] : null;
+  const options = flags
+    ? [...flags, '--help', '-h', '--no-color', '--color', '--profile']
     : command === 'retry' ? [...optionSpellings(cliOptions()), '--last'] : null;
   if (!options) return null; // Download flags are checked by parseCli itself.
   const start = ['config', 'backend', 'alias'].includes(command) && args[1] && !args[1].startsWith('-') ? 2 : 1;
@@ -421,7 +427,7 @@ export async function main(args = process.argv.slice(2), { config } = {}) {
     }
     // The command's own validation reports configuration errors.
   }
-  if (['stats', 'history', 'flush', 'runs', 'inspect', 'stop', 'update', 'up', 'upgrade', 'check', 'doctor', 'backend', 'alias', 'uninstall'].includes(args[0])) args = display.remaining;
+  if (['stats', 'history', 'changes', 'changelog', 'flush', 'runs', 'inspect', 'stop', 'update', 'up', 'upgrade', 'check', 'doctor', 'backend', 'alias', 'uninstall'].includes(args[0])) args = display.remaining;
   const code = await withOutputSettings(color, () => runMain(args, { config }));
   // One throttled (once per day) update hint after every successful command.
   // Failures, cancellations, help/version output and the update commands
@@ -446,7 +452,7 @@ export async function main(args = process.argv.slice(2), { config } = {}) {
 // anything else earns the daily update hint on success.
 export function shouldUpdateNotice(args = []) {
   if (args.includes('-h') || args.includes('--help') || args.includes('-v') || args.includes('--version')) return false;
-  if (['update', 'up', 'upgrade', 'check', 'version', 'help'].includes(args[0])) return false;
+  if (['update', 'up', 'upgrade', 'check', 'version', 'help', 'changes', 'changelog'].includes(args[0])) return false;
   return true;
 }
 
@@ -461,6 +467,10 @@ async function runMain(args, { config }) {
     try { return await (await import('./history.js')).historyMain(args.slice(1)); }
     catch (error) { stderr.write(`veo: ${readableError(error)}\n`); return 1; }
   }
+  if (args[0] === 'changes' || args[0] === 'changelog') {
+    try { return await (await import('./changes.js')).changesMain(args.slice(1), { stdout }); }
+    catch (error) { stderr.write(`veo: ${readableError(error)}\n`); return 1; }
+  }
   if (args[0] === 'flush') {
     try { return await (await import('./flush.js')).flushMain(args.slice(1)); }
     catch (error) { stderr.write(`veo: ${readableError(error)}\n`); return 1; }

package/src/output.js

@@ -38,7 +38,10 @@ export function formatOutput(text, stream, enabled = settings.getStore()?.enable
         || /^\s{6,}\S/.test(line)) line = indent + terminalText(available, value);
     }
     let role = 'muted';
-    if (/^(?:veo (?:stats|history|runs|stop|doctor|flush|update|backend|alias|uninstall)\b|veo \d[^ ]* doctor|ID\s+PID\s+STATE|Usage:|Options:|Commands:|Examples:|\d+\. )/.test(value)) role = 'title';
+    if (/^(?:veo (?:stats|history|changes|changelog|runs|stop|doctor|flush|update|backend|alias|uninstall)\b|veo \d[^ ]* doctor|ID\s+PID\s+STATE|Usage:|Options:|Commands:|Examples:|\d+\. )/.test(value)) role = 'title';
+    // A bare version line introduces one release in `veo changes` range output; the
+    // list rows carry a summary and stay muted.
+    if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?(?:\s+\(installed\))?$/.test(value)) role = 'title';
     if (/^(?:\[?OK\]?\s|Saved:|Flushed:|Stopped\b|Removed\b|Config OK:|Statistics reset|Managed tools are ready)|\bis up to date\b|\bupdated to\b|\binstalled and will be used\b/i.test(value)) role = 'success';
     if (/^(?:\[?FAIL\]?\s|Error:|veo: (?!note:))|Status:\s*(?:failed|cancelled)/i.test(value)) role = 'error';
     if (/Status:\s*saved/.test(value)) role = 'success';

package/src/progress.js

@@ -34,7 +34,7 @@ function fit(text, width) {
   return width > 0 ? result + '…' : '';
 }
 
-function wrap(text, width) {
+export function wrap(text, width) {
   if (!Number.isFinite(width)) return text;
   const lines = [];
   let line = '';