npm package: @quarry-systems/drift-cli
Description: CLI tool for Drift plugin development
Author: Quarry Systems
Latest version: 0.1.1-alpha.1

# @quarry-systems/drift-cli

Command-line interface for Drift (Managed Cyclic Graph) - scaffold, develop, and manage Drift plugins and workflows.

[![npm version](https://img.shields.io/npm/v/@quarry-systems/drift-cli.svg)](https://www.npmjs.com/package/@quarry-systems/drift-cli)
[![License](https://img.shields.io/badge/license-AGPL--3.0%20OR%20Commercial-blue.svg)](LICENSE.md)

## Overview

Drift CLI provides command-line tools for working with Drift plugins and workflows. It includes scaffolding tools, development utilities, testing helpers, and plugin management commands.

## Installation

### Global Installation (Recommended)

```bash
npm install -g @quarry-systems/drift-cli
```

### Local Installation

```bash
npm install --save-dev @quarry-systems/drift-cli
```

## Quick Start

```bash
# Initialize a new plugin
drift plugin init

# Run plugin in development mode
drift plugin dev

# Test your plugin
drift plugin test

# Build plugin for distribution
drift plugin build

# Search for available plugins
drift plugin search http

# Get plugin information
drift plugin info @quarry-systems/drift-http
```

## Commands

### Plugin Management

#### `drift plugin init`

Scaffold a new Drift plugin with interactive prompts.

```bash
drift plugin init

# Options:
#   --name <name>         Plugin name
#   --description <desc>  Plugin description
#   --author <author>     Author name
#   --license <license>   License type
#   --template <type>     Template type (execution|infrastructure)
```

**Interactive prompts:**
- Plugin name
- Description
- Author
- License (MIT, ISC, Apache-2.0, etc.)
- Template type:
  - `execution` - For node handlers (HTTP, Timer, etc.)
  - `infrastructure` - For services (Secrets, Store, etc.)

**Generated structure:**
```
my-plugin/
├── src/
│   ├── index.ts           # Main plugin export
│   ├── index.test.ts      # Tests
│   └── plugin.manifest.ts # Plugin manifest
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md
```

#### `drift plugin dev`

Run plugin in development mode with hot reload.

```bash
drift plugin dev

# Options:
#   --watch              Enable watch mode (default: true)
#   --port <port>        Dev server port (default: 3000)
```

#### `drift plugin test`

Run plugin tests with Vitest.

```bash
drift plugin test

# Options:
#   --watch              Run in watch mode
#   --coverage           Generate coverage report
#   --ui                 Open Vitest UI
```

#### `drift plugin build`

Build plugin for distribution.

```bash
drift plugin build

# Options:
#   --outDir <dir>       Output directory (default: dist)
#   --minify             Minify output
#   --sourcemap          Generate sourcemaps
```

#### `drift plugin search`

Search for available Drift plugins on npm.

```bash
drift plugin search <query>

# Examples:
drift plugin search http
drift plugin search timer
drift plugin search openai
```

#### `drift plugin info`

Get detailed information about a plugin.

```bash
drift plugin info <package-name>

# Examples:
drift plugin info @quarry-systems/drift-http
drift plugin info @quarry-systems/drift-timer
```

#### `drift plugin list`

List installed Drift plugins in current project.

```bash
drift plugin list

# Options:
#   --global             List globally installed plugins
```

#### `drift plugin doctor`

Diagnose plugin issues and validate configuration.

```bash
drift plugin doctor

# Checks:
# - Plugin manifest validity
# - TypeScript configuration
# - Dependencies
# - Test setup
# - Build configuration
```

#### `drift plugin pack`

Package plugin for distribution (creates tarball).

```bash
drift plugin pack

# Options:
#   --dry-run            Show what would be packaged
```

## Plugin Templates

### Execution Plugin Template

For plugins that add custom node types:

```typescript
// src/index.ts
import type { Plugin, NodeHandler } from '@quarry-systems/drift-contracts';

const myNodeHandler: NodeHandler = async (node, ctx, meta) => {
  // Your node logic here
  return ctx;
};

export const myPlugin: Plugin = {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'My custom plugin',
  nodes: {
    'my-node-type': myNodeHandler
  }
};

export default myPlugin;
```

### Infrastructure Plugin Template

For plugins that provide services:

```typescript
// src/index.ts
import type { Plugin } from '@quarry-systems/drift-contracts';

export const myPlugin: Plugin = {
  name: 'my-service-plugin',
  version: '1.0.0',
  description: 'My service plugin',
  services: {
    myService: {
      factory: (ctx) => ({
        doSomething: async () => {
          // Service implementation
        }
      })
    }
  },
  onInit: async (ctx) => {
    // Initialize service
  },
  onDispose: async (ctx) => {
    // Cleanup
  }
};

export default myPlugin;
```

## Configuration Files

### package.json

The CLI expects certain fields in your plugin's `package.json`:

```json
{
  "name": "@your-scope/drift-my-plugin",
  "version": "1.0.0",
  "description": "My Drift plugin",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "keywords": ["drift", "drift-plugin"],
  "peerDependencies": {
    "@quarry-systems/drift-contracts": "^0.3.0"
  }
}
```

### tsconfig.json

Recommended TypeScript configuration:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "declaration": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}
```

### vitest.config.ts

Test configuration:

```typescript
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html']
    }
  }
});
```

## Development Workflow

### 1. Create Plugin

```bash
drift plugin init
# Follow prompts
```

### 2. Develop

```bash
cd my-plugin
npm install
drift plugin dev --watch
```

### 3. Test

```bash
drift plugin test --coverage
```

### 4. Build

```bash
drift plugin build
```

### 5. Publish

```bash
npm publish
```

## Best Practices

### Plugin Naming

- Use scoped packages: `@your-scope/drift-plugin-name`
- Include `drift-plugin` in keywords
- Follow semantic versioning

### Testing

- Write tests for all node handlers
- Test edge cases and error conditions
- Aim for >80% code coverage
- Use Vitest for testing

### Documentation

- Include comprehensive README
- Document all configuration options
- Provide usage examples
- Add TypeScript types

### Dependencies

- Minimize dependencies
- Use peer dependencies for Drift packages
- Keep bundle size small

## Troubleshooting

### Plugin Not Found

```bash
drift plugin doctor
# Check if plugin is properly installed
```

### Build Errors

```bash
# Clean build artifacts
rm -rf dist node_modules
npm install
drift plugin build
```

### Test Failures

```bash
# Run tests with verbose output
drift plugin test --reporter=verbose
```

## Examples

### Creating an HTTP Plugin

```bash
drift plugin init
# Name: drift-http
# Template: execution
# ... follow prompts

cd drift-http
# Edit src/index.ts with HTTP logic
drift plugin test
drift plugin build
```

### Creating a Secrets Plugin

```bash
drift plugin init
# Name: drift-secrets
# Template: infrastructure
# ... follow prompts

cd drift-secrets
# Edit src/index.ts with secrets service
drift plugin test
drift plugin build
```

## Related Packages

- **[@quarry-systems/drift-core](https://www.npmjs.com/package/@quarry-systems/drift-core)** - Core graph engine
- **[@quarry-systems/drift-contracts](https://www.npmjs.com/package/@quarry-systems/drift-contracts)** - Type definitions
- **[@quarry-systems/drift-testing](https://www.npmjs.com/package/@quarry-systems/drift-testing)** - Testing utilities

## Official Plugins

Browse official plugins for reference:
- `@quarry-systems/drift-http` - HTTP client
- `@quarry-systems/drift-timer` - Timers and scheduling
- `@quarry-systems/drift-openai` - OpenAI integration
- `@quarry-systems/drift-secrets` - Secrets management
- `@quarry-systems/drift-store-sqlite` - SQLite storage

## Contributing

This package is part of the Drift monorepo. See the main repository for contribution guidelines.

## License

Dual-licensed under:
- **AGPL-3.0** for open source projects
- **Commercial License** for proprietary use

See [LICENSE.md](LICENSE.md) for details.

For commercial licensing:
- Email: licensing@quarry-systems.com
- Web: https://quarry-systems.com/license

## Support

- 📖 [Documentation](https://drift.quarry-systems.com)
- 🐛 [Issues](https://github.com/QuarrySystems/drift/issues)
- 💬 [Discussions](https://github.com/QuarrySystems/drift/discussions)