xamxam/TODO.md

Test Coverage (docs/test-plan.md)

Phase 0 — Prerequisites

• 0.1 Install PHPUnit (composer require --dev phpunit/phpunit ^11)
• 0.2 Create phpunit.xml at project root
• 0.3 Create tests/bootstrap.php (autoload classes, define constants)
• 0.4 Create tests/phpunit/ directory

Phase 1 — Pure Logic (no DB, no filesystem, no network)

• 1.1 CryptoTest.php — encrypt/decrypt round-trip, isEncrypted, legacy fallback, edge cases
• 1.2 EmailObfuscatorTest.php — encode, email, mailto, emailText, obfuscateHtml, edge cases
• 1.3 SystemControllerHelpersTest.php — humanBytes, diskColor, logLineClass, nginxLineClass, statusLabel/statusClass
• 1.4 StudentEmailTest.php — buildHtml: thesis fields, HTML escaping, missing optional fields
• 1.5 TfeControllerOgTest.php — buildOgTags: required keys, image fallback, description truncation

Phase 2 — Integration (requires test database)

• 2.0 Setup: tests/fixtures/, TestDatabase helper, .env.test
• 2.1 DatabaseExtendedTest.php — escapeLikeString, buildSearchConditions, findDuplicateThesis, generateThesisIdentifier, getCoverPathsForTheses, findOrCreateAuthor, deduplicateLanguages/renameLanguage/mergeLanguage, renameTag/mergeTag
• 2.2 ShareLinkExtendedTest.php — listActive, listArchived, findBySlug, setPassword+getDecryptedPassword round-trip, update
• 2.3 RateLimitExtendedTest.php — checkKey per-key counts, getRemaining decrement, getClientIdentifier consistency

Phase 3 — Controller Validation

• 3.1 ThesisCreateValidationTest.php — valid submission, missing required fields, invalid year, malformed URL, tag dedup, XSS escaping
• 3.2 ThesisEditValidationTest.php — load known/404, collectJuryMembers, handleWebsiteUrl normalisation
• 3.3 AutofocusFieldForErrorTest.php — correct field per error key, unknown key returns null/default, no CreateController name leak

Phase 4 — Cleanup

• 4.1 Migrate 8 existing custom-runner tests to PHPUnit in tests/phpunit/
• 4.2 Verify all pass under vendor/bin/phpunit
• 4.3 Remove run-tests.php and old test files
• 4.4 Add vendor/bin/phpunit to justfile/Makefile CI target
• 4.5 Generate baseline coverage report (--coverage-html coverage/) — needs Xdebug/PCov
• 4.6 Commit coverage baseline

---

Current tasks

De-librairisation — replace custom infrastructure with off-the-shelf libraries

• Write docs/de-librairisation.md strategy document
• Create composer.json with league/commonmark, guzzlehttp/guzzle, phpmailer/phpmailer
• composer install (prod + dev deps)
• Wire vendor/autoload.php into app/bootstrap.php
• Update phpstan.neon (scanDirectories replaces manual Parsedown scan)
• Write docs/system-setup.md (PHP extension requirements)
• Phase 1: Replace Parsedown with league/commonmark (4 call sites)
• Phase 2: Replace PeerTubeService HTTP client with Guzzle
• Phase 3: Replace SmtpRelay SMTP socket with PHPMailer
• [-] Phase 4: Crypto → defuse/php-encryption — DEFERRED (current AES-256-GCM impl is correct; migration risk > reward)

justfile: combine phpstan + cs-check + cs-fix into lint-php

• Merge phpstan, cs-check, cs-fix into single lint-php recipe with backward-compat aliases
• Run lint-php + cs-fix, fix all fixable issues (4 real bugs + CS formatting + regenerated baseline)

Récapitulatif admin: fieldset + table fichiers

• Convert all sections to fieldsets with legends
• Convert files list to table (recap-files-table)
• Add bottom margins on fieldsets (admin-main--recap class)
• Remove image thumbnails from files table (emoji icon only)
• Fix spurious beforeunload dialog on edit page (FilePond addfile on existing files)

Mots-clés fieldset in contenus

• Create contenus-motscles-fragment.php (tags fragment mirroring langues)
• Add Mots-clés fieldset to contenus template (search + table + bulk actions)
• Keep button linking to dedicated tags.php page as backup
• Add "Annuler" cancel button to both langues and mots-clés bulk action bars
• Add max-height:50vh + overflow-y:auto to both table wraps
• Deploy: just deploy
• Fix: .env permission check — removed from generic file-perm loop (was expecting 660, but .env is 640)

Tmp file cleanup (stale filepond + _trash)

• Session-based detection: check manifest session_id against PHP session files
• DB-based detection for _trash: check thesis_files row still exists
• Time-based fallback: >2h filepond, >30d trash
• admin cleanup-stats.php: stale vs active breakdown with sizes
• admin cleanup-tmp.php: smart cleanup with detailed JSON response
• admin index: Nettoyer button + dialog with stats and cleanup trigger
• .gitignore: exclude tmp/filepond/* and tmp/_trash/*
• Deploy: just deploy

Index page improvements

• Remove 'Mots-clés' button from toolbar
• Move export to bulk selection bar (Exporter CSV + Exporter fichiers buttons)
• Export dispatcher accepts ?ids= for per-selection filtering
• All ExportController/Database export methods accept optional thesisIds
• Graceful error when ZipArchive extension missing (php8.4-zip not installed)
• Move DB export (SQLite download) to paramètres → Maintenance section
• Sticky thead on index table (position: sticky, top: 0, z-index: 5)

Dialog & trash page margins

• Add admin-dialog__body CSS rule with padding + margin resets
• Add admin-dialog__stats + admin-dialog__hint classes
• Fix admin-dialog__alert p margins (not-last-child gets bottom margin)
• Add horizontal margins to .admin-main--list > direct children (trash page forms, tables, flash msgs)
• Clean up tmp-cleanup dialog inline styles → CSS classes

Deploy exclusions

• Exclude storage/tmp/ (not just filepond/*) to skip _trash dirs with bad perms
• Exclude storage/documents/ and storage/theses/ from rsync deploy

Commit history cleanup

• Squash 177→98 commits by merging similar/iterative fixes and immediate follow-ups
• Resolve 206k lines of nested jj conflict markers in acces.php
• Update commit descriptions for squashed groups

acces.php conflict marker cleanup

• Remove 206k lines of nested jj conflict markers from acces.php (resolved from clean nzllwsxo base)
• Restore missing features: create-result dialog, locked_year field, auto-generated password UI, file restrictions section, admin TOC wrapper

Save fixes (files disappearing on edit/terminer)

• Fix: note_intention deleted on save — handleFilePondSingleFile treats existing DB id as new upload, deletes existing, then can't re-process (integer vs hex mismatch)
• Fix: cover removal now uses trash, same hex-vs-integer guard as note_intention
• Fix: all file deletions now route through deleteThesisFileToTrash (renames to tmp/_trash instead of unlinking)

Storage restructure

• Move storage root from theses/ to documents/ (ThesisFileHandler, ThesisEditController, ThesisCreateController, MediaController)
• MediaController: support both theses/ and documents/ prefixes for visibility gate
• Migration: rename existing theses/ directories to documents/ on disk and update DB paths

Relink feature

• Backend: endpoint to browse documents/ directory (file-browser.php with HTMX tree)
• Backend: endpoint to relink an existing file to a thesis (relink.php inserts thesis_files row)
• Frontend: modal with folder browser, triggered by a "Relier" button next to each FilePond pool
• JS: integrate relink button into FilePond UI (XamxamOpenFileBrowser + XamxamRelinkFile)
• CSS: .relink-modal + .file-browser styles in form.css
• Fix: relinked file not appearing in FilePond pool — add file metadata to addFile() options and extensive diag logging
• Fix: addFile called with single object instead of (source, options) — FilePond API mismatch prevented files from loading
• Fix: use type 'limbo' for relinked files so they go through DID_COMPLETE_ITEM_PROCESSING → onprocessfile → syncOrderInput + green checkmark visual
• Fix: change .filepond--file default border from yellow to green (existing files never reach processing-complete state)
• Migration: rename existing theses/ directories to documents/ on disk and update DB paths

Trash policy

• FilePond remove moves to tmp/_trash (already implemented in handleRemove)

• Fix: partage FilePond asks admin password — shared handler + separate partage endpoints with share_active session gate

• Fix: mots-clé HTMX search — restored tag-search-fragment.php logic lost during fragment architecture refactor

• Generalize pill-search: single fragment endpoint (type=tag|language|supervisor), deduplicate tag & language backends, add jury autocomplete (promoteur·ice interne/externe ULB, lecteur·ice interne/externe)

• Deploy: just deploy (includes new partage/actions/filepond/ + FilepondHandler.php)

• Fix: language pill-search showing mots-clé results — form field name collision; replaced hidden inputs with scoped hx-vals; fixed exclude logic per type

• Add Créer button to jury supervisor autocomplete (removed guard in pill-search-fragment.php)

• Fix: UNIQUE constraint on authors.email — findOrCreateAuthor now checks for existing author by email before inserting; prevents crash when two authors share an email

CSS Refactoring (css-methodology-spec.md)

• Split variables.css into colors.css + typography.css
• Create reset.css (modern-normalize base — matches prior project reset; Tailwind Preflight caused regressions)
• Create base.css (≤ 5 site-wide rules)
• Create utilities.css (sr-only, skip-link, reduced-motion)
• Create components/ (links, focus, forms, tables, dialog, details, media, buttons, badges, toasts, pagination, header, search)
• Create style.css root @import file
• Remove redundant @import url("./variables.css") from page files
• Clean up duplicate status-badge / toast definitions from admin.css (now in components/)
• Update head.php + partage pages to load style.css
• Common.css → backward-compat wrapper importing style.css
• Variables.css → backward-compat wrapper importing colors.css + typography.css
• Update comment references from common.css → component files
• Reverted CSS nesting (native CSS nesting breaks in browsers without support; no build step available)
• Unnest header.css (was missed in original nesting revert — admin nav-left-links rendered vertically)
• reset.css: modern-normalize base (not Tailwind Preflight) to avoid border/list/heading regressions
• search.css: restored !important flags on input (overrides forms.css base selectors)
• acces.php: copy password button now shows toast feedback
• Verify no visual regressions

Current tasks

• Add ZipArchive guard to legacy export-files.php

• Refactor deploy recipe: split into deploy-code / deploy-deps / deploy-migrate; deploy-deps patches classmap path (app/src/ → src/) for flat server layout before running composer install; only runs install when lockfile checksum changed

• Fix bootstrap.php autoload path: detect vendor/ location (same dir vs parent dir) to work on both flat server layout and nested local dev layout

• Cleanup modal: list files that will be removed (not just counts)

• Storage restructure: documents/ → {objet}/ (tfe/theses/frart)

• Migration script: move files + update DB paths

• Fix: hardDeleteThesis doesn't prepend STORAGE_ROOT to file_path

• Sticky thead: fix with border-collapse:separate, CSS class, --sticky-top var, +min-height:50vh on wrappers, +bulk delete for mots-clés

• Edit submit redirects to recapitulatif instead of staying on edit.php

• Mandatory auto-generated passwords on share links (no custom passwords, regenerate-only in edit, rate limit on password gate)

• .gitignore / .ignore: exclude *.db-wal and *.db-shm

• CSS: FilePond pool file block border yellow → green on upload complete

• Move shared fichiers-fragment.php from partage/ to templates/partials/form/ and update all links

• Remove Écriture and Image format types (migration 035 + schema seed + query filter)

• FilePond image previews: use site light colors (--bg-secondary, --text-secondary, --accent-green, --error)

• Edit mode: remove custom file preview list above FilePond pools; use FilePond pools for preexisting files

• Cover + note_intention: add data-existing-files to their FilePond inputs (per-queue-type JSON arrays)

• Remove upload-progress bar at bottom (FilePond handles its own progress)

• Remove upload-progress.js from edit/add/partage page extraJs arrays

FilePond Refactor — Merge video/audio into TFE pool

• A. fichiers-fragment.php — Remove separate video/audio pools, merge into TFE; include PeerTube in data-existing-files
• B. file-upload-filepond.js — Remove peertube_video/peertube_audio/video/audio from QUEUE_CONFIG, remove acceptedFileTypesPeerTube, remove data-peertube-active logic
• C. process.php — When queue_type=tfe and video/audio + PeerTube enabled, upload to PeerTube, return peertube:UUID
• D. load.php — Handle peertube DB files: return placeholder SVG blob
• E. form.php — Include PeerTube files in existingFilesJsonForTfe for edit mode
• F. ThesisEditController.php — Remove separate video/audio/peertube_* handleFilePondQueueFiles calls; also legacy $_FILES path
• G. ThesisCreateController.php — Same as F

HTMX Fragment Architecture Reorganization

• Create shared templates _licence.php and _format-website.php in templates/partials/form/
• Create src/FragmentRenderer.php helper
• Create public/admin/fragments/ and public/partage/fragments/ subdirectories
• Create thin fragment endpoint files (auth + data prep + render shared template)
• Update all hx-post references in templates to point to new fragments/ paths
• Update partage/index.php routing for new fragments
• Keep old fragment files as thin delegates to new fragments/ for backward compat
• Update nginx config for partage fragment PHP handling

Maintenance mode + partage fragment fix

• bootstrap.php: add /partage as allowed path prefix in maintenance gate
• SystemController.php: update maintenance detail message
• admin/parametres.php: always-visible accessibility table (Normal vs Maintenance)
• admin.css: .param-access-table styles (border-radius via overflow:hidden, green/secondary colours)
• partage/index.php: fix fragment routing — $slug was 'fragments' but check used str_starts_with($slug, 'fragments/'), causing HTMX fragments to redirect to / (main page)
• Deploy: just deploy + just deploy-nginx

File browser fixes

• Fix: top-folder navigation regex doesn't match bare documents/theses (requires trailing slash)
• Replace emoji icons (📁📄) with proper SVG icons (folder, pdf, file-archive, text-file)
• Fix relink endpoint: always return JSON (even on errors), guard finfo class, add diagnostic logging
• Fix JS relink error handler to parse JSON error responses

Previous items

• Step 1 — Build 4 PHP endpoints (process.php, revert.php, load.php, remove.php)
• Step 2 — Update ThesisFileHandler to accept file_ids instead of $_FILES
• Step 3 — Update file-upload-filepond.js (async server model + all fixes)
• Step 4 — Update templates (data-queue-type on all inputs, data-existing-files in edit)
• Step 5 — Update upload-progress.js (new collectFileNames, pending-uploads guard)
• Step 6 — QA / integration testing
• Logs accessible via Paramètres: app, admin, error, audit tabs (JSON parsed to readable lines), nginx tabs kept
• Remove nginx config tab and PHP-FPM error log tab from UI
• Step 7 — Cleanup: remove transition flags, remove INPUT_ID_TO_TYPE

CSP & Deploy Fixes (May 2026)

• Track vendor JS files in jj (they were moved to vendor/ but never jj file tracked)
• Add script-src 'self' 'unsafe-inline' to main CSP header (public pages use inline scripts + onclick handlers)
• Add storage/tmp/filepond/* to .gitignore + rsync exclude, with .gitkeep
• Deploy: just deploy to sync vendor JS files + updated CSP + .gitkeep to server

improvements_postlaunch — Année verrouillable dans partage + correction ID

Implémentation

1. Schema: ajouter locked_year aux share_links

• Database::runMigrations(): ALTER TABLE share_links ADD COLUMN locked_year INTEGER
• app/storage/schema.sql: ajouter la colonne

2. ShareLink model: lire/écrire locked_year

• ShareLink::create(): accepter et stocker locked_year
• ShareLink::update(): accepter et stocker locked_year
• findBySlug() retourne déjà SELECT *, donc locked_year remonte automatiquement

3. Admin UI — Dialog de création de lien

• Ajouter champ "Année académique verrouillée" dans create-dialog (acces.php)
• Ajouter champ dans edit-dialog (acces.php)

4. Admin UI — Liste des liens

• Afficher colonne "Année" dans le tableau des liens (acces.php)

5. Admin actions (acces-etudiante.php)

• Lire locked_year depuis $_POST dans action 'create' et 'update'
• Passer au ShareLink model

6. Partage — Formulaire

• partage/index.php (renderShareLinkForm): lire locked_year depuis le lien
• fieldset-academic.php: quand $lockedYear est défini → hidden input + span "Année académique verrouillée : YYYY" + explication; quand null → comportement actuel
• ThesisCreateController::validateAndSanitise(): respecter locked_year si présent dans POST (priorité sur $_POST['année'])

7. Admin edit.php — Forcer l'identifiant

• Ajouter un champ "Identifiant" en lecture seule mais avec un bouton "Regénérer"
• ThesisEditController: ajouter méthode regenerateIdentifier() qui reconstruit YYYY-NNN avec MAX+1 sur la nouvelle année
• Database: méthode regenerateThesisIdentifier(int $thesisId, int $year) — met à jour identifier basé sur l'année dans un SELECT FOR UPDATE
• Attention: renommer les dossiers de fichiers sur disque si l'identifiant change