cli.py

"""
cli.py — Operator CLI for the APDT Product Agent Framework.

PURPOSE
-------
A practical terminal interface for running and inspecting product analysis
workflows during local development and debugging.

USAGE
-----
    # Workflow
    python cli.py --prompt "Analyse my product idea"
    python cli.py --prompt "..." --thread-id <existing-thread-id>
    python cli.py --prompt "..." --product-context config/products/my_product.yaml
    python cli.py --prompt "..." --verbose
    python cli.py --prompt "..." --save --project-name "MyApp"
    python cli.py --prompt "..." --no-product-context
    python cli.py --prompt "..." --save --auto-refresh-index

    # Index management (--prompt not required)
    python cli.py --show-pending-index
    python cli.py --refresh-index
    python cli.py --rebuild-index
    python cli.py --show-pending-index --project-name "MyApp"

    # Conversation deletion (--prompt not required)
    python cli.py --delete-conversation "InvoiceAI Analysis"
    python cli.py --delete-conversation "InvoiceAI Analysis" --deep-delete
    python cli.py --show-conversations

DESIGN NOTES
------------
This CLI is intentionally thin — it orchestrates inputs and display only.
All workflow logic lives in src/graph/workflow.py.

TODO: A future UI layer may replace or extend this CLI.  The display helper
functions below (_print_run_header, _print_artefacts, etc.) are designed to
be reusable from any text-based output context.
"""

import argparse
import sys
from pathlib import Path
from typing import Any, Dict, Optional

# Default product context path — loaded automatically if no --product-context given.
# Set --no-product-context to run without any product context.
_DEFAULT_CONTEXT_PATH = "config/products/default_product_context.yaml"

# Terminal separator width
_WIDTH = 64


# ---------------------------------------------------------------------------
# Argument parsing
# ---------------------------------------------------------------------------

def _parse_args(argv=None) -> argparse.Namespace:
    """Parse command-line arguments. Returns a Namespace object."""
    parser = argparse.ArgumentParser(
        prog="cli.py",
        description="APDT Product Agent Framework — operator CLI",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "examples:\n"
            '  python cli.py --prompt "Analyse my invoice OCR SaaS idea"\n'
            "  python cli.py --prompt \"...\" --thread-id abc-123\n"
            "  python cli.py --prompt \"...\" --product-context config/products/my_product.yaml\n"
            "  python cli.py --prompt \"...\" --verbose\n"
            "  python cli.py --prompt \"...\" --save --project-name InvoiceAI\n"
            "  python cli.py --delete-conversation \"My Analysis\"\n"
            "  python cli.py --delete-conversation \"My Analysis\" --deep-delete\n"
            "  python cli.py --show-conversations\n"
        ),
    )

    parser.add_argument(
        "--prompt", "-p",
        required=False,
        default=None,
        metavar="TEXT",
        help=(
            "Product analysis prompt or question. "
            "Required unless using --show-pending-index, --refresh-index, or --rebuild-index."
        ),
    )
    parser.add_argument(
        "--file", "-f",
        action="append",
        metavar="PATH",
        default=None,
        dest="files",
        help=(
            "Path to a document (.pdf or .docx) to include as context for this run. "
            "Can be specified multiple times: --file doc1.pdf --file doc2.docx. "
            "By default, documents are conversation-scoped only. "
            "Use --persist-doc to save them to durable project memory."
        ),
    )
    parser.add_argument(
        "--persist-doc",
        action="store_true",
        default=False,
        help=(
            "Persist uploaded documents to durable project memory after the run. "
            "Has no effect if no --file arguments are given. "
            "Documents are stored under data/documents/ and tracked in SQLite."
        ),
    )
    parser.add_argument(
        "--auto-embed",
        action="store_true",
        default=False,
        help=(
            "Index persisted documents into the FAISS vector store immediately. "
            "Only meaningful when --persist-doc is also set."
        ),
    )
    parser.add_argument(
        "--thread-id",
        metavar="ID",
        default=None,
        help=(
            "Thread ID for continuing an existing conversation. "
            "If omitted, a new thread is started automatically."
        ),
    )
    parser.add_argument(
        "--product-context",
        metavar="YAML_FILE",
        default=_DEFAULT_CONTEXT_PATH,
        help=(
            f"Path to a product context YAML file. "
            f"Defaults to {_DEFAULT_CONTEXT_PATH}. "
            f"Ignored if --no-product-context is set."
        ),
    )
    parser.add_argument(
        "--no-product-context",
        action="store_true",
        default=False,
        help="Skip loading any product context file, even the default.",
    )
    parser.add_argument(
        "--verbose", "-v",
        action="store_true",
        default=False,
        help="Show verbose/debug output including per-node progress and per-agent token detail.",
    )
    parser.add_argument(
        "--save",
        action="store_true",
        default=False,
        help=(
            "Persist workflow results (decisions, risks, usage) to SQLite after the run. "
            "Uses the db path from config/settings.yaml unless overridden there."
        ),
    )
    parser.add_argument(
        "--project-name",
        metavar="NAME",
        default=None,
        help=(
            "Project name for SQLite records (used with --save). "
            "Defaults to product_name from the product context, or 'default'."
        ),
    )

    # --- Index management flags ---
    parser.add_argument(
        "--show-pending-index",
        action="store_true",
        default=False,
        help=(
            "Show document indexing status for the current project. "
            "Can be used standalone (no --prompt required) or combined with a run."
        ),
    )
    parser.add_argument(
        "--refresh-index",
        action="store_true",
        default=False,
        help=(
            "Run an incremental index refresh: only index pending, stale, or failed "
            "documents.  Does NOT clear the FAISS index.  Safe to run any time."
        ),
    )
    parser.add_argument(
        "--rebuild-index",
        action="store_true",
        default=False,
        help=(
            "⚠  Full rebuild: clear the FAISS index and re-index ALL documents. "
            "Non-document content (decisions, artefacts) must be re-seeded afterwards "
            "via scripts/seed_project.py.  Requires interactive confirmation."
        ),
    )
    parser.add_argument(
        "--auto-refresh-index",
        action="store_true",
        default=False,
        help=(
            "After a workflow run with --save, automatically run an incremental index "
            "refresh for any newly pending documents.  Only indexes the delta — "
            "already-indexed documents are not touched."
        ),
    )

    # --- Conversation deletion flags ---
    parser.add_argument(
        "--delete-conversation",
        metavar="NAME_OR_THREAD_ID",
        default=None,
        help=(
            "Delete a named conversation.  Accepts the human-readable conversation "
            "name (as shown in sidebar/--show-conversations) OR the raw thread_id UUID. "
            "By default performs a safe Mode A delete: removes the conversation record "
            "and message history only.  Add --deep-delete to also remove all "
            "thread-attributed memory, documents, and usage logs.  Requires confirmation."
        ),
    )
    parser.add_argument(
        "--deep-delete",
        action="store_true",
        default=False,
        help=(
            "Used with --delete-conversation.  Enables Mode B (deep delete): removes "
            "the conversation AND all related persistent content attributed to it — "
            "decisions, risks, persisted documents (+ disk files), usage logs, etc. "
            "FAISS vector chunks for deleted indexed documents are NOT removed; run "
            "--rebuild-index afterwards to clean the vector index."
        ),
    )
    parser.add_argument(
        "--show-conversations",
        action="store_true",
        default=False,
        help=(
            "List all named conversations stored in the database, with their "
            "thread IDs and last-used timestamps.  No changes are made."
        ),
    )

    return parser.parse_args(argv)


# ---------------------------------------------------------------------------
# Document helpers
# ---------------------------------------------------------------------------


def _load_documents(file_paths: list, thread_id=None) -> list:
    """
    Parse a list of document file paths using ``ingest_file``.

    Prints a summary line for each file (success or failure) so the operator
    can immediately see what was loaded.  Always returns a list of
    UploadedDocument objects — failed documents are included with
    parse_success=False so callers can inspect them.

    Args:
        file_paths: List of file-system paths to documents.
        thread_id:  Optional thread ID to attach to each document record.

    Returns:
        list[UploadedDocument]: One object per file (success or failure).
    """
    from src.tools.document_ingestion import ingest_file

    _sep("-")
    print("DOCUMENTS")
    _sep("-")

    docs = []
    for path in file_paths:
        doc = ingest_file(path, thread_id=thread_id)
        if doc.parse_success:
            print(
                f"  ✓ {doc.file_name}  "
                f"({doc.file_type.upper()}, {len(doc.extracted_text):,} chars extracted)"
            )
        else:
            print(f"  ✗ {doc.file_name}: {doc.parse_error}")
        docs.append(doc)
    print()
    return docs


def _persist_documents(docs: list, project_name: str, auto_embed: bool) -> None:
    """
    Persist successfully-parsed documents to durable project memory.

    Called when the operator passes --persist-doc.  Any documents that failed
    to parse are skipped with a warning; the rest are written to disk, a
    metadata record is inserted into SQLite, and (if --auto-embed was set)
    their chunks are indexed into FAISS.

    Args:
        docs:         List of UploadedDocument objects from the run.
        project_name: Project namespace for storage and SQLite records.
        auto_embed:   If True, immediately index each persisted document.
    """
    from src.tools.document_memory import persist_document

    _sep("-")
    print("PERSISTING DOCUMENTS TO PROJECT MEMORY")
    _sep("-")
    for doc in docs:
        if not doc.parse_success:
            print(f"  ⚠  Skipping {doc.file_name} — parse failed")
            continue
        try:
            result = persist_document(
                doc,
                project_name=project_name,
                persistence_source="cli",
                auto_embed=auto_embed,
            )
            if result.get("error"):
                print(
                    f"  ✗ {doc.file_name}: {result['error']}"
                )
            elif result["embedded"]:
                print(
                    f"  ✓ Persisted + indexed "
                    f"({result['chunk_count']} chunks): {doc.file_name}"
                )
            else:
                print(f"  ✓ Persisted (not yet indexed): {doc.file_name}")
        except Exception as exc:
            print(f"  ✗ Failed to persist {doc.file_name}: {exc}")
    print()


def _print_documents(state) -> None:
    """
    Print a summary of documents that were attached to the run.

    Shows file name, type, parse status, and character count for each doc.
    Skipped entirely if no documents were attached.
    """
    docs = state.uploaded_documents or []
    if not docs:
        return

    _sep("-")
    print("UPLOADED DOCUMENTS")
    _sep("-")
    for doc in docs:
        if doc.parse_success:
            print(
                f"  ✓ [{doc.file_type.upper()}] {doc.file_name}  "
                f"({len(doc.extracted_text):,} chars)"
            )
            if doc.preview:
                print(f"     Preview: {doc.preview[:80]}...")
        else:
            print(f"  ✗ [{doc.file_type.upper()}] {doc.file_name}: {doc.parse_error}")


# ---------------------------------------------------------------------------
# Product context loading
# ---------------------------------------------------------------------------

def _load_product_context(
    path: str,
    is_default: bool = False,
) -> Optional[Dict[str, Any]]:
    """
    Load a product context YAML file and return it as a dict.

    Args:
        path:       Path to the YAML file.
        is_default: When True, a missing file is silently ignored and None
                    is returned so the run can proceed without context.
                    When False (explicit --product-context path), a missing
                    file prints a clear error and exits.

    Returns:
        dict: Loaded product context.
        None: File not found and is_default=True (run without context).
    """
    try:
        import yaml
    except ImportError:
        raise ValueError(
            "PyYAML is required to load product context files.\n"
            "Install it with: pip install pyyaml"
        )

    file_path = Path(path)

    if not file_path.exists():
        if is_default:
            # Default file missing is fine — proceed without product context
            return None
        raise ValueError(f"Product context file not found: {path}")

    try:
        with file_path.open("r", encoding="utf-8") as f:
            context = yaml.safe_load(f)
        if not isinstance(context, dict):
            raise ValueError(
                f"Product context file must be a YAML mapping (key: value pairs): {path}"
            )
        return context
    except ValueError:
        raise
    except Exception as exc:
        raise ValueError(f"Failed to parse product context file: {path}\n{exc}") from exc


# ---------------------------------------------------------------------------
# Display helpers
# ---------------------------------------------------------------------------

def _sep(char: str = "=") -> None:
    """Print a full-width separator line."""
    print(char * _WIDTH)


def _print_run_header(state, is_new_thread: bool) -> None:
    """Print the top identity block shown immediately after workflow completion."""
    _sep()
    print("APDT — RUN COMPLETE")
    _sep()
    thread_label = "NEW THREAD" if is_new_thread else "EXISTING THREAD"
    print(f"  Thread   : {state.thread_id}  [{thread_label}]")
    print(f"  Run ID   : {state.run_id}")
    print(f"  Stage    : {state.workflow_stage}")
    print(f"  Duration : {state.total_execution_time:.1f}s")


def _print_agents_and_retrieval(state) -> None:
    """Print agent selection and retrieval status."""
    _sep("-")
    print("AGENTS & RETRIEVAL")
    _sep("-")

    agents = state.selected_agents or []
    ran_set = set(state.agent_outputs.keys()) if state.agent_outputs else set()
    print(f"  Selected agents    : {len(agents)}")
    for name in agents:
        ran_mark = "✓" if name in ran_set else "—"
        print(f"    {ran_mark}  {name}")

    icon = {
        "success": "✓",
        "empty": "○",
        "failed": "✗",
        "not_attempted": "—",
    }.get(state.retrieval_status, "?")
    print(f"  Retrieval status   : {icon}  {state.retrieval_status}")
    print(f"  Retrieval items    : {state.retrieval_item_count}")

    if state.specialist_round_count:
        print(f"  Specialist rounds  : {state.specialist_round_count}")


def _print_approval_status(state) -> None:
    """Print approval and guardrail status."""
    _sep("-")
    print("APPROVAL & GUARDRAILS")
    _sep("-")

    if state.approval_required:
        print(f"  ⚠  Approval REQUIRED  (status: {state.approval_status})")
        if state.approval_context:
            print(f"     Reason : {state.approval_context}")
        if state.approval_status == "pending":
            print(f"     Action : Review the analysis above, then re-run with")
            print(f"              --thread-id {state.thread_id} to continue.")
    else:
        print(f"  ✓  No approval required  (status: {state.approval_status})")

    if state.guardrail_triggered:
        print(f"  ⚠  Guardrail triggered  : {state.guardrail_reason or 'limit exceeded'}")
    else:
        print(f"  ✓  No guardrails triggered")


def _handle_inline_approval(state, args) -> Optional[Any]:
    """
    Interactively prompt the operator to approve or reject a pending workflow.

    Presents a console menu with four choices:
      [A] Approve — continues the workflow to finalize_response.
      [R] Reject  — marks the workflow as rejected and ends it.
      [D] Details — prints extra context (guardrail reason, risks, build package).
      [Q] Quit    — leaves the workflow pending; thread can be resumed later.

    Args:
        state: The GraphState currently in "pending" approval status.
        args:  Parsed CLI arguments (used for the --thread-id hint).

    Returns:
        The updated GraphState if the operator approved or rejected, or
        None if they chose to quit without deciding.
    """
    from src.graph.workflow import resume_workflow_with_approval

    print()
    _sep()
    print("HUMAN-IN-THE-LOOP APPROVAL REQUIRED")
    _sep()
    print()
    print("  The workflow has paused and requires your review before")
    print("  proceeding to the final report.")
    print()

    reason = state.approval_context or state.guardrail_reason or "No reason given."
    print(f"  Reason : {reason}")
    print()

    while True:
        print("  [A] Approve  — continue to final report")
        print("  [R] Reject   — halt this run")
        print("  [D] Details  — show extra context")
        print("  [Q] Quit     — leave pending (re-run with --thread-id to resume)")
        print()
        try:
            choice = input("  Your choice: ").strip().upper()
        except (KeyboardInterrupt, EOFError):
            choice = "Q"
        print()

        if choice == "A":
            print("  Approving workflow…")
            updated = resume_workflow_with_approval(
                thread_id=state.thread_id,
                decision="approved",
                approver="cli-operator",
                verbose=args.verbose,
            )
            if updated:
                print()
                _sep()
                print("  Workflow resumed and finalized after approval.")
                _sep()
                _print_artefacts(updated)
                _print_consolidated_response(updated, verbose=args.verbose)
                _print_usage_summary(updated)
            return updated

        elif choice == "R":
            rejection_reason = input("  Rejection reason (or press Enter to skip): ").strip()
            print()
            print("  Rejecting workflow…")
            updated = resume_workflow_with_approval(
                thread_id=state.thread_id,
                decision="rejected",
                reason=rejection_reason or None,
                verbose=args.verbose,
            )
            print()
            _sep()
            print("  Workflow REJECTED.")
            _sep()
            return updated

        elif choice == "D":
            _sep("-")
            print("APPROVAL DETAIL")
            _sep("-")
            print(f"  Thread ID     : {state.thread_id}")
            print(f"  Approval stage: {state.workflow_stage}")
            print(f"  Reason        : {reason}")
            if state.guardrail_reason:
                print(f"  Guardrail     : {state.guardrail_reason}")
            cr = state.consolidated_response or {}
            risks = cr.get("risk_assessment") or []
            if risks:
                print(f"  Risks ({len(risks)}):")
                for r in risks[:5]:
                    rt = r if isinstance(r, str) else r.get("text", str(r))
                    print(f"    - {rt[:100]}")
                if len(risks) > 5:
                    print(f"    … and {len(risks) - 5} more")
            bp = state.build_package
            if bp:
                print(f"  Build package : {bp.title}  ({len(bp.scope)} scope items)")
            print()

        elif choice == "Q":
            print("  Leaving workflow pending.")
            print(f"  Re-run with --thread-id {state.thread_id} to resume.")
            print()
            return None

        else:
            print("  Invalid choice — please enter A, R, D, or Q.")
            print()


def _print_warnings_errors(state) -> None:
    """Print warnings and errors — skipped entirely when there are none."""
    errors = state.errors or []
    warnings = state.warnings or []
    if not errors and not warnings:
        return

    _sep("-")
    print("WARNINGS & ERRORS")
    _sep("-")
    for err in errors:
        severity = "CRITICAL" if not err.recoverable else "ERROR  "
        print(f"  [{severity}] {err.error_type}: {err.message}")
    for warn in warnings:
        print(f"  [WARN   ] {warn.warning_type}: {warn.message}")


def _print_artefacts(state) -> None:
    """Print the list of artefacts written to disk during the run."""
    _sep("-")
    print("ARTEFACTS")
    _sep("-")

    artefacts = state.artefacts_written or []
    if not artefacts:
        print("  None written")
        return

    print(f"  {len(artefacts)} artefact(s) written:")
    for a in artefacts:
        size_str = f"  ({a.file_size_bytes:,} bytes)" if a.file_size_bytes else ""
        print(f"    [{a.artifact_type}] {a.title}")
        if a.file_path:
            print(f"             → {a.file_path}{size_str}")

    build_types = {"build_package", "copilot_handoff"}
    build_artefacts = [a for a in artefacts if a.artifact_type in build_types]
    if build_artefacts:
        print()
        print("  BUILD PACKAGE:")
        for a in build_artefacts:
            print(f"    {a.file_path}")


def _print_consolidated_response(state, verbose: bool = False) -> None:
    """
    Print the consolidated response.

    G2: shows the full conversational prose answer as primary output.
    Falls back to assembled sections for pre-G2 states.
    In verbose mode: also shows specialist counts, risks, and next actions.
    """
    _sep("-")
    print("CONSOLIDATED RESPONSE")
    _sep("-")

    cr = state.consolidated_response or {}
    if not cr:
        print("  No consolidated response available")
        return

    # G2 primary: full conversational prose answer
    prose = cr.get("conversational_response") or cr.get("synthesis_analysis") or ""
    if prose:
        print()
        for line in _wrap_text(str(prose), width=76, indent="  "):
            print(line)
        print()
    else:
        # Pre-G2 fallback: structured fields
        summary = cr.get("executive_summary") or cr.get("summary") or ""
        if summary:
            print("  Summary:")
            for line in _wrap_text(str(summary), width=56, indent="    "):
                print(line)
            print()

        recs = cr.get("recommendations") or []
        if recs:
            print(f"  Recommendations ({len(recs)}):")
            for i, rec in enumerate(recs[:5], 1):
                rec_text = rec if isinstance(rec, str) else rec.get("text", str(rec))
                print(f"    {i}. {str(rec_text)[:100]}")
            if len(recs) > 5:
                print(f"    ... and {len(recs) - 5} more (run with --verbose to see all)")

    if verbose:
        specialist_count = cr.get("specialist_count", 0)
        if specialist_count:
            print(f"  Specialist agents: {specialist_count}")

        risks = cr.get("risk_assessment") or []
        if risks:
            print(f"\n  Risks ({len(risks)}):")
            for risk in risks[:6]:
                risk_text = risk if isinstance(risk, str) else risk.get("text", str(risk))
                print(f"    - {str(risk_text)[:100]}")
            if len(risks) > 6:
                print(f"    ... and {len(risks) - 6} more")

        next_actions = cr.get("next_actions") or []
        if next_actions:
            print(f"\n  Next actions ({len(next_actions)}):")
            for action in next_actions[:4]:
                action_text = action if isinstance(action, str) else action.get("text", str(action))
                print(f"    \u2192 {str(action_text)[:100]}")


def _print_usage_summary(state) -> None:
    """Print token and cost usage summary using the standard formatter."""
    from src.tools.usage_logger import format_usage_summary
    print()
    print(format_usage_summary(state))


def _print_session_usage_summary(thread_id: str) -> None:
    """
    Print a session-level (conversation) usage summary for an existing thread.

    Queries SQLite for all usage_logs rows that share *thread_id* and
    formats them as a human-readable session summary. Only shown when
    continuing an existing thread (``--thread-id``).

    Silently skipped if the database is unavailable or the thread has no
    recorded usage (e.g. the run was not saved with ``--save``).

    Args:
        thread_id: The conversation thread to summarise.
    """
    try:
        from src.tools.usage_logger import aggregate_session_usage, format_session_usage_summary
        from src.memory.sqlite_store import get_db_path_from_config

        db_path = get_db_path_from_config()
        session_agg = aggregate_session_usage(db_path, thread_id)

        if session_agg.run_count == 0:
            # No persisted usage for this thread — skip silently
            return

        print()
        print(format_session_usage_summary(session_agg))
    except Exception:
        # Non-fatal — session summary is a nice-to-have, not critical
        pass


def _print_verbose_detail(state) -> None:
    """
    Print extra debug detail when --verbose is enabled.

    Includes: per-agent token breakdown, retrieval detail,
    guardrail evaluation, build package summary.
    """
    _sep("-")
    print("VERBOSE / DEBUG DETAIL")
    _sep("-")

    # Per-agent token breakdown
    if state.agent_outputs:
        print("  Per-agent token usage:")
        for agent_name, ao in state.agent_outputs.items():
            usage = ao.token_usage
            cost_str = (
                f"  est. ${usage.cost_estimate:.6f}"
                if usage.cost_estimate is not None else ""
            )
            print(
                f"    {agent_name:<32}: "
                f"{usage.total_tokens:>6,} tokens  "
                f"(model: {usage.model}){cost_str}"
            )

    # Retrieval detail
    print(f"\n  Retrieval:")
    print(f"    Status  : {state.retrieval_status}")
    print(f"    Items   : {state.retrieval_item_count}")
    if state.retrieved_memory:
        sources = [m.source for m in state.retrieved_memory[:5]]
        print(f"    Sources : {sources}")

    # Guardrail detail
    print(f"\n  Guardrails:")
    print(f"    Triggered : {state.guardrail_triggered}")
    if state.guardrail_reason:
        print(f"    Reason    : {state.guardrail_reason}")

    # Build package detail
    if state.build_package:
        bp = state.build_package
        print(f"\n  Build package : {bp.title}")
        print(f"    Project      : {bp.project_name}")
        print(f"    Scope items  : {len(bp.scope)}")
        if bp.scope:
            for item in bp.scope[:3]:
                print(f"      - {item}")
        if len(bp.scope) > 3:
            print(f"      ... and {len(bp.scope) - 3} more")


def _wrap_text(text: str, width: int = 56, indent: str = "    ") -> list:
    """
    Simple word-wrap helper. Returns a list of indented lines.

    Args:
        text:   The string to wrap.
        width:  Maximum line width including indent.
        indent: Prefix added to every line.
    """
    words = text.split()
    lines: list = []
    current = indent
    for word in words:
        if len(current) + len(word) + 1 > width + len(indent):
            lines.append(current)
            current = indent + word
        else:
            current = current + (" " if current != indent else "") + word
    if current != indent:
        lines.append(current)
    return lines or [indent + text]


# ---------------------------------------------------------------------------
# Index management helpers
# ---------------------------------------------------------------------------

def _show_pending_index(project_name: str, db_path: str) -> None:
    """Print a summary of document indexing status for the given project."""
    from src.tools.index_refresh import get_index_status_report

    _sep("-")
    print("INDEX STATUS")
    _sep("-")

    try:
        report = get_index_status_report(project_name, db_path=db_path)
    except Exception as exc:
        print(f"  ERROR: Could not read index status: {exc}")
        return

    print(f"  Project     : {report['project_name']}")
    print(f"  Total docs  : {report['total']}")
    print(f"  Indexed     : {report['indexed']}")
    print(f"  Not indexed : {report['not_indexed']}")
    print(f"  Stale       : {report['stale']}")
    print(f"  Failed      : {report['failed']}")

    docs = report.get("documents") or []
    pending = [d for d in docs if d["status"] != "indexed"]
    if pending:
        print()
        print("  Pending / non-indexed documents:")
        status_icon = {"not_indexed": "--", "stale": "~~", "failed": "XX"}
        for d in pending:
            icon = status_icon.get(d["status"], "??")
            print(f"    [{icon}] {d['file_name']:<40} {d['status']}")
            if d.get("last_error"):
                print(f"           Error: {d['last_error'][:80]}")
    elif docs:
        print()
        print("  All documents are indexed and up to date.")
    else:
        print()
        print("  No persisted documents found for this project.")
    print()


def _run_index_refresh(project_name: str, db_path: str) -> None:
    """Run an incremental (delta-only) index refresh for the given project."""
    from src.tools.index_refresh import refresh_all_pending_indexes

    _sep("-")
    print("INCREMENTAL INDEX REFRESH")
    _sep("-")
    print(f"  Project : {project_name}")
    print(f"  Mode    : delta only — already-indexed documents are not touched")
    print()

    try:
        result = refresh_all_pending_indexes(project_name, db_path=db_path)
    except Exception as exc:
        print(f"  ERROR: Index refresh failed: {exc}")
        return

    print()
    print(f"  Indexed     : {result['indexed']}")
    print(f"  Failed      : {result['failed']}")
    print(f"  Newly stale : {result['newly_stale']}")

    for d in result.get("details", []):
        if d.get("error"):
            print(f"    XX  {d.get('file_name')}: {d['error'][:80]}")
    print()


def _run_rebuild_index(project_name: str, db_path: str) -> None:
    """Prompt for confirmation, then run a full FAISS rebuild for the project."""
    from src.tools.index_refresh import full_rebuild_document_index

    _sep("-")
    print("FULL INDEX REBUILD")
    _sep("-")
    print(f"  Project : {project_name}")
    print()
    print("  WARNING: This will CLEAR the entire FAISS index, including")
    print("  decisions, artefacts, and markdown content — not just documents.")
    print("  Non-document content must be re-seeded via scripts/seed_project.py")
    print("  after the rebuild.")
    print()

    try:
        choice = input("  Type 'yes' to confirm full rebuild, or press Enter to cancel: ").strip()
    except (KeyboardInterrupt, EOFError):
        choice = ""
    print()

    if choice.lower() != "yes":
        print("  Cancelled — no changes made.")
        print()
        return

    try:
        result = full_rebuild_document_index(project_name, db_path=db_path)
    except Exception as exc:
        print(f"  ERROR: Full rebuild failed: {exc}")
        return

    print()
    print(f"  Indexed : {result['indexed']}")
    print(f"  Failed  : {result['failed']}")
    if result["indexed"] > 0:
        print()
        print("  To restore non-document content (decisions, artefacts, etc.):")
        print("    python scripts/seed_project.py")
    print()


# ---------------------------------------------------------------------------
# Conversation management helpers
# ---------------------------------------------------------------------------

def _show_conversations(db_path: str) -> None:
    """List all named conversations in the database (read-only, no changes)."""
    from src.memory.sqlite_store import get_all_conversations, initialize_database

    _sep("-")
    print("CONVERSATIONS")
    _sep("-")

    try:
        initialize_database(db_path)
        conversations = get_all_conversations(db_path)
    except Exception as exc:
        print(f"  ERROR: Could not read conversations: {exc}")
        return

    if not conversations:
        print("  No conversations found.")
        print()
        return

    print(f"  {len(conversations)} conversation(s) found:")
    print()
    for i, c in enumerate(conversations, 1):
        last = c.last_used_at[:10] if c.last_used_at else "unknown"
        print(f"  {i:>3}.  {c.name}")
        print(f"        Thread ID  : {c.thread_id}")
        print(f"        Last used  : {last}")
        if i < len(conversations):
            print()
    print()


def _run_delete_conversation(
    name_or_thread_id: str,
    deep: bool,
    db_path: str,
) -> None:
    """
    Interactively delete a named conversation with confirmation.

    Shows a deletion preview, asks for explicit confirmation, then performs
    the deletion and prints a result summary.

    Args:
        name_or_thread_id: Conversation name or thread_id UUID.
        deep:              True = Mode B (deep delete), False = Mode A (conversation-only).
        db_path:           SQLite path.
    """
    from src.tools.conversation_delete import (
        format_deletion_preview,
        get_deletion_preview,
        delete_conversation_mode_a,
        delete_conversation_mode_b,
    )

    mode_label = "Deep Delete (Mode B)" if deep else "Conversation-Only Delete (Mode A)"
    _sep("-")
    print(f"DELETE CONVERSATION — {mode_label}")
    _sep("-")
    print(f"  Target : {name_or_thread_id!r}")
    print()

    # --- Preview ---
    preview = get_deletion_preview(name_or_thread_id, db_path=db_path)

    if not preview.get("found"):
        print(f"  ✗ Conversation not found: {name_or_thread_id!r}")
        print()
        print("  Tip: Use --show-conversations to list available conversations.")
        print()
        return

    print("  Preview of what will be deleted:")
    print()
    print(format_deletion_preview(preview))
    print()

    # --- Confirmation ---
    if deep:
        confirm_msg = (
            "  ⚠  Deep delete will permanently remove all linked memory,\n"
            "  documents, and usage logs.  This cannot be undone.\n\n"
            "  Type 'yes' to confirm deep delete, or press Enter to cancel: "
        )
    else:
        confirm_msg = (
            "  This removes the conversation record and message history only.\n"
            "  Project-level memory and documents are preserved.\n\n"
            "  Type 'yes' to confirm, or press Enter to cancel: "
        )

    try:
        choice = input(confirm_msg).strip()
    except (KeyboardInterrupt, EOFError):
        choice = ""
    print()

    if choice.lower() != "yes":
        print("  Cancelled — no changes made.")
        print()
        return

    # --- Deletion ---
    if deep:
        result = delete_conversation_mode_b(name_or_thread_id, db_path=db_path)
    else:
        result = delete_conversation_mode_a(name_or_thread_id, db_path=db_path)

    if not result.get("success"):
        print(f"  ✗ Deletion failed: {result.get('error', 'unknown error')}")
        print()
        return

    # --- Summary ---
    _sep("-")
    print("DELETION COMPLETE")
    _sep("-")
    print(f"  Conversation : {result.get('conversation_name')!r}")
    print(f"  Thread ID    : {result.get('thread_id')}")
    print(f"  Messages     : {result.get('deleted_messages', 0)} deleted")

    if deep:
        print(f"  Documents    : {result.get('deleted_documents', 0)} SQLite rows removed")
        print(f"  Disk files   : {result.get('disk_files_deleted', 0)} removed")
        if result.get("disk_files_missing", 0):
            print(f"               {result['disk_files_missing']} already missing (skipped)")
        if result.get("disk_files_error", 0):
            print(f"               {result['disk_files_error']} could not be removed")
        print(f"  Usage logs   : {result.get('deleted_usage_logs', 0)} removed")
        mem = result.get("deleted_memory", {})
        if any(v > 0 for v in mem.values()):
            print(
                f"  Memory rows  : "
                f"{mem.get('decisions', 0)}d  "
                f"{mem.get('risks', 0)}r  "
                f"{mem.get('monetisation_hypotheses', 0)}h  "
                f"{mem.get('product_facts', 0)}f  "
                f"{mem.get('build_artefact_summaries', 0)}a"
            )

    if result.get("faiss_rebuild_recommended"):
        print()
        print("  ⚠  Deleted documents were indexed in FAISS.")
        print("     Ghost chunks remain until you rebuild:")
        print("       python cli.py --rebuild-index")
    print()


# ---------------------------------------------------------------------------
# Main entry point
# ---------------------------------------------------------------------------

def main(argv=None) -> None:
    """
    Main CLI entry point.

    Parses arguments, loads product context, runs the workflow, and prints
    a structured operator summary to the terminal.

    Args:
        argv: Argument list (defaults to sys.argv[1:] when None).

    TODO: When a future UI layer is added, this function becomes the CLI
    adapter and the display helpers above can be reused for any text output.
    """
    args = _parse_args(argv)

    # Detect non-workflow modes (no --prompt required)
    _index_flags = args.show_pending_index or args.refresh_index or args.rebuild_index
    _deletion_flags = bool(args.delete_conversation) or args.show_conversations
    _no_prompt_flags = _index_flags or _deletion_flags

    if args.prompt is None and not _no_prompt_flags:
        print(
            "ERROR: --prompt is required unless using "
            "--show-pending-index, --refresh-index, --rebuild-index, "
            "--delete-conversation, or --show-conversations."
        )
        sys.exit(1)

    # --- Load product context ---
    # Loaded in all modes so that project_name can be derived from it.
    product_context: Optional[Dict[str, Any]] = None
    context_source = "none"

    if not args.no_product_context:
        is_default = (args.product_context == _DEFAULT_CONTEXT_PATH)
        try:
            product_context = _load_product_context(args.product_context, is_default=is_default)
        except ValueError as exc:
            print(f"ERROR: {exc}")
            sys.exit(1)
        if product_context is not None:
            context_source = args.product_context

    # Determine project name early — used by both index operations and workflow.
    project_name = (
        args.project_name
        or (product_context or {}).get("product_name")
        or "default"
    )

    # --- Non-workflow mode (no --prompt) ---
    if _no_prompt_flags and args.prompt is None:
        from src.memory.sqlite_store import get_db_path_from_config
        db_path = get_db_path_from_config()
        if args.show_pending_index:
            _show_pending_index(project_name, db_path)
        if args.refresh_index:
            _run_index_refresh(project_name, db_path)
        if args.rebuild_index:
            _run_rebuild_index(project_name, db_path)
        if args.show_conversations:
            _show_conversations(db_path)
        if args.delete_conversation:
            _run_delete_conversation(
                args.delete_conversation,
                deep=args.deep_delete,
                db_path=db_path,
            )
        return

    # --- Load uploaded documents ---
    uploaded_documents: list = []
    if args.files:
        print()
        uploaded_documents = _load_documents(args.files, thread_id=args.thread_id)

    # --- Pre-run header ---
    is_new_thread = args.thread_id is None
    thread_label = (
        "starting new thread"
        if is_new_thread
        else f"continuing thread {args.thread_id}"
    )

    print()
    _sep()
    print("APDT — PRODUCT AGENT FRAMEWORK")
    _sep()
    print(f"  Prompt  : {args.prompt[:80]}{'...' if len(args.prompt) > 80 else ''}")
    print(f"  Thread  : {thread_label}")
    print(f"  Context : {context_source}")
    if uploaded_documents:
        success = sum(1 for d in uploaded_documents if d.parse_success)
        failed = len(uploaded_documents) - success
        label = f"{success} doc(s) loaded"
        if failed:
            label += f", {failed} failed"
        print(f"  Files   : {label}")
    else:
        print(f"  Files   : none")
    print(f"  Verbose : {args.verbose}")
    _sep()
    print()

    # --- Run workflow ---
    # Deferred import keeps the CLI importable even when the workflow
    # dependencies are not fully installed (e.g. during fast arg-only tests).
    from src.graph.workflow import run_workflow, save_workflow_results_to_memory

    state = run_workflow(
        args.prompt,
        product_context=product_context,
        thread_id=args.thread_id,
        verbose=args.verbose,
        uploaded_documents=uploaded_documents or None,
    )
    print()

    # --- Post-run display ---
    _print_run_header(state, is_new_thread)
    _print_documents(state)
    _print_agents_and_retrieval(state)
    _print_approval_status(state)

    # --- Inline approval prompt ---
    if state.approval_required and state.approval_status == "pending":
        updated = _handle_inline_approval(state, args)
        if updated:
            # Use the post-approval state for the rest of the output
            state = updated

    _print_warnings_errors(state)
    _print_artefacts(state)
    _print_consolidated_response(state, verbose=args.verbose)
    _print_usage_summary(state)

    # Session-level summary: only relevant when continuing an existing thread
    # AND the thread has persisted usage entries in SQLite (i.e. --save has
    # been used at least once in this conversation).
    if not is_new_thread:
        _print_session_usage_summary(state.thread_id)

    if args.verbose:
        _print_verbose_detail(state)

    # --- Warn when --auto-embed used without --persist-doc ---
    if getattr(args, "auto_embed", False) and not getattr(args, "persist_doc", False):
        print("  ⚠  --auto-embed has no effect without --persist-doc")
        print()

    # --- Persist documents to project memory if requested ---
    loaded_docs = list(state.uploaded_documents or [])
    if getattr(args, "persist_doc", False) and loaded_docs:
        _persist_documents(loaded_docs, project_name, getattr(args, "auto_embed", False))

    if args.save:
        _sep("-")
        print("SAVING TO SQLITE")
        _sep("-")
        try:
            counts = save_workflow_results_to_memory(state, project_name=project_name)
            for table, count in counts.items():
                if count > 0:
                    print(f"  {table:<30}: {count} record(s) saved")
        except Exception as exc:
            print(f"  WARNING: Could not save to SQLite: {exc}")

    # --- Auto-refresh index after run ---
    if args.auto_refresh_index:
        from src.memory.sqlite_store import get_db_path_from_config
        _run_index_refresh(project_name, get_db_path_from_config())

    # --- Post-run show-pending-index (if combined with a workflow run) ---
    if args.show_pending_index and args.prompt is not None:
        from src.memory.sqlite_store import get_db_path_from_config
        _show_pending_index(project_name, get_db_path_from_config())

    # --- Footer — thread ID for easy copy-paste follow-up ---
    _sep()
    print(f"  Thread ID for follow-up: {state.thread_id}")
    _sep()
    print()


if __name__ == "__main__":
    main()