CLI, instalare și reconciliere

CLI-ul operează în directorul de lucru curent. Rulează comenzile din directorul a cărui configurație vrei să o gestionezi. Detectarea poate raporta mai multe ținte într-un monorepo; reconcilierea alege ținta care corespunde directorului curent sau, în lipsa unei potriviri, prima țintă detectată. Nu aplică o configurație separată fiecărui workspace descoperit într-o singură invocare.

Instalare și compilare din sursă

Ai nevoie de Git, Node.js și Yarn înainte de a rula comenzile de instalare de mai jos. Pachetul declară Node.js >=22.18.0; mediul său de dezvoltare fixează Node.js 26.5.0 și Yarn 4.17.0. Pentru a reproduce mediul de dezvoltare, folosește aceste versiuni. Node.js execută JavaScript, iar Yarn instalează dependențele necesare compilării și rulării CLI-ului.

Instalează Node.js de pe pagina de descărcare și configurează Yarn urmând ghidul de instalare.

Odată publicat, pachetul va putea fi instalat sub numele său @sabinmarcu/ai:

yarn add @sabinmarcu/ai

pnpm add @sabinmarcu/ai

npm install @sabinmarcu/ai

Pachetul nu este încă publicat pe npm, dar va fi în curând. Până la publicare, clonarea și compilarea din sursă sunt necesare:

git clone https://github.com/sabinmarcu/ai.git ai-lib
cd ai-lib
yarn install
yarn build
export PATH="$PWD/bin:$PATH"

Modificarea PATH face comanda ai disponibilă în shell-ul curent. Pentru o instalare persistentă, adaugă calea absolută a directorului bin din checkout în configurația shell-ului. Recompilează după actualizarea sursei, deoarece lansatorul execută dist/cli.js, nu punctul de intrare TypeScript.

Lansatorul este un script shell POSIX, deci acest flux presupune un shell de tip Unix. Detectează un checkout Yarn Plug'n'Play și furnizează loader-ul corespunzător, păstrând directorul de lucru țintă. Poți invoca și bin/ai prin calea sa absolută.

Intră în repository-ul pe care vrei să îl configurezi înainte de inițializare. Înlocuiește calea de mai jos cu directorul respectiv:

cd /path/to/target-repository
ai --help
ai detect
ai init
ai status -v

detect doar citește. init modifică repository-ul: detectează modulele aplicabile, rezolvă configurația, scrie fișierele gestionate și starea configurației și adaugă referința în AGENTS.md de la rădăcină. Inspectează fișierele AI existente și păstrează o copie recuperabilă a modificărilor locale înainte de inițializare. Comanda nu generează doar fișiere goale și nu este o simulare.

Selectarea unui preset sau a unor module suplimentare

Preset-urile exprimă combinații reutilizabile. Preset-ul node-web combină instrucțiuni pentru aplicații web, React, TypeScript, Yarn, platformă și stilizare. Pentru un repository care chiar are nevoie de această combinație:

ai init --preset node-web

Atât --preset, cât și --module pot fi repetate. Formele scurte sunt -p și -m. Inițializarea rulează reconcilierea, deci modulele cu detector sunt reevaluate folosind indicii din repository; un argument explicit pentru modul nu suprascrie permanent detectorul acestuia. Selecțiile din preset-uri sunt păstrate.

Folosește init pentru configurarea inițială și reconcile pentru schimbările ulterioare. Inițializarea construiește o configurație nouă, cu un nou moment de creare; nu adaugă pur și simplu opțiuni la selecția existentă.

Inspectarea instalării

Comandă	Ce inspectează
`ai detect`	Țintele repository-ului, modulele efective detectate și mixin-urile active. Nu necesită o configurație salvată.
`ai status`	Rezolvarea configurației salvate, numărul de mixin-uri, modul fișierelor și problemele fișierelor gestionate.
`ai status -v`	Adaugă ID-urile mixin-urilor active.
`ai status -vv`	Arată și căile surselor din catalog. `--verbosity 0`, `1` sau `2` selectează un nivel explicit.
`ai verify`	Parsează configurația salvată, încarcă catalogul și verifică existența ID-urilor modulelor selectate explicit.

status întoarce un cod de ieșire diferit de zero pentru module sau preset-uri selectate necunoscute și pentru probleme ale fișierelor gestionate. Dacă nu există configurație, raportează absența ei și întoarce zero. Nu folosi doar acel cod pentru a demonstra că repository-ul a fost inițializat.

verify are un domeniu mai restrâns decât ar putea sugera numele: nu inspectează conținutul fișierelor instalate și nu execută rezolvarea completă a configurației salvate folosită de status. Nu înlocuiește verificarea divergențelor sau a selecțiilor incompatibile.

Inspectează înainte de reconciliere

După adăugarea sau eliminarea unor instrumente, schimbarea dependențelor sau actualizarea catalogului folosit de CLI:

ai reconcile

Fără opțiuni, comanda afișează un plan și nu face modificări. Planul raportează modulele, mixin-urile și diagnosticele fișierelor gestionate:

Previzualizarea întoarce zero chiar dacă diagnosticele conțin erori; este o comandă de inspectare, nu o verificare strictă pentru CI.

Detectarea actualizează selecțiile bazate pe detectoare, păstrează preset-urile selectate și modulele selectate explicit care nu au detector. Dependențele și mixin-urile sunt apoi recalculate pornind de la configurația propusă.

Când schimbările propuse sunt potrivite și nu mai există probleme blocante:

ai reconcile --apply

Comanda aplică fișierele, elimină fișierele vechi eligibile, scrie configurația propusă și se asigură că referința de la rădăcină există. Apoi construiește un alt plan pentru a verifica schimbările sau problemele rămase. Fișierele lipsă ori neactualizate pot fi tratate prin acest flux normal; fișierele editate și modulele selectate necunoscute necesită mai întâi atenție.

Interpretarea diagnosticelor

Inspectarea compară trei lucruri: conținutul dorit din catalog, hash-ul înregistrat anterior și conținutul curent al fișierului.

Diagnostic	Semnificație
`missing`	Un fișier gestionat dorit lipsește.
`outdated`	Un fișier instalat anterior necesită o actualizare din catalog sau reîmprospătarea hash-ului ori a metadatelor de proprietate.
`drifted`	Conținutul curent diferă de cel dorit și nu poate fi tratat ca o instalare anterioară nemodificată.
`untracked`	Există un fișier la o cale gestionată dorită, dar fără o înregistrare a proprietății.
`stale`	Un fișier înregistrat nu mai face parte din plan și nu a fost modificat local sau lipsește deja.
`stale-drifted`	Un fișier înregistrat nu mai este dorit, dar conținutul său diferă de hash-ul înregistrat.

reconcile --apply este blocat de fișiere drifted, stale-drifted și untracked. Este blocat și dacă ID-uri de module selectate au dispărut din catalog. Păstrează editările utile și mută schimbările specifice repository-ului în locațiile locale corespunzătoare înainte de a decide înlocuirea fișierelor gestionate.

Reparare deliberată

ai reconcile --repair

Repararea este o operație forțată. Poate suprascrie conținut local la căile gestionate, elimina fișiere vechi editate și renunța la ID-uri necunoscute de module selectate explicit. Nu îmbină acele editări și nu creează copii de siguranță. Inspectează previzualizarea și păstrează tot ce îți trebuie înainte de a o folosi.

--apply și --repair se exclud reciproc. Repararea este respinsă dacă nu există erori blocante; pentru fișiere doar lipsă sau neactualizate folosește --apply. Preset-urile necunoscute nu sunt acoperite de pasul de reparare a modulelor selectate.

Există și o operație de nivel inferior:

ai apply

Aceasta materializează selecția salvată fără să detecteze din nou repository-ul. Spre deosebire de reconcile --apply, poate suprascrie fișiere editate deja înregistrate ca gestionate. Refuză în continuare suprascrierea unui fișier neînregistrat cu un conținut diferit și eliminarea unui fișier vechi editat. Folosește-o când restaurarea configurației curente este intenționată, nu ca sinonim pentru inspectare sau reconciliere cu protecții.

Explorarea interactivă a modulelor

ai interactive

Comanda necesită o configurație existentă și un terminal interactiv. Arată modulele efective, relațiile de dependență și motivele selecției. Caută cu /, navighează cu săgețile sau j și k, schimbă gruparea cu t și ieși cu q.

Interfața curentă permite explorarea, nu editarea selecției. Căutarea, navigarea și gruparea nu modifică configurația salvată și nu aplică fișiere.

Modul source

Pentru un repository care conține catalogul pe care îl consumă:

ai init --asset-mode source

Modul source încarcă directorul local catalog și leagă direct fișierele sale din .ai/AGENTS.md. Acestea trebuie să se afle în repository-ul țintă. Doar punctul de intrare este materializat în acest mod; instrucțiunile catalogului și skill-ul de reconciliere rămân linkuri către sursă.

Consumatorii obișnuiți ar trebui să folosească modul implicit materialized. Acesta copiază instrucțiunile în repository și nu cere păstrarea unui checkout separat al catalogului la dispoziția agentului.