bppicker 0.2.3__tar.gz → 0.2.4__tar.gz

{bppicker-0.2.3 → bppicker-0.2.4}/CHANGELOG.md

@@ -6,6 +6,33 @@ this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.4] — 2026-11-14
+
+### Fixed
+- **The Mac app starts again on Macs where its server took longer than
+  30 seconds** ("Server failed to start"). The server used to unpack
+  itself, about 1 GB, into a temporary folder on every launch, and macOS
+  checked those new files each time. It now ships ready to run inside
+  the app, so a start takes about a second; the first start after an
+  install or update takes longer while macOS checks the new files. The
+  app now waits up to two minutes and says when a first start takes a
+  while.
+- **The server no longer waits on a network name lookup before it opens
+  its port.** On macOS that lookup could hold the start for about 35
+  seconds.
+- **Try Again on the "failed to start" screen starts over cleanly.** It
+  used to leave the previous server running, so the new one collided
+  with it.
+- **Quitting the Mac app stops its server.** Quitting with ⌘Q, the app
+  menu or the Dock left the server running in the background until the
+  next launch.
+
+### Added
+- `bpp selfcheck` loads the native libraries the desktop app bundles and
+  reports any that is missing or won't load. The Mac app's release check
+  runs it in the signed app, along with a check that the server starts
+  quickly.
+
 ## [0.2.3] — 2026-11-03
 
 ### Added
@@ -618,7 +645,8 @@ External calls are limited to documented features:
   desktop wrapper currently builds only the macOS bundle.
 - Python 3.11 only (CI tests this version; 3.12+ is unvalidated).
 
-[Unreleased]: https://github.com/Arkalogy/best-photo-picker/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/Arkalogy/best-photo-picker/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.4
 [0.2.3]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.3
 [0.2.2]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.2
 [0.2.1]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.1

{bppicker-0.2.3 → bppicker-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bppicker
-Version: 0.2.3
+Version: 0.2.4
 Summary: Local-first photo curation tool — score, deduplicate, and select the best photos from large collections
 Project-URL: Homepage, https://github.com/Arkalogy/best-photo-picker
 Project-URL: Repository, https://github.com/Arkalogy/best-photo-picker
@@ -65,7 +65,7 @@ Description-Content-Type: text/markdown
 
 # Best Photo Picker
 
-[![CI](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml/badge.svg)](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml)
+[![CI](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml)
 [![PyPI version](https://img.shields.io/pypi/v/bppicker.svg)](https://pypi.org/project/bppicker/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Arkalogy/best-photo-picker/blob/main/LICENSE)
 [![Python 3.11](https://img.shields.io/badge/python-3.11-green.svg)](https://www.python.org/downloads/)
@@ -537,6 +537,10 @@ bpp model {list|accept|accept-attribution|accepted|use-context|byom|remove|regis
                    `accept-attribution` accepts every built-in
                    Apache 2.0 / BSD-style model in one step.
 bpp db restore-backup --library PATH [--previous] [--yes] [--accept-stale] [--force]
+bpp selfcheck [--require-all]
+                 — loads the native libraries the desktop app bundles
+                   (opens no photo library) and names any that is missing
+                   or won't load. The optional dlib backend isn't checked.
 
 Global: --extensions STR (default: every supported photo, camera RAW and video format)
 ```
@@ -656,7 +660,7 @@ cd desktop && npm run dev
 For a standalone `.app` bundle (launchable from Finder/Spotlight):
 
 ```bash
-# Build sidecar (PyInstaller-bundled Python server)
+# Build the server (PyInstaller-bundled Python server, as a helper app)
 cd desktop && ./build-sidecar.sh
 
 # Build .app + .dmg
@@ -664,7 +668,7 @@ npm run build
 # Output: desktop/src-tauri/target/release/bundle/
 ```
 
-The sidecar binary lands at `desktop/src-tauri/binaries/bpp-server-{target-triple}` (e.g., `bpp-server-aarch64-apple-darwin`).
+The server lands at `desktop/src-tauri/helpers/bpp-server.app`, and the app carries it in `Contents/Helpers/`. `desktop/bpp-server.spec` is the PyInstaller build (layout, hidden imports, signing).
 
 > **Note:** A build you make yourself isn't signed with an Apple Developer ID, so Gatekeeper will block it the first time. To open it: right-click → Open → Open (once). The release DMG and the app inside are signed with a Developer ID and notarized by Apple, so they open normally.
 
@@ -701,7 +705,7 @@ bpp/
     templates/index.html    # Single-page HTML shell
 desktop/
   src-tauri/                # Tauri v2 Rust app
-  build-sidecar.sh          # PyInstaller sidecar build
+  build-sidecar.sh          # builds the server helper app (bpp-server.spec)
   scripts/dev-macos.sh      # Dev launcher
 ```
 

{bppicker-0.2.3 → bppicker-0.2.4}/README.md

@@ -1,6 +1,6 @@
 # Best Photo Picker
 
-[![CI](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml/badge.svg)](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml)
+[![CI](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Arkalogy/best-photo-picker/actions/workflows/ci.yml)
 [![PyPI version](https://img.shields.io/pypi/v/bppicker.svg)](https://pypi.org/project/bppicker/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Arkalogy/best-photo-picker/blob/main/LICENSE)
 [![Python 3.11](https://img.shields.io/badge/python-3.11-green.svg)](https://www.python.org/downloads/)
@@ -472,6 +472,10 @@ bpp model {list|accept|accept-attribution|accepted|use-context|byom|remove|regis
                    `accept-attribution` accepts every built-in
                    Apache 2.0 / BSD-style model in one step.
 bpp db restore-backup --library PATH [--previous] [--yes] [--accept-stale] [--force]
+bpp selfcheck [--require-all]
+                 — loads the native libraries the desktop app bundles
+                   (opens no photo library) and names any that is missing
+                   or won't load. The optional dlib backend isn't checked.
 
 Global: --extensions STR (default: every supported photo, camera RAW and video format)
 ```
@@ -591,7 +595,7 @@ cd desktop && npm run dev
 For a standalone `.app` bundle (launchable from Finder/Spotlight):
 
 ```bash
-# Build sidecar (PyInstaller-bundled Python server)
+# Build the server (PyInstaller-bundled Python server, as a helper app)
 cd desktop && ./build-sidecar.sh
 
 # Build .app + .dmg
@@ -599,7 +603,7 @@ npm run build
 # Output: desktop/src-tauri/target/release/bundle/
 ```
 
-The sidecar binary lands at `desktop/src-tauri/binaries/bpp-server-{target-triple}` (e.g., `bpp-server-aarch64-apple-darwin`).
+The server lands at `desktop/src-tauri/helpers/bpp-server.app`, and the app carries it in `Contents/Helpers/`. `desktop/bpp-server.spec` is the PyInstaller build (layout, hidden imports, signing).
 
 > **Note:** A build you make yourself isn't signed with an Apple Developer ID, so Gatekeeper will block it the first time. To open it: right-click → Open → Open (once). The release DMG and the app inside are signed with a Developer ID and notarized by Apple, so they open normally.
 
@@ -636,7 +640,7 @@ bpp/
     templates/index.html    # Single-page HTML shell
 desktop/
   src-tauri/                # Tauri v2 Rust app
-  build-sidecar.sh          # PyInstaller sidecar build
+  build-sidecar.sh          # builds the server helper app (bpp-server.spec)
   scripts/dev-macos.sh      # Dev launcher
 ```
 

{bppicker-0.2.3 → bppicker-0.2.4}/bpp/__init__.py

@@ -18,7 +18,7 @@ _os.environ.setdefault("OPENCV_IO_MAX_IMAGE_PIXELS", str(200_000_000))
 # the first import.
 _os.environ.setdefault("NO_ALBUMENTATIONS_UPDATE", "1")
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 APP_NAME = "Best Photo Picker"
 
 # Eagerly import the model registry so the download chokepoint

{bppicker-0.2.3 → bppicker-0.2.4}/bpp/cli.py

@@ -36,6 +36,7 @@ def build_parser() -> argparse.ArgumentParser:
         _add_pick,
         _add_model,
         _add_db,
+        _add_selfcheck,
     ):
         add(sub)
     return parser
@@ -252,6 +253,19 @@ def _add_db(sub: argparse._SubParsersAction) -> None:
     )
 
 
+def _add_selfcheck(sub: argparse._SubParsersAction) -> None:
+    """`bpp selfcheck`: load the native libraries bpp uses."""
+    p = sub.add_parser(
+        "selfcheck",
+        help="Check that the native libraries the desktop app bundles load (no photo library)",
+    )
+    p.add_argument(
+        "--require-all",
+        action="store_true",
+        help="Also fail when an optional part isn't installed (the desktop app has them all)",
+    )
+
+
 def cmd_analyze(args: argparse.Namespace) -> int:
     """Scan images, extract features, and compute quality scores."""
     from bpp.commands import do_analyze
@@ -324,6 +338,12 @@ def cmd_db(args: argparse.Namespace) -> int:
     return 1
 
 
+def cmd_selfcheck(args: argparse.Namespace) -> int:
+    from bpp.commands.selfcheck import do_selfcheck
+
+    return do_selfcheck(args)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
@@ -342,6 +362,7 @@ def main(argv: list[str] | None = None) -> int:
         "pick": cmd_pick,
         "model": cmd_model,
         "db": cmd_db,
+        "selfcheck": cmd_selfcheck,
     }
     if args.command in ("serve", "web", "demo", "run", "analyze", "pick"):
         from bpp.scoring.cpu_support import probe_before_threads

bppicker-0.2.4/bpp/commands/selfcheck.py

@@ -0,0 +1,147 @@
+"""``bpp selfcheck``: load the native libraries the desktop app bundles.
+
+The checks are the list in ``CHECKS``: the base install plus the web,
+HEIC, RAW, faces (MediaPipe, LiteRT, SciPy) and inpainting extras. The
+optional dlib face backend of a pip install is not among them (the app
+leaves it out). It opens no photo library: each check only imports a
+package (or loads the shared library it loads at runtime), exactly as
+bpp does at first use, and reports one of
+
+* ``ok``      — it loaded;
+* ``missing`` — the package isn't installed (an optional part of a pip
+  install, e.g. ``bppicker[raw]``);
+* ``FAILED``  — it is installed but would not load;
+* ``skipped`` — this processor can't run it, and bpp turns it off
+  (MediaPipe on an x86-64 processor without AVX).
+
+An import may write what it would write at first use anyway (MediaPipe
+pulls in matplotlib, which builds its font cache once), and starting
+``bpp`` reads the model registry online as every command does (set
+``BPP_DISABLE_REMOTE_REGISTRY=1`` to skip that).
+
+The Mac app's release check runs it with ``--require-all`` in the signed
+server, so a library macOS refuses to load fails the release instead of
+a user's first import, face scan or inpaint.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+import importlib
+import importlib.util
+import os
+import sys
+from collections.abc import Callable
+
+OK = "ok"
+MISSING = "missing"
+FAILED = "FAILED"
+SKIPPED = "skipped"
+
+
+def _import(module: str) -> Callable[[], object]:
+    return lambda: importlib.import_module(module)
+
+
+def _opencv() -> None:
+    import cv2
+
+    cascade = os.path.join(cv2.data.haarcascades, "haarcascade_frontalface_default.xml")
+    if not os.path.isfile(cascade):  # the last-resort face detector reads it
+        raise FileNotFoundError(cascade)
+
+
+def _onnxruntime() -> None:
+    import onnxruntime
+
+    if not onnxruntime.get_available_providers():
+        raise RuntimeError("onnxruntime reports no execution providers")
+
+
+def _cryptography() -> None:
+    from cryptography.hazmat.primitives.asymmetric import ed25519
+
+    ed25519.Ed25519PrivateKey.generate()  # the model-registry verifier's backend
+
+
+def _pillow_heif() -> None:
+    from pillow_heif import register_heif_opener
+
+    register_heif_opener()
+
+
+def _mediapipe() -> None:
+    from bpp.scoring.cpu_support import refuse_if_cpu_unsupported
+
+    # Loading it would crash this process on a processor without AVX; bpp
+    # checks first everywhere it imports mediapipe, and so does this.
+    refuse_if_cpu_unsupported("mediapipe")
+    import mediapipe
+
+    # Load the native code the Tasks API runs on now, so a library the OS
+    # refuses shows up here. Newer releases load a C library with ctypes
+    # at first use (through mediapipe_c_bindings); older ones (e.g. 0.10.21,
+    # which `mediapipe>=0.10` allows) ship a Python extension instead.
+    if importlib.util.find_spec("mediapipe.tasks.python.core.mediapipe_c_bindings"):
+        name = {"darwin": "libmediapipe.dylib", "linux": "libmediapipe.so"}.get(sys.platform)
+        if name:
+            ctypes.CDLL(os.path.join(os.path.dirname(mediapipe.__file__), "tasks", "c", name))
+    else:
+        importlib.import_module("mediapipe.python._framework_bindings")
+
+
+def _litert() -> None:
+    from ai_edge_litert.interpreter import Interpreter  # noqa: F401
+
+
+def _inpainting() -> None:
+    from simple_lama_inpainting import SimpleLama  # noqa: F401  (loads PyTorch)
+
+
+# (name shown, top-level module whose absence means "not installed", check)
+CHECKS: list[tuple[str, str, Callable[[], object]]] = [
+    ("numpy", "numpy", _import("numpy")),
+    ("Pillow", "PIL", _import("PIL.Image")),
+    ("OpenCV", "cv2", _opencv),
+    ("ONNX Runtime", "onnxruntime", _onnxruntime),
+    ("cryptography", "cryptography", _cryptography),
+    ("Flask", "flask", _import("flask")),
+    ("HEIC (pillow-heif)", "pillow_heif", _pillow_heif),
+    ("camera RAW (rawpy)", "rawpy", _import("rawpy")),
+    ("SciPy clustering", "scipy", _import("scipy.cluster.hierarchy")),
+    ("MediaPipe", "mediapipe", _mediapipe),
+    ("LiteRT", "ai_edge_litert", _litert),
+    ("inpainting (PyTorch)", "simple_lama_inpainting", _inpainting),
+]
+
+
+def run_check(top: str, check: Callable[[], object]) -> tuple[str, str]:
+    """(status, detail) for one check. Only the package itself being
+    absent is "missing"; an installed package that lacks one of its own
+    modules (a partial install, a module a frozen build left out) failed."""
+    from bpp.scoring.cpu_support import CpuUnsupported
+
+    try:
+        check()
+    except CpuUnsupported as e:
+        return SKIPPED, str(e)
+    except ModuleNotFoundError as e:
+        if e.name == top:
+            return MISSING, ""
+        return FAILED, f"{type(e).__name__}: {e}"
+    except Exception as e:  # anything else means installed but broken
+        return FAILED, f"{type(e).__name__}: {e}"
+    return OK, ""
+
+
+def do_selfcheck(args: argparse.Namespace) -> int:
+    failed = absent = 0
+    for name, top, check in CHECKS:
+        status, detail = run_check(top, check)
+        print(f"{status:<8}{name}" + (f": {detail}" if detail else ""), flush=True)
+        failed += status == FAILED
+        absent += status in (MISSING, SKIPPED)
+    if failed or (absent and args.require_all):
+        return 1
+    return 0

{bppicker-0.2.3 → bppicker-0.2.4}/bpp/commands/serve.py

@@ -15,6 +15,7 @@ import os
 from typing import Any
 
 from bpp.utils.logging import get_logger, setup_logging
+from bpp.web.wsgi_bind import bind_without_reverse_dns
 
 
 def do_web(args: argparse.Namespace) -> int:
@@ -54,6 +55,7 @@ def do_web(args: argparse.Namespace) -> int:
     # ``--debug`` means verbose logging (setup_logging above), never
     # Werkzeug's interactive debugger: that would hand a traceback page
     # and a code console to anyone who can reach the port.
+    bind_without_reverse_dns()
     app.run(host=host, port=port, debug=False, threaded=True)
     return 0
 
@@ -133,6 +135,7 @@ def do_serve(args: argparse.Namespace) -> int:
     # Werkzeug's interactive debugger: with sharing on the server binds the
     # LAN, and the debugger's traceback pages and console would be reachable
     # by any device that can send a loopback Host header.
+    bind_without_reverse_dns()
     app.run(
         host=host,
         port=port,

bppicker-0.2.4/bpp/web/wsgi_bind.py

@@ -0,0 +1,40 @@
+"""Bind the Werkzeug server without a reverse DNS lookup.
+
+``http.server.HTTPServer.server_bind``, which Werkzeug's servers inherit,
+looks up the fully qualified name of the bound host (``socket.getfqdn``)
+only to fill ``server_name``. Werkzeug never reads that attribute: the
+WSGI ``SERVER_NAME`` comes from ``server_address``. On macOS the lookup
+can go to multicast DNS and block. In the desktop app's server it held
+the port unopened for about 35 s while the app was waiting for it. So
+the bind skips the lookup and records the host as given.
+"""
+
+from __future__ import annotations
+
+import http.server
+import socketserver
+
+
+def _server_bind(self: socketserver.TCPServer) -> None:
+    # http.server.HTTPServer.server_bind, minus socket.getfqdn(host).
+    socketserver.TCPServer.server_bind(self)
+    host, port = self.server_address[:2]
+    self.server_name = host  # type: ignore[attr-defined]
+    self.server_port = port  # type: ignore[attr-defined]
+
+
+def bind_without_reverse_dns() -> None:
+    """Make Werkzeug's servers in this process bind without the lookup.
+
+    Only while Werkzeug inherits ``server_bind`` from ``http.server``
+    unchanged: if a Werkzeug release brings its own, replacing it could
+    drop what it does, so the bind is left alone (with the lookup) and
+    tests/test_wsgi_bind.py fails until this is looked at again.
+    """
+    from werkzeug.serving import BaseWSGIServer
+
+    if BaseWSGIServer.server_bind is _server_bind:
+        return
+    if BaseWSGIServer.server_bind is not http.server.HTTPServer.server_bind:
+        return
+    BaseWSGIServer.server_bind = _server_bind  # type: ignore[method-assign]

{bppicker-0.2.3 → bppicker-0.2.4}/docs/architecture-notes.md

@@ -9,7 +9,7 @@ deep dives.
 
 ```
  Mac app (Tauri shell, desktop/)          Browser (bpp serve / bpp demo)
-   spawns `bpp-server` (PyInstaller)         opens the printed ?_boot= link
+   spawns `bpp-server` (PyInstaller helper)  opens the printed ?_boot= link
             │ boot key, port 5001                   │
             ▼                                       ▼
  ┌──────────────────── Flask app (bpp/web) ─────────────────────┐
@@ -42,8 +42,11 @@ deep dives.
   and Playwright against the same endpoints.
 - **Why a Tauri sidecar.** The desktop app is the same server frozen
   with PyInstaller and a thin Rust shell that starts it, proves the
-  port is ours (a boot key), and shows the page. Python is pinned to
-  3.11 because the frozen runtime is; the pip install matches it.
+  port is ours (a boot key), and shows the page. The server is a
+  one-folder build in a background-only helper app
+  (`Contents/Helpers/bpp-server.app`, `desktop/bpp-server.spec`), so
+  nothing is unpacked at launch. Python is pinned to 3.11 because the
+  frozen runtime is; the pip install matches it.
 - **Long work is a job, not a request.** Analyze and face extraction
   run in subprocesses with journaled progress, so a crash or a quit
   resumes on the next start; cheaper background work (hash backfill,

{bppicker-0.2.3 → bppicker-0.2.4}/docs/macos-signing.md

@@ -5,6 +5,13 @@ One-time setup so `release-desktop.yml` produces a DMG that is
 the DMG and the app inside it — so it opens on double-click with no
 Gatekeeper "Open Anyway" detour.
 
+What gets signed first: the app's server is a helper app
+(`Contents/Helpers/bpp-server.app`) that the Tauri bundler copies in but
+does not sign, so the workflow imports the same certificate into a
+temporary keychain and PyInstaller signs every binary in the helper with
+it (hardened runtime, secure timestamp) before the Tauri build. That
+keychain is deleted again before Tauri imports the certificate itself.
+
 What gets notarized: Tauri signs the `.app`, submits it to Apple's
 notary service, staples the ticket to the `.app`, then builds the DMG
 around it and signs the DMG. Tauri does not notarize the DMG itself, so
@@ -95,5 +102,6 @@ build-only path to exercise the full CI build before tagging.)
 ## Fallback behavior
 
 If the secrets are absent (e.g. a fork), the workflow still builds an
-**unsigned** DMG instead of failing — only Arkalogy's releases are signed.
+**unsigned** DMG instead of failing (the server helper is ad-hoc signed)
+— only Arkalogy's releases are signed.
 A fork's users would see the old Gatekeeper warning; Arkalogy's don't.

{bppicker-0.2.3 → bppicker-0.2.4}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 # *import* package stays `bpp` — `pip install bppicker` then
 # `import bpp` is the contract.
 name = "bppicker"
-version = "0.2.3"
+version = "0.2.4"
 description = "Local-first photo curation tool — score, deduplicate, and select the best photos from large collections"
 readme = "README.md"
 requires-python = ">=3.11,<3.12"

{bppicker-0.2.3 → bppicker-0.2.4}/scripts/third_party_bundled.py

@@ -1,9 +1,11 @@
 """Record what PyInstaller actually packed into the frozen sidecar.
 
-Used by ``third_party_inventory.py bundled``. Reads the sidecar's
-archive table of contents (PyInstaller's own reader, so it must run in
-the build environment) and attributes every packed file and module to
-its owner:
+Used by ``third_party_inventory.py bundled``. The sidecar is the
+``bpp-server.app`` helper app (a one-folder build): its files are read
+from the bundle on disk and its Python modules from the archive inside
+the executable (PyInstaller's own reader, so it must run in the build
+environment). A one-file binary (up to 0.2.3) is still read from its
+archive alone. Every packed file and module is attributed to its owner:
 
 * a distribution, via the files its RECORD lists or the top-level
   import names it provides;
@@ -23,6 +25,7 @@ from __future__ import annotations
 
 import hashlib
 import importlib.metadata as md
+import os
 import re
 import sys
 from collections.abc import Iterable, Mapping
@@ -106,6 +109,96 @@ def read_archive(binary: Path) -> tuple[dict, list[str]]:
     return reader.toc, modules
 
 
+_MACHO_MAGIC = {
+    bytes.fromhex(m)
+    for m in ("feedface", "cefaedfe", "feedfacf", "cffaedfe", "cafebabe", "bebafeca")
+}
+
+
+def _is_binary(path: Path) -> bool:
+    with path.open("rb") as fh:
+        head = fh.read(4)
+    return head in _MACHO_MAGIC or head == b"\x7fELF"
+
+
+def bundle_roots(app: Path) -> list[Path]:
+    """Where a helper app's packed files live: PyInstaller puts binaries
+    in Contents/Frameworks and data in Contents/Resources, each relative
+    to the same root (sys._MEIPASS), with symlinks between the two."""
+    return [app / "Contents" / "Frameworks", app / "Contents" / "Resources"]
+
+
+def read_bundle(app: Path) -> tuple[dict, list[str]]:
+    """(TOC-shaped entries for every packed file plus the executable's own
+    archive entries, module names in the embedded PYZ) for a one-folder
+    helper app. Symlinks are aliases of a file listed once; the app's own
+    icon is bpp's and is skipped. PyInstaller renames a dotted folder in
+    Contents/Frameworks (``python3.11``, ``cv2/.dylibs``) to ``__dot__``
+    and links the original name to it; entries keep the original name,
+    the one the running server sees and the distributions record (see
+    ``_original_rel``)."""
+    import plistlib
+
+    info = plistlib.loads((app / "Contents" / "Info.plist").read_bytes())
+    exe = app / "Contents" / "MacOS" / info["CFBundleExecutable"]
+    toc, modules = read_archive(exe)
+    toc = dict(toc)
+    icon = info.get("CFBundleIconFile")
+    for root in bundle_roots(app):
+        for path in _walk(root):
+            if path.is_symlink() or not path.is_file():
+                continue
+            rel = _original_rel(root, path)
+            if root.name == "Resources" and icon and rel == icon:
+                continue
+            toc.setdefault(rel, ("b" if _is_binary(path) else "x",))
+    return toc, modules
+
+
+def _original_rel(root: Path, path: Path) -> str:
+    """*path* relative to *root*, with each Frameworks folder PyInstaller
+    renamed (``.`` → ``__dot__``) given back its original name. A folder
+    counts as renamed only when its parent holds PyInstaller's link from
+    the original name to it; file names, Resources paths and a literal
+    ``__dot__`` without that link are kept as they are."""
+    parts = list(path.relative_to(root).parts)
+    if root.name != "Frameworks":
+        return "/".join(parts)
+    base = root
+    for i, part in enumerate(parts[:-1]):
+        here = base / part
+        if "__dot__" in part:
+            alias = base / part.replace("__dot__", ".")
+            if alias.is_symlink() and Path(os.readlink(alias)) == Path(part):
+                parts[i] = alias.name
+        base = here
+    return "/".join(parts)
+
+
+def _walk(root: Path) -> list[Path]:
+    """Every entry under *root*, sorted, without following symlinks (a
+    linked folder is listed as the link, not walked twice)."""
+    out: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        base = Path(dirpath)
+        out.extend(base / n for n in dirnames + filenames)
+    return sorted(out)
+
+
+def tree_sha256(app: Path) -> str:
+    """One digest over every file and link of the helper app (path +
+    content or target), so the inventory names exactly the build it
+    describes."""
+    h = hashlib.sha256()
+    for path in _walk(app):
+        rel = path.relative_to(app).as_posix()
+        if path.is_symlink():
+            h.update(f"L {rel} -> {path.readlink()}\n".encode())
+        elif path.is_file():
+            h.update(f"F {rel} {_sha256(path)}\n".encode())
+    return h.hexdigest()
+
+
 def attribute(toc: Mapping[str, tuple], modules: Iterable[str], attributor: Attributor) -> dict:
     owners: dict[str, dict] = {}
     unattributed: list[str] = []
@@ -153,7 +246,8 @@ def _sha256(path: Path) -> str:
 def record_bundled(inv: dict, binary: Path, dists: Mapping[str, md.Distribution]) -> None:
     from third_party_inventory import canon, dist_record
 
-    toc, modules = read_archive(binary)
+    is_bundle = binary.is_dir()
+    toc, modules = read_bundle(binary) if is_bundle else read_archive(binary)
     result = attribute(toc, modules, Attributor(dists, inv["root"]["name"]))
     listed = {canon(d["name"]) for d in inv["distributions"]}
     special = {CPYTHON, PYINSTALLER, inv["root"]["name"]}
@@ -173,7 +267,8 @@ def record_bundled(inv: dict, binary: Path, dists: Mapping[str, md.Distribution]
     inv["distributions"].sort(key=lambda r: r["name"].lower())
     inv["sidecar"] = {
         "binary": binary.name,
-        "sha256": _sha256(binary),
+        "layout": "one-folder helper app" if is_bundle else "one-file binary",
+        "sha256": tree_sha256(binary) if is_bundle else _sha256(binary),
         "archive_entries": len(toc),
         "pyz_modules": len(modules),
         "added_by_pyinstaller": sorted(added),