https://github.com/stone-foundation/stone-js-node-cli-adapter
CLI adapter for Stone.js. Enables command-line execution and custom commands using the Continuum Architecture.
https://github.com/stone-foundation/stone-js-node-cli-adapter
cli cli-app context-aware javascript official-stonejs stone-foundation stonejs stonejs-adapter typescript
Last synced: 11 months ago
JSON representation
CLI adapter for Stone.js. Enables command-line execution and custom commands using the Continuum Architecture.
- Host: GitHub
- URL: https://github.com/stone-foundation/stone-js-node-cli-adapter
- Owner: stone-foundation
- License: mit
- Created: 2024-12-04T15:25:56.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-13T02:26:46.000Z (about 1 year ago)
- Last Synced: 2025-06-13T02:27:19.749Z (about 1 year ago)
- Topics: cli, cli-app, context-aware, javascript, official-stonejs, stone-foundation, stonejs, stonejs-adapter, typescript
- Language: TypeScript
- Homepage: https://stonejs.dev
- Size: 752 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Stone.js - Node CLI Adapter
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@stone-js/node-cli-adapter)
[](https://www.npmjs.com/package/@stone-js/node-cli-adapter)
[](https://github.com/stone-foundation/stone-js-node-cli-adapter/actions/workflows/main.yml)
[](https://github.com/stone-foundation/stone-js-node-cli-adapter/actions/workflows/release.yml)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-node-cli-adapter)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-node-cli-adapter)
[](./SECURITY.md)
[](https://github.com/stone-foundation/stone-js-node-cli-adapter/security/code-scanning)
[](https://github.com/stone-foundation/stone-js-node-cli-adapter/network/updates)
[](https://conventionalcommits.org)
The **Node CLI Adapter** enables you to run Stone.js applications in a command-line interface (CLI) context, transforming user-defined or custom commands into system-executable events.
---
## Introduction
In the Continuum Architecture, adapters are responsible for translating external context into normalized system events. The Node CLI Adapter takes terminal input, parsed arguments and commands, and turns them into `IncomingEvent` objects that your system can handle.
This allows you to:
* Build CLI tools, scripts, or developer utilities with Stone.js
* Define custom commands and map them to handlers
* Leverage Stone.js's lifecycle, configuration, and event system in the terminal
---
## Installation
```bash
npm install @stone-js/node-cli-adapter
```
> This package is **pure ESM**. Ensure your project is ESM-compatible (`"type": "module"` in `package.json`) or configure your tooling accordingly.
## Usage
You can activate the adapter using either the declarative or imperative API.
### Declarative API
```ts
import { NodeConsole } from '@stone-js/node-cli-adapter'
import { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'
@StoneApp()
@NodeConsole()
export class Application implements IEventHandler {
handle(event: IncomingEvent) {
console.log('CLI event received:', event.get('command'))
return { status: 'ok' }
}
}
```
### Imperative API
```ts
import { defineStoneApp, IncomingEvent } from '@stone-js/core'
import { nodeConsoleAdapterBlueprint } from '@stone-js/node-cli-adapter'
const handler = (event: IncomingEvent) => {
console.log('Running CLI command:', event.get('command'))
return { status: 'done' }
}
export const MyCLIApp = defineStoneApp(handler, {}, [nodeConsoleAdapterBlueprint])
```
## What It Enables
* **Universal CLI Entry Point**
Use the same `defineStoneApp` structure as other environments, just change the adapter.
* **Custom Commands**
Register your own CLI commands using `defineCommand()` or `@Command()`, and bind them to handlers in your system.
* **Runtime Argument Parsing**
Inputs from the terminal are automatically parsed and mapped into an `IncomingEvent`, with parameters available via `.get()`.
* **Cross-platform Logic**
You can reuse the same handler logic between CLI and server, the adapter abstracts away the runtime.
## Configuration Options
The CLI adapter supports command registration via metadata or blueprint configuration.
To register commands imperatively:
```ts
import { defineConfig, IBlueprint } from '@stone-js/core'
import { defineCommand, NODE_CONSOLE_PLATFORM } from '@stone-js/node-cli-adapter'
export const AppConfig = defineConfig({
afterConfigure (blueprint: IBlueprint) {
if (blueprint.is('stone.adapter.platform', NODE_CONSOLE_PLATFORM)) {
blueprint.set(defineCommand(handler, { name: '*' }))
}
}
})
```
> You can also register commands using metadata decorators. See the main Stone.js documentation on [Command Handlers](https://stonejs.dev/docs/deeper/commands) for more.
## Summary
The `@stone-js/node-cli-adapter` lets you run your Stone.js system as a CLI, turning terminal arguments and commands into system-level events. It enables you to reuse your event-handling logic, configuration, and hooks across environments without rewriting platform-specific glue code.
This adapter is ideal for scripting, developer tooling, generators, or any use case where your application lives in the terminal.
## API documentation
* [API](https://github.com/stone-foundation/stone-js-node-cli-adapter/blob/main/docs)
## Contributing
We welcome contributions! See the [Contributing Guide](https://github.com/stone-foundation/stone-js-node-cli-adapter/blob/main/CONTRIBUTING.md) for details.