yt-liked 0.2.0-alpha.0

package/dist/cli.js

@@ -0,0 +1,625 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { backfillStatePath, dataDir, defaultChromeUserDataDir, ensureDataDir, videosDbPath, videosJsonlPath, videosMetaPath, } from './paths.js';
+import { extractChromeYoutubeCookies } from './chrome-cookies.js';
+import { classifyCategories, classifyDomains, GEMINI_DEFAULT_MODEL } from './gemini-classify.js';
+import { resolveClassifySetup } from './classify-setup.js';
+import { geminiEnvLocalPath, loadEnv } from './config.js';
+import { importVideoArchive } from './videos-import.js';
+import { getVideoByLookupKey, getVideoStatusView, getVideoVizView, listVideos, requireVideoData, searchVideos } from './videos-db.js';
+import { probeLikesHistory } from './youtube-web.js';
+import { readProbeReport, saveProbeReport } from './report.js';
+import { renderVideoViz } from './videos-viz.js';
+import { enrichChannels } from './channel-enrich.js';
+const R = '\x1b[38;5;196m';
+const R2 = '\x1b[38;5;203m';
+const W = '\x1b[97m';
+const D = '\x1b[2m';
+const X = '\x1b[0m';
+const LOGO = `
+   ${R}┌──────────────────────────────┐${X}
+   ${R}│${X}  ${W}Y T${X}  ${R2}L i k e d${X}            ${R}│${X}
+   ${R}│${X}  ${D}youtube-first archive CLI${X} ${R}│${X}
+   ${R}└──────────────────────────────┘${X}`;
+function stringifyDate(value) {
+    return value?.slice(0, 10) ?? '?';
+}
+function showIntro() {
+    console.log(`
+  Import, search, classify, and inspect a YouTube likes archive with
+  Gemini, Claude, or Codex, while keeping the browser-session probe
+  around for future native sync work.
+  Your data stays on your machine.
+`);
+}
+function showClassifyPlan(plan) {
+    console.log(`
+  Launch plan:
+    Engine: ${plan.engine}
+    Profile: ${plan.profileLabel}
+    Model: ${plan.model ?? 'managed by local CLI'}
+    Batch size: ${plan.batchSize}
+    Workers: ${plan.concurrency}
+
+  Resume-safe:
+    Re-run the same command any time to continue filling missing labels.
+`);
+}
+function safe(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (error) {
+            console.error(`\n  Error: ${error.message}\n`);
+            process.exitCode = 1;
+        }
+    };
+}
+function showPaths() {
+    ensureDataDir();
+    console.log(`
+  Data directory:
+    ${dataDir()}
+
+  Local files:
+    ${videosJsonlPath()}
+    ${videosDbPath()}
+    ${videosMetaPath()}
+    ${backfillStatePath()}
+    ${geminiEnvLocalPath()}
+`);
+}
+function renderRecordSummary(record) {
+    const tags = [record.primary_category, record.primary_domain].filter(Boolean).join(' · ');
+    const summary = record.description && record.description.length > 140
+        ? `${record.description.slice(0, 137)}...`
+        : record.description;
+    console.log(`${record.id}  ${record.channel_title ?? 'Unknown channel'}  ${stringifyDate(record.liked_at)}${tags ? `  ${tags}` : ''}`);
+    console.log(`  ${record.title}`);
+    if (summary)
+        console.log(`  ${summary}`);
+    console.log(`  ${record.url}`);
+    console.log();
+}
+function formatPct(count, total) {
+    if (total <= 0)
+        return '0.0%';
+    return `${((count / total) * 100).toFixed(1)}%`;
+}
+function renderCountRows(rows, total, indent = '  ') {
+    if (rows.length === 0) {
+        console.log(`${indent}none yet`);
+        return;
+    }
+    const labelWidth = Math.max(...rows.map((row) => row.label.length), 4);
+    const countWidth = Math.max(...rows.map((row) => row.count.toLocaleString().length), 1);
+    for (const row of rows) {
+        console.log(`${indent}${row.label.padEnd(labelWidth)}  ${row.count.toLocaleString().padStart(countWidth)}  (${formatPct(row.count, total)})`);
+    }
+}
+async function requireImportedData() {
+    const hasData = await requireVideoData();
+    if (!hasData) {
+        console.log(`
+  No local video archive imported yet.
+
+  Run:
+    ytl import /path/to/liked_videos.json
+`);
+        process.exitCode = 1;
+        return false;
+    }
+    return true;
+}
+async function showStatus() {
+    const view = await getVideoStatusView();
+    const report = readProbeReport();
+    const geminiConfigured = Boolean(process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY);
+    console.log(LOGO);
+    showIntro();
+    console.log(`
+  Imported videos: ${view.importedCount.toLocaleString()}
+  Categorized: ${view.categorizedCount.toLocaleString()}
+  Domain-tagged: ${view.domainCount.toLocaleString()}
+  Last classification engine: ${view.lastClassificationEngine ?? 'never'}
+  Last classification model: ${view.lastClassificationModel ?? 'n/a'}
+  Gemini key: ${geminiConfigured ? 'configured' : 'not configured'}
+`);
+    if (report) {
+        console.log(`
+  Last probe: ${report.generatedAt}
+  Probe discovered via web continuation: ${report.discoveredCount.toLocaleString()}
+  Existing comparison ceiling: ${report.baselineCeiling.toLocaleString()}
+  Probe stop reason: ${report.stopReason}
+  Probe passed feasibility gate: ${report.browserMethodBeatCeiling ? 'yes' : 'no'}
+`);
+        if (report.statedVideoCount != null) {
+            console.log(`  YouTube page header count: ${report.statedVideoCount.toLocaleString()}`);
+        }
+        if (report.alertMessages?.length) {
+            console.log(`  Alerts: ${report.alertMessages.join(' | ')}`);
+        }
+    }
+    console.log(`
+  Saved files:
+    ${videosJsonlPath()}
+    ${videosDbPath()}
+    ${videosMetaPath()}
+    ${backfillStatePath()}
+    ${geminiEnvLocalPath()}
+`);
+}
+async function showViz() {
+    if (!await requireImportedData())
+        return;
+    const view = await getVideoVizView();
+    console.log(renderVideoViz(view));
+}
+async function runSearchCommand(query, options) {
+    if (!await requireImportedData())
+        return;
+    const results = await searchVideos({
+        query,
+        channel: options.channel,
+        category: options.category,
+        domain: options.domain,
+        limit: options.limit,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log('\n  No matching videos found.\n');
+        return;
+    }
+    for (const result of results) {
+        renderRecordSummary({
+            id: result.id,
+            title: result.title,
+            channel_title: result.channelTitle,
+            liked_at: result.likedAt,
+            primary_category: result.primaryCategory,
+            primary_domain: result.primaryDomain,
+            url: result.url,
+            description: result.description,
+        });
+    }
+}
+async function runListCommand(options) {
+    if (!await requireImportedData())
+        return;
+    const items = await listVideos({
+        query: options.query,
+        channel: options.channel,
+        category: options.category,
+        domain: options.domain,
+        privacy: options.privacy,
+        after: options.after,
+        before: options.before,
+        limit: options.limit,
+        offset: options.offset,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        console.log('\n  No videos matched those filters.\n');
+        return;
+    }
+    for (const item of items) {
+        renderRecordSummary(item);
+    }
+}
+async function runShowCommand(id, options) {
+    if (!await requireImportedData())
+        return;
+    const item = await getVideoByLookupKey(id);
+    if (!item) {
+        console.log(`\n  Video not found: ${id}\n`);
+        console.log('  Tip: ytl show accepts the stored id, a YouTube video id, or the full URL.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(item, null, 2));
+        return;
+    }
+    console.log(`${item.id} · ${item.channel_title ?? 'Unknown channel'}`);
+    console.log(item.url);
+    console.log(`title: ${item.title}`);
+    if (item.description)
+        console.log(`description: ${item.description}`);
+    console.log(`liked_at: ${item.liked_at ?? 'unknown'}`);
+    if (item.video_published_at)
+        console.log(`video_published_at: ${item.video_published_at}`);
+    if (item.duration)
+        console.log(`duration: ${item.duration}`);
+    if (item.privacy_status)
+        console.log(`privacy: ${item.privacy_status}`);
+    if (item.categories?.length)
+        console.log(`categories: ${item.categories.join(', ')}`);
+    if (item.domains?.length)
+        console.log(`domains: ${item.domains.join(', ')}`);
+    if (item.classification_reason)
+        console.log(`reason: ${item.classification_reason}`);
+    if (item.classification_engine) {
+        console.log(`classified_by: ${item.classification_engine}${item.classification_model ? ` (${item.classification_model})` : ''}`);
+    }
+}
+async function runProbeCommand(options) {
+    console.log(LOGO);
+    showIntro();
+    console.log(`
+  Reading Chrome cookies from:
+    ${options.chromeUserDataDir}/${options.chromeProfileDirectory}
+`);
+    const cookies = extractChromeYoutubeCookies(options.chromeUserDataDir, options.chromeProfileDirectory);
+    const report = await probeLikesHistory({
+        cookieHeader: cookies.cookieHeader,
+        sapisid: cookies.sapisid,
+        maxPages: options.maxPages,
+        delayMs: options.delayMs,
+        maxMinutes: options.maxMinutes,
+        baselineCeiling: options.baselineCeiling,
+    });
+    report.chromeUserDataDir = options.chromeUserDataDir;
+    report.chromeProfileDirectory = options.chromeProfileDirectory;
+    saveProbeReport(report);
+    console.log(`
+  Probe complete.
+
+  Liked page title: ${report.pageTitle}
+  YouTube page header count: ${report.statedVideoCount ?? 'unknown'}
+  Discovered through direct web continuation: ${report.discoveredCount.toLocaleString()}
+  Existing comparison ceiling: ${report.baselineCeiling.toLocaleString()}
+  Stop reason: ${report.stopReason}
+`);
+    if (!report.browserMethodBeatCeiling) {
+        console.log(`
+  Feasibility gate failed.
+
+  The browser-only continuation path still does not outperform the
+  existing archive ceiling on this machine, so the sync story remains
+  exploratory rather than production-ready.
+`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`
+  Feasibility gate passed.
+`);
+}
+async function runImportCommand(filePath) {
+    console.log(LOGO);
+    showIntro();
+    console.log(`
+  Importing archive:
+    ${filePath}
+`);
+    const result = await importVideoArchive(filePath);
+    console.log(`
+  ✓ ${result.imported.toLocaleString()} input videos imported
+  ✓ ${result.total.toLocaleString()} total videos in local archive
+  ✓ JSONL: ${videosJsonlPath()}
+  ✓ SQLite: ${videosDbPath()}
+`);
+    console.log(`
+  Next steps:
+        ytl enrich-channels
+        ytl classify
+        ytl classify-domains
+        ytl status
+`);
+}
+async function runEnrichChannelsCommand(options) {
+    if (!await requireImportedData())
+        return;
+    console.log(LOGO);
+    showIntro();
+    console.log(`
+  Repairing uploader metadata from YouTube's public oEmbed endpoint.
+  This updates the imported channel fields in place so search, show,
+  and viz reflect each video's actual uploader rather than the likes
+  playlist owner.
+`);
+    const started = Date.now();
+    process.stderr.write('Enriching channel metadata...\n');
+    const result = await enrichChannels({
+        limit: options.limit,
+        concurrency: options.concurrency ?? 8,
+        force: options.force,
+        onProgress: (done, total) => {
+            const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+            const elapsed = Math.round((Date.now() - started) / 1000);
+            process.stderr.write(`  Channels: ${done}/${total} (${pct}%) │ ${elapsed}s elapsed\n`);
+        },
+    });
+    console.log(`
+Attempted: ${result.attempted.toLocaleString()}
+Updated: ${result.updated.toLocaleString()}
+Skipped: ${result.skipped.toLocaleString()}
+Failed: ${result.failed.toLocaleString()}
+${result.dominantFallbackTitle ? `Detected fallback importer signal: ${result.dominantFallbackTitle}${result.dominantFallbackId ? ` (${result.dominantFallbackId})` : ''}\n` : ''}Next:
+  ytl viz
+  ytl search "your query"
+  ytl show <video-id>
+`);
+}
+async function runClassifyCommand(options) {
+    if (!await requireImportedData())
+        return;
+    console.log(LOGO);
+    showIntro();
+    const setup = await resolveClassifySetup({
+        engine: options.engine,
+        model: options.model,
+        batchSize: options.batchSize,
+        concurrency: options.concurrency,
+        limit: options.limit,
+        defaultGeminiModel: GEMINI_DEFAULT_MODEL,
+        defaultBatchSize: 50,
+        defaultConcurrency: 10,
+    });
+    if (!setup) {
+        return;
+    }
+    showClassifyPlan(setup);
+    const categoryStart = Date.now();
+    process.stderr.write(`Classifying categories with ${setup.engine === 'gemini' ? `Gemini (${setup.model}, batches of ${setup.batchSize})` : `${setup.engine} CLI (batches of ${setup.batchSize})`}...\n`);
+    const categories = await classifyCategories({
+        engine: setup.engine,
+        model: setup.model,
+        batchSize: setup.batchSize,
+        concurrency: setup.concurrency,
+        limit: setup.limit,
+        onBatch: (done, total) => {
+            const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+            const elapsed = Math.round((Date.now() - categoryStart) / 1000);
+            process.stderr.write(`  Categories: ${done}/${total} (${pct}%) │ ${elapsed}s elapsed\n`);
+        },
+    });
+    console.log(`
+Engine: ${categories.engine}
+${categories.model ? `Model: ${categories.model}\n` : ''}Categories: ${categories.classified}/${categories.totalPending} classified
+`);
+    const domainStart = Date.now();
+    process.stderr.write(`Classifying domains with ${setup.engine === 'gemini' ? `Gemini (${setup.model}, batches of ${setup.batchSize})` : `${setup.engine} CLI (batches of ${setup.batchSize})`}...\n`);
+    const domains = await classifyDomains({
+        engine: setup.engine,
+        model: setup.model,
+        batchSize: setup.batchSize,
+        concurrency: setup.concurrency,
+        limit: setup.limit,
+        onBatch: (done, total) => {
+            const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+            const elapsed = Math.round((Date.now() - domainStart) / 1000);
+            process.stderr.write(`  Domains: ${done}/${total} (${pct}%) │ ${elapsed}s elapsed\n`);
+        },
+    });
+    console.log(`
+Domains: ${domains.classified}/${domains.totalPending} classified
+`);
+}
+async function runClassifyDomainsCommand(options) {
+    if (!await requireImportedData())
+        return;
+    console.log(LOGO);
+    showIntro();
+    const setup = await resolveClassifySetup({
+        engine: options.engine,
+        model: options.model,
+        batchSize: options.batchSize,
+        concurrency: options.concurrency,
+        limit: options.limit,
+        defaultGeminiModel: GEMINI_DEFAULT_MODEL,
+        defaultBatchSize: 50,
+        defaultConcurrency: 10,
+    });
+    if (!setup) {
+        return;
+    }
+    showClassifyPlan(setup);
+    const start = Date.now();
+    process.stderr.write(`Classifying domains with ${setup.engine === 'gemini' ? `Gemini (${setup.model}, batches of ${setup.batchSize})` : `${setup.engine} CLI (batches of ${setup.batchSize})`}...\n`);
+    const result = await classifyDomains({
+        engine: setup.engine,
+        all: options.all,
+        model: setup.model,
+        batchSize: setup.batchSize,
+        concurrency: setup.concurrency,
+        limit: setup.limit,
+        onBatch: (done, total) => {
+            const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+            const elapsed = Math.round((Date.now() - start) / 1000);
+            process.stderr.write(`  Domains: ${done}/${total} (${pct}%) │ ${elapsed}s elapsed\n`);
+        },
+    });
+    console.log(`
+Engine: ${result.engine}
+${result.model ? `Model: ${result.model}\n` : ''}Domains: ${result.classified}/${result.totalPending} classified
+`);
+}
+export function buildCli() {
+    const program = new Command();
+    program
+        .name('ytl')
+        .description('Import, search, classify, and inspect your YouTube liked videos locally.')
+        .version('0.1.0')
+        .showHelpAfterError()
+        .action(() => {
+        console.log(LOGO);
+        showIntro();
+        showPaths();
+        console.log(`
+  Get started:
+        ytl import /path/to/liked_videos.json
+        ytl enrich-channels
+        ytl classify
+        ytl status
+`);
+    });
+    program
+        .command('sync')
+        .description('Run the exploratory browser-session feasibility probe for YouTube Likes.')
+        .option('--full', 'Accepted for FT-style compatibility.', false)
+        .option('--classify', 'Accepted for FT-style compatibility.', false)
+        .option('--max-pages <n>', 'Maximum continuation pages to request.', '80')
+        .option('--delay-ms <ms>', 'Delay between continuation requests.', '0')
+        .option('--max-minutes <n>', 'Maximum runtime in minutes.', '10')
+        .option('--chrome-user-data-dir <path>', 'Chrome user data dir.', defaultChromeUserDataDir())
+        .option('--chrome-profile-directory <name>', 'Chrome profile directory.', 'Default')
+        .option('--baseline-ceiling <n>', 'Comparison ceiling that the browser method must beat.', '4953')
+        .action(safe(async (options) => {
+        await runProbeCommand({
+            maxPages: Number.parseInt(options.maxPages, 10),
+            delayMs: Number.parseInt(options.delayMs, 10),
+            maxMinutes: Number.parseInt(options.maxMinutes, 10),
+            chromeUserDataDir: options.chromeUserDataDir,
+            chromeProfileDirectory: options.chromeProfileDirectory,
+            baselineCeiling: Number.parseInt(options.baselineCeiling, 10),
+        });
+    }));
+    program
+        .command('import')
+        .description('Import a YouTube liked-videos JSON archive into the local ytl store.')
+        .argument('<path>', 'Path to a JSON archive like liked_videos.json')
+        .action(safe(async (filePath) => {
+        await runImportCommand(filePath);
+    }));
+    program
+        .command('classify')
+        .description('Classify imported videos by category and domain using Gemini, Claude, or Codex.')
+        .option('--engine <engine>', 'Engine: gemini, claude, or codex (omit to choose interactively)')
+        .option('--model <name>', 'Gemini model name', GEMINI_DEFAULT_MODEL)
+        .option('--batch-size <n>', 'Batch size', (v) => Number(v), 50)
+        .option('--concurrency <n>', 'Concurrent Gemini batches (Gemini only)', (v) => Number(v), 10)
+        .option('--limit <n>', 'Only classify the first N pending videos', (v) => Number(v))
+        .action(safe(async (options) => {
+        await runClassifyCommand({
+            engine: options.engine ? String(options.engine) : undefined,
+            model: options.model,
+            batchSize: Number(options.batchSize) || 50,
+            concurrency: Number(options.concurrency) || 10,
+            limit: typeof options.limit === 'number' && !Number.isNaN(options.limit) ? options.limit : undefined,
+        });
+    }));
+    program
+        .command('enrich-channels')
+        .description('Repair uploader channel metadata for imported videos.')
+        .option('--limit <n>', 'Only enrich the first N candidate videos', (v) => Number(v))
+        .option('--concurrency <n>', 'Concurrent oEmbed requests', (v) => Number(v), 8)
+        .option('--force', 'Re-check all imported videos, not just suspicious ones', false)
+        .action(safe(async (options) => {
+        await runEnrichChannelsCommand({
+            limit: typeof options.limit === 'number' && !Number.isNaN(options.limit) ? options.limit : undefined,
+            concurrency: Number(options.concurrency) || 8,
+            force: Boolean(options.force),
+        });
+    }));
+    program
+        .command('classify-domains')
+        .description('Classify imported videos by subject domain using Gemini, Claude, or Codex.')
+        .option('--all', 'Re-classify all videos, not just missing domains')
+        .option('--engine <engine>', 'Engine: gemini, claude, or codex (omit to choose interactively)')
+        .option('--model <name>', 'Gemini model name', GEMINI_DEFAULT_MODEL)
+        .option('--batch-size <n>', 'Batch size', (v) => Number(v), 50)
+        .option('--concurrency <n>', 'Concurrent Gemini batches (Gemini only)', (v) => Number(v), 10)
+        .option('--limit <n>', 'Only classify the first N pending videos', (v) => Number(v))
+        .action(safe(async (options) => {
+        await runClassifyDomainsCommand({
+            all: Boolean(options.all),
+            engine: options.engine ? String(options.engine) : undefined,
+            model: options.model,
+            batchSize: Number(options.batchSize) || 50,
+            concurrency: Number(options.concurrency) || 10,
+            limit: typeof options.limit === 'number' && !Number.isNaN(options.limit) ? options.limit : undefined,
+        });
+    }));
+    program
+        .command('path')
+        .description('Show local data paths.')
+        .action(showPaths);
+    program
+        .command('status')
+        .description('Show imported archive counts, last classification engine/model, and last probe result.')
+        .action(safe(async () => {
+        await showStatus();
+    }));
+    program
+        .command('viz')
+        .description('Show a terminal summary of archive coverage, labels, and top channels.')
+        .action(safe(async () => {
+        await showViz();
+    }));
+    program
+        .command('stats')
+        .description('Show the same summary dashboard as viz.')
+        .action(safe(async () => {
+        await showViz();
+    }));
+    program
+        .command('search')
+        .description('Search your imported archive using local full-text search.')
+        .argument('<query>', 'Search query')
+        .option('--channel <name>', 'Filter by channel title')
+        .option('--category <slug>', 'Filter by primary category')
+        .option('--domain <slug>', 'Filter by primary domain')
+        .option('--limit <n>', 'Limit results', (v) => Number(v), 20)
+        .option('--json', 'JSON output')
+        .action(safe(async (query, options) => {
+        await runSearchCommand(query, {
+            channel: options.channel,
+            category: options.category,
+            domain: options.domain,
+            limit: Number(options.limit) || 20,
+            json: Boolean(options.json),
+        });
+    }));
+    program
+        .command('list')
+        .description('List imported videos with filters.')
+        .option('--query <q>', 'Optional full-text query')
+        .option('--channel <name>', 'Filter by channel title')
+        .option('--category <slug>', 'Filter by primary category')
+        .option('--domain <slug>', 'Filter by primary domain')
+        .option('--privacy <value>', 'Filter by privacy status')
+        .option('--after <date>', 'Filter after YYYY-MM-DD')
+        .option('--before <date>', 'Filter before YYYY-MM-DD')
+        .option('--limit <n>', 'Limit results', (v) => Number(v), 30)
+        .option('--offset <n>', 'Offset results', (v) => Number(v), 0)
+        .option('--json', 'JSON output')
+        .action(safe(async (options) => {
+        await runListCommand({
+            query: options.query,
+            channel: options.channel,
+            category: options.category,
+            domain: options.domain,
+            privacy: options.privacy,
+            after: options.after,
+            before: options.before,
+            limit: Number(options.limit) || 30,
+            offset: Number(options.offset) || 0,
+            json: Boolean(options.json),
+        });
+    }));
+    program
+        .command('show')
+        .description('Show one imported video in detail.')
+        .argument('<id>', 'Stored id, YouTube video id, or full URL')
+        .option('--json', 'JSON output')
+        .action(safe(async (id, options) => {
+        await runShowCommand(id, { json: Boolean(options.json) });
+    }));
+    return program;
+}
+export async function run(argv = process.argv) {
+    loadEnv();
+    await buildCli().parseAsync(argv);
+}
+const isEntrypoint = process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (isEntrypoint) {
+    run(process.argv);
+}

package/dist/config.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+import { dataDir, ensureDataDir } from './paths.js';
+let loadedEnvPath = null;
+export function geminiEnvLocalPath() {
+    return path.join(dataDir(), '.env.local');
+}
+export function loadEnv() {
+    const envPath = geminiEnvLocalPath();
+    if (loadedEnvPath === envPath) {
+        return;
+    }
+    ensureDataDir();
+    dotenv.config({ path: envPath, override: false, quiet: true });
+    loadedEnvPath = envPath;
+}
+export function writeGeminiApiKeyToEnvLocal(apiKey) {
+    ensureDataDir();
+    const envPath = geminiEnvLocalPath();
+    const keyLine = `GEMINI_API_KEY=${apiKey}`;
+    let lines = [];
+    if (fs.existsSync(envPath)) {
+        lines = fs.readFileSync(envPath, 'utf8')
+            .split(/\r?\n/)
+            .filter((line) => line.length > 0);
+    }
+    let updated = false;
+    lines = lines.map((line) => {
+        if (/^\s*GEMINI_API_KEY=/.test(line)) {
+            updated = true;
+            return keyLine;
+        }
+        return line;
+    });
+    if (!updated) {
+        lines.push(keyLine);
+    }
+    fs.writeFileSync(envPath, `${lines.join('\n')}\n`, { mode: 0o600 });
+    return envPath;
+}

package/dist/db.js

@@ -0,0 +1,28 @@
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+const require = createRequire(import.meta.url);
+let sqlPromise;
+function getSql() {
+    if (!sqlPromise) {
+        const initSqlJs = require('sql.js-fts5');
+        const wasmPath = require.resolve('sql.js-fts5/dist/sql-wasm.wasm');
+        const wasmBinary = fs.readFileSync(wasmPath);
+        sqlPromise = initSqlJs({ wasmBinary });
+    }
+    return sqlPromise;
+}
+export async function openDb(filePath) {
+    const SQL = await getSql();
+    if (fs.existsSync(filePath)) {
+        return new SQL.Database(fs.readFileSync(filePath));
+    }
+    return new SQL.Database();
+}
+export function saveDb(db, filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, Buffer.from(db.export()));
+}