Repo Reader

repo-reader è un applicativo pensato per esplorare un repository locale, leggere la documentazione presente nelle cartelle docs e offrire un punto di ingresso unico per navigazione, anteprima Markdown e, in una fase successiva, editing guidato dei contenuti.

L’idea di partenza nasce dal mini applicativo già esistente nel repository sorgente che mi hai mostrato: un server Node.js avvia una finestra del browser, permette di navigare le cartelle, aprire file Markdown e gestire alcune azioni base sul repository. Questo progetto vuole evolvere quella base in un prodotto impacchettabile via npm, più completo e più semplice da integrare in altri progetti.

L’interfaccia nuova parte sempre in modalità visualizzazione. Quando serve modificare un file si passa alla modalità modifica con un toggle dedicato, così l’intera area di lavoro cambia contesto senza tenere preview ed editor divisi inutilmente.

Regola operativa per gli agenti GitHub Copilot

Prima di fare qualunque modifica al repository, gli agenti GitHub Copilot devono leggere questo README per allinearsi su architettura, stato corrente e regole di lavoro. Se il README cambia in modo sostanziale, va riletto prima di intervenire di nuovo sul codice.

Obiettivo

L’obiettivo è distribuire repo-reader come strumento installabile nelle devDependencies di un progetto e avviabile con un comando breve da terminale. In prospettiva, il tool dovrà fornire:

1. una finestra desktop dedicata, senza dipendere da un server Node avviato manualmente;
2. una navigazione del repository e della documentazione in stile file explorer, con filtro rapido e apertura di file collegati dai Markdown;
3. un visualizzatore Markdown integrato;
4. funzionalità di editing assistito per file testuali e documentazione tramite Monaco Editor;
5. una base estendibile per comandi futuri legati alla gestione del repository.

Stato attuale del materiale di partenza

Dal mini-app mostrato emergono già alcuni comportamenti utili da preservare o rifattorizzare:

1. avvio automatico dell’interfaccia;
2. lista dei file e delle cartelle del repository;
3. apertura dei file Markdown in una vista dedicata;
4. placeholder per le cartelle;
5. apertura del repository in VS Code o di cartelle specifiche nell’Explorer di Windows;
6. gestione di heartbeat e chiusura del processo quando la finestra si chiude.

Questi punti sono un buon riferimento per il primo rilascio, ma l’architettura va spostata verso un’app desktop distribuita come pacchetto npm, non come semplice server HTTP locale.

Direzione tecnica proposta

La soluzione più adatta, in base a quanto si vede ora, è una desktop app costruita con Electron e affiancata da un layer di rendering moderno per l’interfaccia. In parallelo, per l’editing guidato, Monaco Editor è una scelta naturale perché offre una UX molto vicina a un IDE senza dover incorporare un editor completo.

Componenti consigliati

1. Electron per creare finestra, lifecycle e integrazione con il sistema operativo.
2. Un processo main per accesso al filesystem, dialog, shell e gestione repository.
3. Un renderer UI per navigazione, preview, ricerca e azioni contestuali.
4. Monaco Editor per editing assistito, validazione e anteprima del contenuto.
5. Un parser Markdown e una pipeline di rendering separata dalla UI.
6. Un piccolo layer CLI o un bin npm per l’avvio rapido del tool.

Distribuzione npm

Se l’obiettivo è farlo installare come devDependency, conviene prevedere:

1. un pacchetto con bin per esporre un comando tipo repo-reader;
2. uno script di avvio che individui il repository corrente;
3. un fallback che permetta di passare il percorso del repository come argomento;
4. una configurazione chiara di build e packaging per Windows, macOS e Linux.

Roadmap implementativa

Fase 1: baseline applicativa

1. Creare la struttura del progetto Electron.
2. Separare la logica di filesystem, navigazione e rendering Markdown dal bootstrap iniziale.
3. Definire un comando di avvio unico da terminale.
4. Rendere configurabile la root del repository da esplorare.

Fase 2: navigazione e preview

1. Implementare un file explorer interno.
2. Filtrare e classificare correttamente documentazione, cartelle e file supportati.
3. Aprire file Markdown in preview integrata.
4. Gestire placeholder e stati vuoti in modo coerente.

Fase 3: editing guidato

1. Integrare Monaco Editor nella vista principale o in un pannello dedicato.
2. Aggiungere apertura file, modifica e salvataggio controllato.
3. Introdurre sintassi, evidenziazione e auto-complete per Markdown e file testuali.
4. Escludere o proteggere i file binari e i percorsi sensibili.

Fase 4: integrazione con il repository

1. Aggiungere comandi contestuali per aprire cartelle e file in editor esterni.
2. Integrare operazioni utili come ricerca nel repository e refresh della vista.
3. Prevedere hook per future funzioni di gestione Git o documentazione.

Fase 5: packaging e distribuzione

1. Preparare build per desktop app.
2. Pubblicare il pacchetto npm con metadata, bin e documentazione d’uso.
3. Verificare il comportamento quando il progetto viene installato come devDependency.
4. Aggiungere una guida rapida per l’uso nel README del progetto ospitante.

Prossimi passi consigliati

1. Definire il nome definitivo del pacchetto e il comando CLI esposto.
2. Creare la nuova struttura Electron partendo dalla logica già presente nel mini-app.
3. Scegliere l’architettura del renderer: HTML semplice, framework leggero oppure UI moderna con componenti.
4. Stabilire il perimetro della prima release: sola lettura, oppure lettura più editing base.

Nota sul materiale esistente

I file che hai mostrato sono già sufficienti per definire il comportamento di partenza, ma non ancora per il prodotto finale. La priorità dovrebbe essere trasformare il server monolitico attuale in moduli separati: boot, filesystem, rendering, UI e comandi. Questo rende più semplice introdurre Electron e Monaco senza riscrivere tutto in un solo passaggio.

Avvio rapido

1. Installare le dipendenze del progetto con npm install.
2. Avviare l'app con npm run start.
3. In alternativa, dopo la pubblicazione del pacchetto, usare il comando esposto da bin come repo-reader --root <percorso-repository>.

Stato dell’implementazione

La base iniziale ora include:

1. un comando CLI che avvia Electron puntando al repository selezionato;
2. una finestra desktop dedicata;
3. navigazione delle cartelle del repository con filtro e breadcrumb;
4. anteprima Markdown integrata;
5. un editor Monaco attivato solo in modalità modifica, con salvataggio diretto;
6. apertura della cartella nel file manager e in VS Code quando disponibile;
7. stampa del documento ed esportazione PDF tramite un menu compatto.
8. una finestra di stampa/esportazione con frontespizio, indice automatico, numerazione dei paragrafi H2-H4 e intestazione/piè di pagina ripetuti;
9. watermark di classificazione distribuito su ogni pagina del documento esportato;
10. una dialog dedicata per i parametri di stampa, con autore e organizzazione gestiti separatamente.
11. cambio workspace protetto da conferma quando ci sono modifiche non salvate;
12. apertura di una cartella trascinata sull'area di lavoro come nuovo workspace.

Modalita' di rilascio

Il progetto mantiene due canali di distribuzione distinti e complementari.

1. App desktop Windows installabile

Per la distribuzione come applicazione desktop autonoma e' ora prevista la build con Electron Forge.

Comandi principali:

1. npm run dev per l'avvio in sviluppo tramite Forge.
2. npm run package per produrre il pacchetto applicativo non installante.
3. npm run make per generare gli artefatti di distribuzione.
4. npm run make:win per generare in modo esplicito gli artefatti Windows, incluso l'installer Squirrel.

Comportamento applicativo previsto in modalita' desktop:

1. l'utente puo' trascinare una cartella sull'area di lavoro per aprirla come workspace;
2. se esistono modifiche non salvate, l'app chiede se salvare, proseguire senza salvare o annullare il cambio workspace;
3. durante il drag-and-drop compare un overlay esplicito sull'area di lavoro;
4. l'app puo' essere usata anche senza avere il repository di sviluppo del progetto aperto localmente.

Nota su Squirrel e menu Start

Il primo packaging con Squirrel produceva l'installer ma non creava correttamente la voce nel menu Start. La causa non era Forge in se', ma l'assenza della gestione degli eventi Squirrel all'avvio dell'app.

Per correggere questo comportamento sono stati aggiunti:

1. electron-squirrel-startup nel runtime dell'app;
2. la chiusura immediata dell'app quando viene lanciata con gli switch di installazione/aggiornamento/rimozione di Squirrel;
3. una configurazione esplicita di shortcutName e dell'icona .ico nella build Forge.

Questo e' il passaggio che permette a Squirrel di completare correttamente la creazione e l'aggiornamento degli shortcut, incluso quello del menu Start.

In aggiunta, durante installazione e aggiornamento vengono registrate voci di menu contestuale in Windows per:

1. cartelle;
2. file .md;
3. file .mdx.

Queste voci permettono di aprire rapidamente il percorso selezionato in Repo Reader senza passare dalla finestra di selezione workspace.

2. Pacchetto npm come strumento di sviluppo

Resta invariata la modalita' di utilizzo come tool installabile nelle devDependencies di un altro progetto.

In questo scenario:

1. il pacchetto espone il comando repo-reader tramite bin;
2. l'avvio continua a passare da src/cli.js;
3. il workspace iniziale puo' essere dedotto dalla cartella corrente oppure passato con --root.

Esempio:

npm install --save-dev repo-reader
npx repo-reader --root .

Direzione UI consigliata

Per evitare che la UI diventi troppo densa, la linea migliore è spostare le azioni meno frequenti in un menu overflow e introdurre un vero document focus mode:

1. barra superiore ridotta alle sole azioni primarie e al toggle di modalità;
2. sidebar comprimibile o richiudibile in un rail più stretto;
3. stampa, export PDF e altre azioni secondarie dentro un menu contestuale;
4. area documento estesa quasi a tutta la finestra quando si lavora in lettura o modifica.

In pratica, il documento deve restare il centro della schermata e il resto dell’interfaccia deve arretrare quando non è necessario.