@elizaos/cli 1.2.4 → 1.2.7

package/templates/plugin-quick-starter/README.md

@@ -0,0 +1,214 @@
+# Plugin Quick Starter
+
+A minimal backend-only plugin template for ElizaOS. This template provides a clean starting point for creating simple plugins without frontend complexity.
+
+## Overview
+
+This quick-starter template is ideal for:
+
+- Backend-only plugins
+- Simple API integrations
+- Services and providers
+- Actions without UI components
+- Lightweight extensions
+
+## Structure
+
+```
+plugin-quick-starter/
+├── src/
+│   ├── __tests__/          # Unit tests
+│   │   ├── plugin.test.ts
+│   │   └── test-utils.ts
+│   ├── plugin.ts           # Main plugin implementation
+│   ├── tests.ts            # Plugin test suite
+│   └── index.ts            # Plugin export
+├── scripts/
+│   └── install-test-deps.js # Test dependency installer
+├── tsup.config.ts          # Build configuration
+├── tsconfig.json           # TypeScript config
+├── package.json            # Minimal dependencies
+└── README.md               # This file
+```
+
+## Getting Started
+
+1. **Create your plugin:**
+
+   ```bash
+   elizaos create my-plugin
+   # Select: Plugin
+   # Select: Quick Plugin (Backend Only)
+   ```
+
+2. **Navigate to your plugin:**
+
+   ```bash
+   cd my-plugin
+   ```
+
+3. **Install dependencies:**
+
+   ```bash
+   bun install
+   ```
+
+4. **Start development:**
+   ```bash
+   bun run dev
+   ```
+
+## Key Features
+
+### Minimal Dependencies
+
+- Only essential packages (`@elizaos/core`, `zod`)
+- No frontend frameworks or build tools
+- Fast installation and builds
+
+### Simple Testing
+
+- Unit tests only with Bun test runner
+- No E2E or component testing overhead
+- Quick test execution
+
+### Backend Focus
+
+- API routes for server-side functionality
+- Services for state management
+- Actions for agent capabilities
+- Providers for contextual data
+
+## Plugin Components
+
+### Actions
+
+Define agent capabilities:
+
+```typescript
+const myAction: Action = {
+  name: 'MY_ACTION',
+  description: 'Description of what this action does',
+  validate: async (runtime, message, state) => {
+    // Validation logic
+    return true;
+  },
+  handler: async (runtime, message, state, options, callback) => {
+    // Action implementation
+    return { success: true, data: {} };
+  },
+};
+```
+
+### Services
+
+Manage plugin state:
+
+```typescript
+export class MyService extends Service {
+  static serviceType = 'my-service';
+
+  async start() {
+    // Initialize service
+  }
+
+  async stop() {
+    // Cleanup
+  }
+}
+```
+
+### Providers
+
+Supply contextual information:
+
+```typescript
+const myProvider: Provider = {
+  name: 'MY_PROVIDER',
+  description: 'Provides contextual data',
+  get: async (runtime, message, state) => {
+    return {
+      text: 'Provider data',
+      values: {},
+      data: {},
+    };
+  },
+};
+```
+
+### API Routes
+
+Backend endpoints:
+
+```typescript
+routes: [
+  {
+    name: 'api-endpoint',
+    path: '/api/endpoint',
+    type: 'GET',
+    handler: async (req, res) => {
+      res.json({ data: 'response' });
+    },
+  },
+];
+```
+
+## Development Commands
+
+```bash
+# Start in development mode with hot reload
+bun run dev
+
+# Start in production mode
+bun run start
+
+# Build the plugin
+bun run build
+
+# Run tests
+bun test
+
+# Format code
+bun run format
+```
+
+## Testing
+
+Write unit tests in `src/__tests__/`:
+
+```typescript
+import { describe, it, expect } from 'bun:test';
+
+describe('My Plugin', () => {
+  it('should work correctly', () => {
+    expect(true).toBe(true);
+  });
+});
+```
+
+## Publishing
+
+1. Update `package.json` with your plugin details
+2. Build your plugin: `bun run build`
+3. Publish: `elizaos publish`
+
+## When to Use Quick Starter
+
+Use this template when you need:
+
+- ✅ Backend-only functionality
+- ✅ Simple API integrations
+- ✅ Lightweight plugins
+- ✅ Fast development cycles
+- ✅ Minimal dependencies
+
+Consider the full plugin-starter if you need:
+
+- ❌ React frontend components
+- ❌ Complex UI interactions
+- ❌ E2E testing with Cypress
+- ❌ Frontend build pipeline
+
+## License
+
+This template is part of the ElizaOS project.

package/templates/plugin-quick-starter/bunfig.toml

@@ -0,0 +1,10 @@
+[test]
+timeout = 60000
+coverage = true
+
+[test.env]
+NODE_ENV = "test"
+
+coverage-exclude = [
+  "**/dist/**",
+]

package/templates/plugin-quick-starter/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@elizaos/plugin-quick-starter",
+  "description": "Quick backend-only plugin template for ElizaOS",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "packageType": "plugin",
+  "platform": "node",
+  "license": "UNLICENSED",
+  "author": "${GITHUB_USERNAME}",
+  "keywords": [
+    "plugin",
+    "elizaos"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": "https://elizaos.ai",
+  "bugs": {
+    "url": "https://github.com/${GITHUB_USERNAME}/${PLUGINNAME}/issues"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".npmignore",
+    "package.json",
+    "tsup.config.ts"
+  ],
+  "dependencies": {
+    "@elizaos/core": "1.2.7",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@elizaos/cli": "latest",
+    "dotenv": "16.4.5",
+    "prettier": "3.5.3",
+    "tsup": "8.5.0",
+    "typescript": "5.8.2"
+  },
+  "scripts": {
+    "start": "elizaos start",
+    "dev": "elizaos dev",
+    "build": "tsc --noEmit && tsup",
+    "test": "bun test",
+    "format": "prettier --write ./src"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "resolutions": {
+    "zod": "^3.24.4"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "API_KEY": {
+        "type": "string",
+        "description": "API key for the service"
+      }
+    }
+  },
+  "gitHead": "d5bd5c43bfebeb7ac02f9e029f924cb6cd5c2ec7"
+}

package/templates/plugin-quick-starter/scripts/install-test-deps.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const testDependencies = {
+  '@elizaos/core': 'latest',
+  '@elizaos/test-utils': 'latest',
+};
+
+function isInstalled(packageName) {
+  try {
+    const packageJsonPath = join(process.cwd(), 'package.json');
+    if (existsSync(packageJsonPath)) {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+      const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+      return packageName in deps;
+    }
+  } catch (error) {
+    // Silent fail, will install if error
+  }
+  return false;
+}
+
+function installTestDependencies() {
+  const missingDeps = Object.entries(testDependencies)
+    .filter(([name]) => !isInstalled(name))
+    .map(([name, version]) => `${name}@${version}`);
+
+  if (missingDeps.length === 0) {
+    console.log('✓ Test dependencies already installed');
+    return;
+  }
+
+  console.log('Installing test dependencies...');
+  try {
+    const proc = Bun.spawnSync(['bun', 'add', '-d', ...missingDeps], {
+      stdout: 'inherit',
+      stderr: 'inherit',
+      cwd: process.cwd(),
+    });
+
+    if (proc.exitCode !== 0) {
+      throw new Error('bun add command failed');
+    }
+    console.log('✓ Test dependencies installed successfully');
+  } catch (error) {
+    console.error('Failed to install test dependencies:', error.message);
+    process.exit(1);
+  }
+}
+
+installTestDependencies();

package/templates/plugin-quick-starter/src/__tests__/plugin.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it, spyOn, beforeEach, afterEach, beforeAll, afterAll } from 'bun:test';
+import { starterPlugin, StarterService } from '../index';
+import { ModelType, logger, type IAgentRuntime, type Service } from '@elizaos/core';
+import dotenv from 'dotenv';
+
+// Setup environment variables
+dotenv.config();
+
+// Need to spy on logger for documentation
+beforeAll(() => {
+  spyOn(logger, 'info');
+  spyOn(logger, 'error');
+  spyOn(logger, 'warn');
+  spyOn(logger, 'debug');
+});
+
+afterAll(() => {
+  // No global restore needed in bun:test
+});
+
+// Create a real runtime for testing
+function createRealRuntime(): Partial<IAgentRuntime> {
+  const services = new Map<string, Service>();
+
+  // Create a real service instance if needed
+  const createService = (serviceType: string): Service | null => {
+    if (serviceType === StarterService.serviceType) {
+      return new StarterService({
+        character: {
+          name: 'Test Character',
+          system: 'You are a helpful assistant for testing.',
+        },
+      } as IAgentRuntime);
+    }
+    return null;
+  };
+
+  return {
+    character: {
+      name: 'Test Character',
+      system: 'You are a helpful assistant for testing.',
+      bio: 'A test character for unit testing',
+      plugins: [],
+      settings: {},
+    },
+    getSetting: (key: string) => null,
+    db: {
+      get: async (key: string) => null,
+      set: async (key: string, value: unknown) => true,
+      delete: async (key: string) => true,
+      getKeys: async (pattern: string) => [],
+    },
+    getService: <T extends Service>(serviceType: string): T | null => {
+      // Log the service request for debugging
+      logger.debug(`Requesting service: ${serviceType}`);
+
+      // Get from cache or create new
+      if (!services.has(serviceType)) {
+        logger.debug(`Creating new service: ${serviceType}`);
+        const service = createService(serviceType);
+        if (service) {
+          services.set(serviceType, service);
+        }
+      }
+
+      return (services.get(serviceType) as T) || null;
+    },
+    registerService: async (ServiceClass: typeof Service): Promise<void> => {
+      logger.debug(`Registering service: ${ServiceClass.serviceType}`);
+      const runtime = {
+        character: {
+          name: 'Test Character',
+          system: 'You are a helpful assistant for testing.',
+          bio: 'A test character for unit testing',
+        },
+      } as IAgentRuntime;
+      const service = await ServiceClass.start(runtime);
+      services.set(ServiceClass.serviceType, service);
+    },
+  };
+}
+
+describe('Plugin Configuration', () => {
+  it('should have correct plugin metadata', () => {
+    expect(starterPlugin.name).toBe('plugin-quick-starter');
+    expect(starterPlugin.description).toBe('Quick backend-only plugin template for elizaOS');
+    expect(starterPlugin.config).toBeDefined();
+  });
+
+  it('should include the EXAMPLE_PLUGIN_VARIABLE in config', () => {
+    expect(starterPlugin.config).toHaveProperty('EXAMPLE_PLUGIN_VARIABLE');
+  });
+
+  it('should initialize properly', async () => {
+    const originalEnv = process.env.EXAMPLE_PLUGIN_VARIABLE;
+
+    try {
+      process.env.EXAMPLE_PLUGIN_VARIABLE = 'test-value';
+
+      // Initialize with config - using real runtime
+      const runtime = createRealRuntime();
+
+      if (starterPlugin.init) {
+        await starterPlugin.init(
+          { EXAMPLE_PLUGIN_VARIABLE: 'test-value' },
+          runtime as IAgentRuntime
+        );
+        expect(true).toBe(true); // If we got here, init succeeded
+      }
+    } finally {
+      process.env.EXAMPLE_PLUGIN_VARIABLE = originalEnv;
+    }
+  });
+
+  it('should have a valid config', () => {
+    expect(starterPlugin.config).toBeDefined();
+    if (starterPlugin.config) {
+      // Check if the config has expected EXAMPLE_PLUGIN_VARIABLE property
+      expect(Object.keys(starterPlugin.config)).toContain('EXAMPLE_PLUGIN_VARIABLE');
+    }
+  });
+});
+
+describe('Plugin Models', () => {
+  it('should have TEXT_SMALL model defined', () => {
+    expect(starterPlugin.models?.[ModelType.TEXT_SMALL]).toBeDefined();
+    if (starterPlugin.models) {
+      expect(typeof starterPlugin.models[ModelType.TEXT_SMALL]).toBe('function');
+    }
+  });
+
+  it('should have TEXT_LARGE model defined', () => {
+    expect(starterPlugin.models?.[ModelType.TEXT_LARGE]).toBeDefined();
+    if (starterPlugin.models) {
+      expect(typeof starterPlugin.models[ModelType.TEXT_LARGE]).toBe('function');
+    }
+  });
+
+  it('should return a response from TEXT_SMALL model', async () => {
+    if (starterPlugin.models?.[ModelType.TEXT_SMALL]) {
+      const runtime = createRealRuntime();
+      const result = await starterPlugin.models[ModelType.TEXT_SMALL](runtime as IAgentRuntime, {
+        prompt: 'test',
+      });
+
+      // Check that we get a non-empty string response
+      expect(result).toBeTruthy();
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(10);
+    }
+  });
+});
+
+describe('StarterService', () => {
+  it('should start the service', async () => {
+    const runtime = createRealRuntime();
+    const startResult = await StarterService.start(runtime as IAgentRuntime);
+
+    expect(startResult).toBeDefined();
+    expect(startResult.constructor.name).toBe('StarterService');
+
+    // Test real functionality - check stop method is available
+    expect(typeof startResult.stop).toBe('function');
+  });
+
+  it('should stop the service', async () => {
+    const runtime = createRealRuntime();
+
+    // Start the service to get the actual instance
+    const service = await StarterService.start(runtime as IAgentRuntime);
+
+    // Spy on the real service's stop method
+    const stopSpy = spyOn(service, 'stop');
+
+    // Mock getService to return our spied service
+    const originalGetService = runtime.getService;
+    runtime.getService = <T extends Service>(serviceType: string): T | null => {
+      if (serviceType === StarterService.serviceType) {
+        return service as T;
+      }
+      return null;
+    };
+
+    // Call the static stop method
+    await StarterService.stop(runtime as IAgentRuntime);
+
+    // Verify the service's stop method was called
+    expect(stopSpy).toHaveBeenCalled();
+
+    // Restore original getService
+    runtime.getService = originalGetService;
+  });
+
+  it('should throw an error when stopping a non-existent service', async () => {
+    const runtime = createRealRuntime();
+    // Don't register a service, so getService will return null
+
+    // We'll patch the getService function to ensure it returns null
+    const originalGetService = runtime.getService;
+    runtime.getService = () => null;
+
+    await expect(StarterService.stop(runtime as IAgentRuntime)).rejects.toThrow(
+      'Starter service not found'
+    );
+
+    // Restore original getService function
+    runtime.getService = originalGetService;
+  });
+});