@xpulse/cli – Component Spec

1
xpulse doc:fetch chat -tag="v1.3.0" --dry-run -V
2
  ↓
3
@xpulse/cli          discovers node_modules/@xpulse/*/src/commands/*.js
4
                     finds FetchCommand (name = 'doc:fetch' from configure())
5
                     builds Input + Output, injects keepAlive
6
                     calls new FetchCommand().run(input, output)
7
  ↓
8
FetchCommand.run()   executes, returns exit code
9
  ↓
10
@xpulse/cli          process.exit(code)

1
@xpulse/cli
2
  └── @xpulse/event   ← cli:keepalive (internal, xParts do not see this)

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('Fetch docs via git archive')
10
            .setHelp('Fetches docs from an xPulse repo and stores them locally.')
11
            .addArgument('tool',     null,    'Name of the tool (e.g. chat)')
12
            .addOption('tag',        null,    'Git tag to fetch')
13
            .addFlag('dry-run',      false,   'Simulate only, write nothing');
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(); // Reset timeout
23
        }
24
 
25
        output.success('Done!');
26
        return 0;
27
    }
28
}

1
input.getArgument('tool')     // positional argument by name
2
input.getOption('tag')        // -key=value, kebab-case or camelCase
3
input.hasOption('tag')        // → true | false
4
input.getFlag('dryRun')       // --flag, kebab-case or camelCase
5
input.isVerbose()             // --verbose / -V
6
input.isQuiet()               // --quiet / -q
7
input.isAnsi()                // false if --no-ansi

1
output.write('...')           // without line break
2
output.writeln('...')         // with line break
3
output.success('...')         // ✓ green
4
output.warn('...')            // ! yellow
5
output.error('...')           // ✗ red – ignores --quiet
6
output.table(headers, rows)   // formatted table

1
xpulse --help              # all commands with name, alias, description
2
xpulse --help doc:fetch    # name, alias, description, help text,
3
                           # usage example, 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   ← installed xParts
2
2. src/commands/*.js                           ← local project

1
CLI_TIMEOUT=30   # seconds, default: 30

1
xpulse doc:fetch chat -tag="v1.3.0" --dry-run -V
2
  ↓
3
@xpulse/cli starts
4
  → discovers node_modules/@xpulse/*/src/commands/*.js
5
  → parses input → { name: 'doc:fetch', args: { tag: 'v1.3.0', dryRun: true },
6
                    rawArguments: ['chat'], verbose: true, ansi: true }
7
  → finds FetchCommand (name = 'doc:fetch')
8
  → builds Input + Output
9
  → injects 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       ← entry point: autodiscovery, parser, Input/Output, timeout
4
  src/
5
    command.js      ← Command base class with configure(), keepAlive(), run()
6
    input.js        ← Input class: getArgument, getOption, getFlag, isVerbose ...
7
    output.js       ← Output class + internal helpers (--help, --list, --version)
8
    loader.js       ← find + import node_modules/@xpulse/*/src/commands/*.js
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": "my-project",
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"   # ✓ correct
2
npx xpulse cmd --name="Johnny"  # ✓ correct
3
npx xpulse cmd -name Johnny     # ✗ warning – Johnny is interpreted as positional argument
4
npx xpulse cmd --name Johnny    # ✗ warning – Johnny is interpreted as positional argument

1
! Invalid syntax: "--name Johnny" – did you mean --name="Johnny"?
2
  "Johnny" is interpreted as a positional argument.