From ffd1450f627d7da14d9f98426db3059dc4307d95 Mon Sep 17 00:00:00 2001
From: pyr0ball <pyroballpcs@gmail.com>
Date: Tue, 3 Mar 2026 13:22:17 -0800
Subject: [PATCH] feat(avocet): FastAPI skeleton + JSONL helpers

---
 app/api.py        | 59 +++++++++++++++++++++++++++++++++++++++++++++++
 tests/test_api.py |  8 +++++++
 2 files changed, 67 insertions(+)
 create mode 100644 app/api.py
 create mode 100644 tests/test_api.py

diff --git a/app/api.py b/app/api.py
new file mode 100644
index 0000000..7148d9c
--- /dev/null
+++ b/app/api.py
@@ -0,0 +1,59 @@
+"""Avocet — FastAPI REST layer.
+
+JSONL read/write helpers and FastAPI app instance.
+Endpoints and static file serving are added in subsequent tasks.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fastapi import FastAPI
+
+_ROOT = Path(__file__).parent.parent
+_DATA_DIR: Path = _ROOT / "data"   # overridable in tests via set_data_dir()
+
+
+def set_data_dir(path: Path) -> None:
+    """Override data directory — used by tests."""
+    global _DATA_DIR
+    _DATA_DIR = path
+
+
+def _queue_file() -> Path:
+    return _DATA_DIR / "email_label_queue.jsonl"
+
+
+def _score_file() -> Path:
+    return _DATA_DIR / "email_score.jsonl"
+
+
+def _discarded_file() -> Path:
+    return _DATA_DIR / "discarded.jsonl"
+
+
+def _read_jsonl(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    lines = path.read_text(encoding="utf-8").splitlines()
+    return [json.loads(l) for l in lines if l.strip()]
+
+
+def _write_jsonl(path: Path, records: list[dict]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "\n".join(json.dumps(r, ensure_ascii=False) for r in records) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _append_jsonl(path: Path, record: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+app = FastAPI(title="Avocet API")
+
+# In-memory last-action store (single user, local tool — in-memory is fine)
+_last_action: dict | None = None
diff --git a/tests/test_api.py b/tests/test_api.py
new file mode 100644
index 0000000..311e8f7
--- /dev/null
+++ b/tests/test_api.py
@@ -0,0 +1,8 @@
+# tests/test_api.py
+import json, pytest
+from pathlib import Path
+
+# We'll import helpers once they exist
+# For now just verify the file can be imported
+def test_import():
+    from app import api  # noqa: F401