@sandro-sikic/maker 1.0.7 → 1.0.9

package/README.md

@@ -0,0 +1,244 @@
+# Maker
+
+A lightweight library for building interactive command-line tools with ease.
+
+[![npm version](https://img.shields.io/npm/v/@sandro-sikic/maker)](https://www.npmjs.com/package/@sandro-sikic/maker)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+## Features
+
+✨ **Simple API** - Just 5 core functions to build powerful CLI tools  
+🎯 **Interactive Prompts** - Built-in support for user input via [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js)  
+⚡ **Command Execution** - Run shell commands with streaming output  
+🎨 **Beautiful Spinners** - Visual feedback with [ora](https://github.com/sindresorhus/ora)  
+🛡️ **Graceful Shutdown** - Automatic cleanup on exit signals  
+📘 **TypeScript Support** - Full type definitions included
+
+## Installation
+
+```bash
+npm install @sandro-sikic/maker
+```
+
+## Quick Start
+
+```javascript
+import * as maker from '@sandro-sikic/maker';
+
+// Initialize CLI environment
+maker.init();
+
+// Prompt user for input
+const name = await maker.prompt.input({
+	message: 'What is your project name?',
+});
+
+// Show progress with spinner
+const loading = maker.spinner('Creating project...').start();
+
+// Run shell commands
+await maker.run(`mkdir ${name}`);
+await maker.run(`cd ${name} && npm init -y`);
+
+loading.succeed('Project created! 🎉');
+```
+
+## API Overview
+
+### Core Functions
+
+| Function             | Description                                        |
+| -------------------- | -------------------------------------------------- |
+| `init()`             | Validates interactive terminal environment         |
+| `run(command, opts)` | Executes shell commands with streaming output      |
+| `onExit(callback)`   | Registers cleanup function for graceful shutdown   |
+| `prompt.*`           | Interactive prompts (input, select, confirm, etc.) |
+| `spinner(text)`      | Creates terminal loading indicators                |
+
+### Example: Simple Build Tool
+
+```javascript
+import * as maker from '@sandro-sikic/maker';
+
+async function build() {
+	maker.init();
+
+	// Register cleanup
+	maker.onExit(() => {
+		console.log('Cleanup complete');
+	});
+
+	// Confirm action
+	const shouldBuild = await maker.prompt.confirm({
+		message: 'Start build?',
+		default: true,
+	});
+
+	if (!shouldBuild) return;
+
+	// Execute with spinner
+	const building = maker.spinner('Building...').start();
+	const result = await maker.run('npm run build');
+
+	if (result.isError) {
+		building.fail('Build failed!');
+		process.exit(1);
+	}
+
+	building.succeed('Build complete!');
+}
+
+build();
+```
+
+## Documentation
+
+📖 **[Complete Usage Guide](./docs/USAGE.md)** - Detailed documentation with examples  
+⚡ **[API Quick Reference](./docs/API.md)** - Fast lookup for all functions
+
+## API Details
+
+### `init()`
+
+Ensures your CLI is running in an interactive terminal. Always call this first.
+
+```javascript
+maker.init();
+```
+
+### `run(command, opts)`
+
+Execute shell commands with real-time output streaming.
+
+```javascript
+const result = await maker.run('npm test');
+
+if (result.isError) {
+	console.error('Command failed:', result.stderr);
+}
+```
+
+**Returns:** `{ output, stdout, stderr, code, isError, error }`
+
+### `onExit(callback)`
+
+Register cleanup handlers for graceful shutdown (SIGINT, SIGTERM, SIGQUIT).
+
+```javascript
+maker.onExit(async () => {
+	await closeDatabase();
+	await stopServer();
+});
+```
+
+### `prompt.*`
+
+Interactive prompts powered by [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js):
+
+```javascript
+await maker.prompt.input({ message: 'Name?' });
+await maker.prompt.confirm({ message: 'Continue?' });
+await maker.prompt.select({ message: 'Choose:', choices: [...] });
+await maker.prompt.checkbox({ message: 'Select:', choices: [...] });
+await maker.prompt.password({ message: 'API key:' });
+```
+
+### `spinner(text)`
+
+Create terminal spinners with [ora](https://github.com/sindresorhus/ora):
+
+```javascript
+const s = maker.spinner('Loading...').start();
+s.succeed('Done!'); // ✔
+s.fail('Failed!'); // ✖
+s.warn('Warning!'); // ⚠
+s.info('Info!'); // ℹ
+```
+
+## Real-World Example
+
+```javascript
+import * as maker from '@sandro-sikic/maker';
+
+async function setupProject() {
+	maker.init();
+
+	// Get project configuration
+	const config = {
+		name: await maker.prompt.input({
+			message: 'Project name:',
+		}),
+		framework: await maker.prompt.select({
+			message: 'Framework:',
+			choices: [
+				{ name: 'React', value: 'react' },
+				{ name: 'Vue', value: 'vue' },
+				{ name: 'Angular', value: 'angular' },
+			],
+		}),
+		features: await maker.prompt.checkbox({
+			message: 'Features:',
+			choices: [
+				{ name: 'TypeScript', value: 'typescript' },
+				{ name: 'ESLint', value: 'eslint' },
+				{ name: 'Testing', value: 'testing' },
+			],
+		}),
+	};
+
+	// Confirm setup
+	const proceed = await maker.prompt.confirm({
+		message: 'Create project?',
+		default: true,
+	});
+
+	if (!proceed) {
+		console.log('Cancelled');
+		return;
+	}
+
+	// Setup with progress indicators
+	const setup = maker.spinner('Creating project...').start();
+
+	await maker.run(`mkdir ${config.name}`);
+	setup.text = 'Installing dependencies...';
+	await maker.run(`cd ${config.name} && npm init -y`);
+	await maker.run(`cd ${config.name} && npm install ${config.framework}`);
+
+	for (const feature of config.features) {
+		setup.text = `Installing ${feature}...`;
+		await maker.run(`cd ${config.name} && npm install ${feature}`);
+	}
+
+	setup.succeed('Project ready! 🚀');
+	console.log(`\nNext:\n  cd ${config.name}\n  npm start`);
+}
+
+setupProject();
+```
+
+## TypeScript
+
+Full TypeScript support with included type definitions:
+
+```typescript
+import { run, RunResult, Ora } from '@sandro-sikic/maker';
+
+const result: RunResult = await run('echo "Hello"');
+const spinner: Ora = maker.spinner('Loading...');
+```
+
+## Repository
+
+[github.com/sandro-sikic/maker](https://github.com/sandro-sikic/maker)
+
+## License
+
+ISC
+
+## Credits
+
+Built with:
+
+- [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js) - Interactive prompts
+- [ora](https://github.com/sindresorhus/ora) - Terminal spinners

package/docs/API.md

@@ -0,0 +1,191 @@
+# Maker - API Quick Reference
+
+Quick reference guide for `@sandro-sikic/maker` functions.
+
+---
+
+## `init()`
+
+Validates interactive terminal environment. **Call first** in your CLI app.
+
+```javascript
+maker.init();
+```
+
+Exits with code 1 if not running in an interactive terminal (TTY).
+
+---
+
+## `run(command, opts)`
+
+Execute shell commands with streaming output.
+
+```javascript
+const result = await run('npm install', { maxLines: 10000 });
+```
+
+**Parameters:**
+
+- `command` - Shell command string (required)
+- `opts.maxLines` - Max output lines to capture (default: 10000)
+
+**Returns:**
+
+```javascript
+{
+  output: string,      // Combined stdout + stderr
+  stdout: string,      // Standard output
+  stderr: string,      // Standard error
+  code: number|null,   // Exit code
+  isError: boolean,    // true if failed
+  error: Error|null    // Spawn error if any
+}
+```
+
+**Usage patterns:**
+
+```javascript
+// Foreground (waits for completion)
+await run('npm test');
+
+// Background (non-blocking)
+run('npm run dev');
+
+// Error handling
+const result = await run('npm build');
+if (result.isError) {
+	console.error('Failed:', result.stderr);
+}
+```
+
+---
+
+## `onExit(callback)`
+
+Register cleanup function for graceful shutdown.
+
+```javascript
+onExit(async () => {
+	await cleanup();
+});
+```
+
+**Parameters:**
+
+- `callback` - Sync or async cleanup function
+
+**Returns:**
+
+- Unregister function
+
+**Triggers on:**
+
+- SIGINT (Ctrl+C)
+- SIGTERM
+- SIGQUIT
+
+---
+
+## `prompt.*`
+
+Interactive prompts ([inquirer](https://github.com/SBoudrias/Inquirer.js/tree/master/packages/prompts)).
+
+```javascript
+// Text input
+await prompt.input({ message: 'Name?' });
+
+// Yes/no
+await prompt.confirm({ message: 'Continue?' });
+
+// Select one
+await prompt.select({
+  message: 'Choose:',
+  choices: [
+    { name: 'Option 1', value: '1' },
+    { name: 'Option 2', value: '2' }
+  ]
+});
+
+// Select multiple
+await prompt.checkbox({
+  message: 'Select:',
+  choices: [...]
+});
+
+// Password
+await prompt.password({ message: 'API key:' });
+
+// Number
+await prompt.number({ message: 'Port:', default: 3000 });
+```
+
+---
+
+## `spinner(text)`
+
+Terminal spinner ([ora](https://github.com/sindresorhus/ora)).
+
+```javascript
+const s = spinner('Loading...').start();
+
+// Update text
+s.text = 'Still loading...';
+
+// Complete
+s.succeed('Done!'); // ✔
+s.fail('Failed!'); // ✖
+s.warn('Warning!'); // ⚠
+s.info('Info!'); // ℹ
+s.stop(); // Stop and clear
+```
+
+---
+
+## Complete Example
+
+```javascript
+import * as maker from '@sandro-sikic/maker';
+
+// 1. Initialize
+maker.init();
+
+// 2. Register cleanup
+maker.onExit(async () => {
+	console.log('Cleaning up...');
+});
+
+// 3. Prompt user
+const name = await maker.prompt.input({
+	message: 'Project name:',
+	default: 'my-app',
+});
+
+const confirmed = await maker.prompt.confirm({
+	message: 'Install dependencies?',
+});
+
+// 4. Run commands with spinner
+if (confirmed) {
+	const s = maker.spinner('Installing...').start();
+
+	const result = await maker.run(`npm create ${name}`);
+
+	if (result.isError) {
+		s.fail('Installation failed');
+		process.exit(1);
+	}
+
+	s.succeed('Installation complete!');
+}
+```
+
+---
+
+## TypeScript Types
+
+```typescript
+import type { RunResult, Ora } from '@sandro-sikic/maker';
+
+// Also exports all @inquirer/prompts types
+import type { ConfirmPrompt, InputPrompt } from '@sandro-sikic/maker';
+```