feat(library): list saved projects so you can reopen one without its id

The project store already persists each analysis to SQLite, but there was no
way to enumerate it — you could only reopen a project if you'd kept its UUID.
Add cache.list_projects() and a GET /api/projects endpoint that returns the
saved library newest-first (id, name, file count, created_at), merging in any
project held only in memory this process. Heavy file contents stay in the row
and are read back only when a project is actually opened.

Author: he-yufeng

backend/models.py

@@ -306,6 +306,15 @@ class SecuritySummary(BaseModel):
     notes: list[str] = []
 
 
+class ProjectSummary(BaseModel):
+    """A lightweight entry in the project library list (no file contents)."""
+
+    id: str
+    name: str
+    total_files: int = 0
+    created_at: float | None = None  # unix seconds; None for in-memory-only
+
+
 class ProjectMeta(BaseModel):
     id: str
     name: str

backend/routers/project.py

@@ -44,6 +44,7 @@
     PackageDependency,
     ProjectHealth,
     ProjectMeta,
+    ProjectSummary,
     ReadingStep,
     RiskHotspot,
     SecurityFinding,
@@ -434,6 +435,30 @@ async def _resolve_project(project_id: str) -> dict | None:
     return proj
 
 
+@router.get("/projects", response_model=list[ProjectSummary])
+async def list_projects():
+    """List previously analyzed projects (the on-disk library), newest first.
+
+    Lets you reopen a past analysis without re-cloning or re-scanning. The
+    persisted SQLite store is the source of truth; a project created in this
+    process that isn't persisted yet (e.g. the cache DB is unavailable) is
+    merged in so it still shows up.
+    """
+    stored = await cache.list_projects()
+    seen = {p["id"] for p in stored}
+    summaries = [ProjectSummary(**p) for p in stored]
+    summaries.extend(
+        ProjectSummary(
+            id=project_id,
+            name=proj.get("name") or project_id,
+            total_files=len(proj.get("files") or []),
+        )
+        for project_id, proj in _projects.items()
+        if project_id not in seen
+    )
+    return summaries
+
+
 @router.get("/project/{project_id}")
 async def get_project(project_id: str):
     """Get project metadata."""

backend/services/cache.py

@@ -140,3 +140,44 @@ async def load_project(project_id: str) -> dict | None:
         await _db.commit()
         return None
     return json.loads(data)
+
+
+async def list_projects(limit: int = 50) -> list[dict]:
+    """List stored projects, newest first, for the on-disk library view.
+
+    Returns lightweight entries (id, name, total_files, created_at) so a user
+    can reopen a past analysis without re-scanning. The heavy file contents stay
+    in the row and are only read back when a project is actually opened via
+    load_project(). Expired rows are skipped (and purged lazily, like get()).
+    """
+    if _db is None:
+        return []
+    async with _db.execute(
+        "SELECT id, data, created_at FROM projects ORDER BY created_at DESC"
+    ) as cursor:
+        rows = await cursor.fetchall()
+    now = time.time()
+    expired: list[str] = []
+    projects: list[dict] = []
+    for project_id, data, created_at in rows:
+        if now - created_at > _TTL_SECONDS:
+            expired.append(project_id)
+            continue
+        if len(projects) >= limit:
+            continue
+        try:
+            parsed = json.loads(data)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        projects.append(
+            {
+                "id": project_id,
+                "name": parsed.get("name") or project_id,
+                "total_files": len(parsed.get("files") or []),
+                "created_at": created_at,
+            }
+        )
+    if expired:
+        await _db.executemany("DELETE FROM projects WHERE id = ?", [(pid,) for pid in expired])
+        await _db.commit()
+    return projects

tests/test_cache.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import time
 
 
 def _with_cache(tmp_path, monkeypatch, scenario):
@@ -140,6 +141,47 @@ async def scenario(cache):
     assert remaining == 0
 
 
+def test_list_projects_newest_first_without_file_contents(tmp_path, monkeypatch):
+    async def scenario(cache):
+        await cache.save_project("old", {"name": "旧项目", "files": [1, 2]})
+        await cache.save_project("new", {"name": "新项目", "files": [1, 2, 3]})
+        # pin created_at so the ordering doesn't depend on wall-clock resolution
+        base = time.time()
+        await cache._db.execute(
+            "UPDATE projects SET created_at = ? WHERE id = ?", (base - 10, "old")
+        )
+        await cache._db.execute(
+            "UPDATE projects SET created_at = ? WHERE id = ?", (base - 5, "new")
+        )
+        await cache._db.commit()
+        return await cache.list_projects()
+
+    projects = _with_cache(tmp_path, monkeypatch, scenario)
+    assert [p["id"] for p in projects] == ["new", "old"]  # newest first
+    assert projects[0]["name"] == "新项目"
+    assert projects[0]["total_files"] == 3
+    assert "files" not in projects[0]  # the heavy contents stay out of the listing
+
+
+def test_list_projects_skips_and_purges_expired(tmp_path, monkeypatch):
+    async def scenario(cache):
+        await cache.save_project("fresh", {"name": "在", "files": [1]})
+        await cache.save_project("stale", {"name": "过期", "files": [1]})
+        await cache._db.execute(
+            "UPDATE projects SET created_at = ? WHERE id = ?",
+            (time.time() - cache._TTL_SECONDS - 1, "stale"),
+        )
+        await cache._db.commit()
+        listed = await cache.list_projects()
+        async with cache._db.execute("SELECT COUNT(*) FROM projects") as cur:
+            (remaining,) = await cur.fetchone()
+        return [p["id"] for p in listed], remaining
+
+    ids, remaining = _with_cache(tmp_path, monkeypatch, scenario)
+    assert ids == ["fresh"]
+    assert remaining == 1  # the expired row was purged on listing
+
+
 def test_operations_are_safe_before_init(monkeypatch):
     """Every accessor degrades gracefully when the DB was never initialised."""
     from backend.services import cache
@@ -151,6 +193,7 @@ async def scenario():
         await cache.put("k", {"v": 1})  # no-op, must not raise
         await cache.save_project("p", {"v": 1})  # no-op, must not raise
         assert await cache.load_project("p") is None
+        assert await cache.list_projects() == []
         await cache.increment_rate_limit("ip")  # no-op, must not raise
         # storage unavailable -> fail open: allow, with the full quota
         return await cache.check_rate_limit("ip")

tests/test_project.py

@@ -73,3 +73,37 @@ def test_content_analyses_maps_knowledge_silos_from_ownership():
     assert len(extras["knowledge_silos"]) == 1
     silo = extras["knowledge_silos"][0]
     assert silo.path == "core.py" and silo.primary_author == "amy" and silo.bus_factor == 1
+
+
+def test_list_projects_endpoint_merges_persisted_and_in_memory(tmp_path, monkeypatch):
+    # The library list should surface both projects saved to SQLite and any only
+    # held in memory this process, without duplicating one that is in both.
+    import asyncio
+
+    from backend.routers import project as project_router
+    from backend.services import cache
+
+    monkeypatch.setattr(cache, "_DB_PATH", tmp_path / "cache.db")
+    monkeypatch.setattr(project_router, "_projects", {})
+
+    async def main():
+        await cache.init_db()
+        try:
+            await cache.save_project("persisted", {"name": "已存盘", "files": [1, 2]})
+            project_router._projects["persisted"] = {"name": "已存盘", "files": [1, 2]}
+            project_router._projects["memory-only"] = {"name": "仅内存", "files": [1]}
+            return await project_router.list_projects()
+        finally:
+            if cache._db is not None:
+                await cache._db.close()
+                cache._db = None
+
+    summaries = asyncio.run(main())
+    by_id = {s.id: s for s in summaries}
+
+    assert set(by_id) == {"persisted", "memory-only"}  # persisted one not duplicated
+    assert by_id["persisted"].name == "已存盘"
+    assert by_id["persisted"].total_files == 2
+    assert by_id["persisted"].created_at is not None
+    assert by_id["memory-only"].name == "仅内存"
+    assert by_id["memory-only"].created_at is None  # not persisted yet