create-web-ai-service 1.0.0

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.js');

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Create Web AI Service CLI
+ *
+ * Main entry point for the scaffolder.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,103 @@
+/**
+ * Create Web AI Service CLI
+ *
+ * Main entry point for the scaffolder.
+ */
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { promptForOptions } from './prompts.js';
+import { generateProject } from './templates.js';
+/**
+ * Print banner
+ */
+function printBanner() {
+    console.log('');
+    console.log(chalk.bold.cyan('╔════════════════════════════════════════════╗'));
+    console.log(chalk.bold.cyan('║') + chalk.bold.white('   🚀 Create Web AI Service                ') + chalk.bold.cyan('║'));
+    console.log(chalk.bold.cyan('║') + chalk.gray('   Build AI-powered APIs with YAML         ') + chalk.bold.cyan('║'));
+    console.log(chalk.bold.cyan('╚════════════════════════════════════════════╝'));
+    console.log('');
+}
+/**
+ * Parse command line arguments
+ */
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {};
+    // First non-flag argument is the project name
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--plugins' && args[i + 1]) {
+            result.plugins = args[i + 1].split(',').map(s => s.trim());
+            i++;
+        }
+        else if (!arg.startsWith('-') && !result.projectName) {
+            result.projectName = arg;
+        }
+    }
+    return result;
+}
+/**
+ * Install dependencies using npm
+ */
+function installDependencies(projectPath) {
+    console.log('');
+    console.log(chalk.cyan('📦 Installing dependencies...'));
+    console.log('');
+    try {
+        execSync('npm install', {
+            cwd: projectPath,
+            stdio: 'inherit',
+        });
+    }
+    catch (error) {
+        console.log(chalk.yellow('⚠️  Failed to install dependencies. Please run npm install manually.'));
+    }
+}
+/**
+ * Print success message with next steps
+ */
+function printSuccess(projectName) {
+    console.log('');
+    console.log(chalk.green('✅ Project created successfully!'));
+    console.log('');
+    console.log(chalk.bold('Next steps:'));
+    console.log('');
+    console.log(chalk.cyan(`  cd ${projectName}`));
+    console.log(chalk.cyan('  cp .env.example .env'));
+    console.log(chalk.gray('  # Edit .env with your API keys'));
+    console.log(chalk.cyan('  npm run dev'));
+    console.log('');
+    console.log(chalk.gray('Then visit: ') + chalk.underline('http://localhost:3000/hello'));
+    console.log('');
+    console.log(chalk.bold('Documentation:'));
+    console.log(chalk.gray('  • Getting Started: ') + chalk.underline('https://github.com/yourrepo/web-ai-service#readme'));
+    console.log(chalk.gray('  • Creating Endpoints: see docs/creating-endpoints.md'));
+    console.log('');
+}
+/**
+ * Main function
+ */
+async function main() {
+    printBanner();
+    const cliArgs = parseArgs();
+    // Get scaffold options (from prompts or CLI args)
+    const options = await promptForOptions(cliArgs.projectName);
+    // Override plugins if provided via CLI
+    if (cliArgs.plugins && cliArgs.plugins.length > 0) {
+        options.plugins = cliArgs.plugins;
+    }
+    console.log('');
+    console.log(chalk.cyan('🔧 Creating project...'));
+    // Generate project
+    await generateProject(options);
+    // Install dependencies
+    installDependencies(options.projectPath);
+    // Print success
+    printSuccess(options.projectName);
+}
+// Run
+main().catch((error) => {
+    console.error(chalk.red('Error:'), error.message);
+    process.exit(1);
+});

package/dist/plugins.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Plugin Registry
+ *
+ * Defines available plugins for the scaffolder.
+ * Add new plugins here to make them available in the CLI.
+ */
+export interface PluginEnvVar {
+    name: string;
+    description: string;
+    example: string;
+}
+export interface PluginConfig {
+    name: string;
+    description: string;
+    dependencies: Record<string, string>;
+    envVars: PluginEnvVar[];
+    files: {
+        source: string;
+        destination: string;
+    }[];
+}
+/**
+ * Available plugins registry
+ * Add new plugins to this object to make them available in the CLI
+ */
+export declare const plugins: Record<string, PluginConfig>;
+/**
+ * Get list of available plugin names
+ */
+export declare function getAvailablePlugins(): string[];
+/**
+ * Get plugin config by name
+ */
+export declare function getPluginConfig(name: string): PluginConfig | undefined;
+/**
+ * Get choices for inquirer checkbox
+ */
+export declare function getPluginChoices(): {
+    name: string;
+    value: string;
+    checked: boolean;
+}[];

package/dist/plugins.js

@@ -0,0 +1,64 @@
+/**
+ * Plugin Registry
+ *
+ * Defines available plugins for the scaffolder.
+ * Add new plugins here to make them available in the CLI.
+ */
+/**
+ * Available plugins registry
+ * Add new plugins to this object to make them available in the CLI
+ */
+export const plugins = {
+    supabase: {
+        name: 'Supabase',
+        description: 'Database & Auth integration with Supabase',
+        dependencies: {
+            '@supabase/supabase-js': '^2.90.1',
+        },
+        envVars: [
+            {
+                name: 'SUPABASE_URL',
+                description: 'Your Supabase project URL',
+                example: 'https://your-project.supabase.co',
+            },
+            {
+                name: 'SUPABASE_ANON_KEY',
+                description: 'Your Supabase anon/public key',
+                example: 'your-supabase-anon-key',
+            },
+            {
+                name: 'SUPABASE_SERVICE_KEY',
+                description: 'Your Supabase service role key (optional, for admin operations)',
+                example: 'your-supabase-service-key',
+            },
+        ],
+        files: [
+            {
+                source: 'plugins/supabase/src/plugins/supabase.ts',
+                destination: 'src/plugins/supabase.ts',
+            },
+        ],
+    },
+};
+/**
+ * Get list of available plugin names
+ */
+export function getAvailablePlugins() {
+    return Object.keys(plugins);
+}
+/**
+ * Get plugin config by name
+ */
+export function getPluginConfig(name) {
+    return plugins[name];
+}
+/**
+ * Get choices for inquirer checkbox
+ */
+export function getPluginChoices() {
+    return Object.entries(plugins).map(([key, plugin]) => ({
+        name: `${plugin.name} - ${plugin.description}`,
+        value: key,
+        checked: false,
+    }));
+}

package/dist/prompts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI Prompts Module
+ *
+ * Defines interactive prompts for the scaffolder CLI.
+ */
+export interface ScaffoldOptions {
+    projectName: string;
+    projectPath: string;
+    plugins: string[];
+}
+/**
+ * Run interactive prompts to gather scaffold options
+ */
+export declare function promptForOptions(initialName?: string): Promise<ScaffoldOptions>;

package/dist/prompts.js

@@ -0,0 +1,77 @@
+/**
+ * CLI Prompts Module
+ *
+ * Defines interactive prompts for the scaffolder CLI.
+ */
+import inquirer from 'inquirer';
+import { getPluginChoices } from './plugins.js';
+import path from 'path';
+import fs from 'fs-extra';
+/**
+ * Validate project name
+ */
+function validateProjectName(input) {
+    if (!input || input.trim().length === 0) {
+        return 'Project name is required';
+    }
+    // Check for valid npm package name format
+    const validPattern = /^[a-z0-9]([a-z0-9-_.]*[a-z0-9])?$/;
+    if (!validPattern.test(input.toLowerCase())) {
+        return 'Project name must be lowercase and can only contain letters, numbers, hyphens, dots, and underscores';
+    }
+    return true;
+}
+/**
+ * Check if directory exists
+ */
+async function checkDirectoryExists(projectPath) {
+    try {
+        await fs.access(projectPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run interactive prompts to gather scaffold options
+ */
+export async function promptForOptions(initialName) {
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'projectName',
+            message: 'What is your project name?',
+            default: initialName || 'my-api',
+            validate: validateProjectName,
+            filter: (input) => input.trim().toLowerCase(),
+        },
+        {
+            type: 'checkbox',
+            name: 'plugins',
+            message: 'Which plugins would you like to install?',
+            choices: getPluginChoices(),
+        },
+    ]);
+    const projectPath = path.resolve(process.cwd(), answers.projectName);
+    // Check if directory already exists
+    if (await checkDirectoryExists(projectPath)) {
+        const { overwrite } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'overwrite',
+                message: `Directory ${answers.projectName} already exists. Overwrite?`,
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log('Aborted. Please choose a different project name.');
+            process.exit(1);
+        }
+    }
+    return {
+        projectName: answers.projectName,
+        projectPath,
+        plugins: answers.plugins,
+    };
+}

package/dist/templates.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Template Generation Module
+ *
+ * Handles copying and rendering template files.
+ */
+import { ScaffoldOptions } from './prompts.js';
+/**
+ * Generate project from templates
+ */
+export declare function generateProject(options: ScaffoldOptions): Promise<void>;

package/dist/templates.js

@@ -0,0 +1,107 @@
+/**
+ * Template Generation Module
+ *
+ * Handles copying and rendering template files.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import ejs from 'ejs';
+import { fileURLToPath } from 'url';
+import { getPluginConfig } from './plugins.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Templates are in the parent directory relative to dist/
+const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
+/**
+ * Build template data from scaffold options
+ */
+function buildTemplateData(options) {
+    const dependencies = {
+        'web-ai-service': '^1.0.0',
+    };
+    const devDependencies = {
+        '@types/node': '^20.11.5',
+        'typescript': '^5.3.3',
+        'tsx': '^4.7.0',
+    };
+    const envVars = [];
+    // Add plugin dependencies and env vars
+    for (const pluginName of options.plugins) {
+        const plugin = getPluginConfig(pluginName);
+        if (plugin) {
+            Object.assign(dependencies, plugin.dependencies);
+            envVars.push(...plugin.envVars);
+        }
+    }
+    return {
+        projectName: options.projectName,
+        plugins: options.plugins,
+        dependencies,
+        devDependencies,
+        envVars,
+    };
+}
+/**
+ * Copy and render base template files
+ */
+async function copyBaseTemplate(options, data) {
+    const baseDir = path.join(TEMPLATES_DIR, 'base');
+    // Get all files in base template
+    const files = await fs.readdir(baseDir, { recursive: true });
+    for (const file of files) {
+        const sourcePath = path.join(baseDir, file.toString());
+        const stat = await fs.stat(sourcePath);
+        if (stat.isDirectory()) {
+            continue;
+        }
+        // Determine destination path (remove .ejs extension if present)
+        let destFile = file.toString();
+        const isEjsTemplate = destFile.endsWith('.ejs');
+        if (isEjsTemplate) {
+            destFile = destFile.slice(0, -4); // Remove .ejs
+        }
+        const destPath = path.join(options.projectPath, destFile);
+        // Ensure destination directory exists
+        await fs.ensureDir(path.dirname(destPath));
+        if (isEjsTemplate) {
+            // Render EJS template
+            const content = await fs.readFile(sourcePath, 'utf-8');
+            const rendered = ejs.render(content, data);
+            await fs.writeFile(destPath, rendered);
+        }
+        else {
+            // Copy file as-is
+            await fs.copy(sourcePath, destPath);
+        }
+    }
+}
+/**
+ * Copy plugin files
+ */
+async function copyPluginFiles(options) {
+    for (const pluginName of options.plugins) {
+        const plugin = getPluginConfig(pluginName);
+        if (!plugin)
+            continue;
+        for (const fileMapping of plugin.files) {
+            const sourcePath = path.join(TEMPLATES_DIR, fileMapping.source);
+            const destPath = path.join(options.projectPath, fileMapping.destination);
+            // Ensure destination directory exists
+            await fs.ensureDir(path.dirname(destPath));
+            // Copy file
+            await fs.copy(sourcePath, destPath);
+        }
+    }
+}
+/**
+ * Generate project from templates
+ */
+export async function generateProject(options) {
+    const data = buildTemplateData(options);
+    // Ensure project directory exists (clean if exists)
+    await fs.ensureDir(options.projectPath);
+    // Copy base template
+    await copyBaseTemplate(options, data);
+    // Copy plugin files
+    await copyPluginFiles(options);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "create-web-ai-service",
+    "version": "1.0.0",
+    "description": "CLI scaffolder for creating new web-ai-service projects",
+    "type": "module",
+    "main": "dist/index.js",
+    "bin": {
+        "create-web-ai-service": "./bin/cli.js"
+    },
+    "files": [
+        "dist",
+        "bin",
+        "templates"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "cli",
+        "scaffolder",
+        "web-ai-service",
+        "api",
+        "workflow",
+        "llm"
+    ],
+    "author": "",
+    "license": "ISC",
+    "dependencies": {
+        "chalk": "^5.3.0",
+        "ejs": "^3.1.10",
+        "inquirer": "^9.2.12",
+        "fs-extra": "^11.2.0"
+    },
+    "devDependencies": {
+        "@types/ejs": "^3.1.5",
+        "@types/fs-extra": "^11.0.4",
+        "@types/inquirer": "^9.0.7",
+        "@types/node": "^20.11.5",
+        "typescript": "^5.3.3"
+    }
+}

package/templates/base/.env.example.ejs

@@ -0,0 +1,22 @@
+# Server Configuration
+PORT=3000
+
+# LLM Provider API Keys (add keys for providers you want to use)
+GEMINI_API_KEY=your-gemini-api-key-here
+GROK_API_KEY=your-grok-api-key-here
+OPENAI_API_KEY=your-openai-api-key-here
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+
+# LLM Configuration
+LLM_TIMEOUT_MS=30000
+
+# Logging
+LOG_LEVEL=info
+<% if (envVars.length > 0) { %>
+
+# Plugin Configuration
+<% for (const envVar of envVars) { %>
+# <%= envVar.description %>
+<%= envVar.name %>=<%= envVar.example %>
+<% } %>
+<% } %>

package/templates/base/README.md.ejs

@@ -0,0 +1,46 @@
+# <%= projectName %>
+
+    An AI-powered API service built with [web-ai-service](https://github.com/yourrepo/web-ai-service).
+
+    ## Quick Start
+
+    ```bash
+    # Install dependencies
+    npm install
+
+    # Configure environment
+    cp .env.example .env
+    # Edit .env with your API keys
+
+    # Start development server
+    npm run dev
+    ```
+
+    Server starts at `http://localhost:3000`.
+
+    ## Project Structure
+
+    ```
+    <%= projectName %>/
+        ├── src/
+        │ ├── endpoints/ # API endpoint definitions
+        │ │ └── hello/ # Example endpoint → GET /hello
+        │ │ ├── GET.yaml # Workflow definition
+        │ │ ├── codes/ # TypeScript code nodes
+        │ │ └── prompts/ # LLM system prompts
+        │ └── plugins/ # Shared code modules
+        ├── .env # Environment configuration
+        └── package.json
+        ```
+
+        ## Creating Endpoints
+
+        Each folder in `src/endpoints/` becomes an API route. Create a YAML file named after the HTTP method (e.g.,
+        `POST.yaml`, `GET.yaml`).
+
+        See the `hello` endpoint for an example.
+
+        ## Learn More
+
+        - [Web AI Service Documentation](https://github.com/yourrepo/web-ai-service)
+        - [Creating Endpoints Guide](./docs/creating-endpoints.md)

package/templates/base/package.json.ejs

@@ -0,0 +1,25 @@
+{
+  "name": "<%= projectName %>",
+  "version": "1.0.0",
+  "description": "An AI-powered API service built with web-ai-service",
+  "type": "module",
+  "scripts": {
+    "dev": "web-ai-service",
+    "build": "tsc",
+    "start": "node dist/engine/cli.js",
+    "validate": "web-ai-service validate"
+  },
+  "keywords": [
+    "api",
+    "ai",
+    "workflow"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+<%- Object.entries(dependencies).map(([name, version]) => `    "${name}": "${version}"`).join(',\n') %>
+  },
+  "devDependencies": {
+<%- Object.entries(devDependencies).map(([name, version]) => `    "${name}": "${version}"`).join(',\n') %>
+  }
+}

package/templates/base/src/endpoints/hello/GET.yaml

@@ -0,0 +1,23 @@
+version: "1.0"
+
+stages:
+  - name: process
+    nodes:
+      # Code node to transform and validate the request
+      format_greeting:
+        type: code
+        input: $input
+        file: format-greeting.ts
+
+  - name: respond
+    nodes:
+      # LLM node to generate a personalized greeting
+      greeting:
+        type: llm
+        input: process.format_greeting
+        provider: gemini
+        model: gemini-2.0-flash-lite
+        temperature: 0.7
+        maxTokens: 256
+        systemMessages:
+          - file: greeting-system.txt

package/templates/base/src/endpoints/hello/codes/format-greeting.ts

@@ -0,0 +1,65 @@
+/**
+ * Format Greeting Code Node
+ * 
+ * This code node demonstrates input processing before passing to an LLM.
+ * It extracts and validates the name parameter, then formats the request
+ * for the greeting LLM node.
+ */
+
+import type { NodeOutput } from '@workflow/types';
+
+interface HelloInput {
+    name?: string;
+}
+
+interface FormattedRequest {
+    name: string;
+    timestamp: string;
+    greeting_type: 'morning' | 'afternoon' | 'evening';
+}
+
+/**
+ * Determine greeting type based on current time
+ */
+function getGreetingType(): 'morning' | 'afternoon' | 'evening' {
+    const hour = new Date().getHours();
+
+    if (hour < 12) {
+        return 'morning';
+    } else if (hour < 17) {
+        return 'afternoon';
+    } else {
+        return 'evening';
+    }
+}
+
+/**
+ * Main code node function
+ * 
+ * @param input - The raw request input
+ * @returns Formatted request for the LLM node
+ */
+export default async function (input: unknown): Promise<NodeOutput> {
+    const data = input as HelloInput;
+
+    // Extract and validate name (default to 'World')
+    const name = data.name?.trim() || 'World';
+
+    // Validate name length
+    if (name.length > 100) {
+        throw new Error('Name must be 100 characters or less');
+    }
+
+    // Build formatted request
+    const formatted: FormattedRequest = {
+        name,
+        timestamp: new Date().toISOString(),
+        greeting_type: getGreetingType(),
+    };
+
+    // Return as JSON output for the next node
+    return {
+        type: 'json',
+        value: formatted,
+    };
+}

package/templates/base/src/endpoints/hello/prompts/greeting-system.txt

@@ -0,0 +1,18 @@
+You are a friendly greeting assistant. Generate warm, personalized greetings.
+
+You will receive a JSON object with:
+- name: The person's name to greet
+- timestamp: Current ISO timestamp
+- greeting_type: Either 'morning', 'afternoon', or 'evening'
+
+Generate a friendly, contextual greeting that:
+1. Uses the appropriate time-of-day salutation (Good morning/afternoon/evening)
+2. Addresses the person by name
+3. Adds a brief, positive message appropriate to the time of day
+4. Keeps the total response under 2 sentences
+
+Example input:
+{"name": "Alice", "timestamp": "2024-01-15T09:30:00Z", "greeting_type": "morning"}
+
+Example output:
+Good morning, Alice! Hope you have a wonderful and productive day ahead.

package/templates/base/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "paths": {
+            "@workflow/types": [
+                "./node_modules/web-ai-service/dist/engine/types/index.js"
+            ],
+            "@code-plugins/*": [
+                "./src/plugins/*"
+            ]
+        }
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}

package/templates/plugins/supabase/src/plugins/supabase.ts

@@ -0,0 +1,93 @@
+/**
+ * Supabase Plugin
+ * 
+ * Provides a configured Supabase client for use in code nodes.
+ * 
+ * Usage in code nodes:
+ * ```typescript
+ * import { supabase, getSupabaseClient } from '@code-plugins/supabase.js';
+ * 
+ * // Use the default client (reads from env vars)
+ * const { data, error } = await supabase.from('table').select('*');
+ * 
+ * // Or create a custom client
+ * const client = getSupabaseClient('https://custom.supabase.co', 'custom-key');
+ * ```
+ * 
+ * Required environment variables:
+ * - SUPABASE_URL: Your Supabase project URL
+ * - SUPABASE_ANON_KEY: Your Supabase anon/public key
+ * - SUPABASE_SERVICE_KEY: (Optional) Service role key for admin operations
+ */
+
+import { createClient, SupabaseClient } from '@supabase/supabase-js';
+
+// Default client instance (lazy initialized)
+let defaultClient: SupabaseClient | null = null;
+
+/**
+ * Get the Supabase URL from environment
+ */
+function getSupabaseUrl(): string {
+    const url = process.env.SUPABASE_URL;
+    if (!url) {
+        throw new Error('SUPABASE_URL environment variable is required');
+    }
+    return url;
+}
+
+/**
+ * Get the Supabase key from environment
+ * Prefers service key for server-side operations, falls back to anon key
+ */
+function getSupabaseKey(): string {
+    const serviceKey = process.env.SUPABASE_SERVICE_KEY;
+    const anonKey = process.env.SUPABASE_ANON_KEY;
+
+    if (serviceKey) {
+        return serviceKey;
+    }
+    if (anonKey) {
+        return anonKey;
+    }
+    throw new Error('SUPABASE_SERVICE_KEY or SUPABASE_ANON_KEY environment variable is required');
+}
+
+/**
+ * Create a new Supabase client with custom URL and key
+ */
+export function getSupabaseClient(url?: string, key?: string): SupabaseClient {
+    const supabaseUrl = url || getSupabaseUrl();
+    const supabaseKey = key || getSupabaseKey();
+
+    return createClient(supabaseUrl, supabaseKey, {
+        auth: {
+            autoRefreshToken: false,
+            persistSession: false,
+        },
+    });
+}
+
+/**
+ * Get the default Supabase client (singleton)
+ * Uses environment variables for configuration
+ */
+export function getDefaultClient(): SupabaseClient {
+    if (!defaultClient) {
+        defaultClient = getSupabaseClient();
+    }
+    return defaultClient;
+}
+
+/**
+ * Default Supabase client instance
+ * Lazy-loaded on first access
+ */
+export const supabase: SupabaseClient = new Proxy({} as SupabaseClient, {
+    get(_target, prop) {
+        return Reflect.get(getDefaultClient(), prop);
+    },
+});
+
+// Re-export useful types
+export type { SupabaseClient } from '@supabase/supabase-js';