Merge pull request teng-lin#197 from teng-lin/issue-112

fix(cli): add explicit source delete-by-title command

Author: teng-lin

docs/cli-reference.md

@@ -102,8 +102,11 @@ Supported source types: URLs, YouTube videos, files (PDF, text, Markdown, Word,
 | `rename <id> <title>` | Source ID, new title | - | `source rename src123 "New Name"` |
 | `refresh <id>` | Source ID | - | `source refresh src123` |
 | `delete <id>` | Source ID | - | `source delete src123` |
+| `delete-by-title <title>` | Exact source title | - | `source delete-by-title "My Source"` |
 | `wait <id>` | Source ID | `--timeout`, `--interval` | `source wait src123` |
 
+`source delete <id>` accepts only full source IDs or unique partial-ID prefixes. To delete by exact source title, use `source delete-by-title "<title>"`.
+
 ### Research Commands (`notebooklm research <cmd>`)
 
 | Command | Arguments | Options | Example |

docs/troubleshooting.md

@@ -210,6 +210,8 @@ If the title contains error-related text, remove the source and use the pre-fetc
 ```bash
 # Remove incorrectly parsed source
 notebooklm source delete <source_id>
+# Or, if you only have the exact title:
+notebooklm source delete-by-title "Exact Source Title"
 
 # Then re-add using the bird CLI method above
 ```

src/notebooklm/cli/source.py

@@ -8,13 +8,15 @@
     guide        Get AI-generated source summary and keywords
     stale        Check if a URL/Drive source needs refresh
     delete       Delete a source
+    delete-by-title Delete a source by exact title
     rename       Rename a source
     refresh      Refresh a URL/Drive source
     add-drive    Add a Google Drive document
     add-research Search web/drive and add sources from results
 """
 
 import asyncio
+import re
 from pathlib import Path
 
 import click
@@ -33,6 +35,7 @@
     require_notebook,
     resolve_notebook_id,
     resolve_source_id,
+    validate_id,
     with_client,
 )
 
@@ -50,6 +53,7 @@ def source():
       guide        Get AI-generated source summary and keywords
       stale        Check if source needs refresh
       delete       Delete a source
+      delete-by-title Delete a source by exact title
       rename       Rename a source
       refresh      Refresh a URL/Drive source
 
@@ -61,6 +65,91 @@ def source():
     pass
 
 
+def _build_id_ambiguity_error(source_id: str, matches) -> click.ClickException:
+    """Build a consistent ambiguity error for source ID prefix matches."""
+    lines = [f"Ambiguous ID '{source_id}' matches {len(matches)} sources:"]
+    for item in matches[:5]:
+        title = item.title or "(untitled)"
+        lines.append(f"  {item.id[:12]}... {title}")
+    if len(matches) > 5:
+        lines.append(f"  ... and {len(matches) - 5} more")
+    lines.append("Specify more characters to narrow down.")
+    return click.ClickException("\n".join(lines))
+
+
+def _looks_like_full_source_id(source_id: str) -> bool:
+    """Return True for UUID-shaped source IDs that can skip list-based resolution."""
+    return bool(
+        re.fullmatch(
+            r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}",
+            source_id,
+        )
+    )
+
+
+async def _resolve_source_for_delete(client, notebook_id: str, source_id: str) -> str:
+    """Resolve a source ID for delete, returning the full source ID string.
+
+    Canonical UUIDs take a fast path and skip the live source list lookup.
+    Partial IDs are resolved against the live list.
+    """
+    source_id = validate_id(source_id, "source")
+    if _looks_like_full_source_id(source_id):
+        return source_id
+
+    sources = await client.sources.list(notebook_id)
+    matches = [item for item in sources if item.id.lower().startswith(source_id.lower())]
+
+    if len(matches) == 1:
+        if matches[0].id != source_id:
+            title = matches[0].title or "(untitled)"
+            console.print(f"[dim]Matched: {matches[0].id[:12]}... ({title})[/dim]")
+        return matches[0].id
+
+    if len(matches) > 1:
+        raise _build_id_ambiguity_error(source_id, matches)
+
+    title_matches = [item for item in sources if item.title == source_id]
+    if title_matches:
+        lines = [
+            f"'{source_id}' matches {len(title_matches)} source title(s), not source IDs.",
+            f"Use 'notebooklm source delete-by-title \"{source_id}\"' or delete by ID:",
+        ]
+        for item in title_matches[:5]:
+            lines.append(f"  {item.id[:12]}... {item.title}")
+        if len(title_matches) > 5:
+            lines.append(f"  ... and {len(title_matches) - 5} more")
+        raise click.ClickException("\n".join(lines))
+
+    raise click.ClickException(
+        f"No source found starting with '{source_id}'. "
+        "Run 'notebooklm source list' to see available sources."
+    )
+
+
+async def _resolve_source_by_exact_title(client, notebook_id: str, title: str):
+    """Resolve a source by exact title for the explicit delete-by-title flow."""
+    title = validate_id(title, "source title")
+    sources = await client.sources.list(notebook_id)
+    matches = [item for item in sources if item.title == title]
+
+    if len(matches) == 1:
+        return matches[0]
+
+    if len(matches) > 1:
+        lines = [f"Title '{title}' matches {len(matches)} sources. Delete by ID instead:"]
+        for item in matches[:5]:
+            lines.append(f"  {item.id[:12]}... {item.title}")
+        if len(matches) > 5:
+            lines.append(f"  ... and {len(matches) - 5} more")
+        raise click.ClickException("\n".join(lines))
+
+    raise click.ClickException(
+        f"No source found with title '{title}'. "
+        "Run 'notebooklm source list' to see available sources."
+    )
+
+
 @source.command("list")
 @click.option(
     "-n",
@@ -274,8 +363,7 @@ def source_delete(ctx, source_id, notebook_id, yes, client_auth):
     async def _run():
         async with NotebookLMClient(client_auth) as client:
             nb_id_resolved = await resolve_notebook_id(client, nb_id)
-            # Resolve partial ID to full ID
-            resolved_id = await resolve_source_id(client, nb_id_resolved, source_id)
+            resolved_id = await _resolve_source_for_delete(client, nb_id_resolved, source_id)
 
             if not yes and not click.confirm(f"Delete source {resolved_id}?"):
                 return
@@ -289,6 +377,38 @@ async def _run():
     return _run()
 
 
+@source.command("delete-by-title")
+@click.argument("title")
+@click.option(
+    "-n",
+    "--notebook",
+    "notebook_id",
+    default=None,
+    help="Notebook ID (uses current if not set)",
+)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@with_client
+def source_delete_by_title(ctx, title, notebook_id, yes, client_auth):
+    """Delete a source by exact title."""
+    nb_id = require_notebook(notebook_id)
+
+    async def _run():
+        async with NotebookLMClient(client_auth) as client:
+            nb_id_resolved = await resolve_notebook_id(client, nb_id)
+            source = await _resolve_source_by_exact_title(client, nb_id_resolved, title)
+
+            if not yes and not click.confirm(f"Delete source '{source.title}' ({source.id})?"):
+                return
+
+            success = await client.sources.delete(nb_id_resolved, source.id)
+            if success:
+                console.print(f"[green]Deleted source:[/green] {source.id}")
+            else:
+                console.print("[yellow]Delete may have failed[/yellow]")
+
+    return _run()
+
+
 @source.command("rename")
 @click.argument("source_id")
 @click.argument("new_title")

src/notebooklm/data/SKILL.md

@@ -129,6 +129,8 @@ Before starting workflows, verify the CLI is ready:
 | Add file | `notebooklm source add ./file.pdf` |
 | Add YouTube | `notebooklm source add "https://youtube.com/..."` |
 | List sources | `notebooklm source list` |
+| Delete source by ID | `notebooklm source delete <source_id>` |
+| Delete source by exact title | `notebooklm source delete-by-title "Exact Title"` |
 | Wait for source processing | `notebooklm source wait <source_id>` |
 | Web research (fast) | `notebooklm source add-research "query"` |
 | Web research (deep) | `notebooklm source add-research "query" --mode deep --no-wait` |
@@ -173,7 +175,7 @@ Before starting workflows, verify the CLI is ready:
 
 **Parallel safety:** Use explicit notebook IDs in parallel workflows. Commands supporting `-n` shorthand: `artifact wait`, `source wait`, `research wait/status`, `download *`. Download commands also support `-a/--artifact`. Other commands use `--notebook`. For chat, use `-c <conversation_id>` to target a specific conversation.
 
-**Partial IDs:** Use first 6+ characters of UUIDs. Must be unique prefix (fails if ambiguous). Works for: `use`, `delete`, `wait` commands. For automation, prefer full UUIDs to avoid ambiguity.
+**Partial IDs:** Use first 6+ characters of UUIDs. Must be unique prefix (fails if ambiguous). Works for ID-based commands such as `use`, `source delete`, and `wait`. For exact source-title deletion, use `source delete-by-title "Title"`. For automation, prefer full UUIDs to avoid ambiguity.
 
 ## Command Output Formats
 

tests/integration/cli_vcr/test_sources.py

@@ -78,3 +78,23 @@ def test_source_content(self, runner, mock_auth_for_vcr, mock_context, command,
         with notebooklm_vcr.use_cassette(cassette):
             result = runner.invoke(cli, ["source", command, "test_source_id"])
             assert_command_success(result)
+
+
+class TestSourceDeleteCommand:
+    """Test delete command paths that can reuse existing VCR coverage."""
+
+    @notebooklm_vcr.use_cassette("sources_delete.yaml")
+    def test_source_delete_full_uuid(self, runner, mock_auth_for_vcr, mock_context):
+        """Delete source by full UUID works with real client."""
+        result = runner.invoke(
+            cli,
+            [
+                "source",
+                "delete",
+                "ff503bfa-5e39-4281-a1d8-2a66c7b86724",
+                "-n",
+                "06f0c5bd-108f-4c8b-8911-34b2acc656de",
+                "-y",
+            ],
+        )
+        assert_command_success(result, allow_no_context=False)

tests/integration/test_cli_source_delete.py

@@ -0,0 +1,120 @@
+"""Integration tests for source delete CLI flows."""
+
+import json
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from click.testing import CliRunner
+from pytest_httpx import HTTPXMock
+
+from notebooklm.notebooklm_cli import cli
+from notebooklm.rpc import RPCMethod
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    """Create a Click test runner."""
+    return CliRunner()
+
+
+@pytest.fixture
+def mock_auth():
+    """Mock authentication for CLI integration tests."""
+    with (
+        patch(
+            "notebooklm.cli.helpers.load_auth_from_storage",
+            return_value={
+                "SID": "test",
+                "HSID": "test",
+                "SSID": "test",
+                "APISID": "test",
+                "SAPISID": "test",
+            },
+        ),
+        patch("notebooklm.cli.helpers.fetch_tokens", new_callable=AsyncMock) as mock_fetch,
+    ):
+        mock_fetch.return_value = ("csrf_token", "session_id")
+        yield
+
+
+@pytest.fixture
+def mock_context(tmp_path: Path):
+    """Provide a canonical notebook UUID so CLI skips notebook-list resolution."""
+    context_file = tmp_path / "context.json"
+    context_file.write_text(
+        json.dumps({"notebook_id": "06f0c5bd-108f-4c8b-8911-34b2acc656de"}),
+        encoding="utf-8",
+    )
+
+    with patch("notebooklm.cli.helpers.get_context_path", return_value=context_file):
+        yield context_file
+
+
+def _build_source_list_response(build_rpc_response, source_id: str, title: str) -> str:
+    """Build a GET_NOTEBOOK response containing a single source."""
+    return build_rpc_response(
+        RPCMethod.GET_NOTEBOOK,
+        [
+            [
+                "Test Notebook",
+                [
+                    [
+                        [source_id],
+                        title,
+                        [None, 11, [1704067200, 0], None, 5, None, None, None],
+                        [None, 2],
+                    ]
+                ],
+                "06f0c5bd-108f-4c8b-8911-34b2acc656de",
+                "📘",
+                None,
+                [None, None, None, None, None, [1704067200, 0]],
+            ]
+        ],
+    )
+
+
+class TestCliSourceDeleteIntegration:
+    """Integration coverage for CLI source delete flows."""
+
+    def test_source_delete_by_title(
+        self, runner, mock_auth, mock_context, httpx_mock: HTTPXMock, build_rpc_response
+    ):
+        httpx_mock.add_response(
+            content=_build_source_list_response(
+                build_rpc_response,
+                "ff503bfa-5e39-4281-a1d8-2a66c7b86724",
+                "VCR Delete Test Source",
+            ).encode()
+        )
+        httpx_mock.add_response(
+            content=build_rpc_response(RPCMethod.DELETE_SOURCE, [True]).encode()
+        )
+
+        result = runner.invoke(
+            cli,
+            ["source", "delete-by-title", "VCR Delete Test Source", "-y"],
+        )
+
+        assert result.exit_code == 0
+        assert "Deleted source" in result.output
+
+    def test_source_delete_title_suggests_delete_by_title(
+        self, runner, mock_auth, mock_context, httpx_mock: HTTPXMock, build_rpc_response
+    ):
+        httpx_mock.add_response(
+            content=_build_source_list_response(
+                build_rpc_response,
+                "ff503bfa-5e39-4281-a1d8-2a66c7b86724",
+                "VCR Delete Test Source",
+            ).encode()
+        )
+
+        result = runner.invoke(
+            cli,
+            ["source", "delete", "VCR Delete Test Source", "-y"],
+        )
+
+        assert result.exit_code == 1
+        assert "delete-by-title" in result.output