yt-briefing 0.1.0

package/dist/lib/llm.js

@@ -0,0 +1,57 @@
+/**
+ * Minimal OpenAI-compatible chat client — the only LLM dependency in yt-briefing.
+ *
+ * Provider-agnostic: point LLM_BASE_URL at any OpenAI-compatible endpoint —
+ * OpenRouter (default, "any model, one key"), Google Gemini's OpenAI-compat
+ * endpoint, OpenAI itself, a local Ollama, etc. The tool depends only on an API key
+ * here — not on any specific vendor and not on a coding agent being installed.
+ *
+ * One model does both stages (title classification + summaries). Gemini 2.5 Flash is
+ * the default — cheap and fast enough for the batch title filter, capable enough for
+ * the summaries.
+ *
+ * Env (see .env.example):
+ *   LLM_BASE_URL   default https://openrouter.ai/api/v1
+ *   LLM_API_KEY    required
+ *   LLM_MODEL      default google/gemini-2.5-flash
+ */
+const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
+const DEFAULT_MODEL = "google/gemini-2.5-flash";
+export function getModel() {
+    return process.env.LLM_MODEL || DEFAULT_MODEL;
+}
+export async function chat(prompt, opts = {}) {
+    const baseUrl = (process.env.LLM_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const apiKey = process.env.LLM_API_KEY;
+    if (!apiKey)
+        throw new Error("LLM_API_KEY not set (see .env.example)");
+    const model = opts.model || getModel();
+    const messages = [];
+    if (opts.system)
+        messages.push({ role: "system", content: opts.system });
+    messages.push({ role: "user", content: prompt });
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        "X-Title": "yt-briefing",
+    };
+    const res = await fetch(`${baseUrl}/chat/completions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            model,
+            messages,
+            temperature: opts.temperature ?? 0.3,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`LLM ${res.status} ${res.statusText}: ${body.slice(0, 300)}`);
+    }
+    const data = await res.json();
+    const text = data?.choices?.[0]?.message?.content;
+    if (typeof text !== "string") {
+        throw new Error(`LLM: no content in response: ${JSON.stringify(data).slice(0, 300)}`);
+    }
+    return text.trim();
+}

package/dist/lib/paths.js

@@ -0,0 +1,56 @@
+/**
+ * Filesystem layout for yt-briefing — the single source of truth for every path.
+ *
+ * Three roots:
+ *   PKG_ROOT   the installed package (code + the compiled dist/).
+ *   BASE_DIR   where the user's secrets + state live. In a dev clone (you run the package
+ *              itself) this IS the package root, so the repo layout (`.env`, `data/`) is
+ *              unchanged. When the package is *consumed as a dependency* — PKG_ROOT sits
+ *              inside node_modules — that would be wiped on reinstall, so BASE_DIR moves to
+ *              `<your project>/.yt-briefing/` instead. Override explicitly with YT_BASE_DIR.
+ *   DATA_DIR   the mutable state (subscriptions, profiles, cursor, throwaway cache).
+ *              Defaults to <BASE_DIR>/data; override with YT_DATA_DIR to keep it anywhere
+ *              (e.g. a synced git folder, separate from secrets).
+ *
+ * BASE_DIR and DATA_DIR are pinned back into the environment so detached child processes —
+ * which we spawn with `cwd: PKG_ROOT`, a *different* cwd — resolve to the exact same folders.
+ *
+ * Nothing here reads the disk — it only resolves paths, so it is safe to import from every
+ * script and from the bootstrap wizard before any data exists.
+ */
+import { join, dirname, resolve, extname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SELF = fileURLToPath(import.meta.url); // …/lib/paths.ts (dev) or …/lib/paths.js (built)
+const HERE = dirname(SELF); // src/lib  or  dist/lib
+export const SRC_DIR = resolve(HERE, '..'); // src       or  dist
+export const PKG_ROOT = resolve(HERE, '../..'); // package root
+/** This build's script extension: '.ts' running from source under Bun, '.js' when compiled. */
+const SCRIPT_EXT = extname(SELF) || '.ts';
+// Consumed as a dependency? Then PKG_ROOT lives under node_modules and must not hold user state.
+const CONSUMED = PKG_ROOT.split(sep).includes('node_modules');
+export const BASE_DIR = process.env.YT_BASE_DIR
+    ? resolve(process.env.YT_BASE_DIR)
+    : CONSUMED ? join(process.cwd(), '.yt-briefing') : PKG_ROOT;
+process.env.YT_BASE_DIR = BASE_DIR; // pin for children (their cwd differs)
+export const ENV_PATH = join(BASE_DIR, '.env');
+export const DATA_DIR = process.env.YT_DATA_DIR
+    ? resolve(process.env.YT_DATA_DIR)
+    : join(BASE_DIR, 'data');
+process.env.YT_DATA_DIR = DATA_DIR; // pin for children (their cwd differs)
+export const CHANNELS_MD = join(DATA_DIR, 'channels.md');
+export const STATE_MD = join(DATA_DIR, 'state.md');
+export const CONFIG_JSON = join(DATA_DIR, 'config.json');
+export const CHANNELS_DIR = join(DATA_DIR, 'channels');
+export const CACHE_DIR = join(DATA_DIR, '.cache');
+export const QUEUE_FILE = join(CACHE_DIR, 'queue.json');
+export const REST_FILE = join(CACHE_DIR, 'queue-rest.json');
+export const PENDING_FILE = join(CACHE_DIR, 'pending.json');
+export const PREFETCH_FILE = join(CACHE_DIR, 'prefetch.json');
+export const LOG_FILE = join(CACHE_DIR, 'sweep.log');
+/** Absolute path to a channel profile from its slug. */
+export const profilePath = (slug) => join(CHANNELS_DIR, `${slug}.md`);
+/**
+ * Absolute path to a sibling engine script by its base name (no extension), so subprocess
+ * calls never depend on cwd and resolve to `.ts` in dev or `.js` once compiled to dist/.
+ */
+export const script = (base) => join(SRC_DIR, base + SCRIPT_EXT);

package/dist/lib/prompt.js

@@ -0,0 +1,39 @@
+/**
+ * Portable synchronous line reader — works under Node and Bun, for an interactive TTY and
+ * for piped stdin alike.
+ *
+ * Why not just `prompt()`: that global exists in Bun but NOT in Node. And Node's
+ * readline/promises stalls on a pipe under Bun. Reading file descriptor 0 directly sidesteps
+ * both runtimes' quirks. Bytes are accumulated and decoded as UTF-8 only at the end, so
+ * non-ASCII input (e.g. Polish characters) is preserved.
+ */
+import { readSync } from 'node:fs';
+/** Print `text` and block until the user types a line; returns it trimmed of the newline. */
+export function question(text) {
+    process.stdout.write(text.endsWith(' ') ? text : text + ' ');
+    const bytes = [];
+    const buf = Buffer.alloc(1);
+    while (true) {
+        let n = 0;
+        try {
+            n = readSync(0, buf, 0, 1, null);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === 'EAGAIN')
+                continue; // stdin momentarily not ready — retry
+            if (code === 'EOF')
+                break; // some platforms surface EOF as an error
+            throw e;
+        }
+        if (n === 0)
+            break; // EOF (e.g. end of a pipe)
+        const b = buf[0];
+        if (b === 0x0a)
+            break; // \n — end of line
+        if (b === 0x0d)
+            continue; // \r — ignore (CRLF)
+        bytes.push(b);
+    }
+    return Buffer.from(bytes).toString('utf8');
+}

package/dist/lib/skill-install.js

@@ -0,0 +1,66 @@
+/**
+ * skill-install — place the `/yt` SKILL.md into a coding agent's skills directory.
+ *
+ * Shared by the onboarding wizard (`bootstrap.ts`, final step) and the standalone
+ * `install-skill.ts` command, so both write the skill identically.
+ *
+ * The shipped SKILL.md uses `bun run src/X.ts` — the dev shortcut: it works when the agent's
+ * cwd IS the package folder AND the runtime is Bun (which runs TypeScript directly). That's
+ * true for the publisher's own day-to-day use, so it stays the default.
+ *
+ * For everyone else — a Node user, or any install whose cwd won't be the package — we bake an
+ * absolute, runtime-correct command instead: `"<this runtime>" "<abs>/dist/X.js"`. The runtime
+ * is `process.execPath` of whoever runs the installer (so `init` under Node bakes node, under
+ * Bun bakes bun), and it points at the compiled build, so it runs from any cwd. The engine
+ * resolves data/.env from its own location regardless. (Requires `dist/` — build once with
+ * `bun run build` / `npm run build`; that's exactly how a Node user already got here.)
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { PKG_ROOT } from "./paths.js";
+/** Compiled output dir — what a baked (dist) skill command points the runtime at. */
+const DIST_DIR = join(PKG_ROOT, 'dist');
+/** True when the installer itself is running under Bun (vs plain Node). */
+export const isBun = process.versions.bun != null;
+/**
+ * The shipped `bun run src/X.ts` command is only correct in ONE situation: the publisher
+ * developing *inside the package clone* under Bun (cwd === package, TypeScript runs directly,
+ * no build). Everywhere else — and crucially when the package is consumed as a dependency, so
+ * the engine lives in node_modules while the user works in their own project — we must bake the
+ * compiled `dist/` command instead. This detects that one dev-in-clone case.
+ */
+export const isPackageDevCwd = () => isBun && resolve(process.cwd()) === PKG_ROOT;
+export const SOURCE = join(PKG_ROOT, '.claude/skills/yt/SKILL.md');
+/** Agent key → display name + the skills subdirectory it scans. */
+export const AGENTS = {
+    '1': { name: 'Claude Code', sub: join('.claude', 'skills', 'yt') },
+    '2': { name: 'Cursor', sub: join('.cursor', 'skills', 'yt') },
+};
+/**
+ * The shipped SKILL.md. `dist=false` (default) returns it verbatim — the `bun run src/X.ts`
+ * dev form, correct only when cwd is the package AND the runtime is Bun. `dist=true` rewrites
+ * the engine commands to `"<process.execPath>" "<abs>/dist/X.js"` — this machine's runtime
+ * (Node or Bun) against the compiled build, so it runs from any cwd.
+ */
+export function skillBody(dist = false) {
+    const raw = readFileSync(SOURCE, 'utf8');
+    if (!dist)
+        return raw;
+    const exe = process.execPath;
+    const cmd = (base) => `"${exe}" "${join(DIST_DIR, base + '.js')}"`;
+    return raw
+        .replace(/bun run src\/yt-sweep\.ts/g, cmd('yt-sweep'))
+        .replace(/bun run src\/yt-rating\.ts/g, cmd('yt-rating'));
+}
+/** Write the skill into `dir` (created if needed). Returns the SKILL.md path written. */
+export function installSkill(dir, dist = false) {
+    mkdirSync(dir, { recursive: true });
+    const target = join(dir, 'SKILL.md');
+    writeFileSync(target, skillBody(dist), 'utf8');
+    return target;
+}
+/** The agent's skills directory inside a project folder (the project you open in the agent). */
+export const projectSkillDir = (agentKey, projectDir) => join(projectDir, AGENTS[agentKey].sub);
+/** Suggested target for a "custom" (any other agent) install — the open `.agents` convention,
+ *  rooted at the user's current project (not the package, which may be in node_modules). */
+export const customSkillDirDefault = () => join(process.cwd(), '.agents', 'skills', 'yt');

package/dist/lib/yt-api.js

@@ -0,0 +1,122 @@
+/**
+ * yt-api.ts — YouTube Data API v3 client over plain `fetch` (no SDK).
+ *
+ * Replaces the monolithic `googleapis` import, whose multi-thousand-file module tree
+ * cost ~7s to load from a cold FS cache on every fresh process. The Data API is a
+ * trivial REST surface, so direct fetch keeps cold-start near the runtime's own startup.
+ *
+ * Auth: YOUTUBE_API_KEY — the entrypoint loads it (dotenv.config from ENV_PATH) before
+ * calling; this module only reads process.env at call time.
+ */
+const API = 'https://www.googleapis.com/youtube/v3';
+function apiKey() {
+    const k = process.env.YOUTUBE_API_KEY;
+    if (!k)
+        throw new Error('YOUTUBE_API_KEY env var not set (see .env.example)');
+    return k;
+}
+async function get(path, params) {
+    const qs = new URLSearchParams({ ...params, key: apiKey() }).toString();
+    const res = await fetch(`${API}/${path}?${qs}`);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`YouTube API ${path} ${res.status}: ${body.slice(0, 200)}`);
+    }
+    return res.json();
+}
+/** handle (@x) or channelId (UC…) → uploads playlist id. */
+async function resolveUploadsPlaylist(handleOrId) {
+    const params = { part: 'contentDetails' };
+    if (handleOrId.startsWith('@'))
+        params.forHandle = handleOrId.slice(1);
+    else
+        params.id = handleOrId;
+    const data = await get('channels', params);
+    const items = data.items;
+    if (!items?.length)
+        throw new Error(`Channel not found: ${handleOrId}`);
+    return items[0].contentDetails.relatedPlaylists.uploads;
+}
+async function listUploads(playlistId, since, maxCount) {
+    const sinceTs = since ? new Date(since).getTime() : 0;
+    const videos = [];
+    let pageToken;
+    while (true) {
+        const params = {
+            part: 'snippet',
+            playlistId,
+            maxResults: String(maxCount !== null ? Math.min(maxCount, 50) : 50),
+        };
+        if (pageToken)
+            params.pageToken = pageToken;
+        const data = await get('playlistItems', params);
+        const items = data.items || [];
+        let hitOld = false;
+        for (const item of items) {
+            const publishedAt = item.snippet.publishedAt;
+            if (since && new Date(publishedAt).getTime() < sinceTs) {
+                hitOld = true;
+                break;
+            }
+            videos.push({ videoId: item.snippet.resourceId.videoId, title: item.snippet.title, publishedAt });
+            if (maxCount !== null && videos.length >= maxCount)
+                return videos;
+        }
+        if (hitOld || !data.nextPageToken)
+            break;
+        pageToken = data.nextPageToken;
+    }
+    return videos;
+}
+function parseDurationISO8601(iso) {
+    // PT#H#M#S — any segment may be absent. Examples: PT45S, PT3M12S, PT1H2M3S.
+    const m = iso.match(/^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?$/);
+    if (!m)
+        return 0;
+    const h = m[1] ? parseInt(m[1], 10) : 0;
+    const min = m[2] ? parseInt(m[2], 10) : 0;
+    const s = m[3] ? parseFloat(m[3]) : 0;
+    return h * 3600 + min * 60 + Math.round(s);
+}
+async function enrichWithTypes(videos) {
+    const out = [];
+    for (let i = 0; i < videos.length; i += 50) {
+        const chunk = videos.slice(i, i + 50);
+        const data = await get('videos', {
+            part: 'contentDetails,snippet,liveStreamingDetails',
+            id: chunk.map(v => v.videoId).join(','),
+        });
+        const byId = new Map();
+        for (const item of data.items || [])
+            byId.set(item.id, item);
+        for (const v of chunk) {
+            const item = byId.get(v.videoId);
+            if (!item) {
+                // metadata fetch failed for this id — treat as longform with unknown duration
+                v.type = 'longform';
+                v.durationSeconds = 0;
+                out.push(v);
+                continue;
+            }
+            const liveFlag = item.snippet?.liveBroadcastContent;
+            if (liveFlag === 'live' || liveFlag === 'upcoming')
+                continue; // not consumable yet
+            const duration = parseDurationISO8601(item.contentDetails?.duration || 'PT0S');
+            v.durationSeconds = duration;
+            const isPastLive = !!item.liveStreamingDetails?.actualEndTime;
+            v.type = isPastLive ? 'live' : duration <= 180 ? 'short' : 'longform';
+            out.push(v);
+        }
+    }
+    return out;
+}
+/**
+ * List a channel's uploads (newest first). With `enrich` (default true) each video is
+ * typed (short/live/longform) and current/upcoming live broadcasts are filtered out.
+ */
+export async function fetchChannelVideos(handleOrId, opts = {}) {
+    const { since = null, all = false, limit = null, enrich = true } = opts;
+    const uploads = await resolveUploadsPlaylist(handleOrId);
+    const videos = await listUploads(uploads, all ? null : since, limit);
+    return enrich ? enrichWithTypes(videos) : videos;
+}

package/dist/lib/yt-lib.js

@@ -0,0 +1,157 @@
+/**
+ * Shared utilities for yt-briefing: channels.md / state.md parsing and channel-profile
+ * editing. Pure string functions where possible — the caller does the I/O.
+ *
+ * The data files are human-editable Markdown on purpose: a channel profile is meant to
+ * be read and tweaked by hand, and ratings append to it as plain bullet lists.
+ */
+/** Canonical profile section headings (single source — used by the engine and rating writer). */
+export const SKIP_TITLES_HEADING = '## Skip titles';
+export const NOTES_HEADING = '## Notes';
+const NULL_CELL = /^[—\-]$/;
+const ENTRY_RE = /^-\s*\[(@[^\]]+)\]\([^)]+\)\s*→\s*\[\[channels\/([^\]]+)\]\]/;
+// ---------- channels.md ----------
+/** A flat list of `- [@Handle](url) → [[channels/slug]]` lines under `# Channels`. */
+export function parseChannels(content) {
+    const entries = [];
+    for (const line of content.split('\n')) {
+        const m = line.match(ENTRY_RE);
+        if (m)
+            entries.push({ handle: m[1], slug: m[2] });
+    }
+    return entries;
+}
+// ---------- state.md ----------
+/** One flat table; rows `| @Handle | id | id | id | date | int |`. */
+export function parseState(content) {
+    const rows = [];
+    for (const line of content.split('\n')) {
+        if (!line.startsWith('| @'))
+            continue;
+        const cells = line.split('|').map(c => c.trim()).filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
+        if (cells.length !== 6)
+            continue;
+        const [handle, lf, sh, lv, updated, session] = cells;
+        rows.push({
+            handle,
+            last_longform_id: NULL_CELL.test(lf) ? null : lf,
+            last_short_id: NULL_CELL.test(sh) ? null : sh,
+            last_live_id: NULL_CELL.test(lv) ? null : lv,
+            updated: NULL_CELL.test(updated) ? null : updated,
+            session: NULL_CELL.test(session) ? 0 : parseInt(session, 10) || 0,
+        });
+    }
+    return rows;
+}
+export function bumpStateFrontmatterDate(content, date) {
+    return content.replace(/^updated:\s*\d{4}-\d{2}-\d{2}/m, `updated: ${date}`);
+}
+/**
+ * Per-video pointer bump. Updates one type's last_id for one channel.
+ * Session counter increments only on first touch of the day (updated != date).
+ * Also bumps frontmatter `updated`.
+ */
+export function bumpStatePointer(content, handle, type, videoId, date) {
+    const lines = content.split('\n');
+    let touched = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.startsWith(`| ${handle} |`))
+            continue;
+        const cells = line.split('|');
+        if (cells.length < 8)
+            continue;
+        const cur = {
+            lf: cells[2].trim(),
+            sh: cells[3].trim(),
+            lv: cells[4].trim(),
+            updated: cells[5].trim(),
+            session: cells[6].trim(),
+        };
+        if (type === 'longform')
+            cur.lf = videoId;
+        else if (type === 'short')
+            cur.sh = videoId;
+        else if (type === 'live')
+            cur.lv = videoId;
+        const sessionNum = NULL_CELL.test(cur.session) ? 0 : parseInt(cur.session, 10) || 0;
+        if (cur.updated !== date) {
+            cur.session = String(sessionNum + 1);
+            cur.updated = date;
+        }
+        lines[i] = `| ${handle} | ${cur.lf} | ${cur.sh} | ${cur.lv} | ${cur.updated} | ${cur.session} |`;
+        touched = true;
+        break;
+    }
+    if (!touched)
+        throw new Error(`bumpStatePointer: row for ${handle} not found`);
+    return bumpStateFrontmatterDate(lines.join('\n'), date);
+}
+// ---------- channel profile: durable signal writes ----------
+/**
+ * Append `line` under `## <section>`, creating the section if missing (before `## Notes`
+ * when present, unless we ARE Notes — then at EOF), FIFO-capping the section's bullets to
+ * `cap`. Dedup: no-op if an identical bullet already exists. The profile is the durable
+ * store — there is no rolling buffer / consolidation; a rating writes straight here.
+ */
+export function appendToSection(profileContent, heading, line, cap = Infinity) {
+    const lines = profileContent.split('\n');
+    let hi = -1;
+    for (let i = 0; i < lines.length; i++)
+        if (lines[i].trim() === heading) {
+            hi = i;
+            break;
+        }
+    if (hi === -1) {
+        let insertAt = lines.length;
+        if (heading !== NOTES_HEADING) {
+            for (let i = 0; i < lines.length; i++)
+                if (lines[i].trim() === NOTES_HEADING) {
+                    insertAt = i;
+                    break;
+                }
+        }
+        const before = lines.slice(0, insertAt);
+        const after = lines.slice(insertAt);
+        while (before.length && before[before.length - 1].trim() === '')
+            before.pop();
+        const section = [heading, '', line, ''].join('\n');
+        const segments = [before.join('\n'), '', section];
+        if (after.length)
+            segments.push(after.join('\n'));
+        return segments.join('\n').replace(/\n{3,}/g, '\n\n');
+    }
+    let end = lines.length;
+    for (let i = hi + 1; i < lines.length; i++)
+        if (lines[i].startsWith('## ')) {
+            end = i;
+            break;
+        }
+    const body = lines.slice(hi + 1, end).filter(l => l.trim().startsWith('- '));
+    if (body.some(l => l.trim() === line.trim()))
+        return profileContent; // dedup
+    body.push(line);
+    while (body.length > cap)
+        body.shift(); // FIFO
+    const before = lines.slice(0, hi);
+    const after = lines.slice(end);
+    while (before.length && before[before.length - 1].trim() === '')
+        before.pop();
+    while (after.length && after[0].trim() === '')
+        after.shift();
+    const section = [heading, '', ...body, ''].join('\n');
+    const segments = [before.join('\n'), '', section];
+    if (after.length)
+        segments.push(after.join('\n'));
+    return segments.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+/** A `rating=0` writes a compact negative few-shot to `## Skip titles` (FIFO cap, default 10). */
+export function appendSkipTitle(profileContent, entry, cap = 10) {
+    const why = entry.comment && entry.comment.trim() ? ` · ${entry.comment.trim()}` : '';
+    const line = `- "${entry.title.replace(/"/g, "'")}" — ${entry.type}${why}`;
+    return appendToSection(profileContent, SKIP_TITLES_HEADING, line, cap);
+}
+/** A comment writes a durable rule to `## Notes` (uncapped — manual curation territory). */
+export function appendNote(profileContent, rule) {
+    return appendToSection(profileContent, NOTES_HEADING, `- ${rule.trim()}`);
+}

package/dist/yt-channel-pending.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Usage: bun src/yt-channel-pending.ts @HANDLE
+ *
+ * For one channel: reads state.md pointers + last-updated date,
+ * fetches the channel's videos in-process via lib/yt-api.ts (--since updated),
+ * filters to videos NEWER than each type's pointer (or baseline if pointer null),
+ * sorts ASC by publishedAt (process oldest first → state pointer advances monotonically),
+ * outputs JSON array: [{videoId, title, publishedAt, type, is_baseline}].
+ *
+ * Baseline (null pointer): emits ONLY the newest video of that type (others discarded).
+ * Empty result is valid (channel has no new content).
+ */
+import { readFileSync } from 'fs';
+import dotenv from 'dotenv';
+import { parseState } from "./lib/yt-lib.js";
+import { STATE_MD, ENV_PATH } from "./lib/paths.js";
+import { fetchChannelVideos } from "./lib/yt-api.js";
+dotenv.config({ path: ENV_PATH });
+const handle = process.argv[2];
+if (!handle) {
+    console.error('Usage: yt-channel-pending @HANDLE   (internal helper)');
+    process.exit(1);
+}
+const state = parseState(readFileSync(STATE_MD, 'utf8'));
+const row = state.find(r => r.handle === handle);
+if (!row) {
+    console.error(`Channel ${handle} not found in state.md`);
+    process.exit(1);
+}
+const since = row.updated ?? '2020-01-01';
+let videos;
+try {
+    videos = await fetchChannelVideos(handle, { since });
+}
+catch (e) {
+    console.error(e.message);
+    process.exit(1);
+}
+const pointerByType = {
+    longform: row.last_longform_id,
+    short: row.last_short_id,
+    live: row.last_live_id,
+};
+const pending = [];
+for (const type of ['longform', 'short', 'live']) {
+    const pointerId = pointerByType[type];
+    const ofType = videos.filter(v => v.type === type);
+    if (ofType.length === 0)
+        continue;
+    // Sort by publishedAt asc; oldest first
+    ofType.sort((a, b) => new Date(a.publishedAt).getTime() - new Date(b.publishedAt).getTime());
+    if (pointerId === null) {
+        // baseline: only emit newest of type
+        const newest = ofType[ofType.length - 1];
+        pending.push({
+            videoId: newest.videoId,
+            title: newest.title,
+            publishedAt: newest.publishedAt,
+            type,
+            is_baseline: true,
+        });
+        continue;
+    }
+    // normal: find pointer's publishedAt, take everything strictly newer
+    const pointerVideo = ofType.find(v => v.videoId === pointerId);
+    const cutoffTs = pointerVideo
+        ? new Date(pointerVideo.publishedAt).getTime()
+        : // pointer not in fetched window (older than --since cutoff) — take all videos of this type from response
+            -Infinity;
+    for (const v of ofType) {
+        if (new Date(v.publishedAt).getTime() <= cutoffTs)
+            continue;
+        pending.push({
+            videoId: v.videoId,
+            title: v.title,
+            publishedAt: v.publishedAt,
+            type,
+            is_baseline: false,
+        });
+    }
+}
+// Merge sort ASC across all types for stable iteration order
+pending.sort((a, b) => new Date(a.publishedAt).getTime() - new Date(b.publishedAt).getTime());
+console.log(JSON.stringify(pending, null, 2));

package/dist/yt-channel-videos.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Usage:
+ *   bun src/yt-channel-videos.ts @HANDLE_OR_CHANNEL_ID --since YYYY-MM-DD
+ *   bun src/yt-channel-videos.ts @HANDLE_OR_CHANNEL_ID --all
+ *   ... [--limit N] [--no-enrich]
+ *
+ * Output: JSON array [{videoId, title, publishedAt, type, durationSeconds}] on stdout (newest first)
+ *   type ∈ {'short', 'live', 'longform'}:
+ *     - 'short':    durationSeconds ≤ 180 (YT Shorts limit since Oct 2024), not live
+ *     - 'live':     past livestream/premiere — liveStreamingDetails.actualEndTime present
+ *     - 'longform': default (>180s, not live)
+ *   Filtered OUT: current and upcoming live broadcasts (no transcript yet, never consumable).
+ *   --no-enrich → skip the videos.list pass; type/durationSeconds omitted; no filtering.
+ *
+ * Requires: YOUTUBE_API_KEY (see .env.example). Thin CLI wrapper over lib/yt-api.ts.
+ *
+ * Quota: ~1 unit per page (playlistItems.list) + 1 unit per 50 videos (videos.list).
+ */
+import dotenv from 'dotenv';
+import { ENV_PATH } from "./lib/paths.js";
+import { fetchChannelVideos } from "./lib/yt-api.js";
+dotenv.config({ path: ENV_PATH });
+const args = process.argv.slice(2);
+const handleOrId = args[0];
+const sinceIdx = args.indexOf('--since');
+const since = sinceIdx !== -1 && args[sinceIdx + 1] ? args[sinceIdx + 1] : null;
+const all = args.includes('--all');
+const limitIdx = args.indexOf('--limit');
+const limit = limitIdx !== -1 && args[limitIdx + 1] ? parseInt(args[limitIdx + 1], 10) : null;
+const noEnrich = args.includes('--no-enrich');
+if (!handleOrId || (!since && !all)) {
+    console.error('Usage: yt-channel-videos @HANDLE_OR_ID (--since YYYY-MM-DD | --all) [--limit N] [--no-enrich]   (internal helper)');
+    process.exit(1);
+}
+try {
+    const out = await fetchChannelVideos(handleOrId, { since, all, limit, enrich: !noEnrich });
+    console.log(JSON.stringify(out, null, 2));
+}
+catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+}