casebook 0.1.0__py3-none-any.whl

casebook/__init__.py

@@ -0,0 +1,3 @@
+"""Casebook: a local YAML test case browser and editor."""
+
+__version__ = "0.1.0"

casebook/app.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+import queue
+import atexit
+from pathlib import Path
+from typing import Any
+
+from flask import Flask, Response, jsonify, render_template, request, stream_with_context
+
+from . import __version__
+from .editor import CaseEditor, CaseNotFoundError, EditConflictError
+from .marks import MarksStore
+from .scanner import CasebookStore
+from .watcher import CasebookWatcher
+
+
+class EventBroker:
+    def __init__(self):
+        self._subscribers: list[queue.Queue[dict[str, Any]]] = []
+
+    def subscribe(self) -> queue.Queue[dict[str, Any]]:
+        subscriber: queue.Queue[dict[str, Any]] = queue.Queue()
+        self._subscribers.append(subscriber)
+        return subscriber
+
+    def unsubscribe(self, subscriber: queue.Queue[dict[str, Any]]) -> None:
+        try:
+            self._subscribers.remove(subscriber)
+        except ValueError:
+            pass
+
+    def publish(self, event: dict[str, Any]) -> None:
+        for subscriber in list(self._subscribers):
+            subscriber.put(event)
+
+
+def create_app(
+    project_root: Path,
+    scan_dirs: list[str] | None = None,
+    watch: bool = True,
+) -> Flask:
+    app = Flask(__name__)
+    store = CasebookStore(project_root=project_root, scan_dirs=scan_dirs)
+    editor = CaseEditor(project_root=project_root)
+    marks = MarksStore(project_root=project_root)
+    broker = EventBroker()
+
+    initial_summary = store.refresh()
+    app.config["CASEBOOK_INITIAL_SUMMARY"] = initial_summary
+
+    def refresh_and_publish(reason: str) -> dict[str, Any]:
+        summary = store.refresh()
+        broker.publish({"type": "reload", "reason": reason, "summary": summary})
+        return summary
+
+    watcher: CasebookWatcher | None = None
+    if watch:
+        watcher = CasebookWatcher(
+            project_root=store.project_root,
+            scan_dirs=store.scan_dirs,
+            on_change=lambda: refresh_and_publish("filesystem"),
+        )
+        watcher.start()
+        app.config["CASEBOOK_WATCHER"] = watcher
+        atexit.register(watcher.stop)
+
+    @app.after_request
+    def add_no_cache_headers(response):
+        if request.path.startswith("/api/"):
+            response.headers["Cache-Control"] = "no-store"
+        return response
+
+    @app.route("/")
+    def index():
+        return render_template("index.html", casebook_version=__version__)
+
+    @app.get("/favicon.ico")
+    def favicon():
+        return Response(status=204)
+
+    @app.get("/api/summary")
+    def api_summary():
+        return jsonify(store.summary())
+
+    @app.get("/api/tree")
+    def api_tree():
+        return jsonify(store.tree())
+
+    @app.get("/api/files")
+    def api_files():
+        return jsonify(store.list_files())
+
+    @app.get("/api/files/<path:file_path>")
+    def api_file(file_path: str):
+        entry = store.get_file(file_path)
+        if not entry:
+            return jsonify({"error": f"File not found: {file_path}"}), 404
+        all_marks = marks.all()
+        entry["marks"] = {
+            f"{file_path}#{case['id']}": all_marks.get(f"{file_path}#{case['id']}")
+            for case in entry["cases"]
+            if all_marks.get(f"{file_path}#{case['id']}")
+        }
+        entry["needs_update_count"] = len(entry["marks"])
+        return jsonify(entry)
+
+    @app.get("/api/marks")
+    def api_marks():
+        return jsonify(marks.all())
+
+    @app.post("/api/marks/toggle")
+    def api_toggle_mark():
+        payload = request.get_json(silent=True) or {}
+        file_path = str(payload.get("file_path") or payload.get("filePath") or "")
+        case_id = str(payload.get("case_id") or payload.get("caseId") or "")
+        if not file_path or not case_id:
+            return jsonify({"error": "Missing file_path or case_id"}), 400
+        result = marks.toggle_needs_update(file_path, case_id)
+        broker.publish({
+            "type": "marks",
+            "file_path": file_path,
+            "case_id": case_id,
+            "marked": result["marked"],
+        })
+        return jsonify(result)
+
+    @app.patch("/api/cases")
+    def api_update_case():
+        payload = request.get_json(silent=True) or {}
+        file_path = str(payload.get("file_path") or "")
+        case_id = str(payload.get("case_id") or "")
+        updates = payload.get("updates") or {}
+        mtime_ns = payload.get("mtime_ns")
+        if not file_path or not case_id or not isinstance(updates, dict):
+            return jsonify({"error": "Missing file_path, case_id, or updates"}), 400
+        try:
+            result = editor.update_case(file_path, case_id, updates, mtime_ns=mtime_ns)
+        except EditConflictError as exc:
+            return jsonify({"error": str(exc), "code": "edit_conflict"}), 409
+        except CaseNotFoundError:
+            return jsonify({"error": f"Case not found: {case_id}"}), 404
+        except FileNotFoundError:
+            return jsonify({"error": f"File not found: {file_path}"}), 404
+        summary = refresh_and_publish("edit")
+        return jsonify({"status": "ok", "result": result, "summary": summary})
+
+    @app.route("/api/refresh", methods=["GET", "POST"])
+    def api_refresh():
+        return jsonify(refresh_and_publish("manual"))
+
+    @app.get("/api/events")
+    def api_events():
+        subscriber = broker.subscribe()
+
+        def stream():
+            try:
+                yield "event: hello\ndata: {}\n\n"
+                while True:
+                    try:
+                        event = subscriber.get(timeout=15)
+                        data = json.dumps(event, ensure_ascii=False)
+                        yield f"event: {event.get('type', 'message')}\ndata: {data}\n\n"
+                    except queue.Empty:
+                        yield "event: ping\ndata: {}\n\n"
+            finally:
+                broker.unsubscribe(subscriber)
+
+        return Response(
+            stream_with_context(stream()),
+            mimetype="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    return app

casebook/cli.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import logging
+import webbrowser
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from . import __version__
+
+
+LOGGER = logging.getLogger("casebook.main")
+
+app = typer.Typer(
+    help="Render, review, and edit YAML test cases locally.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def configure_logging() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="[%(asctime)s] %(levelname)s/%(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"casebook {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Show the Casebook version and exit.",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    configure_logging()
+
+
+def serve_project(
+    paths: list[str],
+    host: str = "127.0.0.1",
+    port: int = 8089,
+    open_browser: bool = False,
+    watch: bool = True,
+) -> None:
+    from werkzeug.serving import make_server
+
+    from .app import create_app
+
+    project_root = Path.cwd()
+    flask_app = create_app(project_root=project_root, scan_dirs=paths, watch=watch)
+    summary = flask_app.config.get("CASEBOOK_INITIAL_SUMMARY", {})
+    url = f"http://{host}:{port}"
+    browser_url = f"http://localhost:{port}" if host in {
+        "127.0.0.1", "::"} else url
+
+    LOGGER.info("Starting web interface at %s", url)
+    LOGGER.info("Starting Casebook %s", __version__)
+    LOGGER.info("Watching YAML cases in %s", ", ".join(
+        summary.get("scan_dirs", paths or [])))
+    LOGGER.info("Loaded %s files, %s cases", summary.get(
+        "files", 0), summary.get("cases", 0))
+
+    if open_browser:
+        webbrowser.open(browser_url)
+
+    server = make_server(host, port, flask_app, threaded=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        LOGGER.info("Stopping Casebook")
+    finally:
+        server.server_close()
+
+
+@app.command(help="Start the local Casebook web UI.")
+def serve(
+    paths: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="YAML case directories relative to the current project root.",
+        ),
+    ] = None,
+    host: Annotated[
+        str,
+        typer.Option("--host", help="Host to bind."),
+    ] = "127.0.0.1",
+    port: Annotated[
+        int,
+        typer.Option("--port", "-p", help="Port to bind."),
+    ] = 8089,
+    open_browser: Annotated[
+        bool,
+        typer.Option("--open", "-o", help="Open the web UI in a browser."),
+    ] = False,
+    no_watch: Annotated[
+        bool,
+        typer.Option("--no-watch", help="Disable filesystem auto-refresh."),
+    ] = False,
+) -> None:
+    serve_project(
+        paths=paths or [],
+        host=host,
+        port=port,
+        open_browser=open_browser,
+        watch=not no_watch,
+    )
+
+
+def initialize_project(project: str, force: bool = False) -> None:
+    from .initializer import ProjectInitError, init_project
+
+    try:
+        result = init_project(project, force=force)
+    except ProjectInitError as exc:
+        typer.echo(f"casebook init: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(f"Initialized Casebook project at {result.project_root}")
+    if result.created:
+        typer.echo("\nCreated:")
+        for path in result.created:
+            typer.echo(f"  {path.as_posix()}")
+    if result.skipped:
+        typer.echo("\nSkipped existing files:")
+        for path in result.skipped:
+            typer.echo(f"  {path.as_posix()}")
+        typer.echo("\nUse --force to overwrite scaffold files.")
+    typer.echo("\nNext steps:")
+    typer.echo(f"  cd {result.project_root}")
+    typer.echo("  casebook serve releases")
+
+
+@app.command(help="Create a new Casebook test case project.")
+def init(
+    project: Annotated[
+        str,
+        typer.Argument(help="Project directory to create or initialize."),
+    ],
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite existing scaffold files."),
+    ] = False,
+) -> None:
+    initialize_project(project, force=force)
+
+
+def main(argv: list[str] | None = None) -> None:
+    app(args=argv)
+
+
+if __name__ == "__main__":
+    main()

casebook/editor.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+from ruamel.yaml.scalarstring import LiteralScalarString
+
+from .scanner import case_to_api, resolve_project_path
+
+
+ALLOWED_FIELDS = {
+    "title",
+    "description",
+    "priority",
+    "type",
+    "preconditions",
+    "steps",
+    "expected_results",
+    "tags",
+    "auto",
+}
+LIST_FIELDS = {"preconditions", "steps", "expected_results", "tags"}
+FIELD_ORDER = [
+    "id",
+    "title",
+    "description",
+    "priority",
+    "type",
+    "preconditions",
+    "steps",
+    "expected_results",
+    "tags",
+    "auto",
+]
+
+
+class EditConflictError(Exception):
+    pass
+
+
+class CaseNotFoundError(Exception):
+    pass
+
+
+class CaseEditor:
+    def __init__(self, project_root: Path):
+        self.project_root = project_root.resolve()
+        self.yaml = YAML(typ="rt")
+        self.yaml.preserve_quotes = True
+        self.yaml.indent(mapping=2, sequence=4, offset=2)
+        self.yaml.width = 4096
+
+    def update_case(
+        self,
+        file_path: str,
+        case_id: str,
+        updates: dict[str, Any],
+        mtime_ns: int | None = None,
+    ) -> dict[str, Any]:
+        target = resolve_project_path(self.project_root, file_path)
+        if not target.exists():
+            raise FileNotFoundError(file_path)
+        current_mtime = target.stat().st_mtime_ns
+        if mtime_ns is not None and int(mtime_ns) != current_mtime:
+            raise EditConflictError("The file changed after it was loaded.")
+
+        data = self.yaml.load(target.read_text(encoding="utf-8"))
+        test_cases = data.get("test_cases") if isinstance(data, dict) else None
+        if not isinstance(test_cases, list):
+            raise CaseNotFoundError(case_id)
+
+        for index, case in enumerate(test_cases):
+            if str(case.get("id", "")) != str(case_id):
+                continue
+            self._apply_updates(case, updates)
+            with target.open("w", encoding="utf-8") as handle:
+                self.yaml.dump(data, handle)
+            return {
+                "case": case_to_api(case, index),
+                "mtime_ns": str(target.stat().st_mtime_ns),
+            }
+        raise CaseNotFoundError(case_id)
+
+    def _apply_updates(self, case: dict[str, Any], updates: dict[str, Any]) -> None:
+        for field, value in updates.items():
+            if field not in ALLOWED_FIELDS:
+                continue
+            if field not in case and self._empty_missing_value(field, value):
+                continue
+            if field in LIST_FIELDS:
+                self._set_field(case, field, self._list_value(value, case.get(field)))
+            elif field == "auto":
+                self._set_field(case, field, bool(value))
+            elif field == "description":
+                text = "" if value is None else str(value)
+                self._set_field(
+                    case,
+                    field,
+                    LiteralScalarString(text) if "\n" in text else text,
+                )
+            else:
+                self._set_field(case, field, "" if value is None else str(value))
+
+    def _empty_missing_value(self, field: str, value: Any) -> bool:
+        if field == "auto":
+            return value in {False, None, ""}
+        if field in LIST_FIELDS:
+            if isinstance(value, str):
+                return not value.strip()
+            if isinstance(value, list):
+                return not any(str(item).strip() for item in value)
+            return True
+        if value is None:
+            return True
+        if isinstance(value, str):
+            return not value.strip()
+        return False
+
+    def _set_field(self, case: dict[str, Any], field: str, value: Any) -> None:
+        if field in case:
+            case[field] = value
+            return
+        if isinstance(case, CommentedMap):
+            case.insert(self._insert_index(case, field), field, value)
+            return
+        case[field] = value
+
+    def _insert_index(self, case: CommentedMap, field: str) -> int:
+        keys = list(case.keys())
+        try:
+            field_order_index = FIELD_ORDER.index(field)
+        except ValueError:
+            return len(keys)
+        for previous in reversed(FIELD_ORDER[:field_order_index]):
+            if previous in case:
+                return keys.index(previous) + 1
+        return len(keys)
+
+    def _list_value(self, value: Any, existing: Any) -> CommentedSeq:
+        seq = CommentedSeq()
+        if isinstance(value, str):
+            items = [line.strip() for line in value.splitlines()]
+        elif isinstance(value, list):
+            items = [str(item).strip() for item in value]
+        else:
+            items = []
+        seq.extend([item for item in items if item])
+        if isinstance(existing, CommentedSeq) and existing.fa.flow_style():
+            seq.fa.set_flow_style()
+        return seq

casebook/initializer.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Iterable
+
+
+class ProjectInitError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class ProjectInitResult:
+    project_root: Path
+    created: list[Path]
+    skipped: list[Path]
+
+
+def init_project(project_path: str | Path, force: bool = False) -> ProjectInitResult:
+    project_root = Path(project_path).expanduser().resolve()
+    if project_root.exists() and not project_root.is_dir():
+        raise ProjectInitError(f"Target exists and is not a directory: {project_root}")
+
+    project_root.mkdir(parents=True, exist_ok=True)
+    created: list[Path] = []
+    skipped: list[Path] = []
+
+    template_root = resources.files("casebook").joinpath("project_template")
+    for relative_path, template_file in _iter_template_files(template_root):
+        target = project_root / relative_path
+        if target.exists() and not force:
+            skipped.append(relative_path)
+            continue
+        if target.exists() and target.is_dir():
+            raise ProjectInitError(f"Target path is a directory: {target}")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(template_file.read_bytes())
+        created.append(relative_path)
+
+    return ProjectInitResult(
+        project_root=project_root,
+        created=created,
+        skipped=skipped,
+    )
+
+
+def _iter_template_files(root, prefix: Path = Path()) -> Iterable[tuple[Path, object]]:
+    for child in sorted(root.iterdir(), key=lambda item: item.name):
+        relative_path = prefix / child.name
+        if child.is_dir():
+            yield from _iter_template_files(child, relative_path)
+        elif child.is_file():
+            yield relative_path, child

casebook/marks.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import RLock
+from typing import Any
+
+
+class MarksStore:
+    def __init__(self, project_root: Path):
+        self.project_root = project_root.resolve()
+        self.path = self.project_root / ".casebook" / "marks.json"
+        self._lock = RLock()
+
+    def _load(self) -> dict[str, Any]:
+        if not self.path.exists():
+            return {}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except Exception:
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _save(self, marks: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(marks, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+    def all(self) -> dict[str, Any]:
+        with self._lock:
+            return self._load()
+
+    def key(self, file_path: str, case_id: str) -> str:
+        return f"{file_path}#{case_id}"
+
+    def toggle_needs_update(self, file_path: str, case_id: str) -> dict[str, Any]:
+        with self._lock:
+            marks = self._load()
+            key = self.key(file_path, case_id)
+            current = marks.get(key)
+            if current and current.get("needs_update"):
+                marks.pop(key, None)
+                marked = False
+            else:
+                marks[key] = {
+                    "needs_update": True,
+                    "updated_at": datetime.now(timezone.utc).isoformat(),
+                }
+                marked = True
+            self._save(marks)
+            return {"key": key, "marked": marked, "marks": marks}