Riferimento della CLI di CapDAG

capdag è sia l’implementazione di riferimento di questa specifica sia un prodotto da riga di comando: uno strumento in stile Unix che esegue una singola cap, esegue un intero grafo .machine, ispeziona il fabric e crea lo scheletro di cartucce e ne supporta lo sviluppo. Ogni modalità pilota un vero host Bifaci con le cartucce incluse registrate, così le chiamate peer di una cap (download di modelli, ricerche nel fabric) funzionano esattamente come all’interno del motore.

Collegamento al fabric

Ogni invocazione di capdag risolve cap, media e alias rispetto a un solo registro del fabric. Un eseguibile distribuito incorpora l’URL di quel registro al momento della build (CDG_FABRIC_REGISTRY_URL); una variabile d’ambiente con lo stesso nome, a runtime, sostituisce il valore incorporato. La base degli schemi (CDG_SCHEMA_BASE_URL) è sempre e solo abbinata all’URL del fabric, mai separata da esso. È questo che fa sì che una build --staging risolva disbind-pdf rispetto al fabric di staging anziché a quello di produzione.

Comandi

capdag <cap-alias-or-urn> [cap args] [inputs...] [options]   Run one cap
capdag run <machine-file> [inputs...] [options]              Run a .machine file
capdag plan <files...> [--to <t>]... [options]               Discover targets / plan machines for a file set
capdag dag-viz <machine-file> [--mermaid|--dot]              Render the execution plan
capdag find <cap-alias-or-urn>                               Show the providing cartridge(s)
capdag resolve [--no-cache] <cap-alias-or-urn>...            Print cap definition JSON (array for >1)
capdag cache [clear|refresh]                                 Invalidate/renew the local fabric cache
capdag install <cap-alias-or-urn-or-cartridge-id>            Download + verify without running
capdag new <name> --<language> [-o <dir>]                    Scaffold a new cartridge project
capdag dev-install <project-dir>                             Install/update a dev cartridge under the dev slug
capdag self update                                           Replace this capdag with its channel's latest release

capdag <cap> …: esegue una cap (modalità a cap singola)

La modalità predefinita: un alias o un URN di cap, da solo, viene eseguito come uno strumento in stile Unix, pilotando l’interfaccia dichiarata dalla cap stessa.

• Lo stdin in pipe, oppure il percorso o i percorsi dei file di input, alimentano l’argomento stdin della cap.
• I --flags e gli argomenti posizionali dichiarati dalla cap vengono accettati nativamente.
• --arg <name-or-media-urn>=<value> indirizza esplicitamente qualsiasi argomento, con il name che gli dà la sua definizione o con il suo media URN (ripetibile; @<path> legge i byte di un file per un argomento binario). Un nome che la cap non dichiara viene rifiutato, indicando quelli che dichiara.

Presentazione dell’interfaccia della cap. capdag <cap> --help stampa l’interfaccia dichiarata di quella cap, strutturata per ruolo dell’argomento anziché come un elenco piatto di argomenti:

• Input: l’input PRINCIPALE della cap: l’argomento la cui sorgente stdin dichiarata ha come URN la specifica in= del cap URN (identificato tramite equivalenza dei tagged URN, mai tramite confronto di stringhe; vedi Input e output §”Ruoli degli argomenti”). Viene mostrato per primo: è così che la cap viene alimentata, con lo stdin in pipe oppure con il percorso o i percorsi dei file di input posizionali. Le eventuali ulteriori vie, tramite flag o posizione, dichiarate dall’argomento sono elencate accanto.
• Opzioni obbligatorie: gli argomenti non principali che sono required senza default_value. Ogni invocazione deve fornire ciascuno di essi; se ne manca uno, il controllo preliminare fallisce con un errore che nomina il flag dell’opzione (oppure la posizione, o la forma --arg), il suo media URN e la sua descrizione, raggruppati sotto “missing required options”. Le opzioni con un valore predefinito non vengono mai richieste né menzionate in quell’errore.
• Opzioni: gli argomenti rimanenti, elencati con i loro valori predefiniti (oppure indicati come facoltativi quando non ne hanno).
• Output (disciplina della pipe): un singolo risultato scalare viene trasmesso GREZZO su stdout; le sequenze e i fan-out scrivono file ({input}.{node}[.{i}].{ext}) ed elencano i loro percorsi su stdout. Log e avanzamento vanno su stderr.

Le cap astratte (gli ombrelli di dispatch convert-image, convert-audio, disbind, extract-frames ed extract-audio-track) vengono ristrette qui: capdag risolve l’alias nella cap astratta, rileva il media dell’input e restringe alla cap concreta tramite is_dispatchable (vedi Dispatch §”Cap astratte”). Un bersaglio ambiguo viene risolto con --to <ext|media-urn>; uno non risolvibile fallisce in modo netto.

Ripiego sullo sviluppo locale. Se il token nomina una cap che il fabric non definisce, capdag ripiega sul manifest di una cartuccia installata localmente in sviluppo (eseguita tramite il suo alias) ed esegue quella cap attraverso l’host completo, a condizione che la cap non sia in conflitto con il fabric (nessun suo alias indica già una cap diversa a monte). È questo che permette di sviluppare ed eseguire una cap nuovissima prima ancora che venga pubblicata. Vedi Costruisci ed esegui una cartuccia.

capdag run <machine-file> …

Esegue un grafo di flusso dei dati .machine. Mappe, raccolte, fan-out e macchine incluse vengono pianificati ed eseguiti dall’orchestratore condiviso. I flag vengono riconosciuti in qualsiasi posizione: run m.machine input --force e run --force m.machine input sono equivalenti.

Input. Gli input di una macchina sono le sue ancore di input (Notazione delle macchine).

• --input <node>=<value> fornisce l’input che la notazione chiama <node>: @<path> legge un file, qualsiasi altra cosa è il valore stesso (--input window=20). Dati più volte per un nodo, i valori sono una sequenza. Un nome che la macchina non ha viene rifiutato, indicando quelli che ha.
• Un percorso posizionale, o un token di sorgente dal vivo, va all’input a cui il suo media rilevato è conforme più da vicino, fra gli input che --input non ha nominato. Quando è conforme allo stesso modo a più input l’esecuzione viene rifiutata, indicandoli. Un input a cui sono dati più percorsi li prende come una sola sequenza.
• Una macchina con esattamente un input, a cui sono dati più percorsi e nient’altro, viene eseguita una volta per percorso.
• A ogni input deve essere dato qualcosa; una macchina che parte da una sorgente (() -> step -> ..., o un passo a cui sono date solo costanti) non ne prende nessuno.

Output. Gli output di una macchina sono le sue ancore di output. Un output che contiene un solo valore va su stdout. Tutto il resto viene scritto come file nella directory di output, uno per elemento, con nome {input_stem}.{output}[.{index}].{ext}: {output} è il nome che la notazione dà al nodo di output, e ogni percorso scritto viene stampato su stdout. Un output che non è stato prodotto, perché il ramo che lo genera non è scattato, non scrive nulla e viene nominato su stderr. Una macchina che termina in un pozzo (... -> step -> ()) non ha output.

Macchine incluse. Il riferimento dell’intestazione di una macchina (Notazione delle macchine) viene letto come un percorso relativo al file che lo ha scritto.

Tutto il resto è nel file. Una macchina eseguita dalla riga di comando è autosufficiente: ogni argomento di ogni passo è legato nella notazione (a un nodo o a una costante), oppure ha un valore predefinito. Un argomento obbligatorio che non è né l’uno né l’altro è un errore di pre-controllo che nomina il passo e l’argomento, e come dirlo: una costante nel wiring, o un nodo fornito con --input.

Come termina un’esecuzione.

Un passo che è stato saltato viene nominato su stderr insieme ai valori che attendeva, con i nomi che la macchina dà loro.

Ctrl-C su un’esecuzione dal vivo. Il primo Ctrl-C è la chiusura degli input (15.2 §Le esecuzioni si arrestano): ogni input dal vivo viene fermato e la CLI stampa il verdetto ricevuto: Input stopped: N host tap(s) closed, M feed request(s) stopped, M ended; the run is draining to complete outputs., oppure il rifiuto (Stop input refused: no live input is open on this run, oppure un’alimentazione che non è terminata entro il timeout di svuotamento, indicata per nome). L’esecuzione quindi si svuota ed emette i suoi output. Un secondo Ctrl-C, in qualsiasi momento (anche mentre il primo arresto sta ancora attendendo la sua conferma), interrompe con un Cancel attribuito a user (codice di uscita 130). Gli stessi due controlli valgono per la modalità a cap singola con una sorgente dal vivo.

capdag plan <files...> [--to <t>]... [options]

Il planner unificato e configurabile su un insieme di file (gli stessi PlanEngine/LiveCapFab che pilotano le procedure guidate del motore). Prima di ogni altra cosa, plan riscalda le cache del fabric a partire dal manifest fissato (il riscaldamento che il motore esegue all’avvio; il recupero di una cap è atomico insieme alle definizioni di media che essa referenzia, ed è questo che popola l’indice delle estensioni) e rileva ogni input con la rilevazione del motore discriminata sul contenuto: candidati per estensione → scelta strutturale di base → discriminazione statica tramite validation su un prefisso limitato del contenuto. La rilevazione è deterministica; un input la cui estensione non è nota al fabric è un errore netto che nomina l’estensione, mai un media: nudo e silenzioso.

• Scoperta (senza --to): elenca ogni bersaglio raggiungibile per l’insieme (i bersagli convergenti sono contrassegnati con il loro apice), con stime dei passi.
• --to <t>: t viene risolto come: prima un alias di media registrato (un token nudo; i nomi degli alias non contengono mai :), altrimenti un URN di media (contiene :), altrimenti l’abbreviazione per estensione di file (png → media:ext=png). Il risultato viene confrontato con i bersagli RAGGIUNGIBILI:
  • equivalente a un nodo raggiungibile → pianifica direttamente verso di esso;
  • più generale, esattamente un nodo conforme → restringe a quel nodo (stderr annota la risoluzione) e pianifica;
  • più generale, diversi nodi conformi → non c’è modo di sapere quale percorso voglia l’utente, quindi ogni macchina candidata viene stampata come notazione delle macchine eseguibile (raggruppata sotto intestazioni # target: <urn>) e il comando termina con codice 0; l’utente sceglie salvando la notazione che vuole ed eseguendola con capdag run;
  • nulla è conforme → errore netto (codice di uscita 1) che rimanda alla scoperta.
• Scelta: i candidati vengono ordinati e stampati con la loro notazione. --pick <rank> ne seleziona uno; non esiste una scelta predefinita: --save / --run con diversi candidati e senza un --pick esplicito rifiutano (codice di uscita 1) invece di agire in silenzio sul candidato 0.
• Parametri di regolazione: --converge auto|combine|independent, --where auto|earliest|latest|source|target|depth=N, --mechanism any|generalize|collect|merge, --rank intent|shortest|cost, --depth, --max-paths, --max; qualsiasi parametro esplicito porta la richiesta in modalità Configured.

capdag dag-viz <machine-file> [--mermaid|--dot]

Rappresenta il piano di esecuzione completo della macchina (MachinePlan) come diagramma: i passi, i loro altri output, le mappe con i loro elementi, le raccolte, gli input e gli output, e gli archi tipizzati. Le macchine incluse sono disegnate come i passi che sono. --mermaid (predefinito) emette Mermaid; --dot emette Graphviz DOT.

capdag find <cap-alias-or-urn>

Risolve una cap e stampa quale o quali cartucce del registro la forniscono (e se è disponibile un eseguibile firmato per questa piattaforma), senza scaricare nulla.

capdag resolve [--no-cache] <cap-alias-or-urn>...

Stampa il JSON della definizione canonica della cap, risolta tramite il registro del fabric incorporato: la stessa definizione usata da ogni mirror. Le cartucce lo usano per (ri)generare gli snapshot delle definizioni di cap che incorporano. Passando più token viene stampato un array JSON di definizioni di cap (un solo processo, una sola lettura del manifest); la generazione degli snapshot di una cartuccia risolve in questo modo un intero cap-aliases.txt in un’unica chiamata raggruppata. --no-cache forza un nuovo recupero, scavalcando la cache su disco indicizzata per versione (che un canale di staging mutabile può lasciare non aggiornata).

capdag cache [clear|refresh]

Gestisce la cache locale del fabric indicizzata per versione. clear la svuota (in memoria e su disco, manifest compreso); refresh (il predefinito) la svuota e poi recupera di nuovo il manifest, così il comando successivo parte rinnovato. Usalo dopo che un canale ripubblica con la stessa versione del manifest.

capdag install <cap-alias-or-urn-or-cartridge-id>

Risolve, scarica e verifica una cartuccia (catena di firme + hash) senza eseguire nulla, come riscaldamento della cache. Stampa il percorso dell’eseguibile installato.

capdag new <name> --<language> [-o <dir>]

Crea lo scheletro di un nuovo progetto di cartuccia in <dir>/<name>/ (il <dir> predefinito è la directory corrente). Scegli esattamente uno fra --python, --rust, --go o --swift; non c’è un linguaggio predefinito. Ogni opzione produce lo stesso contratto di capacità iniziale attraverso il runtime di quel linguaggio e scrive le relative istruzioni di build e di sviluppo. <name> deve essere uno slug minuscolo e sicuro come percorso ([a-z0-9] con separatori -/_). Vedi Costruisci ed esegui una cartuccia.

capdag dev-install <project-dir>

Installa o aggiorna una cartuccia di sviluppo sotto lo slug riservato dev della radice delle cartucce per utente, così che l’host la scopra. capdag legge il manifest del progetto (eseguendo il sottocomando manifest del suo punto d’ingresso), verifica che nessuna delle sue cap sia in conflitto con il fabric, quindi la colloca in ~/.capdag/cartridges/dev/v{CARTRIDGE_REGISTRY_VERSION}/{channel}/{name}/{version}/ con un record di installazione cartridge.json (registry_url: null). Eseguirlo di nuovo sovrascrive la stessa directory di versione; questo è il passo di aggiornamento del ciclo modifica/reinstallazione. <project-dir> è per impostazione predefinita ..

capdag self update

Sostituisce questo capdag — l’eseguibile e la bundled-cartridges/ accanto a esso — con l’ultima release del canale su cui è stato pubblicato. Stampa capdag <old> -> <new>, oppure capdag <version> is the latest release quando non c’è nulla di più recente.

Legge il manifest delle release del registro in cui questo capdag è stato pubblicato, e installa una release solo quando vale tutto questo:

• la firma del manifest risale alle chiavi radice compilate in questo capdag: un certificato per la chiave di release, firmato da due di quelle radici, per l’ambiente di firma di questa build e valido ora, e il manifest firmato da quella chiave di release;
• il bundle ha la dimensione e il digest SHA-256 che il manifest elenca;
• l’eseguibile nel bundle si avvia e riporta la versione con cui è stato pubblicato.

Altrimenti non viene installato nulla, il motivo viene stampato e lo stato di uscita è 1. Il nuovo bundle prende il posto del vecchio dove si trova il vecchio: prima le cartucce, poi l’eseguibile. Un aggiornamento interrotto lascia un bundle che funziona, e il successivo capdag self update rimette a posto o ripulisce ciò che ha lasciato (in .capdag-update/, accanto all’eseguibile). Su Windows l’eseguibile in esecuzione non può essere rimosso: viene lasciato accanto al nuovo come capdag.exe.old, e l’aggiornamento successivo lo rimuove.

Due tipi di capdag non vengono aggiornati in questo modo, e dicono che cosa li aggiorna:

Il capdag di un gestore di pacchetti viene riconosciuto dal file installed-by che il suo pacchetto mette accanto all’eseguibile. Un bundle installato dove non puoi scrivere viene aggiornato con gli stessi diritti con cui è stato installato. self è un sottocomando, quindi un alias di cap chiamato self si esegue con il suo URN.

Opzioni globali

La radice delle cartucce per utente

capdag ospita le cartucce da ~/.capdag/cartridges/, usando lo stesso albero suddiviso per registro, versione e canale che usa ogni host: {registry_slug}/v{CARTRIDGE_REGISTRY_VERSION}/{channel}/{name}/{version}/. Lo slug dev è riservato alle cartucce costruite localmente (registry_url: null); vedi Anatomia di una cartuccia per la scoperta e per la struttura di slug e versioni.