@hyperfixi/server-bridge 2.0.0

package/src/generators/fastapi-generator.ts

@@ -0,0 +1,248 @@
+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 FastAPIGenerator implements RouteGenerator {
+  readonly framework = 'fastapi';
+
+  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);
+
+    for (const [groupKey, groupRoutes] of groups) {
+      const content = this.generateRouterFile(groupRoutes, groupKey);
+      const pyFilename = groupKey.replace(/-/g, '_');
+      files.push({ path: `routers/${pyFilename}.py`, content, isNew: true });
+    }
+
+    // Main app file that includes all routers
+    const mainContent = this.generateMain(groups);
+    files.push({ path: 'main.py', content: mainContent, isNew: true });
+
+    // Pydantic models file if any routes have request bodies
+    const allRoutes = [...groups.values()].flat();
+    const routesWithBodies = allRoutes.filter(
+      r => r.requestBody && r.requestBody.length > 0 && ['POST', 'PUT', 'PATCH'].includes(r.method)
+    );
+    if (routesWithBodies.length > 0) {
+      const models = this.generateModels(routesWithBodies);
+      files.push({ path: 'models.py', content: models, isNew: true });
+    }
+
+    return { files, preserved: [], warnings };
+  }
+
+  private generateRouterFile(routes: RouteDescriptor[], groupKey: string): string {
+    const lines: string[] = [];
+
+    lines.push(`# Generated by @hyperfixi/server-bridge — DO NOT EDIT scaffold markers`);
+
+    // Check if we need Query import
+    const needsQuery = routes.some(r => r.queryParams && r.queryParams.length > 0);
+    if (needsQuery) {
+      lines.push(`from fastapi import APIRouter, Query`);
+    } else {
+      lines.push(`from fastapi import APIRouter`);
+    }
+
+    // Check if we need models import
+    const routesWithBodies = routes.filter(
+      r => r.requestBody && r.requestBody.length > 0 && ['POST', 'PUT', 'PATCH'].includes(r.method)
+    );
+    if (routesWithBodies.length > 0) {
+      const modelNames = routesWithBodies.map(r => modelName(r.handlerName));
+      lines.push(`from ..models import ${modelNames.join(', ')}`);
+    }
+
+    // Check response types needed
+    const needsHtml = routes.some(r => r.responseFormat === 'html');
+    const needsPlaintext = routes.some(r => r.responseFormat === 'text');
+    if (needsHtml || needsPlaintext) {
+      lines.push(`from fastapi.responses import HTMLResponse, PlainTextResponse`);
+    }
+
+    lines.push('');
+    lines.push(`router = APIRouter()`);
+    lines.push('');
+
+    for (const route of routes) {
+      lines.push('');
+      lines.push(`${PY_ROUTE_MARKER} ${route.method} ${route.path}`);
+      lines.push(this.generateEndpoint(route));
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  private generateEndpoint(route: RouteDescriptor): string {
+    const lines: string[] = [];
+    const method = route.method.toLowerCase();
+    const funcName = toSnakeCase(route.handlerName);
+    const fastapiPath = toFastAPIPath(route.path);
+
+    // Response class for non-JSON
+    const extraArgs: string[] = [];
+    if (route.responseFormat === 'html') {
+      extraArgs.push('response_class=HTMLResponse');
+    } else if (route.responseFormat === 'text') {
+      extraArgs.push('response_class=PlainTextResponse');
+    }
+
+    const argsStr = extraArgs.length > 0 ? `, ${extraArgs.join(', ')}` : '';
+    lines.push(`@router.${method}('${fastapiPath}'${argsStr})`);
+
+    // Function signature with typed params
+    const params: string[] = [];
+    for (const param of route.pathParams) {
+      params.push(`${param}: str`);
+    }
+    if (route.queryParams && route.queryParams.length > 0) {
+      for (const qp of route.queryParams) {
+        params.push(`${qp.name}: str = Query(...)`);
+      }
+    }
+    if (
+      route.requestBody &&
+      route.requestBody.length > 0 &&
+      ['POST', 'PUT', 'PATCH'].includes(route.method)
+    ) {
+      params.push(`body: ${modelName(route.handlerName)}`);
+    }
+
+    lines.push(`async 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}`);
+    }
+
+    // Response stub
+    if (route.responseFormat === 'json') {
+      lines.push(`    return {'message': 'Not implemented'}`);
+    } else if (route.responseFormat === 'html') {
+      lines.push(`    return '<div>Not implemented</div>'`);
+    } else {
+      lines.push(`    return 'Not implemented'`);
+    }
+
+    lines.push(`    ${PY_USER_END}`);
+    return lines.join('\n');
+  }
+
+  private generateMain(groups: Map<string, RouteDescriptor[]>): string {
+    const lines: string[] = [];
+
+    lines.push(`# Generated by @hyperfixi/server-bridge — DO NOT EDIT`);
+    lines.push(`from fastapi import FastAPI`);
+
+    for (const groupKey of groups.keys()) {
+      const pyName = groupKey.replace(/-/g, '_');
+      lines.push(`from .routers.${pyName} import router as ${pyName}_router`);
+    }
+
+    lines.push('');
+    lines.push('app = FastAPI()');
+    lines.push('');
+
+    for (const groupKey of groups.keys()) {
+      const pyName = groupKey.replace(/-/g, '_');
+      lines.push(`app.include_router(${pyName}_router)`);
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  private generateModels(routes: RouteDescriptor[]): string {
+    const lines: string[] = [];
+
+    lines.push(`# Generated by @hyperfixi/server-bridge — DO NOT EDIT`);
+    lines.push(`from pydantic import BaseModel`);
+    lines.push(`from typing import Optional`);
+    lines.push('');
+
+    for (const route of routes) {
+      if (!route.requestBody || route.requestBody.length === 0) continue;
+
+      lines.push('');
+      lines.push(`class ${modelName(route.handlerName)}(BaseModel):`);
+
+      for (const field of route.requestBody) {
+        const pyType = pythonType(field.type);
+        if (field.required) {
+          lines.push(`    ${field.name}: ${pyType}`);
+        } else {
+          lines.push(`    ${field.name}: Optional[${pyType}] = None`);
+        }
+      }
+    }
+
+    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 FastAPI {param} path.
+ * "/api/users/:id" → "/api/users/{id}"
+ */
+function toFastAPIPath(path: string): string {
+  return path.replace(/:(\w+)/g, '{$1}');
+}
+
+/**
+ * Generate a Pydantic model name from handler name.
+ * "postApiUsers" → "PostApiUsersBody"
+ */
+function modelName(handlerName: string): string {
+  return handlerName.charAt(0).toUpperCase() + handlerName.slice(1) + 'Body';
+}
+
+/**
+ * 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 'bytes';
+    default:
+      return 'str';
+  }
+}

package/src/generators/hono-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 HonoGenerator implements RouteGenerator {
+  readonly framework = 'hono';
+
+  generate(routes: RouteDescriptor[], options: GeneratorOptions): GenerateResult {
+    const ts = options.typescript !== false;
+    const files: GeneratedFile[] = [];
+    const warnings: string[] = [];
+
+    if (routes.length === 0) {
+      warnings.push('No routes to generate');
+      return { files, preserved: [], warnings };
+    }
+
+    const groups = groupRoutesByPrefix(routes);
+
+    for (const [groupKey, groupRoutes] of groups) {
+      const filename = groupToFilename(groupKey, ts);
+      const content = this.generateRouteFile(groupRoutes, groupKey, ts);
+      files.push({ path: `routes/${filename}`, content, isNew: true });
+    }
+
+    const indexContent = this.generateIndex(groups, ts);
+    files.push({ path: `routes/index.${ts ? 'ts' : 'js'}`, content: indexContent, isNew: true });
+
+    return { files, preserved: [], warnings };
+  }
+
+  private generateRouteFile(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 { Hono } from 'hono';`);
+    lines.push('');
+    lines.push('const app = new Hono();');
+    lines.push('');
+
+    for (const route of routes) {
+      lines.push(routeMarker(route));
+      lines.push(this.generateHandler(route, ts));
+      lines.push('');
+    }
+
+    lines.push('export default app;');
+    lines.push('');
+
+    return lines.join('\n');
+  }
+
+  private generateHandler(route: RouteDescriptor, ts: boolean): string {
+    const method = route.method.toLowerCase();
+    const lines: string[] = [];
+
+    lines.push(`app.${method}('${route.path}', async (c) => {`);
+    lines.push(`  ${USER_START}`);
+    lines.push(todoBlock(route, '  '));
+
+    // Destructure path params
+    if (route.pathParams.length > 0) {
+      for (const param of route.pathParams) {
+        lines.push(`  const ${param} = c.req.param('${param}');`);
+      }
+    }
+
+    // Extract query params
+    if (route.queryParams && route.queryParams.length > 0) {
+      for (const param of route.queryParams) {
+        lines.push(`  const ${param.name} = c.req.query('${param.name}');`);
+      }
+    }
+
+    // Parse body for POST/PUT/PATCH
+    if (
+      route.requestBody &&
+      route.requestBody.length > 0 &&
+      ['POST', 'PUT', 'PATCH'].includes(route.method)
+    ) {
+      lines.push(`  const body = await c.req.json();`);
+      const fieldList = route.requestBody.map(f => f.name).join(', ');
+      lines.push(`  const { ${fieldList} } = body;`);
+    }
+
+    // Response stub
+    if (route.responseFormat === 'json') {
+      lines.push(`  return c.json({ message: 'Not implemented' });`);
+    } else if (route.responseFormat === 'html') {
+      lines.push(`  return c.html('<div>Not implemented</div>');`);
+    } else {
+      lines.push(`  return c.text('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 { Hono } from 'hono';`);
+
+    for (const groupKey of groups.keys()) {
+      const filename = groupKey;
+      lines.push(`import ${toCamelCase(groupKey)}Routes from './${filename}.js';`);
+    }
+
+    lines.push('');
+    lines.push('const app = new Hono();');
+    lines.push('');
+
+    for (const groupKey of groups.keys()) {
+      lines.push(`app.route('/', ${toCamelCase(groupKey)}Routes);`);
+    }
+
+    lines.push('');
+    lines.push('export default app;');
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}
+
+function toCamelCase(str: string): string {
+  return str.replace(/-(\w)/g, (_, c) => c.toUpperCase());
+}

package/src/generators/index.ts

@@ -0,0 +1,25 @@
+import { ExpressGenerator } from './express-generator.js';
+import { HonoGenerator } from './hono-generator.js';
+import { OpenAPIGenerator } from './openapi-generator.js';
+import { DjangoGenerator } from './django-generator.js';
+import { FastAPIGenerator } from './fastapi-generator.js';
+import type { RouteGenerator } from './types.js';
+
+/**
+ * Select the appropriate RouteGenerator for a framework name.
+ * Falls back to ExpressGenerator for unrecognized values.
+ */
+export function selectGenerator(framework: string): RouteGenerator {
+  switch (framework) {
+    case 'hono':
+      return new HonoGenerator();
+    case 'openapi':
+      return new OpenAPIGenerator();
+    case 'django':
+      return new DjangoGenerator();
+    case 'fastapi':
+      return new FastAPIGenerator();
+    default:
+      return new ExpressGenerator();
+  }
+}

package/src/generators/manifest.ts

@@ -0,0 +1,164 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import type { RouteDescriptor } from '../types.js';
+import { USER_START, USER_END } from './template-helpers.js';
+
+const MANIFEST_FILENAME = 'server-bridge.manifest.json';
+
+export interface ManifestEntry {
+  method: string;
+  path: string;
+  handlerName: string;
+  hash: string;
+}
+
+export interface Manifest {
+  version: number;
+  generatedAt: string;
+  routes: Record<string, ManifestEntry>;
+}
+
+/**
+ * Create a hash for a RouteDescriptor to detect changes.
+ */
+export function hashRoute(route: RouteDescriptor): string {
+  const data = JSON.stringify({
+    path: route.path,
+    method: route.method,
+    responseFormat: route.responseFormat,
+    pathParams: route.pathParams,
+    queryParams: route.queryParams,
+    requestBody: route.requestBody,
+  });
+  return createHash('md5').update(data).digest('hex').slice(0, 8);
+}
+
+/**
+ * Build a manifest key from method + path.
+ */
+function manifestKey(method: string, path: string): string {
+  return `${method}:${path}`;
+}
+
+/**
+ * Create a new manifest from a set of routes.
+ */
+export function createManifest(routes: RouteDescriptor[]): Manifest {
+  const manifest: Manifest = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    routes: {},
+  };
+
+  for (const route of routes) {
+    const key = manifestKey(route.method, route.path);
+    manifest.routes[key] = {
+      method: route.method,
+      path: route.path,
+      handlerName: route.handlerName,
+      hash: hashRoute(route),
+    };
+  }
+
+  return manifest;
+}
+
+/**
+ * Load an existing manifest from the output directory.
+ * Returns null if no manifest exists.
+ */
+export async function loadManifest(outputDir: string): Promise<Manifest | null> {
+  try {
+    const content = await readFile(join(outputDir, MANIFEST_FILENAME), 'utf-8');
+    return JSON.parse(content) as Manifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save a manifest to the output directory.
+ */
+export async function saveManifest(outputDir: string, manifest: Manifest): Promise<void> {
+  await writeFile(
+    join(outputDir, MANIFEST_FILENAME),
+    JSON.stringify(manifest, null, 2) + '\n',
+    'utf-8'
+  );
+}
+
+/**
+ * Extract user-written code between @serverbridge-user-start and @serverbridge-user-end markers.
+ * Returns a map from route key (METHOD:path) to user code string.
+ */
+export function extractUserCode(fileContent: string): Map<string, string> {
+  const result = new Map<string, string>();
+
+  // Find each route marker followed by a user code block
+  const routeMarkerPattern = /\/\/ @serverbridge-route:\s+(\w+)\s+(\/\S+)/g;
+  let match;
+  while ((match = routeMarkerPattern.exec(fileContent)) !== null) {
+    const method = match[1];
+    const path = match[2];
+    const key = manifestKey(method, path);
+
+    // Find the user-start/user-end block after this marker
+    const afterMarker = fileContent.slice(match.index);
+    const startIdx = afterMarker.indexOf(USER_START);
+    const endIdx = afterMarker.indexOf(USER_END);
+
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+      const userCode = afterMarker.slice(
+        startIdx + USER_START.length + 1, // +1 for newline
+        endIdx
+      );
+      // Only save if it differs from the default TODO
+      if (!userCode.includes('// TODO: Implement')) {
+        result.set(key, userCode);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Determine what changed between old and new route sets.
+ */
+export function diffRoutes(
+  oldManifest: Manifest | null,
+  newRoutes: RouteDescriptor[]
+): {
+  added: RouteDescriptor[];
+  removed: ManifestEntry[];
+  changed: RouteDescriptor[];
+  unchanged: RouteDescriptor[];
+} {
+  const oldRoutes = oldManifest?.routes ?? {};
+
+  const added: RouteDescriptor[] = [];
+  const changed: RouteDescriptor[] = [];
+  const unchanged: RouteDescriptor[] = [];
+
+  for (const route of newRoutes) {
+    const key = manifestKey(route.method, route.path);
+    const existing = oldRoutes[key];
+
+    if (!existing) {
+      added.push(route);
+    } else if (existing.hash !== hashRoute(route)) {
+      changed.push(route);
+    } else {
+      unchanged.push(route);
+    }
+  }
+
+  // Find removed routes
+  const newKeys = new Set(newRoutes.map(r => manifestKey(r.method, r.path)));
+  const removed = Object.values(oldRoutes).filter(
+    entry => !newKeys.has(manifestKey(entry.method, entry.path))
+  );
+
+  return { added, removed, changed, unchanged };
+}