@tacone/prosey 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacone/prosey",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Download YouTube video transcripts from the CLI",
   "module": "src/index.ts",
   "type": "module",
@@ -51,14 +51,14 @@
   "devDependencies": {
     "@types/bun": "latest",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.7",
-    "prettier": "^3.8.4"
+    "lint-staged": "^17.0.7"
   },
   "peerDependencies": {
     "typescript": "^5"
   },
   "dependencies": {
     "js-toml": "^1.1.2",
+    "prettier": "^3.8.4",
     "youtube-transcript-plus": "^2.0.0"
   }
 }

package/src/config-command.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test, afterEach } from "bun:test";
+import { $ } from "bun";
+import { rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+
+const testConfigPath = "/tmp/prosey-test-config.toml";
+
+afterEach(async () => {
+  try {
+    await rm(testConfigPath);
+  } catch {}
+  delete process.env.PROSEY_CONFIG_PATH;
+});
+
+describe("config subcommand", () => {
+  test("prints config path when EDITOR is not set", async () => {
+    delete process.env.EDITOR;
+    process.env.PROSEY_CONFIG_PATH = testConfigPath;
+
+    const { stdout, exitCode } = await $`bin/prosey config`.quiet();
+
+    expect(exitCode).toBe(0);
+    expect(stdout.toString().trim()).toBe(`Config file: ${testConfigPath}`);
+  });
+
+  test("creates config file when missing", async () => {
+    delete process.env.EDITOR;
+    process.env.PROSEY_CONFIG_PATH = testConfigPath;
+
+    expect(existsSync(testConfigPath)).toBe(false);
+    await $`bin/prosey config`.quiet();
+    expect(existsSync(testConfigPath)).toBe(true);
+  });
+
+  test("does not require a video ID", async () => {
+    delete process.env.EDITOR;
+    process.env.PROSEY_CONFIG_PATH = testConfigPath;
+
+    const { exitCode } = await $`bin/prosey config`.quiet();
+    expect(exitCode).toBe(0);
+  });
+
+  test("exits with code 0 after spawning editor", async () => {
+    process.env.EDITOR = "cat";
+    process.env.PROSEY_CONFIG_PATH = testConfigPath;
+
+    const { exitCode } = await $`bin/prosey config`.quiet();
+    expect(exitCode).toBe(0);
+  });
+});

package/src/config.test.ts

@@ -54,7 +54,7 @@ describe("loadConfig", () => {
 
     const content = await readFile(tmpConfig, "utf8");
     expect(content).toContain("[summarize]");
-    expect(content).toContain('command = "opencode run"');
+    expect(content).toContain("command = ");
   });
 
   test("reads existing config file", async () => {
@@ -63,7 +63,7 @@ describe("loadConfig", () => {
     await loadConfig();
     const config = await loadConfig();
     expect(config.summarize?.prompt).toBeString();
-    expect(config.summarize?.command).toBe("opencode run");
+    expect(config.summarize?.command).toBeString();
   });
 
   test("handles invalid TOML gracefully", async () => {
@@ -93,6 +93,6 @@ describe("resetConfig", () => {
 
     const content = await readFile(tmpConfig, "utf8");
     expect(content).toContain("[summarize]");
-    expect(content).toContain('command = "opencode run"');
+    expect(content).toContain("command = ");
   });
 });

package/src/config.ts

@@ -6,6 +6,8 @@ import { fileURLToPath } from "node:url";
 import { load } from "js-toml";
 
 export interface ProseyConfig {
+  pager?: string;
+  hints?: boolean;
   summarize?: {
     prompt?: string;
     command?: string;
@@ -15,6 +17,16 @@ export interface ProseyConfig {
 const FALLBACK_CONFIG_TOML = `# Default prosey configuration
 # Created automatically on first run. Edit as needed.
 
+# Pager command for transcript and summary output.
+# Defaults to "auto": bat -lmd → glow → 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 for missing tools (e.g. markdown highlighter).
+# 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.
 # Customize this to change how transcripts are summarized.

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 → glow → 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 for missing tools (e.g. markdown highlighter).
+# 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.
@@ -12,5 +22,18 @@ 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_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,8 +12,8 @@ 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 pkg from "../package.json";
+import prettier from "prettier";
 
 const NAME = "prosey";
 const VERSION = pkg.version;
@@ -20,12 +24,14 @@ function help(): string {
 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
@@ -42,7 +48,13 @@ Options:
   --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.
+  --no-format            Skip prettier formatting.
+  --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.
 
@@ -120,6 +132,50 @@ function printLanguages(languages: CaptionTrackInfo[]): void {
   console.log(`Available transcripts (${languages.length}):\n${rows.join("\n")}`);
 }
 
+async function formatMd(text: string): Promise<string> {
+  try {
+    return await prettier.format(text, { parser: "markdown" });
+  } catch {
+    return text;
+  }
+}
+
+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")) {
@@ -141,7 +197,7 @@ if (args.includes("--reset-config")) {
 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);
@@ -156,7 +212,10 @@ let outputJson = false;
 let noDecode = false;
 let showDetails = true;
 let noCache = false;
-let debugMode = false;
+let noFormat = false;
+let usePager = true;
+let useHints = true;
+let logLevel: LogLevel = "normal";
 
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
@@ -187,8 +246,20 @@ for (let i = 0; i < args.length; i++) {
     showDetails = false;
   } else if (arg === "--no-cache") {
     noCache = true;
-  } else if (arg === "--debug") {
-    debugMode = true;
+  } else if (arg === "--no-format") {
+    noFormat = 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("-")) {
@@ -199,6 +270,21 @@ for (let i = 0; i < args.length; i++) {
   }
 }
 
+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}`);
+  }
+  process.exit(0);
+}
+
 if (!videoId) {
   console.error("Error: missing video URL or ID");
   console.log(help());
@@ -214,7 +300,28 @@ if (!extracted) {
 
 videoId = extracted;
 
-if (debugMode) enableDebug();
+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" || pagerCmd === "glow" || pagerCmd === "mdcat -l -p";
+  if (!hasMarkdownPager) {
+    hint("Tip: install a markdown highlighter for better output (e.g. bat, glow, mdcat)");
+  }
+}
+
 debug("Config file:", configPath());
 debug("Video ID:", videoId);
 debug("Mode:", mode);
@@ -242,10 +349,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;
@@ -257,9 +367,9 @@ 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");
     }
@@ -268,23 +378,20 @@ try {
     const transcriptText = toText(segments, !noDecode);
 
     if (!summary) {
-      debug("Running command:", config.summarize.command);
+      info(`Summarizing...`);
       summary = await summarize({
         prompt,
         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");
     }
 
-    if (outputPath) {
-      await writeFile(outputPath, summary, "utf8");
-    } else {
-      console.log(summary);
-    }
+    const formatted = noFormat ? summary : await formatMd(summary);
+    await outputText(formatted + "\n");
     process.exit(0);
   } else if (listOnly) {
     const languages = await listLanguages(videoId);
@@ -298,9 +405,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 {
@@ -311,7 +421,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 {
@@ -323,6 +433,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));
   }
 
@@ -342,11 +453,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"
@@ -354,11 +461,7 @@ try {
         ? formatWithTimestamps(segments, decode) + "\n"
         : toText(segments, decode) + "\n";
 
-    if (outputPath) {
-      await writeFile(outputPath, output, "utf8");
-    } else {
-      console.log(output);
-    }
+    await outputText(output);
   }
 } catch (err: unknown) {
   const message = err instanceof Error ? err.message : String(err);