@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

$3

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

$3

`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

$3

#### drift plugin init

Scaffold a new Drift plugin with interactive prompts.

`bash
drift plugin init

Options:

--name Plugin name

--description Plugin description

--author Author name

--license License type

--template 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 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 Output directory (default: dist)

--minify Minify output

--sourcemap Generate sourcemaps

`

#### drift plugin search

Search for available Drift plugins on npm.

`bash
drift plugin search

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

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

$3

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;
`

$3

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

$3

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"
}
}
`

$3

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"]
}
`

$3

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

$3

`bash
drift plugin init


Follow prompts


`

$3

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

$3

`bash
drift plugin test --coverage
`

$3

`bash
drift plugin build
`

$3

`bash
npm publish
`

Best Practices

$3

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

$3

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

$3

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

$3

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

Troubleshooting

$3

`bash
drift plugin doctor


Check if plugin is properly installed


`

$3

`bash


Clean build artifacts


rm -rf dist node_modules
npm install
drift plugin build
`

$3

`bash


Run tests with verbose output


drift plugin test --reporter=verbose
`

Examples

$3

`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
`

$3

`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 - 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: licensing@quarry-systems.com
- Web: https://quarry-systems.com/license

Support

- 📖 Documentation
- 🐛 Issues
- 💬 Discussions