@hyperfixi/server-bridge 2.0.0

package/src/cli/generate-command.ts

@@ -0,0 +1,108 @@
+import { resolve, join } from 'node:path';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { scanDirectory } from '../scanner/route-scanner.js';
+import { formatConflicts } from '../scanner/conflict-detector.js';
+import { selectGenerator } from '../generators/index.js';
+import {
+  loadManifest,
+  saveManifest,
+  createManifest,
+  diffRoutes,
+  extractUserCode,
+} from '../generators/manifest.js';
+import { loadConfig } from './config.js';
+interface GenerateOptions {
+  dir: string;
+  framework?: 'express' | 'hono' | 'openapi' | 'django' | 'fastapi';
+  output?: string;
+  typescript?: boolean;
+  overwrite?: boolean;
+  include?: string[];
+  exclude?: string[];
+  ignore?: string[];
+}
+
+export async function runGenerate(options: GenerateOptions): Promise<void> {
+  const cwd = resolve(options.dir);
+  const config = await loadConfig(cwd, {
+    framework: options.framework,
+    output: options.output,
+    typescript: options.typescript,
+    include: options.include,
+    exclude: options.exclude,
+    ignore: options.ignore,
+  });
+
+  // Scan for routes
+  const result = await scanDirectory(cwd, {
+    include: config.include,
+    exclude: config.exclude,
+    ignore: config.ignore,
+  });
+
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      console.error(`Warning: ${err.file}: ${err.message}`);
+    }
+  }
+
+  if (result.conflicts.length > 0) {
+    console.error(
+      `\nWarning: ${result.conflicts.length} route conflict(s) detected:\n${formatConflicts(result.conflicts)}\nFirst occurrence used for generation.\n`
+    );
+  }
+
+  if (result.routes.length === 0) {
+    console.log('No routes found. Nothing to generate.');
+    return;
+  }
+
+  // Select generator
+  const generator = selectGenerator(config.framework ?? 'express');
+
+  const outputDir = resolve(cwd, config.output ?? './server/routes');
+
+  // Load existing manifest for coexistence
+  const oldManifest = options.overwrite ? null : await loadManifest(outputDir);
+  const diff = diffRoutes(oldManifest, result.routes);
+
+  // Generate
+  const generated = generator.generate(result.routes, {
+    outputDir,
+    typescript: config.typescript,
+    overwrite: options.overwrite,
+  });
+
+  // Write files — create subdirectories as needed
+  await mkdir(outputDir, { recursive: true });
+
+  for (const file of generated.files) {
+    const filePath = join(outputDir, file.path);
+    const fileDir = join(filePath, '..');
+    await mkdir(fileDir, { recursive: true });
+    await writeFile(filePath, file.content, 'utf-8');
+  }
+
+  // Save manifest
+  const manifest = createManifest(result.routes);
+  await saveManifest(outputDir, manifest);
+
+  // Print summary
+  console.log(`Generated ${generated.files.length} file(s) in ${outputDir}/`);
+  console.log(`  Framework: ${generator.framework}`);
+  console.log(`  Routes: ${result.routes.length}`);
+
+  if (diff.added.length > 0) {
+    console.log(`  New: ${diff.added.length}`);
+  }
+  if (diff.changed.length > 0) {
+    console.log(`  Changed: ${diff.changed.length}`);
+  }
+  if (diff.removed.length > 0) {
+    console.log(`  Removed: ${diff.removed.length} (routes no longer in source)`);
+  }
+
+  for (const warning of generated.warnings) {
+    console.log(`  Warning: ${warning}`);
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+import { runScan } from './scan-command.js';
+import { runGenerate } from './generate-command.js';
+import { runDiff } from './diff-command.js';
+import { runWatch } from './watch-command.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function parseFlags(args: string[]): Record<string, string | boolean> {
+  const flags: Record<string, string | boolean> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const [key, ...valueParts] = arg.slice(2).split('=');
+      const value = valueParts.join('=');
+      if (value) {
+        flags[key] = value;
+      } else if (key.startsWith('no-')) {
+        flags[key.slice(3)] = false;
+      } else {
+        // Check if next arg is a value
+        const next = args[i + 1];
+        if (next && !next.startsWith('--')) {
+          flags[key] = next;
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      }
+    }
+  }
+  return flags;
+}
+
+function getPositionalArgs(args: string[]): string[] {
+  return args.filter(a => !a.startsWith('--'));
+}
+
+function parseFramework(flags: Record<string, string | boolean>) {
+  return (
+    ['hono', 'openapi', 'django', 'fastapi'].includes(flags.framework as string)
+      ? flags.framework
+      : 'express'
+  ) as 'express' | 'hono' | 'openapi' | 'django' | 'fastapi';
+}
+
+async function main(): Promise<void> {
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  const flagArgs = args.slice(1);
+  const flags = parseFlags(flagArgs);
+  const positional = getPositionalArgs(flagArgs);
+  const dir = positional[0] || '.';
+
+  if (command === 'scan') {
+    await runScan({
+      dir,
+      format: flags.format === 'table' ? 'table' : 'json',
+      include: typeof flags.include === 'string' ? flags.include.split(',') : undefined,
+      exclude: typeof flags.exclude === 'string' ? flags.exclude.split(',') : undefined,
+      ignore: typeof flags.ignore === 'string' ? flags.ignore.split(',') : undefined,
+    });
+  } else if (command === 'generate') {
+    await runGenerate({
+      dir,
+      framework: parseFramework(flags),
+      output: typeof flags.output === 'string' ? flags.output : undefined,
+      typescript: flags.typescript !== false,
+      overwrite: flags.overwrite === true,
+      include: typeof flags.include === 'string' ? flags.include.split(',') : undefined,
+      exclude: typeof flags.exclude === 'string' ? flags.exclude.split(',') : undefined,
+    });
+  } else if (command === 'diff') {
+    await runDiff({
+      dir,
+      format: flags.format === 'detailed' ? 'detailed' : 'summary',
+      include: typeof flags.include === 'string' ? flags.include.split(',') : undefined,
+      exclude: typeof flags.exclude === 'string' ? flags.exclude.split(',') : undefined,
+      ignore: typeof flags.ignore === 'string' ? flags.ignore.split(',') : undefined,
+    });
+  } else if (command === 'watch') {
+    await runWatch({
+      dir,
+      framework: parseFramework(flags),
+      output: typeof flags.output === 'string' ? flags.output : undefined,
+      typescript: flags.typescript !== false,
+      include: typeof flags.include === 'string' ? flags.include.split(',') : undefined,
+      exclude: typeof flags.exclude === 'string' ? flags.exclude.split(',') : undefined,
+      ignore: typeof flags.ignore === 'string' ? flags.ignore.split(',') : undefined,
+      debounce: typeof flags.debounce === 'string' ? parseInt(flags.debounce, 10) : undefined,
+    });
+  } else {
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "serverbridge --help" for usage.');
+    process.exit(1);
+  }
+}
+
+function printHelp(): void {
+  console.log(`
+serverbridge - Extract routes from hyperscript/htmx HTML and generate server stubs
+
+Usage:
+  serverbridge scan [dir] [options]      Scan files and print extracted routes
+  serverbridge generate [dir] [options]  Scan + generate server route stubs
+  serverbridge diff [dir] [options]      Show changes since last generation
+  serverbridge watch [dir] [options]     Watch files and auto-regenerate
+
+Scan options:
+  --format=json|table    Output format (default: json)
+  --include=PATTERNS     Comma-separated glob patterns (default: **/*.{html,htm})
+  --exclude=PATTERNS     Comma-separated exclusion patterns
+  --ignore=URLS          Comma-separated URL patterns to ignore
+
+Generate options:
+  --framework=express|hono|openapi|django|fastapi  Target framework (default: express)
+  --output=DIR              Output directory (default: ./server/routes)
+  --typescript              Generate TypeScript (default: true)
+  --no-typescript           Generate JavaScript
+  --overwrite               Overwrite existing user code
+
+Diff options:
+  --format=summary|detailed  Output format (default: summary)
+
+Watch options:
+  --framework=...         Same as generate
+  --output=DIR            Same as generate
+  --debounce=MS           Debounce delay in ms (default: 300)
+
+Config file:
+  Place .serverbridgerc.json in your project root to set defaults.
+`);
+}
+
+main().catch(err => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/src/cli/scan-command.ts

@@ -0,0 +1,72 @@
+import { resolve } from 'node:path';
+import { scanDirectory } from '../scanner/route-scanner.js';
+import { formatConflicts } from '../scanner/conflict-detector.js';
+import { loadConfig } from './config.js';
+
+interface ScanOptions {
+  dir: string;
+  format?: 'json' | 'table';
+  include?: string[];
+  exclude?: string[];
+  ignore?: string[];
+}
+
+export async function runScan(options: ScanOptions): Promise<void> {
+  const cwd = resolve(options.dir);
+  const config = await loadConfig(cwd, {
+    include: options.include,
+    exclude: options.exclude,
+    ignore: options.ignore,
+  });
+
+  const result = await scanDirectory(cwd, {
+    include: config.include,
+    exclude: config.exclude,
+    ignore: config.ignore,
+  });
+
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      console.error(`Error in ${err.file}: ${err.message}`);
+    }
+  }
+
+  if (result.conflicts.length > 0) {
+    console.error(
+      `\nWarning: ${result.conflicts.length} route conflict(s) detected:\n${formatConflicts(result.conflicts)}\n`
+    );
+  }
+
+  if (options.format === 'table') {
+    printTable(result.routes);
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+function printTable(
+  routes: {
+    path: string;
+    method: string;
+    responseFormat: string;
+    handlerName: string;
+    source: { file: string; kind: string };
+  }[]
+): void {
+  if (routes.length === 0) {
+    console.log('No routes found.');
+    return;
+  }
+
+  console.log(`Found ${routes.length} route(s):\n`);
+  console.log('  METHOD  PATH                          FORMAT  SOURCE');
+  console.log('  ------  ----------------------------  ------  ------');
+
+  for (const route of routes) {
+    const method = route.method.padEnd(6);
+    const path = route.path.padEnd(28);
+    const format = route.responseFormat.padEnd(6);
+    const source = route.source.kind;
+    console.log(`  ${method}  ${path}  ${format}  ${source}`);
+  }
+}

package/src/cli/watch-command.ts

@@ -0,0 +1,242 @@
+import { watch } from 'node:fs';
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { resolve, relative, join } from 'node:path';
+import { scanDirectory, scanRoutes, matchIgnorePattern } from '../scanner/route-scanner.js';
+import { detectConflicts, formatConflicts } from '../scanner/conflict-detector.js';
+import { selectGenerator } from '../generators/index.js';
+import { createManifest, saveManifest } from '../generators/manifest.js';
+import { loadConfig } from './config.js';
+import type { RouteDescriptor } from '../types.js';
+
+interface WatchOptions {
+  dir: string;
+  framework?: 'express' | 'hono' | 'openapi' | 'django' | 'fastapi';
+  output?: string;
+  typescript?: boolean;
+  include?: string[];
+  exclude?: string[];
+  ignore?: string[];
+  debounce?: number;
+}
+
+/** Convert a glob-like pattern to a regex for file matching. */
+function patternToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*\*\//g, '\0/')
+    .replace(/\*\*/g, '\0')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\0\//g, '(.+/)?')
+    .replace(/\0/g, '.*');
+  return new RegExp('^' + escaped + '$');
+}
+
+function shouldScan(filename: string, includePatterns: string[]): boolean {
+  return includePatterns.some(p => patternToRegex(p).test(filename));
+}
+
+function shouldSkip(relPath: string, excludePatterns: string[]): boolean {
+  return excludePatterns.some(p => patternToRegex(p).test(relPath));
+}
+
+/**
+ * Creates a debounced runner that:
+ * - Debounces rapid invocations with setTimeout/clearTimeout
+ * - Guards against overlapping async executions
+ * - Queues a follow-up run if triggered during execution
+ */
+export function createDebouncedRunner(fn: () => Promise<void>, ms: number) {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let running = false;
+  let queued = false;
+
+  function trigger(): void {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(run, ms);
+  }
+
+  async function run(): Promise<void> {
+    timer = null;
+    if (running) {
+      queued = true;
+      return;
+    }
+    running = true;
+    try {
+      await fn();
+    } finally {
+      running = false;
+      if (queued) {
+        queued = false;
+        trigger();
+      }
+    }
+  }
+
+  return { trigger };
+}
+
+/**
+ * Compute a hash of all route method:path pairs for change detection.
+ */
+export function computeRouteHash(routes: RouteDescriptor[]): string {
+  return routes
+    .map(r => `${r.method}:${r.path}`)
+    .sort()
+    .join('\n');
+}
+
+export async function runWatch(options: WatchOptions): Promise<void> {
+  const cwd = resolve(options.dir);
+  const config = await loadConfig(cwd, {
+    framework: options.framework,
+    output: options.output,
+    typescript: options.typescript,
+    include: options.include,
+    exclude: options.exclude,
+    ignore: options.ignore,
+  });
+
+  const includePatterns = config.include ?? ['**/*.html', '**/*.htm'];
+  const excludePatterns = config.exclude ?? ['node_modules/**', 'dist/**'];
+  const ignorePatterns = config.ignore ?? [];
+  const debounceMs = options.debounce ?? 300;
+  const outputDir = resolve(cwd, config.output ?? './server/routes');
+  const framework = config.framework ?? 'express';
+
+  console.log(`\nWatching for changes in ${cwd}/`);
+  console.log(`  Output: ${outputDir}/`);
+  console.log(`  Framework: ${framework}`);
+  console.log(`  Press Ctrl+C to stop.\n`);
+
+  // Per-file route cache
+  const routesByFile = new Map<string, RouteDescriptor[]>();
+  let currentRouteHash = '';
+
+  // Initial full scan
+  const initialScan = await scanDirectory(cwd, {
+    include: config.include,
+    exclude: config.exclude,
+    ignore: config.ignore,
+  });
+  for (const route of initialScan.routes) {
+    const file = route.source.file;
+    const existing = routesByFile.get(file) ?? [];
+    existing.push(route);
+    routesByFile.set(file, existing);
+  }
+
+  // Generate from initial scan
+  await generateFromCache();
+
+  const changedFiles = new Set<string>();
+  const debounced = createDebouncedRunner(async () => {
+    const files = [...changedFiles];
+    changedFiles.clear();
+    await incrementalUpdate(files);
+  }, debounceMs);
+
+  const watcher = watch(cwd, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
+
+    const relPath = relative(cwd, resolve(cwd, filename));
+
+    if (shouldSkip(relPath, excludePatterns)) return;
+    if (!shouldScan(filename, includePatterns)) return;
+
+    console.log(`  Changed: ${relPath}`);
+    changedFiles.add(resolve(cwd, filename));
+    debounced.trigger();
+  });
+
+  process.on('SIGINT', () => {
+    console.log('\nStopping watch mode...');
+    watcher.close();
+    process.exit(0);
+  });
+
+  // Keep alive
+  await new Promise(() => {});
+
+  async function incrementalUpdate(files: string[]): Promise<void> {
+    try {
+      for (const file of files) {
+        try {
+          const content = await readFile(file, 'utf-8');
+          const routes = scanRoutes(content, file);
+          routesByFile.set(file, routes);
+        } catch {
+          // File may have been deleted
+          routesByFile.delete(file);
+        }
+      }
+      await generateFromCache();
+    } catch (err) {
+      console.error('Generation failed:', err instanceof Error ? err.message : err);
+    }
+  }
+
+  async function generateFromCache(): Promise<void> {
+    // Merge all cached routes
+    let allRoutes: RouteDescriptor[] = [];
+    for (const routes of routesByFile.values()) {
+      allRoutes.push(...routes);
+    }
+
+    // Apply ignore patterns
+    if (ignorePatterns.length > 0) {
+      allRoutes = allRoutes.filter(
+        route => !ignorePatterns.some(p => matchIgnorePattern(route.path, p))
+      );
+    }
+
+    // Deduplicate by method:path (first wins)
+    const seen = new Map<string, RouteDescriptor>();
+    for (const route of allRoutes) {
+      const key = `${route.method}:${route.path}`;
+      if (!seen.has(key)) seen.set(key, route);
+    }
+    const routes = [...seen.values()];
+
+    // Hash check — skip generation if unchanged
+    const newHash = computeRouteHash(routes);
+    if (newHash === currentRouteHash) {
+      console.log('  No route changes detected, skipping generation.');
+      return;
+    }
+    currentRouteHash = newHash;
+
+    // Detect conflicts
+    const conflicts = detectConflicts(allRoutes);
+    if (conflicts.length > 0) {
+      console.error(
+        `\n  Warning: ${conflicts.length} route conflict(s):\n${formatConflicts(conflicts)}`
+      );
+    }
+
+    // Generate
+    const generator = selectGenerator(framework);
+    const generated = generator.generate(routes, {
+      outputDir,
+      typescript: config.typescript,
+    });
+
+    // Write files
+    await mkdir(outputDir, { recursive: true });
+    for (const file of generated.files) {
+      const filePath = join(outputDir, file.path);
+      const fileDir = join(filePath, '..');
+      await mkdir(fileDir, { recursive: true });
+      await writeFile(filePath, file.content, 'utf-8');
+    }
+
+    // Save manifest
+    const manifest = createManifest(routes);
+    await saveManifest(outputDir, manifest);
+
+    console.log(`  Generated ${generated.files.length} file(s) for ${routes.length} route(s)`);
+  }
+}
+
+// Exported for testing
+export { patternToRegex, shouldScan, shouldSkip };

package/src/conventions/convention-engine.ts

@@ -0,0 +1,68 @@
+import type { HttpMethod } from '../types.js';
+import { urlToHandlerName } from './url-patterns.js';
+
+export interface ConventionContext {
+  /** HTML element tag (e.g., 'form', 'button') */
+  elementTag?: string;
+  /** Explicit response type from hyperscript (e.g., 'json', 'html') */
+  fetchResponseType?: string;
+  /** Explicit method from source (e.g., from hx-post, fx-method) */
+  explicitMethod?: string;
+}
+
+export interface ConventionResult {
+  method: HttpMethod;
+  responseFormat: 'json' | 'text' | 'html';
+  handlerName: string;
+  notes: string[];
+}
+
+/**
+ * Infer HTTP method, response format, and handler name from URL and context.
+ *
+ * Priority:
+ * 1. Explicit method always wins (hx-post, fx-method, fetch via POST)
+ * 2. Form context implies POST
+ * 3. Default: GET
+ *
+ * Response format:
+ * 1. Explicit format from hyperscript (as json, as html)
+ * 2. URL ending in .html → html
+ * 3. Default: json
+ */
+export function inferConventions(url: string, context: ConventionContext = {}): ConventionResult {
+  const notes: string[] = [];
+
+  // --- Method ---
+  let method: HttpMethod;
+  if (context.explicitMethod) {
+    method = context.explicitMethod.toUpperCase() as HttpMethod;
+  } else if (context.elementTag === 'form') {
+    method = 'POST';
+    notes.push('Inferred POST from <form> context');
+  } else {
+    method = 'GET';
+  }
+
+  // --- Response Format ---
+  let responseFormat: 'json' | 'text' | 'html';
+  if (context.fetchResponseType) {
+    const fmt = context.fetchResponseType.toLowerCase();
+    if (fmt === 'json' || fmt === 'html' || fmt === 'text') {
+      responseFormat = fmt;
+    } else {
+      responseFormat = 'json';
+      notes.push(`Unknown response type "${context.fetchResponseType}", defaulting to json`);
+    }
+  } else if (url.endsWith('.html') || url.includes('/pages/') || url.includes('/partials/')) {
+    responseFormat = 'html';
+    notes.push('Inferred html response from URL pattern');
+  } else {
+    responseFormat = 'json';
+  }
+
+  // --- Handler Name ---
+  const handlerName = urlToHandlerName(url, method);
+
+  return { method, responseFormat, handlerName, notes };
+}