# @push.rocks/smartcli

Build small, reactive command-line tools in TypeScript without hand-rolling argument dispatch. `@push.rocks/smartcli` parses the current runtime's user arguments, dispatches the first positional command into an RxJS `Subject`, exposes the parsed `yargs-parser` result to your handler, and gives you a clean fallback path when no command is provided.

It is ESM-first, ships TypeScript declarations, and handles user argument slicing across Node.js, Deno, Deno-compiled executables, Bun, `tsx`, and `ts-node`.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```sh
pnpm add @push.rocks/smartcli
```

## Why Use Smartcli

- Reactive command handlers: every command is an RxJS `Subject`, so command execution fits naturally into observable-based code.
- Tiny API surface: register commands, subscribe handlers, and call `startParse()`.
- Runtime-aware argument handling: Node.js, Deno, Deno-compiled binaries, Bun, `tsx`, and `ts-node` get user-only arguments consistently.
- `yargs-parser` integration: flags and positional arguments arrive as a familiar parsed object.
- Built-in standard command, help command, version output, manual triggering, and parse completion hooks.

## Quick Start

Create a CLI entrypoint, for example `cli.ts`:

```ts
#!/usr/bin/env node
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addVersion('1.0.0');

cli.addHelp({
  helpText: `
Usage:
  demo greet --name Ada
  demo --version
  demo help

Commands:
  greet    Print a greeting
  help     Print this help text
`,
});

cli.addCommand('greet').subscribe((argv) => {
  const name = argv.name || 'World';
  console.log(`Hello, ${name}!`);
});

cli.standardCommand().subscribe(() => {
  console.log('Usage: demo greet --name Ada');
  console.log('Run "demo help" for details.');
});

cli.startParse();
```

When exposed as a package `bin`, the CLI behaves like this:

```sh
demo greet --name Ada
# Hello, Ada!

demo --version
# 1.0.0

demo help
# prints the configured help text
```

## Terminal Task Rendering

Use `SmartcliTerminal` for long-running jobs that should render cleanly in both interactive and non-interactive environments. In a TTY, active tasks render below each other with a fixed row count, colored status symbols, and elapsed time. In CI, pipes, Docker logs, or `TERM=dumb`, the same calls become throttled append-only lifecycle logs.

```ts
import { SmartcliTerminal } from '@push.rocks/smartcli';

const terminal = new SmartcliTerminal();

const buildTask = terminal.task('Build package', {
  rows: 3,
});

buildTask.update('Installing dependencies');
buildTask.setProgress(1, 2, 'Running tsbuild');
buildTask.complete('Build finished');

const publishTask = terminal.createProcess({
  job: 'Publish package',
  rows: 4,
});

try {
  await publishPackage();
  publishTask.complete('Published');
} catch (error) {
  publishTask.attachError(error);
}
```

Completed tasks collapse into one permanent success line. Failed tasks collapse into one permanent failure line with error details. If an error should remain visible inside the live task area, use `attachError(error, { keepOpen: true })`.

For scoped work, `task.run()` completes or fails automatically:

```ts
await terminal.task('Generate assets').run(async (task) => {
  task.setProgress(1, 3, 'Reading source files');
  await readSourceFiles();
  task.setProgress(2, 3, 'Rendering assets');
  await renderAssets();
  task.setProgress(3, 3, 'Writing output');
}, { successMessage: 'Assets generated' });
```

## Execution Model

1. Create a `Smartcli` instance.
2. Register all commands before parsing.
3. Subscribe handlers to the returned command subjects.
4. Call `startParse()` once to parse the current runtime arguments.
5. `startParse()` parses user args with `yargs-parser`.
6. The first positional argument, `argv._[0]`, is treated as the command name.
7. A matching command subject receives the parsed `argv` object through `.next(argv)`.
8. If no command is provided, the subject from `standardCommand()` is triggered when it exists.
9. After normal dispatch, `parseCompleted.promise` resolves with the parsed argument object.

`startParse()` dispatches synchronously. If a handler starts asynchronous work, manage that lifecycle in your application code.

## Commands and Options

Options are available directly on the parsed object handed to your subscription:

```ts
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('deploy').subscribe((argv) => {
  const environment = argv.env || 'development';
  const force = Boolean(argv.force);

  console.log(`Deploying to ${environment}`);

  if (force) {
    console.log('Force mode enabled');
  }
});

cli.standardCommand().subscribe(() => {
  console.log('Usage: deployer deploy --env production [--force]');
});

cli.startParse();
```

Run it with:

```sh
deployer deploy --env production --force
```

The handler receives a `yargs-parser` result similar to:

```ts
{
  _: ['deploy'],
  env: 'production',
  force: true
}
```

## Positional Arguments

The first positional argument selects the command. Additional positional values remain in `argv._`:

```ts
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('run').subscribe((argv) => {
  const taskName = argv._[1];

  if (!taskName) {
    console.log('Usage: tool run <taskName>');
    return;
  }

  console.log(`Running task: ${taskName}`);
});

cli.startParse();
```

```sh
tool run build
# Running task: build
```

## Standard Command

Use `standardCommand()` for the no-command case:

```ts
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('status').subscribe(() => {
  console.log('Everything is operational.');
});

cli.standardCommand().subscribe(() => {
  console.log('Available commands: status');
});

cli.startParse();
```

If no standard command is registered and the user runs the CLI without a command, smartcli prints `no smartcli standard task was created or assigned.`.

## Help and Version Output

`addVersion()` enables `-v` and `--version` when no command is provided:

```ts
cli.addVersion('2.3.0');
```

```sh
tool --version
# 2.3.0
```

`addHelp()` registers a `help` command. It does not create a `--help` flag:

```ts
cli.addHelp({
  helpText: `
Usage:
  tool build --target app
  tool status
`,
});
```

```sh
tool help
```

## Programmatic Dispatch

Use `triggerCommand()` when you want to invoke a registered command yourself, for example in orchestration code or focused tests:

```ts
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('build').subscribe((argv) => {
  console.log(`Building ${argv.target}`);
});

cli.triggerCommand('build', {
  _: ['build'],
  target: 'docs',
});
```

`triggerCommand()` throws if the command has not been registered.

## Testing CLIs

`startParse()` accepts an optional `argv` override. Pass a full runtime-style argument array for deterministic tests:

```ts
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();
const parsedPromise = cli.parseCompleted.promise;

cli.addCommand('publish').subscribe((argv) => {
  console.log(`Publishing with tag ${argv.tag}`);
});

cli.startParse(['node', 'test-cli.js', 'publish', '--tag', 'next']);

const parsed = await parsedPromise;
console.log(parsed.tag);
// next
```

Create a fresh `Smartcli` instance per parse. `parseCompleted` is a single deferred value on the instance and resolves once.

## Cross-Runtime Argument Handling

smartcli uses `getUserArgs()` internally to remove runtime-specific executable and script entries before parsing:

| Runtime mode | Argument strategy |
| --- | --- |
| Deno without an explicit test argv | Uses `Deno.args`, which is already user-only. |
| Node.js | Uses `process.argv` and skips executable plus script path for known launchers. |
| Bun | Uses `process.argv` and skips executable plus script path for known launchers. |
| `tsx` and `ts-node` | Treated as known launchers and parsed like Node.js. |
| Unknown compiled executable | Skips only the executable path, keeping the first user argument intact. |

This matters for compiled CLIs where `process.argv[0]` is the binary itself and the first user argument should not be mistaken for a script path.

## Aliases

The class exposes `addCommandAlias(original, alias)` and the public `aliasObject` for keeping alias metadata:

```ts
cli.addCommandAlias('deploy', 'd');
console.log(cli.aliasObject.deploy);
// ['d']
```

Current command dispatch is exact-match based on `argv._[0]`. If you want executable aliases, register the alias as a command and subscribe it to the same handler:

```ts
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

const deploy = (argv: any) => {
  console.log(`Deploying ${argv.target || 'default target'}`);
};

cli.addCommand('deploy').subscribe(deploy);
cli.addCommand('d').subscribe(deploy);
cli.addCommandAlias('deploy', 'd');

cli.startParse();
```

## API Reference

| API | Purpose |
| --- | --- |
| `new Smartcli()` | Creates an isolated CLI parser and command registry. |
| `addCommand(commandName)` | Registers a command and returns its RxJS `Subject`. If the command already exists, the existing subject is reused. |
| `standardCommand()` | Registers and returns the fallback subject for runs without a command. |
| `startParse(testArgv?)` | Parses current user args, or the provided full argv array, and dispatches to the matching command. |
| `triggerCommand(commandName, argvObject)` | Manually emits an argv object into a registered command subject. |
| `getCommandSubject(commandName)` | Returns the subject for a registered command or `null`. |
| `getOption(optionName)` | Parses current runtime args and returns one option by name. Inside command handlers, prefer the provided `argv` object. |
| `addHelp({ helpText })` | Registers a `help` command that logs the provided help text. |
| `addVersion(version)` | Stores the version printed by `-v` or `--version` when no command is selected. |
| `addCommandAlias(original, alias)` | Stores alias metadata in `aliasObject`. Register alias command names separately for direct dispatch. |
| `parseCompleted.promise` | Resolves with the parsed argv object after normal `startParse()` dispatch. |

## Practical Example

This example wires a tiny task runner with commands, options, help, version output, and a standard fallback:

```ts
#!/usr/bin/env node
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

const tasks = new Map<string, () => Promise<void> | void>([
  ['build', () => console.log('Building project...')],
  ['test', () => console.log('Running tests...')],
  ['release', () => console.log('Preparing release...')],
]);

cli.addVersion('1.4.0');

cli.addHelp({
  helpText: `
Task Runner

Usage:
  tasker list
  tasker run <taskName> [--dry]
  tasker --version

Available tasks:
  build
  test
  release
`,
});

cli.addCommand('list').subscribe(() => {
  for (const taskName of tasks.keys()) {
    console.log(taskName);
  }
});

cli.addCommand('run').subscribe(async (argv) => {
  const taskName = argv._[1];
  const dryRun = Boolean(argv.dry);

  if (!taskName) {
    console.log('Usage: tasker run <taskName> [--dry]');
    return;
  }

  const task = tasks.get(taskName);

  if (!task) {
    console.log(`Unknown task: ${taskName}`);
    return;
  }

  if (dryRun) {
    console.log(`Would run task: ${taskName}`);
    return;
  }

  await task();
});

cli.standardCommand().subscribe(() => {
  console.log('Usage: tasker <list|run|help>');
});

cli.startParse();
```

## Sharp Edges Worth Knowing

- Register commands before calling `startParse()`.
- `startParse()` dispatches once; create a new `Smartcli` instance for a second parse.
- `addHelp()` registers the `help` command, not a `--help` option.
- `addVersion()` prints only when no positional command is present.
- `getOption()` reads the current runtime args. In command subscriptions, use the `argv` object you receive for the most testable code.
- Alias metadata is stored, but aliases are not automatically dispatched unless you register the alias command name too.
- smartcli does not validate option schemas. Add validation in your own command handlers when inputs matter.

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH  
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.