@tacone/prosey 0.2.3 → 0.2.6

package/src/debug.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test, beforeEach, spyOn } from "bun:test";
+import { setLevel, info, debug, startTimer, resetTimer } from "./debug";
+import type { LogLevel } from "./debug";
+
+beforeEach(() => {
+  setLevel("normal");
+  resetTimer();
+});
+
+describe("setLevel", () => {
+  test("info outputs at normal level", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    setLevel("normal");
+    info("hello");
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  test("info suppressed at quiet level", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    setLevel("quiet");
+    info("hello");
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  test("info outputs at verbose level", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    setLevel("verbose");
+    info("hello");
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  test("debug suppressed at normal level", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    setLevel("normal");
+    debug("detail");
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  test("debug outputs at verbose level", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    setLevel("verbose");
+    debug("detail");
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  test("debug suppressed at quiet level", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    setLevel("quiet");
+    debug("detail");
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("info format", () => {
+  test("includes timestamp and message", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    info("test message");
+    expect(spy.mock.calls[0]?.length).toBeGreaterThanOrEqual(3);
+    spy.mockRestore();
+  });
+});
+
+describe("startTimer", () => {
+  test("resets elapsed time on next info call", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    startTimer();
+    info("after reset");
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("resetTimer", () => {
+  test("resets elapsed time on next info call", () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    resetTimer();
+    info("after reset");
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});

package/src/debug.ts

@@ -1,13 +1,55 @@
 const GRAY = "\x1b[90m";
 const RESET = "\x1b[0m";
 
-let enabled = false;
+export type LogLevel = "quiet" | "normal" | "verbose";
 
-export function enableDebug(): void {
-  enabled = true;
+let level: LogLevel = "normal";
+
+export function setLevel(l: LogLevel): void {
+  level = l;
+}
+
+let lastTime = performance.now();
+let resumed = false;
+
+function stamp(): string {
+  const now = performance.now();
+  if (resumed) {
+    lastTime = now;
+    resumed = false;
+  }
+  const elapsed = now - lastTime;
+  lastTime = now;
+  const text = elapsed < 1000 ? `${elapsed.toFixed(0)}ms` : `${(elapsed / 1000).toFixed(1)}s`;
+  return text.padStart(5);
+}
+
+const INFO_BEFORE = "\x1b[0m\x1b[2m\x1b[1m";
+const INFO_AFTER = "\x1b[0m";
+
+export function info(...args: unknown[]): void {
+  if (level === "quiet") return;
+  console.error(INFO_BEFORE, `[${stamp()}]`, ...args, INFO_AFTER);
 }
 
 export function debug(...args: unknown[]): void {
-  if (!enabled) return;
-  console.error(GRAY, ...args, RESET);
+  if (level !== "verbose") return;
+  console.error(GRAY, `[${stamp()}]`, ...args, RESET);
+}
+
+export function startTimer(): void {
+  resumed = true;
+}
+
+export function resetTimer(): void {
+  lastTime = performance.now();
+  resumed = false;
+}
+
+const YELLOW = "\x1b[33m";
+
+export function hint(message: string): void {
+  console.error(
+    YELLOW + message + RESET + " " + GRAY + "[use prosey config to disable hints]" + RESET,
+  );
 }

package/src/default-config.toml

@@ -1,6 +1,16 @@
 # Default prosey configuration
 # Created automatically on first run. Edit as needed.
 
+# Pager command for transcript and summary output.
+# Defaults to "auto": bat -lmd --style plain → glow -p → mdcat -l -p → less
+# Set to a custom command (e.g. "less -R") to override.
+# Can also be set via the PROSEY_PAGER env var (takes precedence).
+pager = "auto"
+
+# Show hints when available
+# Can also be set via PROSEY_HINTS env var (yes, no, 1, 0, true, false).
+hints = true
+
 [summarize]
 
 # Prompt sent to the command via stdin.
@@ -11,6 +21,13 @@ 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.
-
+# The transcript will be appended to the prompt automatically.
+#
+# Examples:
+#
+#   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
+#   claude --permission-mode plan --print  --read-only
+#   copilot -s --deny-all-tools --read-only
+#   codex --sandbox read-only --read-only
+#
 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/format.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import type { TranscriptSegment } from "youtube-transcript-plus";
-import { formatTime, decodeEntities, formatWithTimestamps, toText, toJSON } from "./format";
+import {
+  formatTime,
+  formatDuration,
+  decodeEntities,
+  formatWithTimestamps,
+  toText,
+  toJSON,
+} from "./format";
 
 const segments: TranscriptSegment[] = [
   { text: "Hello world", offset: 1.5, duration: 2.0, lang: "en" },
@@ -17,6 +24,15 @@ describe("formatTime", () => {
   test("fractional truncated", () => expect(formatTime(90.7)).toBe("01:30"));
 });
 
+describe("formatDuration", () => {
+  test("zero", () => expect(formatDuration(0)).toBe("0:00"));
+  test("seconds only", () => expect(formatDuration(45)).toBe("0:45"));
+  test("minute boundary", () => expect(formatDuration(60)).toBe("1:00"));
+  test("minutes only", () => expect(formatDuration(185)).toBe("3:05"));
+  test("hour boundary", () => expect(formatDuration(3600)).toBe("1:00:00"));
+  test("hours and minutes", () => expect(formatDuration(3661)).toBe("1:01:01"));
+});
+
 describe("decodeEntities", () => {
   test("plain text unchanged", () => expect(decodeEntities("hello")).toBe("hello"));
   test("apostrophe", () => expect(decodeEntities("'")).toBe("'"));

package/src/index.ts

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 
+import { setLevel, info, debug, startTimer, resetTimer, hint } from "./debug";
+import type { LogLevel } from "./debug";
+import { spawn } from "node:child_process";
 import { writeFile } from "node:fs/promises";
+import { detectPager } from "./pager";
 import { fetchTranscript, listLanguages } from "youtube-transcript-plus";
 import type { CaptionTrackInfo, VideoDetails, TranscriptSegment } from "youtube-transcript-plus";
 import { formatWithTimestamps, toText, toJSON, formatDuration, decodeEntities } from "./format";
@@ -8,25 +12,41 @@ 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";
+import { checkVersion } from "./version-check";
 import pkg from "../package.json";
 import prettier from "prettier";
 
 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} info [options] <video-url-or-id>
        ${NAME} summarize [options] <video-url-or-id>
+       ${NAME} config
 
 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]
+  config                Open config file in \$EDITOR
 
 Arguments:
   video-url-or-id        YouTube URL (full or short) or bare video ID
@@ -44,7 +64,12 @@ Options:
   --reset-config         Reset config file to defaults and exit.
   --no-cache             Skip cache and overwrite cache files.
   --no-format            Skip prettier formatting.
-  --debug                Print debug information to stderr.
+  --no-pager             Disable pager for stdout output.
+  --pager                Use pager for stdout output (default).
+  --no-hints             Disable hints.
+  --hints                Show hints (default).
+  -q, --quiet            Suppress all stderr logging.
+  -v, --verbose          Print debug information to stderr.
   --help                 Show this help message.
   --version              Show version.
 
@@ -130,28 +155,64 @@ async function formatMd(text: string): Promise<string> {
   }
 }
 
+async function outputText(text: string): Promise<void> {
+  if (outputPath) {
+    await writeFile(outputPath, text, "utf8");
+    return;
+  }
+
+  if (!pagerCmd || !process.stdout.isTTY) {
+    process.stdout.write(text);
+    return;
+  }
+
+  const parts = pagerCmd.split(/\s+/);
+  const proc = spawn(parts[0]!, parts.slice(1), {
+    stdio: ["pipe", "inherit", "inherit"],
+  }) as import("node:child_process").ChildProcess;
+
+  await new Promise<void>((resolve) => {
+    let done = false;
+    proc.on("error", () => {
+      if (done) return;
+      done = true;
+      process.stdout.write(text);
+      resolve();
+    });
+    proc.on("exit", () => {
+      if (done) return;
+      done = true;
+      resolve();
+    });
+    proc.stdin!.write(text);
+    proc.stdin!.end();
+  });
+}
+
+let pagerCmd: string | null = null;
+
 const args = process.argv.slice(2);
 
 if (args.length === 0 || 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");
+const subcmdIndex = args.findIndex((a) => a === "info" || a === "summarize" || a === "config");
 if (subcmdIndex !== -1) {
   mode = args[subcmdIndex]!;
   args.splice(subcmdIndex, 1);
@@ -167,7 +228,9 @@ let noDecode = false;
 let showDetails = true;
 let noCache = false;
 let noFormat = false;
-let debugMode = false;
+let usePager = true;
+let useHints = true;
+let logLevel: LogLevel = "normal";
 
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
@@ -176,7 +239,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;
@@ -186,7 +249,7 @@ 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;
@@ -200,39 +263,88 @@ for (let i = 0; i < args.length; i++) {
     noCache = true;
   } else if (arg === "--no-format") {
     noFormat = true;
-  } else if (arg === "--debug") {
-    debugMode = true;
+  } else if (arg === "--no-pager") {
+    usePager = false;
+  } else if (arg === "--pager") {
+    usePager = true;
+  } else if (arg === "--no-hints") {
+    useHints = false;
+  } else if (arg === "--hints") {
+    useHints = true;
+  } else if (arg === "--quiet" || arg === "-q") {
+    logLevel = "quiet";
+  } else if (arg === "--verbose" || arg === "-v") {
+    logLevel = "verbose";
   } else if (arg === "--no-decode-entities") {
     noDecode = true;
   } else if (arg.startsWith("-")) {
     console.error(`Unknown option: ${arg}`);
-    process.exit(1);
+    exitProcess(1);
   } else {
     videoId = arg;
   }
 }
 
+if (mode === "config") {
+  const path = configPath();
+  const editor = process.env.EDITOR;
+  if (editor) {
+    await new Promise<void>((resolve) => {
+      const proc = spawn(editor, [path], { stdio: "inherit" });
+      proc.on("exit", () => resolve());
+      proc.on("error", () => resolve());
+    });
+  } else {
+    console.log(`Config file: ${path}`);
+  }
+  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();
+pagerCmd = usePager ? detectPager(config.pager) : null;
+debug("Pager:", pagerCmd ?? "none");
+
+{
+  const envHints = process.env.PROSEY_HINTS;
+  if (envHints !== undefined) {
+    useHints = envHints === "yes" || envHints === "1" || envHints === "true";
+  } else if (config.hints !== undefined) {
+    useHints = config.hints;
+  }
+}
+
+if (useHints) {
+  const hasMarkdownPager =
+    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)");
+  }
+}
 
-if (debugMode) enableDebug();
 debug("Config file:", configPath());
 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))]);
+
 try {
   if (mode === "info") {
     const result = await fetchTranscript(videoId, { videoDetails: true, lang } as any);
@@ -241,13 +353,13 @@ 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);
+      exitProcess(1);
     }
 
     const cacheOpts = { lang, mode: "summarize", noDecode };
@@ -255,10 +367,13 @@ try {
     let segments: TranscriptSegment[] | null = null;
     let summary: string | null = null;
 
+    startTimer();
+
     if (!noCache) {
       const cachedSegments = await readCache(dir, "transcript.json");
       const cachedSummary = await readCache(dir, "summary.md");
       if (cachedSegments && cachedSummary) {
+        info("Transcript cached");
         debug("Cache hit:", dir);
         segments = JSON.parse(cachedSegments);
         summary = cachedSummary;
@@ -270,41 +385,36 @@ try {
     }
 
     if (!segments) {
-      debug("Fetching transcript...");
+      info("Fetching transcript...");
       segments = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
-      debug(`Transcript fetched: ${segments.length} segments`);
+      info(`Transcript: ${segments.length} segments`);
       await writeCache(dir, "transcript.json", JSON.stringify(segments));
       debug("Cache written: transcript.json");
     }
 
-    const prompt = config.summarize.prompt ?? "";
+    const prompt = config.summarize!.prompt ?? "";
     const transcriptText = toText(segments, !noDecode);
 
     if (!summary) {
-      debug("Running command:", config.summarize.command);
+      info(`Summarizing...`);
       summary = await summarize({
         prompt,
-        command: config.summarize.command,
+        command: config.summarize!.command!,
         transcript: transcriptText,
         cwd: dir,
       });
-      debug("Command exit: 0");
+      info("Summary ready");
       await writeCache(dir, "summary.md", summary);
       debug("Cache written: summary.md");
     }
 
     const formatted = noFormat ? summary : await formatMd(summary);
-
-    if (outputPath) {
-      await writeFile(outputPath, formatted, "utf8");
-    } else {
-      console.log(formatted);
-    }
-    process.exit(0);
+    await outputText(formatted + "\n");
+    exitProcess(0);
   } else if (listOnly) {
     const languages = await listLanguages(videoId);
     printLanguages(languages);
-    process.exit(0);
+    exitProcess(0);
   }
 
   const decode = !noDecode;
@@ -313,9 +423,12 @@ try {
   let segments: TranscriptSegment[] | null = null;
   let videoDetailsCache: VideoDetails | null = null;
 
+  startTimer();
+
   if (!noCache) {
     const cached = await readCache(dir, "transcript.json");
     if (cached) {
+      info("Transcript cached");
       debug("Cache hit:", dir);
       segments = JSON.parse(cached);
     } else {
@@ -326,7 +439,7 @@ try {
   }
 
   if (!segments) {
-    debug("Fetching transcript...");
+    info("Fetching transcript...");
     if (showDetails && !outputJson) {
       const opts = lang ? { lang, videoDetails: true as const } : { videoDetails: true as const };
       const result = (await fetchTranscript(videoId, opts)) as {
@@ -338,6 +451,7 @@ try {
     } else {
       segments = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
     }
+    info(`Transcript: ${segments.length} segments`);
     await writeCache(dir, "transcript.json", JSON.stringify(segments));
   }
 
@@ -357,11 +471,7 @@ try {
       : toText(segments, decode);
     const output = detailsBlock + "\n\n\n" + transcriptText + "\n";
 
-    if (outputPath) {
-      await writeFile(outputPath, output, "utf8");
-    } else {
-      console.log(output);
-    }
+    await outputText(output);
   } else {
     const output = outputJson
       ? toJSON(segments, decode) + "\n"
@@ -369,14 +479,11 @@ try {
         ? formatWithTimestamps(segments, decode) + "\n"
         : toText(segments, decode) + "\n";
 
-    if (outputPath) {
-      await writeFile(outputPath, output, "utf8");
-    } else {
-      console.log(output);
-    }
+    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

@@ -0,0 +1,65 @@
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { hasCommand, detectPager } from "./pager";
+
+const ORIGINAL_PROSEY_PAGER = process.env.PROSEY_PAGER;
+
+beforeEach(() => {
+  delete process.env.PROSEY_PAGER;
+});
+
+afterEach(() => {
+  if (ORIGINAL_PROSEY_PAGER !== undefined) {
+    process.env.PROSEY_PAGER = ORIGINAL_PROSEY_PAGER;
+  } else {
+    delete process.env.PROSEY_PAGER;
+  }
+});
+
+describe("hasCommand", () => {
+  test("returns true for existing command", () => {
+    expect(hasCommand("sh")).toBe(true);
+  });
+
+  test("returns false for nonexistent command", () => {
+    expect(hasCommand("nonexistent-cmd-12345")).toBe(false);
+  });
+});
+
+describe("detectPager", () => {
+  test("uses PROSEY_PAGER env var", () => {
+    process.env.PROSEY_PAGER = "custom-pager";
+    expect(detectPager()).toBe("custom-pager");
+  });
+
+  test("env var takes precedence over config pager", () => {
+    process.env.PROSEY_PAGER = "env-pager";
+    expect(detectPager("cfg-pager")).toBe("env-pager");
+  });
+
+  test('"auto" env var falls through to config', () => {
+    process.env.PROSEY_PAGER = "auto";
+    expect(detectPager("cfg-pager")).toBe("cfg-pager");
+  });
+
+  test("empty env var falls through to config", () => {
+    process.env.PROSEY_PAGER = "";
+    expect(detectPager("cfg-pager")).toBe("cfg-pager");
+  });
+
+  test('"auto" config falls through to auto-detection', () => {
+    process.env.PROSEY_PAGER = "auto";
+    const pager = detectPager("auto");
+    // Falls through to auto-detect: one of bat/glow/mdcat/less or null
+    expect(pager === null || typeof pager === "string").toBe(true);
+  });
+
+  test("returns null when no pager is configured or available", () => {
+    const pager = 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 --style plain", "glow -p", "mdcat -l -p", "less"];
+      expect(known).toContain(pager);
+    }
+  });
+});