youtube-knowledge-mcp 2.0.1 → 2.1.0

package/dist/utils/brain-chunks.js

@@ -0,0 +1,87 @@
+import { segmentsToText } from './transcript.js';
+/**
+ * Transcripts cut into retrievable passages.
+ *
+ * A brain is searched, not read: a whole transcript is too long to rank
+ * usefully and far too long to return, while a single caption cue is too short
+ * to carry a thought. A passage of a few sentences is what BM25 scores well and
+ * what a reader can check against the video in one click.
+ *
+ * Chunks do not overlap. Overlap is worth its cost with embeddings, where a
+ * concept split across a boundary can be missed entirely; BM25 matches terms,
+ * and a duplicated passage would only mean two results saying the same thing.
+ */
+/** Where a passage stops being short enough to keep growing. */
+export const CHUNK_TARGET_CHARS = 800;
+/**
+ * Where it stops regardless. Speech without a pause for this long is rare, and
+ * an unbroken passage is worse than one broken in an awkward place.
+ */
+export const CHUNK_MAX_CHARS = 1200;
+/** A pause this long is a sentence or a thought ending. */
+export const CHUNK_BREAK_GAP_SECONDS = 2;
+export function chunkTranscript(options) {
+    const { videoId, title, segments, chapters = [] } = options;
+    const chapterStarts = chapters.map((chapter) => chapter.startTime).sort((a, b) => a - b);
+    const chunks = [];
+    let current = [];
+    let currentChars = 0;
+    let nextChapter = 0;
+    const flush = () => {
+        const chunk = toChunk(videoId, title, current, chunks.length);
+        if (chunk !== undefined)
+            chunks.push(chunk);
+        current = [];
+        currentChars = 0;
+    };
+    for (const segment of segments) {
+        // Consume every chapter that starts at or before this segment. More than
+        // one can land in the same gap when a chapter is shorter than a cue.
+        let startsChapter = false;
+        while (nextChapter < chapterStarts.length) {
+            const start = chapterStarts[nextChapter];
+            if (start === undefined || start > segment.start)
+                break;
+            nextChapter++;
+            startsChapter = true;
+        }
+        const previous = current[current.length - 1];
+        if (previous !== undefined && shouldBreak(previous, segment, currentChars, startsChapter)) {
+            flush();
+        }
+        current.push(segment);
+        // Plus one for the space this segment will be joined with.
+        currentChars += segment.text.length + 1;
+    }
+    flush();
+    return chunks;
+}
+function shouldBreak(previous, segment, currentChars, startsChapter) {
+    if (startsChapter)
+        return true;
+    if (currentChars >= CHUNK_MAX_CHARS)
+        return true;
+    return (currentChars >= CHUNK_TARGET_CHARS && segment.start - previous.end >= CHUNK_BREAK_GAP_SECONDS);
+}
+/** Undefined for an empty run, and for one that turned out to be only whitespace. */
+function toChunk(videoId, title, segments, ordinal) {
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    if (first === undefined || last === undefined)
+        return undefined;
+    const text = segmentsToText(segments);
+    if (text === '')
+        return undefined;
+    return {
+        // Ordinal rather than start time: two passages can begin in the same second
+        // when cues are short, and a colliding id would silently drop one of them
+        // from the index. The start time is a field of its own.
+        id: `${videoId}:${ordinal}`,
+        videoId,
+        title,
+        startSeconds: first.start,
+        endSeconds: last.end,
+        text,
+    };
+}
+//# sourceMappingURL=brain-chunks.js.map

package/dist/utils/brain-chunks.js.map

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

package/dist/utils/brain-index.d.ts

@@ -0,0 +1,27 @@
+import { type BrainChunk, type BrainPassage } from '../brain-schemas.js';
+/**
+ * The searchable half of a brain: the passages, and a BM25 index over them.
+ *
+ * The passages are the only thing persisted. An index file alongside them would
+ * hold a second copy of every word — the serialised index carries the text it
+ * scored — and would then be free to disagree with them. It is built in memory
+ * on first use instead and kept until the passages change: measured at 1.5s for
+ * a corpus at this brain's 100,000-passage ceiling, once, against a class of
+ * bugs forever. A search over that corpus then costs 73ms.
+ *
+ * Retrieval is the only way a corpus reaches a model. That ceiling is 81MB of
+ * transcript, so there is no "give me everything" path here: `readChunks`
+ * exists for statistics and rebuilding, not for answering.
+ */
+export declare const BRAIN_CHUNK_FILE_VERSION = 1;
+export declare function forgetBrainCorpus(channelId: string): void;
+export declare function readChunks(channelId: string): Promise<BrainChunk[]>;
+export declare function writeChunks(channelId: string, chunks: BrainChunk[]): Promise<void>;
+export interface BrainSearchResults {
+    passages: BrainPassage[];
+    /** Passages matching the query, not passages returned. */
+    total: number;
+}
+/** Passages ranked against the query, each with the link that opens it. */
+export declare function searchBrain(channelId: string, query: string, limit: number, offset?: number): Promise<BrainSearchResults>;
+//# sourceMappingURL=brain-index.d.ts.map

package/dist/utils/brain-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-index.d.ts","sourceRoot":"","sources":["../../src/utils/brain-index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAM/F;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAoB1C,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGzE;AAED,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CASxF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,SAAI,GACT,OAAO,CAAC,kBAAkB,CAAC,CAuB7B"}

package/dist/utils/brain-index.js

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs';
+import { mkdir, stat } from 'node:fs/promises';
+import { brainChunkFileSchema } from '../brain-schemas.js';
+import { brainDir, chunksPath } from './brain-paths.js';
+import { readJsonFile, writeJsonAtomic } from './json-file.js';
+import { SearchIndex } from './search-index.js';
+import { deepLink, formatTimestamp } from './transcript.js';
+/**
+ * The searchable half of a brain: the passages, and a BM25 index over them.
+ *
+ * The passages are the only thing persisted. An index file alongside them would
+ * hold a second copy of every word — the serialised index carries the text it
+ * scored — and would then be free to disagree with them. It is built in memory
+ * on first use instead and kept until the passages change: measured at 1.5s for
+ * a corpus at this brain's 100,000-passage ceiling, once, against a class of
+ * bugs forever. A search over that corpus then costs 73ms.
+ *
+ * Retrieval is the only way a corpus reaches a model. That ceiling is 81MB of
+ * transcript, so there is no "give me everything" path here: `readChunks`
+ * exists for statistics and rebuilding, not for answering.
+ */
+export const BRAIN_CHUNK_FILE_VERSION = 1;
+/**
+ * Rebuilding the index on every query would re-read and re-tokenise the whole
+ * corpus each time. The passage file's modification time decides when the
+ * cached copy is wrong, so a build running in another process is picked up
+ * without any coordination between the two.
+ */
+const cache = new Map();
+export function forgetBrainCorpus(channelId) {
+    cache.delete(channelId);
+}
+export async function readChunks(channelId) {
+    const file = await readJsonFile(chunksPath(channelId), brainChunkFileSchema);
+    return file?.chunks ?? [];
+}
+export async function writeChunks(channelId, chunks) {
+    await mkdir(brainDir(channelId), { recursive: true });
+    // Not pretty-printed: indentation would be a fifth of a file nobody reads.
+    await writeJsonAtomic(chunksPath(channelId), { version: BRAIN_CHUNK_FILE_VERSION, chunks }, { pretty: false });
+    forgetBrainCorpus(channelId);
+}
+/** Passages ranked against the query, each with the link that opens it. */
+export async function searchBrain(channelId, query, limit, offset = 0) {
+    const { index, byId } = await corpusOf(channelId);
+    const { hits, total } = index.search(query, limit, offset);
+    const passages = hits.flatMap((hit) => {
+        const chunk = byId.get(hit.id);
+        if (chunk === undefined)
+            return [];
+        return [
+            {
+                videoId: chunk.videoId,
+                title: chunk.title,
+                startSeconds: chunk.startSeconds,
+                startFormatted: formatTimestamp(chunk.startSeconds),
+                endSeconds: chunk.endSeconds,
+                score: hit.score,
+                text: chunk.text,
+                url: deepLink(chunk.videoId, chunk.startSeconds),
+            },
+        ];
+    });
+    return { passages, total };
+}
+async function corpusOf(channelId) {
+    const path = chunksPath(channelId);
+    if (!existsSync(path))
+        return emptyCorpus();
+    const { mtimeMs } = await stat(path);
+    const cached = cache.get(channelId);
+    if (cached?.mtimeMs === mtimeMs)
+        return cached.corpus;
+    const corpus = buildCorpus(await readChunks(channelId));
+    cache.set(channelId, { corpus, mtimeMs });
+    return corpus;
+}
+function emptyCorpus() {
+    return { index: new SearchIndex(), byId: new Map() };
+}
+/**
+ * The shared index is used unchanged: a passage already has an id, a video, a
+ * title and text, which is everything BM25 scores on. `kind` distinguishes
+ * these rows from the library's summaries and skills.
+ */
+function buildCorpus(chunks) {
+    const corpus = emptyCorpus();
+    for (const chunk of chunks) {
+        corpus.index.add({
+            id: chunk.id,
+            videoId: chunk.videoId,
+            title: chunk.title,
+            kind: 'chunk',
+            text: chunk.text,
+        });
+        corpus.byId.set(chunk.id, chunk);
+    }
+    return corpus;
+}
+//# sourceMappingURL=brain-index.js.map

package/dist/utils/brain-index.js.map

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

package/dist/utils/brain-ingest.d.ts

@@ -0,0 +1,57 @@
+import type { BrainChunk, BrainVideoState } from '../brain-schemas.js';
+import { type VideoListItem } from './youtube.js';
+/**
+ * Reading one video into passages.
+ *
+ * Nothing here throws for anything to do with the video itself. A channel with
+ * a members-only upload, a live stream still processing, or an episode nobody
+ * captioned is still a channel worth having a brain for; which videos those
+ * were belongs in the manifest, not in an exception that loses the other two
+ * hundred.
+ *
+ * Metadata is read before the transcript, in that order deliberately: it is the
+ * cheaper request, it carries the date and length the filters need, and a video
+ * ruled out by them then costs one request instead of two.
+ */
+/**
+ * A transcript that chunks past this is not a transcript. Recording the video
+ * as failed keeps the brain buildable; letting it through does not.
+ *
+ * The brain-wide ceiling is what bounds memory, and it was chosen by measuring
+ * rather than by feel: a corpus of 100,000 passages is 81MB on disk, and the
+ * heaviest thing done to it — the phrase pass — peaked at 767MB of heap. Raising
+ * it means measuring again.
+ */
+export declare const MAX_CHUNKS_PER_VIDEO = 2000;
+export declare const MAX_CHUNKS_PER_BRAIN = 100000;
+/** Recorded against a video the size guards refused, alongside yt-dlp's own codes. */
+export declare const TOO_LARGE = "TOO_LARGE";
+export declare const BRAIN_FULL = "BRAIN_FULL";
+export interface VideoFilters {
+    /** Ignore anything published before this date (YYYY-MM-DD). */
+    since?: string;
+    /** Ignore anything shorter, to leave out shorts and clips. */
+    minDurationSeconds: number;
+}
+export interface IngestOptions extends VideoFilters {
+    language: string;
+}
+export interface IngestResult {
+    state: BrainVideoState;
+    chunks: BrainChunk[];
+}
+export declare function ingestVideo(video: VideoListItem, chunksSoFar: number, options: IngestOptions): Promise<IngestResult>;
+/**
+ * Whether the filters rule this video out, or `undefined` when its recorded
+ * state cannot say.
+ *
+ * A build asks this of the manifest before deciding what to read, which is what
+ * lets a changed filter take effect without re-fetching anything: once a video
+ * has been looked at, its real date and length are on disk and the question is
+ * answerable from there. `undefined` is the honest answer for a video only ever
+ * seen in a flat listing — not a licence to assume it qualifies.
+ */
+export declare function isExcluded(state: BrainVideoState, filters: VideoFilters): boolean | undefined;
+export declare function pendingState(video: VideoListItem): BrainVideoState;
+export declare function excluded(state: BrainVideoState): BrainVideoState;
+//# sourceMappingURL=brain-ingest.d.ts.map

package/dist/utils/brain-ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-ingest.d.ts","sourceRoot":"","sources":["../../src/utils/brain-ingest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAKvE,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAElF;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAE5C,sFAAsF;AACtF,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAoDvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,CAe7F;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CAWlE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CAEhE"}

package/dist/utils/brain-ingest.js

@@ -0,0 +1,127 @@
+import { chunkTranscript } from './brain-chunks.js';
+import { throwIfAborted } from './context.js';
+import { asYouTubeError } from './errors.js';
+import { countWords } from './transcript.js';
+import { getTranscript, getVideoDetails } from './youtube.js';
+/**
+ * Reading one video into passages.
+ *
+ * Nothing here throws for anything to do with the video itself. A channel with
+ * a members-only upload, a live stream still processing, or an episode nobody
+ * captioned is still a channel worth having a brain for; which videos those
+ * were belongs in the manifest, not in an exception that loses the other two
+ * hundred.
+ *
+ * Metadata is read before the transcript, in that order deliberately: it is the
+ * cheaper request, it carries the date and length the filters need, and a video
+ * ruled out by them then costs one request instead of two.
+ */
+/**
+ * A transcript that chunks past this is not a transcript. Recording the video
+ * as failed keeps the brain buildable; letting it through does not.
+ *
+ * The brain-wide ceiling is what bounds memory, and it was chosen by measuring
+ * rather than by feel: a corpus of 100,000 passages is 81MB on disk, and the
+ * heaviest thing done to it — the phrase pass — peaked at 767MB of heap. Raising
+ * it means measuring again.
+ */
+export const MAX_CHUNKS_PER_VIDEO = 2000;
+export const MAX_CHUNKS_PER_BRAIN = 100_000;
+/** Recorded against a video the size guards refused, alongside yt-dlp's own codes. */
+export const TOO_LARGE = 'TOO_LARGE';
+export const BRAIN_FULL = 'BRAIN_FULL';
+export async function ingestVideo(video, chunksSoFar, options) {
+    const listed = pendingState(video);
+    try {
+        // The listing is flat, which is what makes enumerating a thousand videos one
+        // request rather than a thousand — and flat entries carry no date. These are
+        // the real values, and the chapters come back in the same request.
+        const details = await getVideoDetails(video.id);
+        const known = {
+            ...listed,
+            uploadDate: details.uploadDate,
+            durationSeconds: details.durationSeconds,
+        };
+        if (isExcluded(known, options) === true)
+            return { state: excluded(known), chunks: [] };
+        const transcript = await getTranscript(video.id, { language: options.language });
+        const chunks = chunkTranscript({
+            videoId: video.id,
+            title: video.title,
+            segments: transcript.segments,
+            chapters: details.chapters,
+        });
+        if (chunks.length > MAX_CHUNKS_PER_VIDEO)
+            return refused(known, TOO_LARGE);
+        if (chunksSoFar + chunks.length > MAX_CHUNKS_PER_BRAIN)
+            return refused(known, BRAIN_FULL);
+        return {
+            state: {
+                ...known,
+                state: 'indexed',
+                chunkCount: chunks.length,
+                wordCount: chunks.reduce((total, chunk) => total + countWords(chunk.text), 0),
+            },
+            chunks,
+        };
+    }
+    catch (error) {
+        // Cancellation is the client's decision, not this video's problem. Asking
+        // the signal rather than classifying the error catches it however it was
+        // raised — an aborted spawn, a rejected read, or the check between videos.
+        throwIfAborted();
+        const failure = asYouTubeError(error);
+        return {
+            state: failure.code === 'NO_CAPTIONS'
+                ? { ...listed, state: 'no-captions' }
+                : { ...listed, state: 'failed', error: failure.code },
+            chunks: [],
+        };
+    }
+}
+/**
+ * Whether the filters rule this video out, or `undefined` when its recorded
+ * state cannot say.
+ *
+ * A build asks this of the manifest before deciding what to read, which is what
+ * lets a changed filter take effect without re-fetching anything: once a video
+ * has been looked at, its real date and length are on disk and the question is
+ * answerable from there. `undefined` is the honest answer for a video only ever
+ * seen in a flat listing — not a licence to assume it qualifies.
+ */
+export function isExcluded(state, filters) {
+    const { since, minDurationSeconds } = filters;
+    let undecided = false;
+    if (minDurationSeconds > 0) {
+        if (state.durationSeconds <= 0)
+            undecided = true;
+        else if (state.durationSeconds < minDurationSeconds)
+            return true;
+    }
+    if (since !== undefined) {
+        if (state.uploadDate === '')
+            undecided = true;
+        else if (state.uploadDate < since)
+            return true;
+    }
+    return undecided ? undefined : false;
+}
+export function pendingState(video) {
+    return {
+        videoId: video.id,
+        title: video.title,
+        url: video.url,
+        uploadDate: video.uploadDate,
+        durationSeconds: video.duration,
+        state: 'pending',
+        chunkCount: 0,
+        wordCount: 0,
+    };
+}
+export function excluded(state) {
+    return { ...state, state: 'excluded', chunkCount: 0, wordCount: 0 };
+}
+function refused(state, reason) {
+    return { state: { ...state, state: 'failed', error: reason }, chunks: [] };
+}
+//# sourceMappingURL=brain-ingest.js.map

package/dist/utils/brain-ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-ingest.js","sourceRoot":"","sources":["../../src/utils/brain-ingest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAsB,MAAM,cAAc,CAAC;AAElF;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C,sFAAsF;AACtF,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AACrC,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AAkBvC,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAoB,EACpB,WAAmB,EACnB,OAAsB;IAEtB,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAEnC,IAAI,CAAC;QACH,6EAA6E;QAC7E,6EAA6E;QAC7E,mEAAmE;QACnE,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,KAAK,GAAoB;YAC7B,GAAG,MAAM;YACT,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,eAAe,EAAE,OAAO,CAAC,eAAe;SACzC,CAAC;QAEF,IAAI,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI;YAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QAEvF,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjF,MAAM,MAAM,GAAG,eAAe,CAAC;YAC7B,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,MAAM,GAAG,oBAAoB;YAAE,OAAO,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAC3E,IAAI,WAAW,GAAG,MAAM,CAAC,MAAM,GAAG,oBAAoB;YAAE,OAAO,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAE1F,OAAO;YACL,KAAK,EAAE;gBACL,GAAG,KAAK;gBACR,KAAK,EAAE,SAAS;gBAChB,UAAU,EAAE,MAAM,CAAC,MAAM;gBACzB,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;aAC9E;YACD,MAAM;SACP,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,cAAc,EAAE,CAAC;QAEjB,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QAEtC,OAAO;YACL,KAAK,EACH,OAAO,CAAC,IAAI,KAAK,aAAa;gBAC5B,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE;gBACrC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE;YACzD,MAAM,EAAE,EAAE;SACX,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB,EAAE,OAAqB;IACtE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC;IAC9C,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,eAAe,IAAI,CAAC;YAAE,SAAS,GAAG,IAAI,CAAC;aAC5C,IAAI,KAAK,CAAC,eAAe,GAAG,kBAAkB;YAAE,OAAO,IAAI,CAAC;IACnE,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,KAAK,CAAC,UAAU,KAAK,EAAE;YAAE,SAAS,GAAG,IAAI,CAAC;aACzC,IAAI,KAAK,CAAC,UAAU,GAAG,KAAK;YAAE,OAAO,IAAI,CAAC;IACjD,CAAC;IAED,OAAO,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE;QACjB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,eAAe,EAAE,KAAK,CAAC,QAAQ;QAC/B,KAAK,EAAE,SAAS;QAChB,UAAU,EAAE,CAAC;QACb,SAAS,EAAE,CAAC;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAsB;IAC7C,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,SAAS,OAAO,CAAC,KAAsB,EAAE,MAAc;IACrD,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC7E,CAAC"}

package/dist/utils/brain-lock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Exclusive access to a brain while it is being built.
+ *
+ * Two builds of one channel would interleave their manifest checkpoints, and
+ * the later write would silently drop whatever the other had recorded since it
+ * last read. A lock file rather than an in-process mutex because a second
+ * server process — a second editor window, a stray `npm start` — is the case
+ * that actually happens.
+ */
+/** Long enough that a slow build is never mistaken for a dead one. */
+export declare const LOCK_STALE_MS: number;
+/**
+ * Run `build` holding the lock.
+ *
+ * It is released on any exit, including cancellation. A process killed outright
+ * leaves one behind, which is why a lock is also broken when its owner is gone
+ * or when it is simply too old to be real.
+ */
+export declare function withBuildLock<T>(channelId: string, build: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=brain-lock.d.ts.map

package/dist/utils/brain-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-lock.d.ts","sourceRoot":"","sources":["../../src/utils/brain-lock.ts"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,eAAO,MAAM,aAAa,QAAiB,CAAC;AAE5C;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAyB7F"}

package/dist/utils/brain-lock.js

@@ -0,0 +1,93 @@
+import { rm, writeFile } from 'node:fs/promises';
+import { brainLockSchema } from '../brain-schemas.js';
+import { ensureBrainDir } from './brain-storage.js';
+import { lockPath } from './brain-paths.js';
+import { YouTubeError } from './errors.js';
+import { readJsonFile } from './json-file.js';
+import { isRecord } from './ytdlp.js';
+/**
+ * Exclusive access to a brain while it is being built.
+ *
+ * Two builds of one channel would interleave their manifest checkpoints, and
+ * the later write would silently drop whatever the other had recorded since it
+ * last read. A lock file rather than an in-process mutex because a second
+ * server process — a second editor window, a stray `npm start` — is the case
+ * that actually happens.
+ */
+/** Long enough that a slow build is never mistaken for a dead one. */
+export const LOCK_STALE_MS = 30 * 60 * 1000;
+/**
+ * Run `build` holding the lock.
+ *
+ * It is released on any exit, including cancellation. A process killed outright
+ * leaves one behind, which is why a lock is also broken when its owner is gone
+ * or when it is simply too old to be real.
+ */
+export async function withBuildLock(channelId, build) {
+    await ensureBrainDir(channelId);
+    const path = lockPath(channelId);
+    if (!(await acquire(path))) {
+        const existing = await readJsonFile(path, brainLockSchema);
+        // An unreadable lock is one being written this instant, which is as held as
+        // it gets. Only a lock whose owner is demonstrably gone gets broken.
+        if (existing === undefined || !isStale(existing.pid, existing.startedAt)) {
+            throw alreadyRunning(channelId, existing);
+        }
+        await rm(path, { force: true });
+        // Losing this second race means another caller broke the same stale lock
+        // first, and is now the legitimate owner.
+        if (!(await acquire(path)))
+            throw alreadyRunning(channelId, undefined);
+    }
+    try {
+        return await build();
+    }
+    finally {
+        await rm(path, { force: true });
+    }
+}
+function alreadyRunning(channelId, existing) {
+    const owner = existing === undefined ? '' : `Started at ${existing.startedAt} by process ${existing.pid}. `;
+    return new YouTubeError('INVALID_INPUT', `A build for ${channelId} is already running.`, {
+        nextStep: `${owner}Wait for it to finish, then call build_brain again to continue where it stopped.`,
+    });
+}
+/**
+ * Create the lock file, or report that someone else already has.
+ *
+ * `wx` fails when the file exists, and that check and the creation are one
+ * operation in the kernel. Reading first and writing after is not a lock: two
+ * builds starting together both see nothing and both proceed.
+ */
+async function acquire(path) {
+    const lock = { pid: process.pid, startedAt: new Date().toISOString() };
+    try {
+        await writeFile(path, JSON.stringify(lock), { encoding: 'utf-8', flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+}
+function isStale(pid, startedAt) {
+    const started = Date.parse(startedAt);
+    if (Number.isNaN(started) || Date.now() - started > LOCK_STALE_MS)
+        return true;
+    return !isProcessAlive(pid);
+}
+function isProcessAlive(pid) {
+    try {
+        // Signal 0 performs the permission and existence checks without delivering
+        // anything.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to another user, which for
+        // this purpose is very much alive.
+        return isRecord(error) && error.code === 'EPERM';
+    }
+}
+//# sourceMappingURL=brain-lock.js.map

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

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

package/dist/utils/brain-lookup.d.ts

@@ -0,0 +1,3 @@
+import type { BrainManifest } from '../brain-schemas.js';
+export declare function resolveBrain(channel: string): Promise<BrainManifest>;
+//# sourceMappingURL=brain-lookup.d.ts.map

package/dist/utils/brain-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-lookup.d.ts","sourceRoot":"","sources":["../../src/utils/brain-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAmBzD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAY1E"}

package/dist/utils/brain-lookup.js

@@ -0,0 +1,62 @@
+import { listManifests } from './brain-storage.js';
+import { YouTubeError } from './errors.js';
+/**
+ * Find a brain from whatever the caller called the channel.
+ *
+ * Every brain tool except `build_brain` answers from disk, so none of them
+ * should need the network to work out which brain is meant — asking YouTube to
+ * resolve a handle before every search would put a round trip in front of a
+ * lookup that is otherwise instant, and would make a brain unusable offline.
+ *
+ * The manifest already records the channel's id, handle, name and URL, which is
+ * everything a caller is likely to type.
+ */
+const CHANNEL_ID_IN_TEXT = /UC[A-Za-z0-9_-]{22}/;
+const HANDLE_IN_TEXT = /@[\w.-]+/;
+export async function resolveBrain(channel) {
+    const manifests = await listManifests();
+    const wanted = candidates(channel);
+    const matches = manifests.filter((manifest) => keysOf(manifest).some((key) => wanted.has(key)));
+    const [first, second] = matches;
+    if (first === undefined)
+        throw noBrain(channel, manifests);
+    if (second !== undefined)
+        throw ambiguous(channel, matches);
+    return first;
+}
+function candidates(channel) {
+    const keys = new Set([normalize(channel)]);
+    const id = CHANNEL_ID_IN_TEXT.exec(channel)?.[0];
+    if (id !== undefined)
+        keys.add(normalize(id));
+    const handle = HANDLE_IN_TEXT.exec(channel)?.[0];
+    if (handle !== undefined) {
+        keys.add(normalize(handle));
+        keys.add(normalize(handle.slice(1)));
+    }
+    return keys;
+}
+function keysOf(manifest) {
+    const { channelId, handle, name, channelUrl } = manifest.channel;
+    return [channelId, handle, handle.replace(/^@/, ''), name, channelUrl]
+        .map(normalize)
+        .filter((key) => key !== '');
+}
+function normalize(value) {
+    return value.trim().toLowerCase().replace(/\/+$/, '');
+}
+function noBrain(channel, manifests) {
+    const built = manifests.map((manifest) => manifest.channel.handle || manifest.channel.name);
+    return new YouTubeError('NOT_FOUND', `No brain has been built for "${channel}".`, {
+        nextStep: built.length === 0
+            ? 'Call build_brain with the channel URL or handle to build one.'
+            : `Call build_brain to build it. Brains that exist: ${built.join(', ')}.`,
+    });
+}
+function ambiguous(channel, matches) {
+    const names = matches.map((manifest) => manifest.channel.channelId);
+    return new YouTubeError('INVALID_INPUT', `"${channel}" matches more than one brain.`, {
+        nextStep: `Use the channel id instead: ${names.join(', ')}.`,
+    });
+}
+//# sourceMappingURL=brain-lookup.js.map

package/dist/utils/brain-lookup.js.map

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