From 381a62046be84d6dcf41fff5756cc5f868ac1646 Mon Sep 17 00:00:00 2001 From: Javanaut Date: Thu, 9 Apr 2026 01:04:47 +0200 Subject: [PATCH] nightly --- AGENTS.md | 376 ------------------ SCRATCHPAD.md | 62 --- .../optional/lean-interface-iteration.md | 28 -- .../optional/preparation-script-design.md | 56 --- requirements/architecture.md | 97 ----- requirements/project.md | 101 ----- 6 files changed, 720 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 SCRATCHPAD.md delete mode 100644 guidance/workflow/optional/lean-interface-iteration.md delete mode 100644 guidance/workflow/optional/preparation-script-design.md delete mode 100644 requirements/architecture.md delete mode 100644 requirements/project.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 36a4081..0000000 --- a/AGENTS.md +++ /dev/null @@ -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 `` 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 `` 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-.md`, `ORDER-0002-.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. - - - - - - - - -# 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/`. - -4. Relevant modular guides in `guidance/stacks/`, `guidance/conventions/`, or `guidance/workflows/`. - -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 diff --git a/SCRATCHPAD.md b/SCRATCHPAD.md deleted file mode 100644 index 22431c8..0000000 --- a/SCRATCHPAD.md +++ /dev/null @@ -1,62 +0,0 @@ - diff --git a/guidance/workflow/optional/lean-interface-iteration.md b/guidance/workflow/optional/lean-interface-iteration.md deleted file mode 100644 index 5566022..0000000 --- a/guidance/workflow/optional/lean-interface-iteration.md +++ /dev/null @@ -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. diff --git a/guidance/workflow/optional/preparation-script-design.md b/guidance/workflow/optional/preparation-script-design.md deleted file mode 100644 index b36a791..0000000 --- a/guidance/workflow/optional/preparation-script-design.md +++ /dev/null @@ -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. diff --git a/requirements/architecture.md b/requirements/architecture.md deleted file mode 100644 index a31476c..0000000 --- a/requirements/architecture.md +++ /dev/null @@ -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. diff --git a/requirements/project.md b/requirements/project.md deleted file mode 100644 index 574b2a7..0000000 --- a/requirements/project.md +++ /dev/null @@ -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.