pyrepowiki-cli 0.1.0__py3-none-any.whl

repowiki/services/deepwiki/cli.py

@@ -0,0 +1,851 @@
+"""CLI entry point for repowiki-cli."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import sys
+from dataclasses import asdict
+from datetime import datetime
+from typing import NoReturn, Optional
+from uuid import uuid4
+
+import typer
+from typer.core import TyperCommand
+
+from repowiki.services.deepwiki.client import (
+    ConnectionError,
+    DeepWikiClient,
+    DeepWikiError,
+    ToolError,
+)
+from repowiki.shared.async_ import run_async
+from repowiki.services.deepwiki.codemap import codemap_to_mermaid
+from repowiki.services.deepwiki.devin import DevinClient
+from repowiki.shared.export import export_pages
+from repowiki.shared.model import Answer
+from repowiki.shared.output import (
+    filter_page,
+    format_answer,
+    format_answer_tail,
+    format_command_json,
+    format_error_json,
+    format_header,
+    format_json,
+    format_list,
+    format_result,
+    format_status,
+    format_warm,
+    render_markdown,
+    split_pages,
+    status,
+)
+from repowiki.shared.repo import normalize_repo
+from repowiki.shared.save import append_entry, default_save_path
+
+deepwiki_app = typer.Typer(add_completion=False, help="Query DeepWiki documentation.")
+
+# Sentinel injected into argv for a bare ``--save`` (no value). ``save`` then
+# resolves to an auto-generated filename instead of an explicit path.
+_SAVE_AUTO = "\x00auto\x00"
+
+
+def _normalize_save(args: list[str]) -> list[str]:
+    """Turn a bare ``--save`` into ``--save <sentinel>`` so typer accepts it.
+
+    Typer has no support for Click's optional-value flags (``flag_value``), so a
+    value-taking ``--save`` normally rejects a bare ``--save``. Rewriting the
+    bare form here lets a single option cover both ``--save`` and
+    ``--save PATH``.
+    """
+    out: list[str] = []
+    i = 0
+    while i < len(args):
+        tok = args[i]
+        out.append(tok)
+        if tok == "--save":
+            if i + 1 >= len(args) or args[i + 1].startswith("-"):
+                out.append(_SAVE_AUTO)
+            else:
+                out.append(args[i + 1])
+                i += 1
+        i += 1
+    return out
+
+
+class _AskCommand(TyperCommand):
+    def parse_args(self, ctx, args):
+        return super().parse_args(ctx, _normalize_save(args))
+
+
+def _error_message(exc: Exception) -> str:
+    if isinstance(exc, ConnectionError):
+        return str(exc) or "Could not connect to DeepWiki server. Check your connection and try again."
+    if isinstance(exc, ToolError):
+        return str(exc)
+    if isinstance(exc, DeepWikiError):
+        return str(exc)
+    return f"Unexpected error: {exc}"
+
+
+def _error_kind(exc: Exception) -> str:
+    if isinstance(exc, ConnectionError):
+        return "connection"
+    if isinstance(exc, ToolError):
+        message = str(exc).lower()
+        if any(
+            token in message
+            for token in ("not indexed", "not_indexed", "not found", "to index")
+        ):
+            return "not_indexed"
+        return "tool"
+    if isinstance(exc, DeepWikiError):
+        return "error"
+    return "unexpected"
+
+
+def _exit_code(kind: str) -> int:
+    return {"not_indexed": 2, "connection": 3}.get(kind, 1)
+
+
+def _fail(message: str, kind: str, json_mode: bool) -> NoReturn:
+    """Print an error (JSON on stderr when requested) and exit."""
+    if json_mode:
+        typer.echo(format_error_json(kind, message), err=True)
+    else:
+        typer.secho(f"Error: {message}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=_exit_code(kind))
+
+
+def _print_error(exc: Exception) -> None:
+    typer.secho(f"Error: {_error_message(exc)}", fg=typer.colors.RED, err=True)
+
+
+def _handle_exception(exc: Exception, json_mode: bool = False) -> None:
+    _fail(_error_message(exc), _error_kind(exc), json_mode)
+
+
+def _resolve_repo(raw: str, json_mode: bool = False) -> str:
+    try:
+        return normalize_repo(raw)
+    except ValueError as exc:
+        _fail(str(exc), "invalid_repo", json_mode)
+
+
+def _mock_text() -> Optional[str]:
+    return os.environ.get("REPOWIKI_MOCK_TEXT")
+
+
+def _repl_prompt() -> str:
+    """Return the REPL input prompt, colored only on a terminal."""
+    if not sys.stdout.isatty():
+        return ">> "
+    return typer.style(">> ", fg=typer.colors.CYAN, bold=True)
+
+
+def _emit(
+    repo: str,
+    command: str,
+    text: str,
+    rich: bool,
+    json_mode: bool = False,
+    **json_fields: object,
+) -> None:
+    if json_mode:
+        typer.echo(format_json(repo, command, **json_fields))
+        return
+    rendered = format_result("DeepWiki", repo, command, text)
+    if rich:
+        render_markdown(rendered)
+    else:
+        typer.echo(rendered)
+
+
+def _run_ask(
+    repos: list[str],
+    question: str,
+    mode: str | None,
+    query_id: str | None,
+    use_devin: bool,
+    context: str,
+    generate_summary: bool,
+    on_chunk=None,
+    timeout: float | None = None,
+) -> Answer:
+    if use_devin:
+        if (mock := os.environ.get("REPOWIKI_DEVIN_MOCK")) is not None:
+            return Answer(body=mock)
+        resolved_mode = mode or "fast"
+        resolved_timeout = _answer_timeout(resolved_mode, timeout)
+        return run_async(
+            _ask_reverse(
+                DevinClient(),
+                repos,
+                question,
+                mode=resolved_mode,
+                query_id=query_id,
+                context=context,
+                generate_summary=generate_summary,
+                timeout=resolved_timeout,
+                on_chunk=on_chunk,
+            )
+        )
+    if (mock := _mock_text()) is not None:
+        return Answer(body=mock)
+    return run_async(DeepWikiClient().ask_question(repos[0], question))
+
+
+def _stream_chunk(text: str) -> None:
+    sys.stdout.write(text)
+    sys.stdout.flush()
+
+
+def _emit_streamed_answer(answer: Answer, show_sources: bool) -> None:
+    tail = format_answer_tail(answer, show_sources=show_sources)
+    if tail:
+        typer.echo(f"\n\n{tail}")
+    else:
+        typer.echo()
+
+
+def _answer_json_fields(answer: Answer) -> dict[str, object]:
+    fields: dict[str, object] = {
+        "answer": answer.body,
+    }
+    if answer.summary:
+        fields["summary"] = answer.summary
+    if answer.references:
+        fields["references"] = [asdict(r) for r in answer.references]
+    if answer.sources:
+        fields["sources"] = [asdict(s) for s in answer.sources]
+    if answer.stats:
+        fields["stats"] = answer.stats
+    if answer.query_id:
+        fields["query_id"] = answer.query_id
+    return fields
+
+
+def _emit_answer(
+    repo: str,
+    question: str,
+    answer: Answer,
+    rich: bool,
+    json_mode: bool,
+    show_sources: bool,
+) -> None:
+    if json_mode:
+        fields = _answer_json_fields(answer)
+        fields = {"question": question, **fields}
+        typer.echo(format_json(repo, "ask", **fields))
+        return
+    _emit(repo, "ask", format_answer(answer, show_sources=show_sources), rich, False)
+
+
+def _append_save(path: str | None, repo: str, question: str, answer: str) -> None:
+    if path is None:
+        return
+    try:
+        append_entry(path, repo, question, answer)
+    except OSError as exc:
+        typer.secho(
+            f"Warning: could not save to {path}: {exc}",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+
+
+async def _repl(resolved: str, rich: bool, save_path: str | None) -> None:
+    prompt = _repl_prompt()
+    async with DeepWikiClient() as client:
+        while True:
+            try:
+                line = input(prompt)
+            except (EOFError, KeyboardInterrupt):
+                typer.echo()
+                break
+            q = line.strip()
+            if not q:
+                continue
+            if q in ("/exit", "/quit", "/q"):
+                break
+            try:
+                with status("Thinking..."):
+                    answer = await client.ask_question(resolved, q)
+            except Exception as exc:
+                _print_error(exc)
+                continue
+            _append_save(save_path, resolved, q, answer.body)
+            typer.echo()
+            if rich:
+                render_markdown(answer.body.strip())
+            else:
+                typer.echo(answer.body.strip())
+            typer.echo()
+
+
+_REPL_RETRY_BASE = 1.0
+_REPL_RETRY_JITTER = 0.5
+_REPL_DEFAULT_ATTEMPTS = 4
+
+_DEFAULT_TIMEOUT = 120.0
+_DEEP_TIMEOUT = 300.0
+
+
+def _repl_attempts() -> int:
+    raw = os.environ.get("DEEPWIKI_REPL_RETRIES", "")
+    if raw.isdigit() and int(raw) > 0:
+        return int(raw)
+    return _REPL_DEFAULT_ATTEMPTS
+
+
+def _answer_timeout(mode: str, explicit: float | None) -> float:
+    """Resolve the answer timeout: explicit flag, then env, then mode default."""
+    if explicit is not None:
+        return explicit
+    raw = os.environ.get("DEEPWIKI_TIMEOUT", "").strip()
+    if raw:
+        try:
+            value = float(raw)
+        except ValueError:
+            value = -1.0
+        if value > 0:
+            return value
+    return _DEEP_TIMEOUT if mode == "deep" else _DEFAULT_TIMEOUT
+
+
+def _retry_delay(attempt: int) -> float:
+    return _REPL_RETRY_BASE * (2 ** attempt) + random.uniform(0, _REPL_RETRY_JITTER)
+
+
+def _is_retryable(exc: Exception) -> bool:
+    """True for transient failures worth retrying (connection / 5xx)."""
+    if isinstance(exc, ConnectionError):
+        return True
+    if isinstance(exc, ToolError):
+        return "HTTP 5" in str(exc)
+    return False
+
+
+async def _ask_reverse(
+    devin: DevinClient,
+    repos: list[str],
+    question: str,
+    *,
+    mode: str,
+    query_id: str | None,
+    context: str,
+    generate_summary: bool,
+    timeout: float,
+    on_chunk=None,
+) -> Answer:
+    """Ask the reverse backend with jittered backoff retry.
+
+    Retries transient failures (connection / HTTP 5xx) only while nothing has
+    streamed yet — once a partial answer has reached the terminal, a dropped
+    connection is reported rather than re-streaming garbled text.
+    """
+    qid = query_id or str(uuid4())
+    emitted = 0
+    attempts = _repl_attempts()
+    for attempt in range(attempts):
+        if on_chunk is not None:
+            def wrapped(text: str) -> None:
+                nonlocal emitted
+                emitted += 1
+                on_chunk(text)
+        else:
+            wrapped = None
+
+        try:
+            return await devin.ask(
+                repos,
+                question,
+                mode=mode,
+                query_id=qid,
+                context=context,
+                generate_summary=generate_summary,
+                timeout=timeout,
+                on_chunk=wrapped,
+            )
+        except Exception as exc:
+            if not _is_retryable(exc) or emitted:
+                raise
+            if attempt == attempts - 1:
+                raise
+            delay = _retry_delay(attempt)
+            typer.secho(
+                f"Transient error ({_error_message(exc)}); retrying in {delay:.1f}s…",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+            await asyncio.sleep(delay)
+    raise ToolError("retries exhausted")
+
+
+async def _repl_devin(
+    repos: list[str],
+    rich: bool,
+    save_path: str | None,
+    mode: str,
+    initial_query_id: str | None,
+    show_sources: bool,
+    context: str,
+    generate_summary: bool,
+    timeout: float,
+) -> None:
+    prompt = _repl_prompt()
+    devin = DevinClient()
+    last_qid = initial_query_id
+    while True:
+        try:
+            line = input(prompt)
+        except (EOFError, KeyboardInterrupt):
+            typer.echo()
+            break
+        q = line.strip()
+        if not q:
+            continue
+        if q in ("/exit", "/quit", "/q"):
+            break
+        if q == "/new":
+            last_qid = None
+            typer.echo("(started a new thread)")
+            continue
+        try:
+            with status("Thinking..."):
+                answer = await _ask_reverse(
+                    devin, repos, q, mode=mode, query_id=last_qid,
+                    context=context, generate_summary=generate_summary,
+                    timeout=timeout,
+                )
+        except Exception as exc:
+            _print_error(exc)
+            continue
+        last_qid = answer.query_id
+        _append_save(save_path, repos[0], q, answer.body)
+        rendered = format_answer(answer, show_sources=show_sources)
+        if rich:
+            render_markdown(rendered)
+        else:
+            typer.echo(f"\n\n{rendered}")
+        typer.echo()
+
+
+@deepwiki_app.command()
+def structure(
+    repo: str = typer.Argument(..., help="Repository (owner/repo or GitHub URL)"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Show the documentation table of contents for a repository."""
+    resolved = _resolve_repo(repo, json)
+    if (mock := _mock_text()) is not None:
+        _emit(resolved, "structure", mock, False, json, content=mock)
+        return
+    client = DeepWikiClient()
+    try:
+        with status("Fetching table of contents..."):
+            text = run_async(client.read_wiki_structure(resolved))
+    except Exception as exc:
+        _handle_exception(exc, json)
+    _emit(resolved, "structure", text, False, json, content=text)
+
+
+@deepwiki_app.command()
+def contents(
+    repo: str = typer.Argument(..., help="Repository (owner/repo or GitHub URL)"),
+    page: Optional[str] = typer.Option(None, "--page", help="Show only the page with this title"),
+    rich: bool = typer.Option(False, "--rich", help="Render Markdown with rich"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Show the full documentation for a repository."""
+    resolved = _resolve_repo(repo, json)
+    if (mock := _mock_text()) is not None:
+        text = mock
+    else:
+        client = DeepWikiClient()
+        try:
+            with status("Fetching documentation..."):
+                text = run_async(client.read_wiki_contents(resolved))
+        except Exception as exc:
+            _handle_exception(exc, json)
+    if page is not None:
+        try:
+            text = filter_page(text, page)
+        except ValueError as exc:
+            _fail(str(exc), "page_not_found", json)
+    fields: dict[str, object] = {"content": text}
+    if page is not None:
+        fields["page"] = page
+    _emit(resolved, "contents", text, rich, json, **fields)
+
+
+@deepwiki_app.command(cls=_AskCommand)
+def ask(
+    repo: str = typer.Argument(..., help="Repository (owner/repo or GitHub URL)"),
+    question: Optional[str] = typer.Argument(None, help="Question (omit for interactive mode)"),
+    rich: bool = typer.Option(False, "--rich", help="Render Markdown with rich"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+    save: Optional[str] = typer.Option(
+        None,
+        "--save",
+        help="Save answers to a Markdown file. Bare --save auto-names the file; "
+        "--save PATH writes/appends to PATH.",
+    ),
+    mode: Optional[str] = typer.Option(
+        None, "--mode", help="Engine: fast, deep, or codemap (reverse backend)",
+    ),
+    query_id: Optional[str] = typer.Option(
+        None, "--id", help="Continue a thread from a previous query id (reverse backend)",
+    ),
+    sources: bool = typer.Option(
+        False, "--sources", help="Show source-code slices for citations (reverse backend)",
+    ),
+    no_summary: bool = typer.Option(
+        False, "--no-summary", help="Skip summary generation (reverse backend)",
+    ),
+    context: Optional[str] = typer.Option(
+        None, "--context", help="Additional context for the question (reverse backend)",
+    ),
+    extra_repos: Optional[list[str]] = typer.Option(
+        None, "--repo", help="Additional repos to query (repeatable, reverse backend)",
+    ),
+    mermaid: bool = typer.Option(
+        False, "--mermaid", help="Output a Mermaid diagram (codemap mode only)",
+    ),
+    stream: bool = typer.Option(
+        False, "--stream", help="Stream answer chunks as they arrive (reverse backend)",
+    ),
+    timeout: Optional[float] = typer.Option(
+        None, "--timeout", help="Answer timeout in seconds (reverse backend). "
+        "Default: 120s, or 300s for --mode deep.",
+    ),
+) -> None:
+    """Ask a question about a repository (single-shot or interactive)."""
+    resolved = _resolve_repo(repo, json)
+    save_path = default_save_path(resolved) if save == _SAVE_AUTO else save
+
+    if mode is not None and mode not in ("fast", "deep", "codemap"):
+        _fail(f"Invalid --mode: {mode!r} (expected fast, deep, or codemap).", "invalid_input", json)
+    if timeout is not None and timeout <= 0:
+        _fail("--timeout must be a positive number of seconds.", "invalid_input", json)
+    all_repos = [resolved] + [_resolve_repo(r, json) for r in (extra_repos or [])]
+    use_devin = bool(mode or query_id or sources or extra_repos
+                     or (context is not None) or no_summary or stream)
+    generate_summary = not no_summary
+    context_value = context or ""
+    resolved_timeout = _answer_timeout(mode or "fast", timeout)
+
+    if stream and json:
+        typer.secho(
+            "Warning: --stream has no effect with --json.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+    if stream and rich:
+        typer.secho(
+            "Warning: --rich has no effect with --stream; the answer streams as plain text.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+
+    if question is not None:
+        if not question.strip():
+            _fail("Question must not be empty.", "invalid_input", json)
+        effective_qid = query_id or str(uuid4())
+        streamed = False
+        try:
+            if stream and not json:
+                answer = _run_ask(all_repos, question, mode, effective_qid, use_devin,
+                                  context_value, generate_summary, on_chunk=_stream_chunk,
+                                  timeout=timeout)
+                streamed = True
+            else:
+                with status("Thinking..."):
+                    answer = _run_ask(all_repos, question, mode, effective_qid, use_devin,
+                                      context_value, generate_summary, timeout=timeout)
+        except Exception as exc:
+            if stream and not json and _is_retryable(exc):
+                typer.secho(
+                    "\nStream dropped; retrieving the complete answer via polling…",
+                    fg=typer.colors.YELLOW,
+                    err=True,
+                )
+                try:
+                    with status("Thinking..."):
+                        answer = _run_ask(all_repos, question, mode, effective_qid, use_devin,
+                                          context_value, generate_summary, timeout=timeout)
+                except Exception as exc2:
+                    _handle_exception(exc2, json)
+                streamed = False
+            else:
+                _handle_exception(exc, json)
+        if mermaid:
+            mermaid_text = codemap_to_mermaid(answer.body)
+            if mermaid_text is not None:
+                if json:
+                    fields: dict[str, object] = {"question": question, "mermaid": mermaid_text}
+                    if answer.query_id:
+                        fields["query_id"] = answer.query_id
+                    typer.echo(format_json(resolved, "ask", **fields))
+                else:
+                    typer.echo(mermaid_text)
+                _append_save(save_path, resolved, question, mermaid_text)
+                return
+            typer.secho(
+                "Warning: --mermaid is set but the answer is not a codemap; showing as text.",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+        if streamed:
+            _emit_streamed_answer(answer, sources)
+        else:
+            _emit_answer(resolved, question, answer, rich, json, sources)
+        _append_save(save_path, resolved, question, answer.body)
+        return
+
+    if json:
+        typer.secho(
+            "Warning: --json has no effect in interactive mode.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+    typer.echo(format_header("DeepWiki", resolved, "ask"))
+    typer.echo()
+    hint = "Ask a question, or /exit to quit."
+    if use_devin:
+        hint += "  (/new starts a new thread)"
+    typer.echo(hint)
+    typer.echo()
+    try:
+        if use_devin:
+            run_async(_repl_devin(all_repos, rich, save_path, mode or "fast", query_id,
+                                  sources, context_value, generate_summary, resolved_timeout))
+        else:
+            run_async(_repl(resolved, rich, save_path))
+    except Exception as exc:
+        _handle_exception(exc)
+
+
+@deepwiki_app.command("list")
+def list_indexes(
+    search: str = typer.Argument(..., help="Search term for indexed repos"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Search DeepWiki's indexed public repositories."""
+    client = DevinClient()
+    try:
+        with status("Searching..."):
+            result = run_async(client.list_public_indexes(search))
+    except Exception as exc:
+        _handle_exception(exc, json)
+    if json:
+        typer.echo(format_command_json(
+            "list", search=search,
+            indices=result.get("indices") or [],
+            needs_reindex=result.get("needs_reindex") or [],
+            pending_repos=result.get("pending_repos") or [],
+        ))
+        return
+    typer.echo(format_list(result))
+
+
+# Named ``status_cmd`` (not ``status``) because the module-level ``status``
+# spinner contextmanager from ``repowiki.shared.output`` is referenced by every other
+# command; a function named ``status`` would shadow it. The CLI name stays
+# ``status`` via the explicit decorator argument, mirroring ``list``.
+@deepwiki_app.command("status")
+def status_cmd(
+    repo: str = typer.Argument(..., help="Repository (owner/repo or GitHub URL)"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Check a repository's indexing status on DeepWiki."""
+    resolved = _resolve_repo(repo, json)
+    client = DevinClient()
+    try:
+        with status("Checking..."):
+            result = run_async(client.public_repo_indexing_status(resolved))
+    except Exception as exc:
+        _handle_exception(exc, json)
+    if json:
+        typer.echo(format_command_json("status", repo=resolved, status=result.get("status") or "unknown"))
+        return
+    typer.echo(format_status(resolved, result))
+
+
+@deepwiki_app.command()
+def warm(
+    repo: str = typer.Argument(..., help="Repository (owner/repo or GitHub URL)"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Pre-warm a repository's documentation cache on DeepWiki."""
+    resolved = _resolve_repo(repo, json)
+    client = DevinClient()
+    try:
+        with status("Warming..."):
+            result = run_async(client.warm_public_repo(resolved))
+    except Exception as exc:
+        _handle_exception(exc, json)
+    if json:
+        typer.echo(format_command_json("warm", repo=resolved, status=result.get("status") or "OK"))
+        return
+    typer.echo(format_warm(resolved, result))
+
+
+@deepwiki_app.command()
+def get(
+    query_id: str = typer.Argument(..., help="Query id to retrieve"),
+    rich: bool = typer.Option(False, "--rich", help="Render Markdown with rich"),
+    sources: bool = typer.Option(False, "--sources", help="Show source-code slices"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+    mermaid: bool = typer.Option(
+        False, "--mermaid", help="Output a Mermaid diagram (codemap queries only)",
+    ),
+) -> None:
+    """Retrieve the result of a previous query by id."""
+    client = DevinClient()
+    try:
+        with status("Fetching..."):
+            answer = run_async(client.get_query(query_id))
+    except Exception as exc:
+        _handle_exception(exc, json)
+    if mermaid:
+        mermaid_text = codemap_to_mermaid(answer.body)
+        if mermaid_text is not None:
+            if json:
+                fields: dict[str, object] = {"mermaid": mermaid_text}
+                if answer.query_id:
+                    fields["query_id"] = answer.query_id
+                typer.echo(format_command_json("get", **fields))
+            else:
+                typer.echo(mermaid_text)
+            return
+        typer.secho(
+            "Warning: --mermaid is set but the answer is not a codemap; showing as text.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+    if json:
+        typer.echo(format_command_json("get", **_answer_json_fields(answer)))
+        return
+    rendered = format_answer(answer, show_sources=sources)
+    if rich:
+        render_markdown(rendered)
+    else:
+        typer.echo(rendered)
+
+
+def _short_sha(index_id: str) -> str:
+    """Extract the short commit sha from an index id (its last segment).
+
+    The last segment may carry a branch suffix (``59aff3e1::main``); keep only
+    the sha part before any ``::``.
+    """
+    last = index_id.rsplit("/", 1)[-1] if index_id else ""
+    return last.split("::", 1)[0]
+
+
+def _iso_to_local(value: str) -> str:
+    """Render an ISO-8601 timestamp as the local timezone's human form."""
+    try:
+        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return dt.astimezone().strftime("%Y-%m-%d %H:%M:%S %Z")
+    except (ValueError, TypeError):
+        return value
+
+
+def _format_stat(entry: dict, human: bool) -> str:
+    lines: list[str] = []
+    if entry.get("repo_name"):
+        lines.append(f"- repo: {entry['repo_name']}")
+    sha = _short_sha(entry.get("id") or "")
+    if sha:
+        lines.append(f"- commit: {sha}")
+    last_modified = entry.get("last_modified")
+    if last_modified:
+        if human:
+            lines.append(f"- last_indexed: {last_modified} ({_iso_to_local(last_modified)})")
+        else:
+            lines.append(f"- last_indexed: {last_modified}")
+    for key in ("language", "stargazers_count", "topics", "description"):
+        if entry.get(key) is not None:
+            lines.append(f"- {key}: {entry[key]}")
+    return "\n".join(lines) or "No data."
+
+
+def _format_stale(info: dict) -> str:
+    wiki_sha = info.get("wiki_sha") or ""
+    github_sha = info.get("github_sha") or ""
+    when = info.get("github_when") or ""
+    if not github_sha:
+        return "Could not fetch GitHub HEAD."
+    if not wiki_sha:
+        return "No commit sha in the index entry."
+    if github_sha.startswith(wiki_sha):
+        return f"最新 (up-to-date): {wiki_sha}"
+    suffix = f" ({when})" if when else ""
+    return f"过期 (stale): wiki {wiki_sha[:7]} != github {github_sha[:7]}{suffix}"
+
+
+@deepwiki_app.command()
+def stat(
+    repo: str = typer.Argument(..., help="Repository (owner/repo or GitHub URL)"),
+    human: bool = typer.Option(False, "--human", help="Show timestamps as human-readable local times"),
+    stale: bool = typer.Option(False, "--stale", help="Compare the indexed commit against GitHub HEAD"),
+    json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Show a repository's DeepWiki index metadata (last indexed time + commit)."""
+    resolved = _resolve_repo(repo, json)
+    client = DevinClient()
+    entry: dict | None = None
+    stale_info: dict | None = None
+    try:
+        with status("Fetching index info..."):
+            entry = run_async(client.repo_index(resolved))
+        if entry is not None and stale:
+            wiki_sha = _short_sha(entry.get("id") or "")
+            with status("Checking GitHub HEAD..."):
+                head = run_async(client.github_head(resolved))
+            stale_info = {
+                "wiki_sha": wiki_sha,
+                "github_sha": head.get("sha") or "",
+                "github_when": head.get("when") or "",
+            }
+    except Exception as exc:
+        _handle_exception(exc, json)
+    if entry is None:
+        _fail(f"No index entry found for {resolved}.", "not_indexed", json)
+    if json:
+        fields: dict[str, object] = {"repo": resolved, "data": entry}
+        if stale_info is not None:
+            fields["stale"] = stale_info
+        typer.echo(format_command_json("stat", **fields))
+        return
+    text = _format_stat(entry, human)
+    if stale_info is not None:
+        text += "\n\n" + _format_stale(stale_info)
+    typer.echo(format_result("DeepWiki", resolved, "stat", text))
+
+
+@deepwiki_app.command()
+def cp(
+    repo: str = typer.Argument(..., help="Repository (owner/repo or GitHub URL)"),
+    output_dir: Optional[str] = typer.Argument(None, help="Output directory"),
+) -> None:
+    """Export the whole wiki as Markdown files plus llms.txt."""
+    resolved = _resolve_repo(repo, False)
+    client = DeepWikiClient()
+    out = output_dir or resolved.replace("/", "_")
+    try:
+        with status("Exporting wiki..."):
+            text = run_async(client.read_wiki_contents(resolved))
+        pages = split_pages(text)
+        count = export_pages(out, resolved, pages, text)
+    except Exception as exc:
+        _handle_exception(exc, False)
+    typer.echo(f"Exported {count} pages to {out}")
+
+
+def register(app: typer.Typer) -> None:
+    """Mount the DeepWiki service commands on the root app."""
+    app.add_typer(deepwiki_app, name="deepwiki")