@tacone/prosey 0.2.3 → 0.2.4

package/README.md

@@ -4,20 +4,43 @@
 
 You can read, skim, search, copy, and manipulate the text using the tools you love the most.
 
-## Usage
+## Features
+
+| Feature                              | Description                                                                                     |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| **📋 Transcript download** | Fetch YouTube transcripts as plain text or JSON                                                 |
+| **🤖 AI summarization**    | Pipe transcripts to any AI agent (opencode, Claude, Copilot, Codex)                             |
+| **🎨 Smart pager**         | Automatic syntax highlighting if bat, glow or mdcat are installed (or configure your own pager) |
+| **🛠️ Customization**            | Use `prosey config` to access and edit your configuration                                       |
+| **💾 Disk caching**        | Transcripts and summaries cached for instant repeat                                             |
+| **📄 Supported formats**   | Plain text and JSON                                                                             |
+
+## Quickstart
+
+Try it out immediately with npx:
 
 ```bash
 npx @tacone/prosey 771PQEDeRmw
 npx @tacone/prosey https://youtu.be/771PQEDeRmw --lang es -o transcript.txt
-npx @tacone/prosey info 771PQEDeRmw
 ```
 
 ## Install
 
-### Global install (npm)
+Install globally with your favorite package manager:
 
 ```bash
 npm install -g @tacone/prosey
+# or
+yarn global add @tacone/prosey
+# or
+pnpm add -g @tacone/prosey
+# or
+bun install -g @tacone/prosey
+```
+
+Then use it anywhere:
+
+```bash
 prosey 771PQEDeRmw
 ```
 
@@ -43,6 +66,7 @@ Grab a compiled binary from the `dist/` directory (requires no runtime).
 prosey [options] <video-url-or-id>
 prosey info [options] <video-url-or-id>
 prosey summarize [options] <video-url-or-id>
+prosey config
 ```
 
 Pass a full YouTube URL or a bare video ID. The transcript is printed to
@@ -51,35 +75,41 @@ stdout by default, with video details prepended.
 The `summarize` command fetches a transcript, prepends the prompt from the
 `[summarize]` config section, and pipes the result to the configured command.
 
+The `config` command opens your config file in `$EDITOR` for editing. If
+`$EDITOR` is not set, the config file path is printed.
+
 ### Examples
 
 ```bash
 # Basic — plain text with details
-npx @tacone/prosey 771PQEDeRmw
+prosey 771PQEDeRmw
 
 # Specify language
-npx @tacone/prosey https://youtu.be/771PQEDeRmw --lang es
+prosey https://youtu.be/771PQEDeRmw --lang es
 
 # Include timestamps
-npx @tacone/prosey 771PQEDeRmw -t
+prosey 771PQEDeRmw -t
 
 # Save to file
-npx @tacone/prosey 771PQEDeRmw -o transcript.txt
+prosey 771PQEDeRmw -o transcript.txt
 
 # JSON output (timestamps always included)
-npx @tacone/prosey 771PQEDeRmw --json
+prosey 771PQEDeRmw --json
 
 # Transcript only, no video details
-npx @tacone/prosey 771PQEDeRmw --no-details
+prosey 771PQEDeRmw --no-details
 
 # List available transcript languages
-npx @tacone/prosey 771PQEDeRmw --list
+prosey 771PQEDeRmw --list
 
 # Show video metadata
-npx @tacone/prosey info 771PQEDeRmw
+prosey info 771PQEDeRmw
 
 # Summarize via the configured command
-npx @tacone/prosey summarize 771PQEDeRmw
+prosey summarize 771PQEDeRmw
+
+# Edit config in $EDITOR
+prosey config
 ```
 
 ## Options
@@ -95,6 +125,13 @@ npx @tacone/prosey summarize 771PQEDeRmw
 | `--details`             | Prepend video details (title, channel, duration, views, description) to the transcript (default).              |
 | `--no-details`          | Suppress video details, transcript only.                                                                       |
 | `--no-decode-entities`  | Preserve raw HTML entities (e.g. `&#39;`). Decoded by default in text mode.                                    |
+| `--no-cache`            | Skip cache reads and force a fresh fetch.                                                                      |
+| `--no-format`           | Skip prettier markdown formatting on summarize output.                                                         |
+| `-q`, `--quiet`         | Suppress all stderr logging.                                                                                   |
+| `-v`, `--verbose`       | Print debug information to stderr.                                                                             |
+| `--no-pager`            | Disable pager for stdout output (auto-detected by default).                                                    |
+| `--pager`               | Use pager for stdout output (default).                                                                         |
+| `--reset-config`        | Reset config file to defaults and exit.                                                                        |
 | `--help`                | Show help message and exit.                                                                                    |
 | `--version`             | Show version number and exit.                                                                                  |
 
@@ -140,6 +177,15 @@ environment variable to use a custom path.
 The config file is created automatically on first run with default values.
 Use `--reset-config` to restore the defaults at any time.
 
+### `pager`
+
+Pager command for transcript and summary output. Defaults to `"auto"`, which
+detects the first available of: `bat -lmd` → `glow` → `mdcat -l -p` → `less`.
+Set to a custom command (e.g. `"less -R"`) to override. The `PROSEY_PAGER`
+environment variable takes precedence over this setting.
+
+### `[summarize]`
+
 The `[summarize]` section configures the `summarize` command:
 
 | Key       | Description                                      |
@@ -147,6 +193,11 @@ The `[summarize]` section configures the `summarize` command:
 | `prompt`  | Instruction prepended to the transcript          |
 | `command` | Shell command that receives the prompt via stdin |
 
+### `PROSEY_PAGER`
+
+Environment variable to set the pager command. Takes precedence over the
+`pager` config value. Set to `"auto"` or empty to use auto-detection.
+
 ## Cache
 
 Transcripts and summaries are cached to `/tmp/prosey/`. Repeated invocations

package/bin/prosey

@@ -2114,7 +2114,7 @@ var require_symbol_define_to_primitive = __commonJS((exports, module) => {
     var valueOf = SymbolPrototype && SymbolPrototype.valueOf;
     var TO_PRIMITIVE = wellKnownSymbol("toPrimitive");
     if (SymbolPrototype && !SymbolPrototype[TO_PRIMITIVE]) {
-      defineBuiltIn(SymbolPrototype, TO_PRIMITIVE, function(hint) {
+      defineBuiltIn(SymbolPrototype, TO_PRIMITIVE, function(hint2) {
         return call(valueOf, this);
       }, { arity: 1 });
     }
@@ -4397,9 +4397,9 @@ In order to be iterable, non-array objects must have a [Symbol.iterator]() metho
     return global2 ? result || [] : result && result[0];
   };
   XRegExp.matchChain = function(str, chain) {
-    return function recurseChain(values, level) {
-      var item = chain[level].regex ? chain[level] : {
-        regex: chain[level]
+    return function recurseChain(values, level2) {
+      var item = chain[level2].regex ? chain[level2] : {
+        regex: chain[level2]
       };
       var matches = [];
       function addMatch(match) {
@@ -4430,7 +4430,7 @@ In order to be iterable, non-array objects must have a [Symbol.iterator]() metho
       } finally {
         _iterator3.f();
       }
-      return level === chain.length - 1 || !matches.length ? matches : recurseChain(matches, level + 1);
+      return level2 === chain.length - 1 || !matches.length ? matches : recurseChain(matches, level2 + 1);
     }([str], 0);
   };
   XRegExp.replace = function(str, search, replacement, scope) {
@@ -94145,9 +94145,81 @@ ${Me13.join(`
   Y42 = k0(G42);
 });
 
+// src/debug.ts
+var GRAY = "\x1B[90m";
+var RESET = "\x1B[0m";
+var level = "normal";
+function setLevel(l) {
+  level = l;
+}
+var lastTime = performance.now();
+var resumed = false;
+function stamp() {
+  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);
+}
+var INFO_BEFORE = "\x1B[0m\x1B[2m\x1B[1m";
+var INFO_AFTER = "\x1B[0m";
+function info(...args) {
+  if (level === "quiet")
+    return;
+  console.error(INFO_BEFORE, `[${stamp()}]`, ...args, INFO_AFTER);
+}
+function debug(...args) {
+  if (level !== "verbose")
+    return;
+  console.error(GRAY, `[${stamp()}]`, ...args, RESET);
+}
+function startTimer() {
+  resumed = true;
+}
+function resetTimer() {
+  lastTime = performance.now();
+  resumed = false;
+}
+var YELLOW = "\x1B[33m";
+function hint(message) {
+  console.error(YELLOW + message + RESET + " " + GRAY + "[use prosey config to disable hints]" + RESET);
+}
+
 // src/index.ts
+import { spawn as spawn2 } from "node:child_process";
 import { writeFile as writeFile3 } from "node:fs/promises";
 
+// src/pager.ts
+import { execSync } from "node:child_process";
+function hasCommand(cmd) {
+  try {
+    execSync(`command -v ${cmd} 2>/dev/null`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function detectPager(cfgPager) {
+  const env = process.env.PROSEY_PAGER;
+  if (env !== undefined && env !== "" && env !== "auto")
+    return env;
+  if (cfgPager !== undefined && cfgPager !== "" && cfgPager !== "auto")
+    return cfgPager;
+  if (hasCommand("bat"))
+    return "bat -lmd";
+  if (hasCommand("glow"))
+    return "glow";
+  if (hasCommand("mdcat"))
+    return "mdcat -l -p";
+  if (hasCommand("less"))
+    return "less";
+  return null;
+}
+
 // node_modules/youtube-transcript-plus/dist/youtube-transcript-plus.mjs
 function __awaiter(thisArg, _arguments, P, generator) {
   function adopt(value) {
@@ -101530,6 +101602,16 @@ var lt = (r) => {
 var 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.
@@ -101674,23 +101756,10 @@ async function writeCache(dir, filename, data) {
     await mkdir2(dir, { recursive: true });
   await writeFile2(join2(dir, filename), data, "utf8");
 }
-
-// src/debug.ts
-var GRAY = "\x1B[90m";
-var RESET = "\x1B[0m";
-var enabled = false;
-function enableDebug() {
-  enabled = true;
-}
-function debug(...args) {
-  if (!enabled)
-    return;
-  console.error(GRAY, ...args, RESET);
-}
 // package.json
 var package_default = {
   name: "@tacone/prosey",
-  version: "0.2.3",
+  version: "0.2.4",
   description: "Download YouTube video transcripts from the CLI",
   module: "src/index.ts",
   type: "module",
@@ -102266,7 +102335,7 @@ function addAlignmentToDoc(doc, size, tabWidth) {
   assertDoc(doc);
   let aligned = doc;
   if (size > 0) {
-    for (let level = 0;level < Math.floor(size / tabWidth); ++level) {
+    for (let level2 = 0;level2 < Math.floor(size / tabWidth); ++level2) {
       aligned = indent(aligned);
     }
     aligned = align(size % tabWidth, aligned);
@@ -107697,7 +107766,7 @@ var require_partial = __commonJS2({
       match(filepath) {
         const parts = filepath.split("/");
         const levels = parts.length;
-        const patterns = this._storage.filter((info) => !info.complete || info.segments.length > levels);
+        const patterns = this._storage.filter((info2) => !info2.complete || info2.segments.length > levels);
         for (const pattern of patterns) {
           const section = pattern.sections[0];
           if (!pattern.complete && levels > section.length) {
@@ -108269,10 +108338,10 @@ var require_picocolors = __commonJS2({
       } while (~index);
       return result + string.substring(cursor2);
     };
-    var createColors2 = (enabled2 = isColorSupported2) => {
-      let f7 = enabled2 ? formatter : () => String;
+    var createColors2 = (enabled = isColorSupported2) => {
+      let f7 = enabled ? formatter : () => String;
       return {
-        isColorSupported: enabled2,
+        isColorSupported: enabled,
         reset: f7("\x1B[0m", "\x1B[0m"),
         bold: f7("\x1B[1m", "\x1B[22m", "\x1B[22m\x1B[1m"),
         dim: f7("\x1B[2m", "\x1B[22m", "\x1B[22m\x1B[2m"),
@@ -113965,8 +114034,8 @@ function buildDefs(colors) {
 }
 var defsOn = buildDefs((0, import_picocolors4.createColors)(true));
 var defsOff = buildDefs((0, import_picocolors4.createColors)(false));
-function getDefs(enabled2) {
-  return enabled2 ? defsOn : defsOff;
+function getDefs(enabled) {
+  return enabled ? defsOn : defsOff;
 }
 var sometimesKeywords = /* @__PURE__ */ new Set(["as", "async", "from", "get", "of", "set"]);
 var NEWLINE$1 = /\r\n|[\n\r\u2028\u2029]/;
@@ -120299,12 +120368,14 @@ function help() {
 Usage: ${NAME2} [options] <video-url-or-id>
        ${NAME2} info [options] <video-url-or-id>
        ${NAME2} summarize [options] <video-url-or-id>
+       ${NAME2} 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
@@ -120322,7 +120393,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.
 
@@ -120392,6 +120468,39 @@ async function formatMd(text) {
     return text;
   }
 }
+async function outputText(text) {
+  if (outputPath) {
+    await writeFile3(outputPath, text, "utf8");
+    return;
+  }
+  if (!pagerCmd || !process.stdout.isTTY) {
+    process.stdout.write(text);
+    return;
+  }
+  const parts = pagerCmd.split(/\s+/);
+  const proc = spawn2(parts[0], parts.slice(1), {
+    stdio: ["pipe", "inherit", "inherit"]
+  });
+  await new Promise((resolve3) => {
+    let done = false;
+    proc.on("error", () => {
+      if (done)
+        return;
+      done = true;
+      process.stdout.write(text);
+      resolve3();
+    });
+    proc.on("exit", () => {
+      if (done)
+        return;
+      done = true;
+      resolve3();
+    });
+    proc.stdin.write(text);
+    proc.stdin.end();
+  });
+}
+var pagerCmd = null;
 var args = process.argv.slice(2);
 if (args.length === 0 || args.includes("--help")) {
   console.log(help());
@@ -120408,7 +120517,7 @@ if (args.includes("--reset-config")) {
 }
 var config = await loadConfig().catch(() => ({}));
 var mode = "transcript";
-var subcmdIndex = args.findIndex((a5) => a5 === "info" || a5 === "summarize");
+var subcmdIndex = args.findIndex((a5) => a5 === "info" || a5 === "summarize" || a5 === "config");
 if (subcmdIndex !== -1) {
   mode = args[subcmdIndex];
   args.splice(subcmdIndex, 1);
@@ -120423,7 +120532,9 @@ var noDecode = false;
 var showDetails = true;
 var noCache = false;
 var noFormat = false;
-var debugMode = false;
+var usePager = true;
+var useHints = true;
+var logLevel = "normal";
 for (let i = 0;i < args.length; i++) {
   const arg = args[i];
   if (!arg)
@@ -120456,8 +120567,18 @@ 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("-")) {
@@ -120467,6 +120588,20 @@ for (let i = 0;i < args.length; i++) {
     videoId = arg;
   }
 }
+if (mode === "config") {
+  const path15 = configPath();
+  const editor = process.env.EDITOR;
+  if (editor) {
+    await new Promise((resolve3) => {
+      const proc = spawn2(editor, [path15], { stdio: "inherit" });
+      proc.on("exit", () => resolve3());
+      proc.on("error", () => resolve3());
+    });
+  } else {
+    console.log(`Config file: ${path15}`);
+  }
+  process.exit(0);
+}
 if (!videoId) {
   console.error("Error: missing video URL or ID");
   console.log(help());
@@ -120478,8 +120613,24 @@ if (!extracted) {
   process.exit(65);
 }
 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);
@@ -120504,10 +120655,12 @@ try {
     const dir2 = cacheDir(videoId, cacheOpts2);
     let segments2 = null;
     let summary = null;
+    startTimer();
     if (!noCache) {
       const cachedSegments = await readCache(dir2, "transcript.json");
       const cachedSummary = await readCache(dir2, "summary.md");
       if (cachedSegments && cachedSummary) {
+        info("Transcript cached");
         debug("Cache hit:", dir2);
         segments2 = JSON.parse(cachedSegments);
         summary = cachedSummary;
@@ -120518,32 +120671,29 @@ try {
       debug("Cache skipped (--no-cache)");
     }
     if (!segments2) {
-      debug("Fetching transcript...");
+      info("Fetching transcript...");
       segments2 = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
-      debug(`Transcript fetched: ${segments2.length} segments`);
+      info(`Transcript: ${segments2.length} segments`);
       await writeCache(dir2, "transcript.json", JSON.stringify(segments2));
       debug("Cache written: transcript.json");
     }
     const prompt = config.summarize.prompt ?? "";
     const transcriptText = toText(segments2, !noDecode);
     if (!summary) {
-      debug("Running command:", config.summarize.command);
+      info(`Summarizing...`);
       summary = await summarize({
         prompt,
         command: config.summarize.command,
         transcript: transcriptText,
         cwd: dir2
       });
-      debug("Command exit: 0");
+      info("Summary ready");
       await writeCache(dir2, "summary.md", summary);
       debug("Cache written: summary.md");
     }
     const formatted = noFormat ? summary : await formatMd(summary);
-    if (outputPath) {
-      await writeFile3(outputPath, formatted, "utf8");
-    } else {
-      console.log(formatted);
-    }
+    await outputText(formatted + `
+`);
     process.exit(0);
   } else if (listOnly) {
     const languages2 = await listLanguages(videoId);
@@ -120555,9 +120705,11 @@ try {
   const dir = cacheDir(videoId, cacheOpts);
   let segments = null;
   let videoDetailsCache = 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 {
@@ -120567,7 +120719,7 @@ try {
     debug("Cache skipped (--no-cache)");
   }
   if (!segments) {
-    debug("Fetching transcript...");
+    info("Fetching transcript...");
     if (showDetails && !outputJson) {
       const opts = lang ? { lang, videoDetails: true } : { videoDetails: true };
       const result = await fetchTranscript(videoId, opts);
@@ -120576,6 +120728,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));
   }
   if (showDetails && !outputJson) {
@@ -120591,21 +120744,13 @@ try {
 
 ` + transcriptText + `
 `;
-    if (outputPath) {
-      await writeFile3(outputPath, output, "utf8");
-    } else {
-      console.log(output);
-    }
+    await outputText(output);
   } else {
     const output = outputJson ? toJSON(segments, decode) + `
 ` : timestamps ? formatWithTimestamps(segments, decode) + `
 ` : toText(segments, decode) + `
 `;
-    if (outputPath) {
-      await writeFile3(outputPath, output, "utf8");
-    } else {
-      console.log(output);
-    }
+    await outputText(output);
   }
 } catch (err) {
   const message = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacone/prosey",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Download YouTube video transcripts from the CLI",
   "module": "src/index.ts",
   "type": "module",

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.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,7 +12,6 @@ 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";
 
@@ -21,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
@@ -44,7 +49,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,6 +140,42 @@ 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")) {
@@ -151,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);
@@ -167,7 +213,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];
@@ -200,8 +248,18 @@ 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("-")) {
@@ -212,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());
@@ -227,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);
@@ -255,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;
@@ -270,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");
     }
@@ -281,25 +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");
     }
 
     const formatted = noFormat ? summary : await formatMd(summary);
-
-    if (outputPath) {
-      await writeFile(outputPath, formatted, "utf8");
-    } else {
-      console.log(formatted);
-    }
+    await outputText(formatted + "\n");
     process.exit(0);
   } else if (listOnly) {
     const languages = await listLanguages(videoId);
@@ -313,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 {
@@ -326,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 {
@@ -338,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));
   }
 
@@ -357,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"
@@ -369,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);

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", "glow", "mdcat -l -p", "less"];
+      expect(known).toContain(pager);
+    }
+  });
+});

package/src/pager.ts

@@ -0,0 +1,23 @@
+import { execSync } from "node:child_process";
+
+export function hasCommand(cmd: string): boolean {
+  try {
+    execSync(`command -v ${cmd} 2>/dev/null`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function detectPager(cfgPager?: string): string | null {
+  const env = process.env.PROSEY_PAGER;
+  if (env !== undefined && env !== "" && env !== "auto") return env;
+
+  if (cfgPager !== undefined && cfgPager !== "" && cfgPager !== "auto") return cfgPager;
+
+  if (hasCommand("bat")) return "bat -lmd";
+  if (hasCommand("glow")) return "glow";
+  if (hasCommand("mdcat")) return "mdcat -l -p";
+  if (hasCommand("less")) return "less";
+  return null;
+}