@hyperfixi/server-bridge 2.0.0

package/src/conventions/url-patterns.ts

@@ -0,0 +1,123 @@
+import type { HttpMethod, QueryParam } from '../types.js';
+
+/**
+ * Extract path parameter names from a URL pattern.
+ * Handles both `:param` and `{param}` styles.
+ *
+ * @example
+ *   extractPathParams('/api/users/:id') // ['id']
+ *   extractPathParams('/api/users/{id}/orders/{orderId}') // ['id', 'orderId']
+ */
+export function extractPathParams(url: string): string[] {
+  const params: string[] = [];
+  // Match :param style
+  for (const match of url.matchAll(/:(\w+)/g)) {
+    params.push(match[1]);
+  }
+  // Match {param} style
+  for (const match of url.matchAll(/\{(\w+)\}/g)) {
+    if (!params.includes(match[1])) {
+      params.push(match[1]);
+    }
+  }
+  return params;
+}
+
+/**
+ * Normalize a URL path:
+ * - Convert `{param}` to `:param`
+ * - Strip trailing slashes
+ * - Ensure leading slash
+ * - Strip query strings
+ * - Strip fragments
+ */
+export function normalizeUrl(url: string): string {
+  // Strip query string and fragment
+  let normalized = url.split('?')[0].split('#')[0];
+
+  // Convert {param} to :param
+  normalized = normalized.replace(/\{(\w+)\}/g, ':$1');
+
+  // Ensure leading slash
+  if (!normalized.startsWith('/')) {
+    normalized = '/' + normalized;
+  }
+
+  // Strip trailing slash (but keep root /)
+  if (normalized.length > 1 && normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+/**
+ * Convert a URL path + method into a handler function name.
+ *
+ * @example
+ *   urlToHandlerName('/api/users', 'GET') // 'getApiUsers'
+ *   urlToHandlerName('/api/users/:id', 'POST') // 'postApiUsersById'
+ */
+export function urlToHandlerName(url: string, method: HttpMethod): string {
+  const prefix = method.toLowerCase();
+
+  // Remove leading slash, split by / and :
+  const segments = url
+    .replace(/^\//, '')
+    .split('/')
+    .map(segment => {
+      if (segment.startsWith(':')) {
+        // :id -> ById, :userId -> ByUserId
+        const param = segment.slice(1);
+        return 'By' + capitalize(param);
+      }
+      // api -> Api, user-list -> UserList
+      return segment.split(/[-_]/).map(capitalize).join('');
+    });
+
+  return prefix + segments.join('');
+}
+
+/**
+ * Extract query parameter names from a URL string.
+ * Must be called BEFORE normalizeUrl (which strips query strings).
+ *
+ * @example
+ *   extractQueryParams('/api/search?q=hello&limit=10')
+ *   // [{ name: 'q', type: 'string', required: true },
+ *   //  { name: 'limit', type: 'string', required: true }]
+ */
+export function extractQueryParams(url: string): QueryParam[] {
+  const queryIndex = url.indexOf('?');
+  if (queryIndex === -1) return [];
+
+  const queryString = url.slice(queryIndex + 1).split('#')[0];
+  if (!queryString) return [];
+
+  const params: QueryParam[] = [];
+  const seen = new Set<string>();
+
+  for (const pair of queryString.split('&')) {
+    const eqIndex = pair.indexOf('=');
+    const rawName = eqIndex === -1 ? pair : pair.slice(0, eqIndex);
+    if (!rawName) continue;
+
+    let name: string;
+    try {
+      name = decodeURIComponent(rawName);
+    } catch {
+      name = rawName;
+    }
+    if (seen.has(name)) continue;
+    seen.add(name);
+
+    params.push({ name, type: 'string', required: true });
+  }
+
+  return params;
+}
+
+function capitalize(s: string): string {
+  if (!s) return '';
+  return s[0].toUpperCase() + s.slice(1);
+}

package/src/generate.ts

@@ -0,0 +1,44 @@
+import { resolve } from 'node:path';
+import { scanDirectory } from './scanner/route-scanner.js';
+import { selectGenerator } from './generators/index.js';
+import type { GenerateResult, RouteDescriptor, ScanResult } from './types.js';
+
+export interface ProgrammaticGenerateOptions {
+  dir: string;
+  framework?: 'express' | 'hono' | 'openapi' | 'django' | 'fastapi';
+  output?: string;
+  typescript?: boolean;
+  include?: string[];
+  exclude?: string[];
+  ignore?: string[];
+}
+
+export interface GenerateFullResult {
+  scan: ScanResult;
+  generated: GenerateResult;
+  routes: RouteDescriptor[];
+}
+
+/**
+ * Programmatic scan + generate. Scans a directory for routes and generates
+ * framework-specific route files. Returns structured results for the caller
+ * to write to disk.
+ */
+export async function generate(options: ProgrammaticGenerateOptions): Promise<GenerateFullResult> {
+  const cwd = resolve(options.dir);
+  const outputDir = resolve(cwd, options.output ?? './server/routes');
+
+  const scan = await scanDirectory(cwd, {
+    include: options.include,
+    exclude: options.exclude,
+    ignore: options.ignore,
+  });
+
+  const generator = selectGenerator(options.framework ?? 'express');
+  const generated = generator.generate(scan.routes, {
+    outputDir,
+    typescript: options.typescript,
+  });
+
+  return { scan, generated, routes: scan.routes };
+}

package/src/generators/django-generator.ts

@@ -0,0 +1,210 @@
+import type { RouteDescriptor, GeneratorOptions, GenerateResult, GeneratedFile } from '../types.js';
+import type { RouteGenerator } from './types.js';
+import { groupRoutesByPrefix } from './template-helpers.js';
+
+const PY_ROUTE_MARKER = '# @serverbridge-route:';
+const PY_USER_START = '# @serverbridge-user-start';
+const PY_USER_END = '# @serverbridge-user-end';
+
+export class DjangoGenerator implements RouteGenerator {
+  readonly framework = 'django';
+
+  generate(routes: RouteDescriptor[], options: GeneratorOptions): GenerateResult {
+    const files: GeneratedFile[] = [];
+    const warnings: string[] = [];
+
+    if (routes.length === 0) {
+      warnings.push('No routes to generate');
+      return { files, preserved: [], warnings };
+    }
+
+    const groups = groupRoutesByPrefix(routes);
+
+    // Generate views.py and urls.py per group
+    for (const [groupKey, groupRoutes] of groups) {
+      const views = this.generateViews(groupRoutes, groupKey);
+      files.push({ path: `${groupKey}/views.py`, content: views, isNew: true });
+
+      const urls = this.generateUrls(groupRoutes, groupKey);
+      files.push({ path: `${groupKey}/urls.py`, content: urls, isNew: true });
+
+      // Empty __init__.py for Python package
+      files.push({ path: `${groupKey}/__init__.py`, content: '', isNew: true });
+    }
+
+    // Root urls.py that includes all groups
+    const rootUrls = this.generateRootUrls(groups);
+    files.push({ path: 'urls.py', content: rootUrls, isNew: true });
+
+    return { files, preserved: [], warnings };
+  }
+
+  private generateViews(routes: RouteDescriptor[], groupKey: string): string {
+    const lines: string[] = [];
+
+    lines.push(`# Generated by @hyperfixi/server-bridge — DO NOT EDIT scaffold markers`);
+    lines.push(`from django.http import JsonResponse, HttpResponse`);
+
+    // Check if any route needs request body parsing
+    const needsJson = routes.some(
+      r => r.requestBody && r.requestBody.length > 0 && ['POST', 'PUT', 'PATCH'].includes(r.method)
+    );
+    if (needsJson) {
+      lines.push(`import json`);
+    }
+
+    // Check if we need decorators
+    const hasNonGet = routes.some(r => r.method !== 'GET');
+    if (hasNonGet) {
+      lines.push(`from django.views.decorators.http import require_http_methods`);
+    }
+
+    lines.push('');
+
+    for (const route of routes) {
+      lines.push('');
+      lines.push(`${PY_ROUTE_MARKER} ${route.method} ${route.path}`);
+      lines.push(this.generateView(route));
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  private generateView(route: RouteDescriptor): string {
+    const lines: string[] = [];
+    const funcName = toSnakeCase(route.handlerName);
+
+    // Method decorator for non-GET routes
+    if (route.method !== 'GET') {
+      lines.push(`@require_http_methods(["${route.method}"])`);
+    }
+
+    // Function signature with path params
+    const params = ['request', ...route.pathParams];
+    lines.push(`def ${funcName}(${params.join(', ')}):`);
+    lines.push(`    ${PY_USER_START}`);
+
+    // TODO block
+    lines.push(`    # TODO: Implement ${route.method} ${route.path}`);
+    if (route.pathParams.length > 0) {
+      lines.push(`    # Path params: ${route.pathParams.join(', ')}`);
+    }
+    if (route.requestBody && route.requestBody.length > 0) {
+      const fields = route.requestBody
+        .map(f => `${f.name}: ${pythonType(f.type)}${f.required ? '' : ' (optional)'}`)
+        .join(', ');
+      lines.push(`    # Expected body: { ${fields} }`);
+    }
+    for (const note of route.notes) {
+      lines.push(`    # Note: ${note}`);
+    }
+
+    // Extract query params
+    if (route.queryParams && route.queryParams.length > 0) {
+      for (const param of route.queryParams) {
+        lines.push(`    ${param.name} = request.GET.get('${param.name}')`);
+      }
+    }
+
+    // Parse body for POST/PUT/PATCH
+    if (
+      route.requestBody &&
+      route.requestBody.length > 0 &&
+      ['POST', 'PUT', 'PATCH'].includes(route.method)
+    ) {
+      lines.push(`    data = json.loads(request.body)`);
+      for (const field of route.requestBody) {
+        const default_ = field.required ? '' : ', None';
+        lines.push(`    ${field.name} = data.get('${field.name}'${default_})`);
+      }
+    }
+
+    // Response stub
+    if (route.responseFormat === 'json') {
+      lines.push(`    return JsonResponse({'message': 'Not implemented'})`);
+    } else if (route.responseFormat === 'html') {
+      lines.push(`    return HttpResponse('<div>Not implemented</div>')`);
+    } else {
+      lines.push(`    return HttpResponse('Not implemented', content_type='text/plain')`);
+    }
+
+    lines.push(`    ${PY_USER_END}`);
+    return lines.join('\n');
+  }
+
+  private generateUrls(routes: RouteDescriptor[], groupKey: string): string {
+    const lines: string[] = [];
+
+    lines.push(`# Generated by @hyperfixi/server-bridge — DO NOT EDIT`);
+    lines.push(`from django.urls import path`);
+    lines.push(`from . import views`);
+    lines.push('');
+    lines.push('urlpatterns = [');
+
+    for (const route of routes) {
+      const djangoPath = toDjangoPath(route.path);
+      const funcName = toSnakeCase(route.handlerName);
+      lines.push(`    path('${djangoPath}', views.${funcName}, name='${funcName}'),`);
+    }
+
+    lines.push(']');
+    lines.push('');
+
+    return lines.join('\n');
+  }
+
+  private generateRootUrls(groups: Map<string, RouteDescriptor[]>): string {
+    const lines: string[] = [];
+
+    lines.push(`# Generated by @hyperfixi/server-bridge — DO NOT EDIT`);
+    lines.push(`from django.urls import path, include`);
+    lines.push('');
+    lines.push('urlpatterns = [');
+
+    for (const groupKey of groups.keys()) {
+      lines.push(`    path('', include('${groupKey}.urls')),`);
+    }
+
+    lines.push(']');
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Convert camelCase handler name to snake_case for Python.
+ */
+function toSnakeCase(str: string): string {
+  return str
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/^_/, '');
+}
+
+/**
+ * Convert Express-style :param path to Django <param> path.
+ * "/api/users/:id" → "api/users/<int:id>"
+ */
+function toDjangoPath(path: string): string {
+  return path
+    .replace(/^\//, '') // Strip leading slash (Django convention)
+    .replace(/:(\w+)/g, '<str:$1>'); // :param → <str:param>
+}
+
+/**
+ * Map our field types to Python type hints.
+ */
+function pythonType(type: string): string {
+  switch (type) {
+    case 'number':
+      return 'int';
+    case 'boolean':
+      return 'bool';
+    case 'file':
+      return 'UploadedFile';
+    default:
+      return 'str';
+  }
+}

package/src/generators/express-generator.ts

@@ -0,0 +1,137 @@
+import type { RouteDescriptor, GeneratorOptions, GenerateResult, GeneratedFile } from '../types.js';
+import type { RouteGenerator } from './types.js';
+import {
+  routeMarker,
+  todoBlock,
+  USER_START,
+  USER_END,
+  groupRoutesByPrefix,
+  groupToFilename,
+} from './template-helpers.js';
+
+export class ExpressGenerator implements RouteGenerator {
+  readonly framework = 'express';
+
+  generate(routes: RouteDescriptor[], options: GeneratorOptions): GenerateResult {
+    const ts = options.typescript !== false; // default true
+    const files: GeneratedFile[] = [];
+    const warnings: string[] = [];
+
+    if (routes.length === 0) {
+      warnings.push('No routes to generate');
+      return { files, preserved: [], warnings };
+    }
+
+    const groups = groupRoutesByPrefix(routes);
+
+    // Generate one router file per group
+    for (const [groupKey, groupRoutes] of groups) {
+      const filename = groupToFilename(groupKey, ts);
+      const content = this.generateRouterFile(groupRoutes, groupKey, ts);
+      files.push({ path: `routes/${filename}`, content, isNew: true });
+    }
+
+    // Generate index file that imports all routers
+    const indexContent = this.generateIndex(groups, ts);
+    files.push({ path: `routes/index.${ts ? 'ts' : 'js'}`, content: indexContent, isNew: true });
+
+    return { files, preserved: [], warnings };
+  }
+
+  private generateRouterFile(routes: RouteDescriptor[], groupKey: string, ts: boolean): string {
+    const lines: string[] = [];
+
+    lines.push(`// Generated by @hyperfixi/server-bridge — DO NOT EDIT scaffold markers`);
+    lines.push(`import { Router${ts ? ', Request, Response' : ''} } from 'express';`);
+    lines.push('');
+    lines.push('const router = Router();');
+    lines.push('');
+
+    for (const route of routes) {
+      lines.push(routeMarker(route));
+      lines.push(this.generateHandler(route, ts));
+      lines.push('');
+    }
+
+    lines.push('export default router;');
+    lines.push('');
+
+    return lines.join('\n');
+  }
+
+  private generateHandler(route: RouteDescriptor, ts: boolean): string {
+    const method = route.method.toLowerCase();
+    const params = ts ? '(req: Request, res: Response)' : '(req, res)';
+    const lines: string[] = [];
+
+    lines.push(`router.${method}('${route.path}', async ${params} => {`);
+    lines.push(`  ${USER_START}`);
+    lines.push(todoBlock(route, '  '));
+
+    // Destructure path params
+    if (route.pathParams.length > 0) {
+      const paramList = route.pathParams.join(', ');
+      lines.push(`  const { ${paramList} } = req.params;`);
+    }
+
+    // Destructure query params
+    if (route.queryParams && route.queryParams.length > 0) {
+      const paramList = route.queryParams.map(p => p.name).join(', ');
+      lines.push(`  const { ${paramList} } = req.query;`);
+    }
+
+    // Destructure body fields for POST/PUT/PATCH
+    if (
+      route.requestBody &&
+      route.requestBody.length > 0 &&
+      ['POST', 'PUT', 'PATCH'].includes(route.method)
+    ) {
+      const fieldList = route.requestBody.map(f => f.name).join(', ');
+      lines.push(`  const { ${fieldList} } = req.body;`);
+    }
+
+    // Response stub
+    if (route.responseFormat === 'json') {
+      lines.push(`  res.json({ message: 'Not implemented' });`);
+    } else if (route.responseFormat === 'html') {
+      lines.push(`  res.send('<div>Not implemented</div>');`);
+    } else {
+      lines.push(`  res.send('Not implemented');`);
+    }
+
+    lines.push(`  ${USER_END}`);
+    lines.push(`});`);
+
+    return lines.join('\n');
+  }
+
+  private generateIndex(groups: Map<string, RouteDescriptor[]>, ts: boolean): string {
+    const lines: string[] = [];
+
+    lines.push(`// Generated by @hyperfixi/server-bridge — DO NOT EDIT`);
+    lines.push(`import { Router } from 'express';`);
+
+    for (const groupKey of groups.keys()) {
+      const filename = groupKey;
+      lines.push(`import ${toCamelCase(groupKey)}Router from './${filename}.js';`);
+    }
+
+    lines.push('');
+    lines.push('const router = Router();');
+    lines.push('');
+
+    for (const groupKey of groups.keys()) {
+      lines.push(`router.use(${toCamelCase(groupKey)}Router);`);
+    }
+
+    lines.push('');
+    lines.push('export default router;');
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}
+
+function toCamelCase(str: string): string {
+  return str.replace(/-(\w)/g, (_, c) => c.toUpperCase());
+}