promappjs

promappjs is a secure, interactive CLI framework for building terminal apps with prompts, chat loops, shells, and command-based CLIs.

Features

• Interactive prompts: input, password, confirm, select, and multiselect
• Command-based CLI apps with subcommands and hooks
• Chat-style terminal sessions
• Shell-style terminal sessions with line buffering
• Simple per-app storage through app.data(), chat.data(), and shell.data()

Install

npm install promappjs

Usage

This package is published as an ES module.

import proma from 'promappjs';

const app = proma.app({
  name: 'my-cli',
  version: '1.0.0'
});

app.command('hello <name>')
  .description('Say hello')
  .action(async (name) => {
    console.log(`Hello, ${name}`);
  });

await app.start(['hello', 'Danny']);

Prompt API

import proma from 'promappjs';

const name = await proma.input('What is your name?');
const secret = await proma.password('Enter secret:');
const confirmed = await proma.confirm('Proceed?');
const color = await proma.select('Favorite color?', ['Red', 'Blue', 'Green']);
const toppings = await proma.multiselect('Choose toppings:', ['Cheese', 'Pepperoni', 'Olives']);

// Batch prompt example
const { host, port, username, password } = await proma.ask([
  { input: 'host: ', required: 1 },
  { input: 'port' },
  { input: 'username' },
  { password: 'password: ' }
]);

CLI Apps

Create a CLI app with commands, options, hooks, and persistent storage:

import proma from 'promappjs';

const app = proma.app({
  name: 'secure-cli',
  version: '1.0.0'
});

const storage = app.data();

app.before(async (command, args, options) => {
  console.log(`Running ${command.name}`);
});

app.command('login <token>')
  .description('Save an API token')
  .action(async (token) => {
    await storage.set('api_token', token);
    console.log('Token saved');
  });

app.command('get-token')
  .description('Read the saved token')
  .action(async () => {
    const token = await storage.get('api_token');
    console.log(token);
  });

await app.start();

CLI Options

• app.option(flags, description) adds a global option
• command.option(flags, description) adds a command-specific option
• app.before(fn) registers a hook before command execution
• app.onError(fn) registers an error handler
• app.addCommand(command) attaches a nested command group

Chat Sessions

import proma from 'promappjs';

const chat = proma.chat({
  name: 'assistant',
  userPrompt: 'You: ',
  botPrompt: 'AI: '
});

chat.onMessage(async (input) => {
  console.log(`${chat.botPrompt}I heard: ${input}`);
});

chat.onExit(() => {
  console.log('Bye');
});

chat.start();

Type exit or quit to leave the session.

Shell Sessions

import proma from 'promappjs';

const shell = proma.shell({
  name: 'sql-client',
  prompt: 'sql> ',
  delimiter: ';'
});

shell.onLine(async (line) => {
  console.log(`Executing: ${line}`);
});

shell.start();

API

The default export includes:

• proma.app(options)
• proma.chat(options)
• proma.shell(options)
• proma.input(message)
• proma.password(message)
• proma.ask(prompts)
• proma.confirm(message)
• proma.select(message, choices)
• proma.multiselect(message, choices)
• proma.command(nameAndArgs)

You can also import individual helpers:

import { app, chat, shell, input, password, ask, confirm, select, multiselect } from 'promappjs';

Development

npm test

This runs the included example script.

License

MIT