@mkterswingman/5mghost-yonder 0.0.38 → 0.0.40

package/dist/telemetry.js

@@ -0,0 +1,225 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { PATHS } from "./utils/config.js";
+const PRODUCT = "5mghost-yonder";
+const PRODUCT_VERSION = "0.0.40";
+const MAX_ERROR_CODE_CHARS = 64;
+export class ToolTelemetryClient {
+    config;
+    tokenManager;
+    fetchImpl;
+    configuredInstallId;
+    persistedInstallId;
+    logger;
+    constructor(config, tokenManager, deps = {}) {
+        this.config = config;
+        this.tokenManager = tokenManager;
+        this.fetchImpl = deps.fetchImpl ?? fetch;
+        this.configuredInstallId = deps.installId;
+        this.logger = deps.logger ?? { warn: () => { } };
+    }
+    recordToolCall(input) {
+        if (!this.config.telemetry_enabled) {
+            return;
+        }
+        const event = buildToolTelemetryEvent({
+            toolName: input.toolName,
+            startedAtMs: input.startedAtMs,
+            installId: this.getInstallId(),
+            result: input.result,
+            thrown: input.thrown,
+        });
+        setImmediate(() => {
+            void this.send(event);
+        });
+    }
+    getInstallId() {
+        if (this.configuredInstallId) {
+            return this.configuredInstallId;
+        }
+        this.persistedInstallId ??= getOrCreateInstallId();
+        return this.persistedInstallId;
+    }
+    async send(event) {
+        if (!isSameOrigin(this.config.telemetry_endpoint_url, this.config.auth_url)) {
+            this.logger.warn("yt_mcp_telemetry_same_origin_blocked", {
+                product: PRODUCT,
+                tool_name: event.tool_name,
+            });
+            return;
+        }
+        try {
+            const token = await this.tokenManager.getValidToken();
+            if (!token) {
+                return;
+            }
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.config.telemetry_timeout_ms);
+            timeout.unref?.();
+            try {
+                const response = await this.fetchImpl(this.config.telemetry_endpoint_url, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({ events: [event] }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    this.logger.warn("yt_mcp_telemetry_send_failed", {
+                        product: PRODUCT,
+                        tool_name: event.tool_name,
+                        status_code: response.status,
+                    });
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (error) {
+            this.logger.warn("yt_mcp_telemetry_send_failed", {
+                product: PRODUCT,
+                tool_name: event.tool_name,
+                code: "TELEMETRY_NETWORK_ERROR",
+                message: error instanceof Error ? error.name : "UnknownError",
+            });
+        }
+    }
+}
+export function buildToolTelemetryEvent(input) {
+    const durationMs = Math.max(0, Math.round(Date.now() - input.startedAtMs));
+    const error = classifyTelemetryError(input.result, input.thrown);
+    const base = {
+        schema_version: 1,
+        event_id: `${PRODUCT}-${Date.now()}-${randomUUID()}`,
+        occurred_at: new Date().toISOString(),
+        product: PRODUCT,
+        product_version: PRODUCT_VERSION,
+        install_id: input.installId,
+        event_type: "tool_call",
+        tool_name: input.toolName,
+        duration_ms: durationMs,
+    };
+    if (!error) {
+        return {
+            ...base,
+            outcome: "success",
+        };
+    }
+    return {
+        ...base,
+        outcome: "failure",
+        error_kind: error.kind,
+        error_code: error.code,
+        error_message: error.message,
+    };
+}
+export function classifyTelemetryError(result, thrown) {
+    if (thrown) {
+        return {
+            kind: "internal",
+            code: "INTERNAL_ERROR",
+            message: "Tool handler threw an unexpected error",
+        };
+    }
+    if (!result?.isError) {
+        return null;
+    }
+    const error = readStructuredError(result.structuredContent);
+    const code = normalizeErrorCode(error.code);
+    return {
+        kind: classifyErrorKind(code),
+        code,
+        message: safeErrorMessage(code),
+    };
+}
+function readStructuredError(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { code: null };
+    }
+    const error = value.error;
+    if (!error || typeof error !== "object" || Array.isArray(error)) {
+        return { code: null };
+    }
+    const record = error;
+    return {
+        code: typeof record.code === "string" ? record.code : null,
+    };
+}
+function normalizeErrorCode(code) {
+    if (!code) {
+        return "UNKNOWN_ERROR";
+    }
+    const normalized = code.toUpperCase().replace(/[^A-Z0-9_.:-]/g, "_").slice(0, MAX_ERROR_CODE_CHARS);
+    return normalized || "UNKNOWN_ERROR";
+}
+function classifyErrorKind(code) {
+    if (code.includes("RATE_LIMIT") || code === "HTTP_429") {
+        return "rate_limit";
+    }
+    if (code.startsWith("AUTH") || code.includes("COOKIE") || code === "SIGN_IN_REQUIRED") {
+        return "auth";
+    }
+    if (code === "INVALID_INPUT" || code.includes("VALIDATION")) {
+        return "validation";
+    }
+    if (code.startsWith("REMOTE") || code.startsWith("UPSTREAM") || code.startsWith("HTTP_") || code === "NETWORK_ERROR") {
+        return "upstream";
+    }
+    return "internal";
+}
+function safeErrorMessage(code) {
+    const kind = classifyErrorKind(code);
+    if (kind === "rate_limit") {
+        return "Rate limit was reached";
+    }
+    if (kind === "auth") {
+        return "Authorization failed";
+    }
+    if (kind === "validation") {
+        return "Invalid input";
+    }
+    if (kind === "upstream") {
+        return "Remote tool request failed";
+    }
+    if (code === "NO_SUBTITLES") {
+        return "Requested subtitles were not found";
+    }
+    return "Tool call failed";
+}
+function isSameOrigin(endpoint, authUrl) {
+    try {
+        return new URL(endpoint).origin === new URL(authUrl).origin;
+    }
+    catch {
+        return false;
+    }
+}
+function getOrCreateInstallId() {
+    const path = join(PATHS.configDir, "telemetry.json");
+    try {
+        if (existsSync(path)) {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (typeof parsed.install_id === "string" && parsed.install_id.trim()) {
+                return parsed.install_id.trim();
+            }
+        }
+    }
+    catch {
+        // Why: telemetry must never block MCP tool registration on local state corruption.
+    }
+    const installId = `local-${randomUUID()}`;
+    try {
+        mkdirSync(PATHS.configDir, { recursive: true });
+        const tempPath = `${path}.tmp`;
+        writeFileSync(tempPath, JSON.stringify({ install_id: installId }, null, 2), { encoding: "utf8", mode: 0o600 });
+        renameSync(tempPath, path);
+    }
+    catch {
+        // Why: a read-only home directory should disable persistence, not MCP tools.
+    }
+    return installId;
+}

package/dist/tools/remote.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { YOUTUBE_TOOL_CONTRACTS } from "../contracts/youtubeToolContracts.js";
 function toolErr(code, message) {
     const payload = { status: "failed", error: { code, message } };
     return {
@@ -69,9 +70,8 @@ function createRemoteTool(server, def, tokenManager, apiUrl) {
         }
     });
 }
-const REMOTE_TOOLS = [
-    {
-        name: "search_videos",
+const REMOTE_TOOL_META = {
+    search_videos: {
         description: "Search YouTube videos by keyword. Supports up to 300 results.",
         schema: {
             query: z.string().min(1),
@@ -87,42 +87,32 @@ const REMOTE_TOOLS = [
             ])
                 .optional(),
         },
-        remotePath: "api/search",
     },
-    {
-        name: "get_video_stats",
+    get_video_stats: {
         description: "Get YouTube video stats in one request. Accepts up to 1000 video IDs/URLs.",
         schema: {
             videos: z.array(z.string().min(1)).min(1).max(1000),
         },
-        remotePath: "api/video-stats/bulk",
     },
-    {
-        name: "start_video_stats_job",
+    start_video_stats_job: {
         description: "Start an async YouTube video stats job. Accepts up to 1000 items.",
         schema: {
             videos: z.array(z.string().min(1)).min(1).max(1000),
         },
-        remotePath: "api/video-stats/job/start",
     },
-    {
-        name: "poll_video_stats_job",
+    poll_video_stats_job: {
         description: "Poll job progress and get partial/final results for a job_id.",
         schema: {
             job_id: z.string().min(1),
         },
-        remotePath: "api/video-stats/job/poll",
     },
-    {
-        name: "resume_video_stats_job",
+    resume_video_stats_job: {
         description: "Resume a previously partial job with a resume_token.",
         schema: {
             resume_token: z.string().min(1),
         },
-        remotePath: "api/video-stats/job/resume",
     },
-    {
-        name: "get_trending",
+    get_trending: {
         description: "Get official YouTube mostPopular videos. Supports region/category filters.",
         schema: {
             region_code: z
@@ -132,38 +122,30 @@ const REMOTE_TOOLS = [
             category_id: z.string().min(1).max(64).optional(),
             max_results: z.number().int().min(1).max(300).optional(),
         },
-        remotePath: "api/trending",
     },
-    {
-        name: "search_channels",
+    search_channels: {
         description: "Search YouTube channels by keyword for candidate discovery.",
         schema: {
             query: z.string().min(1).max(200),
             max_results: z.number().int().min(1).max(50).optional(),
         },
-        remotePath: "api/channel/search",
     },
-    {
-        name: "get_channel_stats",
+    get_channel_stats: {
         description: "Get YouTube channel statistics for up to 50 channel inputs.",
         schema: {
             channels: z.array(z.string().min(1)).min(1).max(50).optional(),
             channel_ids: z.array(z.string().min(1)).min(1).max(50).optional(),
         },
-        remotePath: "api/channel/stats",
     },
-    {
-        name: "list_channel_uploads",
+    list_channel_uploads: {
         description: "List videos uploaded by a YouTube channel. Supports up to 1000 results.",
         schema: {
             channel: z.string().min(1).optional(),
             channel_id: z.string().min(1).optional(),
             max_results: z.number().int().min(1).max(1000).optional(),
         },
-        remotePath: "api/channel/uploads",
     },
-    {
-        name: "get_comments",
+    get_comments: {
         description: "Get comments for one YouTube video. max_comments up to 1000.",
         schema: {
             video: z.string().min(1),
@@ -173,46 +155,36 @@ const REMOTE_TOOLS = [
             replies_preview_per_comment: z.number().int().min(1).max(5).optional(),
             replies_preview_parent_limit: z.number().int().min(1).max(25).optional(),
         },
-        remotePath: "api/comments/sync",
     },
-    {
-        name: "start_comments_job",
+    start_comments_job: {
         description: "Start a comments export job for one YouTube video.",
         schema: {
             video: z.string().min(1),
             max_comments: z.number().int().min(1).max(1000).optional(),
             order: z.enum(["time", "relevance"]).optional(),
         },
-        remotePath: "api/comments/start",
     },
-    {
-        name: "poll_comments_job",
+    poll_comments_job: {
         description: "Check comments export job progress by job_id.",
         schema: {
             job_id: z.string().min(1),
         },
-        remotePath: "api/comments/poll",
     },
-    {
-        name: "resume_comments_job",
+    resume_comments_job: {
         description: "Resume an unfinished comments export job.",
         schema: {
             resume_token: z.string().min(1),
         },
-        remotePath: "api/comments/resume",
     },
-    {
-        name: "get_comment_replies",
+    get_comment_replies: {
         description: "Get 2nd-level replies for one top-level comment.",
         schema: {
             parent_comment_id: z.string().min(1),
             max_results: z.number().int().min(1).max(1000).optional(),
             page_token: z.string().min(1).optional(),
         },
-        remotePath: "api/comments/replies",
     },
-    {
-        name: "get_quota_usage",
+    get_quota_usage: {
         description: "Get YouTube API quota usage for today or a specific date.",
         schema: {
             date: z
@@ -220,18 +192,27 @@ const REMOTE_TOOLS = [
                 .regex(/^\d{4}-\d{2}-\d{2}$/)
                 .optional(),
         },
-        remotePath: "api/quota",
     },
-    {
-        name: "get_patch_notes",
+    get_patch_notes: {
         description: "Read server patch notes for latest MCP/API updates.",
         schema: {
             max_chars: z.number().int().min(500).max(50_000).optional(),
         },
-        remotePath: "api/patch-notes",
-        method: "GET",
     },
-];
+};
+const REMOTE_TOOLS = YOUTUBE_TOOL_CONTRACTS.map((contract) => {
+    const meta = REMOTE_TOOL_META[contract.id];
+    if (!meta) {
+        throw new Error(`Missing remote tool metadata for contract id: ${contract.id}`);
+    }
+    return {
+        name: contract.remote_tool_name,
+        description: meta.description,
+        schema: meta.schema,
+        remotePath: contract.http_path.replace(/^\//, ""),
+        method: contract.http_method,
+    };
+});
 export function registerRemoteTools(server, config, tokenManager) {
     for (const def of REMOTE_TOOLS) {
         createRemoteTool(server, def, tokenManager, config.api_url);

package/dist/tools/subtitles/cookieSession.d.ts

@@ -0,0 +1,22 @@
+export declare const COOKIE_MISSING_MESSAGE = "No valid YouTube cookies found.\nPlease run in your terminal: yt-mcp setup-cookies";
+export declare const COOKIE_EXPIRED_MESSAGE = "YouTube cookies have expired and auto-refresh failed.\nPlease run in your terminal: yt-mcp setup-cookies";
+export declare const COOKIE_INVALID_MESSAGE = "YouTube rejected the current cookies and auto-refresh failed.\nPlease run in your terminal: yt-mcp setup-cookies";
+export declare const SIGN_IN_REQUIRED_MESSAGE = "YouTube requested an additional sign-in confirmation and auto-refresh failed.\nPlease run in your terminal: yt-mcp setup-cookies";
+export declare const RATE_LIMITED_MESSAGE = "The current YouTube session has been rate-limited. Wait and retry later.";
+export declare const COOKIE_JOB_MESSAGE = "YouTube cookies are missing, expired, or invalid.\nPlease run in your terminal: yt-mcp setup-cookies";
+export type CookieFailureCode = "COOKIES_INVALID" | "COOKIES_EXPIRED" | "SIGN_IN_REQUIRED" | "RATE_LIMITED";
+export declare function tryRefreshSubtitleCookies(): Promise<boolean>;
+export declare function isCookieFailureText(error?: string): boolean;
+export declare function classifyYtDlpCookieFailure(stderr: string): {
+    code: CookieFailureCode;
+    message: string;
+} | null;
+export declare function toReadableSubtitleJobError(error: unknown): string;
+export declare function ensureSubtitleCookiesReady(): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    code: "COOKIES_MISSING" | "COOKIES_EXPIRED";
+    toolMessage: string;
+    jobMessage: string;
+}>;

package/dist/tools/subtitles/cookieSession.js

@@ -0,0 +1,66 @@
+import { PATHS } from "../../utils/config.js";
+import { hasSIDCookies, areCookiesExpired } from "../../utils/cookies.js";
+import { tryHeadlessRefresh } from "../../utils/cookieRefresh.js";
+import { appendDiagnosticLog, classifyYtDlpFailure } from "../../utils/ytdlpFailures.js";
+const COOKIE_SETUP_COMMAND = "yt-mcp setup-cookies";
+export const COOKIE_MISSING_MESSAGE = `No valid YouTube cookies found.\nPlease run in your terminal: ${COOKIE_SETUP_COMMAND}`;
+export const COOKIE_EXPIRED_MESSAGE = `YouTube cookies have expired and auto-refresh failed.\nPlease run in your terminal: ${COOKIE_SETUP_COMMAND}`;
+export const COOKIE_INVALID_MESSAGE = `YouTube rejected the current cookies and auto-refresh failed.\nPlease run in your terminal: ${COOKIE_SETUP_COMMAND}`;
+export const SIGN_IN_REQUIRED_MESSAGE = `YouTube requested an additional sign-in confirmation and auto-refresh failed.\nPlease run in your terminal: ${COOKIE_SETUP_COMMAND}`;
+export const RATE_LIMITED_MESSAGE = "The current YouTube session has been rate-limited. Wait and retry later.";
+export const COOKIE_JOB_MESSAGE = `YouTube cookies are missing, expired, or invalid.\nPlease run in your terminal: ${COOKIE_SETUP_COMMAND}`;
+export async function tryRefreshSubtitleCookies() {
+    try {
+        return await tryHeadlessRefresh();
+    }
+    catch {
+        return false;
+    }
+}
+export function isCookieFailureText(error) {
+    if (!error) {
+        return false;
+    }
+    const normalized = error.toLowerCase();
+    return (normalized.includes("cookies_expired") ||
+        normalized.includes("cookie") ||
+        normalized.includes("sign in") ||
+        normalized.includes("login") ||
+        normalized.includes("not a bot"));
+}
+export function classifyYtDlpCookieFailure(stderr) {
+    const kind = classifyYtDlpFailure(stderr);
+    switch (kind) {
+        case "COOKIES_EXPIRED":
+            return { code: kind, message: COOKIE_EXPIRED_MESSAGE };
+        case "COOKIES_INVALID":
+            return { code: kind, message: COOKIE_INVALID_MESSAGE };
+        case "SIGN_IN_REQUIRED":
+            return { code: kind, message: SIGN_IN_REQUIRED_MESSAGE };
+        case "RATE_LIMITED":
+            return { code: kind, message: RATE_LIMITED_MESSAGE };
+        default:
+            return null;
+    }
+}
+export function toReadableSubtitleJobError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return isCookieFailureText(message) ? COOKIE_JOB_MESSAGE : message;
+}
+export async function ensureSubtitleCookiesReady() {
+    const hasSession = hasSIDCookies(PATHS.cookiesTxt);
+    const expired = areCookiesExpired(PATHS.cookiesTxt);
+    if (hasSession && !expired) {
+        return { ok: true };
+    }
+    const refreshed = await tryRefreshSubtitleCookies();
+    if (refreshed && hasSIDCookies(PATHS.cookiesTxt) && !areCookiesExpired(PATHS.cookiesTxt)) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        code: hasSession && expired ? "COOKIES_EXPIRED" : "COOKIES_MISSING",
+        toolMessage: hasSession && expired ? COOKIE_EXPIRED_MESSAGE : COOKIE_MISSING_MESSAGE,
+        jobMessage: appendDiagnosticLog(COOKIE_JOB_MESSAGE, undefined),
+    };
+}

package/dist/tools/subtitles/download.d.ts

@@ -0,0 +1,24 @@
+import { COOKIE_EXPIRED_MESSAGE, COOKIE_INVALID_MESSAGE, RATE_LIMITED_MESSAGE, SIGN_IN_REQUIRED_MESSAGE, type CookieFailureCode } from "./cookieSession.js";
+export declare function downloadSubtitle(videoId: string, lang: string, format: string, options?: {
+    sourceUrl?: string;
+    outputDir?: string;
+    outputStem?: string;
+    targetFile?: string;
+}): Promise<{
+    ok: boolean;
+    filePath?: string;
+    text?: string;
+    error?: string;
+    cookieFailureCode?: CookieFailureCode;
+    diagnosticLogPath?: string;
+}>;
+export declare function downloadSubtitlesForLanguages(input: {
+    videoId: string;
+    sourceUrl?: string;
+    languages: string[];
+    formats: string[];
+    subtitlesDir: string;
+    skipMissingLanguages?: boolean;
+    onProgress?: (completed: number, total: number) => void;
+}): Promise<Record<string, string[]>>;
+export { COOKIE_EXPIRED_MESSAGE, COOKIE_INVALID_MESSAGE, SIGN_IN_REQUIRED_MESSAGE, RATE_LIMITED_MESSAGE };