Agent README

Scope

Acest fisier este pentru agentii si toolurile care folosesc acest repository ca baza pentru importuri media automate, inclusiv rulari unattended din udev, systemd, cron, pipeline-uri NAS sau wrapper-e generate.

Scriptul principal validat este:

media-importer.sh

Prototipurile Raspberry Pi / unattended wrapper au fost eliminate din repository deoarece erau bazate pe o versiune invechita si netestata a importerului. Nu le recreati si nu le folositi ca reference design fara o decizie explicita de reluare a acelei directii.

Context critic: incidente de pierdere de date

Au existat pierderi reale de date in mediul nostru cu versiuni anterioare ale importerului. Incidentul documentat in INCIDENTS.md a fost declansat de fisiere GoPro chapter care au ajuns sa fie mapate la acelasi nume destinatie. Scriptul vechi a continuat dupa conflict, copia/mutarea a suprascris destinatia existenta, verificarea a validat fisierul suprascris, iar sursele au fost sterse.

Orice agent care copiaza, deriva, rescrie sau integreaza acest script intr-un tool unattended trebuie sa verifice explicit ca nu reintroduce bugurile care au dus la acea pierdere de date.

Reguli obligatorii pentru import unattended

• Nu folositi variante vechi, copii locale sau scripturi derivate fara comparatie cu protectiile curente din media-importer.sh.
• Nu folositi cp, mv, rsync sau alte unelte lasate sa rezolve singure conflictele de destinatie. Conflictele trebuie rezolvate in cod inainte de operatie.
• Nu suprascrieti niciodata o destinatie existenta.
• Nu stergeti sursa pana cand destinatia nu exista si verificarea a trecut.
• In move mode, fluxul sigur este copy -> verify -> delete source; nu inlocuiti acest flux cu mv direct in scripturi unattended.
• Destinatiile planificate in aceeasi rulare trebuie rezervate in memorie, ca doua surse sa nu poata ajunge la acelasi path chiar daca fisierul destinatie nu exista inca.
• Pentru conflicte unattended, comportamentul acceptat este suffix numeric unic (_1, _2, ...), skip explicit sau abort. Nu este acceptat overwrite silentios.
• Daca destinatia este in interiorul sursei, destinatia trebuie exclusa din scanare, iar orice fisier aflat deja in destinatie trebuie refuzat inainte de procesare.
• Pentru camere GoPro/Garmin/Varia sau fisiere QuickTime, nu modificati logica de data/timp fara teste de regresie; timestampurile identice sunt un caz normal, nu o eroare de intrare.

Checklist pentru copii sau scripturi derivate

Inainte ca o copie sau derivare sa fie folosita unattended, verificati ca include echivalentul acestor protectii:

• safe_cp si safe_mv refuza destinatii existente.
• Copierea se face intr-un fisier temporar, se verifica temporarul, apoi se muta in destinatia finala doar daca destinatia finala nu exista.
• VERIFY_MODE=size este default; strict este disponibil pentru comparatie byte-to-byte.
• Stergerea sursei are loc doar dupa verificarea destinatiei.
• Conflictele de destinatie sunt rezolvate prin resolve_destination_conflict / ensure_unique_destination_path sau logica echivalenta.
• Path-urile destinatie deja planificate sunt rezervate, nu doar cele existente pe disk.
• Testul timestamp-collision trece.
• Dry-run-ul pentru camere noi arata destinatii distincte pentru fiecare fisier.

Teste minime inainte de automatizare

Pentru orice schimbare care atinge importul, copierea, mutarea, verificarea, stergerea sursei, generarea numelor sau extragerea datelor, rulati cel putin:

./test_runner.sh timestamp-collision
./test_runner.sh verify-mode
./test_runner.sh dest-in-source

Pentru schimbari legate de GoPro sau metadata sidecar, rulati si:

./test_runner.sh gopro-sidecar-sync
./test_runner.sh gopro-no-sidecar-reimport

Daca aceste teste nu pot fi rulate, agentul trebuie sa marcheze integrarea ca nevalidata si sa nu recomande unattended move mode.

Recomandari operationale

Pentru camere sau destinatii noi, prima rulare trebuie sa fie dry-run:

./media-importer.sh -s "/path/to/camera" -d "/path/to/destination" --dry-run -v

Verificati in output ca:

• fiecare fisier sursa are o destinatie distincta;
• nu exista mesaje de overwrite;
• conflictele sunt suffixate, sarite explicit sau duc la abort;
• pentru GoPro, sursa datei este cea asteptata, inclusiv sidecar THM/LRV cand exista.

Pentru date cu valoare mare sau cand sursa poate fi pastrata, preferati temporar:

./media-importer.sh -s "/path/to/camera" -d "/path/to/destination" --verify-mode strict --keep-originals -v

Regula de oprire

Daca un agent gaseste o copie a scriptului care:

• foloseste mv direct in move mode;
• permite overwrite;
• sterge sursa fara verificare;
• nu rezerva destinatii planificate;
• sau nu poate demonstra ca trece testul timestamp-collision;

atunci agentul trebuie sa opreasca integrarea unattended si sa raporteze riscul ca posibil bug de pierdere de date.