@hyperfixi/server-bridge 2.0.0

package/src/scanner/htmx-extractor.ts

@@ -0,0 +1,174 @@
+import type { RouteDescriptor, HttpMethod, RouteSource } from '../types.js';
+import {
+  extractPathParams,
+  extractQueryParams,
+  normalizeUrl,
+} from '../conventions/url-patterns.js';
+import { inferConventions } from '../conventions/convention-engine.js';
+
+/**
+ * Regex patterns forked from packages/vite-plugin/src/scanner.ts (lines 12-21)
+ * with URL capture groups added for route extraction.
+ */
+const HTMX_REQUEST_PATTERN =
+  /\b(hx-get|hx-post|hx-put|hx-patch|hx-delete)\s*=\s*["']([^"']+)["']/gi;
+
+const FIXI_ACTION_PATTERN = /\bfx-action\s*=\s*["']([^"']+)["']/gi;
+const FIXI_METHOD_PATTERN = /\bfx-method\s*=\s*["'](GET|POST|PUT|PATCH|DELETE)["']/gi;
+
+const HTMX_TARGET_PATTERN = /\b(?:hx-target|fx-target)\s*=\s*["']([^"']+)["']/gi;
+const HTMX_SWAP_PATTERN = /\b(?:hx-swap|fx-swap)\s*=\s*["']([^"']+)["']/gi;
+
+/** Map hx-{method} attribute names to HTTP methods */
+const HTMX_METHOD_MAP: Record<string, HttpMethod> = {
+  'hx-get': 'GET',
+  'hx-post': 'POST',
+  'hx-put': 'PUT',
+  'hx-patch': 'PATCH',
+  'hx-delete': 'DELETE',
+};
+
+interface ExtractionOptions {
+  file: string;
+}
+
+/**
+ * Extract route descriptors from htmx (hx-*) and fixi (fx-*) attributes.
+ */
+export function extractHtmxRoutes(content: string, options: ExtractionOptions): RouteDescriptor[] {
+  const routes: RouteDescriptor[] = [];
+  const seen = new Set<string>();
+
+  // --- htmx request attributes: hx-get, hx-post, etc. ---
+  HTMX_REQUEST_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = HTMX_REQUEST_PATTERN.exec(content)) !== null) {
+    const attrName = match[1].toLowerCase();
+    const rawUrl = match[2];
+    const method = HTMX_METHOD_MAP[attrName];
+    if (!method) continue;
+
+    addRoute(routes, seen, rawUrl, {
+      file: options.file,
+      line: lineNumberAt(content, match.index),
+      kind: 'hx-attr',
+      raw: `${match[1]}="${match[2]}"`,
+      explicitMethod: method,
+      // htmx default response is html (server-rendered partials)
+      fetchResponseType: 'html',
+    });
+  }
+
+  // --- fixi action attributes ---
+  // Collect fx-method if present (for context)
+  const fxMethods = collectFxMethods(content);
+
+  FIXI_ACTION_PATTERN.lastIndex = 0;
+  while ((match = FIXI_ACTION_PATTERN.exec(content)) !== null) {
+    const rawUrl = match[1];
+    const line = lineNumberAt(content, match.index);
+
+    // Try to find a fx-method near this fx-action (within ~200 chars)
+    const nearbyMethod = findNearbyFxMethod(content, match.index, fxMethods);
+
+    addRoute(routes, seen, rawUrl, {
+      file: options.file,
+      line,
+      kind: 'fx-attr',
+      raw: `fx-action="${match[1]}"`,
+      explicitMethod: nearbyMethod,
+    });
+  }
+
+  return routes;
+}
+
+function lineNumberAt(content: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) {
+    if (content[i] === '\n') line++;
+  }
+  return line;
+}
+
+interface FxMethodMatch {
+  method: string;
+  index: number;
+}
+
+function collectFxMethods(content: string): FxMethodMatch[] {
+  const methods: FxMethodMatch[] = [];
+  FIXI_METHOD_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = FIXI_METHOD_PATTERN.exec(content)) !== null) {
+    methods.push({ method: match[1], index: match.index });
+  }
+  return methods;
+}
+
+/**
+ * Find an fx-method attribute near an fx-action attribute.
+ * "Near" means within the same HTML element (~300 chars).
+ */
+function findNearbyFxMethod(
+  content: string,
+  actionIndex: number,
+  fxMethods: FxMethodMatch[]
+): string | undefined {
+  for (const fm of fxMethods) {
+    if (Math.abs(fm.index - actionIndex) < 300) {
+      return fm.method;
+    }
+  }
+  return undefined;
+}
+
+interface AddRouteOptions {
+  file: string;
+  line: number;
+  kind: RouteSource['kind'];
+  raw: string;
+  explicitMethod?: string;
+  fetchResponseType?: string;
+}
+
+function addRoute(
+  routes: RouteDescriptor[],
+  seen: Set<string>,
+  rawUrl: string,
+  options: AddRouteOptions
+): void {
+  // Skip external URLs
+  if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
+    return;
+  }
+
+  // Extract query params BEFORE normalization (which strips them)
+  const queryParams = extractQueryParams(rawUrl);
+  const path = normalizeUrl(rawUrl);
+
+  const conventions = inferConventions(path, {
+    explicitMethod: options.explicitMethod,
+    fetchResponseType: options.fetchResponseType,
+  });
+
+  const key = `${conventions.method}:${path}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+
+  routes.push({
+    path,
+    method: conventions.method,
+    responseFormat: conventions.responseFormat,
+    source: {
+      file: options.file,
+      line: options.line,
+      kind: options.kind,
+      raw: options.raw,
+    },
+    pathParams: extractPathParams(path),
+    ...(queryParams.length > 0 ? { queryParams } : {}),
+    handlerName: conventions.handlerName,
+    notes: conventions.notes,
+  });
+}

package/src/scanner/hyperscript-extractor.ts

@@ -0,0 +1,184 @@
+import type { RouteDescriptor, RouteSource } from '../types.js';
+import {
+  extractPathParams,
+  extractQueryParams,
+  normalizeUrl,
+} from '../conventions/url-patterns.js';
+import { inferConventions } from '../conventions/convention-engine.js';
+
+/**
+ * Regex patterns for finding hyperscript with fetch commands.
+ * Matches _="..." attributes in various quote styles.
+ */
+const ATTR_PATTERNS = [
+  /_\s*=\s*"([^"]+)"/g,
+  /_\s*=\s*'([^']+)'/g,
+  /_\s*=\s*`([^`]+)`/g,
+  /_=\{`([^`]+)`\}/g, // JSX template literal
+  /_=\{['"]([^'"]+)['"]\}/g, // JSX string
+];
+
+const SCRIPT_PATTERN = /<script[^>]*type=["']?text\/hyperscript["']?[^>]*>([\s\S]*?)<\/script>/gi;
+
+/**
+ * Regex for fetch commands within hyperscript code.
+ * Captures: url, optional response type (as json/html/text), optional method (via GET/POST)
+ */
+const FETCH_COMMAND = /\bfetch\s+['"]?([^\s'"]+)['"]?(?:\s+as\s+(\w+))?(?:\s+via\s+(\w+))?/gi;
+
+/**
+ * Regex for "send form to URL" pattern (implies POST).
+ */
+const SEND_FORM = /\bsend\s+(?:the\s+)?form\s+to\s+['"]?([^\s'"]+)['"]?(?:\s+as\s+(\w+))?/gi;
+
+interface ExtractionOptions {
+  file: string;
+}
+
+/**
+ * Extract route descriptors from hyperscript attributes in file content.
+ */
+export function extractHyperscriptRoutes(
+  content: string,
+  options: ExtractionOptions
+): RouteDescriptor[] {
+  const routes: RouteDescriptor[] = [];
+  const seen = new Set<string>();
+
+  // Collect all hyperscript code regions with their line numbers
+  const regions = extractHyperscriptRegions(content);
+
+  for (const region of regions) {
+    // Extract fetch commands
+    for (const match of region.code.matchAll(FETCH_COMMAND)) {
+      const rawUrl = match[1];
+      const responseType = match[2]; // json, html, text
+      const method = match[3]; // GET, POST, etc.
+
+      addRoute(routes, seen, rawUrl, {
+        file: options.file,
+        line: region.line,
+        kind: 'fetch',
+        raw: match[0],
+        explicitMethod: method,
+        fetchResponseType: responseType,
+      });
+    }
+
+    // Extract "send form to" commands
+    for (const match of region.code.matchAll(SEND_FORM)) {
+      const rawUrl = match[1];
+      const responseType = match[2];
+
+      addRoute(routes, seen, rawUrl, {
+        file: options.file,
+        line: region.line,
+        kind: 'fetch',
+        raw: match[0],
+        explicitMethod: 'POST',
+        fetchResponseType: responseType,
+      });
+    }
+  }
+
+  return routes;
+}
+
+interface RegionInfo {
+  code: string;
+  line: number;
+}
+
+function extractHyperscriptRegions(content: string): RegionInfo[] {
+  const regions: RegionInfo[] = [];
+  const lines = content.split('\n');
+
+  // Search for _="..." attributes
+  for (const pattern of ATTR_PATTERNS) {
+    // Reset the regex
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const line = lineNumberAt(content, match.index);
+      regions.push({ code: match[1], line });
+    }
+  }
+
+  // Search for <script type="text/hyperscript"> blocks
+  SCRIPT_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = SCRIPT_PATTERN.exec(content)) !== null) {
+    const line = lineNumberAt(content, match.index);
+    regions.push({ code: match[1], line });
+  }
+
+  return regions;
+}
+
+function lineNumberAt(content: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) {
+    if (content[i] === '\n') line++;
+  }
+  return line;
+}
+
+interface AddRouteOptions {
+  file: string;
+  line: number;
+  kind: RouteSource['kind'];
+  raw: string;
+  explicitMethod?: string;
+  fetchResponseType?: string;
+}
+
+function addRoute(
+  routes: RouteDescriptor[],
+  seen: Set<string>,
+  rawUrl: string,
+  options: AddRouteOptions
+): void {
+  // Skip external URLs
+  if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
+    return;
+  }
+
+  // Skip template-only URLs (e.g., {{baseUrl}})
+  if (rawUrl.startsWith('{{') || rawUrl.startsWith('${')) {
+    return;
+  }
+
+  // Skip non-URL strings (e.g., CSS selectors, keywords, bare words ending in colon)
+  if (!rawUrl.startsWith('/') && !rawUrl.includes('/')) {
+    return;
+  }
+
+  // Extract query params BEFORE normalization (which strips them)
+  const queryParams = extractQueryParams(rawUrl);
+  const path = normalizeUrl(rawUrl);
+
+  const conventions = inferConventions(path, {
+    explicitMethod: options.explicitMethod,
+    fetchResponseType: options.fetchResponseType,
+  });
+
+  const key = `${conventions.method}:${path}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+
+  routes.push({
+    path,
+    method: conventions.method,
+    responseFormat: conventions.responseFormat,
+    source: {
+      file: options.file,
+      line: options.line,
+      kind: options.kind,
+      raw: options.raw,
+    },
+    pathParams: extractPathParams(path),
+    ...(queryParams.length > 0 ? { queryParams } : {}),
+    handlerName: conventions.handlerName,
+    notes: conventions.notes,
+  });
+}

package/src/scanner/route-scanner.ts

@@ -0,0 +1,130 @@
+import { readFile } from 'node:fs/promises';
+import { glob } from 'glob';
+import type { RouteDescriptor, ScanResult, ScanError } from '../types.js';
+import { extractHyperscriptRoutes } from './hyperscript-extractor.js';
+import { extractHtmxRoutes } from './htmx-extractor.js';
+import { extractFormBodies } from './form-scanner.js';
+import { detectConflicts } from './conflict-detector.js';
+import { normalizeUrl } from '../conventions/url-patterns.js';
+
+/**
+ * Default file patterns to scan.
+ */
+const DEFAULT_INCLUDE = ['**/*.html', '**/*.htm'];
+const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/.git/**'];
+
+interface ScanOptions {
+  include?: string[];
+  exclude?: string[];
+  /** URL patterns to ignore */
+  ignore?: string[];
+}
+
+/**
+ * Scan a single file's content for routes.
+ */
+export function scanRoutes(content: string, file: string): RouteDescriptor[] {
+  const hsRoutes = extractHyperscriptRoutes(content, { file });
+  const htmxRoutes = extractHtmxRoutes(content, { file });
+
+  // Merge and deduplicate
+  const all = [...hsRoutes, ...htmxRoutes];
+  const deduped = deduplicateRoutes(all);
+
+  // Enrich with form body data
+  const formBodies = extractFormBodies(content);
+  for (const route of deduped) {
+    if (['POST', 'PUT', 'PATCH'].includes(route.method)) {
+      const rawUrl = route.path;
+      const fields = formBodies.get(rawUrl);
+      if (fields && fields.length > 0) {
+        route.requestBody = fields;
+      }
+    }
+  }
+
+  return deduped;
+}
+
+/**
+ * Scan a directory for all HTML/template files and extract routes.
+ */
+export async function scanDirectory(dir: string, options: ScanOptions = {}): Promise<ScanResult> {
+  const include = options.include ?? DEFAULT_INCLUDE;
+  const exclude = options.exclude ?? DEFAULT_EXCLUDE;
+
+  const files: string[] = [];
+  for (const pattern of include) {
+    const matches = await glob(pattern, {
+      cwd: dir,
+      absolute: true,
+      ignore: exclude,
+    });
+    files.push(...matches);
+  }
+
+  // Deduplicate file paths
+  const uniqueFiles = [...new Set(files)];
+
+  const allRoutes: RouteDescriptor[] = [];
+  const errors: ScanError[] = [];
+
+  for (const file of uniqueFiles) {
+    try {
+      const content = await readFile(file, 'utf-8');
+      const routes = scanRoutes(content, file);
+      allRoutes.push(...routes);
+    } catch (err) {
+      errors.push({
+        file,
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  // Detect conflicts BEFORE deduplication (needs all occurrences)
+  const conflicts = detectConflicts(allRoutes);
+
+  // Final deduplication across files
+  const deduped = deduplicateRoutes(allRoutes);
+
+  // Apply ignore patterns
+  const ignored = options.ignore ?? [];
+  const filtered = deduped.filter(
+    route => !ignored.some(pattern => matchIgnorePattern(route.path, pattern))
+  );
+
+  return {
+    routes: filtered,
+    filesScanned: uniqueFiles,
+    errors,
+    conflicts,
+  };
+}
+
+/**
+ * Deduplicate routes by method + path.
+ * First occurrence wins (preserves source from first detection).
+ */
+function deduplicateRoutes(routes: RouteDescriptor[]): RouteDescriptor[] {
+  const seen = new Map<string, RouteDescriptor>();
+  for (const route of routes) {
+    const key = `${route.method}:${route.path}`;
+    if (!seen.has(key)) {
+      seen.set(key, route);
+    }
+  }
+  return [...seen.values()];
+}
+
+/**
+ * Check if a URL path matches an ignore pattern.
+ * Supports simple wildcards: /external/** matches /external/anything
+ */
+export function matchIgnorePattern(path: string, pattern: string): boolean {
+  if (pattern.endsWith('/**')) {
+    const prefix = pattern.slice(0, -3);
+    return path.startsWith(prefix);
+  }
+  return path === pattern;
+}

package/src/types.ts

@@ -0,0 +1,151 @@
+// =============================================================================
+// Core Data Model
+// =============================================================================
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * A server route extracted from hyperscript/htmx/fixi attributes.
+ */
+export interface RouteDescriptor {
+  /** URL path pattern, e.g., "/api/users/:id" */
+  path: string;
+  /** HTTP method */
+  method: HttpMethod;
+  /** Inferred response format */
+  responseFormat: 'json' | 'text' | 'html';
+  /** Where this route was discovered */
+  source: RouteSource;
+  /** Inferred request body shape (for POST/PUT/PATCH) */
+  requestBody?: RequestBodyField[];
+  /** Path parameters extracted from URL */
+  pathParams: string[];
+  /** Query parameters extracted from URL (e.g., ?q=hello&limit=10) */
+  queryParams?: QueryParam[];
+  /** Suggested handler function name */
+  handlerName: string;
+  /** Convention-engine notes */
+  notes: string[];
+}
+
+export interface RouteSource {
+  /** Absolute file path */
+  file: string;
+  /** Line number (1-indexed) */
+  line?: number;
+  /** How the route was detected */
+  kind: 'fetch' | 'hx-attr' | 'fx-attr';
+  /** Original source text */
+  raw: string;
+}
+
+export interface RequestBodyField {
+  /** Field name from form input name="" attribute */
+  name: string;
+  /** Inferred type from input type="" attribute */
+  type: 'string' | 'number' | 'boolean' | 'file' | 'unknown';
+  /** Whether the field has the required attribute */
+  required: boolean;
+}
+
+export interface QueryParam {
+  /** Parameter name from URL query string */
+  name: string;
+  /** HTTP query params are always strings */
+  type: 'string';
+  /** Whether the param appears required (true when explicitly present in URL) */
+  required: boolean;
+}
+
+// =============================================================================
+// Scan Results
+// =============================================================================
+
+export interface ScanResult {
+  /** All extracted routes */
+  routes: RouteDescriptor[];
+  /** Files that were scanned */
+  filesScanned: string[];
+  /** Errors during scanning */
+  errors: ScanError[];
+  /** Route conflicts detected (same method+path, different expectations) */
+  conflicts: ConflictWarning[];
+}
+
+export interface ConflictWarning {
+  routeKey: string;
+  conflicts: ConflictDetail[];
+  sources: RouteSource[];
+}
+
+export interface ConflictDetail {
+  field: 'responseFormat' | 'requestBody' | 'queryParams';
+  values: string[];
+  message: string;
+}
+
+export interface ScanError {
+  file: string;
+  line?: number;
+  message: string;
+}
+
+// =============================================================================
+// Generator Types
+// =============================================================================
+
+export interface GeneratorOptions {
+  /** Output directory for generated files */
+  outputDir: string;
+  /** Whether to use TypeScript (default: true) */
+  typescript?: boolean;
+  /** Overwrite existing user code (default: false) */
+  overwrite?: boolean;
+  /** Base path prefix to strip from routes */
+  basePath?: string;
+}
+
+export interface GeneratedFile {
+  /** Relative path within outputDir */
+  path: string;
+  /** File content */
+  content: string;
+  /** Whether this is a new file or regenerated */
+  isNew: boolean;
+}
+
+export interface GenerateResult {
+  /** Generated files */
+  files: GeneratedFile[];
+  /** Routes with preserved user code */
+  preserved: string[];
+  /** Warnings */
+  warnings: string[];
+}
+
+// =============================================================================
+// Config
+// =============================================================================
+
+export interface ServerBridgeConfig {
+  /** Target framework */
+  framework?: 'express' | 'hono' | 'openapi' | 'django' | 'fastapi';
+  /** Output directory */
+  output?: string;
+  /** TypeScript output */
+  typescript?: boolean;
+  /** File include patterns */
+  include?: string[];
+  /** File exclude patterns */
+  exclude?: string[];
+  /** Base path prefix to strip */
+  basePath?: string;
+  /** Convention overrides */
+  conventions?: {
+    defaultResponseFormat?: 'json' | 'html' | 'text';
+    fetchMethod?: HttpMethod;
+    formMethod?: HttpMethod;
+  };
+  /** URL patterns to ignore */
+  ignore?: string[];
+}