@hyperfixi/server-bridge 2.0.0

package/src/__tests__/openapi-generator.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { OpenAPIGenerator } from '../generators/openapi-generator.js';
+import type { RouteDescriptor } from '../types.js';
+
+function makeRoute(overrides: Partial<RouteDescriptor> = {}): RouteDescriptor {
+  return {
+    path: '/api/users',
+    method: 'GET',
+    responseFormat: 'json',
+    source: { file: 'test.html', line: 5, kind: 'fetch', raw: 'fetch /api/users' },
+    pathParams: [],
+    handlerName: 'getApiUsers',
+    notes: [],
+    ...overrides,
+  };
+}
+
+describe('OpenAPIGenerator', () => {
+  const gen = new OpenAPIGenerator();
+
+  it('has correct framework name', () => {
+    expect(gen.framework).toBe('openapi');
+  });
+
+  it('generates a valid OpenAPI 3.1 spec', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    expect(result.files).toHaveLength(1);
+    expect(result.files[0].path).toBe('openapi.yaml');
+
+    const yaml = result.files[0].content;
+    expect(yaml).toContain("openapi: '3.1.0'");
+    expect(yaml).toContain('title: ServerBridge Generated API');
+    expect(yaml).toContain('/api/users:');
+    expect(yaml).toContain('get:');
+    expect(yaml).toContain('operationId: getApiUsers');
+  });
+
+  it('converts :param to {param} in paths', () => {
+    const route = makeRoute({
+      path: '/api/users/:id',
+      pathParams: ['id'],
+      handlerName: 'getApiUsersById',
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const yaml = result.files[0].content;
+    expect(yaml).toContain('/api/users/{id}:');
+    expect(yaml).toContain('name: id');
+    expect(yaml).toContain('in: path');
+    expect(yaml).toContain('required: true');
+  });
+
+  it('groups multiple methods under same path', () => {
+    const routes = [
+      makeRoute({ path: '/api/users', method: 'GET', handlerName: 'getApiUsers' }),
+      makeRoute({ path: '/api/users', method: 'POST', handlerName: 'postApiUsers' }),
+    ];
+    const result = gen.generate(routes, { outputDir: '/out' });
+    const yaml = result.files[0].content;
+
+    // Should have one /api/users path with both get: and post:
+    const pathCount = (yaml.match(/\/api\/users:/g) || []).length;
+    expect(pathCount).toBe(1);
+    expect(yaml).toContain('get:');
+    expect(yaml).toContain('post:');
+  });
+
+  it('includes request body for POST routes with fields', () => {
+    const route = makeRoute({
+      method: 'POST',
+      handlerName: 'postApiUsers',
+      requestBody: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'email', type: 'string', required: true },
+        { name: 'age', type: 'number', required: false },
+      ],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const yaml = result.files[0].content;
+    expect(yaml).toContain('requestBody:');
+    expect(yaml).toContain("required: ['name', 'email']");
+    expect(yaml).toContain('name:');
+    expect(yaml).toContain('email:');
+    expect(yaml).toContain('age:');
+  });
+
+  it('uses text/html content type for html format', () => {
+    const route = makeRoute({ responseFormat: 'html' });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const yaml = result.files[0].content;
+    expect(yaml).toContain('text/html:');
+  });
+
+  it('includes source file in summary', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const yaml = result.files[0].content;
+    expect(yaml).toContain("summary: 'Source: test.html:5 (fetch)'");
+  });
+
+  it('generates query parameter specs', () => {
+    const route = makeRoute({
+      path: '/api/search',
+      handlerName: 'getApiSearch',
+      queryParams: [{ name: 'q', type: 'string', required: true }],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const yaml = result.files[0].content;
+    expect(yaml).toContain('name: q');
+    expect(yaml).toContain('in: query');
+  });
+
+  it('warns when no routes provided', () => {
+    const result = gen.generate([], { outputDir: '/out' });
+    expect(result.warnings).toContain('No routes to generate');
+    expect(result.files).toHaveLength(0);
+  });
+});

package/src/__tests__/query-params.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { extractQueryParams } from '../conventions/url-patterns.js';
+import { extractHtmxRoutes } from '../scanner/htmx-extractor.js';
+import { extractHyperscriptRoutes } from '../scanner/hyperscript-extractor.js';
+import { scanRoutes } from '../scanner/route-scanner.js';
+
+const FILE = 'test.html';
+
+describe('extractQueryParams', () => {
+  it('extracts single query param', () => {
+    const params = extractQueryParams('/api/search?q=hello');
+    expect(params).toEqual([{ name: 'q', type: 'string', required: true }]);
+  });
+
+  it('extracts multiple query params', () => {
+    const params = extractQueryParams('/api/search?q=hello&limit=10&offset=0');
+    expect(params).toHaveLength(3);
+    expect(params.map(p => p.name)).toEqual(['q', 'limit', 'offset']);
+  });
+
+  it('handles URL-encoded param names', () => {
+    const params = extractQueryParams('/api/search?query%20text=hello');
+    expect(params[0].name).toBe('query text');
+  });
+
+  it('returns empty array for no query string', () => {
+    expect(extractQueryParams('/api/users')).toEqual([]);
+  });
+
+  it('returns empty array for empty query string', () => {
+    expect(extractQueryParams('/api/users?')).toEqual([]);
+  });
+
+  it('strips fragment after query string', () => {
+    const params = extractQueryParams('/api/search?q=hello#results');
+    expect(params).toHaveLength(1);
+    expect(params[0].name).toBe('q');
+  });
+
+  it('deduplicates repeated param names', () => {
+    const params = extractQueryParams('/api/search?q=hello&q=world');
+    expect(params).toHaveLength(1);
+  });
+
+  it('handles params without values', () => {
+    const params = extractQueryParams('/api/search?verbose&q=hello');
+    expect(params).toHaveLength(2);
+    expect(params[0].name).toBe('verbose');
+    expect(params[1].name).toBe('q');
+  });
+
+  it('handles malformed percent-encoded param names gracefully', () => {
+    const params = extractQueryParams('/api/search?%ZZ=hello&q=world');
+    expect(params).toHaveLength(2);
+    expect(params[0].name).toBe('%ZZ');
+    expect(params[1].name).toBe('q');
+  });
+});
+
+describe('query params in htmx extractor', () => {
+  it('extracts query params from hx-get URL', () => {
+    const html = `<div hx-get="/api/search?q=test&limit=10">`;
+    const routes = extractHtmxRoutes(html, { file: FILE });
+    expect(routes).toHaveLength(1);
+    expect(routes[0].path).toBe('/api/search');
+    expect(routes[0].queryParams).toEqual([
+      { name: 'q', type: 'string', required: true },
+      { name: 'limit', type: 'string', required: true },
+    ]);
+  });
+
+  it('omits queryParams when URL has no query string', () => {
+    const html = `<div hx-get="/api/users">`;
+    const routes = extractHtmxRoutes(html, { file: FILE });
+    expect(routes[0].queryParams).toBeUndefined();
+  });
+});
+
+describe('query params in hyperscript extractor', () => {
+  it('extracts query params from fetch URL', () => {
+    const html = `<button _="on click fetch /api/data?id=123 as json">`;
+    const routes = extractHyperscriptRoutes(html, { file: FILE });
+    expect(routes).toHaveLength(1);
+    expect(routes[0].path).toBe('/api/data');
+    expect(routes[0].queryParams).toEqual([{ name: 'id', type: 'string', required: true }]);
+  });
+});
+
+describe('query params in scanRoutes', () => {
+  it('preserves query params through full scan pipeline', () => {
+    const html = `
+      <div hx-get="/api/search?q=test&limit=10" hx-target="#results">
+      <button _="on click fetch /api/data?format=csv as json">
+    `;
+    const routes = scanRoutes(html, FILE);
+    const searchRoute = routes.find(r => r.path === '/api/search');
+    const dataRoute = routes.find(r => r.path === '/api/data');
+    expect(searchRoute?.queryParams).toHaveLength(2);
+    expect(dataRoute?.queryParams).toHaveLength(1);
+  });
+});

package/src/__tests__/route-scanner.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { scanRoutes } from '../scanner/route-scanner.js';
+
+describe('scanRoutes', () => {
+  it('combines hyperscript and htmx routes from one file', () => {
+    const html = `
+      <button _="on click fetch /api/data as json then put it into #result">
+      <div hx-get="/api/users" hx-target="#list">
+    `;
+    const routes = scanRoutes(html, 'test.html');
+    expect(routes).toHaveLength(2);
+    expect(routes.map(r => r.path).sort()).toEqual(['/api/data', '/api/users']);
+  });
+
+  it('deduplicates routes across extractors', () => {
+    const html = `
+      <button _="on click fetch /api/users as html">
+      <div hx-get="/api/users">
+    `;
+    const routes = scanRoutes(html, 'test.html');
+    // Both extract GET /api/users — should deduplicate
+    expect(routes).toHaveLength(1);
+    expect(routes[0].path).toBe('/api/users');
+  });
+
+  it('enriches POST routes with form body fields', () => {
+    const html = `
+      <form hx-post="/api/users">
+        <input name="name" type="text" required>
+        <input name="email" type="email" required>
+        <button type="submit">Create</button>
+      </form>
+    `;
+    const routes = scanRoutes(html, 'test.html');
+    expect(routes).toHaveLength(1);
+    expect(routes[0].method).toBe('POST');
+    expect(routes[0].requestBody).toHaveLength(2);
+    expect(routes[0].requestBody![0].name).toBe('name');
+    expect(routes[0].requestBody![1].name).toBe('email');
+  });
+
+  it('handles file with no routes', () => {
+    const html = `<div>Hello world</div>`;
+    const routes = scanRoutes(html, 'test.html');
+    expect(routes).toHaveLength(0);
+  });
+});

package/src/__tests__/url-patterns.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { extractPathParams, normalizeUrl, urlToHandlerName } from '../conventions/url-patterns.js';
+
+describe('extractPathParams', () => {
+  it('extracts :param style parameters', () => {
+    expect(extractPathParams('/api/users/:id')).toEqual(['id']);
+  });
+
+  it('extracts {param} style parameters', () => {
+    expect(extractPathParams('/api/users/{id}')).toEqual(['id']);
+  });
+
+  it('extracts multiple parameters', () => {
+    expect(extractPathParams('/api/users/:userId/orders/:orderId')).toEqual(['userId', 'orderId']);
+  });
+
+  it('returns empty array for no params', () => {
+    expect(extractPathParams('/api/users')).toEqual([]);
+  });
+
+  it('deduplicates mixed styles', () => {
+    expect(extractPathParams('/api/:id/{id}')).toEqual(['id']);
+  });
+});
+
+describe('normalizeUrl', () => {
+  it('converts {param} to :param', () => {
+    expect(normalizeUrl('/api/users/{id}')).toBe('/api/users/:id');
+  });
+
+  it('strips query strings', () => {
+    expect(normalizeUrl('/api/search?q=hello')).toBe('/api/search');
+  });
+
+  it('strips fragments', () => {
+    expect(normalizeUrl('/api/users#top')).toBe('/api/users');
+  });
+
+  it('ensures leading slash', () => {
+    expect(normalizeUrl('api/users')).toBe('/api/users');
+  });
+
+  it('strips trailing slash', () => {
+    expect(normalizeUrl('/api/users/')).toBe('/api/users');
+  });
+
+  it('preserves root path', () => {
+    expect(normalizeUrl('/')).toBe('/');
+  });
+});
+
+describe('urlToHandlerName', () => {
+  it('generates camelCase from path + method', () => {
+    expect(urlToHandlerName('/api/users', 'GET')).toBe('getApiUsers');
+  });
+
+  it('converts params to ByParam', () => {
+    expect(urlToHandlerName('/api/users/:id', 'GET')).toBe('getApiUsersById');
+  });
+
+  it('handles POST method', () => {
+    expect(urlToHandlerName('/api/users', 'POST')).toBe('postApiUsers');
+  });
+
+  it('handles hyphenated segments', () => {
+    expect(urlToHandlerName('/api/user-list', 'GET')).toBe('getApiUserList');
+  });
+
+  it('handles multiple params', () => {
+    expect(urlToHandlerName('/api/users/:userId/orders/:orderId', 'DELETE')).toBe(
+      'deleteApiUsersByUserIdOrdersByOrderId'
+    );
+  });
+});

package/src/__tests__/watch-command.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  patternToRegex,
+  shouldScan,
+  shouldSkip,
+  createDebouncedRunner,
+} from '../cli/watch-command.js';
+
+describe('watch mode helpers', () => {
+  describe('patternToRegex', () => {
+    it('matches **/*.html', () => {
+      const re = patternToRegex('**/*.html');
+      expect(re.test('pages/index.html')).toBe(true);
+      expect(re.test('deep/nested/page.html')).toBe(true);
+      expect(re.test('page.html')).toBe(true);
+      expect(re.test('page.htm')).toBe(false);
+    });
+
+    it('matches **/*.htm', () => {
+      const re = patternToRegex('**/*.htm');
+      expect(re.test('page.htm')).toBe(true);
+      expect(re.test('page.html')).toBe(false);
+    });
+
+    it('matches node_modules/**', () => {
+      const re = patternToRegex('node_modules/**');
+      expect(re.test('node_modules/package/index.js')).toBe(true);
+      expect(re.test('src/index.html')).toBe(false);
+    });
+  });
+
+  describe('shouldScan', () => {
+    it('returns true for matching patterns', () => {
+      expect(shouldScan('index.html', ['**/*.html', '**/*.htm'])).toBe(true);
+      expect(shouldScan('page.htm', ['**/*.html', '**/*.htm'])).toBe(true);
+    });
+
+    it('returns false for non-matching files', () => {
+      expect(shouldScan('script.js', ['**/*.html', '**/*.htm'])).toBe(false);
+    });
+  });
+
+  describe('shouldSkip', () => {
+    it('skips node_modules', () => {
+      expect(shouldSkip('node_modules/pkg/index.html', ['node_modules/**'])).toBe(true);
+    });
+
+    it('does not skip normal files', () => {
+      expect(shouldSkip('src/index.html', ['node_modules/**', 'dist/**'])).toBe(false);
+    });
+  });
+});
+
+describe('createDebouncedRunner', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('executes after debounce delay', async () => {
+    const fn = vi.fn(async () => {});
+    const { trigger } = createDebouncedRunner(fn, 100);
+
+    trigger();
+    expect(fn).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('resets timer on rapid triggers', async () => {
+    const fn = vi.fn(async () => {});
+    const { trigger } = createDebouncedRunner(fn, 100);
+
+    trigger();
+    await vi.advanceTimersByTimeAsync(50);
+    trigger(); // reset
+    await vi.advanceTimersByTimeAsync(50);
+    expect(fn).not.toHaveBeenCalled(); // only 50ms since last trigger
+
+    await vi.advanceTimersByTimeAsync(50);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('prevents overlapping concurrent executions', async () => {
+    let running = 0;
+    let maxConcurrent = 0;
+    const fn = vi.fn(async () => {
+      running++;
+      maxConcurrent = Math.max(maxConcurrent, running);
+      await new Promise(r => setTimeout(r, 200));
+      running--;
+    });
+    const { trigger } = createDebouncedRunner(fn, 50);
+
+    trigger();
+    await vi.advanceTimersByTimeAsync(50); // starts first run
+
+    // Trigger again while first is running
+    trigger();
+    await vi.advanceTimersByTimeAsync(50); // debounce fires, but run() sees running=true → queued
+
+    expect(fn).toHaveBeenCalledTimes(1); // first call started, second queued
+    expect(maxConcurrent).toBe(1);
+
+    // Let first run complete
+    await vi.advanceTimersByTimeAsync(200);
+    // queued=true → trigger() called → wait for debounce
+    await vi.advanceTimersByTimeAsync(50);
+    // second run starts
+    await vi.advanceTimersByTimeAsync(200);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(maxConcurrent).toBe(1);
+  });
+
+  it('queues follow-up when triggered during execution', async () => {
+    const calls: number[] = [];
+    let callCount = 0;
+    const fn = vi.fn(async () => {
+      const n = ++callCount;
+      calls.push(n);
+      await new Promise(r => setTimeout(r, 100));
+    });
+    const { trigger } = createDebouncedRunner(fn, 50);
+
+    trigger();
+    await vi.advanceTimersByTimeAsync(50); // fn starts (call 1)
+    expect(calls).toEqual([1]);
+
+    trigger(); // during execution → queued
+    await vi.advanceTimersByTimeAsync(100); // call 1 finishes, queued → trigger
+    await vi.advanceTimersByTimeAsync(50); // debounce fires → call 2 starts
+    expect(calls).toEqual([1, 2]);
+
+    await vi.advanceTimersByTimeAsync(100); // call 2 finishes
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});

package/src/cli/config.ts

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { ServerBridgeConfig } from '../types.js';
+
+const CONFIG_FILENAMES = ['.serverbridgerc.json', '.serverbridgerc', 'serverbridge.config.json'];
+
+/**
+ * Load config from file, merging with CLI overrides.
+ */
+export async function loadConfig(
+  cwd: string,
+  overrides: Partial<ServerBridgeConfig> = {}
+): Promise<ServerBridgeConfig> {
+  let fileConfig: Partial<ServerBridgeConfig> = {};
+
+  for (const filename of CONFIG_FILENAMES) {
+    try {
+      const content = await readFile(join(cwd, filename), 'utf-8');
+      fileConfig = JSON.parse(content);
+      break;
+    } catch {
+      // File doesn't exist, try next
+    }
+  }
+
+  return {
+    framework: overrides.framework ?? fileConfig.framework ?? 'express',
+    output: overrides.output ?? fileConfig.output ?? './server/routes',
+    typescript: overrides.typescript ?? fileConfig.typescript ?? true,
+    include: overrides.include ?? fileConfig.include ?? ['**/*.{html,htm}'],
+    exclude: overrides.exclude ?? fileConfig.exclude ?? ['node_modules/**', 'dist/**'],
+    basePath: overrides.basePath ?? fileConfig.basePath,
+    ignore: overrides.ignore ?? fileConfig.ignore,
+  };
+}

package/src/cli/diff-command.ts

@@ -0,0 +1,96 @@
+import { resolve } from 'node:path';
+import { scanDirectory } from '../scanner/route-scanner.js';
+import { loadManifest, diffRoutes } from '../generators/manifest.js';
+import { formatConflicts } from '../scanner/conflict-detector.js';
+import { loadConfig } from './config.js';
+
+interface DiffOptions {
+  dir: string;
+  format?: 'summary' | 'detailed';
+  include?: string[];
+  exclude?: string[];
+  ignore?: string[];
+}
+
+export async function runDiff(options: DiffOptions): Promise<void> {
+  const cwd = resolve(options.dir);
+  const config = await loadConfig(cwd, {
+    include: options.include,
+    exclude: options.exclude,
+    ignore: options.ignore,
+  });
+
+  const outputDir = resolve(cwd, config.output ?? './server/routes');
+  const manifest = await loadManifest(outputDir);
+
+  if (!manifest) {
+    console.log('No manifest found. Run "serverbridge generate" first.');
+    return;
+  }
+
+  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)}\n`
+    );
+  }
+
+  const diff = diffRoutes(manifest, result.routes);
+  const hasChanges = diff.added.length > 0 || diff.changed.length > 0 || diff.removed.length > 0;
+  const total =
+    diff.added.length + diff.changed.length + diff.removed.length + diff.unchanged.length;
+
+  console.log(`\nRoute Diff Summary:`);
+  console.log(`  Total:     ${total}`);
+  console.log(`  Unchanged: ${diff.unchanged.length}`);
+  console.log(`  Added:     ${diff.added.length}`);
+  console.log(`  Changed:   ${diff.changed.length}`);
+  console.log(`  Removed:   ${diff.removed.length}`);
+
+  if (options.format === 'detailed' && hasChanges) {
+    console.log('');
+
+    if (diff.added.length > 0) {
+      console.log('Added:');
+      for (const route of diff.added) {
+        console.log(
+          `  + ${route.method} ${route.path}  (${route.source.file}:${route.source.line ?? '?'})`
+        );
+      }
+    }
+
+    if (diff.changed.length > 0) {
+      console.log('Changed:');
+      for (const route of diff.changed) {
+        console.log(
+          `  ~ ${route.method} ${route.path}  (${route.source.file}:${route.source.line ?? '?'})`
+        );
+      }
+    }
+
+    if (diff.removed.length > 0) {
+      console.log('Removed:');
+      for (const entry of diff.removed) {
+        console.log(`  - ${entry.method} ${entry.path}`);
+      }
+    }
+  }
+
+  if (hasChanges) {
+    console.log('\nChanges detected. Run "serverbridge generate" to update.');
+    process.exitCode = 1;
+  } else {
+    console.log('\nNo changes detected.');
+  }
+}