fndr 0.0.1__tar.gz

fndr-0.0.1/.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: ["https://buymeacoffee.com/ben.dev.au"]

fndr-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pytest (full suite, serial)
+    # macOS so the path resolution (platformdirs uses
+    # ``~/Library/Application Support/fnd`` here) matches what users
+    # actually run. Free tier on public repos; private repos use the
+    # 10x multiplier so keep an eye on the minutes budget while the
+    # repo is still private.
+    runs-on: macos-14
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Sync deps (frozen lockfile)
+        run: uv sync --frozen
+      - name: Test
+        # Serial, no --testmon. CI is the gold-standard catch-all
+        # behind the local pre-commit hook, which uses --testmon for
+        # speed and may skip tests the developer's diff doesn't reach.
+        run: uv run pytest -q -m "not slow"
+
+  format:
+    name: ruff-format
+    # Format check is a separate small job so a formatting miss is
+    # obvious in the PR check list without re-running the slow tests.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install 3.13
+      - run: uv sync --frozen --group dev
+      - name: Ruff format (check only)
+        run: uv run ruff format --check .
+
+  typecheck:
+    name: pyright (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install 3.13
+      - run: uv sync --frozen
+      - name: Pyright
+        run: uv run pyright

fndr-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,210 @@
+name: release
+
+# Triggered on any `v*` tag. Builds sdist + wheel, emits SBOM and a
+# SLSA-style build-provenance attestation, publishes to PyPI via a
+# Trusted Publisher (OIDC — no API token in repo secrets), and opens
+# a bump-PR against the Homebrew tap with the new sdist SHA-256.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # `id-token: write` lets the build job mint an OIDC token for
+      # the attestation step (and later for PyPI Trusted Publisher).
+      id-token: write
+      # `attestations: write` lets actions/attest-build-provenance
+      # record the SLSA-style provenance for the artifacts we produce.
+      attestations: write
+    outputs:
+      sdist-name: ${{ steps.meta.outputs.sdist }}
+      sdist-sha256: ${{ steps.meta.outputs.sha256 }}
+      version: ${{ steps.meta.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Guard — release tag matches pyproject version
+        # Fail fast (before build/publish) if the `vX.Y.Z` tag and the
+        # declared version have drifted. pyproject is the single source;
+        # this just stops a mismatched tag from shipping.
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          ver=$(python3 -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          [ "$tag" = "$ver" ] || { echo "::error::tag v$tag != pyproject version $ver — bump pyproject.toml before tagging"; exit 1; }
+          echo "tag and pyproject version agree: $ver"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - run: uv python install 3.13
+
+      - name: Build sdist + wheel
+        run: uv build --sdist --wheel --out-dir dist
+
+      - name: Generate CycloneDX SBOM (S2)
+        # SBOM lives outside dist/ so the PyPI publish step (which
+        # uploads the whole packages-dir via twine) doesn't try to
+        # upload a JSON file as a distribution and fail.
+        run: |
+          mkdir -p sbom
+          uv tool install cyclonedx-bom
+          uv export --format requirements-txt --no-hashes -o requirements.frozen.txt
+          uv tool run cyclonedx-py requirements requirements.frozen.txt \
+            --output-format JSON \
+            --output-file sbom/sbom.cdx.json
+
+      - name: Attest build provenance (S2)
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: |
+            dist/*.tar.gz
+            dist/*.whl
+
+      - name: Compute sdist metadata
+        id: meta
+        run: |
+          set -euo pipefail
+          sdist=$(ls dist/*.tar.gz | head -n1)
+          sha=$(shasum -a 256 "$sdist" | awk '{print $1}')
+          # PEP 625 sdist name is `{name}-{version}.tar.gz` and the name
+          # part carries no `-` (normalised to `_`), so the first `-`
+          # splits name from version — name-agnostic (fndr, fnd_x, …).
+          base=$(basename "$sdist" .tar.gz)
+          ver="${base#*-}"
+          echo "sdist=$(basename "$sdist")" >> "$GITHUB_OUTPUT"
+          echo "sha256=$sha" >> "$GITHUB_OUTPUT"
+          echo "version=$ver" >> "$GITHUB_OUTPUT"
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload SBOM artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: sbom/
+
+  publish-pypi:
+    name: publish to PyPI (Trusted Publisher)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish (OIDC, no token)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Configure the Trusted Publisher at
+          # https://pypi.org/manage/account/publishing/ pointing at
+          # this repo + `release.yml` workflow + `pypi` environment.
+          packages-dir: dist
+          skip-existing: true
+
+  release-notes:
+    name: publish GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Download SBOM
+        uses: actions/download-artifact@v4
+        with:
+          name: sbom
+          path: sbom/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF##*/}"
+          # Attach sdist, wheel, and SBOM; the provenance attestation
+          # is fetched separately via `gh attestation verify` and is
+          # not uploaded as a release asset (GitHub stores it).
+          gh release create "$tag" \
+            --title "fnd $tag" \
+            --notes "See CHANGELOG / commit log for details. SHA-256: ${{ needs.build.outputs.sdist-sha256 }}" \
+            dist/*.tar.gz dist/*.whl sbom/sbom.cdx.json
+
+  bump-homebrew-tap:
+    name: bump homebrew-tap formula
+    # Needs publish-pypi so the sdist exists when we resolve its URL.
+    needs: [build, publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Open formula bump PR
+        env:
+          # HOMEBREW_TAP_PAT: fine-scoped PAT with PR-write to the tap
+          # (the default GITHUB_TOKEN can't push cross-repo). Both live
+          # on THIS repo, not the tap — the workflow runs here.
+          # HOMEBREW_TAP_REPO = ben-dev-au/homebrew-tap.
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_PAT }}
+          TAP_REPO: ${{ vars.HOMEBREW_TAP_REPO }}
+          VERSION: ${{ needs.build.outputs.version }}
+        if: ${{ vars.HOMEBREW_TAP_REPO != '' }}
+        run: |
+          set -euo pipefail
+          # Resolve url + sha256 from PyPI's JSON API — one source of
+          # truth, immune to name normalisation and the hashed storage
+          # path. The index can lag the publish by a few seconds, so retry.
+          meta=""
+          for i in 1 2 3 4 5 6; do
+            meta=$(curl -fsSL "https://pypi.org/pypi/fndr/${VERSION}/json" \
+              | python3 -c "import sys,json;u=next(x for x in json.load(sys.stdin)['urls'] if x['packagetype']=='sdist');print(u['url']);print(u['digests']['sha256'])") \
+              && [ -n "$meta" ] && break
+            echo "PyPI JSON not ready (attempt $i); retrying…" >&2
+            sleep 10
+          done
+          [ -n "$meta" ] || { echo "could not resolve sdist for fndr $VERSION" >&2; exit 1; }
+          new_url=$(printf '%s\n' "$meta" | sed -n 1p)
+          new_sha=$(printf '%s\n' "$meta" | sed -n 2p)
+
+          tmp=$(mktemp -d)
+          git clone "https://x-access-token:$GH_TOKEN@github.com/$TAP_REPO.git" "$tmp/tap"
+          cd "$tmp/tap"
+          formula=Formula/fnd.rb
+          sed -i.bak "s|^  url \".*\"|  url \"$new_url\"|" "$formula"
+          sed -i.bak "s|^  sha256 \".*\"|  sha256 \"$new_sha\"|" "$formula"
+          rm -f "$formula.bak"
+          branch="bump/fnd-$VERSION"
+          git checkout -b "$branch"
+          git add "$formula"
+          git -c user.email="actions@github.com" -c user.name="fnd-release-bot" \
+            commit -m "fnd $VERSION"
+          git push -u origin "$branch"
+          gh pr create \
+            --title "fnd $VERSION" \
+            --body "Automated bump from ben-dev-au/fnd@${GITHUB_REF##*/}. sha256 \`$new_sha\`."

fndr-0.0.1/.github/workflows/security.yml

@@ -0,0 +1,73 @@
+name: security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly Monday 09:00 UTC — catches CVEs published since the last
+    # human-driven push.
+    - cron: "0 9 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  pip-audit:
+    name: pip-audit (lockfile)
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+      - name: Sync deps (frozen lockfile)
+        run: uv sync --frozen --all-extras --group dev
+      - name: Install pip-audit
+        run: uv tool install pip-audit
+      - name: Export resolved requirements
+        # `--no-emit-project` drops the local `fnd` package (which uv
+        # emits as `-e .`); pip-audit can't look up an unpublished
+        # editable install and would fail the whole audit. Once Phase
+        # 0 of the publish runbook lands `fnd` on PyPI, the flag stays
+        # — we don't need to audit ourselves, only our deps.
+        run: |
+          uv export \
+            --format requirements-txt \
+            --no-hashes \
+            --no-emit-project \
+            -o requirements.frozen.txt
+      - name: Audit
+        run: uv tool run pip-audit -r requirements.frozen.txt --strict
+
+  ruff-security:
+    name: ruff (bandit ruleset)
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install 3.13
+      - run: uv sync --frozen --group dev
+      - name: Ruff (project config includes select=S)
+        run: uv run ruff check .
+
+  gitleaks:
+    name: gitleaks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # gitleaks-action posts a PR-summary comment on findings; without
+      # `pull-requests: write` the action fails with
+      # `Resource not accessible by integration`.
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fndr-0.0.1/.gitignore

@@ -0,0 +1,30 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.coverage
+htmlcov/
+# pytest-testmon per-developer test-impact cache
+.testmondata
+.testmondata-journal
+.testmondata-shm
+.testmondata-wal
+.vscode/
+.idea/
+tests/fixtures/.cache/
+# Index data is never committed (lives in user's Library on macOS)
+index/
+# Per-user Claude Code config / scheduled-task state
+.claude/
+# Per-user operational notes (release runbooks, account setup) and
+# all developer-only tooling. Lives in a separate private repo at
+# dev/. Not part of the public repo.
+private_dev_docs/
+dev/

fndr-0.0.1/.gitleaksignore

@@ -0,0 +1,6 @@
+# False positive: `key = "corruptkey--v1"` is a literal cache-key
+# fixture for the corrupt-JSON test. Renamed in a later commit on
+# this branch, but the historical commit still trips the
+# generic-api-key heuristic because gitleaks scans the full commit
+# range, not just HEAD.
+ac26e70dc720c7a3b44a5a09497a395814514b4f:tests/test_extraction_cache.py:generic-api-key:84

fndr-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: ["--maxkb=2000"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Keep in sync with the ruff pin in pyproject.toml dev deps; CI runs
+    # `uv run ruff format --check .` so drift here will reformat files
+    # locally that CI then rejects.
+    rev: v0.15.14
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright (strict)
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest-fast
+        name: "pytest (testmon: only tests whose code paths changed)"
+        # --testmon caches per-test code dependencies in
+        # ``.testmondata`` (gitignored). First run pays the full suite
+        # cost while the baseline is built; subsequent commits only
+        # re-run tests whose tracked files changed in the diff. CI
+        # runs the full serial suite without --testmon as the
+        # gold-standard catch-all.
+        entry: uv run pytest -q -m "not slow" --testmon
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: harness-indexing
+        name: "harness: indexer status lines (synthetic, fast)"
+        # Pre-push only - runs the synthetic indexer harness when
+        # touching code that controls how PDFs reach the index.
+        # Catches cascading worker death and counter regressions
+        # without paying the cost on every commit. Real-corpus
+        # validation lives behind FND_AUDIT_REAL_CORPUS=1 and is
+        # opt-in via `pre-commit run --hook-stage manual`.
+        stages: [pre-push]
+        entry: uv run python dev/tools/workflow_audit_tmux.py indexer_status_lines indexer_status_lines_md_only
+        language: system
+        files: ^(fnd/extract/|fnd/index|fnd/walk\.py|fnd/tui/indexer_modal\.py|dev/tools/workflow_audit_tmux\.py)
+        pass_filenames: false

fndr-0.0.1/.python-version

@@ -0,0 +1 @@
+3.13

fndr-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to fnd
+
+Thanks for your interest. fnd is a macOS-only document-search CLI/TUI; it's
+early but actively developed. Bug reports, app-catalogue entries, and focused
+PRs are all welcome.
+
+## Development setup
+
+Requires macOS, Python 3.13, and [uv](https://docs.astral.sh/uv/).
+
+```sh
+git clone https://github.com/ben-dev-au/fnd.git
+cd fnd
+make sync          # uv sync --all-extras --group dev
+make install-hooks # pre-commit hooks (ruff + pyright)
+```
+
+Run fnd from the checkout with `uv run python -m fnd <command>`.
+
+## Before opening a PR
+
+```sh
+make test   # full pytest suite
+make lint   # ruff + pyright (strict)
+make fmt    # auto-format and apply safe fixes
+```
+
+CI runs the same checks on macOS. Keep PRs scoped to one change; match the
+surrounding code's style and comment density.
+
+## Adding an app to the "Open with…" catalogue
+
+Third-party app integrations live in [`docs/apps.md`](docs/apps.md). To
+contribute one, add your `[apps.<id>]` config block to the catalogue; see that
+page for the schema and safety rules.
+
+## Security
+
+Please **do not** open public issues for security-sensitive findings. See
+[`SECURITY.md`](SECURITY.md) for private reporting and the threat model.

fndr-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Davidson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fndr-0.0.1/Makefile

@@ -0,0 +1,27 @@
+.PHONY: sync test lint fmt tui snapshot install-hooks
+
+sync:
+	uv sync --all-extras --group dev
+
+test:
+	uv run pytest -q
+
+test-fast:
+	uv run pytest -q -m "not slow"
+
+lint:
+	uv run ruff check .
+	uv run pyright
+
+fmt:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+tui:
+	uv run textual run --dev fnd.tui.app:FNDApp
+
+snapshot:
+	uv run pytest --snapshot-update
+
+install-hooks:
+	uv run pre-commit install