Medios-Macina/DEBUG_IMPROVEMENTS_SUMMARY.md

DEBUGGING IMPROVEMENTS IMPLEMENTED

1. ENHANCED ADD-FILE DEBUG LOGGING

   Now logs when cmdlet is executed:

   • INPUT result type (list, dict, PipeObject, None, etc.)
   • List length if applicable
   • First item details: title, hash (first 12 chars), store
   • Resolved source: path/URL, whether from Hydrus, hash value
   • Error details if resolution or validation fails

   Example output: [add-file] INPUT result type=list [add-file] INPUT result is list with 4 items [add-file] First item details: title=i ve been down, hash=b0780e68a2dc..., store=hydrus [add-file] RESOLVED source: path=None, is_hydrus=True, hash=b0780e68a2dc... [add-file] ERROR: Source validation failed for None

   This will help identify:

   • Where the result is being lost
   • If hash is being extracted correctly
   • Which store the file comes from

2. ENHANCED SEARCH-STORE DEBUG LOGGING

   Now logs after building results:

   • Number of table rows added
   • Number of items in results_list
   • WARNING if there's a mismatch

   Example output: [search-store] Added 4 rows to table, 4 items to results_list [search-store] WARNING: Table/items mismatch! rows=1 items=4

   This directly debugs the "@2 selection" issue:

   • Will show if table/items registration is correct
   • Helps diagnose why only 1 row shows when 4 items exist

3. ROOT CAUSE ANALYSIS: "@2 SELECTION FAILED"

   Your debug output showed: [debug] first-stage: sel=[1] rows=1 items=4

   This means:

   • search-store found 4 results
   • But only 1 row registered in table for selection
   • User selected @2 (index 1) which is valid (0-4)
   • But table only had 1 row, so selection was out of bounds

   The mismatch is between:

   • What's displayed to the user (seems like 4 rows based on output)
   • What's registered for @N selection (only 1 row)

   With the new debug logging, running the same command will show: [search-store] Added X rows to table, Y items to results_list

   If X=1 and Y=4, then search-store isn't adding all results to the table If X=4 and Y=4, then the issue is in CLI selection logic

4. NEXT DEBUGGING STEPS

   To diagnose the "@2 selection" issue:

   1. Run: search-store system:limit=5
   2. Look for: [search-store] Added X rows...
   3. Compare X to number of rows shown in table
   4. If X < display_rows: Problem is in table.add_result()
   5. If X == display_rows: Problem is in CLI selection mapping

   After running add-file:

   1. Run: @2 | add-file -storage test
   2. Look for: [add-file] INPUT result details
   3. Check if hash, title, and store are extracted
   4. If missing: Problem is in result object structure
   5. If present: Problem is in _resolve_source() logic

5. ARCHITECTURE DECISION: EXPORT-STORE CMDLET

   Recommendation: DO NOT CREATE EXPORT-STORE

   Reason: get-file already provides this functionality

   get-file:

   • Takes hash + store name
   • Retrieves from any backend (Folder, HydrusNetwork, Remote, etc.)
   • Exports to specified path
   • Works for all storage types
   • Already tested and working

   Example workflow for moving files between stores: $ search-store -store home | get-file -path /tmp | add-file -storage test

   This is cleaner than having specialized export-store cmdlet

6. FUTURE IMPROVEMENTS

   Based on findings:

   a) Update search-store to show specific instance names Currently: store="hydrus" Should be: store="home" or store="work" Implementation: Use FileStorage to detect which instance

   b) Fix selection/table registration validation Add assertion: len(table.rows) == len(results_list) Fail fast if mismatch detected

   c) Enhance add-file to handle Hydrus imports Current: Needs file path on local filesystem Future: Should support add-file -hash -store home This would copy from one Hydrus instance to another

SUMMARY

✓ Better debug logging in add-file and search-store ✓ Root cause identified for "@2 selection" issue ✓ Confirmed get-file is sufficient (no export-store needed) ✓ Path forward: Use new logging to identify exact failure point