COMP_cli_adr-001 – Command-Registrierung via Autodiscovery

Status: ACCEPTED Datum: 2026-03-16 Autor: xPulse

Kontext

@xpulse/cli braucht einen Mechanismus um Commands aus verschiedenen xParts zusammenzuführen ohne von ihnen abhängen zu müssen – und ohne Boilerplate in jedem xPart.

Zusätzlich soll ein Command vollständig von CLI-Internals abstrahiert sein: kein Import von @xpulse/event, kein manuelles Emittieren von cli:done, kein Wissen über Timeout-Mechanismen.

Entscheidung

@xpulse/cli ist ein Runner – kein Command-Owner.

Jedes xPart legt Command-Klassen unter src/commands/ ab
@xpulse/cli discovert beim Start alle node_modules/@xpulse/*/src/commands/*.js
Gefundene Command-Subklassen werden automatisch registriert
Kein cli.js im xPart-Root nötig

1 @xpulse/cli  discovert  →  @xpulse/doc/src/commands/FetchCommand.js
2                         →  @xpulse/config/src/commands/ConfigShowCommand.js

Command-Contract

1 import { Command } from '@xpulse/cli/command';
2  
3 export class FetchCommand extends Command {
4  
5     configure() {
6         this
7             .setName('doc:fetch')
8             .setAlias('df')
9             .setDescription('Docs via git archive fetchen')
10             .addArgument('tool',  null,  'Tool name')
11             .addOption('tag',     null,  'Git tag')
12             .addFlag('dry-run',   false, 'Dry run');
13     }
14  
15     async run(input, output) {
16         while (!done) {
17             await doWork();
18             this.keepAlive(); // ← kein Event-Import nötig
19         }
20         output.success('Fertig!');
21         return 0; // ← Exit Code statt cli:done Event
22     }
23 }

Vollständige Abstraktion

Ein Command importiert nichts von @xpulse/event und weiß nichts von CLI-Internals. @xpulse/cli übernimmt alles:

Aufgabe	Wer macht es
Autodiscovery	`@xpulse/cli`
Input aufbauen	`@xpulse/cli`
Output aufbauen	`@xpulse/cli`
`keepAlive`-Funktion injizieren	`@xpulse/cli`
Timer starten + stoppen	`@xpulse/cli`
`process.exit(code)`	`@xpulse/cli`
Logik implementieren	xPart

Exit Codes

run() gibt einen numerischen Exit Code zurück – bekanntes Unix-Schema:

Code	Bedeutung
`0`	Erfolg
`1`	Fehler
`2`	Misuse – falsche oder fehlende Argumente

@xpulse/cli ruft process.exit(exitCode) nach run() auf. Kein cli:done Event – run() resolved und der Prozess endet.

`cli:keepalive` – intern

cli:keepalive existiert weiterhin als internes Event in @xpulse/cli. xParts sehen es nicht – sie rufen this.keepAlive() auf, die Basisklasse emittiert das Event intern via eine injizierte Funktion.

`--help` + `--list`

1 xpulse --help              # alle Commands mit Name, Alias, Description
2 xpulse --help doc:fetch    # Command-Detail mit Arguments, Options, Flags, Beispiel
3 xpulse --list              # nur Namen, maschinenlesbar – für Autocomplete/Scripting

Dependencies

1 @xpulse/cli  →  @xpulse/event   ← intern für keepAlive

Begründung

Single Responsibility – jedes xPart besitzt seine Commands vollständig
Zero Coupling – @xpulse/cli kennt keine anderen xParts
Vollständige Abstraktion – Command weiß nichts von Events, Timeouts oder Prozess-Beendigung; run() gibt einfach einen Exit Code zurück
Kein Boilerplate – kein cli.js, kein cli:done, kein Event-Import
Self-describing – configure() hält alles: Name, Alias, Description, Help-Text, Arguments, Options, Flags
Bekanntes Schema – Exit Codes 0/1/2 sind Unix-Standard, jeder kennt sie
keepAlive() injiziert statt importiert – Command bleibt entkoppelt, CLI bleibt Herr über den Timer
--list für Tooling – maschinenlesbare Ausgabe ermöglicht Shell-Autocomplete und externe Tools ohne HTML-Parsing von --help

Konsequenzen

Jedes xPart das CLI-Commands anbietet, legt sie unter src/commands/ ab
Eine Datei = eine Command-Klasse (Convention)
run() gibt immer einen Exit Code zurück (0/1/2)
this.keepAlive() für long-running Tasks – kein Event-Import nötig
@xpulse/cli ist Dependency in xParts die Commands schreiben
xpulse --help und xpulse --list sind dynamisch – zeigen nur was installiert ist

Alternativen die verworfen wurden

cli.js im Root – Boilerplate, manuelles Event-Binding in jedem xPart
cli:done Event vom Command – Command muss @xpulse/event importieren; Exit Code als Return-Wert ist einfacher und universeller
static name/description – nicht erweiterbar für Arguments/Options/Flags/Alias
cli:keepalive direkt im Command – Command muss Event-System kennen; this.keepAlive() via Injection ist sauberer
Harter Timeout ohne Keepalive – würde long-running Tasks abbrechen
@xpulse/config als Dependency – CLI ist global, kein garantierter Projekt-Kontext

1	@xpulse/cli discovert → @xpulse/doc/src/commands/FetchCommand.js
2	→ @xpulse/config/src/commands/ConfigShowCommand.js

1	import { Command } from '@xpulse/cli/command';
2
3	export class FetchCommand extends Command {
4
5	configure() {
6	this
7	.setName('doc:fetch')
8	.setAlias('df')
9	.setDescription('Docs via git archive fetchen')
10	.addArgument('tool', null, 'Tool name')
11	.addOption('tag', null, 'Git tag')
12	.addFlag('dry-run', false, 'Dry run');
13	}
14
15	async run(input, output) {
16	while (!done) {
17	await doWork();
18	this.keepAlive(); // ← kein Event-Import nötig
19	}
20	output.success('Fertig!');
21	return 0; // ← Exit Code statt cli:done Event
22	}
23	}

1	xpulse --help # alle Commands mit Name, Alias, Description
2	xpulse --help doc:fetch # Command-Detail mit Arguments, Options, Flags, Beispiel
3	xpulse --list # nur Namen, maschinenlesbar – für Autocomplete/Scripting