youtube-knowledge-mcp 2.1.0 → 3.0.0

package/dist/utils/harvest-lock.js

@@ -0,0 +1,26 @@
+import { YouTubeError } from './errors.js';
+import { ensurePrivateDir } from './paths.js';
+import { withFileLock } from './file-lock.js';
+import { channelHarvestLockPath, storeDir, videoHarvestLockPath } from './store-paths.js';
+/**
+ * Exclusive access to one harvest target.
+ *
+ * WAL already keeps concurrent writes consistent, so this is not about the
+ * rows. It is about the requests: two harvests of the same channel would each
+ * spawn yt-dlp and double the rate at the one resource that throttles us.
+ */
+function alreadyRunning(what, id, existing) {
+    const owner = existing === undefined ? '' : `Started at ${existing.startedAt} by process ${existing.pid}. `;
+    return new YouTubeError('INVALID_INPUT', `A harvest of ${what} ${id} is already running.`, {
+        nextStep: `${owner}Wait for it to finish, then call the tool again to continue where it stopped.`,
+    });
+}
+export async function withChannelHarvestLock(channelId, work) {
+    await ensurePrivateDir(storeDir());
+    return withFileLock(channelHarvestLockPath(channelId), work, (existing) => alreadyRunning('channel', channelId, existing));
+}
+export async function withVideoHarvestLock(videoId, work) {
+    await ensurePrivateDir(storeDir());
+    return withFileLock(videoHarvestLockPath(videoId), work, (existing) => alreadyRunning('video', videoId, existing));
+}
+//# sourceMappingURL=harvest-lock.js.map

package/dist/utils/harvest-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest-lock.js","sourceRoot":"","sources":["../../src/utils/harvest-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAmB,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE1F;;;;;;GAMG;AAEH,SAAS,cAAc,CAAC,IAAY,EAAE,EAAU,EAAE,QAAgC;IAChF,MAAM,KAAK,GACT,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,QAAQ,CAAC,SAAS,eAAe,QAAQ,CAAC,GAAG,IAAI,CAAC;IAEhG,OAAO,IAAI,YAAY,CAAC,eAAe,EAAE,gBAAgB,IAAI,IAAI,EAAE,sBAAsB,EAAE;QACzF,QAAQ,EAAE,GAAG,KAAK,+EAA+E;KAClG,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,SAAiB,EACjB,IAAsB;IAEtB,MAAM,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC;IACnC,OAAO,YAAY,CAAC,sBAAsB,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,EAAE,CACxE,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAC/C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,OAAe,EAAE,IAAsB;IACnF,MAAM,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC;IACnC,OAAO,YAAY,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,EAAE,CACpE,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAC3C,CAAC;AACJ,CAAC"}

package/dist/utils/harvest-receipts.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type Coverage } from '../harvest-schemas.js';
+export declare function saveReceipt(database: DatabaseSync, coverage: Coverage, options?: {
+    startedAt?: number;
+    errorCode?: string;
+}): void;
+export declare function readReceipt(database: DatabaseSync, scope: Coverage['scope'], targetId: string): Coverage | undefined;
+export declare function listReceipts(database: DatabaseSync, options?: {
+    scope?: Coverage['scope'];
+    limit?: number;
+    offset?: number;
+}): Coverage[];
+export declare function countReceipts(database: DatabaseSync, scope?: Coverage['scope']): number;
+//# sourceMappingURL=harvest-receipts.d.ts.map

package/dist/utils/harvest-receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest-receipts.d.ts","sourceRoot":"","sources":["../../src/utils/harvest-receipts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAsC,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAgE1F,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACvD,IAAI,CAsCN;AAuBD,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,EACxB,QAAQ,EAAE,MAAM,GACf,QAAQ,GAAG,SAAS,CAQtB;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3E,QAAQ,EAAE,CAwBZ;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,MAAM,CAavF"}

package/dist/utils/harvest-receipts.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { coverageSchema, harvestScopeSchema } from '../harvest-schemas.js';
+import { assertCoverageConsistent } from './coverage.js';
+import { queryRow, queryRows, sqliteBoolean } from './store-rows.js';
+/**
+ * Persisting completeness receipts.
+ *
+ * Written in the same transaction as the rows they describe. That is the whole
+ * reason this store is a database: there is no interval in which a receipt can
+ * claim something the store does not hold, so the reconciliation dance that
+ * `brain-build.ts` performs between its manifest and its chunks has no
+ * analogue here.
+ */
+const receiptRowSchema = z.object({
+    scope: harvestScopeSchema,
+    target_id: z.string(),
+    state: z.string(),
+    reason: z.string(),
+    have: z.number(),
+    expected: z.number().nullable(),
+    expected_source: z.string().nullable(),
+    source: z.string(),
+    limit_applied: z.number().nullable(),
+    sort_applied: z.string().nullable(),
+    ran_to_exhaustion: sqliteBoolean.nullable(),
+    resume_token: z.string().nullable(),
+    started_at: z.number(),
+    finished_at: z.number().nullable(),
+    attempts: z.number(),
+    error_code: z.string().nullable(),
+    note: z.string().nullable(),
+});
+const UPSERT = `
+INSERT INTO harvest_receipt (
+  scope, target_id, state, reason, have, expected, expected_source, source,
+  limit_applied, sort_applied, ran_to_exhaustion, resume_token,
+  started_at, finished_at, attempts, error_code, note
+) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+ON CONFLICT(scope, target_id) DO UPDATE SET
+  state = excluded.state, reason = excluded.reason, have = excluded.have,
+  expected = excluded.expected, expected_source = excluded.expected_source,
+  source = excluded.source, limit_applied = excluded.limit_applied,
+  sort_applied = excluded.sort_applied, ran_to_exhaustion = excluded.ran_to_exhaustion,
+  resume_token = excluded.resume_token, finished_at = excluded.finished_at,
+  attempts = harvest_receipt.attempts + 1, error_code = excluded.error_code,
+  note = excluded.note`;
+/** `complete` is the receipt's own word; the rest describe how it ended. */
+function stateOf(coverage) {
+    if (coverage.complete)
+        return 'complete';
+    if (coverage.reason === 'SOURCE_REFUSED' || coverage.reason === 'TIMEOUT')
+        return 'failed';
+    if (coverage.reason === 'NOT_ATTEMPTED')
+        return 'running';
+    return 'partial';
+}
+function toRow(coverage) {
+    // Re-checked on the way to disk as well as on the way out of coverageOf: a
+    // receipt that reaches storage wrong is one that will be believed later.
+    assertCoverageConsistent(coverage);
+    return coverage;
+}
+export function saveReceipt(database, coverage, options = {}) {
+    const checked = toRow(coverage);
+    const finishedAt = Date.parse(checked.harvestedAt);
+    database
+        .prepare(UPSERT)
+        .run(checked.scope, checked.targetId, stateOf(checked), checked.reason, checked.have, checked.expected ?? null, checked.expectedSource ?? null, checked.source, checked.limitApplied ?? null, checked.sortApplied ?? null, checked.ranToExhaustion === undefined ? null : Number(checked.ranToExhaustion), checked.resumeToken ?? null, options.startedAt ?? finishedAt, finishedAt, 0, options.errorCode ?? null, checked.note ?? null);
+    database
+        .prepare('INSERT INTO harvest_event (scope, target_id, at, state, delta, note) VALUES (?,?,?,?,?,?)')
+        .run(checked.scope, checked.targetId, finishedAt, stateOf(checked), checked.have, checked.reason);
+}
+function fromRow(row) {
+    const expected = row.expected;
+    const expectedSource = row.expected_source;
+    return coverageSchema.parse({
+        scope: row.scope,
+        targetId: row.target_id,
+        complete: row.state === 'complete',
+        reason: row.reason,
+        have: row.have,
+        ...(expected === null || expectedSource === null ? {} : { expected, expectedSource }),
+        ...(row.ran_to_exhaustion === null ? {} : { ranToExhaustion: row.ran_to_exhaustion }),
+        source: row.source,
+        harvestedAt: new Date(row.finished_at ?? row.started_at).toISOString(),
+        ...(row.limit_applied === null ? {} : { limitApplied: row.limit_applied }),
+        ...(row.sort_applied === null ? {} : { sortApplied: row.sort_applied }),
+        ...(row.resume_token === null ? {} : { resumeToken: row.resume_token }),
+        ...(row.note === null ? {} : { note: row.note }),
+    });
+}
+export function readReceipt(database, scope, targetId) {
+    const row = queryRow(database.prepare('SELECT * FROM harvest_receipt WHERE scope = ? AND target_id = ?'), receiptRowSchema, scope, targetId);
+    return row === undefined ? undefined : fromRow(row);
+}
+export function listReceipts(database, options = {}) {
+    const limit = options.limit ?? 50;
+    const offset = options.offset ?? 0;
+    const rows = options.scope === undefined
+        ? queryRows(database.prepare('SELECT * FROM harvest_receipt ORDER BY finished_at DESC, target_id LIMIT ? OFFSET ?'), receiptRowSchema, limit, offset)
+        : queryRows(database.prepare('SELECT * FROM harvest_receipt WHERE scope = ? ORDER BY finished_at DESC, target_id LIMIT ? OFFSET ?'), receiptRowSchema, options.scope, limit, offset);
+    return rows.map(fromRow);
+}
+export function countReceipts(database, scope) {
+    const row = scope === undefined
+        ? queryRow(database.prepare('SELECT COUNT(*) AS n FROM harvest_receipt'), z.object({ n: z.number() }))
+        : queryRow(database.prepare('SELECT COUNT(*) AS n FROM harvest_receipt WHERE scope = ?'), z.object({ n: z.number() }), scope);
+    return row?.n ?? 0;
+}
+//# sourceMappingURL=harvest-receipts.js.map

package/dist/utils/harvest-receipts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest-receipts.js","sourceRoot":"","sources":["../../src/utils/harvest-receipts.ts"],"names":[],"mappings":"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"}

package/dist/utils/image-dimensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reading an image's format and size from its first bytes.
+ *
+ * The manifest a thumbnail job writes records what was actually saved — a
+ * JPEG of 1280 by 720, say — and it must not take that from the URL's name or
+ * the server's Content-Type, both of which describe what was asked for rather
+ * than what arrived. Three container formats cover what YouTube's image hosts
+ * serve; anything else is reported as unknown rather than guessed.
+ */
+export type ImageFormat = 'jpg' | 'png' | 'webp';
+export interface ImageProbe {
+    format: ImageFormat;
+    width: number;
+    height: number;
+    mimeType: string;
+}
+/** The format and pixel size of an image, or `undefined` when the bytes are not one this reads. */
+export declare function probeImage(bytes: Uint8Array): ImageProbe | undefined;
+//# sourceMappingURL=image-dimensions.d.ts.map

package/dist/utils/image-dimensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-dimensions.d.ts","sourceRoot":"","sources":["../../src/utils/image-dimensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AA4FD,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAKpE"}

package/dist/utils/image-dimensions.js

@@ -0,0 +1,93 @@
+/**
+ * Reading an image's format and size from its first bytes.
+ *
+ * The manifest a thumbnail job writes records what was actually saved — a
+ * JPEG of 1280 by 720, say — and it must not take that from the URL's name or
+ * the server's Content-Type, both of which describe what was asked for rather
+ * than what arrived. Three container formats cover what YouTube's image hosts
+ * serve; anything else is reported as unknown rather than guessed.
+ */
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+function startsWith(bytes, signature, at = 0) {
+    return signature.every((byte, index) => bytes[at + index] === byte);
+}
+function ascii(bytes, from, length) {
+    return String.fromCharCode(...bytes.subarray(from, from + length));
+}
+/** Every caller checks the length first, so a read here is always in range. */
+function view(bytes) {
+    return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+function be16(bytes, at) {
+    return view(bytes).getUint16(at);
+}
+function be32(bytes, at) {
+    return view(bytes).getUint32(at);
+}
+function le16(bytes, at) {
+    return view(bytes).getUint16(at, true);
+}
+function le24(bytes, at) {
+    return le16(bytes, at) | (view(bytes).getUint8(at + 2) << 16);
+}
+/** Start-of-frame markers carry the dimensions; C4, C8 and CC are other things. */
+function isStartOfFrame(marker) {
+    return marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+}
+function probeJpeg(bytes) {
+    let at = 2;
+    while (at + 9 < bytes.length) {
+        if (bytes[at] !== 0xff)
+            return undefined;
+        const marker = view(bytes).getUint8(at + 1);
+        // Standalone markers have no length field.
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            at += 2;
+            continue;
+        }
+        // Scan data or end of image: no frame header was found before it.
+        if (marker === 0xda || marker === 0xd9)
+            return undefined;
+        if (isStartOfFrame(marker)) {
+            return sized('jpg', 'image/jpeg', be16(bytes, at + 7), be16(bytes, at + 5));
+        }
+        at += 2 + be16(bytes, at + 2);
+    }
+    return undefined;
+}
+function probePng(bytes) {
+    if (bytes.length < 24 || ascii(bytes, 12, 4) !== 'IHDR')
+        return undefined;
+    return sized('png', 'image/png', be32(bytes, 16), be32(bytes, 20));
+}
+function probeWebp(bytes) {
+    if (bytes.length < 30 || ascii(bytes, 8, 4) !== 'WEBP')
+        return undefined;
+    switch (ascii(bytes, 12, 4)) {
+        case 'VP8 ':
+            return sized('webp', 'image/webp', le16(bytes, 26) & 0x3fff, le16(bytes, 28) & 0x3fff);
+        case 'VP8L': {
+            const bits = view(bytes).getUint32(21, true);
+            return sized('webp', 'image/webp', (bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+        }
+        case 'VP8X':
+            return sized('webp', 'image/webp', le24(bytes, 24) + 1, le24(bytes, 27) + 1);
+        default:
+            return undefined;
+    }
+}
+function sized(format, mimeType, width, height) {
+    return width > 0 && height > 0 ? { format, mimeType, width, height } : undefined;
+}
+/** The format and pixel size of an image, or `undefined` when the bytes are not one this reads. */
+export function probeImage(bytes) {
+    if (startsWith(bytes, JPEG_SIGNATURE))
+        return probeJpeg(bytes);
+    if (startsWith(bytes, PNG_SIGNATURE))
+        return probePng(bytes);
+    if (bytes.length >= 12 && ascii(bytes, 0, 4) === 'RIFF')
+        return probeWebp(bytes);
+    return undefined;
+}
+//# sourceMappingURL=image-dimensions.js.map

package/dist/utils/image-dimensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-dimensions.js","sourceRoot":"","sources":["../../src/utils/image-dimensions.ts"],"names":[],"mappings":"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"}

package/dist/utils/image-fetch.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The one place this server fetches anything over HTTP itself.
+ *
+ * Everything else goes through yt-dlp. Thumbnails are the exception because
+ * their URLs are known from a single channel listing, and asking yt-dlp to
+ * extract each video just to download its image would multiply the requests
+ * YouTube sees by the size of the channel. The fetch is deliberately narrow:
+ * an allowlist of image hosts, https only, redirects re-checked hop by hop, a
+ * timeout, a byte cap enforced while reading, and an image content type.
+ */
+export declare const IMAGE_HOSTS: readonly ["i.ytimg.com", "yt3.googleusercontent.com", "yt3.ggpht.com"];
+export declare const IMAGE_TIMEOUT_MS = 20000;
+/** Cap for images written to disk. */
+export declare const MAX_IMAGE_BYTES: number;
+/** Cap for images returned inline as base64; a 1280x720 JPEG is about 140 KB. */
+export declare const MAX_INLINE_IMAGE_BYTES: number;
+export interface FetchImageOptions {
+    maxBytes?: number;
+    timeoutMs?: number;
+}
+export interface FetchedImage {
+    bytes: Buffer;
+    contentType: string;
+    /** The URL the bytes came from, after any redirects. */
+    url: string;
+}
+/** Validate an image URL against the allowlist, returning it parsed. */
+export declare function assertImageUrl(input: string): URL;
+/** Fetch one image into memory, or throw a typed error saying why not. */
+export declare function fetchImage(input: string, options?: FetchImageOptions): Promise<FetchedImage>;
+//# sourceMappingURL=image-fetch.d.ts.map

package/dist/utils/image-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-fetch.d.ts","sourceRoot":"","sources":["../../src/utils/image-fetch.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,eAAO,MAAM,WAAW,wEAAyE,CAAC;AAClG,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,sCAAsC;AACtC,eAAO,MAAM,eAAe,QAAkB,CAAC;AAC/C,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AAKtD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAcjD;AAgBD,0EAA0E;AAC1E,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,YAAY,CAAC,CA0CvB"}

package/dist/utils/image-fetch.js

@@ -0,0 +1,141 @@
+import { currentContext } from './context.js';
+import { YouTubeError } from './errors.js';
+/**
+ * The one place this server fetches anything over HTTP itself.
+ *
+ * Everything else goes through yt-dlp. Thumbnails are the exception because
+ * their URLs are known from a single channel listing, and asking yt-dlp to
+ * extract each video just to download its image would multiply the requests
+ * YouTube sees by the size of the channel. The fetch is deliberately narrow:
+ * an allowlist of image hosts, https only, redirects re-checked hop by hop, a
+ * timeout, a byte cap enforced while reading, and an image content type.
+ */
+export const IMAGE_HOSTS = ['i.ytimg.com', 'yt3.googleusercontent.com', 'yt3.ggpht.com'];
+export const IMAGE_TIMEOUT_MS = 20_000;
+/** Cap for images written to disk. */
+export const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+/** Cap for images returned inline as base64; a 1280x720 JPEG is about 140 KB. */
+export const MAX_INLINE_IMAGE_BYTES = 2 * 1024 * 1024;
+const MAX_REDIRECTS = 3;
+const HOST_SET = new Set(IMAGE_HOSTS);
+/** Validate an image URL against the allowlist, returning it parsed. */
+export function assertImageUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw notAllowed(input);
+    }
+    const allowed = url.protocol === 'https:' &&
+        HOST_SET.has(url.hostname.toLowerCase()) &&
+        url.username === '' &&
+        url.password === '';
+    if (!allowed)
+        throw notAllowed(input);
+    return url;
+}
+function notAllowed(input) {
+    const shown = input.length > 96 ? `${input.slice(0, 93)}...` : input;
+    return new YouTubeError('INVALID_INPUT', `"${shown}" is not a YouTube image URL.`, {
+        nextStep: `Images are only fetched over https from ${IMAGE_HOSTS.join(', ')}.`,
+    });
+}
+function failed(message, cause) {
+    return new YouTubeError('FETCH_FAILED', message, {
+        nextStep: 'Retry later; if it keeps failing, the image may have been removed.',
+        cause,
+    });
+}
+/** Fetch one image into memory, or throw a typed error saying why not. */
+export async function fetchImage(input, options = {}) {
+    const { maxBytes = MAX_IMAGE_BYTES, timeoutMs = IMAGE_TIMEOUT_MS } = options;
+    const request = currentContext().signal;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = request === undefined ? timeout : AbortSignal.any([timeout, request]);
+    let url = assertImageUrl(input);
+    for (let hop = 0;; hop++) {
+        const response = await send(url, signal, request);
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (location === null || hop >= MAX_REDIRECTS)
+                throw failed('The image URL redirected too far.');
+            // Re-validated: a redirect is a URL the server chose, not the caller.
+            url = assertImageUrl(new URL(location, url).toString());
+            continue;
+        }
+        if (response.status === 404)
+            throw new YouTubeError('NOT_FOUND', 'There is no image at that size.');
+        if (response.status === 429) {
+            throw new YouTubeError('RATE_LIMITED', 'YouTube is rate limiting image downloads.', {
+                nextStep: 'Wait a minute before retrying.',
+                retryable: true,
+            });
+        }
+        if (!response.ok)
+            throw failed(`The image host answered ${response.status}.`);
+        const contentType = mediaType(response.headers.get('content-type') ?? '');
+        if (!contentType.startsWith('image/'))
+            throw failed('The response was not an image.');
+        const declared = Number(response.headers.get('content-length') ?? '0');
+        if (declared > maxBytes)
+            throw failed(`The image is larger than ${maxBytes} bytes.`);
+        return {
+            bytes: await readCapped(response, maxBytes, signal, request),
+            contentType,
+            url: url.toString(),
+        };
+    }
+}
+async function send(url, signal, request) {
+    try {
+        return await fetch(url, { redirect: 'manual', signal });
+    }
+    catch (error) {
+        throw translate(error, request);
+    }
+}
+/** The media type of a Content-Type header, without its parameters. */
+function mediaType(header) {
+    const semicolon = header.indexOf(';');
+    return header.slice(0, semicolon === -1 ? header.length : semicolon).trim();
+}
+/** Read the body, refusing to go past the cap whatever Content-Length claimed. */
+async function readCapped(response, maxBytes, signal, request) {
+    if (response.body === null)
+        return Buffer.alloc(0);
+    // A reader rather than `for await`: the cap has to cancel the stream from
+    // inside the loop, and the async iterator holds the lock that cancel needs.
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (let next = await reader.read(); !next.done; next = await reader.read()) {
+            total += next.value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                throw failed(`The image is larger than ${maxBytes} bytes.`);
+            }
+            chunks.push(next.value);
+        }
+    }
+    catch (error) {
+        if (error instanceof YouTubeError)
+            throw error;
+        throw translate(error, request, signal);
+    }
+    return Buffer.concat(chunks);
+}
+function translate(error, request, signal) {
+    if (request?.aborted === true)
+        return new YouTubeError('CANCELLED', 'The request was cancelled.');
+    const timedOut = (error instanceof Error && error.name === 'TimeoutError') || signal?.aborted === true;
+    if (timedOut) {
+        return new YouTubeError('TIMEOUT', 'The image host did not respond in time.', {
+            nextStep: 'Retry; the host may be slow.',
+            retryable: true,
+        });
+    }
+    return failed('The image could not be downloaded.', error);
+}
+//# sourceMappingURL=image-fetch.js.map

package/dist/utils/image-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-fetch.js","sourceRoot":"","sources":["../../src/utils/image-fetch.ts"],"names":[],"mappings":"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"}

package/dist/utils/json-file.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
 /**
- * Reading and writing the JSON documents this server keeps on disk.
+ * Reading and writing the documents this server keeps on disk.
  *
  * Both halves exist because the library and the brains make the same two
  * mistakes otherwise. Writing straight to the destination means an interrupted
@@ -10,20 +10,29 @@ import type { z } from 'zod';
  * file edited by hand, or truncated by that same crash, propagates `undefined`
  * into code that assumed a shape.
  */
-export interface WriteJsonOptions {
+export interface WriteFileOptions {
+    /** Permission bits for the new file. Owner-only by default: these are the user's notes and caches. */
+    mode?: number;
+}
+export interface WriteJsonOptions extends WriteFileOptions {
     /**
      * Indent the output. Worth it for files a human may open; not for a search
      * index, where indentation is most of the bytes.
      */
     pretty?: boolean;
 }
+export declare const PRIVATE_FILE_MODE = 384;
 /**
- * Write JSON through a temporary file and rename it into place.
+ * Write a file through a temporary name and rename it into place.
  *
+ * The data is flushed to disk before the rename: without `fsync` a power loss
+ * after the rename could leave a zero-length file under the final name, which
+ * is exactly the half-written document the rename was meant to rule out.
  * `rename` within a directory is atomic on POSIX and on Windows via
- * `MoveFileEx`, so a reader sees either the previous document or the new one,
- * never a partial write.
+ * `MoveFileEx`, so a reader sees either the previous document or the new one.
  */
+export declare function writeFileAtomic(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>;
+/** Serialise and write a JSON document atomically. */
 export declare function writeJsonAtomic(path: string, value: unknown, options?: WriteJsonOptions): Promise<void>;
 /**
  * Read and validate a JSON document, or `undefined` if it is missing,

package/dist/utils/json-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-file.d.ts","sourceRoot":"","sources":["../../src/utils/json-file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,GAC1C,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CASxB"}
+{"version":3,"file":"json-file.d.ts","sourceRoot":"","sources":["../../src/utils/json-file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,sGAAsG;IACtG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,iBAAiB,MAAQ,CAAC;AAIvC;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,sDAAsD;AACtD,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,GAC1C,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CASxB"}

package/dist/utils/json-file.js

@@ -1,21 +1,31 @@
 import { existsSync } from 'node:fs';
-import { readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { open, readFile, rename, rm } from 'node:fs/promises';
+export const PRIVATE_FILE_MODE = 0o600;
+let writeSequence = 0;
 /**
- * Write JSON through a temporary file and rename it into place.
+ * Write a file through a temporary name and rename it into place.
  *
+ * The data is flushed to disk before the rename: without `fsync` a power loss
+ * after the rename could leave a zero-length file under the final name, which
+ * is exactly the half-written document the rename was meant to rule out.
  * `rename` within a directory is atomic on POSIX and on Windows via
- * `MoveFileEx`, so a reader sees either the previous document or the new one,
- * never a partial write.
+ * `MoveFileEx`, so a reader sees either the previous document or the new one.
  */
-export async function writeJsonAtomic(path, value, options = {}) {
-    const { pretty = true } = options;
-    const serialised = JSON.stringify(value, null, pretty ? 2 : undefined);
+export async function writeFileAtomic(path, data, options = {}) {
+    const { mode = PRIVATE_FILE_MODE } = options;
     // A shared temporary name would let two writers of the same document destroy
     // each other's staging file, and the loser's rename would fail on a path that
     // the winner had already moved away.
     const temporaryPath = `${path}.${process.pid}.${writeSequence++}.tmp`;
     try {
-        await writeFile(temporaryPath, serialised, 'utf-8');
+        const handle = await open(temporaryPath, 'w', mode);
+        try {
+            await handle.writeFile(data);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
         await rename(temporaryPath, path);
     }
     catch (error) {
@@ -23,7 +33,12 @@ export async function writeJsonAtomic(path, value, options = {}) {
         throw error;
     }
 }
-let writeSequence = 0;
+/** Serialise and write a JSON document atomically. */
+export async function writeJsonAtomic(path, value, options = {}) {
+    const { pretty = true, ...fileOptions } = options;
+    const serialised = JSON.stringify(value, null, pretty ? 2 : undefined);
+    await writeFileAtomic(path, serialised, fileOptions);
+}
 /**
  * Read and validate a JSON document, or `undefined` if it is missing,
  * unparseable or does not match.

package/dist/utils/json-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"json-file.js","sourceRoot":"","sources":["../../src/utils/json-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAuBnE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,KAAc,EACd,UAA4B,EAAE;IAE9B,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAClC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAEvE,6EAA6E;IAC7E,8EAA8E;IAC9E,qCAAqC;IACrC,MAAM,aAAa,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,aAAa,EAAE,MAAM,CAAC;IAEtE,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,aAAa,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,IAAI,aAAa,GAAG,CAAC,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,MAA2C;IAE3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAExC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3E,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"json-file.js","sourceRoot":"","sources":["../../src/utils/json-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AA4B9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC,IAAI,aAAa,GAAG,CAAC,CAAC;AAEtB;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,IAAyB,EACzB,UAA4B,EAAE;IAE9B,MAAM,EAAE,IAAI,GAAG,iBAAiB,EAAE,GAAG,OAAO,CAAC;IAE7C,6EAA6E;IAC7E,8EAA8E;IAC9E,qCAAqC;IACrC,MAAM,aAAa,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,aAAa,EAAE,MAAM,CAAC;IAEtE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC7B,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QACD,MAAM,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,sDAAsD;AACtD,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,KAAc,EACd,UAA4B,EAAE;IAE9B,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,WAAW,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvE,MAAM,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,MAA2C;IAE3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAExC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3E,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/utils/listing-cursor.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/**
+ * The cursor `fetch_videos` hands back.
+ *
+ * YouTube's listings are continuation-paginated, so `--playlist-items 101:120`
+ * still walks from the start: paging server-side is O(n) per page and O(n^2)
+ * overall. It is also not a cursor in any useful sense — a new upload shifts
+ * every index by one, so an offset silently re-reads or skips at the seam.
+ *
+ * So the cursor carries the next index *and* the id of the last item already
+ * returned. If that id reappears on the next page the listing moved under us,
+ * and the duplicate is dropped rather than handed over twice.
+ */
+declare const cursorSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    start: z.ZodNumber;
+    anchor: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    anchor: string;
+    start: number;
+    v: 1;
+}, {
+    anchor: string;
+    start: number;
+    v: 1;
+}>;
+export type ListingCursor = z.infer<typeof cursorSchema>;
+export declare function encodeCursor(cursor: ListingCursor): string;
+export declare function decodeCursor(token: string): ListingCursor;
+export {};
+//# sourceMappingURL=listing-cursor.d.ts.map

package/dist/utils/listing-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing-cursor.d.ts","sourceRoot":"","sources":["../../src/utils/listing-cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AAEH,QAAA,MAAM,YAAY;;;;;;;;;;;;EAIhB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE1D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAezD"}