youtube-knowledge-mcp 2.1.0 → 3.0.0

package/dist/utils/coverage-text.js

@@ -0,0 +1,62 @@
+/**
+ * The human- and model-readable form of a receipt.
+ *
+ * `structuredContent` carries the machine-readable truth, but a model reads
+ * the text block, and that is where an overclaim actually happens. So every
+ * extraction tool prepends this, from one function, rather than each writing
+ * its own wording and drifting.
+ *
+ * The incomplete form says three things on purpose: the numbers, why it
+ * stopped, and an explicit instruction not to describe it as everything. The
+ * last one reads as belt-and-braces next to the `complete: false` field, and
+ * it is: the field is for programs, the sentence is for the reader.
+ */
+const UNITS = {
+    'channel-catalog': 'videos',
+    'video-details': 'videos',
+    'video-comments': 'comments',
+};
+const WHY = {
+    COMPLETE: 'complete',
+    CAP_REACHED: 'stopped by the requested cap',
+    BUDGET_SPENT: 'stopped when the time budget ran out',
+    RATE_LIMITED: 'stopped because YouTube throttled this client',
+    CANCELLED: 'cancelled by the client',
+    TIMEOUT: 'timed out',
+    SOURCE_REFUSED: 'YouTube refused this content to the current session',
+    COMMENTS_DISABLED: 'comments are turned off for this video',
+    SOURCE_SILENT: 'YouTube states no total, so exhaustion cannot be proven',
+    PARTIAL_ERROR: 'some items failed',
+    NOT_ATTEMPTED: 'not attempted yet',
+};
+function count(value) {
+    return value.toLocaleString('en-US');
+}
+function ratio(coverage) {
+    if (coverage.expected === undefined || coverage.expected === 0)
+        return '';
+    const percent = (coverage.have / coverage.expected) * 100;
+    return ` (${percent < 0.1 && percent > 0 ? '<0.1' : percent.toFixed(1)}%)`;
+}
+export function renderCoverage(coverage) {
+    const unit = UNITS[coverage.scope];
+    const of = coverage.expected === undefined
+        ? `${count(coverage.have)} ${unit}`
+        : `${count(coverage.have)} of ${coverage.expectedSource === 'youtube:comment_count' ? 'about ' : ''}${count(coverage.expected)} ${unit}${ratio(coverage)}`;
+    const lines = [`Coverage: ${of} for ${coverage.targetId}.`];
+    if (coverage.complete) {
+        lines.push(`COMPLETE — ${WHY[coverage.reason]}, harvested ${coverage.harvestedAt}.`);
+        if (coverage.staleAfter !== undefined) {
+            lines.push(`Re-check after ${coverage.staleAfter} (this can change upstream).`);
+        }
+        return lines.join('\n');
+    }
+    const bias = coverage.sortApplied === 'top' && coverage.limitApplied !== undefined
+        ? ', sorted by "top" (a biased prefix, not a random sample)'
+        : '';
+    lines.push(`INCOMPLETE — ${WHY[coverage.reason]}${bias}.`, `Do not describe this as the full ${unit === 'comments' ? 'comment history' : 'video list'}.`);
+    if (coverage.note !== undefined)
+        lines.push(coverage.note);
+    return lines.join('\n');
+}
+//# sourceMappingURL=coverage-text.js.map

package/dist/utils/coverage-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-text.js","sourceRoot":"","sources":["../../src/utils/coverage-text.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,KAAK,GAAsC;IAC/C,iBAAiB,EAAE,QAAQ;IAC3B,eAAe,EAAE,QAAQ;IACzB,gBAAgB,EAAE,UAAU;CAC7B,CAAC;AAEF,MAAM,GAAG,GAAuC;IAC9C,QAAQ,EAAE,UAAU;IACpB,WAAW,EAAE,8BAA8B;IAC3C,YAAY,EAAE,sCAAsC;IACpD,YAAY,EAAE,+CAA+C;IAC7D,SAAS,EAAE,yBAAyB;IACpC,OAAO,EAAE,WAAW;IACpB,cAAc,EAAE,qDAAqD;IACrE,iBAAiB,EAAE,wCAAwC;IAC3D,aAAa,EAAE,yDAAyD;IACxE,aAAa,EAAE,mBAAmB;IAClC,aAAa,EAAE,mBAAmB;CACnC,CAAC;AAEF,SAAS,KAAK,CAAC,KAAa;IAC1B,OAAO,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,KAAK,CAAC,QAAkB;IAC/B,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1E,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC;IAC1D,OAAO,KAAK,OAAO,GAAG,GAAG,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,EAAE,GACN,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAC7B,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE;QACnC,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,cAAc,KAAK,uBAAuB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IAE/J,MAAM,KAAK,GAAG,CAAC,aAAa,EAAE,QAAQ,QAAQ,CAAC,QAAQ,GAAG,CAAC,CAAC;IAE5D,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,eAAe,QAAQ,CAAC,WAAW,GAAG,CAAC,CAAC;QACrF,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,kBAAkB,QAAQ,CAAC,UAAU,8BAA8B,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,IAAI,GACR,QAAQ,CAAC,WAAW,KAAK,KAAK,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS;QACnE,CAAC,CAAC,0DAA0D;QAC5D,CAAC,CAAC,EAAE,CAAC;IAET,KAAK,CAAC,IAAI,CACR,gBAAgB,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,EAC9C,oCAAoC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,YAAY,GAAG,CAC9F,CAAC;IACF,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE3D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/utils/coverage.d.ts

@@ -0,0 +1,57 @@
+import { type Coverage, type CompletenessReason, type ExpectedSource, type HarvestScope } from '../harvest-schemas.js';
+/**
+ * The one constructor for a completeness receipt.
+ *
+ * A wrong `complete: true` is the worst thing this server can emit: it is the
+ * difference between a consumer saying "here is a sample of the comments" and
+ * "here is the video's full comment history". So `complete` is not a field a
+ * caller sets — it is derived here, and the derivation is guarded by
+ * invariants that are asserted in code rather than merely documented.
+ *
+ * The rule that does the most work: `expected` is what the SOURCE said, and is
+ * never derived from `have`. Copying the number we collected into the field
+ * that means "how many there are" would turn "we stopped" into "there was
+ * nothing more", silently, and every check downstream would agree with it.
+ */
+/** A complete receipt is still only as fresh as its harvest; comments accrue. */
+export declare const RECEIPT_STALE_MS: number;
+/** Beyond this, receipts are summarised rather than listed in a tool result. */
+export declare const COVERAGE_IN_RESULT_LIMIT = 100;
+export interface ExpectedTotal {
+    value: number;
+    source: ExpectedSource;
+}
+export interface CoverageInput {
+    scope: HarvestScope;
+    targetId: string;
+    have: number;
+    source: string;
+    /**
+     * Only ever an explicit pair or nothing. There is deliberately no code path
+     * that accepts a bare number, because the number would have to come from
+     * somewhere and `have` is the nearest thing to hand.
+     */
+    expected?: ExpectedTotal;
+    ranToExhaustion?: boolean;
+    reason?: CompletenessReason;
+    limitApplied?: number;
+    sortApplied?: 'top' | 'new';
+    resumeToken?: string;
+    harvestedAt?: Date;
+    note?: string;
+}
+/** Thrown for a receipt that contradicts itself. Not a YouTubeError: no caller can fix it. */
+export declare class CoverageInvariantError extends Error {
+    constructor(message: string);
+}
+/**
+ * Checks a receipt against every invariant.
+ *
+ * Called inside `coverageOf` and again by handlers before a result goes out,
+ * because the cost of the second call is nothing and the cost of a wrong
+ * `complete: true` reaching a consumer is the whole point of this module.
+ */
+export declare function assertCoverageConsistent(coverage: Coverage): void;
+/** Builds a validated receipt. The only way to make one. */
+export declare function coverageOf(input: CoverageInput): Coverage;
+//# sourceMappingURL=coverage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/utils/coverage.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AAEH,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAE/C,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAwCD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CA0CjE;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CA8BzD"}

package/dist/utils/coverage.js

@@ -0,0 +1,142 @@
+import { coverageSchema, } from '../harvest-schemas.js';
+/**
+ * The one constructor for a completeness receipt.
+ *
+ * A wrong `complete: true` is the worst thing this server can emit: it is the
+ * difference between a consumer saying "here is a sample of the comments" and
+ * "here is the video's full comment history". So `complete` is not a field a
+ * caller sets — it is derived here, and the derivation is guarded by
+ * invariants that are asserted in code rather than merely documented.
+ *
+ * The rule that does the most work: `expected` is what the SOURCE said, and is
+ * never derived from `have`. Copying the number we collected into the field
+ * that means "how many there are" would turn "we stopped" into "there was
+ * nothing more", silently, and every check downstream would agree with it.
+ */
+/** A complete receipt is still only as fresh as its harvest; comments accrue. */
+export const RECEIPT_STALE_MS = 7 * 86_400_000;
+/** Beyond this, receipts are summarised rather than listed in a tool result. */
+export const COVERAGE_IN_RESULT_LIMIT = 100;
+/** Thrown for a receipt that contradicts itself. Not a YouTubeError: no caller can fix it. */
+export class CoverageInvariantError extends Error {
+    constructor(message) {
+        super(`Coverage invariant violated: ${message}`);
+        this.name = 'CoverageInvariantError';
+    }
+}
+function capWasBinding(input) {
+    return input.limitApplied !== undefined && input.have >= input.limitApplied;
+}
+/**
+ * Whether this server can prove it holds everything in scope.
+ *
+ * Two independent ways to prove it, and a cap overrides both:
+ *
+ *   - the source stated a total and we hold at least that many, or
+ *   - the source's own iteration ran out (`source-exhausted`).
+ *
+ * Exhaustion alone is not proof. Measured against yt-dlp 2026.08.19: a run
+ * capped at 40 parent comments returned a non-null `comment_count` of 58,
+ * because `itertools.islice` ends iteration at the cap exactly as a natural
+ * end would. So a binding cap disqualifies completeness even when the source
+ * says it finished.
+ */
+function isProvablyComplete(input) {
+    if (capWasBinding(input))
+        return false;
+    if (input.expected !== undefined) {
+        if (input.expected.source === 'source-exhausted')
+            return input.ranToExhaustion !== false;
+        return input.have >= input.expected.value;
+    }
+    return false;
+}
+function derivedReason(input, complete) {
+    if (complete)
+        return 'COMPLETE';
+    if (input.reason !== undefined && input.reason !== 'COMPLETE')
+        return input.reason;
+    if (capWasBinding(input))
+        return 'CAP_REACHED';
+    // Nothing said there was more, and nothing proved there was not. That is not
+    // completeness; it is the absence of evidence, and it has its own name.
+    return 'SOURCE_SILENT';
+}
+/**
+ * Checks a receipt against every invariant.
+ *
+ * Called inside `coverageOf` and again by handlers before a result goes out,
+ * because the cost of the second call is nothing and the cost of a wrong
+ * `complete: true` reaching a consumer is the whole point of this module.
+ */
+export function assertCoverageConsistent(coverage) {
+    const fail = (message) => {
+        throw new CoverageInvariantError(message);
+    };
+    if (coverage.complete && coverage.reason !== 'COMPLETE') {
+        fail(`complete is true but reason is ${coverage.reason}`);
+    }
+    if (!coverage.complete && coverage.reason === 'COMPLETE') {
+        fail('reason is COMPLETE but complete is false');
+    }
+    if ((coverage.expected === undefined) !== (coverage.expectedSource === undefined)) {
+        fail('expected and expectedSource must be present or absent together');
+    }
+    if (coverage.complete) {
+        const exhausted = coverage.expectedSource === 'source-exhausted';
+        const enough = coverage.expected !== undefined && coverage.have >= coverage.expected;
+        if (!exhausted && !enough) {
+            fail('complete is true without either a met expected total or an exhausted source');
+        }
+    }
+    // There is deliberately no separate "COMPLETE without an expected total"
+    // guard. It reads like a necessary invariant and is unreachable: reaching it
+    // needs reason COMPLETE, which the checks above already force to pair with
+    // complete:true, which in turn already demands either a met total or an
+    // exhausted source. An unreachable guard is not defence in depth, it is code
+    // no test can justify.
+    // One-directional on purpose. "A token exactly when incomplete" is the
+    // tempting symmetry, and it is wrong: plenty of incomplete receipts have
+    // nothing to resume — SOURCE_REFUSED, COMMENTS_DISABLED, a caller that
+    // simply did not supply one. What must never happen is a token on a
+    // complete receipt, which would invite a caller to page past the end.
+    if (coverage.resumeToken !== undefined && coverage.complete) {
+        fail('a complete receipt cannot carry a resumeToken');
+    }
+    if (coverage.limitApplied !== undefined &&
+        coverage.have >= coverage.limitApplied &&
+        coverage.reason === 'COMPLETE') {
+        fail('a binding cap cannot produce COMPLETE');
+    }
+}
+/** Builds a validated receipt. The only way to make one. */
+export function coverageOf(input) {
+    const complete = isProvablyComplete(input);
+    const reason = derivedReason(input, complete);
+    const harvestedAt = input.harvestedAt ?? new Date();
+    const coverage = coverageSchema.parse({
+        scope: input.scope,
+        targetId: input.targetId,
+        complete,
+        reason,
+        have: input.have,
+        ...(input.expected === undefined
+            ? {}
+            : { expected: input.expected.value, expectedSource: input.expected.source }),
+        ...(input.ranToExhaustion === undefined ? {} : { ranToExhaustion: input.ranToExhaustion }),
+        source: input.source,
+        harvestedAt: harvestedAt.toISOString(),
+        ...(complete
+            ? { staleAfter: new Date(harvestedAt.getTime() + RECEIPT_STALE_MS).toISOString() }
+            : {}),
+        ...(input.limitApplied === undefined ? {} : { limitApplied: input.limitApplied }),
+        ...(input.sortApplied === undefined ? {} : { sortApplied: input.sortApplied }),
+        // A resume token is meaningless on a complete receipt, and its absence is
+        // how a caller knows there is nothing left to ask for.
+        ...(complete || input.resumeToken === undefined ? {} : { resumeToken: input.resumeToken }),
+        ...(input.note === undefined ? {} : { note: input.note }),
+    });
+    assertCoverageConsistent(coverage);
+    return coverage;
+}
+//# sourceMappingURL=coverage.js.map

package/dist/utils/coverage.js.map

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

package/dist/utils/env.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reading configuration from the environment without trusting it.
+ *
+ * A bare `Number()` of an environment value turns a typo into `NaN`, and `NaN` compares
+ * false with everything: a concurrency limit of `NaN` queued every yt-dlp call
+ * forever, and a cache TTL of `NaN` never expired anything. Every numeric or
+ * enumerated setting therefore comes through here, where an unusable value
+ * falls back to the default and says so once on stderr.
+ */
+export interface IntBounds {
+    min?: number;
+    max?: number;
+}
+export declare function envString(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function envInt(name: string, fallback: number, bounds?: IntBounds, env?: NodeJS.ProcessEnv): number;
+export declare function envBool(name: string, fallback: boolean, env?: NodeJS.ProcessEnv): boolean;
+export declare function envList(name: string, env?: NodeJS.ProcessEnv): string[];
+/**
+ * One of a closed set of values, or `undefined` when unset.
+ *
+ * Unlike the helpers above this throws on an unknown value: a browser name or
+ * proxy scheme that is misspelt is a configuration mistake the operator wants
+ * to hear about at boot, not a setting to quietly ignore.
+ */
+export declare function envEnum<T extends string>(name: string, values: readonly T[], env?: NodeJS.ProcessEnv): T | undefined;
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAMD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAGhG;AAED,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,SAAc,EACtB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAkBR;AAKD,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,EACjB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAOT;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAKpF;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,CAAC,GAAG,SAAS,CASf"}

package/dist/utils/env.js

@@ -0,0 +1,72 @@
+/**
+ * Reading configuration from the environment without trusting it.
+ *
+ * A bare `Number()` of an environment value turns a typo into `NaN`, and `NaN` compares
+ * false with everything: a concurrency limit of `NaN` queued every yt-dlp call
+ * forever, and a cache TTL of `NaN` never expired anything. Every numeric or
+ * enumerated setting therefore comes through here, where an unusable value
+ * falls back to the default and says so once on stderr.
+ */
+function warn(name, reason) {
+    console.error(`Ignoring ${name}: ${reason}.`);
+}
+export function envString(name, env = process.env) {
+    const value = env[name]?.trim();
+    return value === undefined || value === '' ? undefined : value;
+}
+export function envInt(name, fallback, bounds = {}, env = process.env) {
+    const raw = envString(name, env);
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed)) {
+        warn(name, `"${raw}" is not a whole number, using ${fallback}`);
+        return fallback;
+    }
+    if (bounds.min !== undefined && parsed < bounds.min) {
+        warn(name, `${parsed} is below the minimum of ${bounds.min}, using ${fallback}`);
+        return fallback;
+    }
+    if (bounds.max !== undefined && parsed > bounds.max) {
+        warn(name, `${parsed} is above the maximum of ${bounds.max}, using ${fallback}`);
+        return fallback;
+    }
+    return parsed;
+}
+const TRUE_WORDS = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_WORDS = new Set(['0', 'false', 'no', 'off']);
+export function envBool(name, fallback, env = process.env) {
+    const raw = envString(name, env)?.toLowerCase();
+    if (raw === undefined)
+        return fallback;
+    if (TRUE_WORDS.has(raw))
+        return true;
+    if (FALSE_WORDS.has(raw))
+        return false;
+    warn(name, `"${raw}" is not a boolean, using ${String(fallback)}`);
+    return fallback;
+}
+export function envList(name, env = process.env) {
+    return (env[name] ?? '')
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+/**
+ * One of a closed set of values, or `undefined` when unset.
+ *
+ * Unlike the helpers above this throws on an unknown value: a browser name or
+ * proxy scheme that is misspelt is a configuration mistake the operator wants
+ * to hear about at boot, not a setting to quietly ignore.
+ */
+export function envEnum(name, values, env = process.env) {
+    const raw = envString(name, env);
+    if (raw === undefined)
+        return undefined;
+    const match = values.find((value) => value === raw.toLowerCase());
+    if (match === undefined) {
+        throw new Error(`${name} must be one of ${values.join(', ')}; got "${raw}".`);
+    }
+    return match;
+}
+//# sourceMappingURL=env.js.map

package/dist/utils/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,SAAS,IAAI,CAAC,IAAY,EAAE,MAAc;IACxC,OAAO,CAAC,KAAK,CAAC,YAAY,IAAI,KAAK,MAAM,GAAG,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC1E,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IAChC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,MAAM,CACpB,IAAY,EACZ,QAAgB,EAChB,SAAoB,EAAE,EACtB,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAEvC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,kCAAkC,QAAQ,EAAE,CAAC,CAAC;QAChE,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC;QACpD,IAAI,CAAC,IAAI,EAAE,GAAG,MAAM,4BAA4B,MAAM,CAAC,GAAG,WAAW,QAAQ,EAAE,CAAC,CAAC;QACjF,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC;QACpD,IAAI,CAAC,IAAI,EAAE,GAAG,MAAM,4BAA4B,MAAM,CAAC,GAAG,WAAW,QAAQ,EAAE,CAAC,CAAC;QACjF,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AACvD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAEzD,MAAM,UAAU,OAAO,CACrB,IAAY,EACZ,QAAiB,EACjB,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC;IAChD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACvC,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,6BAA6B,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,MAAyB,OAAO,CAAC,GAAG;IACxE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CACrB,IAAY,EACZ,MAAoB,EACpB,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAExC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IAClE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,mBAAmB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/errors.d.ts

@@ -7,7 +7,7 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
  * than a wall of yt-dlp stderr it has to guess at — and never a leaked command
  * line or stack trace.
  */
-export type YouTubeErrorCode = 'PRIVATE' | 'AGE_GATED' | 'MEMBERS_ONLY' | 'PREMIUM_ONLY' | 'LOGIN_REQUIRED' | 'NOT_FOUND' | 'NO_CAPTIONS' | 'LIVE_NOT_ENDED' | 'RATE_LIMITED' | 'TIMEOUT' | 'CANCELLED' | 'YTDLP_MISSING' | 'FFMPEG_MISSING' | 'YTDLP_FAILED' | 'MALFORMED_RESPONSE' | 'INVALID_INPUT';
+export type YouTubeErrorCode = 'PRIVATE' | 'AGE_GATED' | 'MEMBERS_ONLY' | 'PREMIUM_ONLY' | 'LOGIN_REQUIRED' | 'BOT_CHECK' | 'NOT_FOUND' | 'NO_CAPTIONS' | 'LIVE_NOT_ENDED' | 'RATE_LIMITED' | 'TIMEOUT' | 'CANCELLED' | 'YTDLP_MISSING' | 'FFMPEG_MISSING' | 'YTDLP_FAILED' | 'FETCH_FAILED' | 'MALFORMED_RESPONSE' | 'INVALID_INPUT' | 'STORE_UNAVAILABLE' | 'STORE_CORRUPT';
 export interface YouTubeErrorOptions {
     /** What the caller should try next. Shown to the model verbatim. */
     nextStep?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,WAAW,GACX,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,WAAW,GACX,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,SAAS,GACT,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,oBAAoB,GACpB,eAAe,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;IAQtF,iFAAiF;IACjF,aAAa,IAAI,MAAM;CAGxB;AA6ED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,YAAY,CAkBlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,YAAY,GAAG,SAAS,CA4C3B;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAQ3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAM1D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,WAAW,GACX,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,WAAW,GACX,WAAW,GACX,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,SAAS,GACT,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,oBAAoB,GACpB,eAAe,GACf,mBAAmB,GACnB,eAAe,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;IAQtF,iFAAiF;IACjF,aAAa,IAAI,MAAM;CAGxB;AAwGD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,YAAY,CAkBlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,YAAY,GAAG,SAAS,CA2C3B;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAQ3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAM1D"}

package/dist/utils/errors.js

@@ -14,7 +14,33 @@ export class YouTubeError extends Error {
         return this.nextStep ? `${this.message}\n\n${this.nextStep}` : this.message;
     }
 }
+/** The two settings that let yt-dlp read what a signed-out client cannot. */
+const COOKIE_HINT = 'Set YOUTUBE_MCP_COOKIES_FROM_BROWSER (for example chrome) or YOUTUBE_MCP_COOKIES_FILE and restart the server; see the README section on signed-in content.';
 const RULES = [
+    {
+        // The one YouTube-authored sentence matched here, and the reason is that
+        // it was observed rather than remembered: on 2026-09-05 every per-video
+        // read from this project's own address printed it, verbatim, while flat
+        // channel listings kept working — so it is about the client, not the
+        // video, and the remedy is different. Matched on the words before the
+        // apostrophe, which YouTube writes as U+2019. Should YouTube reword it,
+        // the login hint yt-dlp appends still lands on LOGIN_REQUIRED below, whose
+        // next step names the same cookie settings. Listed first because both
+        // strings appear in the same output.
+        code: 'BOT_CHECK',
+        emits: 'Sign in to confirm you',
+        source: 'playabilityStatus.reason, re-raised by yt_dlp/extractor/youtube/_video.py',
+        message: 'YouTube is asking this client to prove it is not a bot.',
+        // Ordered by what was measured on 2026-09-06, not by what sounds most
+        // technical. From a datacenter address every account-free lever was
+        // installed and tested — a PO token provider (yt-dlp never even reaches
+        // the point of requesting one; it fails at the player response first),
+        // eight player clients, a 15-minute cooldown, and curl_cffi TLS
+        // impersonation — and none of them changed the answer. So the address
+        // comes first and the PO token provider comes last: leading with a remedy
+        // that was measured not to work sends the reader down a dead end.
+        nextStep: `Per-video reads are refused from this address. Datacenter and VPN/exit-node addresses are gated regardless of client settings, so check whether this host egresses through one. Otherwise: ${COOKIE_HINT} On a residential address a missing PO token provider can be the cause instead — check \`check_health\`.`,
+    },
     {
         code: 'RATE_LIMITED',
         // exceptions.py formats `HTTP Error {status}: {reason}`; the reason for 429
@@ -55,7 +81,7 @@ const RULES = [
         emits: 'for tips on effectively exporting YouTube cookies',
         source: 'yt_dlp/extractor/youtube/_base.py:664',
         message: 'This video requires a signed-in YouTube account.',
-        nextStep: 'It may be private, age-restricted or members-only. Try a different video, or configure yt-dlp with browser cookies.',
+        nextStep: `It may be private, age-restricted or members-only. ${COOKIE_HINT}`,
     },
 ];
 /**
@@ -108,7 +134,7 @@ export function classifyPlayability(fields) {
             });
         case 'needs_auth':
             return new YouTubeError('AGE_GATED', 'This video is age-restricted and requires a signed-in account.', {
-                nextStep: 'Age-gated videos cannot be read without authentication. Try a different video, or configure yt-dlp with browser cookies.',
+                nextStep: `Age-gated videos cannot be read without authentication. ${COOKIE_HINT}`,
             });
     }
     // 'is_live' is deliberately absent: a stream in progress has real metadata,

package/dist/utils/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAoCA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,QAAQ,CAAU;IAClB,SAAS,CAAU;IAE5B,YAAY,IAAsB,EAAE,OAAe,EAAE,UAA+B,EAAE;QACpF,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC9C,CAAC;IAED,iFAAiF;IACjF,aAAa;QACX,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IAC9E,CAAC;CACF;AA8BD,MAAM,KAAK,GAAW;IACpB;QACE,IAAI,EAAE,cAAc;QACpB,4EAA4E;QAC5E,wDAAwD;QACxD,KAAK,EAAE,gBAAgB;QACvB,MAAM,EAAE,oCAAoC;QAC5C,OAAO,EAAE,uCAAuC;QAChD,QAAQ,EAAE,kEAAkE;QAC5E,SAAS,EAAE,IAAI;KAChB;IACD;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,oDAAoD;QAC3D,MAAM,EAAE,0BAA0B;QAClC,OAAO,EAAE,qEAAqE;QAC9E,QAAQ,EACN,uFAAuF;KAC1F;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,6BAA6B;QACpC,MAAM,EAAE,0BAA0B;QAClC,OAAO,EAAE,6DAA6D;QACtE,QAAQ,EAAE,gEAAgE;KAC3E;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,8EAA8E;QACrF,MAAM,EAAE,oCAAoC;QAC5C,OAAO,EAAE,6DAA6D;QACtE,QAAQ,EAAE,gEAAgE;KAC3E;IACD;QACE,oEAAoE;QACpE,yEAAyE;QACzE,yEAAyE;QACzE,iEAAiE;QACjE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,mDAAmD;QAC1D,MAAM,EAAE,uCAAuC;QAC/C,OAAO,EAAE,kDAAkD;QAC3D,QAAQ,EACN,qHAAqH;KACxH;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,KAAe;IAClE,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAEtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAChD,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE;gBAC/C,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,KAAK;aACN,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,yCAAyC,EAAE;QACjF,QAAQ,EACN,kLAAkL;QACpL,KAAK;KACN,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAGnC;IACC,QAAQ,MAAM,CAAC,YAAY,EAAE,CAAC;QAC5B,KAAK,SAAS;YACZ,OAAO,IAAI,YAAY,CAAC,SAAS,EAAE,wBAAwB,EAAE;gBAC3D,QAAQ,EAAE,0EAA0E;aACrF,CAAC,CAAC;QACL,KAAK,iBAAiB;YACpB,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,8CAA8C,EAAE;gBACtF,QAAQ,EAAE,iEAAiE;aAC5E,CAAC,CAAC;QACL,KAAK,cAAc;YACjB,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,gDAAgD,EAAE;gBACxF,QAAQ,EAAE,4DAA4D;aACvE,CAAC,CAAC;QACL,KAAK,YAAY;YACf,OAAO,IAAI,YAAY,CACrB,WAAW,EACX,gEAAgE,EAChE;gBACE,QAAQ,EACN,0HAA0H;aAC7H,CACF,CAAC;IACN,CAAC;IAED,4EAA4E;IAC5E,gDAAgD;IAChD,QAAQ,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1B,KAAK,aAAa;YAChB,OAAO,IAAI,YAAY,CAAC,gBAAgB,EAAE,uCAAuC,EAAE;gBACjF,QAAQ,EAAE,qEAAqE;aAChF,CAAC,CAAC;QACL,KAAK,WAAW;YACd,OAAO,IAAI,YAAY,CACrB,gBAAgB,EAChB,qDAAqD,EACrD;gBACE,QAAQ,EAAE,+DAA+D;gBACzE,SAAS,EAAE,IAAI;aAChB,CACF,CAAC;IACN,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,KAAK,CAAC;IAEhD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,sCAAsC,EAAE;QAC9E,QAAQ,EAAE,0EAA0E;QACpF,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC;KAC3D,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,YAAY,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,YAAY,CAAC,IAAI,KAAK,YAAY,CAAC,aAAa,EAAE,EAAE,EAAE,CAAC;KAC5F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAwCA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,QAAQ,CAAU;IAClB,SAAS,CAAU;IAE5B,YAAY,IAAsB,EAAE,OAAe,EAAE,UAA+B,EAAE;QACpF,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC9C,CAAC;IAED,iFAAiF;IACjF,aAAa;QACX,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IAC9E,CAAC;CACF;AA8BD,6EAA6E;AAC7E,MAAM,WAAW,GACf,4JAA4J,CAAC;AAE/J,MAAM,KAAK,GAAW;IACpB;QACE,yEAAyE;QACzE,wEAAwE;QACxE,wEAAwE;QACxE,qEAAqE;QACrE,sEAAsE;QACtE,wEAAwE;QACxE,2EAA2E;QAC3E,sEAAsE;QACtE,qCAAqC;QACrC,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,wBAAwB;QAC/B,MAAM,EAAE,2EAA2E;QACnF,OAAO,EAAE,yDAAyD;QAClE,sEAAsE;QACtE,oEAAoE;QACpE,wEAAwE;QACxE,uEAAuE;QACvE,gEAAgE;QAChE,sEAAsE;QACtE,0EAA0E;QAC1E,kEAAkE;QAClE,QAAQ,EAAE,8LAA8L,WAAW,0GAA0G;KAC9T;IACD;QACE,IAAI,EAAE,cAAc;QACpB,4EAA4E;QAC5E,wDAAwD;QACxD,KAAK,EAAE,gBAAgB;QACvB,MAAM,EAAE,oCAAoC;QAC5C,OAAO,EAAE,uCAAuC;QAChD,QAAQ,EAAE,kEAAkE;QAC5E,SAAS,EAAE,IAAI;KAChB;IACD;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,oDAAoD;QAC3D,MAAM,EAAE,0BAA0B;QAClC,OAAO,EAAE,qEAAqE;QAC9E,QAAQ,EACN,uFAAuF;KAC1F;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,6BAA6B;QACpC,MAAM,EAAE,0BAA0B;QAClC,OAAO,EAAE,6DAA6D;QACtE,QAAQ,EAAE,gEAAgE;KAC3E;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,8EAA8E;QACrF,MAAM,EAAE,oCAAoC;QAC5C,OAAO,EAAE,6DAA6D;QACtE,QAAQ,EAAE,gEAAgE;KAC3E;IACD;QACE,oEAAoE;QACpE,yEAAyE;QACzE,yEAAyE;QACzE,iEAAiE;QACjE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,mDAAmD;QAC1D,MAAM,EAAE,uCAAuC;QAC/C,OAAO,EAAE,kDAAkD;QAC3D,QAAQ,EAAE,sDAAsD,WAAW,EAAE;KAC9E;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,KAAe;IAClE,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAEtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAChD,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE;gBAC/C,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,KAAK;aACN,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,yCAAyC,EAAE;QACjF,QAAQ,EACN,kLAAkL;QACpL,KAAK;KACN,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAGnC;IACC,QAAQ,MAAM,CAAC,YAAY,EAAE,CAAC;QAC5B,KAAK,SAAS;YACZ,OAAO,IAAI,YAAY,CAAC,SAAS,EAAE,wBAAwB,EAAE;gBAC3D,QAAQ,EAAE,0EAA0E;aACrF,CAAC,CAAC;QACL,KAAK,iBAAiB;YACpB,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,8CAA8C,EAAE;gBACtF,QAAQ,EAAE,iEAAiE;aAC5E,CAAC,CAAC;QACL,KAAK,cAAc;YACjB,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,gDAAgD,EAAE;gBACxF,QAAQ,EAAE,4DAA4D;aACvE,CAAC,CAAC;QACL,KAAK,YAAY;YACf,OAAO,IAAI,YAAY,CACrB,WAAW,EACX,gEAAgE,EAChE;gBACE,QAAQ,EAAE,2DAA2D,WAAW,EAAE;aACnF,CACF,CAAC;IACN,CAAC;IAED,4EAA4E;IAC5E,gDAAgD;IAChD,QAAQ,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1B,KAAK,aAAa;YAChB,OAAO,IAAI,YAAY,CAAC,gBAAgB,EAAE,uCAAuC,EAAE;gBACjF,QAAQ,EAAE,qEAAqE;aAChF,CAAC,CAAC;QACL,KAAK,WAAW;YACd,OAAO,IAAI,YAAY,CACrB,gBAAgB,EAChB,qDAAqD,EACrD;gBACE,QAAQ,EAAE,+DAA+D;gBACzE,SAAS,EAAE,IAAI;aAChB,CACF,CAAC;IACN,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,KAAK,CAAC;IAEhD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,sCAAsC,EAAE;QAC9E,QAAQ,EAAE,0EAA0E;QACpF,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC;KAC3D,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,YAAY,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,YAAY,CAAC,IAAI,KAAK,YAAY,CAAC,aAAa,EAAE,EAAE,EAAE,CAAC;KAC5F,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import type { YouTubeError } from './errors.js';
+/**
+ * Exclusive access to a directory's contents while a long job writes them.
+ *
+ * Two jobs on one channel would interleave their 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 job is never mistaken for a dead one. */
+export declare const LOCK_STALE_MS: number;
+export declare const lockRecordSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    startedAt: string;
+    pid: number;
+}, {
+    startedAt: string;
+    pid: number;
+}>;
+export type LockRecord = z.infer<typeof lockRecordSchema>;
+/**
+ * Run `work` holding the lock at `path`.
+ *
+ * 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. `held` builds the error to throw
+ * when someone else genuinely has it, so each caller can name its own tool.
+ */
+export declare function withFileLock<T>(path: string, work: () => Promise<T>, held: (existing: LockRecord | undefined) => YouTubeError): Promise<T>;
+//# sourceMappingURL=file-lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/utils/file-lock.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD;;;;;;;;GAQG;AAEH,oEAAoE;AACpE,eAAO,MAAM,aAAa,QAAiB,CAAC;AAE5C,eAAO,MAAM,gBAAgB;;;;;;;;;EAG3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,IAAI,EAAE,CAAC,QAAQ,EAAE,UAAU,GAAG,SAAS,KAAK,YAAY,GACvD,OAAO,CAAC,CAAC,CAAC,CAoBZ"}

package/dist/utils/file-lock.js

@@ -0,0 +1,91 @@
+import { rm, writeFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { readJsonFile } from './json-file.js';
+/**
+ * Exclusive access to a directory's contents while a long job writes them.
+ *
+ * Two jobs on one channel would interleave their 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 job is never mistaken for a dead one. */
+export const LOCK_STALE_MS = 30 * 60 * 1000;
+export const lockRecordSchema = z.object({
+    pid: z.number().int(),
+    startedAt: z.string(),
+});
+/**
+ * Run `work` holding the lock at `path`.
+ *
+ * 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. `held` builds the error to throw
+ * when someone else genuinely has it, so each caller can name its own tool.
+ */
+export async function withFileLock(path, work, held) {
+    if (!(await acquire(path))) {
+        const existing = await readJsonFile(path, lockRecordSchema);
+        // 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))
+            throw held(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 held(undefined);
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await rm(path, { force: true });
+    }
+}
+/**
+ * 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
+ * jobs 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 (errorCode(error) === '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 errorCode(error) === 'EPERM';
+    }
+}
+/** The `code` a Node system error carries, when it is one. */
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+//# sourceMappingURL=file-lock.js.map

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

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