footprinter-cli 1.0.0__py3-none-any.whl

footprinter/cli/vectorize_cmd.py

@@ -0,0 +1,215 @@
+"""fp vectorize — manage per-record vectorization control flags.
+
+Commands:
+    fp vectorize exclude <entity> <id> [<id>...]   Mark records to skip vectorization
+    fp vectorize include <entity> <id> [<id>...]   Restore records for vectorization
+    fp vectorize review [<entity>]                 Show excluded record counts
+    fp vectorize import <path>                     Apply flags from a JSON file
+"""
+
+import argparse
+import json
+import sqlite3
+from pathlib import Path
+from typing import Optional, Union
+
+from rich.console import Console
+
+from footprinter.cli._common import FORMATTER, console, open_db
+
+# Entity types that support the vectorize flag
+ENTITY_TABLES = {"files": "files", "messages": "messages", "chats": "chats"}
+
+
+# ---------------------------------------------------------------------------
+# Core flag operations
+# ---------------------------------------------------------------------------
+
+
+def _set_vectorize_flag(
+    conn: sqlite3.Connection,
+    table: str,
+    ids: list[int],
+    value: int,
+) -> int:
+    """Set metadata.vectorize on records via json_set().
+
+    Returns the number of rows updated.
+    """
+    if not ids:
+        return 0
+    placeholders = ",".join("?" for _ in ids)
+    cursor = conn.execute(
+        f"UPDATE {table} SET metadata = json_set("
+        f"COALESCE(metadata, '{{}}'), '$.vectorize', ?) "
+        f"WHERE id IN ({placeholders}) AND status != 'removed'",
+        [value, *ids],
+    )
+    conn.commit()
+    return cursor.rowcount
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def _handle_exclude(
+    args: argparse.Namespace,
+    *,
+    db_path: Optional[Union[str, Path]] = None,
+    output: Optional[Console] = None,
+) -> None:
+    """Set metadata.vectorize=0 for given entity/IDs."""
+    table = ENTITY_TABLES.get(args.entity)
+    if not table:
+        (output or console).print(f"[red]Unknown entity:[/red] {args.entity}. Use one of: {', '.join(ENTITY_TABLES)}")
+        return
+
+    with open_db(db_path) as conn:
+        count = _set_vectorize_flag(conn, table, args.ids, 0)
+        (output or console).print(f"Excluded {count} {args.entity} from vectorization.")
+
+
+def _handle_include(
+    args: argparse.Namespace,
+    *,
+    db_path: Optional[Union[str, Path]] = None,
+    output: Optional[Console] = None,
+) -> None:
+    """Set metadata.vectorize=1 for given entity/IDs."""
+    table = ENTITY_TABLES.get(args.entity)
+    if not table:
+        (output or console).print(f"[red]Unknown entity:[/red] {args.entity}. Use one of: {', '.join(ENTITY_TABLES)}")
+        return
+
+    with open_db(db_path) as conn:
+        count = _set_vectorize_flag(conn, table, args.ids, 1)
+        (output or console).print(f"Included {count} {args.entity} for vectorization.")
+
+
+def _handle_review(
+    args: argparse.Namespace,
+    *,
+    db_path: Optional[Union[str, Path]] = None,
+    output: Optional[Console] = None,
+) -> None:
+    """Show counts of excluded records per entity."""
+    out = output or console
+    entities = (
+        {args.entity: ENTITY_TABLES[args.entity]} if args.entity and args.entity in ENTITY_TABLES else ENTITY_TABLES
+    )
+
+    from rich.table import Table
+
+    table = Table(title="Vectorization Exclusions")
+    table.add_column("Entity", style="bold")
+    table.add_column("Excluded", justify="right")
+    table.add_column("Total", justify="right")
+
+    with open_db(db_path) as conn:
+        for entity_name, table_name in entities.items():
+            excluded = conn.execute(
+                f"SELECT COUNT(*) as n FROM {table_name} "
+                f"WHERE json_extract(metadata, '$.vectorize') = 0 "
+                f"AND status != 'removed'"
+            ).fetchone()["n"]
+            total = conn.execute(f"SELECT COUNT(*) as n FROM {table_name} WHERE status != 'removed'").fetchone()["n"]
+            table.add_row(entity_name, str(excluded), str(total))
+
+    out.print(table)
+
+
+VALID_ACTIONS = frozenset({"exclude", "include"})
+
+
+def _handle_import(
+    args: argparse.Namespace,
+    *,
+    db_path: Optional[Union[str, Path]] = None,
+    output: Optional[Console] = None,
+) -> None:
+    """Apply vectorize flags from a JSON file."""
+    out = output or console
+    path = Path(args.path)
+    if not path.exists():
+        out.print(f"[red]File not found:[/red] {path}")
+        return
+
+    data = json.loads(path.read_text())
+
+    # Support structured format: {"entity": ..., "action": ..., "ids": [...]}
+    # and flat list format: [1, 2, 3] (defaults to files + exclude)
+    if isinstance(data, list):
+        entity = "files"
+        action = "exclude"
+        ids = [int(i) for i in data]
+    elif isinstance(data, dict):
+        entity = data.get("entity", "files")
+        action = data.get("action", "exclude")
+        ids = [int(i) for i in data.get("ids", [])]
+    else:
+        out.print("[red]Invalid JSON format.[/red] Expected a list or object.")
+        return
+
+    if action not in VALID_ACTIONS:
+        out.print(f"[red]Unknown action:[/red] {action}. Use one of: {', '.join(VALID_ACTIONS)}")
+        return
+
+    table = ENTITY_TABLES.get(entity)
+    if not table:
+        out.print(f"[red]Unknown entity:[/red] {entity}. Use one of: {', '.join(ENTITY_TABLES)}")
+        return
+
+    value = 0 if action == "exclude" else 1
+    with open_db(db_path) as conn:
+        count = _set_vectorize_flag(conn, table, ids, value)
+        verb = "Excluded" if action == "exclude" else "Included"
+        out.print(f"{verb} {count} {entity} via import.")
+
+
+# ---------------------------------------------------------------------------
+# CLI registration
+# ---------------------------------------------------------------------------
+
+
+def register(subparsers) -> None:
+    """Register the ``fp vectorize`` subcommand."""
+    parser = subparsers.add_parser(
+        "vectorize",
+        help="Manage per-record vectorization control",
+        description="Exclude or include individual records from vectorization.",
+        formatter_class=FORMATTER,
+    )
+    sub = parser.add_subparsers(dest="vectorize_action", metavar="ACTION")
+
+    # exclude
+    exc = sub.add_parser("exclude", help="Exclude records from vectorization")
+    exc.add_argument("entity", choices=list(ENTITY_TABLES), help="Entity type")
+    exc.add_argument("ids", nargs="+", type=int, help="Record IDs to exclude")
+    exc.set_defaults(func=lambda args: _handle_exclude(args))
+
+    # include
+    inc = sub.add_parser("include", help="Include records for vectorization")
+    inc.add_argument("entity", choices=list(ENTITY_TABLES), help="Entity type")
+    inc.add_argument("ids", nargs="+", type=int, help="Record IDs to include")
+    inc.set_defaults(func=lambda args: _handle_include(args))
+
+    # review
+    rev = sub.add_parser("review", help="Show excluded record counts")
+    rev.add_argument(
+        "entity",
+        nargs="?",
+        default=None,
+        choices=list(ENTITY_TABLES),
+        help="Filter to a specific entity type",
+    )
+    rev.set_defaults(func=lambda args: _handle_review(args))
+
+    # import
+    imp = sub.add_parser("import", help="Apply flags from a JSON file")
+    imp.add_argument("path", help="Path to JSON file")
+    imp.set_defaults(func=lambda args: _handle_import(args))
+
+    # Default: show help if no action given
+    parser.set_defaults(func=lambda args: parser.print_help())

footprinter/cli/view.py

@@ -0,0 +1,322 @@
+"""fp view — unified entity viewer with singular/plural noun convention.
+
+Routes ``fp view client 42`` (single record) and ``fp view clients``
+(paginated collection) through the service layer.  Supports ``--json``,
+``--csv``, and ``--verbose`` output flags.
+"""
+
+import sys
+
+from rich.panel import Panel
+from rich.table import Table
+
+from footprinter.cli._common import (
+    FORMATTER,
+    add_csv_flag,
+    add_json_flag,
+    add_verbose_flag,
+    console,
+    enrich_verbose_access,
+    format_size,
+    open_db,
+    output_csv,
+    output_json,
+    verbose_access_cells,
+)
+
+# ---------------------------------------------------------------------------
+# Entity dispatch table
+# ---------------------------------------------------------------------------
+
+#: Maps every recognised noun to (service_module, list_key, entity_type, mode).
+ENTITY_MAP: dict[str, tuple[str, str, str, str]] = {
+    # singular → single record
+    "client": ("client_service", "clients", "client", "single"),
+    "project": ("project_service", "projects", "project", "single"),
+    "file": ("file_service", "files", "file", "single"),
+    "folder": ("folder_service", "folders", "folder", "single"),
+    "chat": ("chat_service", "chats", "chat", "single"),
+    "email": ("email_service", "emails", "email", "single"),
+    "visit": ("visit_service", "visits", "visit", "single"),
+    # plural → paginated collection
+    "clients": ("client_service", "clients", "client", "collection"),
+    "projects": ("project_service", "projects", "project", "collection"),
+    "files": ("file_service", "files", "file", "collection"),
+    "folders": ("folder_service", "folders", "folder", "collection"),
+    "chats": ("chat_service", "chats", "chat", "collection"),
+    "emails": ("email_service", "emails", "email", "collection"),
+    "visits": ("visit_service", "visits", "visit", "collection"),
+}
+
+# ---------------------------------------------------------------------------
+# Column specs for Rich table rendering
+# ---------------------------------------------------------------------------
+
+#: (header, dict_key, style, justify)
+_Col = tuple[str, str, str | None, str | None]
+
+ENTITY_COLUMNS: dict[str, list[_Col]] = {
+    "client": [
+        ("ID", "id", "dim", "right"),
+        ("Name", "name", "cyan", None),
+        ("Type", "client_type", None, None),
+        ("Status", "status", None, None),
+        ("Projects", "project_count", None, "right"),
+        ("Files", "file_count", None, "right"),
+    ],
+    "project": [
+        ("ID", "id", "dim", "right"),
+        ("Name", "name", "cyan", None),
+        ("Type", "type", None, None),
+        ("Client", "client", None, None),
+        ("Status", "status", None, None),
+        ("Files", "file_count", None, "right"),
+        ("Path", "root_path", "dim", None),
+    ],
+    "file": [
+        ("ID", "id", "dim", "right"),
+        ("Name", "name", None, None),
+        ("Source", "source", None, None),
+        ("Status", "status", None, None),
+        ("Project", "project_name", None, None),
+    ],
+    "folder": [
+        ("ID", "id", "dim", "right"),
+        ("Path", "relative_path", None, None),
+        ("Files", "direct_files", None, "right"),
+        ("Size", "total_size_bytes", None, "right"),
+        ("Project", "project_name", "cyan", None),
+    ],
+    "chat": [
+        ("ID", "id", "cyan", "right"),
+        ("Account", "account", "magenta", None),
+        ("Msgs", "message_count", None, "right"),
+        ("Title", "title", None, None),
+    ],
+    "email": [
+        ("ID", "id", "dim", "right"),
+        ("From", "from_address", None, None),
+        ("Subject", "subject", None, None),
+        ("Account", "account", None, None),
+        ("Date", "received_at", None, None),
+    ],
+    "visit": [
+        ("ID", "id", "dim", "right"),
+        ("Title", "title", None, None),
+        ("URL", "url", None, None),
+        ("Browser", "browser", None, None),
+        ("Time", "visit_time", None, None),
+    ],
+}
+
+# ---------------------------------------------------------------------------
+# Service resolution
+# ---------------------------------------------------------------------------
+
+
+def _get_service(service_name: str):
+    """Lazy-import and return a service module from footprinter.services."""
+    import footprinter.services as svc
+
+    return getattr(svc, service_name)
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def _handle_single(args) -> None:
+    """Handle singular noun: ``fp view client 42``."""
+    from footprinter.services.roles import Role
+
+    noun = args.noun
+    svc_name, _list_key, entity_type, _mode = ENTITY_MAP[noun]
+    service = _get_service(svc_name)
+
+    try:
+        entity_id = int(args.id)
+    except ValueError:
+        console.print(f"[red]Invalid ID: {args.id!r} — expected an integer.[/red]")
+        sys.exit(1)
+
+    with open_db() as conn:
+        record = service.get(conn, entity_id, role=Role.ADMIN)
+
+    if record is None:
+        console.print(f"[red]{entity_type.title()} {args.id} not found.[/red]")
+        sys.exit(1)
+
+    if getattr(args, "json", False):
+        output_json(record)
+        return
+
+    # Rich panel — show all key-value pairs
+    lines = []
+    for key, value in record.items():
+        if key.startswith("mcp_") or isinstance(value, (list, dict)):
+            continue
+        display_val = str(value) if value is not None else "—"
+        lines.append(f"[bold]{key}:[/bold] {display_val}")
+
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title=f"{entity_type.title()} #{record['id']}",
+            border_style="cyan",
+        )
+    )
+
+
+def _handle_collection(args) -> None:
+    """Handle plural noun: ``fp view clients``."""
+    from footprinter.services.roles import Role
+
+    noun = args.noun
+    svc_name, list_key, entity_type, _mode = ENTITY_MAP[noun]
+    service = _get_service(svc_name)
+
+    verbose = getattr(args, "verbose", False)
+    limit = getattr(args, "limit", 50)
+    page = getattr(args, "page", 1)
+
+    with open_db() as conn:
+        result = service.list_(conn, role=Role.ADMIN, limit=limit, page=page)
+        rows = result[list_key]
+        if (verbose or getattr(args, "json", False)) and rows:
+            enrich_verbose_access(rows, entity_type)
+
+    if getattr(args, "json", False):
+        output_json(result)
+        return
+
+    if getattr(args, "csv", False):
+        cols = ENTITY_COLUMNS.get(entity_type)
+        col_keys = [c[1] for c in cols] if cols else None
+        output_csv(rows, columns=col_keys)
+        return
+
+    if not rows:
+        console.print(f"[dim]No {list_key} found.[/dim]")
+        return
+
+    # Build Rich table from column specs
+    pag = result["pagination"]
+    table = Table(
+        title=f"{list_key.title()} (page {pag['page']}/{pag['total_pages']}, {pag['total']} total)",
+    )
+
+    cols = ENTITY_COLUMNS.get(entity_type, [])
+    for header, _key, style, justify in cols:
+        kwargs: dict = {}
+        if style:
+            kwargs["style"] = style
+        if justify:
+            kwargs["justify"] = justify
+        table.add_column(header, **kwargs)
+    if verbose:
+        table.add_column("Access")
+        table.add_column("Visibility")
+
+    for row in rows:
+        cells = []
+        for _header, key, _style, _justify in cols:
+            val = row.get(key)
+            if key == "total_size_bytes" and isinstance(val, (int, float)):
+                cells.append(format_size(int(val)))
+            elif key == "file_count" and isinstance(val, int):
+                cells.append(f"{val:,}")
+            else:
+                cells.append(str(val) if val is not None else "")
+        if verbose:
+            cells.extend(verbose_access_cells(row))
+        table.add_row(*cells)
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+SINGULAR_NOUNS = ["client", "project", "file", "folder", "chat", "email", "visit"]
+PLURAL_NOUNS = ["clients", "projects", "files", "folders", "chats", "emails", "visits"]
+
+
+def register(subparsers) -> None:
+    """Register the ``view`` subcommand with noun sub-subparsers."""
+    parser = subparsers.add_parser(
+        "view",
+        help="View entity records",
+        description=(
+            "View entity records — singular noun for one record, plural for a list.\n\n"
+            "Singular:  fp view client 42     Single record by ID\n"
+            "Plural:    fp view clients        Paginated collection\n"
+            "Export:    fp view clients --csv   Bulk CSV export"
+        ),
+        epilog=(
+            "examples:\n"
+            "  fp view client 42               View a single client\n"
+            "  fp view clients                  List all clients\n"
+            "  fp view clients --json           JSON output\n"
+            "  fp view clients --csv            CSV export\n"
+            "  fp view files --limit 10         First 10 files\n"
+            "  fp view projects --verbose       Include access columns\n"
+            "\n"
+            "entity nouns:\n"
+            "  singular: client, project, file, folder, chat, email, visit\n"
+            "  plural:   clients, projects, files, folders, chats, emails, visits\n"
+            "\n"
+            "tip: use 'fp view <noun> --help' for details on any noun."
+        ),
+        formatter_class=FORMATTER,
+    )
+    noun_subs = parser.add_subparsers(
+        dest="noun",
+        metavar="NOUN",
+        title="entity nouns (one required)",
+    )
+    parser.set_defaults(func=lambda args: parser.print_help())
+
+    # Singular nouns — require an ID positional arg
+    for noun in SINGULAR_NOUNS:
+        entity_type = ENTITY_MAP[noun][2]
+        p = noun_subs.add_parser(
+            noun,
+            help=f"View a single {entity_type}",
+            description=f"Show details for a single {entity_type} record by ID.",
+            formatter_class=FORMATTER,
+        )
+        p.add_argument("id", help=f"{entity_type.title()} ID")
+        add_json_flag(p)
+        p.set_defaults(func=_handle_single)
+
+    # Plural nouns — pagination + format flags
+    for noun in PLURAL_NOUNS:
+        entity_type = ENTITY_MAP[noun][2]
+        p = noun_subs.add_parser(
+            noun,
+            help=f"List {noun}",
+            description=f"List {noun} with pagination.",
+            formatter_class=FORMATTER,
+        )
+        p.add_argument(
+            "--limit",
+            type=int,
+            default=50,
+            help="Max rows to return (default: 50)",
+        )
+        p.add_argument(
+            "--page",
+            type=int,
+            default=1,
+            help="Page number (default: 1)",
+        )
+        add_verbose_flag(p)
+
+        # --json and --csv are mutually exclusive
+        fmt_group = p.add_mutually_exclusive_group()
+        add_json_flag(fmt_group)
+        add_csv_flag(fmt_group)
+
+        p.set_defaults(func=_handle_collection)