@claudetools/tools 0.8.10 → 0.9.0

package/dist/codedna/kappa-api-generator.js

@@ -0,0 +1,493 @@
+// =============================================================================
+// Kappa v2.5 API Generator
+// =============================================================================
+//
+// Generates API route handlers from Kappa API blocks.
+// Supports multiple frameworks: Express, Hono, tRPC.
+//
+// =============================================================================
+// CRUD Action to HTTP Method Mapping
+// =============================================================================
+const CRUD_METHOD_MAP = {
+    create: 'post',
+    read: 'get',
+    update: 'patch',
+    delete: 'delete',
+    list: 'get',
+};
+const CRUD_PATH_SUFFIX = {
+    create: '',
+    read: '/:id',
+    update: '/:id',
+    delete: '/:id',
+    list: '',
+};
+// =============================================================================
+// Type Mappings
+// =============================================================================
+const PRIMITIVE_ZOD_MAP = {
+    string: 'z.string()',
+    int: 'z.number().int()',
+    float: 'z.number()',
+    bool: 'z.boolean()',
+    email: 'z.string().email()',
+    url: 'z.string().url()',
+    uuid: 'z.string().uuid()',
+    phone: 'z.string()',
+    slug: 'z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)',
+    markdown: 'z.string()',
+    json: 'z.record(z.unknown())',
+    timestamp: 'z.string().datetime()',
+    date: 'z.string().date()',
+    time: 'z.string().time()',
+    duration: 'z.string()',
+};
+// =============================================================================
+// Generator Class
+// =============================================================================
+export class KappaAPIGenerator {
+    framework;
+    provenance;
+    validation;
+    errorTypes;
+    basePath;
+    authMiddleware;
+    openapi;
+    constructor(options = {}) {
+        this.framework = options.framework ?? 'hono';
+        this.provenance = options.provenance ?? true;
+        this.validation = options.validation ?? true;
+        this.errorTypes = options.errorTypes ?? true;
+        this.basePath = options.basePath ?? '/api';
+        this.authMiddleware = options.authMiddleware ?? 'requireAuth';
+        this.openapi = options.openapi ?? false;
+    }
+    /**
+     * Generate API code from API blocks
+     */
+    generate(apis) {
+        const routes = this.generateRoutes(apis);
+        const result = { routes };
+        if (this.validation) {
+            result.validation = this.generateValidation(apis);
+        }
+        if (this.errorTypes) {
+            result.errors = this.generateErrors(apis);
+        }
+        if (this.openapi) {
+            result.openapi = this.generateOpenAPI(apis);
+        }
+        return result;
+    }
+    // ===========================================================================
+    // Route Analysis
+    // ===========================================================================
+    /**
+     * Extract all routes from API blocks
+     */
+    extractRoutes(apis) {
+        const routes = [];
+        for (const api of apis) {
+            const apiPath = `${this.basePath}/${this.toKebabCase(api.name)}`;
+            // Process explicit operations
+            for (const op of api.operations) {
+                routes.push(this.operationToRoute(op, apiPath));
+            }
+            // Process CRUD shorthands
+            for (const crud of api.crud) {
+                routes.push(...this.crudToRoutes(crud, apiPath));
+            }
+        }
+        return routes;
+    }
+    operationToRoute(op, apiPath) {
+        // Determine HTTP method from operation name patterns
+        const method = this.inferMethod(op.name);
+        const path = `${apiPath}/${this.toKebabCase(op.name)}`;
+        return {
+            method,
+            path,
+            handlerName: `handle${this.toPascalCase(op.name)}`,
+            operationName: op.name,
+            effects: op.effects,
+            requiresAuth: op.effects.includes('Auth'),
+            parameters: op.parameters,
+            check: op.check,
+            rateLimit: op.rateLimit,
+        };
+    }
+    crudToRoutes(crud, apiPath) {
+        const routes = [];
+        const entityPath = `${apiPath}/${this.toKebabCase(crud.entity)}s`;
+        for (const action of crud.actions) {
+            const method = CRUD_METHOD_MAP[action.action] ?? 'get';
+            const pathSuffix = CRUD_PATH_SUFFIX[action.action] ?? '';
+            routes.push({
+                method,
+                path: `${entityPath}${pathSuffix}`,
+                handlerName: `handle${this.toPascalCase(action.action)}${crud.entity}`,
+                operationName: `${action.action}${crud.entity}`,
+                effects: action.effects,
+                requiresAuth: action.effects.includes('Auth'),
+                parameters: [],
+                check: action.check,
+            });
+        }
+        return routes;
+    }
+    inferMethod(operationName) {
+        const name = operationName.toLowerCase();
+        if (name.startsWith('get') ||
+            name.startsWith('list') ||
+            name.startsWith('find') ||
+            name.startsWith('health') ||
+            name.startsWith('check') ||
+            name.startsWith('fetch') ||
+            name.startsWith('search')) {
+            return 'get';
+        }
+        if (name.startsWith('create') || name.startsWith('add') || name.startsWith('register')) {
+            return 'post';
+        }
+        if (name.startsWith('update') || name.startsWith('edit') || name.startsWith('modify')) {
+            return 'patch';
+        }
+        if (name.startsWith('delete') || name.startsWith('remove')) {
+            return 'delete';
+        }
+        // Default to POST for actions like login, signup, etc.
+        return 'post';
+    }
+    // ===========================================================================
+    // Route Generation
+    // ===========================================================================
+    generateRoutes(apis) {
+        switch (this.framework) {
+            case 'hono':
+                return this.generateHonoRoutes(apis);
+            case 'express':
+                return this.generateExpressRoutes(apis);
+            case 'trpc':
+                return this.generateTRPCRoutes(apis);
+            default:
+                return this.generateHonoRoutes(apis);
+        }
+    }
+    generateHonoRoutes(apis) {
+        const lines = [];
+        const routes = this.extractRoutes(apis);
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Framework: Hono`);
+            lines.push('');
+        }
+        // Imports
+        lines.push("import { Hono } from 'hono';");
+        if (this.validation) {
+            lines.push("import { zValidator } from '@hono/zod-validator';");
+            lines.push("import * as schemas from './validation.js';");
+        }
+        lines.push(`import { ${this.authMiddleware} } from '../middleware/auth.js';`);
+        lines.push('');
+        // Create app
+        lines.push('const app = new Hono();');
+        lines.push('');
+        // Generate route handlers
+        for (const route of routes) {
+            lines.push(this.generateHonoRoute(route));
+            lines.push('');
+        }
+        lines.push('export default app;');
+        lines.push('');
+        return lines.join('\n');
+    }
+    generateHonoRoute(route) {
+        const lines = [];
+        const middlewares = [];
+        // Auth middleware
+        if (route.requiresAuth) {
+            middlewares.push(this.authMiddleware);
+        }
+        // Validation middleware
+        if (this.validation && route.parameters.length > 0) {
+            const schemaName = `${route.operationName}Schema`;
+            middlewares.push(`zValidator('json', schemas.${schemaName})`);
+        }
+        // Build middleware string
+        const middlewareStr = middlewares.length > 0 ? middlewares.join(', ') + ', ' : '';
+        // Route definition
+        lines.push(`// ${route.operationName}`);
+        if (route.check) {
+            lines.push(`// Permission check: ${route.check}`);
+        }
+        lines.push(`app.${route.method}('${route.path}', ${middlewareStr}async (c) => {`);
+        lines.push(`  // TODO: Implement ${route.operationName}`);
+        // Generate effect comments
+        if (route.effects.length > 0) {
+            lines.push(`  // Effects: ${route.effects.join(', ')}`);
+        }
+        lines.push(`  return c.json({ message: 'Not implemented' }, 501);`);
+        lines.push('});');
+        return lines.join('\n');
+    }
+    generateExpressRoutes(apis) {
+        const lines = [];
+        const routes = this.extractRoutes(apis);
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Framework: Express`);
+            lines.push('');
+        }
+        // Imports
+        lines.push("import { Router } from 'express';");
+        if (this.validation) {
+            lines.push("import { validateRequest } from '../middleware/validate.js';");
+            lines.push("import * as schemas from './validation.js';");
+        }
+        lines.push(`import { ${this.authMiddleware} } from '../middleware/auth.js';`);
+        lines.push('');
+        // Create router
+        lines.push('const router = Router();');
+        lines.push('');
+        // Generate route handlers
+        for (const route of routes) {
+            lines.push(this.generateExpressRoute(route));
+            lines.push('');
+        }
+        lines.push('export default router;');
+        lines.push('');
+        return lines.join('\n');
+    }
+    generateExpressRoute(route) {
+        const lines = [];
+        const middlewares = [];
+        // Auth middleware
+        if (route.requiresAuth) {
+            middlewares.push(this.authMiddleware);
+        }
+        // Validation middleware
+        if (this.validation && route.parameters.length > 0) {
+            const schemaName = `${route.operationName}Schema`;
+            middlewares.push(`validateRequest(schemas.${schemaName})`);
+        }
+        // Build middleware array
+        const middlewareArgs = middlewares.length > 0 ? middlewares.join(', ') + ', ' : '';
+        // Route definition
+        lines.push(`// ${route.operationName}`);
+        lines.push(`router.${route.method}('${route.path}', ${middlewareArgs}async (req, res) => {`);
+        lines.push(`  // TODO: Implement ${route.operationName}`);
+        // Generate effect comments
+        if (route.effects.length > 0) {
+            lines.push(`  // Effects: ${route.effects.join(', ')}`);
+        }
+        lines.push(`  res.status(501).json({ message: 'Not implemented' });`);
+        lines.push('});');
+        return lines.join('\n');
+    }
+    generateTRPCRoutes(apis) {
+        const lines = [];
+        const routes = this.extractRoutes(apis);
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push(`// Framework: tRPC`);
+            lines.push('');
+        }
+        // Imports
+        lines.push("import { router, publicProcedure, protectedProcedure } from '../trpc.js';");
+        if (this.validation) {
+            lines.push("import * as schemas from './validation.js';");
+        }
+        lines.push('');
+        // Create router
+        lines.push('export const apiRouter = router({');
+        // Generate procedures
+        for (let i = 0; i < routes.length; i++) {
+            const route = routes[i];
+            const isLast = i === routes.length - 1;
+            lines.push(this.generateTRPCProcedure(route, isLast));
+        }
+        lines.push('});');
+        lines.push('');
+        lines.push('export type ApiRouter = typeof apiRouter;');
+        lines.push('');
+        return lines.join('\n');
+    }
+    generateTRPCProcedure(route, isLast) {
+        const lines = [];
+        const procedure = route.requiresAuth ? 'protectedProcedure' : 'publicProcedure';
+        const isMutation = ['post', 'put', 'patch', 'delete'].includes(route.method);
+        const procedureType = isMutation ? 'mutation' : 'query';
+        lines.push(`  // ${route.operationName}`);
+        lines.push(`  ${route.operationName}: ${procedure}`);
+        // Add input validation
+        if (this.validation && route.parameters.length > 0) {
+            const schemaName = `${route.operationName}Schema`;
+            lines.push(`    .input(schemas.${schemaName})`);
+        }
+        lines.push(`    .${procedureType}(async ({ ctx, input }) => {`);
+        lines.push(`      // TODO: Implement ${route.operationName}`);
+        // Generate effect comments
+        if (route.effects.length > 0) {
+            lines.push(`      // Effects: ${route.effects.join(', ')}`);
+        }
+        lines.push(`      throw new Error('Not implemented');`);
+        lines.push(`    })${isLast ? '' : ','}`);
+        return lines.join('\n');
+    }
+    // ===========================================================================
+    // Validation Generation
+    // ===========================================================================
+    generateValidation(apis) {
+        const lines = [];
+        const routes = this.extractRoutes(apis);
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push('// Validation schemas');
+            lines.push('');
+        }
+        lines.push("import { z } from 'zod';");
+        lines.push('');
+        // Generate schema for each operation with parameters
+        for (const route of routes) {
+            if (route.parameters.length > 0) {
+                lines.push(this.generateValidationSchema(route));
+                lines.push('');
+            }
+        }
+        return lines.join('\n');
+    }
+    generateValidationSchema(route) {
+        const lines = [];
+        const schemaName = `${route.operationName}Schema`;
+        lines.push(`export const ${schemaName} = z.object({`);
+        for (const param of route.parameters) {
+            const zodType = this.fieldTypeToZod(param.type);
+            const optional = param.optional ? '.optional()' : '';
+            lines.push(`  ${param.name}: ${zodType}${optional},`);
+        }
+        lines.push('});');
+        lines.push('');
+        lines.push(`export type ${this.toPascalCase(route.operationName)}Input = z.infer<typeof ${schemaName}>;`);
+        return lines.join('\n');
+    }
+    fieldTypeToZod(type) {
+        switch (type.kind) {
+            case 'primitive':
+                return PRIMITIVE_ZOD_MAP[type.type] || 'z.unknown()';
+            case 'enum':
+                return `z.enum([${type.values.map(v => `'${v}'`).join(', ')}])`;
+            case 'reference':
+                return 'z.string().uuid()';
+            case 'array':
+                return `z.array(${this.fieldTypeToZod(type.itemType)})`;
+            default:
+                return 'z.unknown()';
+        }
+    }
+    // ===========================================================================
+    // Error Types Generation
+    // ===========================================================================
+    generateErrors(apis) {
+        const lines = [];
+        const errorTypes = new Set();
+        // Collect all error types from operations
+        for (const api of apis) {
+            for (const op of api.operations) {
+                if (op.throws) {
+                    for (const error of op.throws) {
+                        errorTypes.add(error);
+                    }
+                }
+            }
+        }
+        // Header
+        if (this.provenance) {
+            lines.push('// Generated by Kappa v2.5 CodeDNA');
+            lines.push('// API error types');
+            lines.push('');
+        }
+        // Base error class
+        lines.push('export class APIError extends Error {');
+        lines.push('  constructor(');
+        lines.push('    public code: string,');
+        lines.push('    public status: number,');
+        lines.push('    message: string');
+        lines.push('  ) {');
+        lines.push('    super(message);');
+        lines.push("    this.name = 'APIError';");
+        lines.push('  }');
+        lines.push('}');
+        lines.push('');
+        // Generate specific error classes
+        for (const errorType of errorTypes) {
+            const className = `${errorType}Error`;
+            const status = this.inferErrorStatus(errorType);
+            lines.push(`export class ${className} extends APIError {`);
+            lines.push(`  constructor(message = '${this.toSentenceCase(errorType)}') {`);
+            lines.push(`    super('${errorType}', ${status}, message);`);
+            lines.push(`    this.name = '${className}';`);
+            lines.push('  }');
+            lines.push('}');
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    inferErrorStatus(errorType) {
+        const type = errorType.toLowerCase();
+        if (type.includes('notfound'))
+            return 404;
+        if (type.includes('unauthorized') || type.includes('auth'))
+            return 401;
+        if (type.includes('forbidden') || type.includes('permission'))
+            return 403;
+        if (type.includes('validation') || type.includes('invalid'))
+            return 400;
+        if (type.includes('conflict') || type.includes('duplicate'))
+            return 409;
+        if (type.includes('ratelimit'))
+            return 429;
+        return 500;
+    }
+    // ===========================================================================
+    // OpenAPI Generation (stub)
+    // ===========================================================================
+    generateOpenAPI(_apis) {
+        // TODO: Implement OpenAPI schema generation
+        return '// OpenAPI schema generation not yet implemented\n';
+    }
+    // ===========================================================================
+    // Utility Functions
+    // ===========================================================================
+    toKebabCase(str) {
+        return str
+            .replace(/([a-z])([A-Z])/g, '$1-$2')
+            .replace(/[\s_]+/g, '-')
+            .toLowerCase();
+    }
+    toPascalCase(str) {
+        return str
+            .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+            .replace(/^./, s => s.toUpperCase());
+    }
+    toSentenceCase(str) {
+        return str
+            .replace(/([A-Z])/g, ' $1')
+            .trim()
+            .toLowerCase()
+            .replace(/^./, s => s.toUpperCase());
+    }
+}
+// =============================================================================
+// Convenience Function
+// =============================================================================
+/**
+ * Generate API code from Kappa API blocks
+ */
+export function generateAPI(apis, options = {}) {
+    const generator = new KappaAPIGenerator(options);
+    return generator.generate(apis);
+}