ghost-reader 0.1.0__py3-none-any.whl

ghost_reader/revision.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from ghost_reader.constants import SCHEMA_VERSIONS
+from ghost_reader.errors import GhostReaderError
+from ghost_reader.io import write_yaml
+from ghost_reader.paths import artifact_paths
+from ghost_reader.project import load_manifest
+from ghost_reader.reviews import feedback_summary, find_review_item, load_reviews
+from ghost_reader.telemetry import append_event
+
+
+def generate_revision_prompt(
+    project_root: Path,
+    home: Path,
+    session_id: str,
+    goal: str | None = None,
+    preserve: list[str] | None = None,
+) -> dict[str, str]:
+    manifest = load_manifest(project_root, session_id)
+    reviews = {
+        review["persona_id"]: review
+        for review in load_reviews(project_root, home, session_id)
+    }
+    feedback = feedback_summary(project_root, session_id)
+    if not feedback["feedback_found"]:
+        raise GhostReaderError(
+            "Feedback artifact not found. Run `ghost-reader feedback add` before generating a revision prompt."
+        )
+
+    selected_reviews: dict[str, dict[str, list[str]]] = defaultdict(
+        lambda: {"included_strengths": [], "included_concerns": []}
+    )
+    selected_details = []
+    change_hints = []
+    for selected in feedback["selected_items"]:
+        persona_id, item_id = selected["target_id"].split(":", 1)
+        review = reviews.get(persona_id)
+        if not review:
+            raise GhostReaderError(
+                f"Selected review `{selected['target_id']}` has no stored review artifact."
+            )
+        found = find_review_item(review, item_id)
+        if not found:
+            raise GhostReaderError(
+                f"Selected review item `{selected['target_id']}` was not found."
+            )
+        kind, item = found
+        bucket = "included_strengths" if kind == "strengths" else "included_concerns"
+        selected_reviews[persona_id][bucket].append(item_id)
+        selected_details.append(
+            {
+                "target_id": selected["target_id"],
+                "kind": kind[:-1],
+                "reason": item.get("reason"),
+                "locators": [
+                    evidence.get("locator")
+                    for evidence in item.get("evidence", [])
+                    if evidence.get("locator")
+                ],
+                "reader_effect": item.get("reader_effect"),
+                "revision_hint": item.get("revision_hint"),
+                "user_note": feedback["user_notes"].get(selected["target_id"], ""),
+            }
+        )
+        if item.get("revision_hint"):
+            change_hints.append(item["revision_hint"])
+
+    preserve_items = preserve or []
+    prompt_goal = (
+        goal
+        or f"Revise {manifest.get('story_unit') or session_id} using selected Ghost Reader feedback."
+    )
+    current_round = manifest.get("current_round", 1)
+    revision_prompt = {
+        "schema_version": SCHEMA_VERSIONS["revision_prompt"],
+        "session_id": session_id,
+        "round": current_round,
+        "selected_reviews": [
+            {"persona_id": persona_id, **values}
+            for persona_id, values in sorted(selected_reviews.items())
+        ],
+        "user_notes": [
+            {"target_id": target_id, "note": note}
+            for target_id, note in feedback["user_notes"].items()
+        ],
+        "revision_brief": {
+            "goal": prompt_goal,
+            "preserve": preserve_items,
+            "change": change_hints,
+        },
+        "prompt_text": build_revision_prompt_text(
+            session_id,
+            manifest.get("story_unit"),
+            project_root,
+            current_round,
+            prompt_goal,
+            preserve_items,
+            selected_details,
+        ),
+    }
+    prompt_dir = artifact_paths(project_root, session_id)["prompts"]
+    yaml_path = prompt_dir / "revision-prompt.yaml"
+    markdown_path = prompt_dir / "revision-prompt.md"
+    write_yaml(yaml_path, revision_prompt)
+    markdown_path.write_text(revision_prompt["prompt_text"], encoding="utf-8")
+    append_event(
+        home,
+        project_root,
+        "revision_prompt_generated",
+        session_id,
+        meta={
+            "selected_review_item_ids": [
+                item["target_id"] for item in feedback["selected_items"]
+            ]
+        },
+    )
+    return {"yaml": str(yaml_path), "markdown": str(markdown_path)}
+
+
+def build_revision_prompt_text(
+    session_id: str,
+    story_unit: str | None,
+    project_root: Path,
+    current_round: int,
+    goal: str,
+    preserve: list[str],
+    selected_details: list[dict[str, Any]],
+) -> str:
+    lines = [
+        "# Ghost Reader Revision Handoff",
+        "",
+        f"Session: {session_id}",
+        f"Round: {current_round}",
+        f"Story unit: {story_unit or session_id}",
+        f"Story project root: {project_root}",
+        f"Session artifacts: .ghostreader/sessions/{session_id}/",
+        "",
+        f"Goal: {goal}",
+        "",
+        "Source handling:",
+        "- Use source text already visible in the current conversation or available from the story project.",
+        "- If only source locators are available, ask for the affected passages before drafting revised prose.",
+        "- Do not reconstruct missing prose from review summaries, locators, or memory.",
+        "",
+    ]
+    if preserve:
+        lines.append("Preserve:")
+        lines.extend(f"- {item}" for item in preserve)
+        lines.append("")
+    lines.append("Selected feedback:")
+    for detail in selected_details:
+        lines.append(f"- {detail['target_id']} ({detail['kind']}): {detail['reason']}")
+        if detail.get("locators"):
+            lines.append(f"  Source locators: {', '.join(detail['locators'])}")
+        if detail.get("reader_effect"):
+            lines.append(f"  Reader effect: {detail['reader_effect']}")
+        if detail.get("revision_hint"):
+            lines.append(f"  Revision hint: {detail['revision_hint']}")
+        if detail.get("user_note"):
+            lines.append(f"  User note: {detail['user_note']}")
+    return "\n".join(lines) + "\n"

ghost_reader/round.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from ghost_reader.constants import ROUND_DIRECTORIES
+from ghost_reader.errors import GhostReaderError
+from ghost_reader.paths import active_round_dir, round_dir
+from ghost_reader.project import (
+    load_manifest,
+    load_round_manifest,
+    save_manifest,
+    save_round_manifest,
+)
+from ghost_reader.telemetry import append_event
+from ghost_reader.time import now_iso
+
+
+def ensure_round_structure(round_path: Path) -> None:
+    for child in ROUND_DIRECTORIES:
+        (round_path / child).mkdir(parents=True, exist_ok=True)
+
+
+def round_init(
+    project_root: Path,
+    home: Path,
+    session_id: str,
+    story_unit: str | None = None,
+    source_file: str | None = None,
+) -> dict[str, Any]:
+    manifest = load_manifest(project_root, session_id)
+    current = manifest.get("current_round", 1)
+    new_round = current + 1
+    rp = round_dir(project_root, session_id, new_round)
+    rp.mkdir(parents=True, exist_ok=True)
+    ensure_round_structure(rp)
+
+    if source_file:
+        src = Path(source_file)
+        if not src.exists():
+            raise GhostReaderError(f"Source file not found: {source_file}")
+        shutil.copy2(src, rp / "context" / "source-text.md")
+
+    save_round_manifest(
+        project_root,
+        session_id,
+        new_round,
+        {
+            "round_id": new_round,
+            "schema_version": 1,
+            "previous_round": current,
+            "status": "reviews_pending",
+            "refinement_count": 0,
+            "created_at": now_iso(),
+        },
+    )
+
+    manifest["current_round"] = new_round
+    manifest.setdefault("rounds", []).append(
+        {
+            "id": new_round,
+            "status": "reviews_pending",
+            "created_at": now_iso(),
+            "refinement_count": 0,
+        }
+    )
+    if story_unit:
+        manifest["story_unit"] = story_unit
+    save_manifest(project_root, session_id, manifest)
+
+    append_event(
+        home,
+        project_root,
+        "round_created",
+        session_id,
+        meta={"round_id": new_round, "previous_round": current},
+    )
+
+    return {"round_id": new_round, "path": str(rp), "status": "reviews_pending"}
+
+
+def round_status(project_root: Path, session_id: str) -> dict[str, Any]:
+    manifest = load_manifest(project_root, session_id)
+    rounds_output: list[dict[str, Any]] = []
+    for entry in manifest.get("rounds", []):
+        rid = entry["id"]
+        try:
+            rm = load_round_manifest(project_root, session_id, rid)
+        except GhostReaderError:
+            rm = {}
+        rp = round_dir(project_root, session_id, rid)
+        reviews_dir = rp / "reviews"
+        review_files = (
+            list(reviews_dir.glob("*.review.yaml"))
+            if reviews_dir.exists()
+            else []
+        )
+        rounds_output.append(
+            {
+                "id": rid,
+                "status": rm.get("status", entry.get("status", "unknown")),
+                "refinement_count": rm.get("refinement_count", 0),
+                "review_count": len(review_files),
+                "created_at": rm.get("created_at", entry.get("created_at", "")),
+            }
+        )
+    return {
+        "session_id": session_id,
+        "current_round": manifest.get("current_round", 1),
+        "rounds": rounds_output,
+    }
+
+
+def refine_snapshot(
+    project_root: Path, home: Path, session_id: str
+) -> dict[str, Any]:
+    manifest = load_manifest(project_root, session_id)
+    current = manifest.get("current_round", 1)
+    rm = load_round_manifest(project_root, session_id, current)
+    current_refinement = rm.get("refinement_count", 0)
+    new_pass = current_refinement + 1
+
+    active = active_round_dir(project_root, session_id)
+    snapshot_dir = active / "refinements" / f"{new_pass:03d}"
+    snapshot_dir.mkdir(parents=True, exist_ok=True)
+
+    reviews_src = active / "reviews"
+    if reviews_src.exists() and any(reviews_src.iterdir()):
+        shutil.copytree(reviews_src, snapshot_dir / "reviews", dirs_exist_ok=True)
+
+    feedback_src = active / "feedback" / "feedback.yaml"
+    if feedback_src.exists():
+        (snapshot_dir / "feedback").mkdir(parents=True, exist_ok=True)
+        shutil.copy2(feedback_src, snapshot_dir / "feedback" / "feedback.yaml")
+
+    rm["refinement_count"] = new_pass
+    save_round_manifest(project_root, session_id, current, rm)
+
+    for entry in manifest.get("rounds", []):
+        if entry["id"] == current:
+            entry["refinement_count"] = new_pass
+            entry["status"] = rm.get("status", entry.get("status", "unknown"))
+            break
+    save_manifest(project_root, session_id, manifest)
+
+    append_event(
+        home,
+        project_root,
+        "refinement_snapshot_created",
+        session_id,
+        meta={"round_id": current, "refinement_pass": new_pass},
+    )
+
+    return {"written": True, "path": str(snapshot_dir), "refinement_pass": new_pass}

ghost_reader/server.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from ghost_reader.dialogue import dialogue_append, load_all_dialogue
+from ghost_reader.errors import GhostReaderError
+from ghost_reader.feedback_store import record_feedback
+from ghost_reader.paths import artifact_paths
+from ghost_reader.project import load_manifest
+from ghost_reader.report import render_report
+from ghost_reader.reviews import feedback_summary
+from ghost_reader.verify import verify_session
+
+# Set by serve_report after successful bind so tests can discover the actual port
+_bound_port: int | None = None
+
+
+def _cors_headers(handler: SimpleHTTPRequestHandler) -> None:
+    origin = handler.headers.get("Origin", "")
+    if origin:
+        try:
+            hostname = urlparse(origin).hostname
+            if hostname in ("127.0.0.1", "localhost", "::1"):
+                handler.send_header("Access-Control-Allow-Origin", origin)
+        except Exception:
+            pass
+    handler.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+    handler.send_header("Access-Control-Allow-Headers", "Content-Type")
+
+
+def _json_response(handler: SimpleHTTPRequestHandler, data: dict[str, Any], status: int = 200) -> None:
+    body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json; charset=utf-8")
+    handler.send_header("Content-Length", str(len(body)))
+    handler.end_headers()
+    handler.wfile.write(body)
+
+
+MAX_BODY_SIZE = 1_048_576  # 1 MiB
+
+
+def _read_body(handler: SimpleHTTPRequestHandler) -> dict[str, Any] | None:
+    length = int(handler.headers.get("Content-Length", 0))
+    if not length:
+        return None
+    if length > MAX_BODY_SIZE:
+        return None
+    return json.loads(handler.rfile.read(length))
+
+
+class _FeedbackHandler(SimpleHTTPRequestHandler):
+    project_root: Path
+    home: Path
+    session_id: str
+    report_subpath: str = ""
+
+    def log_message(self, fmt: str, *args: Any) -> None:
+        self.server._last_active = time.time()
+
+    def end_headers(self) -> None:
+        _cors_headers(self)
+        super().end_headers()
+
+    def do_OPTIONS(self) -> None:
+        self.send_response(200)
+        _cors_headers(self)
+        self.end_headers()
+
+    def do_POST(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/api/feedback":
+            self._handle_feedback()
+        elif parsed.path == "/api/dialogue":
+            self._handle_dialogue()
+        else:
+            self.send_error(404)
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/api/state":
+            self._handle_state()
+        elif parsed.path in ("/", "") and self.report_subpath:
+            self.send_response(302)
+            self.send_header("Location", f"/{self.report_subpath}")
+            self.end_headers()
+        else:
+            super().do_GET()
+
+    def _handle_feedback(self) -> None:
+        try:
+            body = _read_body(self)
+            if not body:
+                return _json_response(self, {"error": "empty body"}, 400)
+            feedback_path = record_feedback(
+                self.project_root,
+                self.home,
+                self.session_id,
+                body,
+                surface="html",
+            )
+            _json_response(self, {"ok": True, "path": str(feedback_path)})
+        except GhostReaderError as exc:
+            _json_response(self, {"error": str(exc)}, 400)
+        except Exception:
+            _json_response(self, {"error": "internal server error"}, 500)
+
+    def _handle_dialogue(self) -> None:
+        try:
+            body = _read_body(self)
+            if not body:
+                return _json_response(self, {"error": "empty body"}, 400)
+            persona_id = body.get("persona_id")
+            text = body.get("text")
+            if not persona_id or not text:
+                return _json_response(self, {"error": "persona_id and text required"}, 400)
+            result = dialogue_append(
+                self.project_root,
+                self.home,
+                self.session_id,
+                persona_id,
+                body.get("item_id", ""),
+                text,
+                thread_id=body.get("thread_id"),
+                round_id=body.get("round_id"),
+                item_uid=body.get("item_uid"),
+            )
+            _json_response(self, {"ok": True, "thread_id": result["thread_id"], "turn_index": result["turn_index"]})
+        except GhostReaderError as exc:
+            _json_response(self, {"error": str(exc)}, 400)
+        except Exception:
+            _json_response(self, {"error": "internal server error"}, 500)
+
+    def _handle_state(self) -> None:
+        try:
+            manifest = load_manifest(self.project_root, self.session_id)
+            try:
+                verification = verify_session(self.project_root, self.home, self.session_id)
+            except Exception:
+                verification = {"status": "incomplete", "ok": False}
+            feedback = feedback_summary(self.project_root, self.session_id)
+            dialogue = load_all_dialogue(
+                self.project_root, self.session_id, manifest.get("personas", [])
+            )
+            _json_response(self, {
+                "session_id": self.session_id,
+                "current_round": manifest.get("current_round", 1),
+                "verification_status": verification.get("status"),
+                "feedback_items": feedback.get("selected_items", []),
+                "dialogue_threads": _serialize_threads(dialogue),
+                "rounds": manifest.get("rounds", []),
+                "story_unit": manifest.get("story_unit"),
+                "personas": manifest.get("personas", []),
+            })
+        except GhostReaderError as exc:
+            _json_response(self, {"error": str(exc)}, 400)
+        except Exception:
+            _json_response(self, {"error": "internal server error"}, 500)
+
+
+def _serialize_threads(dialogue: dict[str, list[dict[str, Any]]]) -> dict[str, list[dict[str, Any]]]:
+    result: dict[str, list[dict[str, Any]]] = {}
+    for persona_id, turns in dialogue.items():
+        serialized = []
+        for turn in turns:
+            serialized.append({
+                "turn_index": turn.get("turn_index"),
+                "timestamp": turn.get("timestamp"),
+                "user": turn.get("user", ""),
+                "persona": turn.get("persona", ""),
+                "thread_id": turn.get("thread_id", ""),
+            })
+        if serialized:
+            result[persona_id] = serialized
+    return result
+
+
+def _build_handler_class(project_root: Path, home: Path, session_id: str, report_subpath: str = "") -> type[_FeedbackHandler]:
+    class _BoundHandler(_FeedbackHandler):
+        pass
+
+    _BoundHandler.project_root = project_root
+    _BoundHandler.home = home
+    _BoundHandler.session_id = session_id
+    _BoundHandler.directory = str(project_root)
+    _BoundHandler.report_subpath = report_subpath
+    return _BoundHandler
+
+
+def serve_report(
+    project_root: Path,
+    home: Path,
+    session_id: str,
+    port: int = 8765,
+    timeout: int = 0,
+    render: bool | None = None,
+    command_prefix: str = "ghost-reader",
+    template_name: str = "report",
+    pipe_wfd: int | None = None,
+) -> str:
+    payload_path = artifact_paths(project_root, session_id)["report"] / "payload.json"
+    should_render = render if render is not None else not payload_path.exists()
+    if should_render:
+        print("Auto-rendering report...")
+        render_report(project_root, home, session_id, command_prefix, template_name)
+
+    handler_class = _build_handler_class(project_root, home, session_id)
+    global _bound_port
+    _bound_port = None  # Reset so each serve_report call gets a fresh port
+    actual_port = port
+    server = None
+    for attempt in range(port, port + 100):
+        try:
+            server = HTTPServer(("127.0.0.1", attempt), handler_class)
+            actual_port = server.server_address[1]
+            _bound_port = actual_port
+            break
+        except OSError:
+            continue
+    if server is None:
+        raise RuntimeError(f"Could not bind to any port starting from {port}")
+
+    url = f"http://localhost:{actual_port}"
+    manifest = load_manifest(project_root, session_id)
+    current_round = manifest.get("current_round", 1)
+    report_rel = f".ghostreader/sessions/{session_id}/round-{current_round}/report/index.html"
+    handler_class.report_subpath = report_rel
+    print(f"Ghost Reader serving at {url}/{report_rel}")
+
+    # Communicate port to parent AFTER all fallible setup completes
+    # but BEFORE entering the blocking serve loop. If load_manifest or
+    # any other setup step fails, the child's except block writes
+    # "error\n" to the pipe and the parent never sees "ok:", avoiding
+    # a silent crash where the parent thinks the server is running.
+    if pipe_wfd is not None:
+        os.write(pipe_wfd, f"ok:{actual_port}\n".encode())
+
+    if timeout > 0:
+        _run_with_timeout(server, url, timeout, session_id)
+    else:
+        _run_forever(server)
+    return url
+
+
+def _run_forever(server: HTTPServer) -> None:
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+        print("Server stopped")
+
+
+def _run_with_timeout(
+    server: HTTPServer, url: str, timeout: int, session_id: str
+) -> None:
+    server._last_active = time.time()
+    server.timeout = 1.0
+    try:
+        while True:
+            server.handle_request()
+            if time.time() - server._last_active > timeout:
+                print(
+                    f"\nGhost Reader server idle for {timeout}s — shutting down.\n"
+                    f"Tip: use `ghost-reader serve --session {session_id} --detach` "
+                    f"for review sessions where you need time to deliberate.\n",
+                    file=sys.stderr,
+                )
+                break
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+        print("Server stopped")