feat: Set File Date to First Aired Date

app/api/session.py

@@ -24,6 +24,10 @@ class SelectedFilesReorderRequest(BaseModel):
     to_index: int = Field(ge=0)
 
 
+class SessionSettingsRequest(BaseModel):
+    set_file_date_to_first_aired_date: bool
+
+
 def _normalize_session_id(session_id: str) -> str:
     normalized = session_id.strip()
     if not normalized:
@@ -139,6 +143,22 @@ def reorder_selected_files(
     return {"session_id": normalized_session_id, "items": items}
 
 
+@router.get("/settings")
+def get_session_settings():
+    service = SessionService()
+    return {"settings": service.get_settings()}
+
+
+@router.put("/settings")
+def put_session_settings(payload: SessionSettingsRequest):
+    service = SessionService()
+    try:
+        settings = service.update_settings(payload.model_dump())
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return {"settings": settings}
+
+
 @router.get("/mapping-preview")
 def get_mapping_preview(session_id: str = Query("default", min_length=1)):
     service = SessionService()

app/services/session_service.py

@@ -10,6 +10,8 @@ from app.config import APP_DATA_DIR
 
 
 class SessionService:
+    FILE_DATE_SETTING_KEY = "set_file_date_to_first_aired_date"
+
     def __init__(self) -> None:
         self._db_path = Path(APP_DATA_DIR) / "session_state.sqlite3"
         self._db_path.parent.mkdir(parents=True, exist_ok=True)
@@ -110,6 +112,53 @@ class SessionService:
                 ON rename_run_items(run_id, item_index)
                 """
             )
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS app_settings (
+                    key TEXT PRIMARY KEY,
+                    value TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )
+                """
+            )
+
+    def get_settings(self) -> dict:
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT key, value
+                FROM app_settings
+                """
+            ).fetchall()
+
+        values = {str(row["key"]): str(row["value"]) for row in rows}
+        return {
+            self.FILE_DATE_SETTING_KEY: values.get(self.FILE_DATE_SETTING_KEY, "0") == "1",
+        }
+
+    def update_settings(self, settings: dict) -> dict:
+        if self.FILE_DATE_SETTING_KEY not in settings:
+            raise ValueError(f"missing required setting: {self.FILE_DATE_SETTING_KEY}")
+        setting_value = settings[self.FILE_DATE_SETTING_KEY]
+        if not isinstance(setting_value, bool):
+            raise ValueError(f"{self.FILE_DATE_SETTING_KEY} must be boolean")
+
+        stored_value = "1" if setting_value else "0"
+        updated_at = datetime.now(timezone.utc).isoformat()
+
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO app_settings (key, value, updated_at)
+                VALUES (?, ?, ?)
+                ON CONFLICT(key) DO UPDATE SET
+                    value = excluded.value,
+                    updated_at = excluded.updated_at
+                """,
+                (self.FILE_DATE_SETTING_KEY, stored_value, updated_at),
+            )
+
+        return self.get_settings()
 
     def list_selected_episodes(self, session_id: str) -> list[dict]:
         with self._connect() as conn:
@@ -467,9 +516,15 @@ class SessionService:
 
         started_at = time.perf_counter()
         preview = self.build_filename_preview(session_id)
+        settings = self.get_settings()
+        set_file_date_to_first_aired = bool(settings.get(self.FILE_DATE_SETTING_KEY, False))
         allowed_roots = self._allowed_media_roots()
         preflight_items = []
         preflight_errors = 0
+        aired_by_index = {}
+
+        for preview_item in preview["items"]:
+            aired_by_index[int(preview_item["index"])] = preview_item["episode"].get("aired")
 
         for item in preview["items"]:
             source_path_str = str(item["file"].get("path") or "").strip()
@@ -499,6 +554,8 @@ class SessionService:
                     "proposed_filename": proposed_filename,
                     "status": status,
                     "errors": errors,
+                    "file_date_status": "file_date_skipped",
+                    "file_date_detail": "rename not executed due to preflight failure",
                 }
             )
 
@@ -523,11 +580,19 @@ class SessionService:
             source_path = Path(item["source_path"])
             destination_path = Path(item["destination_path"])
             os.replace(str(source_path), str(destination_path))
+
+            file_date_status, file_date_detail = self._apply_file_date_after_rename(
+                enabled=set_file_date_to_first_aired,
+                aired_value=aired_by_index.get(int(item["index"])),
+                destination_path=destination_path,
+            )
             results.append(
                 {
                     **item,
                     "status": "renamed",
                     "errors": [],
+                    "file_date_status": file_date_status,
+                    "file_date_detail": file_date_detail,
                 }
             )
 
@@ -546,6 +611,49 @@ class SessionService:
         )
         return result
 
+    def _apply_file_date_after_rename(
+        self,
+        enabled: bool,
+        aired_value,
+        destination_path: Path,
+    ) -> tuple[str, str]:
+        if not enabled:
+            return ("file_date_skipped", "setting disabled")
+
+        ts = self._aired_to_local_noon_timestamp(aired_value)
+        if ts is None:
+            return ("file_date_skipped", "aired date missing or invalid")
+
+        try:
+            os.utime(destination_path, (ts, ts))
+            return ("file_date_updated", "mtime+atime set to aired date at 12:00 local time")
+        except Exception as exc:
+            return ("file_date_error", str(exc))
+
+    def _aired_to_local_noon_timestamp(self, aired_value) -> float | None:
+        if aired_value is None:
+            return None
+
+        text = str(aired_value).strip()
+        if not text:
+            return None
+        date_text = text[:10]
+
+        try:
+            date_part = datetime.strptime(date_text, "%Y-%m-%d")
+        except ValueError:
+            return None
+
+        local_noon = datetime(
+            date_part.year,
+            date_part.month,
+            date_part.day,
+            12,
+            0,
+            0,
+        )
+        return local_noon.timestamp()
+
     def _log_rename_run(self, session_id: str, result: dict, duration_ms: int) -> None:
         created_at = datetime.now(timezone.utc).isoformat()
         counts = result.get("counts", {})

app/static/app.js

@@ -14,6 +14,9 @@
     modalFiles: [],
     modalSelectedFilePaths: new Set(),
     syncScrolling: false,
+    settings: {
+      set_file_date_to_first_aired_date: false,
+    },
   };
 
   const el = {
@@ -30,6 +33,11 @@
     seriesStatus: document.getElementById("seriesStatus"),
     seriesOverview: document.getElementById("seriesOverview"),
     seriesTvdbLink: document.getElementById("seriesTvdbLink"),
+    settingsBtn: document.getElementById("settingsBtn"),
+    settingsModal: document.getElementById("settingsModal"),
+    closeSettingsModalBtn: document.getElementById("closeSettingsModalBtn"),
+    saveSettingsBtn: document.getElementById("saveSettingsBtn"),
+    setFileDateToFirstAiredDateInput: document.getElementById("setFileDateToFirstAiredDateInput"),
     refreshEpisodesBtn: document.getElementById("refreshEpisodesBtn"),
     episodesList: document.getElementById("episodesList"),
     episodeMeta: document.getElementById("episodeMeta"),
@@ -199,6 +207,42 @@
     el.fileMeta.innerHTML = `Rows: <b>${fileCount}</b> <span class="${mismatch ? "mismatch" : ""}">${mismatchText}</span>`;
   }
 
+  function applySettingsToForm() {
+    el.setFileDateToFirstAiredDateInput.checked = !!state.settings.set_file_date_to_first_aired_date;
+  }
+
+  function openSettingsModal() {
+    applySettingsToForm();
+    el.settingsModal.classList.remove("hidden");
+    el.settingsModal.setAttribute("aria-hidden", "false");
+  }
+
+  function closeSettingsModal() {
+    el.settingsModal.classList.add("hidden");
+    el.settingsModal.setAttribute("aria-hidden", "true");
+  }
+
+  async function loadSettings() {
+    const data = await api("/api/session/settings");
+    state.settings = data.settings || { set_file_date_to_first_aired_date: false };
+    applySettingsToForm();
+  }
+
+  async function saveSettings() {
+    const payload = {
+      set_file_date_to_first_aired_date: !!el.setFileDateToFirstAiredDateInput.checked,
+    };
+    const data = await api("/api/session/settings", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    state.settings = data.settings || payload;
+    applySettingsToForm();
+    closeSettingsModal();
+    out("Settings saved", data);
+  }
+
   function selectPair(index) {
     state.selectedPairIndex = index;
     renderSelectedEpisodes();
@@ -557,6 +601,12 @@
 
   function bindEvents() {
     el.searchBtn.addEventListener("click", () => withHandler(doSearch, el.searchBtn));
+    el.settingsBtn.addEventListener("click", openSettingsModal);
+    el.closeSettingsModalBtn.addEventListener("click", closeSettingsModal);
+    el.saveSettingsBtn.addEventListener("click", () => withHandler(saveSettings, el.saveSettingsBtn));
+    el.settingsModal.addEventListener("click", (e) => {
+      if (e.target === el.settingsModal) closeSettingsModal();
+    });
     el.refreshEpisodesBtn.addEventListener("click", () => withHandler(loadEpisodes, el.refreshEpisodesBtn));
 
     el.refreshSelectedEpisodesBtn.addEventListener("click", () => withHandler(loadSelectedEpisodes, el.refreshSelectedEpisodesBtn));
@@ -611,6 +661,7 @@
     el.modalRecursiveInput.checked = true;
     renderSelectedSeriesDetails();
     bindEvents();
+    await loadSettings();
     await loadSelectedEpisodes();
     await loadSelectedFiles();
     await loadRoots();

app/static/styles.css

@@ -63,6 +63,11 @@ body {
   overflow: hidden;
 }
 
+#panelSearch .panel-body {
+  flex: 1;
+  min-height: 0;
+}
+
 .panel h2 {
   margin: 0 0 10px;
   font-size: 16px;
@@ -223,6 +228,10 @@ button.secondary {
   min-height: 40px;
 }
 
+.panel-search-footer {
+  justify-content: flex-end;
+}
+
 .mismatch {
   color: #b91c1c;
   font-weight: 700;
@@ -265,6 +274,29 @@ button.secondary {
   max-height: 280px;
 }
 
+.settings-card {
+  width: min(520px, 94vw);
+}
+
+.settings-section h4 {
+  margin: 0 0 8px;
+  font-size: 14px;
+  color: #1e293b;
+}
+
+.settings-check {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+  color: #334155;
+}
+
+.settings-actions {
+  justify-content: flex-end;
+  margin-top: 12px;
+}
+
 #panelSelectedEpisodes .panel-footer button:first-child,
 #panelSelectedEpisodes .panel-footer button:last-child,
 #panelSelectedFiles .panel-footer button:first-child,

app/templates/index.html

@@ -15,6 +15,7 @@
     <main class="grid">
       <section class="panel" id="panelSearch">
         <h2>1. TV Shows</h2>
+        <div class="panel-body">
           <div class="row">
             <input id="searchInput" type="text" placeholder="Search series..." />
             <button id="searchBtn">Search</button>
@@ -33,6 +34,10 @@
             <p id="seriesOverview" class="series-overview"></p>
             <a id="seriesTvdbLink" class="series-link" href="#" target="_blank" rel="noopener noreferrer">Open TVDB page</a>
           </div>
+        </div>
+        <div class="panel-footer panel-search-footer">
+          <button id="settingsBtn" class="secondary">Settings</button>
+        </div>
       </section>
 
       <section class="panel" id="panelEpisodes">
@@ -131,6 +136,25 @@
       </div>
     </div>
 
+    <div id="settingsModal" class="modal hidden" aria-hidden="true">
+      <div class="modal-card settings-card">
+        <div class="row modal-head">
+          <h3>Settings</h3>
+          <button id="closeSettingsModalBtn" class="secondary">Close</button>
+        </div>
+        <section class="settings-section">
+          <h4>Renaming Rules</h4>
+          <label class="settings-check">
+            <input id="setFileDateToFirstAiredDateInput" type="checkbox" />
+            Set File Date to First Aired Date
+          </label>
+        </section>
+        <div class="row settings-actions">
+          <button id="saveSettingsBtn">Save Settings</button>
+        </div>
+      </div>
+    </div>
+
     <script src="/static/app.js"></script>
   </body>
 </html>

feature_tests_settings.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${BASE_URL:-}" ]; then
+  if curl --silent --fail http://127.0.0.1:8085/api/health >/dev/null 2>&1; then
+    BASE_URL="http://127.0.0.1:8085"
+  elif curl --silent --fail http://host.containers.internal:8085/api/health >/dev/null 2>&1; then
+    BASE_URL="http://host.containers.internal:8085"
+  else
+    echo "ERROR: could not determine BASE_URL. Tried 127.0.0.1 and host.containers.internal." >&2
+    exit 1
+  fi
+fi
+
+if [ -z "${TEST_MEDIA_ROOT:-}" ]; then
+  for candidate in \
+    "/Volumes/8TB/Shared_Folders/TV_Shows" \
+    "/Volumes/8TB_RAID1/Shared_Folders/Library/TV_Shows"
+  do
+    if [ -d "$candidate" ] && [ -w "$candidate" ]; then
+      TEST_MEDIA_ROOT="$candidate"
+      break
+    fi
+  done
+fi
+
+if [ -z "${TEST_MEDIA_ROOT:-}" ]; then
+  echo "ERROR: no writable allowed media root found. Set TEST_MEDIA_ROOT." >&2
+  exit 1
+fi
+
+TMP_DIR="$(mktemp -d)"
+TEST_DIR="${TEST_MEDIA_ROOT}/_rename_mvp_settings_$(date +%s)_$$"
+mkdir -p "${TEST_DIR}"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+SESSION_ID="settings-rename-$(date +%s)-$$"
+
+clear_session() {
+  local sid="$1"
+  curl --fail --silent --show-error -X DELETE \
+    "${BASE_URL}/api/session/selected-episodes?session_id=${sid}" \
+    >/dev/null
+  curl --fail --silent --show-error -X DELETE \
+    "${BASE_URL}/api/session/selected-files?session_id=${sid}" \
+    >/dev/null
+}
+
+echo "== Feature test 1: settings endpoint returns expected key =="
+curl --fail --silent --show-error \
+  "${BASE_URL}/api/session/settings" \
+  -o "${TMP_DIR}/settings_get.json"
+
+cat "${TMP_DIR}/settings_get.json"
+
+python3 - "${TMP_DIR}/settings_get.json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+settings = data.get("settings")
+assert isinstance(settings, dict), "settings must be object"
+assert "set_file_date_to_first_aired_date" in settings, "missing setting key"
+assert isinstance(settings["set_file_date_to_first_aired_date"], bool), "setting must be boolean"
+print("settings GET validation passed")
+PY
+
+echo
+echo "== Feature test 2: settings update persists round-trip =="
+cat > "${TMP_DIR}/settings_put_true.json" <<'JSON'
+{
+  "set_file_date_to_first_aired_date": true
+}
+JSON
+
+curl --fail --silent --show-error \
+  -X PUT "${BASE_URL}/api/session/settings" \
+  -H "Content-Type: application/json" \
+  --data @"${TMP_DIR}/settings_put_true.json" \
+  -o "${TMP_DIR}/settings_put_resp.json"
+
+curl --fail --silent --show-error \
+  "${BASE_URL}/api/session/settings" \
+  -o "${TMP_DIR}/settings_get_after_put.json"
+
+cat "${TMP_DIR}/settings_get_after_put.json"
+
+python3 - "${TMP_DIR}/settings_put_resp.json" "${TMP_DIR}/settings_get_after_put.json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+put_data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+get_data = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
+assert put_data["settings"]["set_file_date_to_first_aired_date"] is True, "PUT should return true"
+assert get_data["settings"]["set_file_date_to_first_aired_date"] is True, "GET after PUT should be true"
+print("settings PUT/GET round-trip passed")
+PY
+
+echo
+echo "== Feature test 3: rename execute updates file date to aired date (12:00 local) =="
+clear_session "${SESSION_ID}"
+
+SRC="${TEST_DIR}/source_settings_test.mkv"
+printf "settings-test" > "${SRC}"
+
+cat > "${TMP_DIR}/episodes.json" <<'JSON'
+{
+  "items": [
+    {
+      "id": 101,
+      "series": "Elsbeth",
+      "year": "2024",
+      "season_number": 1,
+      "episode_number": 3,
+      "title": "Settings Date Test",
+      "aired": "2024-03-15"
+    }
+  ]
+}
+JSON
+
+cat > "${TMP_DIR}/files.json" <<JSON
+{
+  "items": [
+    {
+      "path": "${SRC}",
+      "name": "$(basename "${SRC}")"
+    }
+  ]
+}
+JSON
+
+curl --fail --silent --show-error \
+  -X POST "${BASE_URL}/api/session/selected-episodes?session_id=${SESSION_ID}" \
+  -H "Content-Type: application/json" \
+  --data @"${TMP_DIR}/episodes.json" \
+  >/dev/null
+
+curl --fail --silent --show-error \
+  -X POST "${BASE_URL}/api/session/selected-files?session_id=${SESSION_ID}" \
+  -H "Content-Type: application/json" \
+  --data @"${TMP_DIR}/files.json" \
+  >/dev/null
+
+curl --fail --silent --show-error \
+  -X POST "${BASE_URL}/api/session/rename-execute?session_id=${SESSION_ID}&confirm=true" \
+  -o "${TMP_DIR}/rename_exec.json"
+
+cat "${TMP_DIR}/rename_exec.json"
+
+python3 - "${TMP_DIR}/rename_exec.json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+assert data.get("executed") is True, "rename should execute"
+assert data.get("preflight_ok") is True, "preflight should pass"
+items = data.get("items") or []
+assert len(items) == 1, "expected 1 item"
+item = items[0]
+assert item.get("status") == "renamed", "item status must be renamed"
+assert item.get("file_date_status") == "file_date_updated", "file_date_status should be updated"
+print("rename response settings validation passed")
+PY
+
+DST="${TEST_DIR}/Elsbeth (2024) - S01E03 - Settings Date Test.mkv"
+test -f "${DST}"
+
+python3 - "${DST}" <<'PY'
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+dst = Path(sys.argv[1])
+st = dst.stat()
+expected = datetime(2024, 3, 15, 12, 0, 0).timestamp()
+delta = abs(st.st_mtime - expected)
+assert delta < 2.5, f"mtime delta too large: {delta}"
+print("mtime validation passed")
+PY
+
+# Reset setting back to false to keep environment stable for subsequent runs.
+cat > "${TMP_DIR}/settings_put_false.json" <<'JSON'
+{
+  "set_file_date_to_first_aired_date": false
+}
+JSON
+curl --fail --silent --show-error \
+  -X PUT "${BASE_URL}/api/session/settings" \
+  -H "Content-Type: application/json" \
+  --data @"${TMP_DIR}/settings_put_false.json" \
+  >/dev/null
+
+echo
+echo "All settings feature tests passed."