@swissjs/swite 0.3.0

package/src/dev-engine/pythonDevManager.ts

@@ -0,0 +1,116 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { resolve } from "node:path";
+import chalk from "chalk";
+import { initPythonProxy } from "../adapters/proxy/proxyToPython.js";
+import type { PythonServiceConfig } from "../config/config.js";
+
+const POLL_INTERVAL_MS = 500;
+const HEALTH_TIMEOUT_MS = 15_000;
+const BACKOFF_THRESHOLD = 5;
+
+let _child: ChildProcess | null = null;
+
+/**
+ * Spawn the Python service and wait until its health endpoint responds 200.
+ * Streams stdout/stderr line-buffered, prefixed with [python].
+ * Also calls initPythonProxy so proxyToPython works without PYTHON_SERVICE_URL.
+ */
+export async function startPythonDevService(
+  config: PythonServiceConfig,
+  projectRoot: string,
+): Promise<void> {
+  const entryPath = resolve(projectRoot, config.entry);
+  const healthUrl = `http://localhost:${config.port}${config.healthCheck}`;
+  const pythonCmd = process.platform === "win32" ? "python" : "python3";
+
+  console.log(
+    chalk.blue(`[python] spawning: ${pythonCmd} ${config.entry} (port ${config.port})`),
+  );
+
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...config.env,
+    PORT: String(config.port),
+  };
+
+  _child = spawn(pythonCmd, [entryPath], {
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  pipeLines(_child.stdout, chalk.cyan("[python] "));
+  pipeLines(_child.stderr, chalk.yellow("[python] "));
+
+  _child.on("exit", (code) => {
+    if (code !== null && code !== 0) {
+      console.error(
+        chalk.red(
+          `\n[python] process exited with code ${code} — Node server continuing in degraded mode\n`,
+        ),
+      );
+    }
+    _child = null;
+  });
+
+  initPythonProxy(config);
+
+  await pollHealth(healthUrl);
+
+  console.log(chalk.green(`[python] healthy — ${healthUrl}`));
+}
+
+/**
+ * Send SIGTERM to the Python child process if running.
+ */
+export function stopPythonDevService(): void {
+  if (_child) {
+    console.log(chalk.gray("[python] shutting down..."));
+    _child.kill("SIGTERM");
+    _child = null;
+  }
+}
+
+// ── internals ────────────────────────────────────────────────────────────────
+
+function pipeLines(
+  stream: NodeJS.ReadableStream | null,
+  prefix: string,
+): void {
+  if (!stream) return;
+  let buffer = "";
+  stream.on("data", (chunk: Buffer) => {
+    buffer += chunk.toString();
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (line.trim()) process.stdout.write(prefix + line + "\n");
+    }
+  });
+}
+
+async function pollHealth(url: string): Promise<void> {
+  const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+  let attempt = 0;
+
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(1000) });
+      if (res.ok) return;
+    } catch {
+      // not ready yet
+    }
+
+    attempt++;
+    const delay =
+      attempt <= BACKOFF_THRESHOLD
+        ? POLL_INTERVAL_MS
+        : Math.min(POLL_INTERVAL_MS * Math.pow(2, attempt - BACKOFF_THRESHOLD), 3000);
+
+    await new Promise<void>((resolve) => setTimeout(resolve, delay));
+  }
+
+  stopPythonDevService();
+  throw new Error(
+    `[python] health check timed out after ${HEALTH_TIMEOUT_MS}ms — is ${url} reachable?`,
+  );
+}

package/src/dev-engine/router/file-router.ts

@@ -0,0 +1,164 @@
+/*
+ * Copyright (c) 2024 Themba Mzumara
+ * SWITE - SWISS Development Server
+ * Licensed under the MIT License.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import type { RouteDefinition } from "@swissjs/core";
+import { RouteScanner } from "@swissjs/plugin-file-router/core";
+import { createFileWatcher } from "@swissjs/plugin-file-router/dev";
+import { HMREngine } from "../hmr/hmr.js";
+import { findWorkspaceRoot } from "../../kernel/workspace.js";
+
+export interface FileRouterConfig {
+  root: string;
+  hmr: HMREngine;
+}
+
+export interface FileRouterResult {
+  routeScanner: RouteScanner | null;
+  routeWatcher: Awaited<ReturnType<typeof createFileWatcher>> | null;
+  routes: RouteDefinition[];
+}
+
+/**
+ * Setup file-based routing
+ * Scans for route files in pages/ directories and watches for changes
+ */
+export async function setupFileRouter(
+  config: FileRouterConfig,
+): Promise<FileRouterResult> {
+  const result: FileRouterResult = {
+    routeScanner: null,
+    routeWatcher: null,
+    routes: [],
+  };
+
+  try {
+    const workspaceRoot = await findWorkspaceRoot(config.root);
+    const appRoot = config.root;
+
+    // Initialize route scanner
+    result.routeScanner = new RouteScanner({
+      routesDir: "./src/pages",
+      extensions: [".ui", ".uix"],
+      layouts: true,
+      lazyLoading: true,
+    });
+
+          // Scan routes from multiple locations:
+          // 1. App's pages directory (apps/alpine/src/pages)
+          // 2. SKLTN's pages directory (framework/skltn/src/pages) - for reusable auth pages
+    const routesToScan: string[] = [];
+
+    // App pages
+    const appPagesDir = path.join(appRoot, "src", "pages");
+    try {
+      await fs.access(appPagesDir);
+      routesToScan.push(appPagesDir);
+      console.log(chalk.gray(`  📄 Scanning app routes from ${appPagesDir}`));
+    } catch {
+      // pages directory doesn't exist, skip
+    }
+
+    // SKLTN pages (if workspace root exists)
+    if (workspaceRoot && workspaceRoot !== appRoot) {
+      // Try framework/skltn first (new location), then fallback to lib/skltn (legacy)
+      const skltnPagesDir = path.join(
+        workspaceRoot,
+        "framework",
+        "skltn",
+        "src",
+        "pages",
+      );
+      const legacySkltnPagesDir = path.join(
+        workspaceRoot,
+        "lib",
+        "skltn",
+        "src",
+        "pages",
+      );
+      
+      try {
+        await fs.access(skltnPagesDir);
+        routesToScan.push(skltnPagesDir);
+        console.log(
+          chalk.gray(`  📄 Scanning SKLTN routes from ${skltnPagesDir}`),
+        );
+      } catch {
+        // Try legacy location
+        try {
+          await fs.access(legacySkltnPagesDir);
+          routesToScan.push(legacySkltnPagesDir);
+          console.log(
+            chalk.gray(`  📄 Scanning SKLTN routes from ${legacySkltnPagesDir} (legacy)`),
+          );
+        } catch {
+          // pages directory doesn't exist, skip
+        }
+      }
+    }
+
+    // Scan all route directories
+    for (const pagesDir of routesToScan) {
+      try {
+        const scannedRoutes = await result.routeScanner.scanRoutes(pagesDir);
+        result.routes.push(...scannedRoutes);
+        console.log(
+          chalk.green(
+            `  ✓ Found ${scannedRoutes.length} routes in ${pagesDir}`,
+          ),
+        );
+      } catch (error) {
+        console.warn(
+          chalk.yellow(`  ⚠ Failed to scan routes from ${pagesDir}:`),
+          error,
+        );
+      }
+    }
+
+    // Setup file watcher for route changes
+    if (routesToScan.length > 0) {
+      // Watch the first pages directory (can be extended to watch multiple)
+      result.routeWatcher = await createFileWatcher({
+        directory: routesToScan[0],
+        extensions: [".ui", ".uix"],
+      });
+
+      result.routeWatcher.on("change", async (filePath) => {
+        console.log(chalk.yellow(`  🔄 Route file changed: ${filePath}`));
+        // Rescan routes
+        result.routes = [];
+        for (const pagesDir of routesToScan) {
+          try {
+            const scannedRoutes =
+              await result.routeScanner!.scanRoutes(pagesDir);
+            result.routes.push(...scannedRoutes);
+          } catch (error) {
+            console.warn(`Failed to rescan routes:`, error);
+          }
+        }
+        // Notify HMR about route changes
+        config.hmr.notifyChange(filePath);
+      });
+
+      console.log(
+        chalk.green(
+          `  ✓ File router initialized with ${result.routes.length} routes`,
+        ),
+      );
+    } else {
+      console.log(
+        chalk.gray(`  ⚠ No pages directories found, file router disabled`),
+      );
+    }
+  } catch (error) {
+    console.warn(chalk.yellow(`  ⚠ File router setup failed:`), error);
+    // Continue without file router
+  }
+
+  return result;
+}

package/src/dev-engine/server.ts

@@ -0,0 +1,152 @@
+/*
+ * Copyright (c) 2024 Themba Mzumara
+ * SWITE - SWISS Development Server
+ * Licensed under the MIT License.
+ */
+
+import type { RouteDefinition } from "@swissjs/core";
+import { RouteScanner } from "@swissjs/plugin-file-router/core";
+import { createFileWatcher } from "@swissjs/plugin-file-router/dev";
+import express from "express";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { ModuleResolver } from "../resolution/resolver.js";
+import { HMREngine } from "./hmr/hmr.js";
+import chalk from "chalk";
+import { setupMiddleware } from "./middleware/middleware-setup.js";
+import { buildSymlinkRegistry } from "../resolution/symlink-registry.js";
+import { findSwissLibMonorepo } from "../kernel/package-finder.js";
+
+export interface SwiteConfig {
+  root: string;
+  // Workspace/monorepo root. When set, Swite will use this for resolving
+  // node_modules, workspace packages, and import-map generation.
+  // This avoids relying on auto-detection (pnpm-workspace.yaml) which may not
+  // exist in some deployment contexts.
+  rootDir?: string;
+  publicDir: string;
+  port: number;
+  host: string;
+  open: boolean;
+  hmrPort?: number; // Optional HMR WebSocket port
+}
+
+export class SwiteServer {
+  private app = express();
+  private resolver: ModuleResolver;
+  private hmr: HMREngine;
+  private config: SwiteConfig;
+  private routeScanner: RouteScanner | null = null;
+  private routeWatcher: Awaited<ReturnType<typeof createFileWatcher>> | null =
+    null;
+  private routes: RouteDefinition[] = [];
+
+  constructor(config: Partial<SwiteConfig> = {}) {
+    this.config = {
+      root: process.cwd(),
+      publicDir: "public",
+      port: 3000,
+      host: "localhost",
+      open: true,
+      ...config,
+    };
+
+    this.resolver = new ModuleResolver(this.config.root);
+    this.hmr = new HMREngine(this.config.root, this.config.hmrPort);
+  }
+
+  // CG-03: find workspace root by walking up from startDir
+  private async findWorkspaceRoot(startDir: string): Promise<string | null> {
+    if (this.config.rootDir) {
+      return path.resolve(this.config.rootDir);
+    }
+    let current = startDir;
+    for (let i = 0; i < 6; i++) {
+      try {
+        await fs.access(path.join(current, "pnpm-workspace.yaml"));
+        return current;
+      } catch {}
+      try {
+        const pkgJson = JSON.parse(
+          await fs.readFile(path.join(current, "package.json"), "utf-8")
+        );
+        if (pkgJson.workspaces) return current;
+      } catch {}
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+    return null;
+  }
+
+  async start() {
+    const startTime = Date.now();
+    console.log(chalk.cyan("\n⚡ SWITE - SWISS Development Server\n"));
+    console.time("Startup");
+
+    // CG-03: Build symlink registry before serving any requests.
+    // Maps realpath(node_modules/pkg symlink) → /node_modules/pkg browser URL
+    // so toUrl() can map absolute filesystem paths back to browser URLs.
+    console.time("Symlink Registry");
+    try {
+      const nodeModulesDirs: string[] = [
+        path.join(this.config.root, "node_modules"),
+        // Also scan the server package's own node_modules (one level up from the
+        // app root, e.g. apps/server/node_modules) — pnpm places workspace package
+        // symlinks there, not in the app root's node_modules subfolder.
+        path.join(path.dirname(this.config.root), "node_modules"),
+      ];
+      const workspaceRoot = await this.findWorkspaceRoot(this.config.root);
+      if (workspaceRoot) {
+        nodeModulesDirs.push(path.join(workspaceRoot, "node_modules"));
+      }
+      const swissLib = await findSwissLibMonorepo(this.config.root);
+      if (swissLib) {
+        nodeModulesDirs.push(path.join(swissLib, "node_modules"));
+      }
+      await buildSymlinkRegistry(nodeModulesDirs);
+    } catch (err: any) {
+      console.warn(`[SWITE] Symlink registry build failed: ${err.message}`);
+    }
+    console.timeEnd("Symlink Registry");
+
+    // Setup middleware
+    console.time("Middleware Setup");
+    const workspaceRoot = await this.findWorkspaceRoot(this.config.root);
+    const middlewareResult = await setupMiddleware(this.app, {
+      root: this.config.root,
+      workspaceRoot,
+      publicDir: this.config.publicDir,
+      resolver: this.resolver,
+      hmr: this.hmr,
+    });
+    this.routes = middlewareResult.routes;
+    this.routeScanner = middlewareResult.routeScanner;
+    this.routeWatcher = middlewareResult.routeWatcher;
+    console.timeEnd("Middleware Setup");
+
+    // Start HMR
+    console.time("HMR Start");
+    await this.hmr.initialize();
+    await this.hmr.start();
+    console.timeEnd("HMR Start");
+
+    // Start HTTP server
+    // Use 0.0.0.0 to bind to all interfaces (IPv4 and IPv6)
+    const bindHost = this.config.host === "localhost" ? "0.0.0.0" : this.config.host;
+    console.time("HTTP Listen");
+    await new Promise<void>((resolve) => {
+      this.app.listen(this.config.port, bindHost, () => {
+        console.timeEnd("HTTP Listen");
+        console.timeEnd("Startup");
+        console.log(
+          chalk.green(
+            `  ➜ Local:   http://localhost:${this.config.port}/`,
+          ),
+        );
+        console.log(chalk.gray(`  ➜ Ready in ${Date.now() - startTime}ms\n`));
+        resolve();
+      });
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/*
+ * SWITE - SWISS Development Server
+ * Main exports
+ */
+
+export { SwiteServer } from "./dev-engine/server.js";
+export type { SwiteConfig } from "./dev-engine/server.js";
+export { SwiteBuilder, build } from "./build-engine/builder.js";
+export type { BuildConfig } from "./build-engine/builder.js";
+export { ModuleResolver } from "./resolution/resolver.js";
+export { HMREngine } from "./dev-engine/hmr/hmr.js";
+export { defineConfig } from "./config/config.js";
+export type {
+  SwiteUserConfig,
+  ServerConfig,
+  ServicesConfig,
+  PythonServiceConfig,
+} from "./config/config.js";
+export { proxyToPython, initPythonProxy, setProductionMode } from "./adapters/proxy/proxyToPython.js";
+export type { ProxyOptions } from "./adapters/proxy/proxyToPython.js";
+export { SwiteProxyError } from "./adapters/proxy/SwiteProxyError.js";
+export { loadUserConfig } from "./config/config-loader.js";
+export {
+  startPythonDevService,
+  stopPythonDevService,
+} from "./dev-engine/pythonDevManager.js";

package/src/internal/cache/compilation-cache.ts

@@ -0,0 +1,182 @@
+/*
+ * Copyright (c) 2024 Themba Mzumara
+ * SWITE - SWISS Development Server
+ * Compilation Cache for .ui, .uix, .ts files
+ * Licensed under the MIT License.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+
+interface CacheEntry {
+  compiled: string;
+  rewritten: string;
+  mtime: number;
+  dependencies: string[];
+  timestamp: number;
+}
+
+/**
+ * Compilation cache with dependency tracking
+ * Invalidates when source file or dependencies change
+ */
+export class CompilationCache {
+  private cache = new Map<string, CacheEntry>();
+  private readonly maxSize = 1000; // Prevent memory leaks
+
+  /**
+   * Get cached compilation result if valid
+   */
+  async get(
+    filePath: string,
+    getDependencies: (compiled: string) => Promise<string[]>,
+  ): Promise<string | null> {
+    const entry = this.cache.get(filePath);
+    if (!entry) {
+      return null;
+    }
+
+    // Check if source file changed
+    try {
+      const stats = await fs.stat(filePath);
+      if (stats.mtimeMs !== entry.mtime) {
+        console.log(
+          chalk.yellow(`[Cache] Invalidating ${filePath}: file modified`),
+        );
+        this.cache.delete(filePath);
+        return null;
+      }
+    } catch (error) {
+      // File deleted or inaccessible
+      this.cache.delete(filePath);
+      return null;
+    }
+
+    // Check if dependencies changed (order-independent comparison)
+    const currentDeps = await getDependencies(entry.compiled);
+    const prevSet = new Set(entry.dependencies);
+    const depsChanged =
+      currentDeps.length !== entry.dependencies.length ||
+      currentDeps.some((dep) => !prevSet.has(dep));
+
+    if (depsChanged) {
+      console.log(
+        chalk.yellow(
+          `[Cache] Invalidating ${filePath}: dependencies changed`,
+        ),
+      );
+      this.cache.delete(filePath);
+      return null;
+    }
+
+    // Check if dependencies still exist and haven't changed
+    for (const dep of entry.dependencies) {
+      try {
+        const depStats = await fs.stat(dep);
+        // If dependency was modified after cache entry, invalidate
+        if (depStats.mtimeMs > entry.timestamp) {
+          console.log(
+            chalk.yellow(
+              `[Cache] Invalidating ${filePath}: dependency ${dep} modified`,
+            ),
+          );
+          this.cache.delete(filePath);
+          return null;
+        }
+      } catch {
+        // Dependency deleted or inaccessible
+        console.log(
+          chalk.yellow(
+            `[Cache] Invalidating ${filePath}: dependency ${dep} not found`,
+          ),
+        );
+        this.cache.delete(filePath);
+        return null;
+      }
+    }
+
+    // Check if cached content has stale CDN URLs (from before import rewriter fix)
+    if (entry.rewritten.includes("cdn.jsdelivr.net") || entry.rewritten.includes("esm.sh")) {
+      console.log(
+        chalk.yellow(
+          `[Cache] Invalidating ${filePath}: contains stale CDN URLs`,
+        ),
+      );
+      this.cache.delete(filePath);
+      return null;
+    }
+
+    console.log(chalk.green(`[Cache] ✅ Cache hit for ${filePath}`));
+    return entry.rewritten;
+  }
+
+  /**
+   * Store compilation result in cache
+   */
+  async set(
+    filePath: string,
+    compiled: string,
+    rewritten: string,
+    getDependencies: (compiled: string) => Promise<string[]>,
+  ): Promise<void> {
+    // Enforce max size (LRU eviction)
+    if (this.cache.size >= this.maxSize) {
+      // Remove oldest entry (simple FIFO)
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+        console.log(chalk.gray(`[Cache] Evicted ${firstKey} (cache full)`));
+      }
+    }
+
+    try {
+      const stats = await fs.stat(filePath);
+      const dependencies = await getDependencies(compiled);
+
+      this.cache.set(filePath, {
+        compiled,
+        rewritten,
+        mtime: stats.mtimeMs,
+        dependencies,
+        timestamp: Date.now(),
+      });
+
+      console.log(
+        chalk.green(
+          `[Cache] ✅ Cached ${filePath} (${dependencies.length} deps)`,
+        ),
+      );
+    } catch (error) {
+      console.warn(chalk.yellow(`[Cache] Failed to cache ${filePath}:`, error));
+    }
+  }
+
+  /**
+   * Clear cache for a specific file
+   */
+  clear(filePath: string): void {
+    this.cache.delete(filePath);
+  }
+
+  /**
+   * Clear entire cache
+   */
+  clearAll(): void {
+    this.cache.clear();
+    console.log(chalk.gray("[Cache] Cleared all entries"));
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): { size: number; maxSize: number } {
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+    };
+  }
+}
+
+// Singleton instance
+export const compilationCache = new CompilationCache();

package/src/internal/generate-import-map-cli.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) 2024 Themba Mzumara
+ * SWITE - SWISS Development Server
+ * CLI tool to generate import maps
+ * Licensed under the MIT License.
+ */
+
+import { generateImportMap, saveImportMap } from "./generate-import-map.js";
+import { findWorkspaceRoot } from "../kernel/workspace.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function main() {
+  // Find app root (where swite is running from)
+  // This script is typically run from the app directory
+  const appRoot = process.cwd();
+  const workspaceRoot = await findWorkspaceRoot(appRoot);
+
+  console.log(`[ImportMap] App root: ${appRoot}`);
+  console.log(`[ImportMap] Workspace root: ${workspaceRoot || "none"}`);
+
+  // Generate import map
+  const importMap = await generateImportMap(appRoot, workspaceRoot);
+
+  // Save to .swite/import-map.json in app root
+  const outputPath = path.join(appRoot, ".swite", "import-map.json");
+  await saveImportMap(importMap, outputPath);
+
+  console.log(`[ImportMap] ✅ Import map generated successfully`);
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error("[ImportMap] Error:", error);
+  process.exit(1);
+});