nightly

ff
2026-04-09 01:04:47 +02:00 · 2026-04-09 01:03:41 +02:00
7 changed files with 7 additions and 723 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,376 +0,0 @@
 # AGENTS.md
 This file is the entry point for agent guidance in this repository.
 It is intentionally generic and reusable across projects. Keep this file focused on non-project-specific constraints, working style, and the structure used to link more detailed guidance.
 # Purpose
 - Provide a small default rule set for agents working in this repository.
 - Keep the base guidance modular and easy to extend.
 - Separate reusable agent behavior from project-specific requirements.
 # Comment Syntax
 - A segment wrapped in `<!--` and `-->` is a comment and must be ignored by agents.
 - Use HTML comments for optional guidance that should stay inactive until enabled.
 - To enable an optional segment, remove the surrounding `<!--` and `-->` markers.
 # Core Principles
 - Prefer the simplest solution that satisfies the current goal.
 - Keep guidance lightweight: only add detail when it meaningfully improves outcomes.
 - Reuse modular guideline files instead of expanding this file indefinitely.
 - Treat project-specific documents as the source of truth for project behavior.
 - When guidance conflicts, use the most specific applicable document.
 # Rule Terms
 - A `rule` is the general term for any constraint, requirement, definition, or similar guidance item.
 - A `rule set` addresses all rules inside one file that share the same rule set ID.
 - Any rule inside a rule set shall use an ID following the schema `RULESET-0001`, `RULESET-0002`, and so on.
 - Rules without a rule set ID are also valid, but they are not addressable by rule ID.
 # Scope Of This File
 This file should contain:
 - Generic agent behavior and constraints.
 - Rules that are reusable across multiple projects.
 - Links to optional guideline modules.
 - Links to project-specific requirements.
 - Commented optional templates for released-product documentation and agent-output locations.
 This file should not contain:
 - Project business requirements.
 - Project architecture decisions.
 - Stack-specific implementation details unless they are universally applicable.
 - Task-specific runbooks that belong in dedicated modules.
 # Default Agent Behavior
 - Read the relevant context before making changes.
 - Prefer small, understandable edits over broad refactors.
 - Preserve existing patterns unless there is a clear reason to change them.
 - Document assumptions when context is missing.
 - Ignore HTML comment segments.
 - If a more specific enabled guideline exists for the current task, follow it.
 # Guideline Structure
 Use the following structure for reusable guidance files and project-specific documentation as needed:
 ```text
 /
 |-- AGENTS.md
 |-- guidance/
 |   |-- stacks/
 |   |-- conventions/
 |   `-- workflows/
 |-- prompts/
 `-- requirements/
 Optional files and directories
 |-- SCRATCHPAD.md
 |-- docs/
 |   |-- readme.md
 |   |-- installation.md
 |   `-- history.md
 |-- process/
 |   |-- log.md
 |   `-- coding-handbook.md
 ```
 # Optional Reusable Modules
 Add files under `guidance/` only when they are needed.
 # Optional Scratchpad
 - `SCRATCHPAD.md` is an optional repo-root scratchpad for temporary
  information aimed at the next iteration.
 - Developers may create or delete `SCRATCHPAD.md` at any time.
 - Developers may refer to `SCRATCHPAD.md` as `scratchpad` when giving agents a
  source or target for information.
 - Agents may read, update, create, or remove the scratchpad when the task
  explicitly calls for it.
 - Treat the scratchpad as low-formality working context rather than canonical
  project truth.
 - Use the scratchpad for short-lived notes, open questions, sketches, and
  temporary decisions that should be resolved away.
 - Move durable outcomes into `requirements/`, `guidance/`, code, tests, or
  another long-lived location.
 - If `SCRATCHPAD.md` is absent, agents should continue normally.
 # Optional Rule Sets
 - Optional rule sets may be stored in `guidance/optional/` or in `guidance/{section}/optional/`.
 - Optional rule sets are inactive by default and shall only be applied when a prompt explicitly requests them, for example by phrases such as `Apply rules for lean interface iteration in the following steps.` or `Apply LII rules.`
 - An optional rule set may be requested by its descriptive name, by its rule set ID, or by another equally clear explicit reference.
 - Agents shall never infer or auto-enable optional rule sets from general intent alone.
 - If an optional rule or rule set cannot be identified and addressed clearly, agents shall stop and ask before proceeding.
 # Prepared Orders
 - An `order` is a prepared prompt for one isolated operation rather than a general workflow or standing rule set.
 - Orders shall be stored under `prompts/`.
 - Order files shall use the naming schema `ORDER-0001-<slug>.md`, `ORDER-0002-<slug>.md`, and so on.
 - The canonical order identifier is the `ORDER-0001` style prefix. The trailing slug is descriptive only.
 - Recommended internal order file structure is: prompt ID, prompt name, purpose, trigger examples, scope, operation, and expected output.
 - Orders shall only be executed when they are explicitly requested by a prompt such as `Execute ORDER-0007.` or `Execute ORDER 7.`
 - Agents may accept an unambiguous short numeric reference such as `ORDER 7` as an alias for `ORDER-0007`.
 - If an order cannot be identified uniquely and clearly, agents shall stop and ask before proceeding.
 # Toolstack Guides
 Location:
 ```text
 guidance/stacks/
 ```
 Examples:
 - `guidance/stacks/python.md`
 - `guidance/stacks/typescript.md`
 - `guidance/stacks/docker.md`
 - `guidance/stacks/terraform.md`
 Use for:
 - Language or framework expectations.
 - Tooling and environment conventions.
 - Build, test, and runtime guidance tied to a specific stack.
 # Coding Conventions
 Location:
 ```text
 guidance/conventions/
 ```
 Examples:
 - `guidance/conventions/naming.md`
 - `guidance/conventions/testing.md`
 - `guidance/conventions/review.md`
 Use for:
 - Naming and structure conventions.
 - Testing expectations.
 - Code review and quality rules.
 # Recurring Workflows
 Location:
 ```text
 guidance/workflows/
 ```
 Examples:
 - `guidance/workflows/feature-delivery.md`
 - `guidance/workflows/bugfix.md`
 - `guidance/workflows/release.md`
 - `guidance/workflows/incident-response.md`
 Use for:
 - Repeatable task flows.
 - Checklists for common delivery work.
 - Operational or maintenance procedures.
 <!-- Enable this optional section by removing the outer HTML comment markers from this segment
 when you want agents to create, update, and consult released-product
 documentation in `docs/`.
 # Released Product Documentation
 Released-product documentation should live outside the generic sections above.
 Recommended location:
 ```text
 docs/
 ```
 Examples:
 - `docs/readme.md`
 - `docs/installation.md`
 - `docs/history.md`
 Agent rules for docs output:
 - Keep content compact but comprehensive.
 - Write for end users, operators, or other consumers of the released product.
 - Prefer shipped behavior, supported workflows, and stable terminology over
  internal implementation detail.
 - Keep documentation synchronized with released behavior.
 - Update release history when user-visible changes are shipped.
 Recommended topics:
 - Product overview and intended use.
 - Installation, configuration, and upgrade guidance.
 - Usage patterns, operational instructions, and support boundaries.
 - Compatibility notes, migration notes, and release history.
 - Troubleshooting and common pitfalls when relevant. -->
 <!-- Enable this optional section by removing the outer HTML comment markers from this
 segment when you want agents to produce and consult workflow output in `process/`.
 # Agent Output In `process/`
 The `process/` directory is primarily for agent output created during
 delivery, maintenance, and review work.
 Recommended location:
 ```text
 process/
 ```
 Agent rules for process output:
 - Use `process/` for agent-produced artifacts rather than released-product
  documentation.
 - Keep entries concise, traceable, and tied to resulting changes.
 - Treat `process/` as workflow output, not as the primary source of product
  truth.
 - Prefer summaries and rationale over raw transcript dumps unless a workflow
  explicitly requires full prompt history.
 # Agent Change Log
 Location:
 ```text
 process/log.md
 ```
 Use for:
 - Capturing prompts given to agents.
 - Recording concise explanations of the resulting changes made by agents.
 - Preserving task-by-task rationale, decisions, and implementation notes.
 # Coding Handbook
 Location:
 ```text
 process/coding-handbook.md
 ```
 Use for:
 - A tutorial-style handbook that explains the programming components used in
  the project.
 - Compact but comprehensive technical onboarding material for future
  contributors.
 - Written explanations that connect code structure, concepts, and
  implementation patterns. -->
 # Project-Specific Requirements
 Project-specific material should live outside the generic sections above.
 Recommended location:
 ```text
 requirements/
 ```
 Examples:
 - `requirements/project.md`
 - `requirements/architecture.md`
 - `requirements/decisions.md`
 - `requirements/domain.md`
 Use for:
 - Product and business requirements.
 - Project goals and constraints.
 - Architecture and design decisions.
 - Domain knowledge that is specific to this repository.
 # Agent-Level Variables
 When present, `requirements/identifiers.yml` is an optional project-specific
 input that defines agent-level variables for use inside `requirements/` and
 `guidance/`.
 Variable schema:
 - Use `@{VARIABLE_NAME}` for agent-level variables.
 - Prefer uppercase snake case names such as `@{PROJECT_ID}` or `@{VENDOR_ID}`.
 - Do not treat `${...}` as an agent-level variable form; that syntax may appear
  in Bash or other code and should not be interpreted as agent metadata.
 Scope:
 - The effective scope of `requirements/identifiers.yml` is limited to
  `requirements/` and `guidance/`.
 - Definitions from `requirements/identifiers.yml` must not leak into product code.
 Defaults:
 - Default `@{VENDOR_ID}` is `osgw`.
 - Default `@{PROJECT_ID}` is the current repository directory name.
 Resolution rules:
 - Treat `requirements/identifiers.yml` as optional; when it is absent, agents
  may still resolve the defaults defined above.
 - If a variable is used in `requirements/` or `guidance/` and it is not
  defined in `requirements/identifiers.yml` and does not have a default in this
  file, agents may stop and report the undefined variable.
 - Prefer updating duplicated identifier values in `requirements/` and
  `guidance/` to use the variable schema when that improves consistency.
 # Precedence
 Some precedence levels may be absent because optional levels can remain inside
 HTML comments. The smaller numeric index wins.
 Apply guidance in this order:
 1. Direct user or task instructions.
 2. Project-specific documents in `requirements/`.
 <!-- 3. Released-product documentation in `docs/` when shipped behavior or
 user-facing expectations are relevant. -->
 4. Relevant modular guides in `guidance/stacks/`, `guidance/conventions/`, or `guidance/workflows/`.
 <!-- 5. Agent output in `process/` when prior prompts, rationale, or
 implementation notes are relevant. -->
 6. This `AGENTS.md`.
 # Maintenance
 - Keep this file short and stable.
 - Move detail into dedicated modules when a section becomes too specific or too long.
 - Add new guideline files only when they solve a recurring need.
 - Remove outdated references when the repository structure changes.
 # Current Status
 This repository defines the base `AGENTS.md` structure plus project-specific
 requirements and modular guidance.
 Future project work can add:
 - Reusable modules under `guidance/`
 - Project-specific documentation under `requirements/`
 - Optional temporary iteration context in `SCRATCHPAD.md`
 - Optional released-product documentation under `docs/` by uncommenting its segment
 - Optional agent output under `process/` by uncommenting its segment
 - Cross-references from this file once those documents exist
--- a/SCRATCHPAD.md
+++ b/SCRATCHPAD.md
@@ -1,62 +0,0 @@
 <!--
 # Scratchpad
 Temporary information holder for the next iteration. Developers may create or
 delete this file at any time. Anything durable should move into code, tests, or
 canonical docs, then this file should disappear.
 ## Goal
 Use this section for the current slice of work. It should explain what the
 scratchpad is helping us move forward right now.
 ## Settled
 Use this for decisions that are stable enough to guide the next steps, but are
 still temporary enough to live in the scratchpad for now.
 ## Focused Snapshot
 Use an extra section like this only when one slice needs its own compact
 summary. This is useful when a specific API, boundary, or model was recently
 recreated and should be captured clearly.
 ## Open
 Use this for unresolved questions, design choices, and risks that still need a
 decision.
 ## Sketches
 Use this for rough candidate structures, names, or shapes. Keep it explicit
 that these are sketches, not committed architecture.
 ## Gaps Right Now
 Use this for concrete missing pieces in the current repo state. This section
 should describe what is absent or incomplete, not broad future ambitions.
 ## Next
 Use this for the immediate sequence of work. It should be short, ordered, and
 biased toward the next deliverable rather than a long roadmap.
 ## Delete When
 Use this to define when the scratchpad should disappear. That keeps it clearly
 temporary and helps prevent it from turning into shadow documentation.
 ## Suggested Style
 - Prefer short bullets over long prose.
 - Keep facts, questions, and rough sketches in separate sections.
 - Add custom sections only when they help the next iteration move faster.
 - Move durable outcomes out of the scratchpad once they stop being temporary.
 -->
--- a/guidance/workflow/optional/lean-interface-iteration.md
+++ b/guidance/workflow/optional/lean-interface-iteration.md
@@ -1,28 +0,0 @@
 # Lean Interface Iteration
 Rule set name: `lean-interface-iteration`
 Rule set ID: `LII`
 Status: optional, prompt-activated only
 Trigger examples:
 - `Apply the lean-interface-iteration rules.`
 - `Apply LII rules.`
 LII-0001: Apply this rule set only when it is explicitly requested in the prompt.
 LII-0002: The target of work under this rule set is the iterated product state for the addressed iteration only.
 LII-0003: Optimize the addressed interface toward the leanest and least complex model that still satisfies the iteration order.
 LII-0004: Backward compatibility, legacy aliases, and compatibility shims are not required unless the prompt explicitly asks to preserve them.
 LII-0005: Prefer one authoritative interface over multiple overlapping parameters, flags, or naming variants.
 LII-0006: Remove or avoid transitional interface layers when they are not required by the addressed iteration order.
 LII-0007: Update affected tests, guidance, requirements, and documentation so they describe the simplified interface model rather than a mixed legacy-and-new model.
 LII-0008: Never change behavior, interfaces, or surrounding areas that are not addressed by the current iteration order.
--- a/guidance/workflow/optional/preparation-script-design.md
+++ b/guidance/workflow/optional/preparation-script-design.md
@@ -1,56 +0,0 @@
 # Preparation Script Design
 Rule set name: `preparation-script-design`
 Rule set ID: `PSD`
 Status: optional, prompt-activated only
 Trigger examples:
 - `Apply the preparation-script-design rules.`
 - `Apply PSD rules.`
 PSD-0001: Apply this rule set only when it is explicitly requested in the prompt.
 PSD-0002: Use this rule set for scripts whose purpose is to prepare, verify, or expose a local development or automation environment rather than to perform product runtime behavior.
 PSD-0003: Keep a preparation script focused on environment readiness, dependency installation, local helper exposure, and clear verification output; do not mix unrelated product logic into the script.
 PSD-0004: Design the script to be idempotent so repeated runs converge on the same prepared state without unnecessary reinstallation or destructive side effects.
 PSD-0005: Provide a verification-only mode such as `--check` that reports readiness without installing, modifying, or creating dependencies.
 PSD-0006: Separate component checks from installation steps so the script can report what is missing before or after attempted remediation.
 PSD-0007: Group required capabilities into clear purpose-oriented sections such as support toolchains, local package bundles, generated environment helpers, or other relevant readiness areas instead of presenting one undifferentiated dependency list.
 PSD-0008: Prefer explicit per-component check helpers over opaque one-shot checks so failures remain traceable and easy to extend.
 PSD-0009: Generate or update environment helper files only when they provide a stable, reusable way to expose repo-local or workspace-local tools, paths, or environment variables.
 PSD-0010: Generated environment helper files shall be safe to source multiple times and should avoid duplicating path entries or clobbering unrelated user environment state.
 PSD-0011: When a preparation flow seeds optional user-owned files such as config templates, do so non-destructively by creating them only when absent unless the prompt explicitly requests overwrite behavior.
 PSD-0012: Report status in a concise scan-friendly line format of the shape `[status] Label: detail`, where the label names the checked component and the detail string stays short and specific.
 PSD-0013: Prefer a small canonical status vocabulary in those report lines, with `ok` for satisfied checks, `warn` for non-blocking gaps, and a failure status such as `failed` for blocking or unsuccessful states.
 PSD-0014: When a preparation script uses terminal colors in its status output, apply a consistent severity mapping so `ok` is green, `warn` is yellow, and all other status levels are red.
 PSD-0015: In bracketed status markers such as `[ok]` or `[warn]`, keep the square brackets uncolored and apply the severity color only to the inner status text.
 PSD-0016: Colorized status output shall degrade safely in non-terminal or non-color contexts so the script remains readable and automation-friendly without ANSI support.
 PSD-0017: End with an explicit readiness conclusion that distinguishes between successful preparation, incomplete prerequisites, and failed installation attempts.
 PSD-0018: Installation logic should use the narrowest supported platform-specific package-manager actions necessary for the declared scope and should fail clearly when no supported installation path is available.
 PSD-0019: Treat repo-local helper tooling and local package installation boundaries explicitly rather than assuming global installs, especially when the prepared environment is intended to be reproducible.
 PSD-0020: Keep the script suitable for both interactive local developer use and non-interactive automation checks by avoiding prompts during normal execution unless the prompt explicitly requires interactivity.
 PSD-0021: When a script depends on generated helper files or adjacent validation helpers, update those supporting files only as needed to keep the preparation flow coherent and usable.
 PSD-0022: Verify shell syntax after changes and, when feasible, run a dry readiness check so the resulting preparation flow is validated rather than only written.
--- a/requirements/architecture.md
+++ b/requirements/architecture.md
@@ -1,97 +0,0 @@
 # Architecture
 ## Architecture Goals
 - Keep the tool small, local, and easy to reason about.
 - Separate media inspection, stored normalization rules, and conversion execution clearly enough that users can inspect and adjust behavior.
 - Favor explicit local state and deterministic rule application over opaque automation.
 - Make external runtime dependencies and platform assumptions visible.
 ## System Context
 - Primary actors:
  - Local operator running the CLI.
  - Local operator using the Textual TUI to inspect files and maintain rules.
 - External systems:
  - `ffprobe` for media introspection.
  - `ffmpeg` for conversion and extraction.
  - TMDB API for optional show and episode metadata.
  - Local filesystem for source media, generated outputs, subtitles, logs, config, and database files.
 - Data entering the system:
  - Media container and stream metadata from source files.
  - Regex patterns and per-show normalization rules entered in the TUI.
  - Optional config values from `~/.local/etc/ffx.json`.
  - Optional TMDB identifiers and CLI overrides.
  - Optional external subtitle files.
 - Data leaving the system:
  - Normalized output media files.
  - Extracted stream files from unmux operations.
  - SQLite rows representing shows, patterns, tracks, tags, shifted seasons, and properties.
  - Local log output and console messages.
 ## High-Level Building Blocks
 - Frontend, CLI, API, or worker:
  - A Click-based CLI in [`src/ffx/ffx.py`](/home/osgw/.local/src/codex/ffx/src/ffx/ffx.py).
  - A Textual terminal UI rooted in [`src/ffx/ffx_app.py`](/home/osgw/.local/src/codex/ffx/src/ffx/ffx_app.py) with screens for shows, patterns, file inspection, tracks, tags, and shifted seasons.
 - Core business logic:
  - Descriptor objects model media files, shows, and tracks.
  - Controllers encapsulate CRUD operations and workflow orchestration for shows, patterns, tags, tracks, season shifts, configuration, and conversion.
  - `MediaDescriptorChangeSet` computes differences between a file and its stored target schema to drive metadata and disposition updates.
 - Storage:
  - SQLite via SQLAlchemy ORM, with schema rooted in shows, patterns, tracks, media tags, track tags, shifted seasons, and generic properties.
  - A configuration JSON file supplies optional path, metadata-filtering, and filename-template settings.
 - Integration adapters:
  - Process execution wrapper for `ffmpeg`, `ffprobe`, `nice`, and `cpulimit`.
  - HTTP adapter for TMDB via `requests`.
 ## Data And Interface Notes
 - Key entities or records:
  - `Show`: canonical TV show metadata plus digit-formatting rules for generated filenames.
  - `Pattern`: regex rule tying filenames to one show and one target media schema.
  - `Track` and `TrackTag`: persisted target stream layout, codec, dispositions, audio layout, and stream-level tags.
  - `MediaTag`: persisted container-level metadata for a pattern.
  - `ShiftedSeason`: mapping from source numbering ranges to adjusted season and episode numbers.
  - `Property`: internal key-value storage currently used for database versioning.
 - External interfaces:
  - CLI commands for conversion, inspection, extraction, and crop detection.
  - TUI workflows for rule authoring and rule maintenance.
  - Environment variable `TMDB_API_KEY` for TMDB access.
  - Config keys `databasePath`, `logDirectory`, and `outputFilenameTemplate`, plus optional metadata-filter rules.
 - Validation rules:
  - Only supported media-file extensions are accepted for conversion.
  - Stored database version must match the runtime-required version.
  - A normalized descriptor may have at most one default and one forced stream per relevant track type.
  - Stored target tracks must refer to valid source tracks of matching types.
  - Shifted-season ranges are intended not to overlap for the same show and season.
  - TMDB lookups require a show ID and season and episode numbers.
 - Error-handling approach:
  - User-facing operational failures are raised as `click.ClickException` or warnings.
  - Ambiguous default and forced stream states trigger prompts unless `--no-prompt` is set, in which case the command fails fast.
  - External-process failures and invalid media are surfaced through logs and command errors rather than retries, except for TMDB rate-limit retries.
 ## Deployment And Operations
 - Runtime environment:
  - Local Python environment with the package installed and `ffmpeg`, `ffprobe`, `nice`, and `cpulimit` available on `PATH`.
 - Deployment shape:
  - Single-process command execution on demand; no daemon, queue, or network service of its own.
 - Secrets and configuration handling:
  - TMDB secret is read from `TMDB_API_KEY`.
  - User config is read from `~/.local/etc/ffx.json`.
  - Database path may also be overridden per command via `--database-file`.
 - Logging and monitoring approach:
  - File and console logging configured per invocation.
  - Default log file path is `~/.local/var/log/ffx.log`.
  - No dedicated monitoring integration is present.
 ## Open Technical Questions
 - Question: Should Linux-specific assumptions such as `/dev/null`, `nice`, `cpulimit`, and `~/.local` remain part of the supported-platform contract?
 - Risk: Portability and operational behavior are underspecified for non-Linux environments.
 - Next decision needed: Either document Linux-like systems as the official support boundary or refactor the process and path handling for broader portability.
 - Question: Should placeholder TUI surfaces such as settings and help become part of the required product surface or stay explicitly out of scope?
 - Risk: The UI appears broader than the actually finished feature set.
 - Next decision needed: Either remove or complete placeholder screens and update requirements accordingly.
--- a/requirements/project.md
+++ b/requirements/project.md
@@ -1,101 +0,0 @@
 ## Purpose And Scope
 - Project name: FFX
 - User problem: TV episode files from mixed sources arrive with inconsistent codecs, stream metadata, subtitle layouts, season and episode numbering, and output filenames, which makes them awkward to archive and use in media-player applications.
 - Target users: Individual operators curating a local TV media library on a workstation, especially users willing to define normalization rules per show.
 - Success outcome: A user can inspect source files, define reusable show and pattern rules, and produce output files whose streams, metadata, and filenames follow a predictable schema for web playback and library import.
 - Out of scope:
  - Multi-user or hosted service workflows.
  - General movie-library management.
  - Distributed transcoding or remote job orchestration.
  - Broad media-server administration beyond file preparation.
 ## Required Product
 - Deliverable type: Installable Python command-line application with a Textual terminal UI for inspection and rule editing.
 - Core capabilities:
  - Maintain an SQLite-backed database of shows, filename-matching patterns, per-pattern stream layouts and metadata tags, and optional season-shift rules.
  - Inspect existing media files through `ffprobe` and compare discovered stream metadata with stored normalization rules.
  - Convert media files through `ffmpeg` into a normalized output layout, including video recoding, audio transcoding to Opus, metadata cleanup and rewrite, and controlled disposition flags.
  - Build output filenames from detected or configured show, season, and episode information, optionally enriched from TMDB and a configurable Jinja-style filename template.
  - Support auxiliary file operations such as subtitle import, unmuxing, crop detection, and rename-only runs.
 - Supported environments:
  - Local execution on a Python-capable workstation.
  - Best-supported on Linux-like systems because the implementation assumes `~/.local`, `/dev/null`, `nice`, and `cpulimit`.
  - Requires `ffmpeg`, `ffprobe`, and `cpulimit` on `PATH`.
 - Operational owner: The local user running the tool and maintaining its config, database, and external tooling.
 ## Suggested User Stories
 - As a library maintainer, I want to define show-specific matching rules once so that future source files can be normalized automatically.
 - As an operator, I want to inspect a file before conversion so that I can compare its actual streams and tags against the stored target schema.
 - As a user preparing web-playback files, I want to recode video and audio with a small set of predictable options so that results are compatible and consistently named.
 - As a user dealing with nonstandard releases, I want CLI overrides for language, title, stream order, default and forced tracks, and season and episode data so that one-off fixes do not require database edits first.
 - As a user importing anime or other shifted numbering schemes, I want season and episode offsets per show so that generated filenames align with TMDB and media-library expectations.
 ## Functional Requirements
 - The system shall provide a CLI entrypoint named `ffx` with commands for `convert`, `inspect`, `shows`, `unmux`, `cropdetect`, `version`, and `help`.
 - The system shall persist reusable normalization rules in SQLite for:
  - shows and show formatting digits,
  - regex-based filename patterns,
  - per-pattern media tags,
  - per-pattern stream definitions,
  - shifted-season mappings,
  - internal database version properties.
 - The system shall inspect source media using `ffprobe` and derive a structured description of container metadata and streams.
 - The system shall optionally open a Textual UI to browse shows, inspect files, and create, edit, or delete shows, patterns, stream definitions, tags, and shifted-season rules.
 - The system shall match filenames against stored regex patterns to decide whether an input file should inherit a target stream and metadata schema.
 - The system shall convert supported input files (`mkv`, `mp4`, `avi`, `flv`, `webm`) with `ffmpeg`, supporting at least:
  - VP9, AV1, and H.264 video encoding,
  - Opus audio encoding with bitrate selection based on channel layout,
  - metadata and disposition rewriting,
  - optional crop detection and crop application,
  - optional deinterlacing and denoising,
  - optional subtitle import from external files,
  - rename-only copy mode.
 - The system shall support optional TMDB lookups to resolve show names, years, and episode titles when a show ID, season, and episode are available.
 - The system shall generate output filenames from show metadata, season and episode indices, and episode names using the configured filename template.
 - The system shall allow CLI overrides for stream languages, stream titles, default and forced tracks, stream order, TMDB show and episode data, output directory, label prefix, and processing resource limits.
 - The system shall support extracting streams into separate files via `unmux` and reporting suggested crop parameters via `cropdetect`.
 - The system shall handle invalid input and system failures gracefully by logging warnings or raising `click` errors for missing files, invalid media, missing TMDB credentials, incompatible database versions, and ambiguous track dispositions when prompting is disabled.
 ## Quality Requirements
 - The system should stay understandable as a small local tool: controllers, descriptors, models, and screens should remain separate enough for contributors to trace a workflow end to end.
 - The system should produce predictable output for the same database rules, CLI overrides, and source files.
 - The system should preserve a lightweight operational footprint: local SQLite state, local log file, no mandatory background services.
 - The system should be testable through the existing combinatorial CLI-oriented test harness and through isolated logic in descriptors and controllers.
 - The system should expose enough logging to diagnose failed probes, failed conversions, and rule mismatches without requiring a debugger.
 ## Constraints And Assumptions
 - Technology constraints:
  - Python package built with setuptools.
  - Primary libraries: `click`, `textual`, `sqlalchemy`, `jinja2`, `requests`.
  - Conversion and inspection rely on external executables rather than pure-Python media libraries.
 - Hosting or infrastructure constraints:
  - Intended for local execution, not server deployment.
  - Stores default state in `~/.local/etc/ffx.json`, `~/.local/var/ffx/ffx.db`, and `~/.local/var/log/ffx.log`.
 - Timeline constraints:
  - The current implemented scope reflects a compact alpha release stream up to version `0.2.3`.
 - Team capacity assumptions:
  - Maintained as a small codebase where simple patterns and direct controller logic are preferred over framework-heavy abstractions.
 - Third-party dependencies:
  - `ffmpeg`, `ffprobe`, and `cpulimit`.
  - TMDB API access through `TMDB_API_KEY` for metadata enrichment.
 ## Acceptance Scope
 - First release boundary:
  - Local installation through `pip`.
  - Working SQLite-backed rule storage.
  - Functional CLI conversion and inspection workflows.
  - Textual CRUD flows for shows, patterns, tags, tracks, and shifted seasons.
  - TMDB-assisted filename generation, subtitle import, season shifting, database versioning, and configurable output filename templating.
 - Excluded follow-up ideas:
  - Completing placeholder screens such as settings and help.
  - Hardening platform portability beyond Linux-like systems.
  - Broader media types, richer release packaging, and production-grade background processing.
 - Demonstration scenario:
  - Inspect a TV episode file, define or update the matching show and pattern in the TUI, then run `ffx convert` so the result uses the stored stream schema, optional TMDB episode naming, and a normalized output filename.
--- a/src/ffx/ffx.py
+++ b/src/ffx/ffx.py
@@ -150,7 +150,7 @@ def setup_dependencies(ctx, check, prepare_args):
@ffx.command(name='upgrade')
@click.pass_context
-@click.argument('branch', required=False, default='main')
+@click.option('--branch', type=str, default='', help='Checkout this branch before pulling')
 def upgrade(ctx, branch):
    bundleRepoPath = getBundleRepoPath()
    bundlePipPath = getBundlePipPath()
@@ -161,8 +161,12 @@ def upgrade(ctx, branch):
    if not os.path.isfile(bundlePipPath):
        raise click.ClickException(f"Bundle pip not found at {bundlePipPath}")
-    commandSequences = [
+    commandSequences = []
-        ['git', 'checkout', branch],
+
    if branch:
        commandSequences.append(['git', 'checkout', branch])
    commandSequences += [
        ['git', 'pull'],
        [bundlePipPath, 'install', '--editable', '.'],
    ]
Author	SHA1	Message	Date
Javanaut	381a62046b	nightly	2026-04-09 01:04:47 +02:00
Javanaut	52724ecc5b	ff	2026-04-09 01:03:41 +02:00