footprinter-cli 1.0.0rc1__py3-none-any.whl

footprinter/cli/_prompt.py

@@ -0,0 +1,220 @@
+"""Safe prompt wrappers with Escape key and Ctrl+C/Ctrl+D support.
+
+Wraps Rich's ``Prompt`` and ``Confirm`` to detect Escape (via raw terminal)
+and convert ``KeyboardInterrupt``/``EOFError`` into ``PromptCancelled``.
+
+``PromptCancelled`` inherits from ``BaseException`` so it passes through the
+~9 ``except Exception`` broad catches in the setup wizard without being
+swallowed.
+"""
+
+import os
+import sys
+
+from rich.prompt import Confirm, Prompt
+
+try:
+    import select
+    import termios
+    import tty
+
+    _HAS_TERMIOS = True
+except ImportError:
+    # Windows or other non-POSIX — fall back to input()
+    select = None  # type: ignore[assignment]
+    termios = None  # type: ignore[assignment]
+    tty = None  # type: ignore[assignment]
+    _HAS_TERMIOS = False
+
+
+class PromptCancelled(BaseException):
+    """Raised when the user presses Escape, Ctrl+C, or Ctrl+D at a prompt.
+
+    Inherits from ``BaseException`` (not ``Exception``) so it propagates
+    through ``except Exception`` blocks in wizard steps.
+    """
+
+
+_ESCAPE_TIMEOUT = 0.05  # 50ms to distinguish bare Escape from escape sequences
+
+
+def _read_utf8_char(fd: int, lead: int) -> tuple[str, bytes]:
+    """Read a complete UTF-8 character given its lead byte.
+
+    Determines the expected continuation byte count from the lead byte
+    pattern, reads that many bytes via ``_read_with_timeout``, and decodes.
+
+    Returns ``(char, leftover)`` where *char* is the decoded character
+    (empty string on failure) and *leftover* is a non-continuation byte
+    that was consumed but could not be used — the caller must re-process it.
+    """
+    if 0xC0 <= lead <= 0xDF:
+        n = 1
+    elif 0xE0 <= lead <= 0xEF:
+        n = 2
+    elif 0xF0 <= lead <= 0xF7:
+        n = 3
+    else:
+        return ("", b"")
+
+    raw = bytes([lead])
+    for _ in range(n):
+        b = _read_with_timeout(fd, _ESCAPE_TIMEOUT)
+        if not b:
+            return ("", b"")
+        if not (0x80 <= b[0] <= 0xBF):
+            return ("", b)  # Return consumed byte for re-processing
+        raw += b
+
+    decoded = raw.decode("utf-8", errors="replace")
+    if "\ufffd" in decoded:
+        return ("", b"")
+    return (decoded, b"")
+
+
+def _read_with_timeout(fd: int, timeout: float) -> bytes:
+    """Read a single byte from *fd* with a timeout via ``select``."""
+    ready, _, _ = select.select([fd], [], [], timeout)
+    if ready:
+        return os.read(fd, 1)
+    return b""
+
+
+def _safe_readline(password: bool = False) -> str:
+    """Read a line from stdin with Escape/Ctrl+C/Ctrl+D detection.
+
+    Uses raw terminal mode on POSIX systems. Falls back to ``input()``
+    when termios is unavailable (Windows, non-TTY, piped input).
+    """
+    if not _HAS_TERMIOS or not sys.stdin.isatty():
+        try:
+            return input()
+        except (KeyboardInterrupt, EOFError) as exc:
+            raise PromptCancelled(str(exc)) from exc
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    buf: list[str] = []
+
+    try:
+        tty.setraw(fd)
+        pending = b""
+
+        while True:
+            if pending:
+                ch = pending
+                pending = b""
+            else:
+                ready, _, _ = select.select([fd], [], [])
+                if not ready:
+                    continue
+                ch = os.read(fd, 1)
+
+            if not ch:
+                raise PromptCancelled("EOF")
+
+            byte = ch[0]
+
+            if byte == 0x1B:  # Escape
+                # Check if more bytes follow (escape sequence vs bare Escape)
+                follow = _read_with_timeout(fd, _ESCAPE_TIMEOUT)
+                if not follow:
+                    # Bare Escape — user pressed Esc
+                    raise PromptCancelled("Escape")
+                # Escape sequence — consume and ignore
+                if follow == b"[":
+                    # CSI sequence (\x1b[...) — consume until alpha terminator
+                    while True:
+                        seq_byte = _read_with_timeout(fd, _ESCAPE_TIMEOUT)
+                        if not seq_byte or (0x40 <= seq_byte[0] <= 0x7E):
+                            break
+                elif follow == b"O":
+                    # SS3 sequence (\x1bO..., e.g., F1–F4) — consume terminator
+                    _read_with_timeout(fd, _ESCAPE_TIMEOUT)
+                continue
+
+            if byte == 0x03:  # Ctrl+C
+                raise PromptCancelled("Ctrl+C")
+
+            if byte == 0x04:  # Ctrl+D
+                raise PromptCancelled("Ctrl+D")
+
+            if byte in (0x0D, 0x0A):  # Enter
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+                return "".join(buf)
+
+            if byte in (0x7F, 0x08):  # Backspace / Delete
+                if buf:
+                    buf.pop()
+                    if not password:
+                        sys.stdout.write("\b \b")
+                        sys.stdout.flush()
+                continue
+
+            if byte >= 0x80:  # High byte (UTF-8 lead or stray continuation)
+                char, leftover = _read_utf8_char(fd, byte)
+                if char:
+                    buf.append(char)
+                    if not password:
+                        sys.stdout.write(char)
+                        sys.stdout.flush()
+                if leftover:
+                    pending = leftover
+            elif byte >= 0x20:  # Printable ASCII character
+                buf.append(chr(byte))
+                if not password:
+                    sys.stdout.write(chr(byte))
+                    sys.stdout.flush()
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+class SafePrompt(Prompt):
+    """Rich Prompt subclass with Escape key and interrupt handling."""
+
+    @classmethod
+    def get_input(
+        cls,
+        console,  # noqa: ANN001
+        prompt,  # noqa: ANN001
+        password: bool = False,
+        stream=None,  # noqa: ANN001
+    ) -> str:
+        if stream is not None:
+            try:
+                return super().get_input(console, prompt, password=password, stream=stream)
+            except (KeyboardInterrupt, EOFError) as exc:
+                raise PromptCancelled(str(exc)) from exc
+
+        console.print(prompt, end="")
+        try:
+            return _safe_readline(password=password)
+        except PromptCancelled:
+            console.print()  # Newline after the prompt
+            raise
+
+
+class SafeConfirm(Confirm):
+    """Rich Confirm subclass with Escape key and interrupt handling."""
+
+    @classmethod
+    def get_input(
+        cls,
+        console,  # noqa: ANN001
+        prompt,  # noqa: ANN001
+        password: bool = False,
+        stream=None,  # noqa: ANN001
+    ) -> str:
+        if stream is not None:
+            try:
+                return super().get_input(console, prompt, password=password, stream=stream)
+            except (KeyboardInterrupt, EOFError) as exc:
+                raise PromptCancelled(str(exc)) from exc
+
+        console.print(prompt, end="")
+        try:
+            return _safe_readline(password=password)
+        except PromptCancelled:
+            console.print()  # Newline after the prompt
+            raise

footprinter/cli/_sample_seed.py

@@ -0,0 +1,204 @@
+"""Seed and clear sample data for new-user onboarding.
+
+``fp setup --seed-samples`` copies bundled sample files to FOOTPRINTER_HOME/samples/,
+inserts tagged records (``source='sample'``), and seeds demonstration access policies.
+
+``fp setup --clear-samples`` soft-deletes all sample records and removes sample policies.
+"""
+
+import os
+import shutil
+import sqlite3
+from pathlib import Path
+
+from footprinter.access import recalculate_access
+from footprinter.db.policies import set_permission_policy, set_visibility_policy
+from footprinter.paths import get_bundled_path, get_home
+
+SAMPLE_SOURCE = "sample"
+"""Value used in the ``source`` column to identify sample records."""
+
+_SAMPLE_FILES = [
+    "visible-file-sample.txt",
+    "opaque-project-file-sample.txt",
+    "hidden-client-file-sample.txt",
+]
+"""Bundled sample filenames (must match footprinter/bundled/samples/)."""
+
+
+def _get_sample_dir() -> Path:
+    """Return the sample-data directory inside FOOTPRINTER_HOME."""
+    return get_home() / "samples"
+
+
+def _copy_bundled_samples(sample_dir: Path) -> list[Path]:
+    """Copy bundled sample .txt files into *sample_dir*.
+
+    Returns list of destination paths.
+    """
+    sample_dir.mkdir(parents=True, exist_ok=True)
+    bundled = Path(get_bundled_path("samples"))
+    copied: list[Path] = []
+    for name in _SAMPLE_FILES:
+        src = bundled / name
+        dst = sample_dir / name
+        if src.exists():
+            shutil.copy2(src, dst)
+            copied.append(dst)
+    return copied
+
+
+def seed_samples(conn: sqlite3.Connection) -> dict:
+    """Create sample records and demonstration access policies.
+
+    Copies bundled sample files to ``~/.footprinter/samples/``, inserts
+    folder + file records tagged with ``source='sample'``, seeds policies
+    that demonstrate the access-control hierarchy, and stamps
+    ``mcp_view``/``mcp_read`` columns via ``recalculate_access()``.
+
+    Idempotent — re-running skips existing records via INSERT OR IGNORE.
+
+    Returns:
+        Dict with ``files_created``, ``folder_created``, ``policies_seeded``.
+    """
+    sample_dir = _get_sample_dir()
+    copied = _copy_bundled_samples(sample_dir)
+
+    cursor = conn.cursor()
+
+    # --- Source row (required FK target on some queries) ---
+    cursor.execute(
+        "INSERT OR IGNORE INTO sources (name, source_type, adapter, account, label, icon, enabled) "
+        "VALUES (?, 'file', 'sample', NULL, 'Sample Data', 'beaker', 1)",
+        (SAMPLE_SOURCE,),
+    )
+
+    # --- Folder ---
+    sample_path = str(sample_dir)
+    relative = sample_path.replace(os.path.expanduser("~"), "").lstrip(os.sep)
+    cursor.execute(
+        "INSERT OR IGNORE INTO folders (path, relative_path, name, source) "
+        "VALUES (?, ?, 'samples', ?)",
+        (sample_path, relative, SAMPLE_SOURCE),
+    )
+    conn.commit()
+
+    folder_id = cursor.execute(
+        "SELECT id FROM folders WHERE path = ?", (sample_path,)
+    ).fetchone()[0]
+
+    # --- Files ---
+    files_created = 0
+    file_ids: dict[str, int] = {}
+    for file_path in copied:
+        name = file_path.name
+        full_path = str(file_path)
+        size = file_path.stat().st_size if file_path.exists() else 0
+        # Guard: skip if this sample file already exists (idempotency)
+        existing = cursor.execute(
+            "SELECT id FROM files WHERE path = ? AND source = ?",
+            (full_path, SAMPLE_SOURCE),
+        ).fetchone()
+        if existing is None:
+            cursor.execute(
+                "INSERT INTO files (name, path, source, status, content_type, size_bytes, folder_id) "
+                "VALUES (?, ?, ?, 'active', 'text', ?, ?)",
+                (name, full_path, SAMPLE_SOURCE, size, folder_id),
+            )
+            files_created += cursor.rowcount
+
+    conn.commit()
+
+    # Collect IDs for policy seeding
+    rows = cursor.execute(
+        "SELECT id, name FROM files WHERE source = ? AND status != 'removed'",
+        (SAMPLE_SOURCE,),
+    ).fetchall()
+    for row in rows:
+        file_ids[row[1]] = row[0]
+
+    # --- Demonstration policies ---
+    policies_seeded = 0
+
+    # visible-file-sample.txt → visible + allow (default, no override needed)
+    # opaque-project-file-sample.txt → opaque visibility
+    opaque_id = file_ids.get("opaque-project-file-sample.txt")
+    if opaque_id:
+        set_visibility_policy(conn, f"file:{opaque_id}", "opaque")
+        policies_seeded += 1
+
+    # hidden-client-file-sample.txt → hidden visibility + deny read
+    hidden_id = file_ids.get("hidden-client-file-sample.txt")
+    if hidden_id:
+        set_visibility_policy(conn, f"file:{hidden_id}", "hidden")
+        set_permission_policy(conn, f"file:{hidden_id}", "deny")
+        policies_seeded += 2
+
+    # Stamp mcp_view/mcp_read columns
+    recalculate_access(conn, "global")
+
+    return {
+        "files_created": files_created,
+        "folder_created": 1,
+        "policies_seeded": policies_seeded,
+    }
+
+
+def clear_samples(conn: sqlite3.Connection) -> dict:
+    """Remove all sample records and policies.
+
+    Soft-deletes entity records (``status='removed'``) per the project's
+    never-delete-rows convention.  Hard-deletes policy rows since the
+    policy tables have no status column.
+
+    Returns:
+        Dict with ``files_removed``, ``folders_removed``, ``policies_removed``.
+    """
+    cursor = conn.cursor()
+
+    # Find sample file IDs for policy cleanup
+    sample_file_ids = [
+        row[0]
+        for row in cursor.execute(
+            "SELECT id FROM files WHERE source = ? AND status != 'removed'",
+            (SAMPLE_SOURCE,),
+        ).fetchall()
+    ]
+
+    # Soft-delete files
+    cursor.execute(
+        "UPDATE files SET status = 'removed', status_reason = 'sample:cleared' "
+        "WHERE source = ? AND status != 'removed'",
+        (SAMPLE_SOURCE,),
+    )
+    files_removed = cursor.rowcount
+
+    # Soft-delete folders
+    cursor.execute(
+        "UPDATE folders SET status = 'removed' "
+        "WHERE source = ? AND status != 'removed'",
+        (SAMPLE_SOURCE,),
+    )
+    folders_removed = cursor.rowcount
+
+    # Remove item-level policies for sample files
+    policies_removed = 0
+    for fid in sample_file_ids:
+        cursor.execute(
+            "DELETE FROM visibility_policies WHERE scope = ?",
+            (f"file:{fid}",),
+        )
+        policies_removed += cursor.rowcount
+        cursor.execute(
+            "DELETE FROM permission_policies WHERE scope = ?",
+            (f"file:{fid}",),
+        )
+        policies_removed += cursor.rowcount
+
+    conn.commit()
+
+    return {
+        "files_removed": files_removed,
+        "folders_removed": folders_removed,
+        "policies_removed": policies_removed,
+    }

footprinter/cli/api_cmd.py

@@ -0,0 +1,32 @@
+"""fp api — start the HTTP API server."""
+
+from footprinter.cli._common import FORMATTER
+
+
+def _start_api(args) -> None:
+    from footprinter.api.server import main
+
+    main(host=args.host, port=args.port)
+
+
+def register(subparsers) -> None:
+    """Register the ``api`` subcommand."""
+    parser = subparsers.add_parser(
+        "api",
+        help="Start the HTTP API server",
+        description=(
+            "Start the Footprinter HTTP API server.\n\n"
+            "Provides REST endpoints for programmatic access to indexed data.\n"
+            "Auto-generated docs available at /docs (Swagger UI)."
+        ),
+        epilog=(
+            "examples:\n"
+            "  fp api                     Start on localhost:8000\n"
+            "  fp api --port 9000         Start on custom port\n"
+            "  fp api --host 0.0.0.0      Listen on all interfaces"
+        ),
+        formatter_class=FORMATTER,
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8000, help="Port to bind (default: 8000)")
+    parser.set_defaults(func=_start_api)