Anleitung

Installation

@xpulse/cli wird lokal im Projekt installiert – kein globales Install nötig.

1 npm install @xpulse/cli

Wichtig: Die package.json des Projekts muss "type": "module" enthalten, da das gesamte xPulse Ökosystem ESM (import/export) verwendet:

1 {
2   "name": "mein-projekt",
3   "type": "module",
4   "dependencies": {
5     "@xpulse/cli": "^1.0.0"
6   }
7 }

Aufruf – immer mit `npx`

@xpulse/cli wird immer via npx aufgerufen. npx nutzt die lokale Version aus node_modules/.bin/xpulse – konsistent, reproduzierbar, kein Versions-Mismatch.

1 npx xpulse --version
2 npx xpulse --list
3 npx xpulse --help
4 npx xpulse --help tapp:hello
5 npx xpulse tapp:hello --help
6 npx xpulse tapp:hello Johnny -lang="en" --shout -V

Wie funktioniert das?

@xpulse/cli startet und discovert automatisch alle Command-Klassen:

1 npx xpulse doc:fetch chat --dry-run
2   ↓
3 @xpulse/cli discovert:
4   1. node_modules/@xpulse/*/src/commands/*.js  ← installierte xParts
5   2. src/commands/*.js                          ← lokales Projekt
6  
7   → findet FetchCommand (name = 'doc:fetch')
8   → baut Input + Output auf, injiziert keepAlive
9   → new FetchCommand().run(input, output)
10   ↓
11 FetchCommand.run() führt aus → return 0
12   ↓
13 @xpulse/cli → process.exit(0)

Einen Command schreiben

Datei unter src/commands/ anlegen, Command extenden – fertig. @xpulse/cli findet sie automatisch.

1 // src/commands/HelloCommand.js
2 import { Command } from '@xpulse/cli/command';
3  
4 export class HelloCommand extends Command {
5  
6     configure() {
7         this
8             .setName('tapp:hello')
9             .setAlias('hi')
10             .setDescription('Sag Hallo')
11             .setHelp('Gibt eine Begrüßung aus.')
12             .addArgument('name',  'Anon', 'Name des Empfängers')
13             .addOption('lang',    'de',   'Sprache (de/en)')
14             .addFlag('shout',     false,  'In Großbuchstaben');
15     }
16  
17     async run(input, output) {
18         const name  = input.getArgument('name');
19         const shout = input.getFlag('shout');
20         let msg     = `Hallo ${name}!`;
21  
22         if (shout) msg = msg.toUpperCase();
23         output.success(msg);
24         return 0;
25     }
26 }

Kein import event, kein cli:done emittieren – run() gibt einfach einen Exit Code zurück.

Argument vs. Option vs. Flag

Typ	Definition	Aufruf
Argument	`addArgument('name', ...)`	`npx xpulse cmd Johnny` (positional)
Option	`addOption('lang', ...)`	`npx xpulse cmd -lang="en"`
Flag	`addFlag('shout', ...)`	`npx xpulse cmd --shout`

Wichtig: Optionen müssen immer mit = übergeben werden:

1 npx xpulse tapp:hello -lang="en"    # ✓ korrekt
2 npx xpulse tapp:hello --lang="en"   # ✓ korrekt
3 npx xpulse tapp:hello -lang en      # ✗ Warnung – "en" wird als positionales Argument interpretiert
4 npx xpulse tapp:hello --lang en     # ✗ Warnung – "en" wird als positionales Argument interpretiert

Bei falschem Syntax gibt @xpulse/cli eine Warnung aus:

1 ! Ungültige Syntax: "--lang en" – meintest du --lang="en"?
2   "en" wird als positionales Argument interpretiert.

`--help` für einen Command

Beide Varianten sind gleichwertig:

1 npx xpulse --help tapp:hello   # Flag vor dem Command-Namen
2 npx xpulse tapp:hello --help   # Flag nach dem Command-Namen

Exit Codes

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

Long-running Commands

Commands die länger als CLI_TIMEOUT (Default: 30s) laufen, rufen periodisch this.keepAlive() auf um den Timeout zurückzusetzen:

1 async run(input, output) {
2     while (!done) {
3         await doWork();
4         this.keepAlive(); // Timeout zurücksetzen – kein Event-Import nötig
5     }
6     return 0;
7 }

Timeout konfigurieren

1 CLI_TIMEOUT=60 npx xpulse repo:changelog:generate

1	{
2	"name": "mein-projekt",
3	"type": "module",
4	"dependencies": {
5	"@xpulse/cli": "^1.0.0"
6	}
7	}

1	npx xpulse --version
2	npx xpulse --list
3	npx xpulse --help
4	npx xpulse --help tapp:hello
5	npx xpulse tapp:hello --help
6	npx xpulse tapp:hello Johnny -lang="en" --shout -V

1	npx xpulse doc:fetch chat --dry-run
2	↓
3	@xpulse/cli discovert:
4	1. node_modules/@xpulse//src/commands/.js ← installierte xParts
5	2. src/commands/*.js ← lokales Projekt
6
7	→ findet FetchCommand (name = 'doc:fetch')
8	→ baut Input + Output auf, injiziert keepAlive
9	→ new FetchCommand().run(input, output)
10	↓
11	FetchCommand.run() führt aus → return 0
12	↓
13	@xpulse/cli → process.exit(0)

1	// src/commands/HelloCommand.js
2	import { Command } from '@xpulse/cli/command';
3
4	export class HelloCommand extends Command {
5
6	configure() {
7	this
8	.setName('tapp:hello')
9	.setAlias('hi')
10	.setDescription('Sag Hallo')
11	.setHelp('Gibt eine Begrüßung aus.')
12	.addArgument('name', 'Anon', 'Name des Empfängers')
13	.addOption('lang', 'de', 'Sprache (de/en)')
14	.addFlag('shout', false, 'In Großbuchstaben');
15	}
16
17	async run(input, output) {
18	const name = input.getArgument('name');
19	const shout = input.getFlag('shout');
20	let msg = `Hallo ${name}!`;
21
22	if (shout) msg = msg.toUpperCase();
23	output.success(msg);
24	return 0;
25	}
26	}

1	npx xpulse tapp:hello -lang="en" # ✓ korrekt
2	npx xpulse tapp:hello --lang="en" # ✓ korrekt
3	npx xpulse tapp:hello -lang en # ✗ Warnung – "en" wird als positionales Argument interpretiert
4	npx xpulse tapp:hello --lang en # ✗ Warnung – "en" wird als positionales Argument interpretiert

1	! Ungültige Syntax: "--lang en" – meintest du --lang="en"?
2	"en" wird als positionales Argument interpretiert.

1	npx xpulse --help tapp:hello # Flag vor dem Command-Namen
2	npx xpulse tapp:hello --help # Flag nach dem Command-Namen

1	async run(input, output) {
2	while (!done) {
3	await doWork();
4	this.keepAlive(); // Timeout zurücksetzen – kein Event-Import nötig
5	}
6	return 0;
7	}