youtube-knowledge-mcp 2.0.2 → 2.2.0

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

@@ -0,0 +1,45 @@
+import type { z } from 'zod';
+/**
+ * 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
+ * process leaves a half-written file where a valid one used to be — survivable
+ * for a cache, fatal for a brain manifest that is checkpointed every few videos
+ * across a build lasting tens of minutes. Reading without validation means a
+ * file edited by hand, or truncated by that same crash, propagates `undefined`
+ * into code that assumed a shape.
+ */
+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 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.
+ */
+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,
+ * unparseable or does not match.
+ *
+ * Callers decide what a missing document means — an empty library, a brain that
+ * has not been built — which is information this function does not have.
+ */
+export declare function readJsonFile<T>(path: string, schema: z.ZodType<T, z.ZodTypeDef, unknown>): Promise<T | undefined>;
+//# sourceMappingURL=json-file.d.ts.map

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

@@ -0,0 +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,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

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { open, readFile, rename, rm } from 'node:fs/promises';
+export const PRIVATE_FILE_MODE = 0o600;
+let writeSequence = 0;
+/**
+ * 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.
+ */
+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 {
+        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) {
+        await rm(temporaryPath, { force: true });
+        throw error;
+    }
+}
+/** 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.
+ *
+ * Callers decide what a missing document means — an empty library, a brain that
+ * has not been built — which is information this function does not have.
+ */
+export async function readJsonFile(path, schema) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = schema.safeParse(JSON.parse(await readFile(path, 'utf-8')));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=json-file.js.map

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

@@ -0,0 +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,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/paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Everything this server writes lives under one directory in the user's home:
+ * transcripts, the library, clips, and the channel brains.
+ *
+ * Spelled out in six places before this existed, which is five chances for a
+ * rename to leave a stray directory behind.
+ */
+export declare function dataDir(...segments: string[]): string;
+/** Permission bits for the directories this server owns: the user's data, nobody else's. */
+export declare const PRIVATE_DIR_MODE = 448;
+/**
+ * Create a directory the server owns, readable by its user only.
+ *
+ * Media that a tool writes for the user to open — downloads, clips, frames —
+ * keeps the umask default; this is for the transcript cache, the library, the
+ * brains and their indexes.
+ */
+export declare function ensurePrivateDir(path: string): Promise<string>;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAErD;AAED,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE"}

package/dist/utils/paths.js

@@ -0,0 +1,27 @@
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Everything this server writes lives under one directory in the user's home:
+ * transcripts, the library, clips, and the channel brains.
+ *
+ * Spelled out in six places before this existed, which is five chances for a
+ * rename to leave a stray directory behind.
+ */
+export function dataDir(...segments) {
+    return join(homedir(), '.youtube-knowledge', ...segments);
+}
+/** Permission bits for the directories this server owns: the user's data, nobody else's. */
+export const PRIVATE_DIR_MODE = 0o700;
+/**
+ * Create a directory the server owns, readable by its user only.
+ *
+ * Media that a tool writes for the user to open — downloads, clips, frames —
+ * keeps the umask default; this is for the transcript cache, the library, the
+ * brains and their indexes.
+ */
+export async function ensurePrivateDir(path) {
+    await mkdir(path, { recursive: true, mode: PRIVATE_DIR_MODE });
+    return path;
+}
+//# sourceMappingURL=paths.js.map

package/dist/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,GAAG,QAAkB;IAC3C,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,oBAAoB,EAAE,GAAG,QAAQ,CAAC,CAAC;AAC5D,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/pattern.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Compiling a caller-supplied search pattern without handing the event loop
+ * to it.
+ *
+ * JavaScript's regex engine backtracks, and a pattern such as `(a+)+$` takes
+ * time exponential in the input on a non-matching string. `search_transcript`
+ * runs the caller's pattern over every caption window of a video, on a server
+ * whose HTTP transport is shared, so an unbounded pattern is a way to stall
+ * every session at once. The rule below is conservative — it refuses some
+ * harmless patterns — but it is simple enough to explain in an error message
+ * and needs no second regex engine.
+ */
+export declare const MAX_PATTERN_LENGTH = 200;
+/**
+ * Throws when a repeated group contains repetition or alternation, or when the
+ * pattern uses a backreference.
+ */
+export declare function assertSafePattern(source: string): void;
+export interface PatternOptions {
+    regex: boolean;
+    caseSensitive: boolean;
+}
+/**
+ * Compile the caller's query once, with the flags the search will use.
+ *
+ * A literal query is escaped so that `a.` matches "a." and nothing else; a
+ * regex query is checked for the backtracking rule and for syntax.
+ */
+export declare function compilePattern(query: string, options: PatternOptions): RegExp;
+//# sourceMappingURL=pattern.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/utils/pattern.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAsDtC;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAuDtD;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAgB7E"}

package/dist/utils/pattern.js

@@ -0,0 +1,130 @@
+import { YouTubeError } from './errors.js';
+/**
+ * Compiling a caller-supplied search pattern without handing the event loop
+ * to it.
+ *
+ * JavaScript's regex engine backtracks, and a pattern such as `(a+)+$` takes
+ * time exponential in the input on a non-matching string. `search_transcript`
+ * runs the caller's pattern over every caption window of a video, on a server
+ * whose HTTP transport is shared, so an unbounded pattern is a way to stall
+ * every session at once. The rule below is conservative — it refuses some
+ * harmless patterns — but it is simple enough to explain in an error message
+ * and needs no second regex engine.
+ */
+export const MAX_PATTERN_LENGTH = 200;
+const QUANTIFIER_START = new Set(['*', '+', '?', '{']);
+function unsafe(reason) {
+    return new YouTubeError('INVALID_INPUT', `This pattern could run for a very long time: ${reason}.`, {
+        nextStep: 'A repeated group may not itself contain repetition or alternation, and backreferences are not supported. Simplify the pattern, or set regex=false to search literally.',
+    });
+}
+/** True when `source[at]` begins a quantifier: `*`, `+`, `?` or a `{n}`, `{n,}`, `{n,m}` bound. */
+function quantifierAt(source, at) {
+    const char = source[at];
+    if (char === undefined || !QUANTIFIER_START.has(char))
+        return false;
+    if (char !== '{')
+        return true;
+    return /^\{\d+(?:,\d*)?\}/.test(source.slice(at));
+}
+/** Index just past the character class that opens at `at`. */
+function skipClass(source, at) {
+    let index = at + 1;
+    while (index < source.length && source[index] !== ']') {
+        if (source[index] === '\\')
+            index++;
+        index++;
+    }
+    return index + 1;
+}
+/**
+ * Index just past a group opener: `(`, or `(?:`, `(?=`, `(?!`, `(?<=`, `(?<!`
+ * and `(?<name>`, whose `?` is syntax rather than a quantifier.
+ */
+function skipGroupOpener(source, at) {
+    if (source[at + 1] !== '?')
+        return at + 1;
+    const modifier = source[at + 2];
+    if (modifier === '<') {
+        const lookbehind = source[at + 3];
+        if (lookbehind === '=' || lookbehind === '!')
+            return at + 4;
+        const close = source.indexOf('>', at + 3);
+        return close === -1 ? at + 3 : close + 1;
+    }
+    return at + 3;
+}
+/**
+ * Throws when a repeated group contains repetition or alternation, or when the
+ * pattern uses a backreference.
+ */
+export function assertSafePattern(source) {
+    if (source.length > MAX_PATTERN_LENGTH) {
+        throw new YouTubeError('INVALID_INPUT', `Patterns are limited to ${MAX_PATTERN_LENGTH} characters.`, {
+            nextStep: 'Search for a shorter phrase, or set regex=false to search literally.',
+        });
+    }
+    const root = { quantified: false, alternation: false };
+    const stack = [root];
+    const current = () => stack[stack.length - 1] ?? root;
+    let index = 0;
+    while (index < source.length) {
+        const char = source[index];
+        if (char === '\\') {
+            const next = source[index + 1];
+            if ((next !== undefined && /[1-9]/.test(next)) || next === 'k') {
+                throw unsafe('backreferences are not supported');
+            }
+            index += 2;
+            continue;
+        }
+        if (char === '[') {
+            index = skipClass(source, index);
+            continue;
+        }
+        if (char === '(') {
+            stack.push({ quantified: false, alternation: false });
+            index = skipGroupOpener(source, index);
+            continue;
+        }
+        if (char === ')') {
+            const closed = stack.pop() ?? root;
+            index++;
+            if (quantifierAt(source, index)) {
+                if (closed.quantified || closed.alternation) {
+                    throw unsafe('a repeated group contains repetition or alternation');
+                }
+                current().quantified = true;
+            }
+            continue;
+        }
+        if (char === '|')
+            current().alternation = true;
+        if (quantifierAt(source, index))
+            current().quantified = true;
+        index++;
+    }
+}
+/**
+ * Compile the caller's query once, with the flags the search will use.
+ *
+ * A literal query is escaped so that `a.` matches "a." and nothing else; a
+ * regex query is checked for the backtracking rule and for syntax.
+ */
+export function compilePattern(query, options) {
+    const flags = options.caseSensitive ? 'g' : 'gi';
+    if (!options.regex) {
+        return new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags);
+    }
+    assertSafePattern(query);
+    try {
+        return new RegExp(query, flags);
+    }
+    catch (error) {
+        throw new YouTubeError('INVALID_INPUT', `"${query}" is not a valid regular expression.`, {
+            nextStep: 'Fix the pattern, or set regex=false to search for it literally.',
+            cause: error,
+        });
+    }
+}
+//# sourceMappingURL=pattern.js.map

package/dist/utils/pattern.js.map

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