@quarry-systems/drift-cli

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

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)

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

Local Installation

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

Quick Start

# 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.

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.

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.

drift plugin test

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

drift plugin build

Build plugin for distribution.

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.

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.

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.

drift plugin list

# Options:
#   --global             List globally installed plugins

drift plugin doctor

Diagnose plugin issues and validate configuration.

drift plugin doctor

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

drift plugin pack

Package plugin for distribution (creates tarball).

drift plugin pack

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

Plugin Templates

Execution Plugin Template

For plugins that add custom node types:

// 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:

// 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:

{
  "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:

{
  "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:

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

drift plugin init
# Follow prompts

2. Develop

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

3. Test

drift plugin test --coverage

4. Build

drift plugin build

5. Publish

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

drift plugin doctor
# Check if plugin is properly installed

Build Errors

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

Test Failures

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

Examples

Creating an HTTP Plugin

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

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 - Core graph engine
• @quarry-systems/drift-contracts - Type definitions
• @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 for details.

For commercial licensing:

• Email: [email protected]
• Web: https://quarry-systems.com/license

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions