yt-liked 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# yt-liked
+
+`yt-liked` gives you the `ytl` command: an archive-first CLI for your YouTube liked videos.
+
+It gives you a local workflow that already works today:
+
+- import an existing likes export
+- repair collapsed uploader metadata
+- classify it with Gemini, Claude, or Codex
+- search it with local FTS
+- inspect it in the terminal
+- keep everything on your machine
+
+It also includes an exploratory browser-session probe for future native sync work, but that part is intentionally not marketed as solved yet.
+
+## What Works Today
+
+- Local-first JSONL + SQLite archive under `~/.yt-liked`
+- Uploader metadata repair via YouTube oEmbed
+- Interactive classify setup with a YouTube-themed engine picker
+- Gemini API-key classification with resumable batching and concurrency
+- Claude CLI and Codex CLI classification support
+- Archive search, list, show, viz, status, and path commands
+- Browser-session feasibility probe for YouTube Likes
+
+## What Is Experimental
+
+- `ytl sync` is still a research/probe command
+- uploader/channel metadata may need the built-in enrichment pass depending on your source archive
+- the main supported path today is `import -> enrich-channels -> classify -> search/list/show/viz`
+
+## Principles
+
+- Local-first
+- No telemetry
+- No hosted sync service
+- No hosted classification service
+- Gemini uses your own `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+- Claude and Codex reuse your existing local CLI login
+- Saved local config lives in `~/.yt-liked/.env.local`
+
+## Install
+
+`ytl` currently targets macOS first, especially for the exploratory Chrome-session sync probe.
+
+Alpha install:
+
+```bash
+npm install -g yt-liked@alpha
+```
+
+One-off use:
+
+```bash
+npx yt-liked@alpha status
+```
+
+Local development:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+Then use the `ytl` command normally.
+
+## Quick Start
+
+Import an existing archive:
+
+```bash
+ytl import /Users/4xiom/code/projects/youtube-liked-organizer/data/liked_videos.json
+```
+
+Classify it:
+
+```bash
+ytl enrich-channels
+ytl classify
+```
+
+Search it:
+
+```bash
+ytl search "sqlite"
+```
+
+Inspect it:
+
+```bash
+ytl list --limit 5
+ytl show <stored-id-or-video-id-or-url>
+ytl viz
+ytl status
+```
+
+## Classification Engines
+
+`ytl classify` and `ytl classify-domains` support three engines:
+
+- `gemini`
+- `claude`
+- `codex`
+
+If you omit `--engine` in an interactive terminal, `ytl` opens an engine picker.
+
+### Gemini
+
+Gemini is the default guided path.
+
+- Model default: `models/gemini-3.1-flash-lite-preview`
+- Default concurrency: `10`
+- Default batch size: `50`
+
+If no Gemini key is configured, `ytl` opens a hidden paste-to-save prompt and writes the key to:
+
+```bash
+~/.yt-liked/.env.local
+```
+
+If you launch `ytl classify` interactively without custom flags, `ytl` also offers these launch profiles:
+
+- `Rocket`: preview Flash Lite, batch `50`, workers `10`
+- `Balanced`: preview Flash Lite, batch `50`, workers `6`
+- `Careful`: preview Flash Lite, batch `25`, workers `3`
+
+### Claude and Codex
+
+Claude and Codex follow the same local-CLI model as Field Theory:
+
+- `claude` uses your existing Claude CLI login
+- `codex` uses your existing Codex CLI login
+- both run single-worker classification for stability
+
+Examples:
+
+```bash
+ytl classify --engine gemini
+ytl classify --engine claude
+ytl classify-domains --engine codex
+```
+
+## Commands
+
+### Archive
+
+```bash
+ytl import <path>
+ytl enrich-channels [--limit <n>] [--concurrency <n>] [--force]
+ytl search <query> [--channel <name>] [--category <slug>] [--domain <slug>] [--limit <n>] [--json]
+ytl list [--query <q>] [--channel <name>] [--category <slug>] [--domain <slug>] [--privacy <value>] [--after <date>] [--before <date>] [--limit <n>] [--offset <n>] [--json]
+ytl show <stored-id-or-video-id-or-url> [--json]
+ytl viz
+ytl stats
+ytl status
+ytl path
+```
+
+### Classification
+
+```bash
+ytl classify [--engine <gemini|claude|codex>] [--model <name>] [--batch-size <n>] [--concurrency <n>] [--limit <n>]
+ytl classify-domains [--all] [--engine <gemini|claude|codex>] [--model <name>] [--batch-size <n>] [--concurrency <n>] [--limit <n>]
+```
+
+### Experimental Sync Probe
+
+```bash
+ytl sync [--max-pages <n>] [--delay-ms <ms>] [--max-minutes <n>] [--chrome-user-data-dir <path>] [--chrome-profile-directory <name>]
+```
+
+This command is deliberately framed as exploratory. It tests whether the logged-in YouTube web client can expose more history than the current archive ceiling on your machine.
+
+## Local Files
+
+- `~/.yt-liked/videos.jsonl`
+- `~/.yt-liked/videos.db`
+- `~/.yt-liked/videos-meta.json`
+- `~/.yt-liked/videos-backfill-state.json`
+- `~/.yt-liked/.env.local`
+
+## Development
+
+Build and test:
+
+```bash
+npm run build
+npm test
+```
+
+Create a publish tarball locally:
+
+```bash
+npm pack
+```
+
+## Current Limitations
+
+- Native YouTube Likes sync is not production-ready yet
+- The remaining unresolved uploader bucket is now mostly private/deleted videos and is no longer attributed to your profile in `ytl viz`
+- Some imported archives collapse uploader metadata to the playlist owner, so `ytl enrich-channels` is the recommended repair step after import
+- `ytl` is strongest today as a personal archive workflow, not as a full YouTube data replacement

package/bin/ytl.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli.js').then(({ run }) => run(process.argv));

package/dist/channel-enrich.js

@@ -0,0 +1,209 @@
+import { buildIndex } from './videos-db.js';
+import { readVideoArchive, writeJsonLines } from './jsonl.js';
+import { videosJsonlPath } from './paths.js';
+function normalizeString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function signatureKey(record) {
+    return `${record.channel_title ?? ''}||${record.channel_id ?? ''}`;
+}
+function detectDominantFallback(records) {
+    if (records.length === 0) {
+        return { title: null, id: null };
+    }
+    const counts = new Map();
+    for (const record of records) {
+        const key = signatureKey(record);
+        const entry = counts.get(key);
+        if (entry) {
+            entry.count += 1;
+        }
+        else {
+            counts.set(key, {
+                count: 1,
+                title: record.channel_title ?? null,
+                id: record.channel_id ?? null,
+            });
+        }
+    }
+    const dominant = Array.from(counts.values()).sort((a, b) => b.count - a.count)[0];
+    if (!dominant) {
+        return { title: null, id: null };
+    }
+    const title = normalizeString(dominant.title);
+    const suspiciousShare = dominant.count / Math.max(records.length, 1);
+    const shortTitle = !title || title.length <= 2;
+    if (suspiciousShare < 0.4 && !shortTitle) {
+        return { title: null, id: null };
+    }
+    return {
+        title,
+        id: normalizeString(dominant.id),
+    };
+}
+function parseChannelKey(authorUrl) {
+    if (!authorUrl)
+        return null;
+    try {
+        const url = new URL(authorUrl);
+        const parts = url.pathname.split('/').filter(Boolean);
+        if (parts.length === 0)
+            return authorUrl;
+        if (parts[0]?.startsWith('@'))
+            return parts[0];
+        if ((parts[0] === 'channel' || parts[0] === 'user' || parts[0] === 'c') && parts[1]) {
+            return parts[1];
+        }
+        return parts.join('/');
+    }
+    catch {
+        return authorUrl;
+    }
+}
+function shouldEnrich(record, fallback, force) {
+    if (!record.video_id && !record.url)
+        return false;
+    if (force)
+        return true;
+    const title = normalizeString(record.channel_title);
+    const id = normalizeString(record.channel_id);
+    if (!title)
+        return true;
+    if (title.length <= 2)
+        return true;
+    if (fallback.title && title === fallback.title) {
+        if (!fallback.id)
+            return true;
+        return id === fallback.id;
+    }
+    return false;
+}
+async function fetchOEmbed(url) {
+    const endpoint = `https://www.youtube.com/oembed?url=${encodeURIComponent(url)}&format=json`;
+    const response = await fetch(endpoint, {
+        headers: {
+            accept: 'application/json',
+            'user-agent': 'ytl/0.2.0 (+https://github.com/afar1/fieldtheory-cli-inspired)',
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`oEmbed request failed (${response.status})`);
+    }
+    return await response.json();
+}
+function extractWatchPageOwner(html) {
+    const ownerName = html.match(/"ownerChannelName":"([^"]+)"/)?.[1] ?? null;
+    const canonicalBaseUrl = html.match(/"canonicalBaseUrl":"([^"]+)"/)?.[1] ?? null;
+    const ownerProfileUrl = html.match(/"ownerProfileUrl":"([^"]+)"/)?.[1] ?? null;
+    const channelId = html.match(/"channelId":"([^"]+)"/)?.[1] ?? null;
+    const channelTitle = normalizeString(ownerName)
+        ?? normalizeString(canonicalBaseUrl?.split('/').filter(Boolean).at(-1)?.replace(/^@/, ''))
+        ?? normalizeString(ownerProfileUrl?.split('/').filter(Boolean).at(-1)?.replace(/^@/, ''));
+    const channelKey = parseChannelKey(normalizeString(ownerProfileUrl))
+        ?? parseChannelKey(normalizeString(canonicalBaseUrl))
+        ?? normalizeString(channelId);
+    return {
+        channelTitle,
+        channelKey,
+    };
+}
+async function fetchWatchPageOwner(url) {
+    const response = await fetch(url, {
+        headers: {
+            accept: 'text/html,application/xhtml+xml',
+            'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36',
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`watch page request failed (${response.status})`);
+    }
+    const html = await response.text();
+    return extractWatchPageOwner(html);
+}
+async function runConcurrent(items, concurrency, worker) {
+    let nextIndex = 0;
+    async function consume() {
+        while (true) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= items.length) {
+                return;
+            }
+            await worker(items[index], index);
+        }
+    }
+    const workers = Array.from({ length: Math.max(1, concurrency) }, () => consume());
+    await Promise.all(workers);
+}
+export async function enrichChannels(options = {}) {
+    const records = await readVideoArchive();
+    const fallback = detectDominantFallback(records);
+    const candidates = records
+        .filter((record) => shouldEnrich(record, fallback, Boolean(options.force)))
+        .slice(0, options.limit ?? Number.MAX_SAFE_INTEGER);
+    let completed = 0;
+    let updated = 0;
+    let failed = 0;
+    let skipped = 0;
+    await runConcurrent(candidates, options.concurrency ?? 8, async (record) => {
+        try {
+            let nextTitle = null;
+            let nextId = null;
+            try {
+                const payload = await fetchOEmbed(record.url);
+                nextTitle = normalizeString(payload.author_name);
+                nextId = parseChannelKey(normalizeString(payload.author_url));
+            }
+            catch {
+                // Some public videos disable or break oEmbed; fall back to the watch page.
+            }
+            if (!nextTitle) {
+                const watchPage = await fetchWatchPageOwner(record.url);
+                nextTitle = watchPage.channelTitle;
+                nextId = nextId ?? watchPage.channelKey;
+            }
+            if (!nextTitle) {
+                skipped += 1;
+            }
+            else {
+                let changed = false;
+                if (record.channel_title !== nextTitle) {
+                    record.channel_title = nextTitle;
+                    changed = true;
+                }
+                if (nextId && record.channel_id !== nextId) {
+                    record.channel_id = nextId;
+                    changed = true;
+                }
+                if (changed) {
+                    updated += 1;
+                }
+                else {
+                    skipped += 1;
+                }
+            }
+        }
+        catch {
+            failed += 1;
+        }
+        finally {
+            completed += 1;
+            options.onProgress?.(completed, candidates.length);
+        }
+    });
+    if (updated > 0) {
+        writeJsonLines(videosJsonlPath(), records);
+        await buildIndex({ force: true });
+    }
+    return {
+        attempted: candidates.length,
+        updated,
+        failed,
+        skipped,
+        dominantFallbackTitle: fallback.title,
+        dominantFallbackId: fallback.id,
+    };
+}

package/dist/chrome-cookies.js

@@ -0,0 +1,130 @@
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, existsSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createDecipheriv, pbkdf2Sync, randomUUID } from 'node:crypto';
+function getMacOSChromeKey() {
+    const candidates = [
+        { service: 'Chrome Safe Storage', account: 'Chrome' },
+        { service: 'Chrome Safe Storage', account: 'Google Chrome' },
+        { service: 'Google Chrome Safe Storage', account: 'Chrome' },
+        { service: 'Google Chrome Safe Storage', account: 'Google Chrome' },
+    ];
+    for (const candidate of candidates) {
+        try {
+            const password = execFileSync('security', ['find-generic-password', '-w', '-s', candidate.service, '-a', candidate.account], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            if (password) {
+                return pbkdf2Sync(password, 'saltysalt', 1003, 16, 'sha1');
+            }
+        }
+        catch {
+            // Try the next naming pair.
+        }
+    }
+    throw new Error('Could not read Chrome Safe Storage from the macOS Keychain.\n' +
+        'Open Google Chrome once, confirm it is installed normally, and try again.');
+}
+function decryptCookieValue(encryptedValue, key, dbVersion) {
+    if (encryptedValue.length === 0)
+        return '';
+    if (encryptedValue[0] === 0x76 && encryptedValue[1] === 0x31 && encryptedValue[2] === 0x30) {
+        const iv = Buffer.alloc(16, 0x20);
+        const ciphertext = encryptedValue.subarray(3);
+        const decipher = createDecipheriv('aes-128-cbc', key, iv);
+        let decrypted = decipher.update(ciphertext);
+        decrypted = Buffer.concat([decrypted, decipher.final()]);
+        if (dbVersion >= 24 && decrypted.length > 32) {
+            decrypted = decrypted.subarray(32);
+        }
+        return decrypted.toString('utf8');
+    }
+    return encryptedValue.toString('utf8');
+}
+function runSqliteQuery(dbPath, sql) {
+    return execFileSync('sqlite3', ['-json', dbPath, sql], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10000,
+    }).trim();
+}
+function withReadableDb(dbPath, fn) {
+    try {
+        return fn(dbPath);
+    }
+    catch {
+        const tmpDb = join(tmpdir(), `ytl-cookies-${randomUUID()}.db`);
+        try {
+            copyFileSync(dbPath, tmpDb);
+            return fn(tmpDb);
+        }
+        finally {
+            try {
+                unlinkSync(tmpDb);
+            }
+            catch {
+                // Ignore cleanup failures.
+            }
+        }
+    }
+}
+function queryDbVersion(dbPath) {
+    return withReadableDb(dbPath, (readablePath) => {
+        const value = execFileSync('sqlite3', [readablePath, "SELECT value FROM meta WHERE key='version';"], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).trim();
+        return Number.parseInt(value, 10) || 0;
+    });
+}
+function queryYoutubeCookies(dbPath) {
+    if (!existsSync(dbPath)) {
+        throw new Error(`Chrome Cookies database not found at ${dbPath}`);
+    }
+    const sql = `
+    SELECT
+      name,
+      host_key,
+      value,
+      hex(encrypted_value) AS encrypted_value_hex
+    FROM cookies
+    WHERE host_key LIKE '%youtube.com'
+    ORDER BY host_key DESC, name ASC;
+  `;
+    const raw = withReadableDb(dbPath, (readablePath) => runSqliteQuery(readablePath, sql));
+    if (!raw || raw === '[]')
+        return [];
+    return JSON.parse(raw);
+}
+function sanitizeCookieValue(name, value) {
+    const cleaned = value.replace(/\0+$/g, '').trim();
+    if (!cleaned) {
+        throw new Error(`Cookie ${name} was empty after decryption.`);
+    }
+    return cleaned;
+}
+export function extractChromeYoutubeCookies(chromeUserDataDir, profileDirectory = 'Default') {
+    const dbPath = join(chromeUserDataDir, profileDirectory, 'Cookies');
+    const key = getMacOSChromeKey();
+    const dbVersion = queryDbVersion(dbPath);
+    const rawCookies = queryYoutubeCookies(dbPath);
+    const cookies = new Map();
+    for (const cookie of rawCookies) {
+        const hexValue = cookie.encrypted_value_hex;
+        const value = hexValue
+            ? decryptCookieValue(Buffer.from(hexValue, 'hex'), key, dbVersion)
+            : cookie.value;
+        if (!value)
+            continue;
+        cookies.set(cookie.name, sanitizeCookieValue(cookie.name, value));
+    }
+    const sapisid = cookies.get('SAPISID') ?? cookies.get('__Secure-1PAPISID') ?? cookies.get('__Secure-3PAPISID');
+    if (!sapisid) {
+        throw new Error('No authenticated YouTube SAPISID cookie was found in Chrome.\n' +
+            'Open Google Chrome, make sure you are logged into YouTube, and try again.');
+    }
+    const cookieHeader = Array.from(cookies.entries())
+        .map(([name, value]) => `${name}=${value}`)
+        .join('; ');
+    return { cookies, cookieHeader, sapisid };
+}