ghost-reader 0.0.1__py3-none-any.whl

ghost_reader/project.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import uuid
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from ghost_reader.agent_loader import load_agent_yaml
+from ghost_reader.constants import AVAILABLE_PERSONAS, DEFAULT_PERSONAS, ROUND_DIRECTORIES
+from ghost_reader.errors import GhostReaderError
+from ghost_reader.io import load_yaml_file, write_yaml
+from ghost_reader.paths import project_dir, round_dir, session_dir
+from ghost_reader.time import now_iso
+from ghost_reader.validators import validate_persona
+
+
+def ensure_home(home: Path) -> None:
+    home.mkdir(parents=True, exist_ok=True)
+    (home / "personas").mkdir(parents=True, exist_ok=True)
+    (home / "templates").mkdir(parents=True, exist_ok=True)
+    for directory in ["outbox", "synced", "receipts"]:
+        (home / "telemetry" / directory).mkdir(parents=True, exist_ok=True)
+
+    config_path = home / "config.yaml"
+    if not config_path.exists():
+        write_yaml(
+            config_path,
+            {
+                "schema_version": 1,
+                "install_id": str(uuid.uuid4()),
+                "created_at": now_iso(),
+                "telemetry": {
+                    "auto_sync": False,
+                    "sync_endpoint": None,
+                    "include_private_notes": False,
+                },
+            },
+        )
+
+    persona_resources = resources.files("ghost_reader.defaults.personas")
+    for persona_id in AVAILABLE_PERSONAS:
+        target = home / "personas" / f"{persona_id}.yaml"
+        if not target.exists():
+            source = persona_resources / f"{persona_id}.yaml"
+            target.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
+
+    template_resources = resources.files("ghost_reader.defaults.templates")
+    for template_path in template_resources.iterdir():
+        if template_path.suffix == ".html":
+            target = home / "templates" / template_path.name
+            target.write_text(template_path.read_text(encoding="utf-8"), encoding="utf-8")
+
+
+def ensure_project(project_root: Path, home: Path) -> dict[str, Any]:
+    ensure_home(home)
+    root = project_dir(project_root)
+    root.mkdir(parents=True, exist_ok=True)
+    project_path = root / "project.yaml"
+    if not project_path.exists():
+        write_yaml(
+            project_path,
+            {
+                "schema_version": 1,
+                "project_id": project_root.name,
+                "created_at": now_iso(),
+                "default_personas": DEFAULT_PERSONAS,
+                "available_personas": AVAILABLE_PERSONAS,
+                "persona_selection": {
+                    "count": 3,
+                    "default_personas": DEFAULT_PERSONAS,
+                    "available_personas": AVAILABLE_PERSONAS,
+                },
+            },
+        )
+    return load_yaml_file(project_path)
+
+
+def read_config(home: Path) -> dict[str, Any]:
+    ensure_home(home)
+    return load_yaml_file(home / "config.yaml")
+
+
+def persona_brief(persona: dict[str, Any]) -> str:
+    focus = persona.get("review_focus", {})
+    primary = focus.get("primary")
+    if isinstance(primary, list) and primary:
+        return ", ".join(str(item) for item in primary)
+    reader_type = persona.get("reader_type")
+    return str(reader_type) if reader_type else ""
+
+
+def read_persona(home: Path, persona_id: str) -> dict[str, Any]:
+    agent = load_agent_yaml(home, persona_id)
+    if agent is not None:
+        persona = _persona_from_agent(agent, persona_id)
+        validate_persona(persona)
+        return persona
+
+    persona_path = home / "personas" / f"{persona_id}.yaml"
+    if persona_path.exists():
+        persona = load_yaml_file(persona_path)
+        validate_persona(persona)
+        return persona
+
+    for agent_home in _fallback_agent_homes(home):
+        agent = load_agent_yaml(agent_home, persona_id)
+        if agent is not None:
+            persona = _persona_from_agent(agent, persona_id)
+            validate_persona(persona)
+            return persona
+
+    raise GhostReaderError(
+        f"Unknown persona `{persona_id}`. Run `ghost-reader init` to install defaults."
+    )
+
+
+def _fallback_agent_homes(home: Path) -> list[Path]:
+    candidates = [Path(__file__).resolve().parents[2], Path.cwd()]
+    unique: list[Path] = []
+    home_resolved = home.resolve()
+    for candidate in candidates:
+        resolved = candidate.resolve()
+        if resolved != home_resolved and resolved not in unique:
+            unique.append(resolved)
+    return unique
+
+
+def _persona_from_agent(agent: dict[str, Any], persona_id: str) -> dict[str, Any]:
+    metadata = agent.get("metadata", {})
+    if not isinstance(metadata, dict):
+        metadata = {}
+    system = str(agent.get("system") or "")
+    return {
+        "schema_version": int(metadata.get("persona_schema_version", 1)),
+        "id": persona_id,
+        "name": _agent_display_name(agent, persona_id, system),
+        "reader_type": _extract_prefixed_value(system, "- Reader type:")
+        or str(agent.get("description") or persona_id),
+        "profile": {
+            "summary": _extract_prefixed_value(system, "- Summary:"),
+            "favorite_genres": _split_agent_list(
+                _extract_prefixed_value(system, "- Favorite genres:")
+            ),
+        },
+        "preferences": {
+            "seeks": _extract_section_list(system, "What you seek:"),
+            "dislikes": _extract_section_list(system, "What you dislike:"),
+        },
+        "review_focus": {
+            "primary": _split_agent_list(
+                _extract_prefixed_value(system, "- Primary:")
+            ),
+            "secondary": _split_agent_list(
+                _extract_prefixed_value(system, "- Secondary:")
+            ),
+        },
+        "feedback_style": {
+            "voice": _extract_prefixed_value(system, "- Voice:"),
+            "default_question": _extract_prefixed_value(
+                system, "- Default guiding question:"
+            ),
+        },
+        "agent": {
+            "name": agent.get("name"),
+            "model": agent.get("model"),
+            "description": agent.get("description"),
+            "system": agent.get("system"),
+        },
+    }
+
+
+def _agent_display_name(agent: dict[str, Any], persona_id: str, system: str) -> str:
+    first_line = system.splitlines()[0] if system else ""
+    prefix = "You are "
+    if first_line.startswith(prefix) and "," in first_line:
+        return first_line[len(prefix) : first_line.index(",")].strip()
+    name = agent.get("name")
+    if isinstance(name, str) and name:
+        return name.split("-", 1)[0].title()
+    return persona_id.title()
+
+
+def _extract_prefixed_value(text: str, prefix: str) -> str | None:
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(prefix):
+            return stripped[len(prefix) :].strip().rstrip(".")
+    return None
+
+
+def _split_agent_list(value: str | None) -> list[str]:
+    if not value:
+        return []
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def _extract_section_list(text: str, heading: str) -> list[str]:
+    items: list[str] = []
+    in_section = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped == heading:
+            in_section = True
+            continue
+        if in_section:
+            if not stripped:
+                break
+            if stripped.startswith("- "):
+                items.append(stripped[2:].strip().rstrip("."))
+    return items
+
+
+def ensure_session_structure(session_path: Path) -> None:
+    dialogue_dir = session_path / "dialogue"
+    dialogue_dir.mkdir(parents=True, exist_ok=True)
+    (session_path / "telemetry").mkdir(parents=True, exist_ok=True)
+
+    round_1 = session_path / "round-1"
+    round_1.mkdir(parents=True, exist_ok=True)
+    for child in ROUND_DIRECTORIES:
+        (round_1 / child).mkdir(parents=True, exist_ok=True)
+
+    if not (round_1 / "manifest.yaml").exists():
+        write_yaml(
+            round_1 / "manifest.yaml",
+            {
+                "round_id": 1,
+                "schema_version": 1,
+                "previous_round": None,
+                "status": "reviews_pending",
+                "refinement_count": 0,
+                "created_at": now_iso(),
+            },
+        )
+
+
+def load_manifest(project_root: Path, session_id: str) -> dict[str, Any]:
+    path = session_dir(project_root, session_id) / "manifest.yaml"
+    if not path.exists():
+        raise GhostReaderError(f"Session `{session_id}` not found.")
+    return load_yaml_file(path)
+
+
+def save_manifest(
+    project_root: Path, session_id: str, manifest: dict[str, Any]
+) -> None:
+    manifest["updated_at"] = now_iso()
+    write_yaml(session_dir(project_root, session_id) / "manifest.yaml", manifest)
+
+
+def load_round_manifest(
+    project_root: Path, session_id: str, round_id: int
+) -> dict[str, Any]:
+    path = round_dir(project_root, session_id, round_id) / "manifest.yaml"
+    if not path.exists():
+        raise GhostReaderError(f"Round `{round_id}` not found in session `{session_id}`.")
+    return load_yaml_file(path)
+
+
+def save_round_manifest(
+    project_root: Path, session_id: str, round_id: int, manifest: dict[str, Any]
+) -> None:
+    write_yaml(
+        round_dir(project_root, session_id, round_id) / "manifest.yaml", manifest
+    )
+
+
+def parse_personas(value: str | None) -> list[str]:
+    if not value:
+        return DEFAULT_PERSONAS
+    personas = [
+        part.strip() for part in value.replace(",", " ").split() if part.strip()
+    ]
+    unknown = [persona for persona in personas if persona not in AVAILABLE_PERSONAS]
+    if unknown:
+        raise GhostReaderError(f"Unknown personas: {', '.join(unknown)}")
+    return personas

ghost_reader/release.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from importlib import resources
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+GITHUB_REPO = "clchinkc/ghost-reader"
+GITHUB_REPO_URL = f"https://github.com/{GITHUB_REPO}"
+# Private repo: HTTPS install uses your git credentials; SSH URL is the reliable default.
+GITHUB_INSTALL_GIT = f"git+ssh://git@github.com/{GITHUB_REPO}.git"
+RELEASES_API = f"https://api.github.com/repos/{GITHUB_REPO}/releases/latest"
+UNAVAILABLE_STATUS = "unavailable (no network and no local release record)"
+
+
+def embedded_release_version() -> str | None:
+    """Return the packaged release marker, if this install includes one."""
+    try:
+        text = resources.files("ghost_reader").joinpath(".release-version").read_text(
+            encoding="utf-8"
+        )
+    except (FileNotFoundError, ModuleNotFoundError):
+        return None
+    version = text.strip().lstrip("v")
+    return version or None
+
+
+def fetch_latest_release() -> dict[str, Any] | None:
+    """Return latest GitHub release metadata, or None if unavailable."""
+    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "ghost-reader-cli",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    request = urllib.request.Request(
+        RELEASES_API,
+        headers=headers,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=8) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, json.JSONDecodeError):
+        return None
+
+    tag = str(payload.get("tag_name", "")).lstrip("v")
+    return {
+        "tag": payload.get("tag_name"),
+        "version": tag,
+        "published_at": payload.get("published_at"),
+        "html_url": payload.get("html_url"),
+    }

ghost_reader/report.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import json
+import os
+import shlex
+from pathlib import Path
+
+import yaml
+
+from ghost_reader.constants import TEMPLATE_VERSION
+from ghost_reader.io import load_yaml_file
+from ghost_reader.paths import artifact_paths
+from ghost_reader.project import ensure_home, load_manifest
+from ghost_reader.reviews import feedback_summary, load_reviews
+from ghost_reader.telemetry import append_event
+from ghost_reader.time import now_iso
+
+
+def ranges_overlap(start_a: int, end_a: int, start_b: int, end_b: int) -> bool:
+    return start_a <= end_b and start_b <= end_a
+
+
+def load_source_ranges(context_dir: Path) -> list[dict[str, object]]:
+    source_map_path = context_dir / "source-map.yaml"
+    if not source_map_path.exists():
+        return []
+    source_map = load_yaml_file(source_map_path)
+    normalized: list[dict[str, object]] = []
+    for item in source_map.get("source_ranges", []):
+        entry: dict[str, object] = {}
+        for field in ("source_id", "locator", "start_line", "end_line"):
+            if field in item:
+                entry[field] = item[field]
+        if "start_line" in entry and "end_line" in entry and "locator" in entry:
+            normalized.append(entry)
+    return normalized
+
+
+def source_ranges_for_lines(
+    source_ranges: list[dict[str, object]], line_start: int, line_end: int
+) -> list[dict[str, object]]:
+    matching_ranges = []
+    for item in source_ranges:
+        if not item.get("start_line") or not item.get("end_line"):
+            continue
+        if ranges_overlap(
+            line_start,
+            line_end,
+            int(item["start_line"]),
+            int(item["end_line"]),
+        ):
+            matching_ranges.append(item)
+    return matching_ranges
+
+
+def source_paragraph_payload(
+    paragraph_id: int,
+    text: str,
+    line_start: int,
+    line_end: int,
+    source_ranges: list[dict[str, object]],
+) -> dict[str, object]:
+    matching_ranges = source_ranges_for_lines(source_ranges, line_start, line_end)
+    locators = [
+        item["locator"] for item in matching_ranges if item.get("locator")
+    ]
+    if not locators:
+        locators = [f"p{paragraph_id}"]
+    return {
+        "id": paragraph_id,
+        "line_start": line_start,
+        "line_end": line_end,
+        "source_ids": [
+            item["source_id"] for item in matching_ranges if item.get("source_id")
+        ],
+        "locators": locators,
+        "text": text,
+    }
+
+
+def source_text_paragraphs(
+    text: str, source_ranges: list[dict[str, object]]
+) -> list[dict[str, object]]:
+    paragraphs: list[dict[str, object]] = []
+    current_lines: list[str] = []
+    line_start: int | None = None
+
+    def flush(line_end: int) -> None:
+        nonlocal current_lines, line_start
+        if line_start is None or not current_lines:
+            return
+        paragraph_text = "\n".join(current_lines).strip()
+        if paragraph_text and not paragraph_text.startswith("#"):
+            paragraphs.append(
+                source_paragraph_payload(
+                    len(paragraphs) + 1,
+                    paragraph_text,
+                    line_start,
+                    line_end,
+                    source_ranges,
+                )
+            )
+        current_lines = []
+        line_start = None
+
+    lines = text.splitlines()
+    for line_number, line in enumerate(lines, start=1):
+        if line.strip():
+            if line_start is None:
+                line_start = line_number
+            current_lines.append(line)
+        else:
+            flush(line_number - 1)
+    flush(len(lines))
+    return paragraphs
+
+
+def load_source_text(project_root: Path, session_id: str) -> dict[str, object]:
+    paths = artifact_paths(project_root, session_id)
+    source_path = paths["context"] / "source-text.md"
+    if not source_path.exists():
+        return {"found": False, "paragraphs": []}
+    paragraphs = source_text_paragraphs(
+        source_path.read_text(encoding="utf-8"),
+        load_source_ranges(paths["context"]),
+    )
+    return {
+        "found": bool(paragraphs),
+        "path": str(source_path),
+        "paragraphs": paragraphs,
+    }
+
+
+def load_revision_prompt(project_root: Path, session_id: str) -> dict[str, str | bool]:
+    paths = artifact_paths(project_root, session_id)
+    yaml_path = paths["prompts"] / "revision-prompt.yaml"
+    markdown_path = paths["prompts"] / "revision-prompt.md"
+    if not markdown_path.exists():
+        return {"found": False}
+    return {
+        "found": True,
+        "yaml": str(yaml_path) if yaml_path.exists() else "",
+        "markdown": str(markdown_path),
+        "text": markdown_path.read_text(encoding="utf-8"),
+    }
+
+
+def load_dialogue_threads(project_root: Path, session_id: str) -> dict[str, object]:
+    paths = artifact_paths(project_root, session_id)
+    index_path = paths["dialogue"] / "index.yaml"
+    if not index_path.exists():
+        return {}
+    index = load_yaml_file(index_path)
+    return index.get("threads", {})
+
+
+def render_report(
+    project_root: Path,
+    home: Path,
+    session_id: str,
+    command_prefix: str = "ghost-reader",
+    template_name: str = "report",
+    export_config: bool = False,
+) -> dict[str, str]:
+    ensure_home(home)
+    manifest = load_manifest(project_root, session_id)
+    reviews = load_reviews(project_root, home, session_id)
+    paths = artifact_paths(project_root, session_id)
+    report_dir = paths["report"]
+    command = command_prefix.strip() or "ghost-reader"
+    project_root_text = str(project_root)
+    current_round = manifest.get("current_round", 1)
+    round_ids = [r["id"] for r in manifest.get("rounds", [])] or [current_round]
+    payload = {
+        "schema_version": 2,
+        "template_version": TEMPLATE_VERSION,
+        "generated_at": now_iso(),
+        "session_id": session_id,
+        "template_name": template_name,
+        "current_round": current_round,
+        "round_ids": round_ids,
+        "story_unit": manifest.get("story_unit"),
+        "personas": manifest.get("personas", []),
+        "source_text": load_source_text(project_root, session_id),
+        "reviews": reviews,
+        "dialogue_threads": load_dialogue_threads(project_root, session_id),
+        "feedback_summary": feedback_summary(project_root, session_id),
+        "revision_prompt": load_revision_prompt(project_root, session_id),
+        "commands": {
+            "project_root": project_root_text,
+            "change_directory": f"cd {shlex.quote(project_root_text)}",
+            "command_prefix": command,
+            "serve": f"{command} serve --session {session_id}",
+            "feedback_add": f"{command} feedback add --session {session_id} --from -",
+            "prompt_revision": f"{command} prompt revision --session {session_id}",
+            "render": f"{command} render --session {session_id} --format {template_name} --command-prefix {shlex.quote(command)}",
+            "verify": f"{command} verify --session {session_id}",
+        },
+    }
+    report_dir.mkdir(parents=True, exist_ok=True)
+    payload_path = report_dir / "payload.json"
+    payload_path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8"
+    )
+    template_name = os.path.basename(template_name)
+    template_path = (home / "templates" / f"{template_name}.html").resolve()
+    templates_dir = (home / "templates").resolve()
+    if not str(template_path).startswith(str(templates_dir) + os.sep) and template_path != templates_dir:
+        raise ValueError(
+            f"Template path traversal detected: {template_name}"
+        )
+    if not template_path.exists():
+        raise FileNotFoundError(
+            f"Template '{template_name}.html' not found. "
+            f"Run 'ghost-reader render --session {session_id} --format list' to see available templates."
+        )
+    template = template_path.read_text(encoding="utf-8")
+    output_name = "index.html" if template_name == "report" else f"{template_name}.html"
+    html_path = report_dir / output_name
+    html_path.write_text(
+        template.replace(
+            "__GHOST_READER_PAYLOAD__", json.dumps(payload, ensure_ascii=False)
+        ),
+        encoding="utf-8",
+    )
+    append_event(
+        home,
+        project_root,
+        "html_rendered",
+        session_id,
+        meta={"review_count": len(reviews), "template": template_name, "round": current_round},
+    )
+    result = {"payload": str(payload_path), "html": str(html_path)}
+
+    if export_config:
+        source_map_path = paths["context"] / "source-map.yaml"
+        source_locators: list[str] = []
+        if source_map_path.exists():
+            source_map = load_yaml_file(source_map_path)
+            source_locators = [
+                f"{item['file']}:{item['start_line']}-{item['end_line']}"
+                for item in source_map.get("source_ranges", [])
+                if item.get("file") and item.get("start_line") and item.get("end_line")
+            ]
+
+        feedback_data = feedback_summary(project_root, session_id)
+        selected_item_ids = [item["target_id"] for item in feedback_data.get("selected_items", [])]
+
+        config = {
+            "report_version": "2.0",
+            "round": current_round,
+            "personas": manifest.get("personas", []),
+            "feedback_count": len(selected_item_ids),
+            "revision_type": "unified",
+            "source_locators": source_locators,
+        }
+        config_path = report_dir / "config.yaml"
+        config_path.write_text(
+            yaml.dump(config, default_flow_style=False, sort_keys=False),
+            encoding="utf-8",
+        )
+        result["config"] = str(config_path)
+
+    return result

ghost_reader/reviews.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ghost_reader.io import load_yaml_file
+from ghost_reader.paths import artifact_paths
+from ghost_reader.project import load_manifest, read_persona
+from ghost_reader.validators import validate_feedback, validate_review
+
+
+def feedback_summary(project_root: Path, session_id: str) -> dict[str, Any]:
+    load_manifest(project_root, session_id)
+    path = artifact_paths(project_root, session_id)["feedback"] / "feedback.yaml"
+    if not path.exists():
+        return {
+            "session_id": session_id,
+            "selected_items": [],
+            "user_notes": {},
+            "helpfulness_rating": None,
+            "feedback_found": False,
+        }
+    feedback = load_yaml_file(path)
+    validate_feedback(feedback, session_id)
+    selected_items = [
+        {"target_id": item["target_id"]} for item in feedback.get("selected_items", [])
+    ]
+    user_notes = {
+        item["target_id"]: item.get("note", "")
+        for item in feedback.get("selected_items", [])
+    }
+    return {
+        "session_id": session_id,
+        "selected_items": selected_items,
+        "user_notes": user_notes,
+        "helpfulness_rating": feedback.get("helpfulness_rating"),
+        "feedback_found": True,
+    }
+
+
+def load_reviews(
+    project_root: Path, home: Path, session_id: str
+) -> list[dict[str, Any]]:
+    manifest = load_manifest(project_root, session_id)
+    reviews = []
+    for review_path in sorted(
+        artifact_paths(project_root, session_id)["reviews"].glob("*.review.yaml")
+    ):
+        review = load_yaml_file(review_path)
+        validate_review(review, session_id)
+        persona = read_persona(home, review["persona_id"])
+        reviews.append(
+            {
+                **review,
+                "persona_name": persona["name"],
+                "reader_type": persona["reader_type"],
+                "review_focus": persona["review_focus"],
+            }
+        )
+    order = {
+        persona_id: index
+        for index, persona_id in enumerate(manifest.get("personas", []))
+    }
+    return sorted(reviews, key=lambda item: order.get(item["persona_id"], 999))
+
+
+def find_review_item(
+    review: dict[str, Any], item_id: str
+) -> tuple[str, dict[str, Any]] | None:
+    for kind in ["strengths", "concerns"]:
+        for item in review.get(kind, []):
+            if item.get("id") == item_id:
+                return kind, item
+    return None
+
+
+def compact_review_item(item: dict[str, Any]) -> dict[str, Any]:
+    locators = [
+        evidence.get("locator")
+        for evidence in item.get("evidence", [])
+        if evidence.get("locator")
+    ]
+    compact = {
+        "reason": item.get("reason"),
+        "locator": locators[0] if locators else None,
+    }
+    if item.get("revision_hint"):
+        compact["revision_hint"] = item["revision_hint"]
+    return compact