footprinter-cli 1.0.2__tar.gz → 1.0.4__tar.gz

{footprinter_cli-1.0.2/footprinter_cli.egg-info → footprinter_cli-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: footprinter-cli
-Version: 1.0.2
+Version: 1.0.4
 Summary: A local context layer for your files, browser history, chats, and email — searchable, user-owned, MCP-served.
 Author: SwellCity Group
 License: MIT
@@ -20,6 +20,8 @@ Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Database
 Classifier: Topic :: Text Processing :: Indexing
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
@@ -52,74 +54,59 @@ Requires-Dist: httpx<1.0,>=0.27.0; extra == "dev"
 
 # Footprinter
 
-[![Tests](https://github.com/swellcitygroup/footprinter/actions/workflows/test.yml/badge.svg)](https://github.com/swellcitygroup/footprinter/actions/workflows/test.yml)
+[![Tests](https://github.com/harringjohn/footprinter-cli/actions/workflows/test.yml/badge.svg)](https://github.com/harringjohn/footprinter-cli/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/footprinter-cli)](https://pypi.org/project/footprinter-cli/)
 
 **A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through [MCP](https://modelcontextprotocol.io/).**
 
-Your work lives across a filesystem, a browser, an inbox, a chat history, and whatever other tools you reach for. Footprinter indexes those sources into a single local store, organizes them into the projects and groupings *you* define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.
-
-## Prerequisites
-
-- **Python 3.11 or newer.** Stock macOS ships with Python 3.9, which won't work — install a newer Python from [python.org](https://www.python.org/downloads/) (recommended) or via `brew install python@3.11`.
-- **macOS 13+** or **Linux**.
-- **Full Disk Access on macOS** for browser history indexing. Grant it to your terminal app under *System Settings → Privacy & Security → Full Disk Access*. `fp setup` will guide you through this when needed.
+Your work lives across filesystems, browsers, inboxes, chat histories, and other tools. Footprinter indexes those sources into a single local store, organizes them into the projects and groupings you define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.
 
 ## Install
 
-The fastest path on a clean machine is the install script — it ensures Python 3.11+ is present and installs `footprinter-cli`:
+Requires **Python 3.11+** and **macOS 13+** or **Linux**. The install script checks your Python version and handles the rest:
 
 ```bash
-# Base install (CLI + MCP + HTTP API)
-curl -fsSL https://raw.githubusercontent.com/swellcitygroup/footprinter/main/scripts/release/install.sh | bash
-
-# Full install (adds semantic search + document parsing)
-curl -fsSL https://raw.githubusercontent.com/swellcitygroup/footprinter/main/scripts/release/install-full.sh | bash
+curl -fsSL https://raw.githubusercontent.com/harringjohn/footprinter-cli/main/scripts/release/install.sh | bash
 ```
 
-If you prefer to manage the install yourself, use **pipx** (recommended) — it isolates Footprinter and sidesteps the macOS install caveats noted below:
+Or install with **pipx** directly:
 
 ```bash
-brew install pipx
-pipx ensurepath           # then restart your terminal
 pipx install footprinter-cli
-pipx install 'footprinter-cli[full]'   # with semantic + parse
-```
-
-> **macOS caveats for manual installs:**
-> - **zsh** treats `[...]` as a glob, so keep the single quotes around any bracketed extras specifier (e.g. `'footprinter-cli[full]'`). Without quotes you'll see `zsh: no matches found`.
-> - **System and Homebrew Python** ship with PEP 668 enabled, which blocks bare `pip install` outside a venv. Use pipx (above) instead.
-> - **python.org-distributed Python** doesn't enforce PEP 668, so a bare `pip install footprinter-cli` outside pipx or a venv may succeed but place `fp` in `/Library/Frameworks/Python.framework/Versions/<x.y>/bin`, which isn't on `PATH` by default. Use pipx (above) or the install script.
-
-Inside an existing venv, `pip` works as expected:
-
-```bash
-./venv/bin/pip install footprinter-cli
-./venv/bin/pip install 'footprinter-cli[full]'
 ```
 
-The base install includes the indexing pipeline, CLI, MCP server, HTTP API, and token encryption. Optional extras add more:
+Either method gives you the `fp` command with the indexing pipeline, CLI, MCP server, and HTTP API. Optional extras add more:
 
 | Extra | What it adds |
 |-------|-------------|
 | `[semantic]` | Semantic search via ChromaDB + ONNX embeddings |
 | `[parse]` | PDF, Word, Excel, PowerPoint content extraction |
-| `[full]` | All optional extras (semantic + parse) |
+| `[full]` | Both of the above |
 
-> **Privacy note:** The `[semantic]` extra installs ChromaDB. Footprinter initializes
-> the ChromaDB client with `anonymized_telemetry=False`, so no telemetry is sent
-> regardless of which version pip resolves. ChromaDB also removed product telemetry
-> entirely in version 1.5.4. See
-> [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss) for details.
+To install with extras: use the [full install script](https://raw.githubusercontent.com/harringjohn/footprinter-cli/main/scripts/release/install-full.sh), or `pipx install 'footprinter-cli[full]'`.
 
-### Uninstall
+<details>
+<summary>Troubleshooting & alternative install methods</summary>
+
+**Python version:** Stock macOS ships Python 3.9. Install 3.11+ from [python.org](https://www.python.org/downloads/) or `brew install python@3.11`.
+
+**macOS caveats:**
+- zsh treats `[...]` as a glob — quote extras specifiers: `'footprinter-cli[full]'`
+- System/Homebrew Python blocks bare `pip install` (PEP 668) — use pipx or a venv instead
+
+**Inside an existing venv:** `pip install footprinter-cli` works as expected.
+
+**Full Disk Access:** Required for browser history indexing on macOS. `fp setup` will prompt you when needed.
+
+**ChromaDB telemetry:** Footprinter sets `anonymized_telemetry=False`. ChromaDB also removed product telemetry in v1.5.4. See [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss).
 
-`fp uninstall` cleans up the MCP entry and user data first, then run the appropriate package uninstall:
+</details>
+
+### Uninstall
 
 ```bash
-fp uninstall                                    # remove MCP entry + user data
-pipx uninstall footprinter-cli                  # if you installed via pipx
-./venv/bin/pip uninstall footprinter-cli        # if you installed inside a venv
+fp uninstall                        # remove MCP entry + user data
+pipx uninstall footprinter-cli      # remove the package
 ```
 
 ## Quick Start
@@ -156,13 +143,11 @@ Once configured, Claude can search your files, browse projects, and find related
 | **Local files** | Path, type, size, timestamps, content hash |
 | **Browser history** | Safari and Chrome — URLs, titles, visit times |
 | **Chat exports** | Claude and ChatGPT conversation exports |
-| **Email** | Subject, sender, recipients, body, timestamps — ingested via [connector plugins](#connectors) |
+| **Email** | Subject, sender, recipients, body, timestamps |
 | **Documents** | PDF, Word, Excel, PowerPoint content (with `[parse]` extra) |
 | **Semantic embeddings** | Conceptual similarity across all sources (with `[semantic]` extra) |
 
-What lands in the database — and when — is controlled by the **content storage tier** you opt into. By default, Footprinter only indexes metadata; it does not read your file content until you explicitly enable it. See [Content Storage](https://github.com/swellcitygroup/footprinter/blob/main/reference/content-storage.md) for the full breakdown.
-
-Additional sources are available through [connector plugins](#connectors).
+What lands in the database — and when — is controlled by the **content storage tier** you opt into. By default, Footprinter only indexes metadata; it does not read your file content until you explicitly enable it. See [Content Storage](https://github.com/harringjohn/footprinter-cli/blob/main/reference/content-storage.md) for the full breakdown.
 
 ## CLI Commands
 
@@ -187,48 +172,28 @@ All commands use the `fp` entry point.
 
 Run `fp <command> --help` for full usage.
 
-## Connectors
-
-Connector plugins add external data sources like email, cloud storage, and third-party services. They install alongside Footprinter and register automatically:
-
-```bash
-pip install footprinter-<name>
-```
-
-First-party and community connectors are in development — check the repository for updates.
-
-Use `fp connect list` to see available connectors and their status.
-
 ## Architecture
 
 Single-process CLI with optional MCP server. SQLite database. No containers, no cloud, no accounts.
 
 Sources are scanned into SQLite with bidirectional links connecting local files to remote backups via content hash matching. Embeddings are generated at ingest time for semantic search. The MCP server exposes indexed data with two-layer access control (visibility + permissions) — you decide what agents can see.
 
-## Requirements
-
-- Python 3.11+
-- macOS 13+ or Linux
-- Full Disk Access on macOS (for browser history)
-
 ## Documentation
 
-- [Interfaces](https://github.com/swellcitygroup/footprinter/blob/main/reference/interfaces.md) — CLI commands, MCP tools, Python API
-- [Data Model](https://github.com/swellcitygroup/footprinter/blob/main/reference/data-model.md) — database schema
-- [Pipeline](https://github.com/swellcitygroup/footprinter/blob/main/reference/pipeline.md) — indexing stages and configuration
-- [Content Storage](https://github.com/swellcitygroup/footprinter/blob/main/reference/content-storage.md) — metadata vs. snippet vs. full-content tiers
-- [Access Control](https://github.com/swellcitygroup/footprinter/blob/main/reference/mcp-access-control.md) — MCP security model
+- [Interfaces](https://github.com/harringjohn/footprinter-cli/blob/main/reference/interfaces.md) — CLI commands, MCP tools, Python API
+- [Data Model](https://github.com/harringjohn/footprinter-cli/blob/main/reference/data-model.md) — database schema
+- [Pipeline](https://github.com/harringjohn/footprinter-cli/blob/main/reference/pipeline.md) — indexing stages and configuration
+- [Content Storage](https://github.com/harringjohn/footprinter-cli/blob/main/reference/content-storage.md) — metadata vs. snippet vs. full-content tiers
+- [Access Control](https://github.com/harringjohn/footprinter-cli/blob/main/reference/mcp-access-control.md) — MCP security model
 
 ## Contributing
 
-Bug fixes, documentation, and tests welcome. For new features or architectural changes, [open an issue](https://github.com/swellcitygroup/footprinter/issues) first to discuss the approach.
-
-Connector plugins use an internal API that isn't stable yet — we're not accepting connector contributions at this time.
+Bug fixes, documentation, and tests welcome. For new features or architectural changes, [open an issue](https://github.com/harringjohn/footprinter-cli/issues) first to discuss the approach.
 
 ### Development setup
 
 ```bash
-git clone https://github.com/swellcitygroup/footprinter.git
+git clone https://github.com/harringjohn/footprinter-cli.git
 cd footprinter
 python3 -m venv venv
 ./venv/bin/pip install -e ".[dev]"
@@ -254,7 +219,7 @@ python3 -m venv venv
 4. Run the test suite
 5. Submit a PR targeting `main`
 
-Never commit API keys, tokens, or credentials. Report security vulnerabilities privately — see [SECURITY.md](https://github.com/swellcitygroup/footprinter/blob/main/SECURITY.md).
+Never commit API keys, tokens, or credentials. Report security vulnerabilities privately — see [SECURITY.md](https://github.com/harringjohn/footprinter-cli/blob/main/SECURITY.md).
 
 ### Pull request expectations
 
@@ -265,13 +230,13 @@ Never commit API keys, tokens, or credentials. Report security vulnerabilities p
 
 All PRs are reviewed by the maintainer. Expect reviews within one week. CI must pass before review begins.
 
-No Contributor License Agreement required. By submitting a PR, you agree your contribution is licensed under the project's [MIT License](https://github.com/swellcitygroup/footprinter/blob/main/LICENSE).
+No Contributor License Agreement required. By submitting a PR, you agree your contribution is licensed under the project's [MIT License](https://github.com/harringjohn/footprinter-cli/blob/main/LICENSE).
 
 ## Community
 
-- [Code of Conduct](https://github.com/swellcitygroup/footprinter/blob/main/CODE_OF_CONDUCT.md)
-- [Security Policy](https://github.com/swellcitygroup/footprinter/blob/main/SECURITY.md)
+- [Code of Conduct](https://github.com/harringjohn/footprinter-cli/blob/main/CODE_OF_CONDUCT.md)
+- [Security Policy](https://github.com/harringjohn/footprinter-cli/blob/main/SECURITY.md)
 
 ## License
 
-MIT — see [LICENSE](https://github.com/swellcitygroup/footprinter/blob/main/LICENSE).
+MIT — see [LICENSE](https://github.com/harringjohn/footprinter-cli/blob/main/LICENSE).

footprinter_cli-1.0.4/README.md

@@ -0,0 +1,188 @@
+# Footprinter
+
+[![Tests](https://github.com/harringjohn/footprinter-cli/actions/workflows/test.yml/badge.svg)](https://github.com/harringjohn/footprinter-cli/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/footprinter-cli)](https://pypi.org/project/footprinter-cli/)
+
+**A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through [MCP](https://modelcontextprotocol.io/).**
+
+Your work lives across filesystems, browsers, inboxes, chat histories, and other tools. Footprinter indexes those sources into a single local store, organizes them into the projects and groupings you define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.
+
+## Install
+
+Requires **Python 3.11+** and **macOS 13+** or **Linux**. The install script checks your Python version and handles the rest:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/harringjohn/footprinter-cli/main/scripts/release/install.sh | bash
+```
+
+Or install with **pipx** directly:
+
+```bash
+pipx install footprinter-cli
+```
+
+Either method gives you the `fp` command with the indexing pipeline, CLI, MCP server, and HTTP API. Optional extras add more:
+
+| Extra | What it adds |
+|-------|-------------|
+| `[semantic]` | Semantic search via ChromaDB + ONNX embeddings |
+| `[parse]` | PDF, Word, Excel, PowerPoint content extraction |
+| `[full]` | Both of the above |
+
+To install with extras: use the [full install script](https://raw.githubusercontent.com/harringjohn/footprinter-cli/main/scripts/release/install-full.sh), or `pipx install 'footprinter-cli[full]'`.
+
+<details>
+<summary>Troubleshooting & alternative install methods</summary>
+
+**Python version:** Stock macOS ships Python 3.9. Install 3.11+ from [python.org](https://www.python.org/downloads/) or `brew install python@3.11`.
+
+**macOS caveats:**
+- zsh treats `[...]` as a glob — quote extras specifiers: `'footprinter-cli[full]'`
+- System/Homebrew Python blocks bare `pip install` (PEP 668) — use pipx or a venv instead
+
+**Inside an existing venv:** `pip install footprinter-cli` works as expected.
+
+**Full Disk Access:** Required for browser history indexing on macOS. `fp setup` will prompt you when needed.
+
+**ChromaDB telemetry:** Footprinter sets `anonymized_telemetry=False`. ChromaDB also removed product telemetry in v1.5.4. See [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss).
+
+</details>
+
+### Uninstall
+
+```bash
+fp uninstall                        # remove MCP entry + user data
+pipx uninstall footprinter-cli      # remove the package
+```
+
+## Quick Start
+
+```bash
+fp setup     # Configure sources (interactive wizard)
+fp ingest    # Index your files
+fp status    # See what's indexed
+fp search "meeting notes"   # Find things
+```
+
+A few first-run notes:
+
+- The first ingest is implicitly full; subsequent runs are incremental. If you change exclusions or add directories after the first run, re-run with `fp ingest --full` so previously skipped files get picked up.
+- With `[semantic]` or `[full]`, the **first ingest downloads ~80MB** of ONNX embedding model weights. It's a one-time cost — subsequent ingests are fast.
+- Keep the directories you want indexed **outside `~/Downloads`** — the default exclusion list skips it.
+
+## Connect to Claude Desktop
+
+Footprinter includes an MCP server that gives Claude Desktop (or any MCP client) structured access to your indexed data:
+
+```bash
+fp setup mcp --claude    # Configure MCP for Claude Desktop
+```
+
+After running this, **fully quit Claude Desktop (Cmd+Q) and relaunch** before the Footprinter tools appear in the conversation tools list. A simple window close isn't enough — the app keeps running in the menu bar.
+
+Once configured, Claude can search your files, browse projects, and find related conversations — through natural language.
+
+## What It Indexes
+
+| Source | What's captured |
+|--------|----------------|
+| **Local files** | Path, type, size, timestamps, content hash |
+| **Browser history** | Safari and Chrome — URLs, titles, visit times |
+| **Chat exports** | Claude and ChatGPT conversation exports |
+| **Email** | Subject, sender, recipients, body, timestamps |
+| **Documents** | PDF, Word, Excel, PowerPoint content (with `[parse]` extra) |
+| **Semantic embeddings** | Conceptual similarity across all sources (with `[semantic]` extra) |
+
+What lands in the database — and when — is controlled by the **content storage tier** you opt into. By default, Footprinter only indexes metadata; it does not read your file content until you explicitly enable it. See [Content Storage](https://github.com/harringjohn/footprinter-cli/blob/main/reference/content-storage.md) for the full breakdown.
+
+## CLI Commands
+
+All commands use the `fp` entry point.
+
+| Command | Purpose |
+|---------|---------|
+| `fp setup` | Configure sources and integrations |
+| `fp ingest` | Run the indexing pipeline |
+| `fp status` | System health and data counts |
+| `fp search` | Search across all indexed sources |
+| `fp connect` | Manage optional integrations |
+| `fp mcp` | MCP server and access policies |
+| `fp api` | Start the HTTP API server |
+| `fp view` | Browse indexed data (files, folders, projects, clients, chats, emails, visits) |
+| `fp upsert` | Create/update records, assign relationships, or soft-delete via `--status removed` |
+| `fp data` | Export data, generate templates, or import metadata corrections |
+| `fp delete` | Hard-delete a super entity (irreversible) |
+| `fp vectorize` | Manage per-record vectorization control |
+| `fp doctor` | Post-install health check (Python version, install location, FDA, MCP wiring) |
+| `fp uninstall` | Remove Footprinter — MCP entry, user data, package |
+
+Run `fp <command> --help` for full usage.
+
+## Architecture
+
+Single-process CLI with optional MCP server. SQLite database. No containers, no cloud, no accounts.
+
+Sources are scanned into SQLite with bidirectional links connecting local files to remote backups via content hash matching. Embeddings are generated at ingest time for semantic search. The MCP server exposes indexed data with two-layer access control (visibility + permissions) — you decide what agents can see.
+
+## Documentation
+
+- [Interfaces](https://github.com/harringjohn/footprinter-cli/blob/main/reference/interfaces.md) — CLI commands, MCP tools, Python API
+- [Data Model](https://github.com/harringjohn/footprinter-cli/blob/main/reference/data-model.md) — database schema
+- [Pipeline](https://github.com/harringjohn/footprinter-cli/blob/main/reference/pipeline.md) — indexing stages and configuration
+- [Content Storage](https://github.com/harringjohn/footprinter-cli/blob/main/reference/content-storage.md) — metadata vs. snippet vs. full-content tiers
+- [Access Control](https://github.com/harringjohn/footprinter-cli/blob/main/reference/mcp-access-control.md) — MCP security model
+
+## Contributing
+
+Bug fixes, documentation, and tests welcome. For new features or architectural changes, [open an issue](https://github.com/harringjohn/footprinter-cli/issues) first to discuss the approach.
+
+### Development setup
+
+```bash
+git clone https://github.com/harringjohn/footprinter-cli.git
+cd footprinter
+python3 -m venv venv
+./venv/bin/pip install -e ".[dev]"
+```
+
+### Running tests
+
+```bash
+./venv/bin/pytest tests/ -v --tb=short
+```
+
+### Code style
+
+- PEP 8
+- Type hints on function signatures
+- `logging` over `print()` in library code
+
+### Workflow
+
+1. Fork the repository
+2. Create a feature branch from `main`
+3. Write tests (TDD preferred — tests before implementation)
+4. Run the test suite
+5. Submit a PR targeting `main`
+
+Never commit API keys, tokens, or credentials. Report security vulnerabilities privately — see [SECURITY.md](https://github.com/harringjohn/footprinter-cli/blob/main/SECURITY.md).
+
+### Pull request expectations
+
+- Tests must pass
+- No breaking changes to existing CLI commands
+- Fill out the PR template
+- One logical change per PR
+
+All PRs are reviewed by the maintainer. Expect reviews within one week. CI must pass before review begins.
+
+No Contributor License Agreement required. By submitting a PR, you agree your contribution is licensed under the project's [MIT License](https://github.com/harringjohn/footprinter-cli/blob/main/LICENSE).
+
+## Community
+
+- [Code of Conduct](https://github.com/harringjohn/footprinter-cli/blob/main/CODE_OF_CONDUCT.md)
+- [Security Policy](https://github.com/harringjohn/footprinter-cli/blob/main/SECURITY.md)
+
+## License
+
+MIT — see [LICENSE](https://github.com/harringjohn/footprinter-cli/blob/main/LICENSE).

footprinter_cli-1.0.2/footprinter/access.py → footprinter_cli-1.0.4/footprinter/access_stamper.py

@@ -12,6 +12,7 @@ import sqlite3
 from collections.abc import Callable
 from typing import Any
 
+from footprinter.db.policies import is_folder_path_scope
 from footprinter.permissions import batch_resolve_permissions
 from footprinter.visibility import batch_resolve_visibility
 
@@ -113,10 +114,21 @@ ENTITY_META: dict[str, dict[str, Any]] = {
         "has_account": False,
         "path_column": None,
     },
+    "visit": {
+        "table": "visits",
+        "has_visibility": True,
+        "has_permissions": True,
+        "has_status": False,
+        "has_project_id": False,
+        "has_client_id": False,
+        "has_account": False,
+        "path_column": None,
+    },
 }
 
 # Reverse map: source scope suffix → entity type (e.g. "files" → "file")
 _SOURCE_TO_ENTITY = {meta["table"]: etype for etype, meta in ENTITY_META.items()}
+_SOURCE_TO_ENTITY["browser"] = "visit"
 
 
 # ---------------------------------------------------------------------------
@@ -170,28 +182,58 @@ def _get_ids_for_scope(conn: sqlite3.Connection, scope: str) -> dict[str, list[i
         return result
 
     if prefix == "folder":
-        # folder:{path} → files/folders with matching path prefix
-        path = os.path.expanduser(value)
-        # Escape LIKE metacharacters so literal %, _ in paths match correctly
-        escaped = path.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-        result = {}
-        for etype in ENTITY_META:
-            meta = ENTITY_META[etype]
-            path_col = meta["path_column"]
-            if path_col is None:
-                continue
-            table = meta["table"]
-            where = f"{path_col} LIKE ? ESCAPE '\\'"
-            if meta["has_status"]:
-                where += " AND status = 'listed'"
-            rows = conn.execute(
-                f"SELECT id FROM {table} WHERE {where}",
-                (escaped + "%",),
+        if is_folder_path_scope(scope):
+            # folder:{path} → files/folders with matching path prefix
+            path = os.path.expanduser(value)
+            # Escape LIKE metacharacters so literal %, _ in paths match correctly
+            escaped = path.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+            result = {}
+            for etype in ENTITY_META:
+                meta = ENTITY_META[etype]
+                path_col = meta["path_column"]
+                if path_col is None:
+                    continue
+                table = meta["table"]
+                where = f"{path_col} LIKE ? ESCAPE '\\'"
+                if meta["has_status"]:
+                    where += " AND status = 'listed'"
+                rows = conn.execute(
+                    f"SELECT id FROM {table} WHERE {where}",
+                    (escaped + "%",),
+                ).fetchall()
+                ids = [r["id"] for r in rows]
+                if ids:
+                    result[etype] = ids
+            return result
+        else:
+            # folder:{id} → folder + all descendants via parent_folder_id
+            folder_id = int(value)
+            descendants_cte = """
+                WITH RECURSIVE descendants(id) AS (
+                    SELECT id FROM folders WHERE id = ?
+                    UNION ALL
+                    SELECT folder.id FROM folders folder
+                    JOIN descendants descendant ON folder.parent_folder_id = descendant.id
+                )
+            """
+            cursor = conn.cursor()
+            cursor.execute(
+                f"{descendants_cte} SELECT id FROM descendants",
+                (folder_id,),
+            )
+            desc_ids = [row["id"] for row in cursor.fetchall()]
+            if not desc_ids:
+                return {}
+            result: dict[str, list[int]] = {"folder": desc_ids}
+            ph = ",".join("?" * len(desc_ids))
+            file_rows = conn.execute(
+                f"SELECT id FROM files WHERE folder_id IN ({ph}) AND status = 'listed'",
+                tuple(desc_ids),
             ).fetchall()
-            ids = [r["id"] for r in rows]
-            if ids:
-                result[etype] = ids
-        return result
+            file_ids = [r["id"] for r in file_rows]
+            if file_ids:
+                result["file"] = file_ids
+            return result
 
     if prefix == "project":
         project_id = int(value)

footprinter_cli-1.0.4/footprinter/api/db.py

@@ -0,0 +1,38 @@
+"""Database connection for Footprinter HTTP API."""
+
+import sqlite3
+from contextlib import contextmanager
+from typing import Generator
+
+from footprinter.db_base import open_checked_connection
+
+
+@contextmanager
+def get_db() -> Generator[sqlite3.Connection, None, None]:
+    """Context manager for database connections.
+
+    Divergences from MCP's ``get_db()``:
+
+    - No ``PRAGMA query_only`` — the HTTP API uses Role.ADMIN and may need
+      write access for future endpoints.
+    - No ``handle_db_errors`` decorator — ``DatabaseNotInitializedError`` is
+      caught by a FastAPI exception handler registered in ``server.create_app()``.
+
+    Calls ``load_globals()`` to refresh the global visibility/permission
+    policy cache in ``access_service`` for the current request.
+    """
+    with open_checked_connection() as conn:
+        yield conn
+
+
+def get_conn():
+    """FastAPI dependency that yields a database connection.
+
+    Usage::
+
+        @router.get("/endpoint")
+        def handler(conn=Depends(get_conn)):
+            ...
+    """
+    with get_db() as conn:
+        yield conn

{footprinter_cli-1.0.2 → footprinter_cli-1.0.4}/footprinter/api/server.py

@@ -3,7 +3,7 @@
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 
-from footprinter.api.db import DatabaseNotInitializedError
+from footprinter.utils.exceptions import DatabaseNotInitializedError
 
 
 def create_app() -> "FastAPI":

{footprinter_cli-1.0.2 → footprinter_cli-1.0.4}/footprinter/bundled/config.example.yaml

@@ -78,9 +78,12 @@ exclusions:
 # Indexing configuration - INDEX ALL FILE TYPES
 indexing:
   supported_extensions: []  # Empty = index ALL file types
-  max_file_size_mb: 0       # 0 = no size limit (index everything)
+  max_file_size_mb: 50      # MB; 0 = no size limit. 50 is generous for prose/docs.
   lookback_days: 14         # Browser history window (days back to index)
   content_snippets: false   # Extract file/email content previews for keyword search
+  # `fp ingest --preview` (FPR-1723) — pre-scan summary tuning
+  preview_top_n: 10                # rows shown for top files / top directories
+  preview_size_threshold_mb: 50    # files at or above this size are flagged as outliers
 
 # Semantic search — stores content as embeddings in a local ChromaDB database
 # Enables finding files and chats by meaning, not just keywords
@@ -104,13 +107,18 @@ vectorization:
     - .txt
     - .pdf
     - .docx
+  # Maximum file size (MB) eligible for vectorization. Applies even when
+  # indexing.max_file_size_mb is 0 (no limit). Chunking a multi-GB file
+  # produces millions of chunks and can OOM the host — this guardrail is
+  # always on. Skipped files appear in the post-ingest summary.
+  max_vectorize_size_mb: 100
   # Chunk size in characters — tuned for MiniLM-L6-v2 (256-token input window).
   # ~1000 chars ≈ 250 tokens. Larger chunks get silently truncated by the model,
   # meaning content past the window is invisible to semantic search.
   chunk_size: 1000
-  # Overlap between consecutive chunks (fraction of chunk_size, 0.0 to 1.0).
-  # Applies to file vectorization only. Chat message chunking uses a fixed
-  # character overlap defined in footprinter/semantic/chunking.py.
+  # Fractional overlap between consecutive chunks (0.0–1.0).
+  # 0.15 = 15% of chunk_size chars shared between adjacent chunks.
+  # Legacy integer values (>= 1) are accepted but deprecated.
   chunk_overlap: 0.15
   # Patterns (fnmatch syntax) for file paths to skip during vectorization.
   # Matched against the full absolute path (e.g. ~/Work/file.json expands at runtime).

{footprinter_cli-1.0.2 → footprinter_cli-1.0.4}/footprinter/cli/__init__.py

@@ -29,10 +29,9 @@ def main(argv=None) -> None:
 
     if argv is None:
         argv = _sys.argv[1:]
-    from footprinter.source_registry import ConfigError as _ConfigError
-
     from footprinter import __version__
     from footprinter.cli._common import FORMATTER
+    from footprinter.source_registry import ConfigError as _ConfigError
 
     parser = argparse.ArgumentParser(
         prog="fp",
@@ -89,12 +88,12 @@ def main(argv=None) -> None:
         doctor,
         ingest,
         mcp_cmd,
-        search_cmd,
+        search,
         setup,
-        status_cmd,
+        status,
         uninstall,
         upsert,
-        vectorize_cmd,
+        vectorize,
         view,
     )
 
@@ -102,15 +101,15 @@ def main(argv=None) -> None:
         ingest,
         mcp_cmd,
         api_cmd,
-        status_cmd,
-        search_cmd,
+        status,
+        search,
         setup,
         connect,
         view,
         upsert,
         data,
         delete,
-        vectorize_cmd,
+        vectorize,
         uninstall,
         doctor,
     ]: