youtube-knowledge-mcp 2.2.0 → 3.0.1

package/dist/utils/ytdlp-pacer.js

@@ -0,0 +1,165 @@
+/**
+ * How this server reacts to being throttled.
+ *
+ * The old behaviour was three attempts with at most ~1.5 seconds of jitter and
+ * no memory between calls, which is fine for a blip and useless for an
+ * hour-long harvest: nothing slowed down, nothing waited, and a hard block
+ * produced an hour of identical failures.
+ *
+ * This adds three things that only make sense across calls — a shared
+ * cooldown, an adaptive concurrency ceiling, and a circuit breaker — so the
+ * state is deliberately process-global, the same scope as the limiter it
+ * cooperates with.
+ */
+export const RATE_LIMIT_COOLDOWN_BASE_MS = 30_000;
+export const RATE_LIMIT_COOLDOWN_MAX_MS = 15 * 60_000;
+export const BOT_CHECK_COOLDOWN_MS = 10 * 60_000;
+export const MAX_BACKOFF_MS = 120_000;
+export const BASE_BACKOFF_MS = 750;
+export const AIMD_MIN_CONCURRENCY = 1;
+export const AIMD_INCREASE_AFTER_SUCCESSES = 20;
+export const AIMD_DECREASE_FACTOR = 0.5;
+/** Consecutive throttles before a global cooldown starts. */
+export const COOLDOWN_AFTER_STRIKES = 2;
+export const CIRCUIT_STRIKES = 5;
+export const CIRCUIT_OPEN_MS = 5 * 60_000;
+const TERMINAL = {
+    attempts: 1,
+    backoff: 'none',
+    cooldown: 'none',
+    concurrency: 'none',
+};
+/**
+ * What to do about each kind of failure.
+ *
+ * BOT_CHECK does not retry, and that is measured rather than assumed: from a
+ * datacenter address, eight player clients, a fifteen-minute cooldown, a PO
+ * token provider and curl_cffi TLS impersonation all returned the same answer.
+ * Retrying spends requests on a known-dead path; stopping and naming the cause
+ * is the useful response. The cooldown still applies, because whatever else is
+ * in flight should not keep hammering.
+ */
+const POLICIES = {
+    RATE_LIMITED: {
+        attempts: 5,
+        backoff: 'exponential',
+        cooldown: 'rate-limit',
+        concurrency: 'decrease',
+    },
+    BOT_CHECK: { attempts: 1, backoff: 'none', cooldown: 'bot-check', concurrency: 'floor' },
+    TIMEOUT: { attempts: 3, backoff: 'exponential', cooldown: 'none', concurrency: 'decrease' },
+    // Deliberately absent: an unclassified yt-dlp failure carries no evidence
+    // that a second attempt would go differently, and `retryable` is false on it,
+    // so it falls through to TERMINAL. Listing it here with attempts > 1 would
+    // state a policy the retry loop correctly refuses to honour.
+};
+export function policyFor(code) {
+    return POLICIES[code] ?? TERMINAL;
+}
+let state = {
+    cooldownUntil: 0,
+    circuitOpenUntil: 0,
+    strikes: 0,
+    successes: 0,
+    concurrency: Number.POSITIVE_INFINITY,
+};
+/** ±25% so parallel callers do not come back in lockstep. */
+function jitter(ms) {
+    return Math.round(ms * (0.75 + Math.random() * 0.5));
+}
+function cooldownFor(kind, strikes) {
+    if (kind === 'none')
+        return 0;
+    if (kind === 'bot-check')
+        return BOT_CHECK_COOLDOWN_MS;
+    const escalated = RATE_LIMIT_COOLDOWN_BASE_MS * 2 ** Math.max(0, strikes - 1);
+    return jitter(Math.min(escalated, RATE_LIMIT_COOLDOWN_MAX_MS));
+}
+export function backoffDelay(attempt, style) {
+    if (style === 'none')
+        return 0;
+    // Exponential with full jitter, capped so a long run cannot stall for hours.
+    const ceiling = Math.min(BASE_BACKOFF_MS * 2 ** (attempt - 1), MAX_BACKOFF_MS);
+    return Math.round(Math.random() * ceiling);
+}
+/** Records a failure and says whether to try again, and after how long. */
+export function onFailure(code, attempt, now = Date.now()) {
+    const policy = policyFor(code);
+    const throttled = policy.cooldown !== 'none';
+    if (throttled) {
+        state.strikes += 1;
+        state.successes = 0;
+        // A first strike gets the exponential backoff and nothing more: one 429 is
+        // a blip, and making a single interactive call wait out a 30-second global
+        // cooldown would be worse than the problem. The cooldown starts once the
+        // client has been refused twice in a row, which is when it has stopped
+        // being a blip. A bot check skips the grace: it was measured not to clear
+        // on its own, so there is nothing to be gained by trying again sooner.
+        const grace = policy.cooldown === 'bot-check' ? 1 : COOLDOWN_AFTER_STRIKES;
+        if (state.strikes >= grace) {
+            state.cooldownUntil = Math.max(state.cooldownUntil, now + cooldownFor(policy.cooldown, state.strikes));
+        }
+        if (policy.concurrency === 'floor') {
+            state.concurrency = AIMD_MIN_CONCURRENCY;
+        }
+        else if (policy.concurrency === 'decrease') {
+            state.concurrency = Math.max(AIMD_MIN_CONCURRENCY, Math.floor(effectiveConcurrency(now) * AIMD_DECREASE_FACTOR));
+        }
+        if (state.strikes >= CIRCUIT_STRIKES) {
+            state.circuitOpenUntil = now + CIRCUIT_OPEN_MS;
+        }
+    }
+    return attempt >= policy.attempts
+        ? { giveUp: true, delayMs: 0 }
+        : { giveUp: false, delayMs: backoffDelay(attempt, policy.backoff) };
+}
+/** Records a clean spawn, easing the ceiling back up one step at a time. */
+export function onSuccess() {
+    state.strikes = 0;
+    state.successes += 1;
+    if (state.successes >= AIMD_INCREASE_AFTER_SUCCESSES) {
+        state.successes = 0;
+        if (Number.isFinite(state.concurrency))
+            state.concurrency += 1;
+    }
+}
+/** How long a caller should wait before spawning, in milliseconds. */
+export function waitMs(now = Date.now()) {
+    if (state.circuitOpenUntil > now)
+        return state.circuitOpenUntil - now;
+    return Math.max(0, state.cooldownUntil - now);
+}
+export function circuitOpen(now = Date.now()) {
+    return state.circuitOpenUntil > now;
+}
+/**
+ * The ceiling the limiter should honour right now.
+ *
+ * Infinite until something throttles us, so an untroubled server runs at
+ * whatever YOUTUBE_MCP_MAX_CONCURRENCY allows and the limiter stays the only
+ * authority on the normal case.
+ */
+export function effectiveConcurrency(now = Date.now()) {
+    if (circuitOpen(now))
+        return AIMD_MIN_CONCURRENCY;
+    return state.concurrency;
+}
+export function pacerState(now = Date.now()) {
+    return {
+        cooldownMs: waitMs(now),
+        circuitOpen: circuitOpen(now),
+        strikes: state.strikes,
+        concurrency: effectiveConcurrency(now),
+    };
+}
+/** Test seam; the pacer is process-global in normal use. */
+export function resetPacer() {
+    state = {
+        cooldownUntil: 0,
+        circuitOpenUntil: 0,
+        strikes: 0,
+        successes: 0,
+        concurrency: Number.POSITIVE_INFINITY,
+    };
+}
+//# sourceMappingURL=ytdlp-pacer.js.map

package/dist/utils/ytdlp-pacer.js.map

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

package/dist/utils/ytdlp-stream.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Running yt-dlp and reading its output a line at a time.
+ *
+ * `runYtDlp` buffers everything into a string, which is right for a metadata
+ * read and wrong for a long walk: a 40,000-entry channel listing killed at
+ * minute nine yields nothing at all, and the 64MB buffer is a hard ceiling.
+ *
+ * Here each line is handed over as it arrives, so a caller can checkpoint as
+ * it goes and keep what it already had. Paired with `--lazy-playlist`, which
+ * makes yt-dlp emit entries while it walks rather than after.
+ */
+export interface StreamOptions {
+    label?: string;
+    timeoutMs?: number;
+    target: string;
+    /** Called per line, in order. A throw here aborts the walk. */
+    onLine: (line: string) => void;
+}
+export interface StreamResult {
+    lines: number;
+    /** False when the walk was cut short, so the caller knows not to claim completeness. */
+    completed: boolean;
+}
+/**
+ * Streams stdout line by line.
+ *
+ * A failure part-way through is not thrown away: the caller keeps every line
+ * delivered so far and is told the walk did not complete, which is the whole
+ * point of streaming rather than buffering.
+ */
+export declare function runYtDlpLines(args: string[], options: StreamOptions): Promise<StreamResult>;
+//# sourceMappingURL=ytdlp-stream.d.ts.map

package/dist/utils/ytdlp-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-stream.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-stream.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA+CjG"}

package/dist/utils/ytdlp-stream.js

@@ -0,0 +1,61 @@
+import { execa } from 'execa';
+import { createInterface } from 'node:readline';
+import { currentContext } from './context.js';
+import { acquireSlot, releaseSlot } from './ytdlp-limiter.js';
+import { readYtDlpEnv } from './ytdlp-env.js';
+import { YouTubeError } from './errors.js';
+import { SOCKET_TIMEOUT_S } from './ytdlp.js';
+/**
+ * Streams stdout line by line.
+ *
+ * A failure part-way through is not thrown away: the caller keeps every line
+ * delivered so far and is told the walk did not complete, which is the whole
+ * point of streaming rather than buffering.
+ */
+export async function runYtDlpLines(args, options) {
+    const { timeoutMs = 0, target, onLine } = options;
+    const { signal } = currentContext();
+    if (signal?.aborted === true) {
+        throw new YouTubeError('CANCELLED', 'The request was cancelled.');
+    }
+    await acquireSlot(signal);
+    let lines = 0;
+    try {
+        const argv = [
+            '--socket-timeout',
+            SOCKET_TIMEOUT_S,
+            ...readYtDlpEnv().args,
+            ...args,
+            '--',
+            target,
+        ];
+        const child = execa('yt-dlp', argv, {
+            timeout: timeoutMs > 0 ? timeoutMs : undefined,
+            cancelSignal: signal,
+            buffer: false,
+            stdout: 'pipe',
+        });
+        // `stdout: 'pipe'` with `buffer: false` guarantees a stream here, so there
+        // is nothing to guard against.
+        const reader = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        for await (const line of reader) {
+            if (line.trim() === '')
+                continue;
+            onLine(line);
+            lines += 1;
+        }
+        await child;
+        return { lines, completed: true };
+    }
+    catch (error) {
+        // Everything delivered so far is already the caller's. Reporting how far
+        // it got matters more than the reason, which the caller can classify.
+        if (error instanceof YouTubeError)
+            throw error;
+        return { lines, completed: false };
+    }
+    finally {
+        releaseSlot();
+    }
+}
+//# sourceMappingURL=ytdlp-stream.js.map

package/dist/utils/ytdlp-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-stream.js","sourceRoot":"","sources":["../../src/utils/ytdlp-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA4B9C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAc,EAAE,OAAsB;IACxE,MAAM,EAAE,SAAS,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAAC;IAEpC,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,YAAY,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,IAAI,CAAC;QACH,MAAM,IAAI,GAAG;YACX,kBAAkB;YAClB,gBAAgB;YAChB,GAAG,YAAY,EAAE,CAAC,IAAI;YACtB,GAAG,IAAI;YACP,IAAI;YACJ,MAAM;SACP,CAAC;QAEF,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE;YAClC,OAAO,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YAC9C,YAAY,EAAE,MAAM;YACpB,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;QAEH,2EAA2E;QAC3E,+BAA+B;QAC/B,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7E,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,SAAS;YACjC,MAAM,CAAC,IAAI,CAAC,CAAC;YACb,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;QAED,MAAM,KAAK,CAAC;QACZ,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,sEAAsE;QACtE,IAAI,KAAK,YAAY,YAAY;YAAE,MAAM,KAAK,CAAC;QAC/C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;YAAS,CAAC;QACT,WAAW,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/utils/ytdlp.d.ts

@@ -19,6 +19,16 @@ export declare const TIMEOUTS: {
     /** Media transfers: unbounded here; cancellation is the client's lever. */
     readonly download: 0;
 };
+/**
+ * Seconds of socket inactivity before yt-dlp gives up on a connection.
+ *
+ * Media transfers deliberately run without a wall-clock timeout — a long clip
+ * is allowed to take as long as it honestly takes — which left a dead
+ * connection indistinguishable from a slow one, holding its concurrency slot
+ * forever. This bounds the silence, not the work: a transfer still making
+ * progress is never interrupted.
+ */
+export declare const SOCKET_TIMEOUT_S = "30";
 export interface RunOptions {
     /** Milliseconds before the child is killed. 0 disables the timeout. */
     timeoutMs?: number;

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

@@ -1 +1 @@
-{"version":3,"file":"ytdlp.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;GAOG;AAEH,kFAAkF;AAClF,eAAO,MAAM,QAAQ;IACnB,wDAAwD;;IAExD,gDAAgD;;IAEhD,iEAAiE;;IAEjE,2EAA2E;;CAEnE,CAAC;AAkBX,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAsBD;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBnF"}
+{"version":3,"file":"ytdlp.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;GAOG;AAEH,kFAAkF;AAClF,eAAO,MAAM,QAAQ;IACnB,wDAAwD;;IAExD,gDAAgD;;IAEhD,iEAAiE;;IAEjE,2EAA2E;;CAEnE,CAAC;AAMX;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8DnF"}

package/dist/utils/ytdlp.js

@@ -1,5 +1,7 @@
 import { execa, ExecaError } from 'execa';
 import { currentContext, log } from './context.js';
+import { sleep } from './sleep.js';
+import { circuitOpen, onFailure, onSuccess, waitMs } from './ytdlp-pacer.js';
 import { YouTubeError, classifyYtDlpFailure } from './errors.js';
 import { acquireSlot, releaseSlot } from './ytdlp-limiter.js';
 import { readYtDlpEnv } from './ytdlp-env.js';
@@ -25,7 +27,6 @@ export const TIMEOUTS = {
     download: 0,
 };
 const MAX_ATTEMPTS = 3;
-const BASE_BACKOFF_MS = 750;
 /** Guards against a pathological video description blowing up memory. */
 const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
 /**
@@ -37,25 +38,7 @@ const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
  * forever. This bounds the silence, not the work: a transfer still making
  * progress is never interrupted.
  */
-const SOCKET_TIMEOUT_S = '30';
-function backoffDelay(attempt) {
-    // Exponential with full jitter, so parallel callers do not retry in lockstep.
-    const ceiling = BASE_BACKOFF_MS * 2 ** (attempt - 1);
-    return Math.round(Math.random() * ceiling);
-}
-async function sleep(ms, signal) {
-    await new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            signal?.removeEventListener('abort', onAbort);
-            resolve();
-        }, ms);
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(new YouTubeError('CANCELLED', 'The request was cancelled.'));
-        };
-        signal?.addEventListener('abort', onAbort, { once: true });
-    });
-}
+export const SOCKET_TIMEOUT_S = '30';
 /**
  * Run yt-dlp and return its stdout.
  *
@@ -74,17 +57,45 @@ export async function runYtDlp(args, options) {
         if (signal?.aborted === true) {
             throw new YouTubeError('CANCELLED', 'The request was cancelled.');
         }
+        // The cooldown gates NEW work, not this call's own retries: it applies on
+        // the first attempt only. Mixing the two would make a single call's latency
+        // unbounded — its retry would wait out a global cooldown that exists to
+        // slow the *next* caller down. Retries use the backoff.
+        //
+        // Deliberately outside the try: an open circuit is this server's own
+        // decision, not a spawn failure, and letting the catch below translate and
+        // retry it would spawn the very request the circuit exists to prevent.
+        // Waiting also happens before a slot is taken, so a cooling-down server
+        // does not sit on the concurrency queue while it waits.
+        const wait = attempt === 1 ? waitMs() : 0;
+        if (wait > 0) {
+            if (circuitOpen()) {
+                throw new YouTubeError('RATE_LIMITED', 'YouTube has refused this client repeatedly, so requests are paused.', {
+                    nextStep: `Wait about ${String(Math.ceil(wait / 60_000))} minutes. If it persists this address is likely being gated: check check_health for the cookie and PO token provider settings.`,
+                    retryable: true,
+                });
+            }
+            log('info', `${label} waiting ${String(wait)}ms before spawning`);
+            await sleep(wait, signal);
+        }
         try {
-            return await spawnOnce(args, target, timeoutMs, signal);
+            const stdout = await spawnOnce(args, target, timeoutMs, signal);
+            onSuccess();
+            return stdout;
         }
         catch (error) {
             const failure = translateExecaFailure(error, timeoutMs);
-            if (!failure.retryable || attempt >= maxAttempts)
+            const decision = onFailure(failure.code, attempt);
+            // The error's own `retryable` wins over the pacer's policy. The
+            // classifier read the stderr and knows whether a retry can help; the
+            // pacer only knows the code. Dropping this gate made every unclassified
+            // YTDLP_FAILED retry, doubling requests on exactly the failures we cannot
+            // diagnose — the opposite of the point.
+            if (!failure.retryable || decision.giveUp || attempt >= maxAttempts)
                 throw failure;
-            const delay = backoffDelay(attempt);
-            log('warning', `${label} failed (${failure.code}), retrying in ${delay}ms`);
+            log('warning', `${label} failed (${failure.code}), retrying in ${String(decision.delayMs)}ms`);
             // The slot is already released, so the backoff does not hold the queue.
-            await sleep(delay, signal);
+            await sleep(decision.delayMs, signal);
         }
     }
 }

package/dist/utils/ytdlp.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "youtube-knowledge-mcp",
-  "version": "2.2.0",
+  "version": "3.0.1",
   "description": "MCP Server for extracting and managing YouTube video knowledge",
   "author": "teobouancheau",
   "repository": {
@@ -42,9 +42,13 @@
     "test:coverage": "vitest run --coverage",
     "test:e2e": "npm run build && vitest run -c vitest.e2e.config.ts",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:coverage",
+    "validate": "npm run secrets && npm run typecheck && npm run lint && npm run format:check && npm run test:coverage",
     "prepare": "husky",
-    "prepublishOnly": "npm run rebuild && npm run validate"
+    "prepublishOnly": "npm run rebuild && npm run validate",
+    "render:icon": "node scripts/render-icon.mjs",
+    "secrets": "sh scripts/secret-scan.sh tree",
+    "audit": "npm audit --audit-level=moderate",
+    "smoke": "npm run build && node scripts/smoke.mjs"
   },
   "files": [
     "dist"
@@ -66,6 +70,8 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
     "@eslint/js": "^10.0.1",
     "@types/express": "^5.0.6",
     "@types/node": "^22.20.1",
@@ -83,6 +89,6 @@
     "vitest": "^4.1.10"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.13.0"
   }
 }