@portel/cli 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,172 @@
+# @portel/cli
+
+CLI toolkit for building beautiful terminal applications. Provides formatting, progress indicators, fuzzy matching, and logging utilities.
+
+## Part of the Portel Ecosystem
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     @portel/cli (this package)                  │
+│            CLI utilities: formatting, progress, logging         │
+└─────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                        @portel/mcp                              │
+│              MCP protocol: client, transport, config            │
+└─────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     @portel/photon-core                         │
+│         Core library: schema extraction, generators, UI         │
+└─────────────────────────────────────────────────────────────────┘
+                              ▲
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+┌───────┴───────┐    ┌───────┴───────┐    ┌───────┴───────┐
+│ @portel/photon│    │    lumina     │    │ @portel/ncp   │
+│  CLI + BEAM   │    │  REST runtime │    │ MCP orchestr. │
+└───────────────┘    └───────────────┘    └───────────────┘
+```
+
+**Use this package if:** You're building CLI tools and need beautiful output formatting, spinners, or fuzzy matching.
+
+## Installation
+
+```bash
+npm install @portel/cli
+```
+
+## Features
+
+### Output Formatting
+
+Format data as tables, trees, lists, or cards with automatic detection.
+
+```typescript
+import { formatOutput, renderTable, renderTree } from '@portel/cli';
+
+// Auto-detect format based on data shape
+formatOutput([{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]);
+
+// Explicit formats
+formatOutput(data, 'table');  // Bordered table
+formatOutput(data, 'tree');   // Indented tree
+formatOutput(data, 'list');   // Bullet list
+formatOutput(data, 'json');   // Pretty JSON
+```
+
+### Progress Indicators
+
+Show spinners and progress bars for long-running operations.
+
+```typescript
+import { startSpinner, stopProgress, showProgress } from '@portel/cli';
+
+// Simple spinner
+startSpinner('Loading...');
+await doWork();
+stopProgress();
+
+// With progress updates
+showProgress('Processing files', 0, 100);
+for (let i = 0; i <= 100; i++) {
+  await processFile(i);
+  showProgress('Processing files', i, 100);
+}
+stopProgress();
+```
+
+### Status Messages
+
+Print colored status messages.
+
+```typescript
+import { printSuccess, printError, printInfo, printWarning } from '@portel/cli';
+
+printSuccess('Operation completed');  // ✓ green
+printError('Something failed');       // ✗ red
+printInfo('FYI...');                  // ℹ blue
+printWarning('Be careful');           // ⚠ yellow
+```
+
+### Fuzzy Matching
+
+Find similar strings for "did you mean?" suggestions.
+
+```typescript
+import { FuzzyMatcher, findBestMatch } from '@portel/cli';
+
+const matcher = new FuzzyMatcher();
+const suggestions = matcher.findSuggestions('helo', ['hello', 'help', 'world']);
+// => ['hello', 'help']
+
+// Or simple best match
+const best = findBestMatch('get-usrs', ['get-users', 'get-posts', 'delete-user']);
+// => 'get-users'
+```
+
+### Text Utilities
+
+Word wrapping, truncation, and formatting helpers.
+
+```typescript
+import { TextUtils } from '@portel/cli';
+
+TextUtils.wrap('Long text...', { width: 80 });
+TextUtils.truncate('Very long string', 20);
+TextUtils.padRight('Name', 10);
+```
+
+### Logging
+
+Structured logging with levels and formatting.
+
+```typescript
+import { createLogger } from '@portel/cli';
+
+const logger = createLogger({ level: 'debug' });
+logger.debug('Detailed info');
+logger.info('General info');
+logger.warn('Warning');
+logger.error('Error occurred');
+```
+
+## API Reference
+
+### Formatting Functions
+
+| Function | Description |
+|----------|-------------|
+| `formatOutput(data, hint?)` | Auto-format and print data |
+| `detectFormat(data)` | Detect best format for data |
+| `renderTable(data)` | Render bordered table |
+| `renderTree(data)` | Render indented tree |
+| `renderList(items)` | Render bullet list |
+| `renderCard(data)` | Render key-value card |
+
+### Progress Functions
+
+| Function | Description |
+|----------|-------------|
+| `startSpinner(message)` | Start a spinner |
+| `showProgress(label, current, total)` | Show progress bar |
+| `updateProgressMessage(message)` | Update spinner text |
+| `stopProgress()` | Stop spinner/progress |
+| `isProgressActive()` | Check if progress is active |
+
+### Status Functions
+
+| Function | Description |
+|----------|-------------|
+| `printSuccess(message)` | Print success (green ✓) |
+| `printError(message)` | Print error (red ✗) |
+| `printInfo(message)` | Print info (blue ℹ) |
+| `printWarning(message)` | Print warning (yellow ⚠) |
+| `printHeader(text)` | Print section header |
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "CLI toolkit for building terminal applications - formatting, progress, fuzzy matching, logging",
   "type": "module",
   "main": "dist/index.js",