@xpulse/cli – Component Spec

1
xpulse doc:fetch chat -tag="v1.3.0" --dry-run -V
2
  ↓
3
@xpulse/cli          discovert node_modules/@xpulse/*/src/commands/*.js
4
                     findet FetchCommand (name = 'doc:fetch' aus configure())
5
                     baut Input + Output auf, injiziert keepAlive
6
                     ruft new FetchCommand().run(input, output) auf
7
  ↓
8
FetchCommand.run()   führt aus, gibt Exit Code zurück
9
  ↓
10
@xpulse/cli          process.exit(code)

1
@xpulse/cli
2
  └── @xpulse/event   ← cli:keepalive (intern, xParts sehen das nicht)

1
xpulse namespace:area:command [arguments] [-option="value"] [--flag] [-V] [-q]

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
            .setHelp('Fetcht Docs aus einem xPulse Repo und legt sie lokal ab.')
11
            .addArgument('tool',     null,    'Name des Tools (z.B. chat)')
12
            .addOption('tag',        null,    'Git-Tag zum Fetchen')
13
            .addFlag('dry-run',      false,   'Nur simulieren, nichts schreiben');
14
    }
15
 
16
    async run(input, output) {
17
        const tool   = input.getArgument('tool');
18
        const dryRun = input.getFlag('dryRun');
19
 
20
        while (!done) {
21
            await doWork();
22
            this.keepAlive(); // Timeout zurücksetzen
23
        }
24
 
25
        output.success('Fertig!');
26
        return 0;
27
    }
28
}

1
input.getArgument('tool')     // positionales Argument per Name
2
input.getOption('tag')        // -key=value, kebab-case oder camelCase
3
input.hasOption('tag')        // → true | false
4
input.getFlag('dryRun')       // --flag, kebab-case oder camelCase
5
input.isVerbose()             // --verbose / -V
6
input.isQuiet()               // --quiet / -q
7
input.isAnsi()                // false wenn --no-ansi

1
output.write('...')           // ohne Zeilenumbruch
2
output.writeln('...')         // mit Zeilenumbruch
3
output.success('...')         // ✓ grün
4
output.warn('...')            // ! gelb
5
output.error('...')           // ✗ rot – ignoriert --quiet
6
output.table(headers, rows)   // formatierte Tabelle

1
xpulse --help              # alle Commands mit Name, Alias, Description
2
xpulse --help doc:fetch    # Name, Alias, Description, Help-Text,
3
                           # Ausführungsbeispiel, Arguments, Options, Flags

1
xpulse --list
2
# doc:fetch
3
# doc:fetch:changelog
4
# project:config:show
5
# repo:changelog:generate

1
1. node_modules/@xpulse/*/src/commands/*.js   ← installierte xParts
2
2. src/commands/*.js                           ← lokales Projekt

1
CLI_TIMEOUT=30   # Sekunden, Default: 30

1
xpulse doc:fetch chat -tag="v1.3.0" --dry-run -V
2
  ↓
3
@xpulse/cli startet
4
  → discovert node_modules/@xpulse/*/src/commands/*.js
5
  → parst Input → { name: 'doc:fetch', args: { tag: 'v1.3.0', dryRun: true },
6
                    rawArguments: ['chat'], verbose: true, ansi: true }
7
  → findet FetchCommand (name = 'doc:fetch')
8
  → baut Input + Output auf
9
  → injiziert cmd._keepAliveFn = startTimer
10
  → startTimer()
11
  → exitCode = await cmd.run(input, output)
12
  → clearTimeout + process.exit(exitCode)

1
@xpulse/cli/
2
  bin/
3
    xpulse.js       ← Einstiegspunkt: Autodiscovery, Parser, Input/Output, Timeout
4
  src/
5
    command.js      ← Command-Basisklasse mit configure(), keepAlive(), run()
6
    input.js        ← Input-Klasse: getArgument, getOption, getFlag, isVerbose ...
7
    output.js       ← Output-Klasse + interne Helfer (--help, --list, --version)
8
    loader.js       ← node_modules/@xpulse/*/src/commands/*.js finden + importieren
9
    parser.js       ← CLI-Input → { name, args, rawArguments, verbose, quiet, ansi }
10
  docs/
11
    index.md
12
    de/ index, guide, api, schema
13
    en/ index, guide, api, schema
14
  test/
15
    command.test.js
16
    input.test.js
17
    parser.test.js
18
    loader.test.js
19
  README.md
20
  package.json
21
  xpulse.json

1
npm install @xpulse/cli

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 doc:fetch
5
npx xpulse doc:fetch chat -tag="v1.3.0" --dry-run

1
npx xpulse cmd -name="Johnny"   # ✓ korrekt
2
npx xpulse cmd --name="Johnny"  # ✓ korrekt
3
npx xpulse cmd -name Johnny     # ✗ Warnung – Johnny wird als positionales Argument interpretiert
4
npx xpulse cmd --name Johnny    # ✗ Warnung – Johnny wird als positionales Argument interpretiert

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