youtube-knowledge-mcp 2.2.0 → 3.0.1

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/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"}

package/dist/utils/listing-cursor.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { YouTubeError } from './errors.js';
+/**
+ * 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.
+ */
+const cursorSchema = z.object({
+    v: z.literal(1),
+    start: z.number().int().min(1),
+    anchor: z.string(),
+});
+export function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
+}
+export function decodeCursor(token) {
+    const parsed = (() => {
+        try {
+            return JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const result = cursorSchema.safeParse(parsed);
+    if (result.success)
+        return result.data;
+    throw new YouTubeError('INVALID_INPUT', 'That cursor is not one this server issued.', {
+        nextStep: 'Omit `cursor` to start from the first page.',
+    });
+}
+//# sourceMappingURL=listing-cursor.js.map

package/dist/utils/listing-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing-cursor.js","sourceRoot":"","sources":["../../src/utils/listing-cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;GAWG;AAEH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAIH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,MAAM,GAAG,CAAC,GAAY,EAAE;QAC5B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAEvC,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,4CAA4C,EAAE;QACpF,QAAQ,EAAE,6CAA6C;KACxD,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/local-transcription.d.ts

@@ -0,0 +1,14 @@
+import { type TranscriptResult } from './transcript-cache.js';
+/**
+ * Turning a video's audio into a transcript when YouTube has no captions for it.
+ *
+ * Slow and CPU-heavy by nature, so it only ever runs when asked for, and what it
+ * produces is kept: a transcription is deterministic and takes minutes to redo.
+ */
+export interface LocalTranscriptionOptions {
+    language?: string;
+    /** Transcribe again even if a kept transcription exists. */
+    refresh?: boolean;
+}
+export declare function transcribeLocally(urlOrId: string, options: LocalTranscriptionOptions): Promise<TranscriptResult>;
+//# sourceMappingURL=local-transcription.d.ts.map

package/dist/utils/local-transcription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-transcription.d.ts","sourceRoot":"","sources":["../../src/utils/local-transcription.ts"],"names":[],"mappings":"AAYA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAO/E;;;;;GAKG;AAEH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAcD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAmE3B"}

package/dist/utils/local-transcription.js

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { YouTubeError } from './errors.js';
+import { ensurePrivateDir } from './paths.js';
+import { requireFfmpeg } from './preflight.js';
+import { TRANSCRIPT_DIR, asrPath, readTranscriptFile, writeTranscriptFile, } from './transcript-files.js';
+import { resultFromEntry } from './transcript-cache.js';
+import { TRANSCRIPT_CACHE_VERSION, segmentsToText } from './transcript.js';
+import { assertLanguageTag } from './validate.js';
+import { requireWhisper, runWhisper } from './whisper.js';
+import { extractVideoId, watchUrl } from './youtube-url.js';
+import { TIMEOUTS, runYtDlp } from './ytdlp.js';
+/** What yt-dlp is told to leave behind: whisper reads 16 kHz mono, so make it that size. */
+const AUDIO_ARGS = [
+    '-f',
+    'bestaudio',
+    '-x',
+    '--audio-format',
+    'wav',
+    '--postprocessor-args',
+    'ExtractAudio:-ar 16000 -ac 1',
+    '--no-playlist',
+];
+export async function transcribeLocally(urlOrId, options) {
+    const language = options.language ?? 'en';
+    const videoId = extractVideoId(urlOrId);
+    assertLanguageTag(language);
+    if (options.refresh !== true) {
+        const kept = await readTranscriptFile(asrPath(videoId, language), { expires: false });
+        if (kept)
+            return resultFromEntry(kept, videoId, 'local-asr');
+    }
+    // Cheap local checks first: a missing tool should fail now, not after the audio
+    // has been downloaded.
+    await requireFfmpeg('Local transcription');
+    const modelPath = await requireWhisper('Local transcription');
+    const tempDir = join(TRANSCRIPT_DIR, 'temp');
+    await ensurePrivateDir(tempDir);
+    // A folder of its own for this call: yt-dlp leaves the original download and `.part`
+    // files beside the wav it makes, and two calls for one video must not share, then
+    // delete, each other's audio. The whole folder goes when this call does.
+    const workDir = await mkdtemp(join(tempDir, `${videoId}-`));
+    const audioBase = join(workDir, 'audio');
+    const audioPath = `${audioBase}.wav`;
+    try {
+        await runYtDlp([...AUDIO_ARGS, '-o', `${audioBase}.%(ext)s`], {
+            label: 'transcribe_video',
+            timeoutMs: TIMEOUTS.download,
+            retry: false,
+            target: watchUrl(videoId),
+        });
+        if (!existsSync(audioPath)) {
+            throw new YouTubeError('YTDLP_FAILED', 'yt-dlp did not produce the audio to transcribe.', {
+                nextStep: 'Check the video is playable, or call check_health.',
+            });
+        }
+        const segments = await runWhisper(audioPath, language, modelPath, join(workDir, 'whisper'));
+        if (segments.length === 0) {
+            throw new YouTubeError('NOT_FOUND', 'No speech was found in this video’s audio.', {
+                nextStep: 'The audio may be music or silence, or the model may not know this language. Try a larger model or another language.',
+            });
+        }
+        const entry = {
+            version: TRANSCRIPT_CACHE_VERSION,
+            videoId,
+            language,
+            fetchedAt: new Date().toISOString(),
+            segments,
+        };
+        await writeTranscriptFile(asrPath(videoId, language), entry);
+        return {
+            transcript: segmentsToText(segments),
+            segments,
+            language,
+            videoId,
+            cached: false,
+            source: 'local-asr',
+        };
+    }
+    finally {
+        await rm(workDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=local-transcription.js.map

package/dist/utils/local-transcription.js.map

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

package/dist/utils/moment.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/**
+ * A point in a video, in every form a caller needs it.
+ *
+ * Frames, contact-sheet cells and scene cuts all answer "when", and each used to
+ * need the same three spellings of it: seconds to compute with, a clock reading to
+ * show a person, and a link that opens the video there.
+ */
+export declare const videoMomentSchema: z.ZodObject<{
+    timestampSeconds: z.ZodNumber;
+    timestamp: z.ZodString;
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    timestamp: string;
+    timestampSeconds: number;
+}, {
+    url: string;
+    timestamp: string;
+    timestampSeconds: number;
+}>;
+export type VideoMoment = z.infer<typeof videoMomentSchema>;
+export declare function videoMoment(videoId: string, seconds: number): VideoMoment;
+//# sourceMappingURL=moment.d.ts.map

package/dist/utils/moment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moment.d.ts","sourceRoot":"","sources":["../../src/utils/moment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAI5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAMzE"}

package/dist/utils/moment.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { deepLink, formatTimestamp } from './transcript.js';
+/**
+ * A point in a video, in every form a caller needs it.
+ *
+ * Frames, contact-sheet cells and scene cuts all answer "when", and each used to
+ * need the same three spellings of it: seconds to compute with, a clock reading to
+ * show a person, and a link that opens the video there.
+ */
+export const videoMomentSchema = z.object({
+    timestampSeconds: z.number(),
+    timestamp: z.string().describe('Clock reading, H:MM:SS or M:SS'),
+    url: z.string().describe('Link that opens the video at this moment'),
+});
+export function videoMoment(videoId, seconds) {
+    return {
+        timestampSeconds: seconds,
+        timestamp: formatTimestamp(seconds),
+        url: deepLink(videoId, seconds),
+    };
+}
+//# sourceMappingURL=moment.js.map

package/dist/utils/moment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moment.js","sourceRoot":"","sources":["../../src/utils/moment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5D;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE;IAC5B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IAChE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CACrE,CAAC,CAAC;AAIH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,OAAe;IAC1D,OAAO;QACL,gBAAgB,EAAE,OAAO;QACzB,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC;QACnC,GAAG,EAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;KAChC,CAAC;AACJ,CAAC"}

package/dist/utils/most-replayed.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The moments of a video people replay most.
+ *
+ * YouTube's heatmap is a hundred or so equal slices, each scored from 0 to 1. A
+ * spike spans several adjacent slices, so taking the highest-scoring slices would
+ * return one spike over and over; instead each moment reserves the slices around it.
+ */
+export interface HeatSegment {
+    startSeconds: number;
+    endSeconds: number;
+    value: number;
+}
+/** Up to `count` distinct moments, strongest first. */
+export declare function mostReplayed(heatmap: HeatSegment[], count: number): HeatSegment[];
+//# sourceMappingURL=most-replayed.d.ts.map

package/dist/utils/most-replayed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"most-replayed.d.ts","sourceRoot":"","sources":["../../src/utils/most-replayed.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAUD,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CASjF"}

package/dist/utils/most-replayed.js

@@ -0,0 +1,25 @@
+/**
+ * The moments of a video people replay most.
+ *
+ * YouTube's heatmap is a hundred or so equal slices, each scored from 0 to 1. A
+ * spike spans several adjacent slices, so taking the highest-scoring slices would
+ * return one spike over and over; instead each moment reserves the slices around it.
+ */
+/** A moment keeps this many slice-widths clear on either side of it. */
+const SPACING_IN_SEGMENTS = 3;
+function isClearOf(segment, chosen) {
+    const reach = SPACING_IN_SEGMENTS * (segment.endSeconds - segment.startSeconds);
+    return chosen.every((peak) => Math.abs(segment.startSeconds - peak.startSeconds) >= reach);
+}
+/** Up to `count` distinct moments, strongest first. */
+export function mostReplayed(heatmap, count) {
+    const chosen = [];
+    for (const segment of [...heatmap].sort((a, b) => b.value - a.value)) {
+        if (chosen.length >= count)
+            break;
+        if (isClearOf(segment, chosen))
+            chosen.push(segment);
+    }
+    return chosen;
+}
+//# sourceMappingURL=most-replayed.js.map

package/dist/utils/most-replayed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"most-replayed.js","sourceRoot":"","sources":["../../src/utils/most-replayed.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,wEAAwE;AACxE,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,SAAS,SAAS,CAAC,OAAoB,EAAE,MAAqB;IAC5D,MAAM,KAAK,GAAG,mBAAmB,GAAG,CAAC,OAAO,CAAC,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,CAAC;AAC7F,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,OAAsB,EAAE,KAAa;IAChE,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACrE,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK;YAAE,MAAM;QAClC,IAAI,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/pot-preflight.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session preflight: what yt-dlp can prove about itself before we ask YouTube
+ * anything.
+ *
+ * Measured on 2026-09-06: with no PO token provider installed, every *player*
+ * request from this host failed with "Sign in to confirm you're not a bot",
+ * while flat listings were never affected. Rotating `player_client` across six
+ * clients and waiting out a 15-minute cooldown both failed. The cause was not
+ * rate limiting and not the address alone — `yt-dlp -v` reported
+ * `PO Token Providers: none`, so every player request went out without the
+ * integrity token a browser attaches.
+ *
+ * That diagnosis is only useful if the server can see it, so this module reads
+ * it out of yt-dlp's own debug output rather than guessing. It is deliberately
+ * provider-agnostic: it reports what yt-dlp says it has, and never looks for a
+ * particular plugin by name.
+ */
+export interface ProviderStatus {
+    name: string;
+    available: boolean;
+    /** Flags yt-dlp printed in parentheses, e.g. "external". */
+    flags: string[];
+}
+export interface SessionReport {
+    /** False when yt-dlp reports no usable PO token provider. */
+    potAvailable: boolean;
+    potProviders: ProviderStatus[];
+    jsRuntimes: ProviderStatus[];
+    impersonateTargets: string[];
+    /** Set when the probe itself could not run; the report is then unknown, not empty. */
+    probeFailed?: string;
+}
+/**
+ * Split on commas that separate entries, not the ones inside a parenthesised
+ * flag list. yt-dlp prints `bgutil:http-1.3.2 (external, unavailable)` — a
+ * plain `split(',')` tears that entry in half and loses the flag that matters.
+ */
+export declare function splitTopLevel(value: string): string[];
+/** Parses one `Providers: ...` payload. `none` is an empty list, not a provider. */
+export declare function parseProviderList(payload: string): ProviderStatus[];
+/**
+ * Reads `yt-dlp --list-impersonate-targets`, keeping only rows that are
+ * actually usable. Every target is unavailable without curl_cffi, and passing
+ * `--impersonate` to a build that lacks it fails every spawn — so an
+ * unavailable target must be visible here rather than discovered per request.
+ */
+export declare function parseImpersonateTargets(stdout: string): string[];
+export declare function runSessionPreflight(options?: {
+    force?: boolean;
+}): Promise<SessionReport>;
+/** Test seam — the report is cached for the process lifetime in normal use. */
+export declare function resetSessionPreflightCache(): void;
+//# sourceMappingURL=pot-preflight.d.ts.map

package/dist/utils/pot-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pot-preflight.d.ts","sourceRoot":"","sources":["../../src/utils/pot-preflight.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAyBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBrD;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBhE;AAqBD,wBAAsB,mBAAmB,CACvC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,aAAa,CAAC,CAwCxB;AAED,+EAA+E;AAC/E,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD"}

package/dist/utils/pot-preflight.js

@@ -0,0 +1,146 @@
+import { execa } from 'execa';
+const PROBE_TIMEOUT_MS = 30_000;
+const FAILED_REPORT_TTL_MS = 60_000;
+/**
+ * The `[youtube] [pot]` and `[youtube] [jsc]` debug lines are emitted only when
+ * the *video* extractor initialises. Measured 2026-09-06: `--version`,
+ * `ytsearch0:` and a `--flat-playlist` channel walk all produce neither line —
+ * the listing plane never touches either subsystem.
+ *
+ * So the probe uses a syntactically valid but nonexistent video id. yt-dlp
+ * initialises the extractor, prints both lines, then fails the lookup. That
+ * failure is expected and ignored: it costs one request, depends on no real
+ * video continuing to exist, and needs no fixture to be kept up to date.
+ */
+const PROBE_VIDEO_URL = 'https://www.youtube.com/watch?v=00000000000';
+const PROBE_ARGS = ['-v', '--simulate', '--skip-download', PROBE_VIDEO_URL];
+const POT_LINE = /PO Token Providers:\s*(.+)$/;
+const JSC_LINE = /JS Challenge Providers:\s*(.+)$/;
+let cached;
+let cachedAt = 0;
+/**
+ * Split on commas that separate entries, not the ones inside a parenthesised
+ * flag list. yt-dlp prints `bgutil:http-1.3.2 (external, unavailable)` — a
+ * plain `split(',')` tears that entry in half and loses the flag that matters.
+ */
+export function splitTopLevel(value) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const char = value[i];
+        if (char === '(')
+            depth += 1;
+        else if (char === ')')
+            depth = Math.max(0, depth - 1);
+        else if (char === ',' && depth === 0) {
+            parts.push(value.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(value.slice(start));
+    return parts.map((part) => part.trim()).filter((part) => part.length > 0);
+}
+/** Parses one `Providers: ...` payload. `none` is an empty list, not a provider. */
+export function parseProviderList(payload) {
+    const trimmed = payload.trim();
+    if (trimmed === '' || trimmed.toLowerCase() === 'none')
+        return [];
+    return splitTopLevel(trimmed).map((entry) => {
+        const match = /^(.*?)\s*\((.*)\)$/.exec(entry);
+        if (match === null)
+            return { name: entry, available: true, flags: [] };
+        const flags = splitTopLevel(match[2] ?? '').map((flag) => flag.toLowerCase());
+        return {
+            name: (match[1] ?? '').trim(),
+            available: !flags.includes('unavailable'),
+            flags,
+        };
+    });
+}
+/**
+ * Reads `yt-dlp --list-impersonate-targets`, keeping only rows that are
+ * actually usable. Every target is unavailable without curl_cffi, and passing
+ * `--impersonate` to a build that lacks it fails every spawn — so an
+ * unavailable target must be visible here rather than discovered per request.
+ */
+export function parseImpersonateTargets(stdout) {
+    const targets = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('[') || line.startsWith('-'))
+            continue;
+        if (line.toLowerCase().startsWith('client'))
+            continue;
+        if (line.toLowerCase().includes('(unavailable)'))
+            continue;
+        const columns = line.split(/\s{2,}/).filter((column) => column.length > 0);
+        const client = columns[0]?.trim();
+        if (client === undefined || client === '')
+            continue;
+        const os = columns[1]?.trim();
+        targets.push(os === undefined || os === '' || os === '-' ? client : `${client}:${os}`);
+    }
+    return targets;
+}
+async function probe(args) {
+    try {
+        // yt-dlp writes debug lines to stderr and exits non-zero on some probes;
+        // `reject: false` keeps both streams instead of throwing them away.
+        const result = await execa('yt-dlp', args, { timeout: PROBE_TIMEOUT_MS, reject: false });
+        return { stdout: result.stdout, stderr: result.stderr };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readProviders(output, pattern) {
+    for (const line of output.split('\n')) {
+        const match = pattern.exec(line);
+        if (match !== null)
+            return parseProviderList(match[1] ?? '');
+    }
+    return [];
+}
+export async function runSessionPreflight(options = {}) {
+    // Mirrors runPreflight: a good answer holds for the process, a bad one gets a
+    // short life so one slow spawn does not pin the diagnosis for good.
+    if (cached !== undefined && !options.force) {
+        if (cached.probeFailed === undefined || Date.now() - cachedAt < FAILED_REPORT_TTL_MS) {
+            return cached;
+        }
+    }
+    const [session, impersonate] = await Promise.all([
+        probe(PROBE_ARGS),
+        probe(['--list-impersonate-targets']),
+    ]);
+    if (session === undefined) {
+        cached = {
+            potAvailable: false,
+            potProviders: [],
+            jsRuntimes: [],
+            impersonateTargets: [],
+            probeFailed: 'yt-dlp could not be probed for session capabilities.',
+        };
+        cachedAt = Date.now();
+        return cached;
+    }
+    const output = `${session.stderr}\n${session.stdout}`;
+    const potProviders = readProviders(output, POT_LINE);
+    cached = {
+        potAvailable: potProviders.some((provider) => provider.available),
+        potProviders,
+        jsRuntimes: readProviders(output, JSC_LINE),
+        impersonateTargets: impersonate === undefined
+            ? []
+            : parseImpersonateTargets(`${impersonate.stdout}\n${impersonate.stderr}`),
+    };
+    cachedAt = Date.now();
+    return cached;
+}
+/** Test seam — the report is cached for the process lifetime in normal use. */
+export function resetSessionPreflightCache() {
+    cached = undefined;
+    cachedAt = 0;
+}
+//# sourceMappingURL=pot-preflight.js.map

package/dist/utils/pot-preflight.js.map

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