feat(fts): Add comprehensive Full Text Search management to CWA Settings

Implemented advanced FTS control interface in CWA Settings page with real-time
status monitoring, replacing basic checkbox in Basic Configuration with full
management capabilities including progress tracking and resource information.

Backend Changes (cps/cwa_functions.py):
- Added /fts-status GET route: Returns JSON with enabled/indexed/total/percentage/
  available/active status, polling-friendly
- Added /fts-action POST route: Handles enable/disable/reindex actions with proper
  subprocess confirmation handling
- Added _get_fts_status_from_calibredb(): Parses calibredb output, handles both
  exit code 0 (enabled) and 2 (disabled) as valid responses
- Added _initialize_fts_index(): Enable/disable FTS with validation, checks actual
  status before skipping enable when database exists
- Fixed duplicate_auto_resolve_cooldown_minutes handling: Added validation (0-1440),
  default value (0), and fallback logic in integer settings processing

Frontend Changes (cps/templates/cwa_settings.html):
- New FTS Management section with live status display showing current state
  (Active/Not Available/Disabled/Error) with emoji indicators
- Progress tracking: "X of Y books indexed (Z%)" with 90% threshold for availability
- Action buttons: Enable/Disable/Reindex/Refresh with proper state management
- JavaScript polling: 10-second intervals with visibility detection, stops during actions
- Network share warning: Static info box about slower indexing on NFS/SMB
- Disable behavior warning: Prominent alert that disabling requires complete re-indexing
  (Calibre design limitation)
- Collapsible resource info: Details on CPU/disk/memory usage, performance characteristics,
  large library considerations

Configuration Page Updates (cps/templates/config_edit.html):
- Added tooltip to FTS checkbox: "Manage FTS indexing in CWA Settings for advanced options"
- Added link to CWA Settings page for full management interface

Bug Fixes:
- Fixed Jinja2 translation errors: Removed colons from {{_()}} calls, escaped %% symbols
- Added @csrf.exempt to /fts-action route for AJAX POST requests
- Fixed calibredb subprocess confirmations:
  * disable command requires input='disable\n'
  * reindex command requires input='reindex\n'
- Fixed status parsing to handle "FTS Indexing is disabled" output (no book counts)
- Fixed duplicate_auto_resolve_cooldown_minutes displaying "False" instead of number
- Fixed enable command check to verify actual status when database exists but disabled

Technical Details:
- Exit codes: calibredb returns 0 when enabled, 2 when disabled (both valid)
- Status outputs: "X of Y books files indexed" (enabled) vs "FTS Indexing is disabled"
- 90% threshold: Search only activates when ≥90% of library indexed
- Active detection: Compares two sequential status checks to detect ongoing indexing
- Environment: All calibredb commands use LD_LIBRARY_PATH=/app/calibre/lib

Known Calibre Limitations:
- Disabling FTS invalidates the index, requiring full re-indexing on re-enable
  (this is Calibre's design for index consistency, not a CWA bug)
- No pause/resume functionality available in calibredb fts_index commands

Author: crocodilestick

CONTRIBUTORS

@@ -11,8 +11,8 @@ Copyright (C) 2018-2026 Calibre-Web contributors
 Copyright (C) 2024-2026 Calibre-Web Automated contributors
 # Upstream Contributors (janeczku/calibre-web)
 
-- OzzieIsaacs (anon) (2788 commits)
-- Ozzie Isaacs (anon) (267 commits)
+- OzzieIsaacs (anon) (2794 commits)
+- Ozzie Isaacs (anon) (269 commits)
 - cbartondock (96 commits)
 - idalin (69 commits)
 - cervinko (68 commits)
@@ -238,6 +238,7 @@ Copyright (C) 2024-2026 Calibre-Web Automated contributors
 - kianmeng (1 commits)
 - knobunc (1 commits)
 - Kreeblah (1 commits)
+- Kugeleis (1 commits)
 - L0garithmic (1 commits)
 - LawssssCat (1 commits)
 - lb803 (1 commits)
@@ -314,7 +315,7 @@ Copyright (C) 2024-2026 Calibre-Web Automated contributors
 - zhiyue (1 commits)
 # Fork Contributors (crocodilestick/calibre-web-automated)
 
-- crocodilestick (948 commits)
+- crocodilestick (953 commits)
 - jmarmstrong1207 (73 commits)
 - demitrix (30 commits)
 - sirwolfgang (29 commits)

Dockerfile

@@ -284,8 +284,9 @@ RUN \
 # Add unrar from unrar stage
 COPY --from=unrar /usr/bin/unrar-ubuntu /usr/bin/unrar
 
-# Set calibre environment variable
+# Set calibre environment variables
 ENV CALIBRE_CONFIG_DIR=/config/.config/calibre
+ENV LD_LIBRARY_PATH=/app/calibre/lib
 
 # Ports and volumes
 WORKDIR /config

cps/admin.py

@@ -2164,6 +2164,7 @@ def _configuration_update_helper():
         _config_checkbox_int(to_save, "config_uploading")
         _config_checkbox_int(to_save, "config_unicode_filename")
         _config_checkbox_int(to_save, "config_embed_metadata")
+        _config_checkbox(to_save, "config_fulltext_search")
         # Reboot on config_anonbrowse with enabled ldap, as decoraters are changed in this case
         reboot_required |= (_config_checkbox_int(to_save, "config_anonbrowse")
                             and config.config_login_type == constants.LOGIN_LDAP)
@@ -2309,10 +2310,19 @@ def _configuration_update_helper():
         _configuration_result(_("Oops! Database Error: %(error)s.", error=e.orig))
 
     config.save()
+    
+    # Note: FTS initialization is now primarily managed via CWA Settings page
+    # This just provides basic validation
+    fts_warning = None
+    if config.config_fulltext_search and not config.config_calibre_dir:
+        fts_warning = _('Full Text Search enabled but no library path configured.')
+    
     if reboot_required:
         web_server.stop(True)
 
-    return _configuration_result(None, reboot_required, " ".join(filter(None, [unrar_warning, arch_warning])))
+    # Combine all warnings
+    combined_warnings = " ".join(filter(None, [unrar_warning, arch_warning, fts_warning]))
+    return _configuration_result(None, reboot_required, combined_warnings if combined_warnings else None)
 
 
 def _configuration_result(error_flash=None, reboot=False, warning_flash=None):

cps/config_sql.py

@@ -146,6 +146,7 @@ class _Settings(_Base):
     config_upload_formats = Column(String, default=','.join(constants.EXTENSIONS_UPLOAD))
     config_unicode_filename = Column(Boolean, default=False)
     config_embed_metadata = Column(Boolean, default=True)
+    config_fulltext_search = Column(Boolean, default=False)
 
     config_updatechannel = Column(Integer, default=constants.UPDATE_STABLE)
 

cps/cwa_functions.py

@@ -711,6 +711,8 @@ def set_cwa_settings():
                             int_value = max(500, min(50000, int_value))
                         elif setting == 'duplicate_scan_debounce_seconds':
                             int_value = max(5, min(600, int_value))
+                        elif setting == 'duplicate_auto_resolve_cooldown_minutes':
+                            int_value = max(0, min(1440, int_value))  # Clamp between 0 and 1440 minutes (24 hours)
                         result[setting] = int_value
                     except (ValueError, TypeError):
                         # Use current value if conversion fails
@@ -724,6 +726,8 @@ def set_cwa_settings():
                             result[setting] = cwa_db.cwa_settings.get(setting, 2)  # Default to 2 AM
                         elif setting == 'duplicate_scan_debounce_seconds':
                             result[setting] = cwa_db.cwa_settings.get(setting, 30)
+                        elif setting == 'duplicate_auto_resolve_cooldown_minutes':
+                            result[setting] = cwa_db.cwa_settings.get(setting, 0)  # Default to 0 (disabled)
                 else:
                     if setting == 'ingest_timeout_minutes':
                         result[setting] = cwa_db.cwa_settings.get(setting, 15)  # Default to 15 minutes
@@ -735,6 +739,8 @@ def set_cwa_settings():
                         result[setting] = cwa_db.cwa_settings.get(setting, 2)  # Default to 2 AM
                     elif setting == 'duplicate_scan_debounce_seconds':
                         result[setting] = cwa_db.cwa_settings.get(setting, 30)
+                    elif setting == 'duplicate_auto_resolve_cooldown_minutes':
+                        result[setting] = cwa_db.cwa_settings.get(setting, 0)  # Default to 0 (disabled)
 
             # Handle float settings
             for setting in float_settings:
@@ -2041,3 +2047,283 @@ def set_profile_picture():
     return render_title_template("profile_pictures.html", 
                                 title=_("CWA Profile Picture Management (WIP)"), 
                                 page="profile-picture")
+
+
+# ========================================
+# Full Text Search (FTS) Management
+# ========================================
+
+def _get_fts_status_from_calibredb():
+    """
+    Get FTS indexing status from calibredb.
+    Returns dict with: enabled, indexed, total, percentage, error
+    """
+    from .admin import get_calibre_binarypath
+    
+    result = {
+        'enabled': False,
+        'indexed': 0,
+        'total': 0,
+        'percentage': 0.0,
+        'error': None
+    }
+    
+    if not config.config_calibre_dir:
+        result['error'] = _('No library path configured')
+        return result
+    
+    calibredb_path = get_calibre_binarypath("calibredb")
+    if not calibredb_path or not os.path.isfile(calibredb_path):
+        result['error'] = _('calibredb not found')
+        return result
+    
+    try:
+        # Set up environment with LD_LIBRARY_PATH for Calibre libraries
+        env = os.environ.copy()
+        env['LD_LIBRARY_PATH'] = '/app/calibre/lib'
+        
+        # Run calibredb fts_index status
+        cmd = [calibredb_path, 'fts_index', 'status', '--library-path', config.config_calibre_dir]
+        proc_result = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=10,
+            env=env
+        )
+        
+        # Exit code 0 = enabled, exit code 2 = disabled (both are valid responses)
+        if proc_result.returncode in [0, 2]:
+            output = proc_result.stdout.strip()
+            
+            # Check if enabled or disabled
+            if 'disabled' in output.lower():
+                result['enabled'] = False
+                # When disabled, there are no books to count
+                result['indexed'] = 0
+                result['total'] = 0
+                result['percentage'] = 0.0
+                return result
+            elif 'enabled' in output.lower():
+                result['enabled'] = True
+            
+            # Parse "X of Y books" pattern
+            match = re.search(r'(\d+)\s+of\s+(\d+)\s+books', output)
+            if match:
+                result['indexed'] = int(match.group(1))
+                result['total'] = int(match.group(2))
+                if result['total'] > 0:
+                    result['percentage'] = (result['indexed'] / result['total']) * 100
+        else:
+            result['error'] = proc_result.stderr.strip() or _('Failed to get FTS status')
+            
+    except subprocess.TimeoutExpired:
+        result['error'] = _('Timeout while checking FTS status')
+    except Exception as ex:
+        result['error'] = str(ex)
+        log.error(f"Error getting FTS status: {ex}")
+    
+    return result
+
+
+def _initialize_fts_index():
+    """
+    Initialize or disable Full Text Search indexing based on config.
+    Returns a tuple of (success: bool, message: str or None)
+    """
+    from .admin import get_calibre_binarypath
+    
+    if not config.config_calibre_dir:
+        return False, _('No library path configured')
+    
+    fts_db_path = os.path.join(config.config_calibre_dir, "full-text-search.db")
+    
+    # If FTS disabled but database exists, disable indexing
+    if not config.config_fulltext_search and os.path.exists(fts_db_path):
+        try:
+            calibredb_path = get_calibre_binarypath("calibredb")
+            if not calibredb_path or not os.path.isfile(calibredb_path):
+                log.warning("calibredb not found, cannot disable FTS indexing")
+                return False, _('calibredb not available. Cannot stop FTS indexing.')
+            
+            env = os.environ.copy()
+            env['LD_LIBRARY_PATH'] = '/app/calibre/lib'
+            
+            cmd = [calibredb_path, 'fts_index', 'disable', '--library-path', config.config_calibre_dir]
+            log.info("Disabling FTS index: %s", ' '.join(cmd))
+            
+            result = subprocess.run(
+                cmd,
+                input='disable\n',  # Must type "disable" to confirm
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                timeout=30,
+                env=env
+            )
+            
+            if result.returncode == 0:
+                log.info("FTS indexing disabled successfully")
+                return True, _('Full Text Search indexing has been disabled and stopped.')
+            else:
+                log.error("Failed to disable FTS indexing: %s", result.stderr.strip())
+                return False, _('Failed to disable FTS indexing: %(error)s', error=result.stderr.strip())
+        except Exception as ex:
+            log.error("Failed to disable FTS indexing: %s", ex)
+            return False, _('Error disabling FTS indexing: %(error)s', error=str(ex))
+    
+    # If FTS not enabled, nothing to do
+    if not config.config_fulltext_search:
+        return True, None
+    
+    # Check if FTS database already exists AND is enabled
+    if os.path.exists(fts_db_path):
+        # Check current status to see if it's actually enabled
+        current_status = _get_fts_status_from_calibredb()
+        if current_status['enabled']:
+            log.debug("FTS database already exists and is enabled at %s", fts_db_path)
+            return True, None
+        # If disabled, fall through to enable it
+    
+    # Try to enable FTS indexing using calibredb
+    try:
+        calibredb_path = get_calibre_binarypath("calibredb")
+        if not calibredb_path or not os.path.isfile(calibredb_path):
+            log.warning("calibredb not found, cannot initialize FTS indexing")
+            return False, _('Full Text Search enabled but calibredb not available. FTS indexing cannot be initialized.')
+        
+        # Run calibredb fts_index enable
+        env = os.environ.copy()
+        env['LD_LIBRARY_PATH'] = '/app/calibre/lib'
+        
+        cmd = [calibredb_path, 'fts_index', 'enable', '--library-path', config.config_calibre_dir]
+        log.info("Initializing FTS index: %s", ' '.join(cmd))
+        
+        result = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=30,
+            env=env
+        )
+        
+        if result.returncode == 0:
+            log.info("FTS indexing enabled successfully: %s", result.stdout.strip())
+            return True, _('Full Text Search indexing enabled. Books are being indexed in the background.')
+        else:
+            log.error("Failed to enable FTS indexing: %s", result.stderr.strip())
+            return False, _('Failed to enable FTS indexing: %(error)s', error=result.stderr.strip())
+            
+    except Exception as ex:
+        log.error("Failed to initialize FTS indexing: %s", ex)
+        return False, _('Error initializing FTS indexing: %(error)s', error=str(ex))
+
+
+@cwa_settings.route('/fts-status', methods=['GET'])
+@login_required_if_no_ano
+@admin_required
+def get_fts_status():
+    """
+    Get current FTS indexing status.
+    Returns JSON with status information.
+    """
+    status = _get_fts_status_from_calibredb()
+    
+    # Determine if search is available (90% threshold)
+    status['available'] = status['enabled'] and status['percentage'] >= 90.0
+    
+    # Check if indexing is currently active by comparing two sequential checks
+    # If indexed count changes, indexing is active
+    if status['enabled'] and status['indexed'] < status['total']:
+        sleep(0.5)  # Brief pause
+        status2 = _get_fts_status_from_calibredb()
+        status['active'] = status2['indexed'] > status['indexed']
+    else:
+        status['active'] = False
+    
+    return jsonify(status)
+
+
+@cwa_settings.route('/fts-action', methods=['POST'])
+@csrf.exempt
+@login_required_if_no_ano
+@admin_required
+def fts_action():
+    """
+    Execute FTS actions: enable, disable, reindex.
+    Returns JSON with success status and message.
+    """
+    from .admin import get_calibre_binarypath
+    
+    action = request.form.get('action')
+    
+    if action not in ['enable', 'disable', 'reindex']:
+        return jsonify({'success': False, 'message': _('Invalid action')}), 400
+    
+    calibredb_path = get_calibre_binarypath("calibredb")
+    if not calibredb_path or not os.path.isfile(calibredb_path):
+        return jsonify({'success': False, 'message': _('calibredb not available')}), 500
+    
+    if not config.config_calibre_dir:
+        return jsonify({'success': False, 'message': _('No library path configured')}), 500
+    
+    try:
+        env = os.environ.copy()
+        env['LD_LIBRARY_PATH'] = '/app/calibre/lib'
+        
+        if action == 'enable':
+            # Update config
+            config.config_fulltext_search = True
+            config.save()
+            
+            # Initialize FTS
+            success, message = _initialize_fts_index()
+            if success:
+                return jsonify({'success': True, 'message': message or _('FTS indexing enabled successfully')})
+            else:
+                return jsonify({'success': False, 'message': message}), 500
+                
+        elif action == 'disable':
+            # Update config
+            try:
+                config.config_fulltext_search = False
+                config.save()
+                log.info("FTS config setting disabled and saved")
+            except Exception as save_ex:
+                log.error(f"Error saving config during FTS disable: {save_ex}")
+                return jsonify({'success': False, 'message': f'Failed to save config: {str(save_ex)}'}), 500
+            
+            # Disable FTS
+            success, message = _initialize_fts_index()
+            if success:
+                return jsonify({'success': True, 'message': message or _('FTS indexing disabled successfully')})
+            else:
+                return jsonify({'success': False, 'message': message}), 500
+                
+        elif action == 'reindex':
+            if not config.config_fulltext_search:
+                return jsonify({'success': False, 'message': _('FTS must be enabled before reindexing')}), 400
+            
+            cmd = [calibredb_path, 'fts_index', 'reindex', '--library-path', config.config_calibre_dir]
+            log.info("Reindexing FTS: %s", ' '.join(cmd))
+            
+            result = subprocess.run(
+                cmd,
+                input='reindex\n',  # Must type "reindex" to confirm
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                timeout=30,
+                env=env
+            )
+            
+            if result.returncode == 0:
+                return jsonify({'success': True, 'message': _('FTS reindexing started successfully')})
+            else:
+                return jsonify({'success': False, 'message': result.stderr.strip()}), 500
+                
+    except Exception as ex:
+        log.error(f"FTS action failed: {ex}")
+        return jsonify({'success': False, 'message': str(ex)}), 500