COMP_cli_adr-001 – Command Registration via Autodiscovery

Status: ACCEPTED Date: 2026-03-16 Author: xPulse

Context

@xpulse/cli needs a mechanism to aggregate commands from various xParts without having to depend on them – and without boilerplate in every xPart.

Additionally, a command should be fully abstracted from CLI internals: no import of @xpulse/event, no manual emission of cli:done, no knowledge of timeout mechanisms.

Decision

@xpulse/cli is a runner – not a command owner.

• Each xPart places command classes under src/commands/
• @xpulse/cli discovers all node_modules/@xpulse/*/src/commands/*.js on startup
• Found Command subclasses are registered automatically
• No cli.js in the xPart root required

1
@xpulse/cli  discovers  →  @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('Fetch docs via git archive')
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(); // ← no event import required
19
        }
20
        output.success('Done!');
21
        return 0; // ← exit code instead of cli:done event
22
    }
23
}

Full Abstraction

A command imports nothing from @xpulse/event and knows nothing about CLI internals. @xpulse/cli handles everything:

Exit Codes

run() returns a numeric exit code – the well-known Unix scheme:

@xpulse/cli calls process.exit(exitCode) after run(). No cli:done event – run() resolves and the process ends.

`cli:keepalive` – internal

cli:keepalive continues to exist as an internal event in @xpulse/cli. xParts do not see it – they call this.keepAlive(), and the base class emits the event internally via an injected function.

`--help` + `--list`

1
xpulse --help              # all commands with name, alias, description
2
xpulse --help doc:fetch    # command detail with arguments, options, flags, example
3
xpulse --list              # names only, machine-readable – for autocomplete/scripting

Dependencies

1
@xpulse/cli  →  @xpulse/event   ← internal for keepAlive

Rationale

• Single Responsibility – each xPart fully owns its commands
• Zero Coupling – @xpulse/cli knows no other xParts
• Full Abstraction – a command knows nothing about events, timeouts, or process termination; run() simply returns an exit code
• No Boilerplate – no cli.js, no cli:done, no event import
• Self-describing – configure() holds everything: name, alias, description, help text, arguments, options, flags
• Known scheme – exit codes 0/1/2 are Unix standard, universally understood
• keepAlive() injected rather than imported – command stays decoupled, CLI stays in control of the timer
• --list for tooling – machine-readable output enables shell autocomplete and external tools without HTML-parsing of --help

Consequences

• Every xPart that provides CLI commands places them under src/commands/
• One file = one command class (convention)
• run() always returns an exit code (0/1/2)
• this.keepAlive() for long-running tasks – no event import required
• @xpulse/cli is a dependency in xParts that write commands
• xpulse --help and xpulse --list are dynamic – show only what is installed

Alternatives Rejected

• cli.js in the root – boilerplate, manual event binding in every xPart
• cli:done event from the command – command must import @xpulse/event; exit code as return value is simpler and more universal
• static name/description – not extensible for arguments/options/flags/alias
• cli:keepalive directly in the command – command must know the event system; this.keepAlive() via injection is cleaner
• Hard timeout without keepalive – would abort long-running tasks
• @xpulse/config as dependency – CLI is global, no guaranteed project context