@tacone/prosey 0.2.0 → 0.2.2

package/README.md

@@ -153,6 +153,18 @@ Transcripts and summaries are cached to `/tmp/prosey/`. Repeated invocations
 for the same video and options are instant and work offline. Use `--no-cache`
 to skip cache reads and force a fresh fetch.
 
+When running `prosey summarize`, the command runs inside the cache directory
+for that video. This prevents the AI agent from picking up project-specific
+files like `AGENTS.md` or `CLAUDE.md` from the current folder, and limits its
+ability to modify files outside that directory.
+
+## Exit codes
+
+| Code | Meaning                 |
+| ---- | ----------------------- |
+| `0`  | Success                 |
+| `65` | Invalid video URL or ID |
+
 ## How it works
 
 prosey uses YouTube's Innertube API via the

package/bin/prosey

@@ -13851,11 +13851,25 @@ var FALLBACK_CONFIG_TOML = `# Default prosey configuration
 # Prompt sent to the command via stdin.
 # Customize this to change how transcripts are summarized.
 prompt = """
-Summarize the following transcript.
-Focus on the key points and main arguments.
+Write a comprehensive summary of the following transcription.
 """
 
-# Command to execute with the prompt piped via stdin.
+# Command to execute with the prompt and transcript piped via stdin.
+# The transcript is appended to the prompt automatically.
+#
+# Available options:
+#
+#   opencode run                    — full access (default)
+#   opencode run --permissions read  — read-only (view files, no edits)
+#
+#   claude -p "" --print            — full access (--print for clean output)
+#   claude --permission-mode plan -p "" --print  — read-only (plan/read only)
+#
+#   copilot -sp ""                  — full access (-s = silent, -p = prompt)
+#   copilot -sp "" --deny-all-tools — read-only (no shell/write access)
+#
+#   codex --sandbox default -p ""   — full access
+#   codex --sandbox read-only -p "" — read-only
 command = "opencode run"
 `;
 async function readDefaultConfig() {
@@ -13934,7 +13948,11 @@ async function summarize(options) {
 
 ${transcript}`;
   const output = await executeCommand(command, fullPrompt, cwd);
-  return output.replace(fullPrompt, "").replace(/\n+$/, "");
+  const cleaned = output.startsWith(fullPrompt) ? output.slice(fullPrompt.length).replace(/\n+$/, "") : output.replace(/\n+$/, "");
+  if (!cleaned || cleaned === transcript) {
+    throw new Error("Summarization command returned no meaningful output");
+  }
+  return cleaned;
 }
 
 // src/cache.ts
@@ -13942,6 +13960,16 @@ import { createHash } from "node:crypto";
 import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2 } from "node:fs/promises";
 import { existsSync as existsSync2 } from "node:fs";
 import { join as join2 } from "node:path";
+var RE_YOUTUBE2 = /(?:v=|\/|v\/|embed\/|watch\?.*v=|youtu\.be\/|\/v\/|e\/|watch\?.*vi?=|\/embed\/|\/v\/|vi?\/|watch\?.*vi?=|youtu\.be\/|\/vi?\/|\/e\/)([a-zA-Z0-9_-]{11})/i;
+var RE_BARE_ID = /^[a-zA-Z0-9_-]{11}$/;
+function extractVideoId(input) {
+  if (RE_BARE_ID.test(input))
+    return input;
+  const match = input.match(RE_YOUTUBE2);
+  if (match)
+    return match[1] || null;
+  return null;
+}
 function hashOptions(opts) {
   return createHash("sha256").update(JSON.stringify(opts)).digest("hex").slice(0, 8);
 }
@@ -13964,9 +13992,87 @@ async function writeCache(dir, filename, data) {
   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.2",
+  description: "Download YouTube video transcripts from the CLI",
+  module: "src/index.ts",
+  type: "module",
+  bin: {
+    prosey: "bin/prosey"
+  },
+  files: [
+    "bin/",
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  scripts: {
+    start: "bun run src/index.ts",
+    build: "bun build src/index.ts --target node --outfile bin/prosey",
+    test: "bun test",
+    typecheck: "tsc --noEmit",
+    prettier: "prettier --write .",
+    prepack: "bun run build",
+    prepare: "husky || true"
+  },
+  "lint-staged": {
+    "*": "prettier --write --ignore-unknown"
+  },
+  author: "tacone <tacone@gmail.com>",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/tacone/prosey.git"
+  },
+  bugs: {
+    url: "https://github.com/tacone/prosey/issues"
+  },
+  homepage: "https://github.com/tacone/prosey#readme",
+  keywords: [
+    "youtube",
+    "transcript",
+    "subtitles",
+    "captions",
+    "cli",
+    "npx",
+    "bun"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    husky: "^9.1.7",
+    "lint-staged": "^17.0.7",
+    prettier: "^3.8.4"
+  },
+  peerDependencies: {
+    typescript: "^5"
+  },
+  dependencies: {
+    "js-toml": "^1.1.2",
+    "youtube-transcript-plus": "^2.0.0"
+  }
+};
+
 // src/index.ts
 var NAME2 = "prosey";
-var VERSION2 = "0.1.0";
+var VERSION2 = package_default.version;
 function help() {
   return `${NAME2} v${VERSION2}
 
@@ -13995,6 +14101,7 @@ 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.
   --help                 Show this help message.
   --version              Show version.
 
@@ -14073,12 +14180,10 @@ if (args.includes("--reset-config")) {
 }
 var config = await loadConfig().catch(() => ({}));
 var mode = "transcript";
-if (args[0] === "info") {
-  mode = "info";
-  args.splice(0, 1);
-} else if (args[0] === "summarize") {
-  mode = "summarize";
-  args.splice(0, 1);
+var subcmdIndex = args.findIndex((a2) => a2 === "info" || a2 === "summarize");
+if (subcmdIndex !== -1) {
+  mode = args[subcmdIndex];
+  args.splice(subcmdIndex, 1);
 }
 var videoId = "";
 var lang;
@@ -14089,6 +14194,7 @@ var outputJson = false;
 var noDecode = false;
 var showDetails = true;
 var noCache = false;
+var debugMode = false;
 for (let i = 0;i < args.length; i++) {
   const arg = args[i];
   if (!arg)
@@ -14119,6 +14225,8 @@ 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-decode-entities") {
     noDecode = true;
   } else if (arg.startsWith("-")) {
@@ -14133,6 +14241,19 @@ if (!videoId) {
   console.log(help());
   process.exit(1);
 }
+var extracted = extractVideoId(videoId);
+if (!extracted) {
+  console.error("Error: invalid YouTube video URL or ID");
+  process.exit(65);
+}
+videoId = extracted;
+if (debugMode)
+  enableDebug();
+debug("Config file:", configPath());
+debug("Video ID:", videoId);
+debug("Mode:", mode);
+if (lang)
+  debug("Language:", lang);
 try {
   if (mode === "info") {
     const result = await fetchTranscript(videoId, { videoDetails: true, lang });
@@ -14156,24 +14277,35 @@ try {
       const cachedSegments = await readCache(dir2, "transcript.json");
       const cachedSummary = await readCache(dir2, "summary.md");
       if (cachedSegments && cachedSummary) {
+        debug("Cache hit:", dir2);
         segments2 = JSON.parse(cachedSegments);
         summary = cachedSummary;
+      } else {
+        debug("Cache miss:", dir2);
       }
+    } else {
+      debug("Cache skipped (--no-cache)");
     }
     if (!segments2) {
+      debug("Fetching transcript...");
       segments2 = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
+      debug(`Transcript fetched: ${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);
       summary = await summarize({
         prompt,
         command: config.summarize.command,
         transcript: transcriptText,
         cwd: dir2
       });
+      debug("Command exit: 0");
       await writeCache(dir2, "summary.md", summary);
+      debug("Cache written: summary.md");
     }
     if (outputPath) {
       await writeFile3(outputPath, summary, "utf8");
@@ -14193,10 +14325,17 @@ try {
   let videoDetailsCache = null;
   if (!noCache) {
     const cached = await readCache(dir, "transcript.json");
-    if (cached)
+    if (cached) {
+      debug("Cache hit:", dir);
       segments = JSON.parse(cached);
+    } else {
+      debug("Cache miss:", dir);
+    }
+  } else {
+    debug("Cache skipped (--no-cache)");
   }
   if (!segments) {
+    debug("Fetching transcript...");
     if (showDetails && !outputJson) {
       const opts = lang ? { lang, videoDetails: true } : { videoDetails: true };
       const result = await fetchTranscript(videoId, opts);

package/package.json

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

package/src/cache.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test, afterEach } from "bun:test";
 import { rm, readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { cacheKey, cacheDir, readCache, writeCache } from "./cache";
+import { cacheKey, cacheDir, readCache, writeCache, extractVideoId } from "./cache";
 
 const testDir = "/tmp/prosey/test-cache-spec";
 
@@ -44,6 +44,34 @@ describe("cacheDir", () => {
   });
 });
 
+describe("extractVideoId", () => {
+  test("bare ID passes through", () => {
+    expect(extractVideoId("dQw4w9WgXcQ")).toBe("dQw4w9WgXcQ");
+  });
+
+  test("full watch URL", () => {
+    expect(extractVideoId("https://www.youtube.com/watch?v=jNAAG3Ma5K8")).toBe("jNAAG3Ma5K8");
+  });
+
+  test("watch URL with extra query params", () => {
+    expect(
+      extractVideoId("https://www.youtube.com/watch?v=jNAAG3Ma5K8&pp=ygUKc3BhY2V4IGlwbw%3D%3D"),
+    ).toBe("jNAAG3Ma5K8");
+  });
+
+  test("short youtu.be URL", () => {
+    expect(extractVideoId("https://youtu.be/dQw4w9WgXcQ")).toBe("dQw4w9WgXcQ");
+  });
+
+  test("embed URL", () => {
+    expect(extractVideoId("https://www.youtube.com/embed/dQw4w9WgXcQ")).toBe("dQw4w9WgXcQ");
+  });
+
+  test("invalid URL without video ID returns null", () => {
+    expect(extractVideoId("https://example.com/search?q=hello")).toBeNull();
+  });
+});
+
 describe("readCache / writeCache", () => {
   test("writes and reads a file", async () => {
     await writeCache(testDir, "test.txt", "hello world");

package/src/cache.ts

@@ -3,6 +3,17 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
+const RE_YOUTUBE =
+  /(?:v=|\/|v\/|embed\/|watch\?.*v=|youtu\.be\/|\/v\/|e\/|watch\?.*vi?=|\/embed\/|\/v\/|vi?\/|watch\?.*vi?=|youtu\.be\/|\/vi?\/|\/e\/)([a-zA-Z0-9_-]{11})/i;
+const RE_BARE_ID = /^[a-zA-Z0-9_-]{11}$/;
+
+export function extractVideoId(input: string): string | null {
+  if (RE_BARE_ID.test(input)) return input;
+  const match = input.match(RE_YOUTUBE);
+  if (match) return match[1] || null;
+  return null;
+}
+
 export interface CacheOptions {
   lang?: string;
   timestamps?: boolean;

package/src/config.ts

@@ -19,11 +19,25 @@ const FALLBACK_CONFIG_TOML = `# Default prosey configuration
 # Prompt sent to the command via stdin.
 # Customize this to change how transcripts are summarized.
 prompt = """
-Summarize the following transcript.
-Focus on the key points and main arguments.
+Write a comprehensive summary of the following transcription.
 """
 
-# Command to execute with the prompt piped via stdin.
+# Command to execute with the prompt and transcript piped via stdin.
+# The transcript is appended to the prompt automatically.
+#
+# Available options:
+#
+#   opencode run                    — full access (default)
+#   opencode run --permissions read  — read-only (view files, no edits)
+#
+#   claude -p "" --print            — full access (--print for clean output)
+#   claude --permission-mode plan -p "" --print  — read-only (plan/read only)
+#
+#   copilot -sp ""                  — full access (-s = silent, -p = prompt)
+#   copilot -sp "" --deny-all-tools — read-only (no shell/write access)
+#
+#   codex --sandbox default -p ""   — full access
+#   codex --sandbox read-only -p "" — read-only
 command = "opencode run"
 `;
 

package/src/debug.ts

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

package/src/default-config.toml

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

package/src/index.ts

@@ -4,13 +4,15 @@ import { writeFile } from "node:fs/promises";
 import { fetchTranscript, listLanguages } from "youtube-transcript-plus";
 import type { CaptionTrackInfo, VideoDetails, TranscriptSegment } from "youtube-transcript-plus";
 import { formatWithTimestamps, toText, toJSON, formatDuration, decodeEntities } from "./format";
-import { loadConfig, resetConfig } from "./config";
+import { loadConfig, resetConfig, configPath } from "./config";
 import type { ProseyConfig } from "./config";
 import { summarize } from "./summarize";
-import { cacheDir, readCache, writeCache } from "./cache";
+import { cacheDir, readCache, writeCache, extractVideoId } from "./cache";
+import { enableDebug, debug } from "./debug";
+import pkg from "../package.json";
 
 const NAME = "prosey";
-const VERSION = "0.1.0";
+const VERSION = pkg.version;
 
 function help(): string {
   return `${NAME} v${VERSION}
@@ -40,6 +42,7 @@ 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.
   --help                 Show this help message.
   --version              Show version.
 
@@ -138,12 +141,10 @@ if (args.includes("--reset-config")) {
 const config: ProseyConfig = await loadConfig().catch(() => ({}) as ProseyConfig);
 
 let mode = "transcript";
-if (args[0] === "info") {
-  mode = "info";
-  args.splice(0, 1);
-} else if (args[0] === "summarize") {
-  mode = "summarize";
-  args.splice(0, 1);
+const subcmdIndex = args.findIndex((a) => a === "info" || a === "summarize");
+if (subcmdIndex !== -1) {
+  mode = args[subcmdIndex]!;
+  args.splice(subcmdIndex, 1);
 }
 
 let videoId = "";
@@ -155,6 +156,7 @@ let outputJson = false;
 let noDecode = false;
 let showDetails = true;
 let noCache = false;
+let debugMode = false;
 
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
@@ -185,6 +187,8 @@ 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-decode-entities") {
     noDecode = true;
   } else if (arg.startsWith("-")) {
@@ -201,6 +205,21 @@ if (!videoId) {
   process.exit(1);
 }
 
+const extracted = extractVideoId(videoId);
+
+if (!extracted) {
+  console.error("Error: invalid YouTube video URL or ID");
+  process.exit(65);
+}
+
+videoId = extracted;
+
+if (debugMode) enableDebug();
+debug("Config file:", configPath());
+debug("Video ID:", videoId);
+debug("Mode:", mode);
+if (lang) debug("Language:", lang);
+
 try {
   if (mode === "info") {
     const result = await fetchTranscript(videoId, { videoDetails: true, lang } as any);
@@ -227,27 +246,38 @@ try {
       const cachedSegments = await readCache(dir, "transcript.json");
       const cachedSummary = await readCache(dir, "summary.md");
       if (cachedSegments && cachedSummary) {
+        debug("Cache hit:", dir);
         segments = JSON.parse(cachedSegments);
         summary = cachedSummary;
+      } else {
+        debug("Cache miss:", dir);
       }
+    } else {
+      debug("Cache skipped (--no-cache)");
     }
 
     if (!segments) {
+      debug("Fetching transcript...");
       segments = lang ? await fetchTranscript(videoId, { lang }) : await fetchTranscript(videoId);
+      debug(`Transcript fetched: ${segments.length} segments`);
       await writeCache(dir, "transcript.json", JSON.stringify(segments));
+      debug("Cache written: transcript.json");
     }
 
     const prompt = config.summarize.prompt ?? "";
     const transcriptText = toText(segments, !noDecode);
 
     if (!summary) {
+      debug("Running command:", config.summarize.command);
       summary = await summarize({
         prompt,
         command: config.summarize.command,
         transcript: transcriptText,
         cwd: dir,
       });
+      debug("Command exit: 0");
       await writeCache(dir, "summary.md", summary);
+      debug("Cache written: summary.md");
     }
 
     if (outputPath) {
@@ -270,10 +300,18 @@ try {
 
   if (!noCache) {
     const cached = await readCache(dir, "transcript.json");
-    if (cached) segments = JSON.parse(cached);
+    if (cached) {
+      debug("Cache hit:", dir);
+      segments = JSON.parse(cached);
+    } else {
+      debug("Cache miss:", dir);
+    }
+  } else {
+    debug("Cache skipped (--no-cache)");
   }
 
   if (!segments) {
+    debug("Fetching transcript...");
     if (showDetails && !outputJson) {
       const opts = lang ? { lang, videoDetails: true as const } : { videoDetails: true as const };
       const result = (await fetchTranscript(videoId, opts)) as {

package/src/summarize.test.ts

@@ -2,22 +2,24 @@ import { describe, expect, test } from "bun:test";
 import { summarize } from "./summarize";
 
 describe("summarize", () => {
-  test("strips input text from output", async () => {
-    const result = await summarize({
-      prompt: "Summarize this:",
-      command: "cat",
-      transcript: "Hello world. This is the transcript.",
-    });
-    expect(result).toBe("");
+  test("rejects when command only echoes input", async () => {
+    await expect(
+      summarize({
+        prompt: "Summarize this:",
+        command: "cat",
+        transcript: "Hello world. This is the transcript.",
+      }),
+    ).rejects.toThrow("Summarization command returned no meaningful output");
   });
 
-  test("strips input text from output with empty prompt", async () => {
-    const result = await summarize({
-      prompt: "",
-      command: "cat",
-      transcript: "Just the transcript.",
-    });
-    expect(result).toBe("");
+  test("rejects when command only echoes input with empty prompt", async () => {
+    await expect(
+      summarize({
+        prompt: "",
+        command: "cat",
+        transcript: "Just the transcript.",
+      }),
+    ).rejects.toThrow("Summarization command returned no meaningful output");
   });
 
   test("preserves response text beyond the input", async () => {

package/src/summarize.ts

@@ -38,5 +38,14 @@ export async function summarize(options: SummarizeOptions): Promise<string> {
   const { prompt, command, transcript, cwd } = options;
   const fullPrompt = `${prompt}\n\n${transcript}`;
   const output = await executeCommand(command, fullPrompt, cwd);
-  return output.replace(fullPrompt, "").replace(/\n+$/, "");
+
+  const cleaned = output.startsWith(fullPrompt)
+    ? output.slice(fullPrompt.length).replace(/\n+$/, "")
+    : output.replace(/\n+$/, "");
+
+  if (!cleaned || cleaned === transcript) {
+    throw new Error("Summarization command returned no meaningful output");
+  }
+
+  return cleaned;
 }