@mkterswingman/5mghost-yonder 0.0.1

package/dist/tools/subtitles.js

@@ -0,0 +1,579 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { PATHS } from "../utils/config.js";
+import { runYtDlp } from "../utils/ytdlp.js";
+import { hasSIDCookies, areCookiesExpired } from "../utils/cookies.js";
+import { tryHeadlessRefresh } from "../utils/cookieRefresh.js";
+import { resolveVideoInput, normalizeVideoInputs } from "../utils/videoInput.js";
+const AUTH_REQUIRED_MSG = "❌ 未认证。请先登录：\n• OAuth: npx @mkterswingman/5mghost-yonder setup\n• PAT: 设置环境变量 YT_MCP_TOKEN 或在 https://mkterswingman.com/pat/login 生成 token";
+function toolOk(payload) {
+    return {
+        structuredContent: payload,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload),
+            },
+        ],
+    };
+}
+function toolErr(code, message) {
+    const payload = { status: "failed", error: { code, message } };
+    return {
+        structuredContent: payload,
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function randomSleep(min, max) {
+    return sleep(Math.random() * (max - min) + min);
+}
+/**
+ * Decode common HTML entities found in YouTube auto-captions.
+ */
+function decodeHtmlEntities(text) {
+    return text
+        .replace(/>/g, ">")
+        .replace(/&lt;/g, "<")
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, " ");
+}
+/**
+ * Parse a VTT timestamp line into start/end seconds + clean time strings.
+ * Input: "00:00:02.159 --> 00:00:03.590 align:start position:0%"
+ * Returns: { startStr, endStr, startSec, endSec } or null if unparseable.
+ */
+function parseTimestamp(line) {
+    // Strip positioning metadata (align:start position:0% etc.)
+    const match = line.match(/(\d{1,2}:\d{2}:\d{2}\.\d{3})\s*-->\s*(\d{1,2}:\d{2}:\d{2}\.\d{3})/);
+    if (!match)
+        return null;
+    const toSec = (t) => {
+        const parts = t.split(":");
+        return (Number(parts[0]) * 3600 + Number(parts[1]) * 60 + Number(parts[2]));
+    };
+    return {
+        startStr: match[1],
+        endStr: match[2],
+        startSec: toSec(match[1]),
+        endSec: toSec(match[2]),
+    };
+}
+/**
+ * Escape a value for CSV (RFC 4180).
+ */
+function csvEscapeField(value) {
+    if (/[",\n\r]/.test(value)) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+/**
+ * Convert VTT subtitle content to clean, human-readable CSV.
+ *
+ * YouTube auto-captions use a "rolling" VTT format where each cue has two
+ * lines: the first line repeats the previous cue's text, and the second line
+ * contains new words (marked with <c> tags for word-level timing). This
+ * function detects and handles this pattern:
+ *
+ * 1. Detects auto-caption format (presence of <c> word-timing tags)
+ * 2. For auto-captions: extracts only the NEW text from each cue's second
+ *    line, skips transition cues, and concatenates into clean sentences
+ * 3. For manual subtitles: passes through cleanly with no data loss
+ * 4. Outputs: start_time, end_time, text
+ */
+function vttToCsv(vtt) {
+    const lines = vtt.split("\n");
+    const isAutoCaption = /<\d{2}:\d{2}:\d{2}\.\d{3}><c>/.test(vtt);
+    const rawCues = [];
+    let currentTs = null;
+    let currentTextLines = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.includes(" --> ")) {
+            // Flush previous cue
+            if (currentTs && currentTextLines.length > 0) {
+                let text;
+                if (isAutoCaption && currentTextLines.length >= 2) {
+                    // Auto-caption: line 1 = repeated text, line 2 = new text with <c> tags
+                    // Only take line 2 (new content)
+                    text = decodeHtmlEntities(currentTextLines[currentTextLines.length - 1]
+                        .replace(/<[^>]*>/g, "")
+                        .trim());
+                }
+                else {
+                    // Manual subtitle or single-line cue: take all lines
+                    text = decodeHtmlEntities(currentTextLines
+                        .map((l) => l.replace(/<[^>]*>/g, "").trim())
+                        .filter(Boolean)
+                        .join(" "));
+                }
+                if (text) {
+                    rawCues.push({ ...currentTs, text });
+                }
+            }
+            currentTs = parseTimestamp(trimmed);
+            currentTextLines = [];
+        }
+        else if (trimmed &&
+            !trimmed.startsWith("WEBVTT") &&
+            !trimmed.startsWith("Kind:") &&
+            !trimmed.startsWith("Language:") &&
+            !/^\d+$/.test(trimmed)) {
+            currentTextLines.push(trimmed);
+        }
+    }
+    // Flush last
+    if (currentTs && currentTextLines.length > 0) {
+        let text;
+        if (isAutoCaption && currentTextLines.length >= 2) {
+            text = decodeHtmlEntities(currentTextLines[currentTextLines.length - 1]
+                .replace(/<[^>]*>/g, "")
+                .trim());
+        }
+        else {
+            text = decodeHtmlEntities(currentTextLines
+                .map((l) => l.replace(/<[^>]*>/g, "").trim())
+                .filter(Boolean)
+                .join(" "));
+        }
+        if (text) {
+            rawCues.push({ ...currentTs, text });
+        }
+    }
+    if (rawCues.length === 0) {
+        return "start_time,end_time,text\n";
+    }
+    // ── Step 2: Deduplicate ───────────────────────────────────────
+    const deduped = [];
+    for (let i = 0; i < rawCues.length; i++) {
+        const cur = rawCues[i];
+        // Skip tiny transition cues (duration < 50ms)
+        const duration = cur.endSec - cur.startSec;
+        if (duration < 0.05)
+            continue;
+        // Merge with previous if same text
+        if (deduped.length > 0 && deduped[deduped.length - 1].text === cur.text) {
+            deduped[deduped.length - 1].endSec = cur.endSec;
+            deduped[deduped.length - 1].endStr = cur.endStr;
+            continue;
+        }
+        deduped.push({ ...cur });
+    }
+    // ── Step 3: Build CSV ─────────────────────────────────────────
+    const csvRows = ["start_time,end_time,text"];
+    for (const cue of deduped) {
+        csvRows.push(`${cue.startStr},${cue.endStr},${csvEscapeField(cue.text)}`);
+    }
+    return csvRows.join("\n") + "\n";
+}
+function todayDateStr() {
+    const d = new Date();
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}`;
+}
+async function downloadSubtitle(videoId, lang, format) {
+    mkdirSync(PATHS.subtitlesDir, { recursive: true });
+    const outTemplate = join(PATHS.subtitlesDir, `${todayDateStr()}_${videoId}_${lang}`);
+    // CSV is not a yt-dlp native format — download as VTT then convert
+    const dlFormat = format === "csv" ? "vtt" : format;
+    const result = await runYtDlp([
+        "--skip-download",
+        "-f", "mhtml",
+        "--write-sub",
+        "--write-auto-sub",
+        "--sub-langs",
+        lang,
+        "--sub-format",
+        dlFormat,
+        "--output",
+        outTemplate,
+        `https://www.youtube.com/watch?v=${videoId}`,
+    ]);
+    if (result.exitCode !== 0 &&
+        (result.stderr.includes("Sign in") ||
+            result.stderr.includes("cookies") ||
+            result.stderr.includes("login"))) {
+        return { ok: false, cookiesExpired: true, error: "COOKIES_EXPIRED" };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            ok: false,
+            error: result.stderr.slice(0, 500) || `yt-dlp exited with ${result.exitCode}`,
+        };
+    }
+    // Find the output file - yt-dlp appends lang and format extension.
+    // For CSV: yt-dlp downloads as VTT first, so only search for VTT (not stale .csv from previous runs).
+    const searchFormat = format === "csv" ? "vtt" : format;
+    const possibleExts = [`${lang}.${searchFormat}`, `${lang}.vtt`, `${lang}.srt`, `${lang}.ttml`, `${lang}.srv3`];
+    let foundFile;
+    for (const ext of possibleExts) {
+        const candidate = `${outTemplate}.${ext}`;
+        if (existsSync(candidate)) {
+            foundFile = candidate;
+            break;
+        }
+    }
+    if (!foundFile) {
+        // Try auto-generated subtitles which may have slightly different naming
+        const dir = PATHS.subtitlesDir;
+        try {
+            const files = readdirSync(dir);
+            const prefix = `${todayDateStr()}_${videoId}_${lang}`;
+            const match = files.find((f) => f.startsWith(prefix));
+            if (match) {
+                foundFile = join(dir, match);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (!foundFile) {
+        return {
+            ok: false,
+            error: `No subtitle file found for language '${lang}'`,
+        };
+    }
+    // If CSV format requested, convert VTT to CSV (timestamp, text)
+    if (format === "csv") {
+        const vttContent = readFileSync(foundFile, "utf8");
+        const csvContent = vttToCsv(vttContent);
+        const csvPath = foundFile.replace(/\.vtt$/, ".csv");
+        writeFileSync(csvPath, csvContent, "utf8");
+        foundFile = csvPath;
+    }
+    const stat = statSync(foundFile);
+    if (stat.size <= 100 * 1024) {
+        const text = readFileSync(foundFile, "utf8");
+        return { ok: true, text, filePath: foundFile };
+    }
+    return { ok: true, filePath: foundFile };
+}
+export function registerSubtitleTools(server, config, tokenManager) {
+    /**
+     * Auth guard — every tool call must pass authentication.
+     * Both OAuth (JWT) and PAT modes are supported.
+     * Returns error message if not authenticated.
+     */
+    async function requireAuth() {
+        const token = await tokenManager.getValidToken();
+        if (!token)
+            return AUTH_REQUIRED_MSG;
+        return null;
+    }
+    // ── get_subtitles ──
+    server.registerTool("get_subtitles", {
+        description: "Download subtitles for a YouTube video. Accepts video ID or any YouTube URL (watch, shorts, youtu.be). Each language is fetched separately. Supports CSV output (timestamp + text columns). If languages is omitted, defaults to English + Simplified Chinese (unavailable languages are silently skipped).",
+        inputSchema: {
+            video: z.string().min(1).describe("YouTube video ID or URL"),
+            languages: z.array(z.string().min(1)).optional(),
+            format: z.enum(["vtt", "srt", "ttml", "srv3", "csv"]).optional(),
+        },
+    }, async ({ video, languages, format }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        const videoId = resolveVideoInput(video);
+        if (!videoId)
+            return toolErr("INVALID_INPUT", `无法解析视频 ID: ${video}`);
+        // Cookie pre-check: missing or expired → try headless refresh
+        if (!hasSIDCookies(PATHS.cookiesTxt) || areCookiesExpired(PATHS.cookiesTxt)) {
+            let refreshed = false;
+            try {
+                refreshed = await tryHeadlessRefresh();
+            }
+            catch { /* */ }
+            if (!refreshed || !hasSIDCookies(PATHS.cookiesTxt)) {
+                return toolErr("COOKIES_MISSING", "No valid YouTube cookies found.\nPlease run in your terminal: yt-mcp setup-cookies");
+            }
+        }
+        const usingDefaults = !languages;
+        const langs = languages ?? config.default_languages;
+        const fmt = format ?? "vtt";
+        const results = [];
+        for (let i = 0; i < langs.length; i++) {
+            if (i > 0) {
+                await randomSleep(2000, 5000);
+            }
+            const lang = langs[i];
+            const dl = await downloadSubtitle(videoId, lang, fmt);
+            if (dl.cookiesExpired) {
+                // Try headless auto-refresh
+                let refreshed = false;
+                try {
+                    refreshed = await tryHeadlessRefresh();
+                }
+                catch {
+                    // Playwright not available or browser failed — fall through
+                }
+                if (refreshed) {
+                    // Retry the download with fresh cookies
+                    const retry = await downloadSubtitle(videoId, lang, fmt);
+                    if (retry.ok) {
+                        if (retry.text) {
+                            results.push({ language: lang, status: "ok", text: retry.text, file_path: retry.filePath });
+                        }
+                        else {
+                            results.push({ language: lang, status: "ok", file_path: retry.filePath });
+                        }
+                        continue;
+                    }
+                    // Retry also failed with expired cookies — give up
+                }
+                return toolErr("COOKIES_EXPIRED", "YouTube cookies have expired and auto-refresh failed.\n" +
+                    "Please run in your terminal: yt-mcp setup-cookies");
+            }
+            if (!dl.ok) {
+                // When using default languages, silently skip unavailable ones
+                if (!usingDefaults) {
+                    results.push({
+                        language: lang,
+                        status: "failed",
+                        error: dl.error,
+                    });
+                }
+            }
+            else if (dl.text) {
+                results.push({
+                    language: lang,
+                    status: "ok",
+                    text: dl.text,
+                    file_path: dl.filePath,
+                });
+            }
+            else {
+                results.push({
+                    language: lang,
+                    status: "ok",
+                    file_path: dl.filePath,
+                });
+            }
+        }
+        return toolOk({
+            status: "completed",
+            video_id: videoId,
+            format: fmt,
+            results,
+        });
+    });
+    // ── batch_get_subtitles ──
+    server.registerTool("batch_get_subtitles", {
+        description: "Download subtitles for multiple YouTube videos. Max 10 per batch. Accepts video IDs or URLs (can mix).",
+        inputSchema: {
+            videos: z.array(z.string().min(1)).min(1).max(10).describe("Video IDs or YouTube URLs"),
+            languages: z.array(z.string().min(1)).optional(),
+            format: z.enum(["vtt", "srt", "ttml", "srv3", "csv"]).optional(),
+        },
+    }, async ({ videos, languages, format }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        const { resolvedIds, invalidInputs } = normalizeVideoInputs(videos);
+        if (resolvedIds.length === 0) {
+            return toolErr("INVALID_INPUT", `无法解析任何视频 ID。无效输入: ${invalidInputs.join(", ")}`);
+        }
+        const langs = languages ?? config.default_languages;
+        const fmt = format ?? "vtt";
+        // Cookie pre-check: missing or expired → try headless refresh
+        if (!hasSIDCookies(PATHS.cookiesTxt) || areCookiesExpired(PATHS.cookiesTxt)) {
+            let refreshed = false;
+            try {
+                refreshed = await tryHeadlessRefresh();
+            }
+            catch { /* */ }
+            if (!refreshed || !hasSIDCookies(PATHS.cookiesTxt)) {
+                return toolErr("COOKIES_MISSING", "No valid YouTube cookies found.\nPlease run in your terminal: yt-mcp setup-cookies");
+            }
+        }
+        const results = [];
+        let succeeded = 0;
+        let failed = 0;
+        for (let v = 0; v < resolvedIds.length; v++) {
+            if (v > 0) {
+                await randomSleep(config.batch_sleep_min_ms, config.batch_sleep_max_ms);
+            }
+            const videoId = resolvedIds[v];
+            const langFound = [];
+            let lastError;
+            let cookiesExpired = false;
+            for (let l = 0; l < langs.length; l++) {
+                if (l > 0) {
+                    await randomSleep(2000, 5000);
+                }
+                const dl = await downloadSubtitle(videoId, langs[l], fmt);
+                if (dl.cookiesExpired) {
+                    cookiesExpired = true;
+                    break;
+                }
+                if (dl.ok) {
+                    langFound.push(langs[l]);
+                }
+                else {
+                    lastError = dl.error;
+                }
+            }
+            if (cookiesExpired) {
+                // Try headless auto-refresh
+                let refreshed = false;
+                try {
+                    refreshed = await tryHeadlessRefresh();
+                }
+                catch { /* fall through */ }
+                if (refreshed) {
+                    // Retry this video's subtitles
+                    let retrySuccess = false;
+                    for (const lang of langs) {
+                        const retry = await downloadSubtitle(videoId, lang, fmt);
+                        if (retry.ok) {
+                            langFound.push(lang);
+                            retrySuccess = true;
+                        }
+                    }
+                    if (retrySuccess) {
+                        cookiesExpired = false;
+                    }
+                }
+                if (cookiesExpired) {
+                    return toolErr("COOKIES_EXPIRED", "YouTube cookies have expired and auto-refresh failed.\n" +
+                        "Please run in your terminal: yt-mcp setup-cookies");
+                }
+            }
+            if (langFound.length > 0) {
+                succeeded++;
+                results.push({
+                    video_id: videoId,
+                    status: "ok",
+                    languages_found: langFound,
+                    file_path: PATHS.subtitlesDir,
+                });
+            }
+            else {
+                failed++;
+                results.push({
+                    video_id: videoId,
+                    status: "failed",
+                    error: lastError ?? "No subtitles found",
+                });
+            }
+        }
+        return toolOk({
+            status: "completed",
+            total: resolvedIds.length,
+            succeeded,
+            failed,
+            invalid_inputs: invalidInputs.length > 0 ? invalidInputs : undefined,
+            results,
+        });
+    });
+    // ── list_available_subtitles ──
+    server.registerTool("list_available_subtitles", {
+        description: "List available subtitle tracks for a YouTube video. Accepts video ID or URL.",
+        inputSchema: {
+            video: z.string().min(1).describe("YouTube video ID or URL"),
+        },
+    }, async ({ video }) => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        const videoId = resolveVideoInput(video);
+        if (!videoId)
+            return toolErr("INVALID_INPUT", `无法解析视频 ID: ${video}`);
+        const result = await runYtDlp([
+            "--list-subs",
+            "--skip-download",
+            `https://www.youtube.com/watch?v=${videoId}`,
+        ]);
+        if (result.exitCode !== 0) {
+            return toolErr("YT_DLP_ERROR", result.stderr.slice(0, 500) || "Failed to list subtitles");
+        }
+        const output = result.stdout;
+        const manual = [];
+        const automatic = [];
+        let section = "none";
+        for (const line of output.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.includes("Available subtitles") ||
+                trimmed.includes("manual subtitles")) {
+                section = "manual";
+                continue;
+            }
+            if (trimmed.includes("Available automatic captions") ||
+                trimmed.includes("automatic captions")) {
+                section = "auto";
+                continue;
+            }
+            if (!trimmed || trimmed.startsWith("Language") || trimmed.startsWith("---")) {
+                continue;
+            }
+            const langCode = trimmed.split(/\s+/)[0];
+            if (!langCode)
+                continue;
+            if (section === "manual")
+                manual.push(langCode);
+            else if (section === "auto")
+                automatic.push(langCode);
+        }
+        return toolOk({
+            status: "completed",
+            video_id: videoId,
+            manual,
+            automatic,
+            translatable: automatic,
+        });
+    });
+    // ── validate_cookies ──
+    server.registerTool("validate_cookies", {
+        description: "Validate current YouTube cookies by testing a subtitle download.",
+        inputSchema: {},
+    }, async () => {
+        const authErr = await requireAuth();
+        if (authErr)
+            return toolErr("AUTH_REQUIRED", authErr);
+        if (!existsSync(PATHS.cookiesTxt)) {
+            return toolOk({
+                valid: false,
+                error: "cookies.txt not found",
+            });
+        }
+        if (!hasSIDCookies(PATHS.cookiesTxt)) {
+            return toolOk({
+                valid: false,
+                error: "cookies.txt does not contain YouTube SID cookies",
+            });
+        }
+        // Test with a known public video (Rick Astley - Never Gonna Give You Up)
+        const result = await runYtDlp([
+            "--skip-download",
+            "-f", "mhtml",
+            "--write-auto-sub",
+            "--sub-langs",
+            "en",
+            "--sub-format",
+            "vtt",
+            "--output",
+            join(PATHS.subtitlesDir, "cookie_test"),
+            "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+        ]);
+        if (result.exitCode === 0) {
+            return toolOk({ valid: true });
+        }
+        const isExpired = result.stderr.includes("Sign in") ||
+            result.stderr.includes("cookies") ||
+            result.stderr.includes("login");
+        return toolOk({
+            valid: false,
+            error: isExpired
+                ? "Cookies expired"
+                : result.stderr.slice(0, 300),
+        });
+    });
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,23 @@
+export declare const PATHS: {
+    configDir: string;
+    authJson: string;
+    cookiesTxt: string;
+    browserProfile: string;
+    launcherJs: string;
+    npmCacheDir: string;
+    subtitlesDir: string;
+    configJson: string;
+};
+export interface YtMcpConfig {
+    /** Auth gateway root URL — for OAuth, PAT, introspection (e.g., https://mkterswingman.com) */
+    auth_url: string;
+    /** v2 API URL — for data tools (e.g., https://mkterswingman.com/mcp/yt) */
+    api_url: string;
+    default_languages: string[];
+    batch_sleep_min_ms: number;
+    batch_sleep_max_ms: number;
+    batch_max_size: number;
+}
+export declare function ensureConfigDir(): void;
+export declare function loadConfig(): YtMcpConfig;
+export declare function saveConfig(config: Partial<YtMcpConfig>): void;

package/dist/utils/config.js

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CONFIG_DIR = join(homedir(), ".yt-mcp");
+const SUBTITLES_DIR = join(homedir(), "Downloads", "yt-mcp");
+export const PATHS = {
+    configDir: CONFIG_DIR,
+    authJson: join(CONFIG_DIR, "auth.json"),
+    cookiesTxt: join(CONFIG_DIR, "cookies.txt"),
+    browserProfile: join(CONFIG_DIR, "browser-profile"),
+    launcherJs: join(CONFIG_DIR, "launcher.mjs"),
+    npmCacheDir: join(CONFIG_DIR, "npm-cache"),
+    subtitlesDir: SUBTITLES_DIR,
+    configJson: join(CONFIG_DIR, "config.json"),
+};
+const DEFAULTS = {
+    auth_url: "https://mkterswingman.com",
+    api_url: "https://mkterswingman.com/mcp/yt",
+    // Fixed list, not probed: --list-subs costs ~10s extra and YouTube has no "source language" concept
+    default_languages: ["en", "zh-Hans"],
+    batch_sleep_min_ms: 3000,
+    batch_sleep_max_ms: 8000,
+    batch_max_size: 10,
+};
+export function ensureConfigDir() {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+}
+export function loadConfig() {
+    ensureConfigDir();
+    if (!existsSync(PATHS.configJson)) {
+        return { ...DEFAULTS };
+    }
+    try {
+        const raw = readFileSync(PATHS.configJson, "utf8");
+        const parsed = JSON.parse(raw);
+        return { ...DEFAULTS, ...parsed };
+    }
+    catch {
+        return { ...DEFAULTS };
+    }
+}
+export function saveConfig(config) {
+    ensureConfigDir();
+    const existing = loadConfig();
+    const merged = { ...existing, ...config };
+    writeFileSync(PATHS.configJson, JSON.stringify(merged, null, 2), "utf8");
+}

package/dist/utils/cookieRefresh.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Headless cookie auto-refresh.
+ *
+ * Uses Playwright to open YouTube in a headless browser with the existing
+ * browser-profile. If Google session is still valid, YouTube cookies are
+ * extracted and saved automatically — no user interaction needed.
+ *
+ * If Google session has expired too, returns false so the caller can
+ * prompt the user for interactive login.
+ */
+/**
+ * Attempt to refresh YouTube cookies headlessly using existing browser profile.
+ *
+ * @returns true if cookies were refreshed, false if Google session expired
+ *          (needs interactive login).
+ * @throws if Playwright is not installed or browser can't launch.
+ */
+export declare function tryHeadlessRefresh(): Promise<boolean>;