npm package: @maybenoobish/synapse-cli
Description: A powerful CLI for the Synapse framework
Author: Synapse Team
Latest version: 1.0.15

# Synapse CLI

A powerful, feature-rich command-line interface for the Synapse framework. Built with pure Node.js APIs and zero external dependencies for core functionality.

[![npm version](https://img.shields.io/npm/v/@maybenoobish/synapse-cli.svg)](https://www.npmjs.com/package/@maybenoobish/synapse-cli)
[![npm downloads](https://img.shields.io/npm/dm/@maybenoobish/synapse-cli.svg)](https://www.npmjs.com/package/@maybenoobish/synapse-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Bun](https://img.shields.io/badge/Bun-1.0+-black?logo=bun)](https://bun.sh)

## Features

- 🚀 **Project Scaffolding** - Create new Synapse projects with multiple templates
- 📦 **Package Management** - Add packages and features with intelligent dependency resolution
- 🔧 **Development Server** - Start development servers with hot reload and file watching
- 🎨 **Rich UI** - Beautiful, colorful output with progress indicators and interactive prompts
- 🔌 **Plugin System** - Extensible architecture with plugin support
- 🛠️ **Zero Dependencies** - Core functionality uses only built-in Node.js APIs
- ⚡ **Fast Startup** - Optimized for speed with lazy loading and caching
- 🎯 **Type Safe** - Full TypeScript support with comprehensive type definitions

## Installation

### Global Installation

```bash
# Using Bun (recommended)
bun install -g @maybenoobish/synapse-cli

# Using npm
npm install -g @maybenoobish/synapse-cli

# Using pnpm
pnpm install -g @maybenoobish/synapse-cli

# Using yarn
yarn global add @maybenoobish/synapse-cli
```

### Local Installation

```bash
# Using Bun
bun add -D @maybenoobish/synapse-cli

# Using npm
npm install -D @maybenoobish/synapse-cli

# Using pnpm
pnpm add -D @maybenoobish/synapse-cli

# Using yarn
yarn add -D @maybenoobish/synapse-cli
```

## Quick Start

### Create a New Project

```bash
# Create a basic project
synapse create my-app

# Create with specific template
synapse create my-app --template full

# Create with custom configuration
synapse create my-app --template minimal --package-manager npm --no-git
```

### Start Development

```bash
# Start development server
synapse dev

# Start with custom port
synapse dev --port 3001

# Start with HTTPS
synapse dev --https --open
```

### Add Features

```bash
# Add a package
synapse add @maybenoobish/synapse-ui

# Add a feature with interactive setup
synapse add auth --interactive

# Add as dev dependency
synapse add typescript --dev
```

## Commands

### `synapse create <name>`

Create a new Synapse project with the specified name.

**Options:**
- `--template, -t` - Project template (basic, full, minimal, api)
- `--package-manager, -p` - Package manager (bun, npm, pnpm, yarn)
- `--no-git` - Skip Git initialization
- `--no-install` - Skip dependency installation
- `--yes, -y` - Skip confirmation prompts
- `--author` - Project author
- `--description` - Project description
- `--license` - Project license

**Examples:**
```bash
synapse create my-app
synapse create my-app --template full --package-manager npm
synapse create my-app --template minimal --no-git --yes
```

### `synapse add <package>`

Add a package or feature to your project.

**Options:**
- `--dev, -D` - Add as dev dependency
- `--version, -v` - Package version
- `--interactive, -i` - Interactive mode
- `--provider` - Provider for feature packages
- `--config` - Configuration file path
- `--yes, -y` - Skip confirmation prompts

**Examples:**
```bash
synapse add @synapse/ui
synapse add auth --provider auth0 --interactive
synapse add typescript --dev --version ^5.0.0
```

### `synapse dev`

Start the development server.

**Options:**
- `--port, -p` - Port number (default: 3000)
- `--host, -h` - Host address (default: localhost)
- `--https` - Enable HTTPS
- `--open, -o` - Open browser automatically
- `--watch, -w` - Watch for file changes
- `--hot-reload` - Enable hot module replacement
- `--sourcemap` - Generate source maps
- `--debug` - Enable debug mode
- `--verbose, -v` - Enable verbose output

**Examples:**
```bash
synapse dev
synapse dev --port 3001 --host 0.0.0.0
synapse dev --https --open --debug
```

### `synapse build`

Build the project for production.

**Options:**
- `--target` - Build target (browser, node, edge)
- `--minify` - Enable minification
- `--sourcemap` - Generate source maps
- `--splitting` - Enable code splitting
- `--outdir` - Output directory
- `--watch` - Watch mode

**Examples:**
```bash
synapse build
synapse build --target browser --minify
synapse build --watch --sourcemap
```

### `synapse test`

Run tests using Bun's test runner.

**Options:**
- `--watch` - Watch mode
- `--coverage` - Generate coverage report
- `--parallel` - Run tests in parallel
- `--timeout` - Test timeout
- `--reporter` - Test reporter

**Examples:**
```bash
synapse test
synapse test --watch --coverage
synapse test --parallel --timeout 10000
```

### `synapse deploy <platform>`

Deploy the application to a platform.

**Options:**
- `--config` - Deployment configuration
- `--env` - Environment variables
- `--build` - Build before deploy
- `--preview` - Preview deployment

**Examples:**
```bash
synapse deploy vercel
synapse deploy netlify --config netlify.toml
synapse deploy cloudflare --env production
```

## Project Templates

### Basic Template

A minimal Synapse project with essential files and configuration.

```
my-app/
├── src/
│   ├── index.ts
│   └── app.ts
├── package.json
├── tsconfig.json
├── synapse.config.ts
└── README.md
```

### Full Template

A complete Synapse project with all features and examples.

```
my-app/
├── src/
│   ├── components/
│   ├── pages/
│   ├── utils/
│   ├── types/
│   ├── index.ts
│   └── app.ts
├── public/
│   └── index.html
├── package.json
├── tsconfig.json
├── synapse.config.ts
└── README.md
```

### Minimal Template

A bare-bones project for advanced users.

```
my-app/
├── src/
│   └── index.ts
├── package.json
└── README.md
```

### API Template

A backend-only project for API development.

```
my-app/
├── src/
│   ├── routes/
│   ├── middleware/
│   ├── models/
│   └── index.ts
├── package.json
└── README.md
```

## Configuration

### synapse.config.ts

The main configuration file for your Synapse project.

```typescript
import type { CLIConfig } from '@maybenoobish/synapse-cli';

export default {
  project: {
    name: 'my-synapse-app',
    version: '1.0.0',
    description: 'A Synapse application',
    author: 'Developer',
    license: 'MIT'
  },
  build: {
    target: 'browser',
    minify: true,
    sourcemap: true,
    splitting: true
  },
  dev: {
    port: 3000,
    host: 'localhost',
    https: false,
    open: true
  },
  deploy: {
    platform: 'vercel',
    config: {}
  },
  plugins: []
} satisfies CLIConfig;
```

### Environment Variables

The CLI respects the following environment variables:

- `SYNAPSE_PORT` - Development server port
- `SYNAPSE_HOST` - Development server host
- `SYNAPSE_HTTPS` - Enable HTTPS
- `SYNAPSE_OPEN` - Open browser automatically
- `SYNAPSE_TARGET` - Build target
- `SYNAPSE_MINIFY` - Enable minification
- `SYNAPSE_SOURCEMAP` - Generate source maps
- `SYNAPSE_PLATFORM` - Deploy platform
- `SYNAPSE_DEBUG` - Enable debug mode
- `SYNAPSE_VERBOSE` - Enable verbose output

## Plugin System

The Synapse CLI supports a powerful plugin system for extending functionality.

### Creating a Plugin

```typescript
// my-plugin.ts
import type { Plugin, PluginAPI } from '@synapse/cli';

export const myPlugin: Plugin = {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'My custom plugin',
  hooks: {
    beforeCommand: async (command, args, flags) => {
      console.log(`Running command: ${command}`);
    },
    afterCommand: async (command, args, flags, result) => {
      console.log(`Command completed: ${command}`);
    }
  }
};
```

### Plugin Hooks

- `beforeCommand` - Execute before any command
- `afterCommand` - Execute after any command
- `onError` - Handle errors
- `onConfig` - Modify configuration
- `onInit` - Initialize plugin
- `onBuild` - Modify build process
- `onDeploy` - Modify deployment

### Plugin API

The plugin API provides access to CLI utilities:

```typescript
interface PluginAPI {
  registerCommand: (command: CLICommand) => void;
  unregisterCommand: (name: string) => void;
  getConfig: () => CLIConfig;
  setConfig: (config: Partial<CLIConfig>) => void;
  getContext: () => CLIContext;
  logger: Logger;
  ui: UIComponents;
  fs: FileSystemUtils;
}
```

## Advanced Usage

### Custom Commands

You can register custom commands programmatically:

```typescript
import { CommandRegistry } from '@synapse/cli';

const registry = new CommandRegistry();

registry.register({
  name: 'custom',
  description: 'Custom command',
  handler: async (args, flags) => {
    console.log('Custom command executed');
  }
});
```

### Error Handling

The CLI provides comprehensive error handling:

```typescript
import { ErrorHandler, SynapseCLIError } from '@synapse/cli';

try {
  // Your code
} catch (error) {
  if (error instanceof SynapseCLIError) {
    console.error(`CLI Error: ${error.message}`);
    console.error(`Suggestions: ${error.suggestions.join(', ')}`);
  } else {
    ErrorHandler.getInstance().handle(error);
  }
}
```

### UI Components

Use the built-in UI components for rich terminal output:

```typescript
import { Logger, Colors, Spinner, Table, Box, Prompt } from '@synapse/cli';

// Logging
Logger.info('Information message');
Logger.success('Success message');
Logger.warning('Warning message');
Logger.error('Error message');

// Spinner
const spinner = new Spinner('Loading...');
spinner.start();
// ... do work
spinner.success('Completed!');

// Table
const table = new Table(['Name', 'Value']);
table.addRow(['key1', 'value1']);
table.addRow(['key2', 'value2']);
table.render();

// Box
Box.render('Content', { title: 'Title', style: 'rounded' });

// Prompts
const name = await Prompt.input('Enter your name');
const choice = await Prompt.select('Choose option', ['option1', 'option2']);
const confirmed = await Prompt.confirm('Are you sure?');
```

## Performance

The Synapse CLI is optimized for performance:

- **Fast Startup** - < 100ms startup time
- **Lazy Loading** - Commands are loaded only when needed
- **Caching** - Configuration and context are cached
- **Parallel Operations** - Multiple operations run concurrently
- **Minimal Dependencies** - Zero external dependencies for core functionality

## Troubleshooting

### Common Issues

**Command not found**
```bash
# Make sure the CLI is installed globally
bun install -g @synapse/cli

# Or use npx
npx @synapse/cli create my-app
```

**Permission denied**
```bash
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm

# Or use a different package manager
bun install -g @synapse/cli
```

**Port already in use**
```bash
# Use a different port
synapse dev --port 3001
```

**Build failures**
```bash
# Enable debug mode
synapse build --debug

# Check TypeScript configuration
synapse build --verbose
```

### Debug Mode

Enable debug mode for detailed logging:

```bash
synapse dev --debug
synapse build --debug
synapse deploy --debug
```

### Verbose Output

Enable verbose output for more information:

```bash
synapse dev --verbose
synapse build --verbose
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/synapse-framework/cli.git
cd cli

# Install dependencies
bun install

# Run tests
bun test

# Build the CLI
bun run build

# Test locally
bun run dev create test-app
```

### Running Tests

```bash
# Run all tests
bun test

# Run specific test file
bun test src/core/parser.test.ts

# Run tests with coverage
bun test --coverage
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://synapse-framework.dev/docs)
- 🐛 [Issue Tracker](https://github.com/synapse-framework/cli/issues)
- 💬 [Discussions](https://github.com/synapse-framework/cli/discussions)
- 📧 [Email Support](mailto:support@synapse-framework.dev)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes and updates.

---

Made with ❤️ by the Synapse team