Analisi tecnica di nikcli v1.259.0: release readiness, sicurezza e performance

[SandroHub013]

Ciao @nikomatt69,

ho fatto una revisione tecnica di live-main al tag v1.259.0, con working tree pulito, concentrandomi su release readiness, sicurezza, architettura e performance.

Sintesi

nikcli ha una base molto ambiziosa e ricca: TUI, server HTTP/SSE/WebSocket, SDK, mobile, plugin, MCP, bot, workflow, sync/event sourcing e telemetria. Per uso locale CLI/TUI lo considero promettente; per un server esposto in produzione lo considererei ancora da consolidare.

Evidenze riproducibili

Passano:

• typecheck del package packages/nikcli;
• lint;
• build single-target Windows;
• route coverage strict: 187/187 route Hono coperte dal bridge;
• diversi test mirati su permission, auth, sync, plugin, backend e adapter LLM.

Restano invece questi blocker:

• bun turbo typecheck fallisce nel checkout Windows con TS1128 in packages/app/src/custom-elements.d.ts e packages/enterprise/src/custom-elements.d.ts. I file sono symlink Git e Windows li presenta come file contenenti il solo path, non come direttive TypeScript; anche desktop eredita il problema da app.
• bun run --cwd packages/nikcli test si ferma al format:check: 247 file non sono conformi a Prettier.
• Bypassando il pretest, la suite registra 3489 pass, 66 fail, 1 skip su 3556 test. I fallimenti includono casi cross-platform, filesystem, PTY, server HTTP, plugin/Herdr, loop e UI; alcuni possono essere specifici dell'ambiente Windows, ma il gate complessivo non è verde.
• README.md indica la versione 1.149.0 mentre package e tag sono 1.259.0; inoltre documenta bun run build dalla root, ma lo script root non esiste.

Sicurezza da hardenizzare

La documentazione chiarisce correttamente che il sandbox locale non è una barriera di sicurezza e che il server senza password è una scelta dell'utente. Restano comunque aree importanti da rendere più difficili da configurare male:

1. un bind non-loopback senza password/OAuth espone API, shell, PTY e filesystem;
2. i bearer token mobile sono accettati come autenticazione generale, mentre il controllo degli scope è principalmente sulle route sync; le route di gestione token dovrebbero richiedere un ruolo privilegiato;
3. la CORS allowlist usa confronti startsWith con credenziali abilitate;
4. i token in query string possono finire in log, proxy o referrer;
5. gli upload teleport hanno ownership e quota totale insufficienti e leggono ogni chunk interamente in memoria;
6. plugin e dipendenze di progetto/configurazione possono installare ed eseguire codice, quindi il trust boundary va reso molto esplicito.

bun audit riporta 255 advisory sull'intero monorepo (le 4 critical risultano in altri workspace); nel percorso nikcli restano comunque advisory high da triagiare su MCP SDK, Hono, Drizzle, minimatch, shell-quote, ws e transitive.

Performance e mantenibilità

Il core è molto grande (circa 845 file e 215k righe) e contiene moduli profondi, dual runtime Hono/Effect e dual percorso AI SDK/native. I miglioramenti con il miglior rapporto rischio/beneficio mi sembrano:

• streaming degli upload teleport con quota e backpressure: memoria massima quasi costante e meno rischio di GC/DoS;
• plugin install/import lazy e deterministico: startup più rapido e niente rete durante il bootstrap;
• adapter LLM più diretto, abort propagato e fallback solo per errori realmente transitori: migliore time-to-first-token e meno allocazioni;
• batching/proiezioni SQLite misurate con benchmark: migliore throughput nelle sessioni e negli eventi;
• separazione dei moduli config, provider, session e TUI: build/typecheck incrementali più rapidi e minore superficie di regressione.

Non stimerei percentuali senza benchmark. Misurerei startup al primo frame, time-to-first-token, RSS su sessioni lunghe, eventi/sec e memoria/throughput degli upload.

Priorità proposta

P0: correggere i .d.ts cross-platform, rendere typecheck/test gate obbligatori e chiudere i problemi auth/scope/upload.

P1: portare il formatting a zero, classificare i 66 test falliti, aggiornare le dipendenze vulnerabili e riallineare README/versioni/script.

P2: consolidare Hono/Effect e AI SDK/native, poi ottimizzare storage e moduli profondi sulla base dei benchmark.

Nel complesso vedo una piattaforma con ottime potenzialità, ma la release attuale beneficia più da hardening e stabilizzazione che dall'aggiunta di nuove feature. @nikomatt69, mi interessa sapere se questa direzione coincide con la roadmap del progetto.

[SandroHub013]

Ho ri-verificato da zero tutti i punti che avevo scritto sopra, su live-main @ 101f56bd (tag v1.259.0), working tree pulito, Windows 11 + Bun 1.3.14. Riporto cosa regge, cosa avevo detto in modo impreciso, e cosa ho trovato di nuovo scavando nel codice.

Confermato con numeri esatti

Punto	Comando	Risultato
typecheck rotto	bun turbo typecheck	enterprise e app: src/custom-elements.d.ts(1,1): error TS1128 + (1,2)
247 file non formattati	bun run --cwd packages/nikcli format:check	Code style issues found in 247 files
README disallineato	—	README:13 dice 1.149.0, package e tag dicono 1.259.0
root build inesistente	—	README:119 documenta bun run build; negli script root non c'è
route coverage	bun run --cwd packages/nikcli check:routes	bridge patterns: 187 (0 sample failures) / hono api routes checked: 187 / hono without bridge support: 0
advisory	bun audit	255 vulnerabilities (4 critical, 91 high, 129 moderate, 31 low)
dimensione core	—	845 file, 214.844 righe sotto packages/nikcli/src

Sui .d.ts: la causa è precisa. git ls-files -s li dà mode 120000 (symlink a ../../ui/src/custom-elements.d.ts), e senza core.symlinks Windows li materializza come file di testo da 33 byte contenenti il path. TypeScript prova a parsare ../ come dichiarazione, da cui i due TS1128 a colonna 1 e 2. Aperta come #195 con due possibili fix.

README → #196. Gate del formatting → #197 (pretest è format:check && lint, quindi bun run test non arriva mai al runner; sospetto che sia anche l'origine dei diff gonfiati tipo quello di #183, +2199/-1925 su 104 file per una modifica descritta come minima).

Una cosa che avevo detto male

Ho scritto "route coverage strict: 187/187". Il numero è giusto ma non è un gate: check:routes chiude con advisory coverage ok (pass --strict to fail on gaps), quindi di default non fallisce. E test/server/routes-coverage.test.ts asserisce solo toBeGreaterThan(50) più una self-consistency dei pattern contro il proprio sample path — non confronta la route table Hono reale. Il dato resta buono, ma va citato come advisory, non come garanzia.

Test suite — confermata, e con la classificazione che mancava

Rieseguita bypassando il pretest, con gli stessi flag dello script del package:

$ cd packages/nikcli
$ bun test --timeout 30000 \
    --path-ignore-patterns='**/*benchmark*.test.ts' \
    --path-ignore-patterns='**/*integration*.test.ts'

 3495 pass
 1 skip
 62 fail
 14813 expect() calls
Ran 3558 tests across 301 files. [116.88s]

Avevo scritto 3489 / 66 / 1 su 3556: combacia a meno di flakiness (2 test di differenza sul totale, 4 sui fallimenti). Il gate non è verde, confermato.

Avevo però lasciato i 62 fallimenti come "alcuni possono essere specifici di Windows", che non è utile a nessuno. Classificati per firma dell'errore:

Ambiente Windows, non bug del prodotto (~la grande maggioranza)

• 32 × EBUSY: resource busy or locked, rm — teardown delle temp dir mentre un handle è ancora aperto. Su Windows non si cancella un file aperto: è un problema reale dell'helper di cleanup dei test, non del codice sotto test.
• ~19 riferimenti a symlink, 5 × EPERM: operation not permitted, symlink — Filesystem.realpathInside (4 test) e tui plugin discovery > follows symlinked plugin files. Creare symlink su Windows richiede Developer Mode o elevazione. Stessa famiglia di causa di typecheck: custom-elements.d.ts symlinks break turbo typecheck on Windows (TS1128) #195: il repo assume symlink POSIX in più punti.
• 4 × PTY spawn failed — Pty.Service.
• 1 × ENOENT ... uv_spawn ... rg.exe — ripgrep installato via winget non trovato al path atteso.

Bug vero, e piccolo — test/tui/entry-coverage.test.ts:19:

const root = new URL("../../src/", import.meta.url).pathname

Su Windows .pathname restituisce /C:/Users/..., con lo slash iniziale, quindi Bun.file(root + path) fallisce con ENOENT: no such file or directory, open '/C:/Users/.../session/index.tsx' (3 test). Va usato fileURLToPath da node:url. Curioso che accada proprio mentre nel repo esiste già una suite cross-platform file:// URL handling che verifica esattamente questo.

Da guardare, non classificabili dall'output — 10 test herdr wire contract (plugin/island/bridge.test.ts) e i cluster su server/sync. Questi non hanno una firma OS-specifica, quindi non me la sento di derubricarli a rumore d'ambiente senza girarli anche su Linux.

Se qualcuno può eseguire la suite su Linux e incollare qui il totale, si separa in un colpo solo il rumore Windows dai fallimenti veri. Sospetto che il verde reale sia molto vicino, ma il costo di scoprirlo non dovrebbe ricadere ogni volta su chi sviluppa da Windows — vedi #195 e #197.

Sicurezza — segnalata in privato

I punti 1, 2, 3 e 5 della mia lista sono confermati nel codice, e in tre casi la situazione è peggiore di come l'avevo descritta: non è solo "da hardenizzare", c'è un percorso di escalation concreto su un server in ascolto. Visto che il repo è pubblico e il pacchetto è su npm, non li metto qui.

Li ho aperti come segnalazione privata: GHSA-28wx-vfqc-xjfx (Security → Advisories). Dentro ci sono file, riga, impatto e fix proposto per ciascuno.

@nikomatt69 in sintesi, senza dettagli sfruttabili:

1. le route di gestione dei token mobile non fanno nessun controllo di autorizzazione nell'handler, malgrado la description dica il contrario — quindi la mia osservazione sugli scope era sotto-dimensionata;
2. l'allowlist CORS con startsWith è aggirabile con un hostname costruito ad arte, e nello stesso blocco convivono già regex ancorate per ts.net e nikcli.store, quindi il pattern corretto è a due righe di distanza;
3. l'upload teleport non lega l'upload a chi lo ha creato e l'id è monotono, non casuale — oltre ai problemi di quota e memoria che avevo già citato.

Posso aprire le PR per tutti e tre appena decidi la tempistica di disclosure; partirei dal primo.

Come la vedo sulla priorità

Confermo la scaletta che avevo proposto, con una correzione: metterei #195 in cima anche prima delle security, perché finché il typecheck non passa su Windows non c'è un gate verde su cui appoggiare la verifica di qualunque fix. Poi advisory, poi #197 (in un commit solo di formatting, con la SHA in .git-blame-ignore-revs), poi la triage dei test falliti.

La classificazione completa dei 62 fallimenti (firme di errore, conteggi, e il bug in entry-coverage.test.ts) è ora in #198, così non resta sepolta in questo thread.

---

Correzione sui 247 file non formattati

Ho sbagliato, e il consiglio che avevo dato era dannoso. I 247 file non hanno drift di formattazione: il repo non ha .gitattributes, quindi su Windows con core.autocrlf=true il working copy esce in CRLF mentre i blob committati restano LF, e Prettier ha default endOfLine: "lf".

Due verifiche:

$ git show "HEAD:./src/agent/agent.ts" | bunx prettier --check --stdin-filepath src/agent/agent.ts
$ echo $?
0

E confrontando ogni file segnalato con il proprio output Prettier a CR rimossi: su 45 file campionati dei 251 (i primi 20 più uno spread di 25 preso ogni decimo), tutti e 45 differivano solo per i fine riga. Zero con modifiche reali.

Quindi il commit prettier --write che avevo proposto avrebbe prodotto un diff da 247 file che non cambia una riga di codice. La fix vera è un .gitattributes con * text=auto eol=lf: dopo averlo aggiunto e rinormalizzato l'albero, format:check passa da 251 file segnalati a All matched files use Prettier code style!, senza toccare il contenuto di nessun sorgente.

Stessa causa, per inciso, dietro il diff gonfiato di #183: fine riga, non riformattazione.

#197 è stato riscritto di conseguenza — titolo e fix erano entrambi sbagliati.

[NovaRouteAI]

The distinction between a green route-coverage number and an actual CI gate is an important production-readiness detail, especially with 62 failures and cross-platform symlink behavior still in the path.

I would separate the release benchmark into platform-specific test classes and record startup, time-to-first-token, long-session RSS, events per second, and fallback/error rates for the LLM adapter. Keeping the 255 advisories, auth scope checks, upload quota, and symlink failures as explicit gates would make the stabilization work measurable without hiding environment-specific failures.

I am testing an OpenAI-compatible multi-model API layer around official/provider-backed Chinese models, with particular interest in latency, fallback, usage visibility, and workflow-level benchmark behavior. For nikcli, would the next useful comparison be Linux vs Windows parity, or the LLM adapter's completed-workflow latency and failure rate?