@tacone/prosey 0.1.0 → 0.2.1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@tacone/prosey",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Download YouTube video transcripts from the CLI",
   "module": "src/index.ts",
   "type": "module",
   "bin": {
-    "prosey": "bin/prosey.js"
+    "prosey": "bin/prosey"
   },
   "files": [
     "bin/",
@@ -16,12 +16,11 @@
   ],
   "scripts": {
     "start": "bun run src/index.ts",
-    "build": "bun build src/index.ts --compile --outfile dist/prosey",
-    "build:node": "bun build src/index.ts --target node --outfile bin/prosey.js",
+    "build": "bun build src/index.ts --target node --outfile bin/prosey",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "prettier": "prettier --write .",
-    "prepack": "bun run build:node",
+    "prepack": "bun run build",
     "prepare": "husky || true"
   },
   "lint-staged": {
@@ -59,6 +58,7 @@
     "typescript": "^5"
   },
   "dependencies": {
+    "js-toml": "^1.1.2",
     "youtube-transcript-plus": "^2.0.0"
   }
 }

package/src/cache.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test, afterEach } from "bun:test";
+import { rm, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { cacheKey, cacheDir, readCache, writeCache, extractVideoId } from "./cache";
+
+const testDir = "/tmp/prosey/test-cache-spec";
+
+afterEach(async () => {
+  await rm(testDir, { recursive: true, force: true });
+});
+
+describe("cacheKey", () => {
+  test("includes video ID and hash", () => {
+    const key = cacheKey("dQw4w9WgXcQ", {});
+    expect(key).toStartWith("dQw4w9WgXcQ_");
+    expect(key.length).toBe(20); // 11 + 1 + 8
+  });
+
+  test("different lang produces different key", () => {
+    const a = cacheKey("dQw4w9WgXcQ", { lang: "en" });
+    const b = cacheKey("dQw4w9WgXcQ", { lang: "fr" });
+    expect(a).not.toBe(b);
+  });
+
+  test("different flags produce different key", () => {
+    const a = cacheKey("dQw4w9WgXcQ", {});
+    const b = cacheKey("dQw4w9WgXcQ", { timestamps: true });
+    expect(a).not.toBe(b);
+  });
+
+  test("mode distinguishes transcript from summarize", () => {
+    const a = cacheKey("dQw4w9WgXcQ", {});
+    const b = cacheKey("dQw4w9WgXcQ", { mode: "summarize" });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("cacheDir", () => {
+  test("returns path under /tmp/prosey with cache key", () => {
+    const key = cacheKey("abc123def45", {});
+    const dir = cacheDir("abc123def45", {});
+    expect(dir).toBe(`/tmp/prosey/${key}`);
+  });
+});
+
+describe("extractVideoId", () => {
+  test("bare ID passes through", () => {
+    expect(extractVideoId("dQw4w9WgXcQ")).toBe("dQw4w9WgXcQ");
+  });
+
+  test("full watch URL", () => {
+    expect(extractVideoId("https://www.youtube.com/watch?v=jNAAG3Ma5K8")).toBe("jNAAG3Ma5K8");
+  });
+
+  test("watch URL with extra query params", () => {
+    expect(
+      extractVideoId("https://www.youtube.com/watch?v=jNAAG3Ma5K8&pp=ygUKc3BhY2V4IGlwbw%3D%3D"),
+    ).toBe("jNAAG3Ma5K8");
+  });
+
+  test("short youtu.be URL", () => {
+    expect(extractVideoId("https://youtu.be/dQw4w9WgXcQ")).toBe("dQw4w9WgXcQ");
+  });
+
+  test("embed URL", () => {
+    expect(extractVideoId("https://www.youtube.com/embed/dQw4w9WgXcQ")).toBe("dQw4w9WgXcQ");
+  });
+
+  test("invalid URL without video ID returns null", () => {
+    expect(extractVideoId("https://example.com/search?q=hello")).toBeNull();
+  });
+});
+
+describe("readCache / writeCache", () => {
+  test("writes and reads a file", async () => {
+    await writeCache(testDir, "test.txt", "hello world");
+    const content = await readCache(testDir, "test.txt");
+    expect(content).toBe("hello world");
+  });
+
+  test("returns null for missing file", async () => {
+    const content = await readCache(testDir, "nonexistent.txt");
+    expect(content).toBeNull();
+  });
+
+  test("creates directory on write", async () => {
+    expect(existsSync(testDir)).toBe(false);
+    await writeCache(testDir, "createdir.txt", "data");
+    expect(existsSync(testDir)).toBe(true);
+  });
+});

package/src/cache.ts

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const RE_YOUTUBE =
+  /(?:v=|\/|v\/|embed\/|watch\?.*v=|youtu\.be\/|\/v\/|e\/|watch\?.*vi?=|\/embed\/|\/v\/|vi?\/|watch\?.*vi?=|youtu\.be\/|\/vi?\/|\/e\/)([a-zA-Z0-9_-]{11})/i;
+const RE_BARE_ID = /^[a-zA-Z0-9_-]{11}$/;
+
+export function extractVideoId(input: string): string | null {
+  if (RE_BARE_ID.test(input)) return input;
+  const match = input.match(RE_YOUTUBE);
+  if (match) return match[1] || null;
+  return null;
+}
+
+export interface CacheOptions {
+  lang?: string;
+  timestamps?: boolean;
+  json?: boolean;
+  noDecode?: boolean;
+  mode?: string;
+}
+
+function hashOptions(opts: CacheOptions): string {
+  return createHash("sha256").update(JSON.stringify(opts)).digest("hex").slice(0, 8);
+}
+
+export function cacheKey(videoId: string, opts: CacheOptions): string {
+  return `${videoId}_${hashOptions(opts)}`;
+}
+
+export function cacheDir(videoId: string, opts: CacheOptions): string {
+  return join("/tmp", "prosey", cacheKey(videoId, opts));
+}
+
+export async function readCache(dir: string, filename: string): Promise<string | null> {
+  try {
+    return await readFile(join(dir, filename), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export async function writeCache(dir: string, filename: string, data: string): Promise<void> {
+  if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, filename), data, "utf8");
+}

package/src/config.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test, afterEach } from "bun:test";
+import { rm, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { configPath, loadConfig, resetConfig } from "./config";
+
+const ORIGINAL_XDG = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_PROSEY_CONFIG = process.env.PROSEY_CONFIG_PATH;
+
+afterEach(() => {
+  if (ORIGINAL_XDG) process.env.XDG_CONFIG_HOME = ORIGINAL_XDG;
+  else delete process.env.XDG_CONFIG_HOME;
+  if (ORIGINAL_PROSEY_CONFIG) process.env.PROSEY_CONFIG_PATH = ORIGINAL_PROSEY_CONFIG;
+  else delete process.env.PROSEY_CONFIG_PATH;
+});
+
+describe("configPath", () => {
+  test("default path uses XDG_CONFIG_HOME when set", () => {
+    process.env.XDG_CONFIG_HOME = "/custom/xdg";
+    delete process.env.PROSEY_CONFIG_PATH;
+    expect(configPath()).toBe("/custom/xdg/prosey/config.toml");
+  });
+
+  test("default path falls back to ~/.config", () => {
+    delete process.env.XDG_CONFIG_HOME;
+    delete process.env.PROSEY_CONFIG_PATH;
+    expect(configPath()).toBe(join(homedir(), ".config", "prosey", "config.toml"));
+  });
+
+  test("PROSEY_CONFIG_PATH overrides everything", () => {
+    process.env.XDG_CONFIG_HOME = "/custom/xdg";
+    process.env.PROSEY_CONFIG_PATH = "/override/path/config.toml";
+    expect(configPath()).toBe("/override/path/config.toml");
+  });
+});
+
+describe("loadConfig", () => {
+  const tmpConfig = join(import.meta.dir, "..", "tmp-test-config.toml");
+
+  afterEach(async () => {
+    try {
+      await rm(tmpConfig);
+    } catch {}
+  });
+
+  test("auto-creates config file when missing", async () => {
+    process.env.PROSEY_CONFIG_PATH = tmpConfig;
+    expect(existsSync(tmpConfig)).toBe(false);
+
+    const config = await loadConfig();
+    expect(config).toEqual({});
+    expect(existsSync(tmpConfig)).toBe(true);
+
+    const content = await readFile(tmpConfig, "utf8");
+    expect(content).toContain("[summarize]");
+    expect(content).toContain('command = "opencode run"');
+  });
+
+  test("reads existing config file", async () => {
+    process.env.PROSEY_CONFIG_PATH = tmpConfig;
+
+    await loadConfig();
+    const config = await loadConfig();
+    expect(config.summarize?.prompt).toBeString();
+    expect(config.summarize?.command).toBe("opencode run");
+  });
+
+  test("handles invalid TOML gracefully", async () => {
+    process.env.PROSEY_CONFIG_PATH = tmpConfig;
+    await Bun.write(tmpConfig, "invalid [[\ntoml{{{");
+
+    const config = await loadConfig();
+    expect(config).toEqual({});
+  });
+});
+
+describe("resetConfig", () => {
+  const tmpConfig = join(import.meta.dir, "..", "tmp-reset-config.toml");
+
+  afterEach(async () => {
+    try {
+      await rm(tmpConfig);
+    } catch {}
+  });
+
+  test("overwrites existing file with defaults", async () => {
+    process.env.PROSEY_CONFIG_PATH = tmpConfig;
+
+    await Bun.write(tmpConfig, "# garbage");
+    const path = await resetConfig();
+    expect(path).toBe(tmpConfig);
+
+    const content = await readFile(tmpConfig, "utf8");
+    expect(content).toContain("[summarize]");
+    expect(content).toContain('command = "opencode run"');
+  });
+});

package/src/config.ts

@@ -0,0 +1,93 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { load } from "js-toml";
+
+export interface ProseyConfig {
+  summarize?: {
+    prompt?: string;
+    command?: string;
+  };
+}
+
+const FALLBACK_CONFIG_TOML = `# Default prosey configuration
+# Created automatically on first run. Edit as needed.
+
+[summarize]
+# Prompt sent to the command via stdin.
+# Customize this to change how transcripts are summarized.
+prompt = """
+Write a comprehensive summary of the following transcription.
+"""
+
+# Command to execute with the prompt and transcript piped via stdin.
+# The transcript is appended to the prompt automatically.
+#
+# Available options:
+#
+#   opencode run                    — full access (default)
+#   opencode run --permissions read  — read-only (view files, no edits)
+#
+#   claude -p "" --print            — full access (--print for clean output)
+#   claude --permission-mode plan -p "" --print  — read-only (plan/read only)
+#
+#   copilot -sp ""                  — full access (-s = silent, -p = prompt)
+#   copilot -sp "" --deny-all-tools — read-only (no shell/write access)
+#
+#   codex --sandbox default -p ""   — full access
+#   codex --sandbox read-only -p "" — read-only
+command = "opencode run"
+`;
+
+async function readDefaultConfig(): Promise<string> {
+  const paths = [
+    join(dirname(fileURLToPath(import.meta.url)), "default-config.toml"),
+    join(dirname(fileURLToPath(import.meta.url)), "..", "src", "default-config.toml"),
+  ];
+  for (const p of paths) {
+    if (existsSync(p)) return readFile(p, "utf8");
+  }
+  return FALLBACK_CONFIG_TOML;
+}
+
+function configDir(): string {
+  const env = process.env.XDG_CONFIG_HOME;
+  if (env) return join(env, "prosey");
+  return join(homedir(), ".config", "prosey");
+}
+
+export function configPath(): string {
+  return process.env.PROSEY_CONFIG_PATH ?? join(configDir(), "config.toml");
+}
+
+function ensureDir(path: string): Promise<void> {
+  return mkdir(path, { recursive: true }) as Promise<void>;
+}
+
+export async function loadConfig(): Promise<ProseyConfig> {
+  const path = configPath();
+
+  if (!existsSync(path)) {
+    const dir = configDir();
+    await ensureDir(dir);
+    await writeFile(path, await readDefaultConfig(), "utf8");
+    return {};
+  }
+
+  const raw = await readFile(path, "utf8");
+  try {
+    return load(raw) as ProseyConfig;
+  } catch {
+    return {};
+  }
+}
+
+export async function resetConfig(): Promise<string> {
+  const path = configPath();
+  const dir = configDir();
+  await ensureDir(dir);
+  await writeFile(path, await readDefaultConfig(), "utf8");
+  return path;
+}

package/src/debug.ts

@@ -0,0 +1,13 @@
+const GRAY = "\x1b[90m";
+const RESET = "\x1b[0m";
+
+let enabled = false;
+
+export function enableDebug(): void {
+  enabled = true;
+}
+
+export function debug(...args: unknown[]): void {
+  if (!enabled) return;
+  console.error(GRAY, ...args, RESET);
+}

package/src/default-config.toml

@@ -0,0 +1,16 @@
+# Default prosey configuration
+# Created automatically on first run. Edit as needed.
+
+[summarize]
+
+# Prompt sent to the command via stdin.
+# Customize this to change how transcripts are summarized.
+
+prompt = """
+Write a comprehensive summary of the following transcription.
+"""
+
+# Command to execute with the prompt and transcript piped via stdin.
+# The transcript is appended to the prompt automatically.
+
+command = "OPENCODE_PERMISSION='{\"read\":\"allow\",\"write\":\"deny\",\"edit\":\"deny\",\"bash\":\"deny\",\"glob\":\"deny\",\"grep\":\"deny\",\"webfetch\":\"deny\",\"task\":\"deny\",\"todowrite\":\"deny\",\"websearch\":\"deny\",\"lsp\":\"deny\"}' opencode run --pure"

package/src/index.ts

@@ -2,8 +2,13 @@
 
 import { writeFile } from "node:fs/promises";
 import { fetchTranscript, listLanguages } from "youtube-transcript-plus";
-import type { CaptionTrackInfo, VideoDetails } from "youtube-transcript-plus";
+import type { CaptionTrackInfo, VideoDetails, TranscriptSegment } from "youtube-transcript-plus";
 import { formatWithTimestamps, toText, toJSON, formatDuration, decodeEntities } from "./format";
+import { loadConfig, resetConfig, configPath } from "./config";
+import type { ProseyConfig } from "./config";
+import { summarize } from "./summarize";
+import { cacheDir, readCache, writeCache, extractVideoId } from "./cache";
+import { enableDebug, debug } from "./debug";
 
 const NAME = "prosey";
 const VERSION = "0.1.0";
@@ -13,11 +18,13 @@ function help(): string {
 
 Usage: ${NAME} [options] <video-url-or-id>
        ${NAME} info [options] <video-url-or-id>
+       ${NAME} summarize [options] <video-url-or-id>
 
 Download a YouTube video transcript or show video details.
 
 Commands:
   info                  Show video metadata (title, channel, duration, etc.)
+  summarize             Pipe transcript to the command configured in [summarize]
 
 Arguments:
   video-url-or-id        YouTube URL (full or short) or bare video ID
@@ -32,6 +39,9 @@ Options:
   --details              Prepend video details to transcript (default, text only).
   --no-details           Suppress video details, transcript only.
   --no-decode-entities   Preserve HTML entities (decoded by default).
+  --reset-config         Reset config file to defaults and exit.
+  --no-cache             Skip cache and overwrite cache files.
+  --debug                Print debug information to stderr.
   --help                 Show this help message.
   --version              Show version.
 
@@ -121,10 +131,19 @@ if (args.includes("--version")) {
   process.exit(0);
 }
 
+if (args.includes("--reset-config")) {
+  const path = await resetConfig();
+  console.log(`Config reset to defaults: ${path}`);
+  process.exit(0);
+}
+
+const config: ProseyConfig = await loadConfig().catch(() => ({}) as ProseyConfig);
+
 let mode = "transcript";
-if (args[0] === "info") {
-  mode = "info";
-  args.splice(0, 1);
+const subcmdIndex = args.findIndex((a) => a === "info" || a === "summarize");
+if (subcmdIndex !== -1) {
+  mode = args[subcmdIndex]!;
+  args.splice(subcmdIndex, 1);
 }
 
 let videoId = "";
@@ -135,6 +154,8 @@ let outputPath: string | undefined;
 let outputJson = false;
 let noDecode = false;
 let showDetails = true;
+let noCache = false;
+let debugMode = false;
 
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
@@ -163,6 +184,10 @@ for (let i = 0; i < args.length; i++) {
     showDetails = true;
   } else if (arg === "--no-details") {
     showDetails = false;
+  } else if (arg === "--no-cache") {
+    noCache = true;
+  } else if (arg === "--debug") {
+    debugMode = true;
   } else if (arg === "--no-decode-entities") {
     noDecode = true;
   } else if (arg.startsWith("-")) {
@@ -179,6 +204,21 @@ if (!videoId) {
   process.exit(1);
 }
 
+const extracted = extractVideoId(videoId);
+
+if (!extracted) {
+  console.error("Error: invalid YouTube video URL or ID");
+  process.exit(65);
+}
+
+videoId = extracted;
+
+if (debugMode) enableDebug();
+debug("Config file:", configPath());
+debug("Video ID:", videoId);
+debug("Mode:", mode);
+if (lang) debug("Language:", lang);
+
 try {
   if (mode === "info") {
     const result = await fetchTranscript(videoId, { videoDetails: true, lang } as any);
@@ -190,25 +230,116 @@ try {
     process.exit(0);
   }
 
-  if (listOnly) {
+  if (mode === "summarize") {
+    if (!config.summarize?.command) {
+      console.error("Error: [summarize] section with a command is required in config");
+      process.exit(1);
+    }
+
+    const cacheOpts = { lang, mode: "summarize", noDecode };
+    const dir = cacheDir(videoId, cacheOpts);
+    let segments: TranscriptSegment[] | null = null;
+    let summary: string | null = null;
+
+    if (!noCache) {
+      const cachedSegments = await readCache(dir, "transcript.json");
+      const cachedSummary = await readCache(dir, "summary.md");
+      if (cachedSegments && cachedSummary) {
+        debug("Cache hit:", dir);
+        segments = JSON.parse(cachedSegments);
+        summary = cachedSummary;
+      } else {
+        debug("Cache miss:", dir);
+      }
+    } else {
+      debug("Cache skipped (--no-cache)");
+    }
+
+    if (!segments) {
+      debug("Fetching transcript...");
+      segments = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
+      debug(`Transcript fetched: ${segments.length} segments`);
+      await writeCache(dir, "transcript.json", JSON.stringify(segments));
+      debug("Cache written: transcript.json");
+    }
+
+    const prompt = config.summarize.prompt ?? "";
+    const transcriptText = toText(segments, !noDecode);
+
+    if (!summary) {
+      debug("Running command:", config.summarize.command);
+      summary = await summarize({
+        prompt,
+        command: config.summarize.command,
+        transcript: transcriptText,
+        cwd: dir,
+      });
+      debug("Command exit: 0");
+      await writeCache(dir, "summary.md", summary);
+      debug("Cache written: summary.md");
+    }
+
+    if (outputPath) {
+      await writeFile(outputPath, summary, "utf8");
+    } else {
+      console.log(summary);
+    }
+    process.exit(0);
+  } else if (listOnly) {
     const languages = await listLanguages(videoId);
     printLanguages(languages);
     process.exit(0);
   }
 
   const decode = !noDecode;
+  const cacheOpts = { lang, timestamps, json: outputJson, noDecode };
+  const dir = cacheDir(videoId, cacheOpts);
+  let segments: TranscriptSegment[] | null = null;
+  let videoDetailsCache: VideoDetails | null = null;
+
+  if (!noCache) {
+    const cached = await readCache(dir, "transcript.json");
+    if (cached) {
+      debug("Cache hit:", dir);
+      segments = JSON.parse(cached);
+    } else {
+      debug("Cache miss:", dir);
+    }
+  } else {
+    debug("Cache skipped (--no-cache)");
+  }
+
+  if (!segments) {
+    debug("Fetching transcript...");
+    if (showDetails && !outputJson) {
+      const opts = lang ? { lang, videoDetails: true as const } : { videoDetails: true as const };
+      const result = (await fetchTranscript(videoId, opts)) as {
+        videoDetails: VideoDetails;
+        segments: TranscriptSegment[];
+      };
+      segments = result.segments;
+      videoDetailsCache = result.videoDetails;
+    } else {
+      segments = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
+    }
+    await writeCache(dir, "transcript.json", JSON.stringify(segments));
+  }
 
   if (showDetails && !outputJson) {
-    const config = lang ? { lang, videoDetails: true as const } : { videoDetails: true as const };
-    const result = (await fetchTranscript(videoId, config)) as {
-      videoDetails: VideoDetails;
-      segments: { text: string; offset: number; duration: number; lang: string }[];
-    };
-    const detailsBlock = formatDetailsBlock(result.videoDetails);
-    const transcript = timestamps
-      ? formatWithTimestamps(result.segments, decode)
-      : toText(result.segments, decode);
-    const output = detailsBlock + "\n\n\n" + transcript + "\n";
+    if (!videoDetailsCache) {
+      const opts = lang ? { lang, videoDetails: true as const } : { videoDetails: true as const };
+      const result = (await fetchTranscript(videoId, opts)) as {
+        videoDetails: VideoDetails;
+        segments: TranscriptSegment[];
+      };
+      videoDetailsCache = result.videoDetails;
+    }
+
+    const detailsBlock = formatDetailsBlock(videoDetailsCache);
+    const transcriptText = timestamps
+      ? formatWithTimestamps(segments, decode)
+      : toText(segments, decode);
+    const output = detailsBlock + "\n\n\n" + transcriptText + "\n";
 
     if (outputPath) {
       await writeFile(outputPath, output, "utf8");
@@ -216,10 +347,6 @@ try {
       console.log(output);
     }
   } else {
-    const segments = lang
-      ? await fetchTranscript(videoId, { lang })
-      : await fetchTranscript(videoId);
-
     const output = outputJson
       ? toJSON(segments, decode) + "\n"
       : timestamps

package/src/summarize.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { summarize } from "./summarize";
+
+describe("summarize", () => {
+  test("rejects when command only echoes input", async () => {
+    await expect(
+      summarize({
+        prompt: "Summarize this:",
+        command: "cat",
+        transcript: "Hello world. This is the transcript.",
+      }),
+    ).rejects.toThrow("Summarization command returned no meaningful output");
+  });
+
+  test("rejects when command only echoes input with empty prompt", async () => {
+    await expect(
+      summarize({
+        prompt: "",
+        command: "cat",
+        transcript: "Just the transcript.",
+      }),
+    ).rejects.toThrow("Summarization command returned no meaningful output");
+  });
+
+  test("preserves response text beyond the input", async () => {
+    const cmd = "sh -c 'cat -; echo \"RESPONSE\"'";
+    const result = await summarize({
+      prompt: "Summarize:",
+      command: cmd,
+      transcript: "Transcript text.",
+    });
+    expect(result).toBe("RESPONSE");
+  });
+
+  test("rejects on non-zero exit code", async () => {
+    await expect(
+      summarize({
+        prompt: "test",
+        command: "false",
+        transcript: "whatever",
+      }),
+    ).rejects.toThrow(/exited with code 1/);
+  });
+});