cli.py

"""
Knowa CLI — manage the knowledge-base index without running the API server.

Commands:
  list                       List all indexed sources
  index <directory>          Index a local directory recursively
  clear <directory>          Clear index for a local directory
  clear --source-id <id>     Clear index for any source by its ID
  clear --all                Clear all indexed sources
"""

import argparse
import logging
import os
import shutil
import sys
import time


def _setup_logging(verbose: bool) -> None:
    level = logging.DEBUG if verbose else logging.WARNING
    logging.basicConfig(
        level=level,
        format="%(asctime)s %(levelname)s — %(message)s",
        datefmt="%H:%M:%S",
        stream=sys.stderr,
    )
    if not verbose:
        # Suppress HTTP-level noise from OpenAI SDK and httpx
        for name in ("httpx", "httpcore", "openai"):
            logging.getLogger(name).setLevel(logging.WARNING)


# ── progress bar ──────────────────────────────────────────────────────────────

class _ProgressBar:
    """Inline progress bar for TTY; falls back to plain line output when not a TTY."""

    _BAR_WIDTH = 25

    def __init__(self, total: int | None) -> None:
        self._total = total
        self._is_tty = sys.stdout.isatty()
        self._last_len = 0

    def update(self, current: int, title: str = "") -> None:
        if not self._is_tty:
            if self._total:
                print(f"  [{current}/{self._total}] {title}", flush=True)
            else:
                print(f"  [{current}] {title}", flush=True)
            return

        cols = shutil.get_terminal_size((80, 20)).columns

        if self._total:
            pct = min(current / self._total, 1.0)
            filled = int(self._BAR_WIDTH * pct)
            bar = "█" * filled + "░" * (self._BAR_WIDTH - filled)
            prefix = f"  [{bar}] {pct*100:5.1f}%  {current}/{self._total}"
        else:
            prefix = f"  {current} indexed"

        title_space = cols - len(prefix) - 3
        if title_space > 4:
            name = (title[: title_space - 1] + "…") if len(title) >= title_space else title
            line = f"{prefix}  {name}"
        else:
            line = prefix

        # Pad to overwrite any leftover characters from the previous line
        padded = line.ljust(self._last_len)
        self._last_len = max(len(line), 0)
        print(f"\r{padded}", end="", flush=True)

    def finish(self) -> None:
        if self._is_tty and self._last_len:
            print()


# ── help ──────────────────────────────────────────────────────────────────────

_HELP_TEXT = """\
Knowa CLI — manage the knowledge-base index without running the API server.

Usage:
  knowa <command> [options]

Commands:
  help                           Show this help message
  list                           List all indexed sources with page/chunk counts
  index <directory>              Index a local directory (incremental by default)
  clear <directory>              Clear index for a local directory
  clear --source-id <id>         Clear any source by its ID (Notion, Confluence, local)
  clear --all                    Clear all indexed sources
  chat [question]                Query the index (interactive REPL or single-shot)

Options:
  index --full                   Force a full rebuild (ignore last-sync state)
  index --name <label>           Attach a friendly label to this source
  index --workers <N>            Number of parallel indexing threads (default: 1)
  index --verbose / -v           Show raw debug output instead of progress bar
  clear --yes / -y               Skip the confirmation prompt
  chat --source <label-or-id>    Scope chat to a specific source
  chat --debug                   Show retrieval path (vector/FTS/graph hits) before each answer
  chat --no-index <dir>          Read documents from DIR directly, bypass the index
  debug                          Show graph backend status, node/edge counts, and sample entities
  bench <file.json>              Run questions with/without index and compare timing

Examples:
  knowa list
  knowa index ~/docs --name "Engineering Docs"
  knowa index ~/docs --full
  knowa index ~/docs --verbose
  knowa clear ~/docs
  knowa clear --source-id abc123def456789012345678901234567890
  knowa clear --all --yes
  knowa chat
  knowa chat "What is our refund policy?"
  knowa chat --source "Engineering Docs"
  knowa chat --debug
  knowa chat --no-index /path/to/docs
  knowa chat "question" --source <notion-workspace-id>
  knowa debug
  knowa bench questions.json

For detailed help on a specific command:
  knowa<command> --help
"""


def cmd_help(args: argparse.Namespace) -> int:
    print(_HELP_TEXT, end="")
    return 0


# ── list ──────────────────────────────────────────────────────────────────────

def cmd_list(args: argparse.Namespace) -> int:
    _setup_logging(False)

    from knowa.storage.db import run_migrations
    from knowa.storage.sync_store import list_sources

    run_migrations()

    sources = list_sources()
    if not sources:
        print("No sources indexed yet.")
        return 0

    has_labels = any(s.get("label") for s in sources)
    type_w  = max(11, max(len(s["source_type"]) for s in sources))
    id_w    = min(60, max(9, max(len(s["source_id"]) for s in sources)))
    label_w = max(5, max(len(s["label"] or "") for s in sources)) if has_labels else 0

    if has_labels:
        header = (
            f"{'TYPE':<{type_w}}  {'LABEL':<{label_w}}  {'SOURCE ID':<{id_w}}"
            f"  {'PAGES':>5}  {'CHUNKS':>6}  LAST SYNCED"
        )
    else:
        header = f"{'TYPE':<{type_w}}  {'SOURCE ID':<{id_w}}  {'PAGES':>5}  {'CHUNKS':>6}  LAST SYNCED"
    print(header)
    print("-" * len(header))

    for s in sources:
        source_id = s["source_id"]
        if len(source_id) > id_w:
            source_id = "…" + source_id[-(id_w - 1):]
        last = s["last_synced_at"] or "never"
        if has_labels:
            label = s.get("label") or ""
            print(
                f"{s['source_type']:<{type_w}}  "
                f"{label:<{label_w}}  "
                f"{source_id:<{id_w}}  "
                f"{s['page_count']:>5}  "
                f"{s['chunk_count']:>6}  "
                f"{last}"
            )
        else:
            print(
                f"{s['source_type']:<{type_w}}  "
                f"{source_id:<{id_w}}  "
                f"{s['page_count']:>5}  "
                f"{s['chunk_count']:>6}  "
                f"{last}"
            )

    print()
    total_pages  = sum(s["page_count"]  for s in sources)
    total_chunks = sum(s["chunk_count"] for s in sources)
    print(f"{len(sources)} source(s)  ·  {total_pages} page(s)  ·  {total_chunks} chunk(s)")
    return 0


# ── index ─────────────────────────────────────────────────────────────────────

def cmd_index(args: argparse.Namespace) -> int:
    _setup_logging(args.verbose)

    from pathlib import Path
    from knowa.storage.db import run_migrations
    from knowa.connectors.local import SUPPORTED_EXTENSIONS, LocalDirectoryConnector
    from knowa.indexing.pipeline import run_full_rebuild, run_incremental_sync
    from knowa.storage.sync_store import get_last_synced

    try:
        source = LocalDirectoryConnector(args.directory)
    except ValueError as exc:
        print(f"Error: {exc}", file=sys.stderr)
        return 1

    run_migrations()

    label: str | None = getattr(args, "name", None) or None

    workers: int = getattr(args, "workers", 1) or 1

    if args.verbose:
        # Verbose mode: raw log output, no progress bar
        stats = (
            run_full_rebuild(source, label=label, workers=workers)
            if args.full
            else run_incremental_sync(source, label=label, workers=workers)
        )
        _print_summary(stats, elapsed=None, source_id=source.source_id)
        return 0 if stats["errors"] == 0 else 1

    # ── friendly mode ─────────────────────────────────────────────────────────

    # Fast filesystem scan to get the total file count (no content read)
    total_files = sum(
        1 for p in Path(source.source_id).rglob("*")
        if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS
    )

    last_synced = get_last_synced(source.source_id)
    is_full_run = args.full or last_synced is None

    if total_files == 0:
        print(f"No supported files found in {source.source_id}")
        print(f"Supported types: {', '.join(sorted(SUPPORTED_EXTENSIONS))}")
        return 0

    display = f"{label!r} ({source.source_id})" if label else source.source_id
    if is_full_run:
        print(f"Indexing {total_files} file(s) in {display}")
    else:
        ts = last_synced.strftime("%Y-%m-%d %H:%M")
        print(f"Checking {total_files} file(s) for changes in {display}  (last synced {ts})")

    started = time.monotonic()

    if workers > 1:
        from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
        from rich.text import Text

        class _BarIfKnown(BarColumn):
            def render(self, task):
                return Text("") if task.total is None else super().render(task)

        with Progress(
            SpinnerColumn(),
            TextColumn("{task.description}"),
            _BarIfKnown(bar_width=25),
            TimeElapsedColumn(),
            refresh_per_second=8,
        ) as progress:
            worker_tasks = [
                progress.add_task(f"  [dim]Worker {i + 1}:[/dim] waiting", total=None)
                for i in range(workers)
            ]
            overall = progress.add_task(
                f"[cyan]Indexing 0{'/' + str(total_files) if is_full_run else ''}[/cyan]",
                total=total_files if is_full_run else None,
            )

            def on_progress(title: str, count: int) -> None:
                label_str = f"[cyan]Indexing {count}{'/' + str(total_files) if is_full_run else ''}[/cyan]"
                progress.update(overall, description=label_str, advance=1)

            def on_worker_status(worker_id: int, page_title: str | None) -> None:
                if page_title:
                    short = page_title[:50] + "…" if len(page_title) > 50 else page_title
                    progress.update(worker_tasks[worker_id], description=f"  [dim]Worker {worker_id + 1}:[/dim] {short}", visible=True)
                else:
                    progress.update(worker_tasks[worker_id], visible=False)

            stats = (
                run_full_rebuild(source, on_progress, label=label, workers=workers, worker_status_callback=on_worker_status)
                if args.full
                else run_incremental_sync(source, on_progress, label=label, workers=workers, worker_status_callback=on_worker_status)
            )
    else:
        bar = _ProgressBar(total=total_files if is_full_run else None)
        stats = (
            run_full_rebuild(source, lambda t, n: bar.update(n, t), label=label, workers=workers)
            if args.full
            else run_incremental_sync(source, lambda t, n: bar.update(n, t), label=label, workers=workers)
        )
        bar.finish()

    elapsed = time.monotonic() - started
    _print_summary(stats, elapsed, source_id=source.source_id)
    return 0 if stats["errors"] == 0 else 1


def _fmt_tokens(n: int) -> str:
    if n >= 1_000_000:
        return f"{n / 1_000_000:.1f}M"
    if n >= 1_000:
        return f"{n / 1_000:.0f}k"
    return str(n)


def _print_summary(stats: dict, elapsed: float | None, source_id: str | None = None) -> None:
    parts = []
    if elapsed is not None:
        elapsed_str = f"{int(elapsed // 60)}m {int(elapsed % 60)}s" if elapsed >= 60 else f"{elapsed:.1f}s"
        parts.append(f"Done in {elapsed_str}")
    else:
        parts.append("Done")
    parts.append(f"{stats['indexed']} indexed")
    if stats.get("deleted"):
        parts.append(f"{stats['deleted']} deleted")
    if stats["errors"]:
        parts.append(f"{stats['errors']} error(s) — run with --verbose for details")
    print("  " + "  ·  ".join(parts))

    if source_id and stats["indexed"] > 0:
        from knowa.storage.chunk_store import get_token_stats
        ts = get_token_stats(source_id)
        full = int(ts.get("full_content_tokens") or 0)
        embedded = int(ts.get("embedded_tokens") or 0)
        chunks = int(ts.get("child_chunks") or 0)
        pages = int(ts.get("total_pages") or 0)
        savings_pct = round((1 - embedded / full) * 100) if full else 0
        print(
            f"  {pages} page(s)  ·  {chunks} chunk(s)  ·  "
            f"{_fmt_tokens(full)} content tokens  ·  "
            f"{_fmt_tokens(embedded)} embedded  ·  "
            f"{savings_pct}% token savings"
        )

    if stats.get("llm_errors"):
        n = stats["llm_errors"]
        print(
            f"\n  Warning: LLM entity extraction failed for {n} page(s).\n"
            f"  Graph enrichment from ENTITY_LLM_MODEL was skipped for those pages.\n"
            f"\n"
            f"  Common fixes:\n"
            f"    • ENTITY_LLM_BASE_URL is set but the server is not running — start it or unset the var\n"
            f"    • ENTITY_LLM_MODEL is set to a model unavailable on the configured endpoint\n"
            f"    • Transient network issue — re-run 'knowa index --full' to retry\n"
            f"    • Too many concurrent requests — lower ENTITY_LLM_CONCURRENCY (currently {n} failed)\n"
            f"\n"
            f"  Run with --verbose to see the full error for each page."
        )


# ── clear ─────────────────────────────────────────────────────────────────────

def cmd_clear(args: argparse.Namespace) -> int:
    _setup_logging(False)

    targets = [bool(args.directory), bool(args.source_id), bool(args.all)]
    if sum(targets) == 0:
        print(
            "Error: specify a target — a directory path, --source-id <id>, or --all",
            file=sys.stderr,
        )
        return 1
    if sum(targets) > 1:
        print(
            "Error: only one of directory / --source-id / --all may be given",
            file=sys.stderr,
        )
        return 1

    from knowa.storage.db import run_migrations
    from knowa.indexing.pipeline import clear_all_sources, clear_source

    if args.all:
        if not args.yes:
            answer = input(
                "This will delete ALL indexed data across every source.\nContinue? [y/N] "
            ).strip().lower()
            if answer != "y":
                print("Aborted.")
                return 0
        run_migrations()
        deleted = clear_all_sources()
        print(f"Cleared {deleted} page(s) across all sources.")
        return 0

    if args.source_id:
        source_id = args.source_id
        label = source_id
    else:
        from knowa.connectors.local import LocalDirectoryConnector
        try:
            source = LocalDirectoryConnector(args.directory)
        except ValueError as exc:
            print(f"Error: {exc}", file=sys.stderr)
            return 1
        source_id = source.source_id
        label = source_id

    if not args.yes:
        answer = input(
            f"This will delete all indexed data for:\n  {label}\nContinue? [y/N] "
        ).strip().lower()
        if answer != "y":
            print("Aborted.")
            return 0

    run_migrations()
    deleted = clear_source(source_id)
    print(f"Cleared {deleted} page(s) (and their chunks/graph data) for: {label}")
    return 0


# ── debug ─────────────────────────────────────────────────────────────────────

def cmd_debug(args: argparse.Namespace) -> int:
    _setup_logging(False)

    from knowa.storage.db import run_migrations
    from knowa.storage.graph_backend import get_graph_backend

    run_migrations()

    from knowa.config import settings
    backend_name = settings.graph_backend.lower()
    print(f"Graph backend: {backend_name}", end="")
    if backend_name == "kuzu":
        print(f"  (path: {settings.kuzu_path})")
    elif backend_name == "neo4j":
        print(f"  ({settings.neo4j_uri})")
    else:
        print()

    try:
        backend = get_graph_backend()
    except RuntimeError as exc:
        if "lock" in str(exc).lower():
            print(f"  Cannot open {backend_name} database: file is locked by another process.")
            if backend_name == "kuzu":
                print("  Kuzu is an embedded database — only one process can hold it open at a time.")
                print("  If the API server is running, stop it first, then retry 'knowa debug'.")
                print("  Alternatively, switch to GRAPH_BACKEND=postgres for concurrent CLI+server access.")
        else:
            print(f"  Error initializing graph backend: {exc}", file=sys.stderr)
        return 1

    try:
        st = backend.stats()
        node_count = st["node_count"]
        edge_count = st["edge_count"]
        print(f"  {node_count:,} node(s)  ·  {edge_count:,} edge(s)")
    except Exception as exc:
        print(f"  Error reading graph stats: {exc}", file=sys.stderr)
        return 1

    if node_count == 0:
        print()
        print("  Graph is empty — no entities were extracted during indexing.")
        print("  Check that spaCy is installed:  python -m spacy download en_core_web_sm")
        return 0

    try:
        labels = backend.sample_entities()
        if labels:
            print(f"  Sample entities: {', '.join(labels)}")
    except Exception as exc:
        print(f"  Error reading sample entities: {exc}", file=sys.stderr)

    print()
    print("  The graph is searched by matching entity names against keywords in your question.")
    print("  Try questions that mention entity names shown above, for example:")
    if labels:
        example = labels[0]
        print(f'    knowa chat "Tell me about {example}"')
        print(f'    knowa chat --debug "Tell me about {example}"')
    return 0


# ── chat ──────────────────────────────────────────────────────────────────────

def _load_dir_as_context(directory: str, max_tokens: int = 100_000) -> tuple[str, int]:
    """Read all supported files from directory, return (context_text, token_estimate).

    Concatenates pages in order, stopping at max_tokens to avoid exceeding LLM context limits.
    """
    from knowa.connectors.local import LocalDirectoryConnector
    max_chars = max_tokens * 4
    parts: list[str] = []
    total_chars = 0
    truncated = False

    connector = LocalDirectoryConnector(directory)
    for page in connector.fetch_all_pages():
        content = f"[{page.title}]\n{page.content}"
        if total_chars + len(content) > max_chars:
            remaining = max_chars - total_chars
            if remaining > 200:
                parts.append(content[:remaining])
            truncated = True
            break
        parts.append(content)
        total_chars += len(content)

    context = "\n\n---\n\n".join(parts)
    token_estimate = len(context) // 4
    if truncated:
        print(f"  Warning: content truncated at ~{_fmt_tokens(max_tokens)} tokens (LLM context limit)")
    return context, token_estimate


# ── bench ─────────────────────────────────────────────────────────────────────

def cmd_bench(args: argparse.Namespace) -> int:
    import json
    from pathlib import Path

    _setup_logging(False)

    # ── load input file ───────────────────────────────────────────────────────
    input_path = Path(args.file)
    if not input_path.exists():
        print(f"Error: {args.file} not found", file=sys.stderr)
        return 1
    try:
        with open(input_path) as f:
            config = json.load(f)
    except json.JSONDecodeError as exc:
        print(f"Error parsing {args.file}: {exc}", file=sys.stderr)
        return 1

    questions: list[str] = config.get("questions", [])
    no_index_dir: str | None = config.get("no_index_dir")
    source: str | None = config.get("source")

    if not questions:
        print("Error: no questions found in input file", file=sys.stderr)
        return 1

    from knowa.storage.db import run_migrations
    run_migrations()

    # ── validate no_index_dir ─────────────────────────────────────────────────
    raw_context: str | None = None
    if no_index_dir:
        from knowa.connectors.local import SUPPORTED_EXTENSIONS
        d = Path(no_index_dir)
        if not d.is_dir():
            print(f"Error: no_index_dir '{no_index_dir}' is not a directory", file=sys.stderr)
            return 1
        files = [p for p in d.rglob("*") if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS]
        if not files:
            print(f"Error: no supported files in '{no_index_dir}'", file=sys.stderr)
            return 1
        print(f"No-index dir : {no_index_dir}  ({len(files)} file(s))")

    # ── validate index ────────────────────────────────────────────────────────
    source_id: str | None = None
    if source:
        from knowa.storage.sync_store import resolve_source_id
        source_id = resolve_source_id(source)
        if source_id is None:
            print(f"Error: no indexed source found for '{source}'", file=sys.stderr)
            print("Run 'knowa list' to see available sources.", file=sys.stderr)
            return 1
        print(f"Index source : {source}")
    else:
        from knowa.storage.sync_store import list_sources
        if not list_sources():
            print("Error: no indexed sources found — run 'knowa index' first", file=sys.stderr)
            return 1
        print("Index source : (all sources)")

    # ── load no-index context once ────────────────────────────────────────────
    if no_index_dir:
        print("Loading documents for no-index mode…", end="", flush=True)
        raw_context, tok = _load_dir_as_context(no_index_dir)
        print(f"\r  Loaded {_fmt_tokens(tok)} tokens from {no_index_dir}          ")

    print(f"\nRunning {len(questions)} question(s)…\n")

    # ── run questions ─────────────────────────────────────────────────────────
    from knowa.retrieval.hybrid import query

    SEP = "─" * 72
    idx_times: list[float] = []
    raw_times: list[float] = []

    for i, question in enumerate(questions, 1):
        print(SEP)
        print(f"Q{i}: {question}\n")

        # with index
        print("  [with index]")
        t0 = time.monotonic()
        try:
            r_idx = query(question, response_mode="with_citations", source_id=source_id)
            elapsed_idx = time.monotonic() - t0
            idx_times.append(elapsed_idx)
            stats = r_idx.get("token_stats", {})
            ctx = stats.get("context_tokens_used", 0)
            pct = stats.get("savings_pct", 0)
            for line in r_idx["answer"].splitlines():
                print(f"  {line}")
            print(f"  [{ctx:,} tokens · {pct}% savings · {elapsed_idx:.1f}s]")
        except Exception as exc:
            print(f"  Error: {exc}")

        # without index
        if raw_context is not None:
            print()
            print(f"  [no index]")
            t0 = time.monotonic()
            try:
                r_raw = query(question, response_mode="answer_only",
                              use_index=False, raw_context=raw_context)
                elapsed_raw = time.monotonic() - t0
                raw_times.append(elapsed_raw)
                stats = r_raw.get("token_stats", {})
                ctx = stats.get("context_tokens_used", 0)
                for line in r_raw["answer"].splitlines():
                    print(f"  {line}")
                print(f"  [{_fmt_tokens(ctx)} tokens · no index · {elapsed_raw:.1f}s]")
            except Exception as exc:
                print(f"  Error: {exc}")

        print()

    # ── summary ───────────────────────────────────────────────────────────────
    print(SEP)
    print(f"Summary: {len(questions)} question(s)\n")
    if idx_times:
        avg_idx = sum(idx_times) / len(idx_times)
        print(f"  With index:    {avg_idx:.1f}s avg  "
              f"(min {min(idx_times):.1f}s · max {max(idx_times):.1f}s)")
    if raw_times:
        avg_raw = sum(raw_times) / len(raw_times)
        print(f"  Without index: {avg_raw:.1f}s avg  "
              f"(min {min(raw_times):.1f}s · max {max(raw_times):.1f}s)")
    if idx_times and raw_times:
        diff = avg_idx - avg_raw
        label = f"{abs(diff):.1f}s {'slower' if diff > 0 else 'faster'} with index"
        print(f"\n  {label}")
    print()
    return 0


def _print_retrieval_path(path: dict) -> None:
    vec = path.get("vector_chunks", [])
    fts = path.get("fts_pages", [])
    graph = path.get("graph_triples", [])
    tb = path.get("token_breakdown", {})

    print()
    vtok = tb.get("vector_tokens", 0)
    print(f"  [vector]  {len(vec)} chunk(s) · {vtok:,} tok")
    for c in vec:
        title = c["page_title"][:30]
        preview = c["preview"][:80]
        print(f"    {c['score']:.3f}  {title!r:<32}  {preview}")

    ftok = tb.get("fts_tokens", 0)
    print(f"  [fts]     {len(fts)} page(s) · {ftok:,} tok")
    for p in fts:
        print(f"    {p['title']}  ({p['source_type']})")

    print(f"  [graph]   {len(graph)} triple(s)")
    for g in graph:
        print(
            f"    {g['label']} ({g['entity_type']}) "
            f"-- {g['relation']} --> "
            f"{g['target_label']} ({g['target_type']})"
        )


def _print_stream_footer(result: dict, elapsed: float | None = None) -> None:
    """Print citations and token stats after a streamed answer (answer text already printed)."""
    use_index = result.get("use_index", True)
    path = result.get("retrieval_path")

    if path is not None and use_index:
        _print_retrieval_path(path)

    citations = result.get("citations")
    if citations:
        print()
        print("Sources:")
        for c in citations:
            title = c.get("title") or c.get("page_id") or "Unknown"
            url = c.get("url")
            print(f"  • {title}" + (f"  {url}" if url else ""))

    stats = result.get("token_stats", {})
    ctx = stats.get("context_tokens_used", 0)
    time_str = f" · {elapsed:.1f}s" if elapsed is not None else ""
    if not use_index:
        print(f"\n  [{_fmt_tokens(ctx)} tokens · no index{time_str}]")
    elif stats.get("savings_pct") is not None:
        print(f"\n  [{ctx:,} tokens · {stats.get('savings_pct')}% savings{time_str}]")
    print()


def _print_answer(result: dict, elapsed: float | None = None) -> None:
    use_index = result.get("use_index", True)
    path = result.get("retrieval_path")

    if path is not None and use_index:
        _print_retrieval_path(path)

    print()
    print(result["answer"])

    citations = result.get("citations")
    if citations:
        print()
        print("Sources:")
        for c in citations:
            title = c.get("title") or c.get("page_id") or "Unknown"
            url = c.get("url")
            print(f"  • {title}" + (f"  {url}" if url else ""))

    stats = result.get("token_stats", {})
    ctx = stats.get("context_tokens_used", 0)
    time_str = f" · {elapsed:.1f}s" if elapsed is not None else ""
    if not use_index:
        print(f"\n  [{_fmt_tokens(ctx)} tokens · no index{time_str}]")
    elif stats.get("savings_pct") is not None:
        print(f"\n  [{ctx:,} tokens · {stats.get('savings_pct')}% savings{time_str}]")
    print()


def cmd_chat(args: argparse.Namespace) -> int:
    _setup_logging(False)

    from knowa.storage.db import run_migrations
    from knowa.retrieval.hybrid import stream_query

    run_migrations()

    from knowa.storage.sync_store import resolve_source_id

    raw_source = getattr(args, "source", None)
    debug: bool = getattr(args, "debug", False)
    no_index_dir: str | None = getattr(args, "no_index", None)
    use_index: bool = no_index_dir is None
    raw_context: str | None = None

    if no_index_dir:
        try:
            raw_context, tok = _load_dir_as_context(no_index_dir)
        except (ValueError, OSError) as exc:
            print(f"Error reading {no_index_dir}: {exc}", file=sys.stderr)
            return 1
        print(f"Loaded {_fmt_tokens(tok)} tokens from {no_index_dir} (no index)")
        print()

    source_id: str | None = None
    if raw_source:
        source_id = resolve_source_id(raw_source)
        if source_id is None:
            print(f"Error: no indexed source found for {raw_source!r}", file=sys.stderr)
            print("Run 'python cli.py list' to see available sources.", file=sys.stderr)
            return 1
        label_display = raw_source if raw_source != source_id else source_id
        print(f"Scoped to source: {label_display}")
        print()

    def _run_stream(question: str, history: list[dict] | None) -> dict | None:
        """Stream answer tokens to stdout; return final metadata dict or None on error."""
        metadata: dict | None = None
        first_token = True
        t0 = time.monotonic()
        print("Thinking…", end="", flush=True)
        try:
            for item in stream_query(
                question,
                response_mode="with_citations",
                history=history,
                source_id=source_id,
                debug=debug,
                use_index=use_index,
                raw_context=raw_context,
            ):
                if isinstance(item, dict):
                    metadata = item
                    metadata["_elapsed"] = time.monotonic() - t0
                else:
                    if first_token:
                        first_token = False
                        print("\r" + " " * 12 + "\r", end="")  # clear "Thinking…"
                        print()
                    print(item, end="", flush=True)
        except Exception as exc:
            print(f"\rError: {exc}", file=sys.stderr)
            return None
        print()  # newline after last token
        return metadata

    # Single-shot mode
    if args.question:
        metadata = _run_stream(args.question, None)
        if metadata is None:
            return 1
        _print_stream_footer(metadata, metadata.pop("_elapsed", None))
        return 0

    # Interactive REPL
    print("Knowa chat — type your question, or 'exit' to quit.")
    print()

    history: list[dict] = []

    while True:
        try:
            question = input("You: ").strip()
        except (EOFError, KeyboardInterrupt):
            print()
            return 0

        if not question:
            continue
        if question.lower() in ("exit", "quit", "q"):
            return 0

        metadata = _run_stream(question, history or None)
        if metadata is None:
            continue
        _print_stream_footer(metadata, metadata.pop("_elapsed", None))

        # Append raw Q+A to history using the clean answer (Sources: line stripped)
        history.append({"role": "user", "content": question})
        history.append({"role": "assistant", "content": metadata["answer"]})

        # Keep at most 10 messages (5 pairs)
        if len(history) > 10:
            history = history[-10:]


# ── parser ────────────────────────────────────────────────────────────────────

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="knowa",
        description="Knowa command-line tool",
    )
    sub = parser.add_subparsers(dest="command", metavar="<command>")
    sub.required = True

    # help
    help_p = sub.add_parser("help", help="Show available commands")
    help_p.set_defaults(func=cmd_help)

    # list
    list_p = sub.add_parser(
        "list",
        help="List all indexed sources with page and chunk counts",
    )
    list_p.set_defaults(func=cmd_list)

    # index
    index_p = sub.add_parser(
        "index",
        help="Index a local directory recursively",
        description=(
            "Recursively index all .md, .txt, .pdf, and .docx files in a directory.\n"
            "Runs an incremental sync by default (re-processes only changed files).\n\n"
            "Default mode shows a progress bar.\n"
            "Use --verbose for raw log output (useful for debugging)."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    index_p.add_argument("directory", help="Path to the directory to index")
    index_p.add_argument(
        "--full",
        action="store_true",
        default=False,
        help="Force a full rebuild, ignoring last-sync state",
    )
    index_p.add_argument(
        "--name",
        metavar="LABEL",
        default=None,
        help="Friendly label for this source (shown in 'list', usable in 'chat --source')",
    )
    index_p.add_argument(
        "--workers",
        metavar="N",
        type=int,
        default=1,
        help="Number of parallel indexing threads (default: 1)",
    )
    index_p.add_argument(
        "--verbose", "-v",
        action="store_true",
        default=False,
        help="Show raw debug output instead of the progress bar",
    )
    index_p.set_defaults(func=cmd_index)

    # clear
    clear_p = sub.add_parser(
        "clear",
        help="Delete indexed data for a source",
        description=(
            "Delete pages, chunks, graph data, and sync state for a source.\n\n"
            "Targets (pick one):\n"
            "  <directory>          path to a local directory\n"
            "  --source-id <id>     source ID shown by 'list' (for Notion/Confluence)\n"
            "  --all                every indexed source\n\n"
            "A subsequent 'index' run will treat the cleared source as new."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    clear_p.add_argument(
        "directory",
        nargs="?",
        default=None,
        help="Path to a local directory to clear",
    )
    clear_p.add_argument(
        "--source-id",
        metavar="ID",
        default=None,
        help="Clear a specific source by its ID (as shown in 'list')",
    )
    clear_p.add_argument(
        "--all",
        action="store_true",
        default=False,
        help="Clear all indexed sources",
    )
    clear_p.add_argument(
        "--yes", "-y",
        action="store_true",
        default=False,
        help="Skip the confirmation prompt",
    )
    clear_p.set_defaults(func=cmd_clear)

    # chat
    chat_p = sub.add_parser(
        "chat",
        help="Query the index — interactive REPL or single-shot",
        description=(
            "Ask questions against the indexed knowledge base.\n\n"
            "Interactive mode (no argument): start a conversation loop.\n"
            "Single-shot mode: pass your question as an argument.\n\n"
            "Conversation history is kept for the duration of the session only."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    chat_p.add_argument(
        "question",
        nargs="?",
        default=None,
        help="Question to ask (omit for interactive REPL)",
    )
    chat_p.add_argument(
        "--source",
        metavar="LABEL_OR_ID",
        default=None,
        help="Limit retrieval to a specific source — accepts a label or the source ID from 'list'",
    )
    chat_p.add_argument(
        "--debug",
        action="store_true",
        default=False,
        help="Show retrieval path (vector chunk scores, FTS pages, graph triples) before each answer",
    )
    chat_p.add_argument(
        "--no-index",
        metavar="DIRECTORY",
        default=None,
        help="Skip the index — read documents directly from DIRECTORY and send as context",
    )
    chat_p.set_defaults(func=cmd_chat)

    # debug
    debug_p = sub.add_parser(
        "debug",
        help="Show graph backend status, node/edge counts, and sample entities",
    )
    debug_p.set_defaults(func=cmd_debug)

    # bench
    bench_p = sub.add_parser(
        "bench",
        help="Run questions with and without index, compare answers and timing",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        description=(
            "Run a set of questions against the index (hybrid RAG) and optionally\n"
            "against raw documents (no index), then print a timing summary.\n\n"
            "Input JSON format:\n"
            "  {\n"
            '    "source": "Engineering Docs",    (optional)\n'
            '    "no_index_dir": "/path/to/docs", (optional)\n'
            '    "questions": ["Q1", "Q2", ...]\n'
            "  }"
        ),
    )
    bench_p.add_argument("file", metavar="FILE", help="Path to JSON benchmark file")
    bench_p.set_defaults(func=cmd_bench)

    return parser


def main() -> None:
    parser = build_parser()
    if len(sys.argv) == 1:
        cmd_help(argparse.Namespace())
        sys.exit(0)
    args = parser.parse_args()
    sys.exit(args.func(args))


if __name__ == "__main__":
    main()