Misc Opts

SCRATCHPAD.md

@@ -9,9 +9,10 @@
 - The biggest near-term wins are in startup cost, repeated subprocess work, repeated database query patterns, and general repo hygiene.
 - This list is intentionally optimization-oriented rather than bug-oriented. Some items below also improve correctness or maintainability, but they were selected because they can reduce runtime cost, operator friction, or iteration overhead.
 - A first modern integration slice now exists under [`tests/integration/subtrack_mapping`](/home/osgw/.local/src/codex/ffx/tests/integration/subtrack_mapping). Remaining test-suite cleanup is now mostly about migrating and shrinking the legacy harness surface under [`tests/legacy`](/home/osgw/.local/src/codex/ffx/tests/legacy).
-- The CLI root now lazy-loads heavy runtime dependencies so lightweight commands such as `version`, `help`, `configure_workstation`, and `upgrade` stay import-light.
+- The CLI root now lazy-loads heavy runtime dependencies so lightweight commands such as `version`, `help`, `setup`, `configure_workstation`, and `upgrade` stay import-light.
 - Shared CLI defaults for container/output tokens now live outside [`src/ffx/ffx_controller.py`](/home/osgw/.local/src/codex/ffx/src/ffx/ffx_controller.py), and a focused unit test locks in the lazy-import contract.
 - `FileProperties` now uses one cached `ffprobe -show_format -show_streams -of json` call per source file, and the combined payload was confirmed against the Dragonball asset to satisfy both previous probe call sites fully.
+- Crop detection now uses configurable sampling windows plus per-process caching keyed by source file and sampling range, and the `cropdetect` CLI command now calls the real `FileProperties.findCropArguments()` path.
 - Database startup now bootstraps schema only when required tables are actually missing, while version enforcement still runs on ordinary DB-backed context creation.
 - Helper filename and rich-text utilities now use compiled raw regexes plus translate-based filename filtering, with unit coverage for TMDB suffix rewriting and Rich color stripping.
 - Process resource limiting now has explicit disabled/default states in the CLI and requirements, and combined CPU-plus-niceness wrapping now executes as `cpulimit -- nice -n ... <command>` instead of a less explicit prefix chain.
@@ -19,37 +20,21 @@
 - The process wrapper now uses `subprocess.run(...)` with centralized command formatting plus stable timeout and missing-command error mapping.
 - Active ORM controllers now use single-query accessors instead of paired `count()` plus `first()` lookups.
 - Pattern matching now uses cached compiled regexes plus explicit duplicate-match errors, and pattern creation flows no longer persist zero-track patterns.
+- The two-step local setup flow now has aligned CLI wrappers for both phases: `ffx setup` for bundle prep and `ffx configure_workstation` for workstation prep, while the shell scripts remain the bootstrap entrypoints before the bundle exists.
+- The large detail screens now share one screen-bootstrap helper for context, metadata-filter extraction, and controller wiring, and show-pattern loading now goes through `PatternController` instead of a screen-local session query.
 
 ## Focused Snapshot
 
 - Highest-leverage application optimizations:
-  - Revisit crop detection cost now that the probe path is consolidated.
+  - Decide whether placeholder help/settings screens should ship or disappear.
+  - Trim dead helpers and other dormant surface that still looks active.
 
 - Highest-leverage repo and workflow optimizations:
-  - Consolidate setup and upgrade tooling to reduce overlapping shell-script responsibilities.
   - Continue migrating the oversized legacy test/combinator surface into focused modern tests so it is easier to run, debug, and extend.
 
 ## Optimization Candidates
 
-1. Crop detection is always a full extra ffmpeg scan
-- [`src/ffx/file_properties.py`](/home/osgw/.local/src/codex/ffx/src/ffx/file_properties.py) runs a dedicated `ffmpeg -vf cropdetect` pass for each file when crop detection is requested.
-- Optimization:
-  - Cache crop results for repeated runs on the same source.
-  - Consider exposing shorter sampling windows or probe presets for large files.
-- Expected value:
-  - Lower latency on repeated experimentation.
-
-2. Tooling overlap and naming drift
-- There are still overlapping workstation-setup entrypoints across [`tools/configure_workstation.sh`](/home/osgw/.local/src/codex/ffx/tools/configure_workstation.sh), [`tools/setup.sh`](/home/osgw/.local/src/codex/ffx/tools/setup.sh), and newer CLI maintenance commands.
-- Optimization:
-  - Decide which scripts remain canonical.
-  - Replace or remove legacy wrappers once equivalent CLI commands exist.
-  - Keep CLI maintenance commands and shell wrappers aligned.
-- Expected value:
-  - Less operator confusion.
-  - Fewer duplicated procedures to maintain.
-
-3. Placeholder UI surfaces should either ship or disappear
+1. Placeholder UI surfaces should either ship or disappear
 - [`src/ffx/help_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/help_screen.py) and [`src/ffx/settings_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/settings_screen.py) are placeholders.
 - Optimization:
   - Either remove them from the active UI surface or complete them.
@@ -58,16 +43,7 @@
   - Leaner interface.
   - Lower UX ambiguity.
 
-4. Large Textual screens repeat configuration and controller loading
-- Screens such as [`src/ffx/media_details_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/media_details_screen.py), [`src/ffx/pattern_details_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/pattern_details_screen.py), and [`src/ffx/show_details_screen.py`](/home/osgw/.local/src/codex/ffx/src/ffx/show_details_screen.py) repeat setup patterns and local metadata filtering extraction.
-- Optimization:
-  - Extract a shared screen base or helper for common config/controller/bootstrap logic.
-  - Reduce repeated table refresh and repeated DB fetch code where possible.
-- Expected value:
-  - Lower maintenance overhead.
-  - Easier UI iteration.
-
-5. Several helper functions are unfinished or dead-weight
+2. Several helper functions are unfinished or dead-weight
 - [`src/ffx/helper.py`](/home/osgw/.local/src/codex/ffx/src/ffx/helper.py) contains `permutateList(...): pass`.
 - There are many combinator and conversion placeholders across tests and migrations.
 - Optimization:
@@ -77,7 +53,7 @@
   - Smaller mental model.
   - Less time spent re-evaluating inactive paths.
 
-6. Test suite shape is expensive to understand and likely expensive to run
+3. Test suite shape is expensive to understand and likely expensive to run
 - The project still carries a large legacy matrix of combinator files under [`tests/legacy`](/home/osgw/.local/src/codex/ffx/tests/legacy), several placeholder `pass` implementations, and at least one suspicious filename with an embedded space: [`tests/legacy/disposition_combinator_2_3 .py`](/home/osgw/.local/src/codex/ffx/tests/legacy/disposition_combinator_2_3 .py).
 - A first focused replacement slice now exists in [`tests/integration/subtrack_mapping/test_cli_bundle.py`](/home/osgw/.local/src/codex/ffx/tests/integration/subtrack_mapping/test_cli_bundle.py), so the remaining work is migration and consolidation rather than creating the modern test shape from scratch.
 - Optimization:
@@ -102,9 +78,9 @@
 ## Next
 
 1. Triage the list into quick wins, medium refactors, and long-horizon cleanup.
-2. Tackle the cheapest high-impact items first:
-   - crop detection sampling or caching pass.
-3. Decide which setup and upgrade entrypoints stay canonical before adding more maintenance surface.
+2. Tackle the cheapest remaining product-surface cleanup first:
+   - placeholder UI surfaces and dead helper cleanup.
+3. Continue replacing oversized legacy test matrices with focused modern integration and unit coverage.
 
 ## Delete When