@tacone/prosey 0.2.4 → 0.3.0

package/src/index.ts

@@ -11,27 +11,57 @@ import { formatWithTimestamps, toText, toJSON, formatDuration, decodeEntities }
 import { loadConfig, resetConfig, configPath } from "./config";
 import type { ProseyConfig } from "./config";
 import { summarize } from "./summarize";
+import {
+  resolveSummarizeCmd,
+  resolveSummarizePrompt,
+  resolveTranscribeCmd,
+  resolveTranscribePrompt,
+} from "./config-resolve";
 import { cacheDir, readCache, writeCache, extractVideoId } from "./cache";
+import { extractChapters, formatChaptersAsText, formatChaptersAsJson } from "./extract-chapters";
+import { checkVersion } from "./version-check";
 import pkg from "../package.json";
 import prettier from "prettier";
 
+process.stdout.on("error", (err: NodeJS.ErrnoException) => {
+  if (err.code === "EPIPE") process.exit(0);
+});
+
 const NAME = "prosey";
 const VERSION = pkg.version;
 
+let latestVersion: string | null = null;
+const versionCheck = checkVersion().then((v) => {
+  latestVersion = v;
+});
+
+function exitProcess(code: number): never {
+  if (useHints && code === 0 && latestVersion && latestVersion !== VERSION) {
+    hint(
+      `📦 New version available: ${latestVersion} — use npm/pnpm/bun -g i ${pkg.name} to upgrade`,
+    );
+  }
+  process.exit(code);
+}
+
 function help(): string {
   return `${NAME} v${VERSION}
 
 Usage: ${NAME} [options] <video-url-or-id>
+       ${NAME} read [options] <video-url-or-id>
        ${NAME} info [options] <video-url-or-id>
        ${NAME} summarize [options] <video-url-or-id>
        ${NAME} config
+       ${NAME} help
 
 Download a YouTube video transcript or show video details.
 
 Commands:
+  summarize             Pipe transcript to the AI command (default command)
+  read                  Download and print a richly formatted transcript
   info                  Show video metadata (title, channel, duration, etc.)
-  summarize             Pipe transcript to the command configured in [summarize]
   config                Open config file in \$EDITOR
+  help                  Show this help message
 
 Arguments:
   video-url-or-id        YouTube URL (full or short) or bare video ID
@@ -41,14 +71,18 @@ Options:
   -t, --timestamps       Include timestamps [MM:SS] in output.
   --list                 List available transcript languages and exit.
   -o, --output <path>    Write output to file instead of stdout.
-  --json                 Output as JSON (suppresses details).
-  --text                 Output as plain text (default).
+  --format <type>        Output format: markdown (default), text, or json.
+  --json                 Shortcut for --format json.
+  --text                 Shortcut for --format text.
+  --markdown             Shortcut for --format markdown.
   --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.
   --no-format            Skip prettier formatting.
+  --dry-run              Print what would be sent to the AI command and exit.
+  --extract-timestamps   Extract chapter timestamps from video description.
   --no-pager             Disable pager for stdout output.
   --pager                Use pager for stdout output (default).
   --no-hints             Disable hints.
@@ -178,26 +212,28 @@ let pagerCmd: string | null = null;
 
 const args = process.argv.slice(2);
 
-if (args.length === 0 || args.includes("--help")) {
+if (args.length === 0 || args.includes("--help") || args.includes("help")) {
   console.log(help());
-  process.exit(0);
+  exitProcess(0);
 }
 
 if (args.includes("--version")) {
   console.log(VERSION);
-  process.exit(0);
+  exitProcess(0);
 }
 
 if (args.includes("--reset-config")) {
   const path = await resetConfig();
   console.log(`Config reset to defaults: ${path}`);
-  process.exit(0);
+  exitProcess(0);
 }
 
 const config: ProseyConfig = await loadConfig().catch(() => ({}) as ProseyConfig);
 
-let mode = "transcript";
-const subcmdIndex = args.findIndex((a) => a === "info" || a === "summarize" || a === "config");
+let mode = "summarize";
+const subcmdIndex = args.findIndex(
+  (a) => a === "info" || a === "summarize" || a === "config" || a === "read",
+);
 if (subcmdIndex !== -1) {
   mode = args[subcmdIndex]!;
   args.splice(subcmdIndex, 1);
@@ -209,12 +245,15 @@ let timestamps = false;
 let listOnly = false;
 let outputPath: string | undefined;
 let outputJson = false;
+let format: "text" | "json" | "markdown" = "markdown";
 let noDecode = false;
 let showDetails = true;
 let noCache = false;
 let noFormat = false;
 let usePager = true;
 let useHints = true;
+let dryRun = false;
+let extractTimestamps = false;
 let logLevel: LogLevel = "normal";
 
 for (let i = 0; i < args.length; i++) {
@@ -224,7 +263,7 @@ for (let i = 0; i < args.length; i++) {
     lang = args[++i] ?? undefined;
     if (!lang) {
       console.error("Error: --lang requires a language code");
-      process.exit(1);
+      exitProcess(1);
     }
   } else if (arg === "--timestamps" || arg === "-t") {
     timestamps = true;
@@ -234,12 +273,31 @@ for (let i = 0; i < args.length; i++) {
     outputPath = args[++i] ?? undefined;
     if (!outputPath) {
       console.error("Error: -o/--output requires a file path");
-      process.exit(1);
+      exitProcess(1);
     }
   } else if (arg === "--json") {
     outputJson = true;
+    format = "json";
   } else if (arg === "--text") {
     outputJson = false;
+    format = "text";
+  } else if (arg === "--markdown") {
+    format = "markdown";
+  } else if (arg === "--format") {
+    const val = args[++i];
+    if (val === "json") {
+      format = "json";
+      outputJson = true;
+    } else if (val === "text") {
+      format = "text";
+      outputJson = false;
+    } else if (val === "markdown") {
+      format = "markdown";
+      outputJson = false;
+    } else {
+      console.error("Error: --format must be text, json, or markdown");
+      exitProcess(1);
+    }
   } else if (arg === "--details") {
     showDetails = true;
   } else if (arg === "--no-details") {
@@ -262,9 +320,13 @@ for (let i = 0; i < args.length; i++) {
     logLevel = "verbose";
   } else if (arg === "--no-decode-entities") {
     noDecode = true;
+  } else if (arg === "--dry-run") {
+    dryRun = true;
+  } else if (arg === "--extract-timestamps") {
+    extractTimestamps = true;
   } else if (arg.startsWith("-")) {
     console.error(`Unknown option: ${arg}`);
-    process.exit(1);
+    exitProcess(1);
   } else {
     videoId = arg;
   }
@@ -282,23 +344,23 @@ if (mode === "config") {
   } else {
     console.log(`Config file: ${path}`);
   }
-  process.exit(0);
+  exitProcess(0);
 }
 
 if (!videoId) {
   console.error("Error: missing video URL or ID");
   console.log(help());
-  process.exit(1);
+  exitProcess(1);
 }
 
 const extracted = extractVideoId(videoId);
 
 if (!extracted) {
   console.error("Error: invalid YouTube video URL or ID");
-  process.exit(65);
+  exitProcess(65);
 }
 
-videoId = extracted;
+videoId = extracted!;
 
 setLevel(logLevel);
 resetTimer();
@@ -316,7 +378,7 @@ debug("Pager:", pagerCmd ?? "none");
 
 if (useHints) {
   const hasMarkdownPager =
-    pagerCmd === "bat -lmd" || pagerCmd === "glow" || pagerCmd === "mdcat -l -p";
+    pagerCmd === "bat -lmd --style plain" || pagerCmd === "glow -p" || pagerCmd === "mdcat -l -p";
   if (!hasMarkdownPager) {
     hint("Tip: install a markdown highlighter for better output (e.g. bat, glow, mdcat)");
   }
@@ -327,6 +389,28 @@ debug("Video ID:", videoId);
 debug("Mode:", mode);
 if (lang) debug("Language:", lang);
 
+// Give the version check a moment to complete
+await Promise.race([versionCheck, new Promise((r) => setTimeout(r, 1000))]);
+
+if (extractTimestamps) {
+  startTimer();
+  info("Fetching transcript...");
+  const result = (await fetchTranscript(videoId, {
+    videoDetails: true,
+    lang,
+  } as any)) as {
+    videoDetails: VideoDetails;
+    segments: TranscriptSegment[];
+  };
+  info("Transcript fetched");
+  const chapters = extractChapters(result.videoDetails.description);
+  const output = outputJson
+    ? JSON.stringify(chapters, null, 2) + "\n"
+    : formatChaptersAsText(chapters) + "\n";
+  await outputText(output);
+  exitProcess(0);
+}
+
 try {
   if (mode === "info") {
     const result = await fetchTranscript(videoId, { videoDetails: true, lang } as any);
@@ -335,13 +419,16 @@ try {
     } else {
       printVideoInfo(result.videoDetails);
     }
-    process.exit(0);
+    exitProcess(0);
   }
 
   if (mode === "summarize") {
-    if (!config.summarize?.command) {
-      console.error("Error: [summarize] section with a command is required in config");
-      process.exit(1);
+    const sumCmd = resolveSummarizeCmd(config);
+    if (!sumCmd) {
+      console.error(
+        "Error: no command configured for summarize. Set [ai].command or [summarize].command in config.",
+      );
+      exitProcess(1);
     }
 
     const cacheOpts = { lang, mode: "summarize", noDecode };
@@ -374,14 +461,25 @@ try {
       debug("Cache written: transcript.json");
     }
 
-    const prompt = config.summarize.prompt ?? "";
+    const prompt = resolveSummarizePrompt(config) ?? "";
+    if (!prompt) {
+      console.error(
+        "Error: no prompt configured. Set a prompt in the [summarize] section of your config.",
+      );
+      exitProcess(1);
+    }
     const transcriptText = toText(segments, !noDecode);
 
+    if (dryRun) {
+      await outputText(`${prompt}\n\n${transcriptText}\n`);
+      exitProcess(0);
+    }
+
     if (!summary) {
       info(`Summarizing...`);
       summary = await summarize({
         prompt,
-        command: config.summarize.command,
+        command: sumCmd,
         transcript: transcriptText,
         cwd: dir,
       });
@@ -392,11 +490,153 @@ try {
 
     const formatted = noFormat ? summary : await formatMd(summary);
     await outputText(formatted + "\n");
-    process.exit(0);
+    exitProcess(0);
   } else if (listOnly) {
     const languages = await listLanguages(videoId);
     printLanguages(languages);
-    process.exit(0);
+    exitProcess(0);
+  }
+
+  if (format === "markdown") {
+    const transcribeCmd = resolveTranscribeCmd(config);
+    if (!transcribeCmd) {
+      console.error(
+        "Error: no command configured for transcribe. Set [transcribe].command, [ai].command, or [summarize].command in config.",
+      );
+      exitProcess(1);
+    }
+
+    const cacheOpts = { lang, mode: "transcribe", noDecode };
+    const dir = cacheDir(videoId, cacheOpts);
+    let segments: TranscriptSegment[] | null = null;
+    let md: string | null = null;
+
+    startTimer();
+
+    let cachedInfo: string | null = null;
+
+    if (!noCache) {
+      const cachedSegments = await readCache(dir, "transcript.json");
+      const cachedMd = await readCache(dir, "transcript.md");
+      cachedInfo = await readCache(dir, "info.json");
+      if (cachedSegments && cachedMd) {
+        info("Transcript cached");
+        debug("Cache hit:", dir);
+        segments = JSON.parse(cachedSegments);
+        md = cachedMd;
+      } else {
+        debug("Cache miss:", dir);
+      }
+    } else {
+      debug("Cache skipped (--no-cache)");
+    }
+
+    const prompt = resolveTranscribePrompt(config) ?? "";
+    if (!prompt) {
+      console.error(
+        "Error: no prompt configured. Set a prompt in the [transcribe] or [summarize] section of your config.",
+      );
+      exitProcess(1);
+    }
+
+    if (!segments) {
+      info("Fetching transcript...");
+      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;
+      const infoJson = JSON.stringify({
+        title: result.videoDetails.title,
+        channel: result.videoDetails.author,
+        description: result.videoDetails.description,
+      });
+      cachedInfo = infoJson;
+      const chapterValue = formatChaptersAsJson(extractChapters(result.videoDetails.description));
+      const truncatedInfo = JSON.stringify({
+        title: result.videoDetails.title,
+        channel: result.videoDetails.author,
+        description: result.videoDetails.description.slice(0, 1000),
+      });
+      const transcriptText = toText(segments, !noDecode);
+      const structuredContent = `INFO:\n${truncatedInfo}\n\nTIMESTAMPS:\n${chapterValue}\n\nTEXT:\n${transcriptText}`;
+
+      if (dryRun) {
+        await outputText(`${prompt}\n\n${structuredContent}\n`);
+        exitProcess(0);
+      }
+
+      info(`Transcript: ${segments.length} segments`);
+      await writeCache(dir, "transcript.json", JSON.stringify(segments));
+      await writeCache(dir, "info.json", infoJson);
+      await writeCache(dir, "chapters.json", chapterValue);
+      debug("Cache written: transcript.json, info.json, chapters.json");
+
+      if (!md) {
+        info(`Transcribing...`);
+        md = await summarize({
+          prompt,
+          command: transcribeCmd,
+          transcript: structuredContent,
+          cwd: dir,
+        });
+        info("Transcription ready");
+        await writeCache(dir, "transcript.md", md);
+        debug("Cache written: transcript.md");
+      }
+    } else {
+      let chapterValue: string;
+      if (!cachedInfo) {
+        debug("Cache missing info.json, re-fetching video details");
+        const fallbackOpts = lang
+          ? { lang, videoDetails: true as const }
+          : { videoDetails: true as const };
+        const fallbackResult = (await fetchTranscript(videoId, fallbackOpts)) as {
+          videoDetails: VideoDetails;
+          segments: TranscriptSegment[];
+        };
+        cachedInfo = JSON.stringify({
+          title: fallbackResult.videoDetails.title,
+          channel: fallbackResult.videoDetails.author,
+          description: fallbackResult.videoDetails.description,
+        });
+        await writeCache(dir, "info.json", cachedInfo);
+        chapterValue = formatChaptersAsJson(
+          extractChapters(fallbackResult.videoDetails.description),
+        );
+        await writeCache(dir, "chapters.json", chapterValue);
+        debug("Cache written: info.json, chapters.json");
+      } else {
+        const cachedChapters = await readCache(dir, "chapters.json");
+        chapterValue = cachedChapters ?? "not available";
+      }
+      const transcriptText = toText(segments, !noDecode);
+      const cachedInfoObj = JSON.parse(cachedInfo);
+      const truncatedInfo = JSON.stringify({
+        title: cachedInfoObj.title,
+        channel: cachedInfoObj.channel,
+        description: cachedInfoObj.description.slice(0, 1000),
+      });
+      const structuredContent = `INFO:\n${truncatedInfo}\n\nTIMESTAMPS:\n${chapterValue}\n\nTEXT:\n${transcriptText}`;
+
+      if (!md) {
+        info(`Transcribing...`);
+        md = await summarize({
+          prompt,
+          command: transcribeCmd,
+          transcript: structuredContent,
+          cwd: dir,
+        });
+        info("Transcription ready");
+        await writeCache(dir, "transcript.md", md);
+        debug("Cache written: transcript.md");
+      }
+    }
+
+    const formatted = noFormat ? md : await formatMd(md);
+    await outputText(formatted + "\n");
+    exitProcess(0);
   }
 
   const decode = !noDecode;
@@ -420,6 +660,14 @@ try {
     debug("Cache skipped (--no-cache)");
   }
 
+  const prompt = resolveTranscribePrompt(config) ?? "";
+  if (!prompt) {
+    console.error(
+      "Error: no prompt configured. Set a prompt in the [transcribe] or [summarize] section of your config.",
+    );
+    exitProcess(1);
+  }
+
   if (!segments) {
     info("Fetching transcript...");
     if (showDetails && !outputJson) {
@@ -463,8 +711,9 @@ try {
 
     await outputText(output);
   }
+  exitProcess(0);
 } catch (err: unknown) {
   const message = err instanceof Error ? err.message : String(err);
   console.error(`Error: ${message}`);
-  process.exit(1);
+  exitProcess(1);
 }

package/src/pager.test.ts

@@ -58,7 +58,7 @@ describe("detectPager", () => {
     // In CI or minimal environments, no pagers may be installed
     // If a pager IS found, it should be one of the expected ones
     if (pager !== null) {
-      const known = ["bat -lmd", "glow", "mdcat -l -p", "less"];
+      const known = ["bat -lmd --style plain", "glow -p", "mdcat -l -p", "less"];
       expect(known).toContain(pager);
     }
   });

package/src/pager.ts

@@ -15,8 +15,8 @@ export function detectPager(cfgPager?: string): string | null {
 
   if (cfgPager !== undefined && cfgPager !== "" && cfgPager !== "auto") return cfgPager;
 
-  if (hasCommand("bat")) return "bat -lmd";
-  if (hasCommand("glow")) return "glow";
+  if (hasCommand("bat")) return "bat -lmd --style plain";
+  if (hasCommand("glow")) return "glow -p";
   if (hasCommand("mdcat")) return "mdcat -l -p";
   if (hasCommand("less")) return "less";
   return null;

package/src/summarize.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { summarize } from "./summarize";
+import type { ExecuteCommand } from "./summarize";
 
 describe("summarize", () => {
   test("rejects when command only echoes input", async () => {
@@ -19,14 +20,13 @@ describe("summarize", () => {
         command: "cat",
         transcript: "Just the transcript.",
       }),
-    ).rejects.toThrow("Summarization command returned no meaningful output");
+    ).rejects.toThrow("No prompt configured");
   });
 
   test("preserves response text beyond the input", async () => {
-    const cmd = "sh -c 'cat -; echo \"RESPONSE\"'";
     const result = await summarize({
       prompt: "Summarize:",
-      command: cmd,
+      command: "sh -c 'cat -; echo \"RESPONSE\"'",
       transcript: "Transcript text.",
     });
     expect(result).toBe("RESPONSE");
@@ -41,4 +41,75 @@ describe("summarize", () => {
       }),
     ).rejects.toThrow(/exited with code 1/);
   });
+
+  test("prompt text is included in stdin sent to the command", async () => {
+    let capturedInput = "";
+    const exec: ExecuteCommand = async (_cmd, input) => {
+      capturedInput = input;
+      return "done";
+    };
+    await summarize({ prompt: "TEST_PROMPT", command: "any", transcript: "SOME_TEXT" }, exec);
+    expect(capturedInput).toContain("TEST_PROMPT");
+    expect(capturedInput).toContain("\n\n");
+    expect(capturedInput).toContain("SOME_TEXT");
+  });
+
+  test("transcript text is included in stdin along with the prompt", async () => {
+    let capturedInput = "";
+    const exec: ExecuteCommand = async (_cmd, input) => {
+      capturedInput = input;
+      return "done";
+    };
+    await summarize({ prompt: "PROMPT:", command: "any", transcript: "SAMPLE_TRANSCRIPT" }, exec);
+    expect(capturedInput).toContain("SAMPLE_TRANSCRIPT");
+  });
+
+  test("prompt appears before transcript text in stdin", async () => {
+    let capturedInput = "";
+    const exec: ExecuteCommand = async (_cmd, input) => {
+      capturedInput = input;
+      return "done";
+    };
+    await summarize({ prompt: "FIRST_LINE", command: "any", transcript: "SECOND_LINE" }, exec);
+    const lines = capturedInput.split("\n");
+    expect(lines[0]).toBe("FIRST_LINE");
+    expect(lines[lines.length - 1]).toBe("SECOND_LINE");
+  });
+
+  test("rejects when prompt is empty string", async () => {
+    const exec: ExecuteCommand = async () => "some output";
+    await expect(
+      summarize({ prompt: "", command: "any", transcript: "text" }, exec),
+    ).rejects.toThrow("No prompt configured");
+  });
+
+  test("execCommand receives the correct content via stdin", async () => {
+    const exec: ExecuteCommand = async (_cmd, input) => {
+      expect(input).toBe("My Prompt\n\nMy Transcript");
+      return "result";
+    };
+    const result = await summarize(
+      { prompt: "My Prompt", command: "any", transcript: "My Transcript" },
+      exec,
+    );
+    expect(result).toBe("result");
+  });
+
+  test("strips echoed input from command output", async () => {
+    // Simulate command that echoes the full input then adds response
+    const exec: ExecuteCommand = async (_cmd, input) => {
+      return `${input}EXTRA_RESPONSE`;
+    };
+    const result = await summarize({ prompt: "P", command: "any", transcript: "T" }, exec);
+    expect(result).toBe("EXTRA_RESPONSE");
+  });
+
+  test("throws when execCommand returns only the input", async () => {
+    const exec: ExecuteCommand = async (_cmd, input) => {
+      return `${input}\n`;
+    };
+    await expect(summarize({ prompt: "P", command: "any", transcript: "T" }, exec)).rejects.toThrow(
+      "Summarization command returned no meaningful output",
+    );
+  });
 });

package/src/summarize.ts

@@ -7,7 +7,13 @@ export interface SummarizeOptions {
   cwd?: string;
 }
 
-function executeCommand(command: string, input: string, cwd?: string): Promise<string> {
+export type ExecuteCommand = (command: string, input: string, cwd?: string) => Promise<string>;
+
+export const defaultExecuteCommand: ExecuteCommand = (
+  command: string,
+  input: string,
+  cwd?: string,
+) => {
   return new Promise((resolve, reject) => {
     const proc = spawn(command, [], { shell: true, stdio: "pipe", cwd });
 
@@ -32,12 +38,20 @@ function executeCommand(command: string, input: string, cwd?: string): Promise<s
     proc.stdin!.write(input);
     proc.stdin!.end();
   });
-}
+};
 
-export async function summarize(options: SummarizeOptions): Promise<string> {
+export async function summarize(
+  options: SummarizeOptions,
+  execCommand: ExecuteCommand = defaultExecuteCommand,
+): Promise<string> {
   const { prompt, command, transcript, cwd } = options;
+
+  if (!prompt) {
+    throw new Error("No prompt configured. A prompt is required in the config.");
+  }
+
   const fullPrompt = `${prompt}\n\n${transcript}`;
-  const output = await executeCommand(command, fullPrompt, cwd);
+  const output = await execCommand(command, fullPrompt, cwd);
 
   const cleaned = output.startsWith(fullPrompt)
     ? output.slice(fullPrompt.length).replace(/\n+$/, "")

package/src/version-check.ts

@@ -0,0 +1,32 @@
+import { debug } from "./debug";
+import pkg from "../package.json";
+
+const TIMEOUT_MS = 3000;
+
+const registryUrl = `https://registry.npmjs.org/${pkg.name}/latest`;
+
+export async function checkVersion(): Promise<string | null> {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    const res = await fetch(registryUrl, { signal: controller.signal });
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      debug("Version check failed: HTTP", res.status);
+      return null;
+    }
+
+    const data = (await res.json()) as { version?: string };
+    if (!data.version) {
+      debug("Version check: no version field in response");
+      return null;
+    }
+
+    return data.version;
+  } catch (err) {
+    debug("Version check error:", err instanceof Error ? err.message : String(err));
+    return null;
+  }
+}