portos-ai-toolkit 0.1.0

package/src/server/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * TypeScript declarations for @portos/ai-toolkit/server
+ */
+
+export interface ProviderService {
+  getAllProviders(): Promise<{ activeProvider: string | null; providers: any[] }>;
+  getProviderById(id: string): Promise<any | null>;
+  getActiveProvider(): Promise<any | null>;
+  setActiveProvider(id: string): Promise<any | null>;
+  createProvider(data: any): Promise<any>;
+  updateProvider(id: string, updates: any): Promise<any | null>;
+  deleteProvider(id: string): Promise<boolean>;
+  testProvider(id: string): Promise<{ success: boolean; [key: string]: any }>;
+  refreshProviderModels(id: string): Promise<any | null>;
+}
+
+export interface RunnerService {
+  createRun(options: any): Promise<any>;
+  executeCliRun(...args: any[]): Promise<string>;
+  executeApiRun(...args: any[]): Promise<string>;
+  stopRun(runId: string): Promise<boolean>;
+  getRun(runId: string): Promise<any | null>;
+  getRunOutput(runId: string): Promise<string | null>;
+  getRunPrompt(runId: string): Promise<string | null>;
+  listRuns(limit?: number, offset?: number, source?: string): Promise<{ total: number; runs: any[] }>;
+  deleteRun(runId: string): Promise<boolean>;
+  deleteFailedRuns(): Promise<number>;
+  isRunActive(runId: string): Promise<boolean>;
+}
+
+export interface PromptsService {
+  init(): Promise<void>;
+  getStages(): Record<string, any>;
+  getStage(name: string): any | null;
+  getStageTemplate(name: string): Promise<string | null>;
+  updateStageTemplate(name: string, content: string): Promise<void>;
+  updateStageConfig(name: string, config: any): Promise<void>;
+  createStage(stageName: string, config: any, template?: string): Promise<void>;
+  deleteStage(stageName: string): Promise<void>;
+  getVariables(): Record<string, any>;
+  getVariable(key: string): any | null;
+  updateVariable(key: string, data: any): Promise<void>;
+  createVariable(key: string, data: any): Promise<void>;
+  deleteVariable(key: string): Promise<void>;
+  buildPrompt(stageName: string, data?: any): Promise<string>;
+  previewPrompt(stageName: string, testData?: any): Promise<string>;
+}
+
+export interface AIToolkit {
+  services: {
+    providers: ProviderService;
+    runner: RunnerService;
+    prompts: PromptsService;
+  };
+  routes: {
+    providers: any;
+    runs: any;
+    prompts: any;
+  };
+  mountRoutes(app: any, basePath?: string): void;
+}
+
+export interface AIToolkitConfig {
+  dataDir?: string;
+  providersFile?: string;
+  runsDir?: string;
+  promptsDir?: string;
+  screenshotsDir?: string;
+  sampleProvidersFile?: string;
+  io?: any;
+  asyncHandler?: (fn: any) => any;
+  hooks?: {
+    onRunCreated?: (metadata: any) => void;
+    onRunStarted?: (run: any) => void;
+    onRunCompleted?: (metadata: any, output: string) => void;
+    onRunFailed?: (metadata: any, error: string, output: string) => void;
+  };
+  maxConcurrentRuns?: number;
+}
+
+export function createAIToolkit(config?: AIToolkitConfig): AIToolkit;
+export function createProviderService(config?: Partial<AIToolkitConfig>): ProviderService;
+export function createRunnerService(config?: Partial<AIToolkitConfig>): RunnerService;
+export function createPromptsService(config?: Partial<AIToolkitConfig>): PromptsService;
+export function createProvidersRoutes(service: ProviderService, options?: any): any;
+export function createRunsRoutes(service: RunnerService, options?: any): any;
+export function createPromptsRoutes(service: PromptsService, options?: any): any;

package/src/server/index.js

@@ -0,0 +1,95 @@
+/**
+ * AI Toolkit Server
+ * Configurable AI provider, runner, and prompt services with Express routes
+ */
+
+import { createProviderService } from './providers.js';
+import { createRunnerService } from './runner.js';
+import { createPromptsService } from './prompts.js';
+import { createProvidersRoutes } from './routes/providers.js';
+import { createRunsRoutes } from './routes/runs.js';
+import { createPromptsRoutes } from './routes/prompts.js';
+
+export * from './validation.js';
+export { createProviderService, createRunnerService, createPromptsService };
+export { createProvidersRoutes, createRunsRoutes, createPromptsRoutes };
+
+/**
+ * Create a complete AI toolkit instance with services and routes
+ */
+export function createAIToolkit(config = {}) {
+  const {
+    dataDir = './data',
+    providersFile = 'providers.json',
+    runsDir = 'runs',
+    promptsDir = 'prompts',
+    screenshotsDir = './data/screenshots',
+    sampleProvidersFile = null,
+
+    // Socket.IO instance for real-time updates
+    io = null,
+
+    // Optional async handler wrapper (e.g., for error handling)
+    asyncHandler = (fn) => fn,
+
+    // Hooks for lifecycle events
+    hooks = {},
+
+    // Runner config
+    maxConcurrentRuns = 5
+  } = config;
+
+  // Create services
+  const providerService = createProviderService({
+    dataDir,
+    providersFile,
+    sampleFile: sampleProvidersFile
+  });
+
+  const runnerService = createRunnerService({
+    dataDir,
+    runsDir,
+    screenshotsDir,
+    providerService,
+    hooks,
+    maxConcurrentRuns
+  });
+
+  const promptsService = createPromptsService({
+    dataDir,
+    promptsDir
+  });
+
+  // Initialize prompts service
+  promptsService.init().catch(err => {
+    console.error(`❌ Failed to initialize prompts: ${err.message}`);
+  });
+
+  // Create routes
+  const providersRouter = createProvidersRoutes(providerService, { asyncHandler });
+  const runsRouter = createRunsRoutes(runnerService, { asyncHandler, io });
+  const promptsRouter = createPromptsRoutes(promptsService, { asyncHandler });
+
+  return {
+    // Services
+    services: {
+      providers: providerService,
+      runner: runnerService,
+      prompts: promptsService
+    },
+
+    // Routes
+    routes: {
+      providers: providersRouter,
+      runs: runsRouter,
+      prompts: promptsRouter
+    },
+
+    // Convenience method to mount all routes
+    mountRoutes(app, basePath = '/api') {
+      app.use(`${basePath}/providers`, providersRouter);
+      app.use(`${basePath}/runs`, runsRouter);
+      app.use(`${basePath}/prompts`, promptsRouter);
+    }
+  };
+}

package/src/server/prompts.js

@@ -0,0 +1,234 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Create a prompts service with configurable storage
+ */
+export function createPromptsService(config = {}) {
+  const {
+    dataDir = './data',
+    promptsDir = 'prompts'
+  } = config;
+
+  const PROMPTS_PATH = join(dataDir, promptsDir);
+
+  let stageConfig = null;
+  let variables = null;
+
+  /**
+   * Load or reload prompts configuration
+   */
+  async function loadPrompts() {
+    const configPath = join(PROMPTS_PATH, 'stage-config.json');
+    const varsPath = join(PROMPTS_PATH, 'variables.json');
+
+    if (existsSync(configPath)) {
+      stageConfig = JSON.parse(await readFile(configPath, 'utf-8'));
+    } else {
+      stageConfig = { stages: {} };
+    }
+
+    if (existsSync(varsPath)) {
+      variables = JSON.parse(await readFile(varsPath, 'utf-8'));
+    } else {
+      variables = { variables: {} };
+    }
+
+    console.log(`📝 Loaded ${Object.keys(stageConfig.stages || {}).length} prompt stages`);
+  }
+
+  /**
+   * Apply Mustache-like template substitution
+   */
+  function applyTemplate(template, data) {
+    let result = template;
+
+    // Handle sections {{#key}}...{{/key}}
+    result = result.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (match, key, content) => {
+      const value = data[key];
+      if (!value) return '';
+      if (Array.isArray(value)) {
+        return value.map(item => {
+          if (typeof item === 'object') {
+            return applyTemplate(content, item);
+          }
+          return content.replace(/\{\{\.\}\}/g, item);
+        }).join('');
+      }
+      return applyTemplate(content, data);
+    });
+
+    // Handle inverted sections {{^key}}...{{/key}}
+    result = result.replace(/\{\{\^(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (match, key, content) => {
+      return data[key] ? '' : content;
+    });
+
+    // Handle simple variables {{key}}
+    result = result.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+      return data[key] !== undefined ? String(data[key]) : '';
+    });
+
+    return result.trim();
+  }
+
+  return {
+    /**
+     * Load prompts configuration
+     */
+    async init() {
+      await loadPrompts();
+    },
+
+    /**
+     * Get all stages
+     */
+    getStages() {
+      return stageConfig?.stages || {};
+    },
+
+    /**
+     * Get a single stage
+     */
+    getStage(stageName) {
+      return stageConfig?.stages?.[stageName] || null;
+    },
+
+    /**
+     * Get stage template content
+     */
+    async getStageTemplate(stageName) {
+      const templatePath = join(PROMPTS_PATH, 'stages', `${stageName}.md`);
+      if (!existsSync(templatePath)) return null;
+      return readFile(templatePath, 'utf-8');
+    },
+
+    /**
+     * Update stage template
+     */
+    async updateStageTemplate(stageName, content) {
+      const stagesDir = join(PROMPTS_PATH, 'stages');
+      if (!existsSync(stagesDir)) await mkdir(stagesDir, { recursive: true });
+      await writeFile(join(stagesDir, `${stageName}.md`), content);
+    },
+
+    /**
+     * Update stage configuration
+     */
+    async updateStageConfig(stageName, updatedConfig) {
+      if (!stageConfig) await loadPrompts();
+      stageConfig.stages[stageName] = { ...stageConfig.stages[stageName], ...updatedConfig };
+      await writeFile(join(PROMPTS_PATH, 'stage-config.json'), JSON.stringify(stageConfig, null, 2));
+    },
+
+    /**
+     * Create a new stage
+     */
+    async createStage(stageName, config, template = '') {
+      if (!stageConfig) await loadPrompts();
+      if (stageConfig.stages[stageName]) {
+        throw new Error(`Stage ${stageName} already exists`);
+      }
+      stageConfig.stages[stageName] = config;
+      await writeFile(join(PROMPTS_PATH, 'stage-config.json'), JSON.stringify(stageConfig, null, 2));
+
+      // Create template file
+      const stagesDir = join(PROMPTS_PATH, 'stages');
+      if (!existsSync(stagesDir)) await mkdir(stagesDir, { recursive: true });
+      await writeFile(join(stagesDir, `${stageName}.md`), template);
+
+      console.log(`✅ Created prompt stage: ${stageName}`);
+    },
+
+    /**
+     * Delete a stage
+     */
+    async deleteStage(stageName) {
+      if (!stageConfig) await loadPrompts();
+      if (!stageConfig.stages[stageName]) {
+        throw new Error(`Stage ${stageName} not found`);
+      }
+      delete stageConfig.stages[stageName];
+      await writeFile(join(PROMPTS_PATH, 'stage-config.json'), JSON.stringify(stageConfig, null, 2));
+
+      // Delete template file if it exists
+      const templatePath = join(PROMPTS_PATH, 'stages', `${stageName}.md`);
+      if (existsSync(templatePath)) {
+        const { unlink } = await import('fs/promises');
+        await unlink(templatePath);
+      }
+
+      console.log(`🗑️ Deleted prompt stage: ${stageName}`);
+    },
+
+    /**
+     * Get all variables
+     */
+    getVariables() {
+      return variables?.variables || {};
+    },
+
+    /**
+     * Get a single variable
+     */
+    getVariable(key) {
+      return variables?.variables?.[key] || null;
+    },
+
+    /**
+     * Update a variable
+     */
+    async updateVariable(key, data) {
+      if (!variables) await loadPrompts();
+      variables.variables[key] = { ...variables.variables[key], ...data };
+      await writeFile(join(PROMPTS_PATH, 'variables.json'), JSON.stringify(variables, null, 2));
+    },
+
+    /**
+     * Create a new variable
+     */
+    async createVariable(key, data) {
+      if (!variables) await loadPrompts();
+      if (variables.variables[key]) {
+        throw new Error(`Variable ${key} already exists`);
+      }
+      variables.variables[key] = data;
+      await writeFile(join(PROMPTS_PATH, 'variables.json'), JSON.stringify(variables, null, 2));
+    },
+
+    /**
+     * Delete a variable
+     */
+    async deleteVariable(key) {
+      if (!variables) await loadPrompts();
+      delete variables.variables[key];
+      await writeFile(join(PROMPTS_PATH, 'variables.json'), JSON.stringify(variables, null, 2));
+    },
+
+    /**
+     * Build a prompt from template and variables
+     */
+    async buildPrompt(stageName, data = {}) {
+      const stage = stageConfig?.stages?.[stageName];
+      if (!stage) throw new Error(`Stage ${stageName} not found`);
+
+      let template = await this.getStageTemplate(stageName);
+      if (!template) throw new Error(`Template for ${stageName} not found`);
+
+      const allVars = { ...data };
+      for (const varName of stage.variables || []) {
+        const v = variables?.variables?.[varName];
+        if (v) allVars[varName] = v.content;
+      }
+
+      return applyTemplate(template, allVars);
+    },
+
+    /**
+     * Preview a prompt with test data
+     */
+    async previewPrompt(stageName, testData = {}) {
+      return this.buildPrompt(stageName, testData);
+    }
+  };
+}

package/src/server/providers.js

@@ -0,0 +1,253 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+/**
+ * Create a provider service with configurable storage
+ */
+export function createProviderService(config = {}) {
+  const {
+    dataDir = './data',
+    providersFile = 'providers.json',
+    sampleFile = null
+  } = config;
+
+  const PROVIDERS_PATH = join(dataDir, providersFile);
+
+  async function ensureDataDir() {
+    if (!existsSync(dataDir)) {
+      await mkdir(dataDir, { recursive: true });
+    }
+  }
+
+  async function loadProviders() {
+    await ensureDataDir();
+
+    if (!existsSync(PROVIDERS_PATH)) {
+      // Copy from sample if exists
+      if (sampleFile && existsSync(sampleFile)) {
+        const sample = await readFile(sampleFile, 'utf-8');
+        await writeFile(PROVIDERS_PATH, sample);
+        return JSON.parse(sample);
+      }
+      return { activeProvider: null, providers: {} };
+    }
+
+    const content = await readFile(PROVIDERS_PATH, 'utf-8');
+    return JSON.parse(content);
+  }
+
+  async function saveProviders(data) {
+    await ensureDataDir();
+    await writeFile(PROVIDERS_PATH, JSON.stringify(data, null, 2));
+  }
+
+  return {
+    /**
+     * Get all providers with active provider info
+     */
+    async getAllProviders() {
+      const data = await loadProviders();
+      return {
+        activeProvider: data.activeProvider,
+        providers: Object.values(data.providers)
+      };
+    },
+
+    /**
+     * Get a specific provider by ID
+     */
+    async getProviderById(id) {
+      const data = await loadProviders();
+      return data.providers[id] || null;
+    },
+
+    /**
+     * Get the currently active provider
+     */
+    async getActiveProvider() {
+      const data = await loadProviders();
+      if (!data.activeProvider) return null;
+      return data.providers[data.activeProvider] || null;
+    },
+
+    /**
+     * Set the active provider
+     */
+    async setActiveProvider(id) {
+      const data = await loadProviders();
+      if (!data.providers[id]) {
+        return null;
+      }
+      data.activeProvider = id;
+      await saveProviders(data);
+      return data.providers[id];
+    },
+
+    /**
+     * Create a new provider
+     */
+    async createProvider(providerData) {
+      const data = await loadProviders();
+      const id = providerData.id || providerData.name.toLowerCase().replace(/[^a-z0-9]/g, '-');
+
+      if (data.providers[id]) {
+        throw new Error('Provider with this ID already exists');
+      }
+
+      const provider = {
+        id,
+        name: providerData.name,
+        type: providerData.type || 'cli',
+        command: providerData.command || null,
+        args: providerData.args || [],
+        endpoint: providerData.endpoint || null,
+        apiKey: providerData.apiKey || '',
+        models: providerData.models || [],
+        defaultModel: providerData.defaultModel || null,
+        timeout: providerData.timeout || 300000,
+        enabled: providerData.enabled !== false,
+        envVars: providerData.envVars || {}
+      };
+
+      data.providers[id] = provider;
+
+      // Set as active if it's the first provider
+      if (!data.activeProvider) {
+        data.activeProvider = id;
+      }
+
+      await saveProviders(data);
+      return provider;
+    },
+
+    /**
+     * Update an existing provider
+     */
+    async updateProvider(id, updates) {
+      const data = await loadProviders();
+
+      if (!data.providers[id]) {
+        return null;
+      }
+
+      const provider = {
+        ...data.providers[id],
+        ...updates,
+        id // Prevent ID override
+      };
+
+      data.providers[id] = provider;
+      await saveProviders(data);
+      return provider;
+    },
+
+    /**
+     * Delete a provider
+     */
+    async deleteProvider(id) {
+      const data = await loadProviders();
+
+      if (!data.providers[id]) {
+        return false;
+      }
+
+      delete data.providers[id];
+
+      // Clear active if it was deleted
+      if (data.activeProvider === id) {
+        const remaining = Object.keys(data.providers);
+        data.activeProvider = remaining.length > 0 ? remaining[0] : null;
+      }
+
+      await saveProviders(data);
+      return true;
+    },
+
+    /**
+     * Test provider connectivity
+     */
+    async testProvider(id) {
+      const data = await loadProviders();
+      const provider = data.providers[id];
+
+      if (!provider) {
+        return { success: false, error: 'Provider not found' };
+      }
+
+      if (provider.type === 'cli') {
+        // Test CLI availability
+        const { stdout, stderr } = await execAsync(`which ${provider.command}`).catch(() => ({ stdout: '', stderr: 'not found' }));
+
+        if (!stdout.trim()) {
+          return { success: false, error: `Command '${provider.command}' not found in PATH` };
+        }
+
+        // Try to get version or help
+        const { stdout: versionOut } = await execAsync(`${provider.command} --version 2>/dev/null || ${provider.command} -v 2>/dev/null || echo "available"`).catch(() => ({ stdout: 'available' }));
+
+        return {
+          success: true,
+          path: stdout.trim(),
+          version: versionOut.trim()
+        };
+      }
+
+      if (provider.type === 'api') {
+        // Test API endpoint
+        const modelsUrl = `${provider.endpoint}/models`;
+        const response = await fetch(modelsUrl, {
+          headers: provider.apiKey ? { 'Authorization': `Bearer ${provider.apiKey}` } : {}
+        }).catch(err => ({ ok: false, error: err.message }));
+
+        if (!response.ok) {
+          return { success: false, error: `API not reachable: ${response.error || response.status}` };
+        }
+
+        const models = await response.json().catch(() => ({ data: [] }));
+        return {
+          success: true,
+          endpoint: provider.endpoint,
+          models: models.data?.map(m => m.id) || []
+        };
+      }
+
+      return { success: false, error: 'Unknown provider type' };
+    },
+
+    /**
+     * Refresh models from API provider
+     */
+    async refreshProviderModels(id) {
+      const data = await loadProviders();
+      const provider = data.providers[id];
+
+      if (!provider || provider.type !== 'api') {
+        return null;
+      }
+
+      const modelsUrl = `${provider.endpoint}/models`;
+      const response = await fetch(modelsUrl, {
+        headers: provider.apiKey ? { 'Authorization': `Bearer ${provider.apiKey}` } : {}
+      }).catch(() => null);
+
+      if (!response?.ok) return null;
+
+      const responseData = await response.json().catch(() => ({ data: [] }));
+      const models = responseData.data?.map(m => m.id) || [];
+
+      const updatedProvider = {
+        ...data.providers[id],
+        models
+      };
+
+      data.providers[id] = updatedProvider;
+      await saveProviders(data);
+      return updatedProvider;
+    }
+  };
+}