@elizaos/cli 1.2.4 → 1.2.7

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

@@ -0,0 +1,162 @@
+import { mock, spyOn } from 'bun:test';
+import {
+  Content,
+  IAgentRuntime,
+  Memory,
+  ModelType,
+  Service,
+  State,
+  UUID,
+  logger,
+} from '@elizaos/core';
+
+/**
+ * Creates a mock runtime for testing
+ *
+ * @param overrides - Optional overrides for the default mock methods and properties
+ * @returns A mock runtime for testing
+ */
+export function createMockRuntime(overrides: Partial<MockRuntime> = {}): MockRuntime {
+  // Create base mock runtime with defaults
+  const mockRuntime: MockRuntime = {
+    // Core properties
+    agentId: 'test-agent-id' as UUID,
+    character: {
+      name: 'Test Character',
+      bio: 'This is a test character for testing',
+    },
+    services: new Map(),
+
+    // Core methods
+    getService: mock().mockReturnValue(null),
+    registerService: mock(),
+    getSetting: mock().mockReturnValue(null),
+
+    // Model methods
+    useModel: mock().mockImplementation((modelType, params) => {
+      if (modelType === ModelType.TEXT_SMALL) {
+        return Promise.resolve('Never gonna give you up, never gonna let you down');
+      } else if (modelType === ModelType.TEXT_LARGE) {
+        return Promise.resolve('Never gonna make you cry, never gonna say goodbye');
+      } else if (modelType === ModelType.OBJECT_LARGE) {
+        return Promise.resolve({
+          thought: 'I should respond in a friendly way',
+          message: 'Hello there! How can I help you today?',
+        });
+      }
+      return Promise.resolve('Default response');
+    }),
+
+    // Additional methods used in tests
+    init: mock().mockResolvedValue(undefined),
+    ...overrides,
+  };
+
+  // Merge with overrides
+  return mockRuntime;
+}
+
+/**
+ * Creates a mock Memory object for testing
+ *
+ * @param overrides - Optional overrides for the default memory properties
+ * @returns A mock memory object
+ */
+export function createMockMemory(overrides: Partial<Memory> = {}): Partial<Memory> {
+  return {
+    id: 'test-message-id' as UUID,
+    roomId: 'test-room-id' as UUID,
+    entityId: 'test-entity-id' as UUID,
+    agentId: 'test-agent-id' as UUID,
+    content: {
+      text: 'Test message',
+      source: 'test',
+    } as Content,
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock State object for testing
+ *
+ * @param overrides - Optional overrides for the default state properties
+ * @returns A mock state object
+ */
+export function createMockState(overrides: Partial<State> = {}): Partial<State> {
+  return {
+    ...overrides,
+    values: {
+      recentMessages: 'User: Test message',
+      ...overrides.values,
+    },
+    data: {
+      ...overrides.data,
+    },
+  };
+}
+
+/**
+ * Creates a standardized setup for testing with consistent mock objects
+ *
+ * @param overrides - Optional overrides for default mock implementations
+ * @returns An object containing mockRuntime, mockMessage, mockState, and callbackFn
+ */
+export function setupTest(
+  overrides: {
+    runtimeOverrides?: Partial<MockRuntime>;
+    messageOverrides?: Partial<Memory>;
+    stateOverrides?: Partial<State>;
+  } = {}
+) {
+  // Create mock callback function
+  const callbackFn = mock();
+
+  // Create a message
+  const mockMessage = createMockMemory(overrides.messageOverrides);
+
+  // Create a state object
+  const mockState = createMockState(overrides.stateOverrides);
+
+  // Create a mock runtime
+  const mockRuntime = createMockRuntime({
+    ...overrides.runtimeOverrides,
+  });
+
+  return {
+    mockRuntime,
+    mockMessage,
+    mockState,
+    callbackFn,
+  };
+}
+
+/**
+ * Type definition for the mock runtime
+ */
+export interface MockRuntime {
+  agentId: UUID;
+  character: {
+    name: string;
+    bio: string;
+    [key: string]: any;
+  };
+  services: Map<string, Service>;
+  getService: ReturnType<typeof mock>;
+  registerService: ReturnType<typeof mock>;
+  getSetting: ReturnType<typeof mock>;
+  useModel: ReturnType<typeof mock>;
+  init: ReturnType<typeof mock>;
+  [key: string]: any;
+}
+
+// Add spy on logger for common usage in tests
+export function setupLoggerSpies() {
+  spyOn(logger, 'info').mockImplementation(() => {});
+  spyOn(logger, 'error').mockImplementation(() => {});
+  spyOn(logger, 'warn').mockImplementation(() => {});
+  spyOn(logger, 'debug').mockImplementation(() => {});
+
+  // allow tests to restore originals
+  return () => mock.restore();
+}

package/templates/plugin-quick-starter/src/index.ts

@@ -0,0 +1,4 @@
+import { starterPlugin } from './plugin.ts';
+
+export { starterPlugin, StarterService } from './plugin.ts';
+export default starterPlugin;

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

@@ -0,0 +1,272 @@
+import type { Plugin } from '@elizaos/core';
+import {
+  type Action,
+  type ActionResult,
+  type Content,
+  type GenerateTextParams,
+  type HandlerCallback,
+  type IAgentRuntime,
+  type Memory,
+  ModelType,
+  type Provider,
+  type ProviderResult,
+  Service,
+  type State,
+  logger,
+  type MessagePayload,
+  type WorldPayload,
+  EventType,
+} from '@elizaos/core';
+import { z } from 'zod';
+
+/**
+ * Defines the configuration schema for a plugin, including the validation rules for the plugin name.
+ *
+ * @type {import('zod').ZodObject<{ EXAMPLE_PLUGIN_VARIABLE: import('zod').ZodString }>}
+ */
+const configSchema = z.object({
+  EXAMPLE_PLUGIN_VARIABLE: z
+    .string()
+    .min(1, 'Example plugin variable is not provided')
+    .optional()
+    .transform((val) => {
+      if (!val) {
+        logger.warn('Example plugin variable is not provided (this is expected)');
+      }
+      return val;
+    }),
+});
+
+/**
+ * Example HelloWorld action
+ * This demonstrates the simplest possible action structure
+ */
+/**
+ * Action representing a hello world message.
+ * @typedef {Object} Action
+ * @property {string} name - The name of the action.
+ * @property {string[]} similes - An array of related actions.
+ * @property {string} description - A brief description of the action.
+ * @property {Function} validate - Asynchronous function to validate the action.
+ * @property {Function} handler - Asynchronous function to handle the action and generate a response.
+ * @property {Object[]} examples - An array of example inputs and expected outputs for the action.
+ */
+const helloWorldAction: Action = {
+  name: 'HELLO_WORLD',
+  similes: ['GREET', 'SAY_HELLO'],
+  description: 'Responds with a simple hello world message',
+
+  validate: async (
+    _runtime: IAgentRuntime,
+    _message: Memory,
+    _state: State | undefined
+  ): Promise<boolean> => {
+    // Always valid
+    return true;
+  },
+
+  handler: async (
+    _runtime: IAgentRuntime,
+    message: Memory,
+    _state: State | undefined,
+    _options: Record<string, unknown> = {},
+    callback?: HandlerCallback,
+    _responses?: Memory[]
+  ): Promise<ActionResult> => {
+    try {
+      logger.info('Handling HELLO_WORLD action');
+
+      // Simple response content for callback
+      const responseContent: Content = {
+        text: 'hello world!',
+        actions: ['HELLO_WORLD'],
+        source: message.content.source,
+      };
+
+      // Call back with the hello world message if callback is provided
+      if (callback) {
+        await callback(responseContent);
+      }
+
+      // Return ActionResult
+      return {
+        text: 'hello world!',
+        success: true,
+        data: {
+          actions: ['HELLO_WORLD'],
+          source: message.content.source,
+        },
+      };
+    } catch (error) {
+      logger.error('Error in HELLO_WORLD action:', error);
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  },
+
+  examples: [
+    [
+      {
+        name: '{{name1}}',
+        content: {
+          text: 'Can you say hello?',
+        },
+      },
+      {
+        name: '{{name2}}',
+        content: {
+          text: 'hello world!',
+          actions: ['HELLO_WORLD'],
+        },
+      },
+    ],
+  ],
+};
+
+/**
+ * Example Hello World Provider
+ * This demonstrates the simplest possible provider implementation
+ */
+const helloWorldProvider: Provider = {
+  name: 'HELLO_WORLD_PROVIDER',
+  description: 'A simple example provider',
+
+  get: async (
+    _runtime: IAgentRuntime,
+    _message: Memory,
+    _state: State | undefined
+  ): Promise<ProviderResult> => {
+    return {
+      text: 'I am a provider',
+      values: {},
+      data: {},
+    };
+  },
+};
+
+export class StarterService extends Service {
+  static override serviceType = 'starter';
+
+  override capabilityDescription =
+    'This is a starter service which is attached to the agent through the starter plugin.';
+
+  constructor(runtime: IAgentRuntime) {
+    super(runtime);
+  }
+
+  static override async start(runtime: IAgentRuntime): Promise<Service> {
+    logger.info('Starting starter service');
+    const service = new StarterService(runtime);
+    return service;
+  }
+
+  static override async stop(runtime: IAgentRuntime): Promise<void> {
+    logger.info('Stopping starter service');
+    const service = runtime.getService(StarterService.serviceType);
+    if (!service) {
+      throw new Error('Starter service not found');
+    }
+    if ('stop' in service && typeof service.stop === 'function') {
+      await service.stop();
+    }
+  }
+
+  override async stop(): Promise<void> {
+    logger.info('Starter service stopped');
+  }
+}
+
+export const starterPlugin: Plugin = {
+  name: 'plugin-quick-starter',
+  description: 'Quick backend-only plugin template for elizaOS',
+  config: {
+    EXAMPLE_PLUGIN_VARIABLE: process.env.EXAMPLE_PLUGIN_VARIABLE,
+  },
+  async init(config: Record<string, string>) {
+    logger.info('Initializing plugin-quick-starter');
+    try {
+      const validatedConfig = await configSchema.parseAsync(config);
+
+      // Set all environment variables at once
+      for (const [key, value] of Object.entries(validatedConfig)) {
+        if (value) process.env[key] = value;
+      }
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        throw new Error(
+          `Invalid plugin configuration: ${error.errors.map((e) => e.message).join(', ')}`
+        );
+      }
+      throw error;
+    }
+  },
+  models: {
+    [ModelType.TEXT_SMALL]: async (
+      _runtime,
+      { prompt, stopSequences = [] }: GenerateTextParams
+    ) => {
+      return 'Never gonna give you up, never gonna let you down, never gonna run around and desert you...';
+    },
+    [ModelType.TEXT_LARGE]: async (
+      _runtime,
+      {
+        prompt,
+        stopSequences = [],
+        maxTokens = 8192,
+        temperature = 0.7,
+        frequencyPenalty = 0.7,
+        presencePenalty = 0.7,
+      }: GenerateTextParams
+    ) => {
+      return 'Never gonna make you cry, never gonna say goodbye, never gonna tell a lie and hurt you...';
+    },
+  },
+  routes: [
+    {
+      name: 'api-status',
+      path: '/api/status',
+      type: 'GET',
+      handler: async (_req: any, res: any) => {
+        res.json({
+          status: 'ok',
+          plugin: 'quick-starter',
+          timestamp: new Date().toISOString(),
+        });
+      },
+    },
+  ],
+  events: {
+    [EventType.MESSAGE_RECEIVED]: [
+      async (params: MessagePayload) => {
+        logger.debug('MESSAGE_RECEIVED event received');
+        logger.debug('Message:', params.message);
+      },
+    ],
+    [EventType.VOICE_MESSAGE_RECEIVED]: [
+      async (params: MessagePayload) => {
+        logger.debug('VOICE_MESSAGE_RECEIVED event received');
+        logger.debug('Message:', params.message);
+      },
+    ],
+    [EventType.WORLD_CONNECTED]: [
+      async (params: WorldPayload) => {
+        logger.debug('WORLD_CONNECTED event received');
+        logger.debug('World:', params.world);
+      },
+    ],
+    [EventType.WORLD_JOINED]: [
+      async (params: WorldPayload) => {
+        logger.debug('WORLD_JOINED event received');
+        logger.debug('World:', params.world);
+      },
+    ],
+  },
+  services: [StarterService],
+  actions: [helloWorldAction],
+  providers: [helloWorldProvider],
+  // dependencies: ['@elizaos/plugin-knowledge'], <--- plugin dependecies go here (if requires another plugin)
+};
+
+export default starterPlugin;

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

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "sourceMap": true,
+    "inlineSources": true,
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

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

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "lib": ["ESNext", "dom"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": false,
+    "allowImportingTsExtensions": true,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "noImplicitAny": true,
+    "allowJs": true,
+    "checkJs": false,
+    "noEmitOnError": false,
+    "moduleDetection": "force",
+    "allowArbitraryExtensions": true,
+    "jsx": "react",
+    "isolatedModules": false,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/__tests__/**/*", "e2e/**/*", "**/*.test.ts", "**/*.spec.ts"]
+}

package/templates/plugin-quick-starter/tsup.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  outDir: 'dist',
+  tsconfig: './tsconfig.build.json', // Use build-specific tsconfig
+  sourcemap: true,
+  clean: false,
+  format: ['esm'], // Ensure you're targeting CommonJS
+  dts: true, // require DTS so we get d.ts in the dist folder on npm
+  external: [
+    'dotenv', // Externalize dotenv to prevent bundling
+    'fs', // Externalize fs to use Node.js built-in module
+    'path', // Externalize other built-ins if necessary
+    'https',
+    'http',
+    '@elizaos/core',
+    'zod',
+  ],
+});

package/templates/plugin-starter/package.json

@@ -40,7 +40,7 @@
     "tsup.config.ts"
   ],
   "dependencies": {
-    "@elizaos/core": "1.2.4",
+    "@elizaos/core": "1.2.7",
     "@tanstack/react-query": "^5.80.7",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.3.1",
@@ -49,7 +49,7 @@
     "zod": "3.24.2"
   },
   "devDependencies": {
-    "@elizaos/cli": "1.1.6",
+    "@elizaos/cli": "1.2.7",
     "@tailwindcss/vite": "^4.1.10",
     "@vitejs/plugin-react-swc": "^3.10.2",
     "dotenv": "16.4.5",

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

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import { existsSync, readFileSync } from 'fs';
-import { execSync } from 'child_process';
 import { join } from 'path';
 
 const testDependencies = {
@@ -36,10 +35,15 @@ function installTestDependencies() {
 
   console.log('Installing test dependencies...');
   try {
-    execSync(`bun add -d ${missingDeps.join(' ')}`, {
-      stdio: 'inherit',
+    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);

package/templates/plugin-starter/src/__tests__/build-order.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it, beforeAll, afterAll } from 'bun:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { $ } from 'bun';
+import { getViteOutDir } from './vite-config-utils';
+
+describe('Build Order Integration Test', () => {
+  const rootDir = path.resolve(__dirname, '../..');
+  const distDir = path.join(rootDir, 'dist');
+  let viteBuildDir: string;
+  const tsupBuildMarker = path.join(distDir, 'index.js'); // TSup creates this
+
+  beforeAll(async () => {
+    // Get the actual vite build directory from config
+    const viteOutDirRelative = await getViteOutDir(rootDir);
+    viteBuildDir = path.join(rootDir, viteOutDirRelative);
+
+    // Clean dist directory before test
+    if (fs.existsSync(distDir)) {
+      await fs.promises.rm(distDir, { recursive: true, force: true });
+    }
+  });
+
+  afterAll(async () => {
+    // Clean up after test
+    if (fs.existsSync(distDir)) {
+      await fs.promises.rm(distDir, { recursive: true, force: true });
+    }
+  });
+
+  it('should ensure vite build outputs persist after tsup build', async () => {
+    // Run the full build process
+    await $`cd ${rootDir} && bun run build`;
+
+    const distFiles = fs.readdirSync(distDir);
+
+    // Should have vite outputs (HTML files)
+    expect(distFiles.some((file) => file.endsWith('.html'))).toBe(true);
+
+    // Should have vite manifest (if configured)
+    const viteBuildMarker = path.join(viteBuildDir, '.vite', 'manifest.json');
+    expect(fs.existsSync(viteBuildMarker)).toBe(true);
+
+    // Should have vite assets directory
+    expect(distFiles.includes('assets')).toBe(true);
+
+    // Should have tsup outputs (JS and d.ts files)
+    expect(distFiles.some((file) => file === 'index.js')).toBe(true);
+    expect(distFiles.some((file) => file === 'index.d.ts')).toBe(true);
+  }, 30000); // 30 second timeout for build process
+});

package/templates/plugin-starter/src/__tests__/vite-config-utils.ts

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+/**
+ * Extracts the Vite build.outDir from vite.config.ts
+ * Handles both relative and absolute paths, accounting for Vite's root directory
+ */
+export async function getViteOutDir(packageRoot: string): Promise<string> {
+  const viteConfigPath = path.join(packageRoot, 'vite.config.ts');
+
+  if (!fs.existsSync(viteConfigPath)) {
+    throw new Error(`vite.config.ts not found at ${viteConfigPath}`);
+  }
+
+  // Import the vite config dynamically
+  const configModule = await import(viteConfigPath);
+  const config =
+    typeof configModule.default === 'function'
+      ? configModule.default({ command: 'build', mode: 'production' })
+      : configModule.default;
+
+  let outDir = config.build?.outDir || 'dist';
+  const viteRoot = config.root || '.';
+
+  // If outDir is relative, resolve it relative to the vite root
+  if (!path.isAbsolute(outDir)) {
+    const viteRootAbsolute = path.resolve(packageRoot, viteRoot);
+    outDir = path.resolve(viteRootAbsolute, outDir);
+  }
+
+  // Ensure the path is relative to packageRoot for consistency
+  return path.relative(packageRoot, outDir);
+}

package/templates/plugin-starter/src/plugin.ts

@@ -1,19 +1,17 @@
-import type { Plugin } from '@elizaos/core';
-import {
-  type Action,
-  type ActionResult,
-  type Content,
-  type GenerateTextParams,
-  type HandlerCallback,
-  type IAgentRuntime,
-  type Memory,
-  ModelType,
-  type Provider,
-  type ProviderResult,
-  Service,
-  type State,
-  logger,
+import type {
+  Action,
+  ActionResult,
+  Content,
+  GenerateTextParams,
+  HandlerCallback,
+  IAgentRuntime,
+  Memory,
+  Plugin,
+  Provider,
+  ProviderResult,
+  State,
 } from '@elizaos/core';
+import { ModelType, Service, logger } from '@elizaos/core';
 import { z } from 'zod';
 import { StarterPluginTestSuite } from './tests';
 

package/templates/plugin-starter/tsup.config.ts

@@ -5,7 +5,7 @@ export default defineConfig({
   outDir: 'dist',
   tsconfig: './tsconfig.build.json', // Use build-specific tsconfig
   sourcemap: true,
-  clean: true,
+  clean: false,
   format: ['esm'], // Ensure you're targeting CommonJS
   dts: true, // require DTS so we get d.ts in the dist folder on npm
   external: [

package/templates/plugin-starter/vite.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
   plugins: [tailwindcss(), react()],
   base: './',
   build: {
-    emptyOutDir: false,
+    emptyOutDir: true,
     outDir: 'dist',
     manifest: true,
   },