@swissjs/swite 0.3.0

package/docs/PATH_RESOLUTION_GUIDE.md

@@ -0,0 +1,221 @@
+# Path Resolution Guide
+
+## Overview
+
+SWITE must correctly resolve URL paths to filesystem paths for different types of resources:
+- **App files**: `/src/index.ui` → `apps/alpine/src/index.ui`
+- **Workspace packages**: `/packages/ai-agents/...` → `SwissEnterpriseRepo/packages/ai-agents/...`
+- **Business modules**: `/businessModules/cart/...` → `SwissEnterpriseRepo/businessModules/cart/...`
+- **SWISS packages**: `/swiss-packages/core/...` → `SWISS/packages/core/...`
+
+## Common Issues
+
+### Issue 1: 500 Errors for `/businessModules/` Files
+
+**Browser Error:**
+```
+GET http://localhost:3001/businessModules/cart/src/context/PosContext.js 
+net::ERR_ABORTED 500 (Internal Server Error)
+```
+
+**Server Error:**
+```
+Error: File not found: /businessModules/cart/src/context/PosContext.js (tried .js, .ts, .ui, .uix)
+filePath was: C:\...\apps\alpine\businessModules\cart\src\context\PosContext.js
+```
+
+**Root Cause:**
+
+The file resolver was looking in the WRONG location:
+- ❌ Looking in: `apps/alpine/businessModules/cart/...`
+- ✅ Should look in: `SwissEnterpriseRepo/businessModules/cart/...` (workspace root)
+
+**Why This Happened:**
+
+The `file-path-resolver.ts` only had special handling for `/lib/` and `/packages/` paths. When a URL like `/businessModules/cart/...` was requested, it fell through to generic path resolution logic that incorrectly resolved to the app directory instead of workspace root.
+
+**The Fix:**
+
+Added `/businessModules/` to the workspace-level directory list in `src/utils/file-path-resolver.ts`:
+
+```typescript
+// Workspace-level directories: always resolve from workspace root
+if (url.startsWith("/lib/") || 
+    url.startsWith("/packages/") || 
+    url.startsWith("/businessModules/")) {
+    const wsRoot = workspaceRoot || (await findWorkspaceRoot(root));
+    if (wsRoot) {
+        return path.join(wsRoot, url);
+    } else {
+        return path.join(root, url);
+    }
+}
+```
+
+**Testing:**
+
+```bash
+# Should return compiled JavaScript code
+curl http://localhost:3001/businessModules/cart/src/context/PosContext.js
+
+# Should NOT return error
+```
+
+## Path Resolution Rules
+
+### 1. SWISS Packages (`/swiss-packages/*`)
+
+**URL Pattern:** `/swiss-packages/core/src/index.ts`
+
+**Resolution:**
+1. Try: `SWS/SWISS/packages/core/src/index.ts`
+2. Try: Alternative SWISS monorepo locations
+3. Fallback: First path even if file doesn't exist (will error later)
+
+**Location:** Always in SWISS monorepo, not SwissEnterpriseRepo
+
+### 2. Workspace Packages (`/packages/*`, `/lib/*`, `/businessModules/*`)
+
+**URL Pattern:** 
+- `/packages/ai-agents/src/index.ui`
+- `/lib/skltn/src/index.ui`
+- `/businessModules/cart/src/context/PosContext.uix`
+
+**Resolution:**
+1. Find workspace root (pnpm-workspace.yaml)
+2. Join: `{workspaceRoot}{url}`
+3. Example: `SwissEnterpriseRepo` + `/packages/ai-agents/...`
+
+**Location:** Always at workspace root
+
+### 3. App Files (`/src/*`, `/public/*`, `/assets/*`)
+
+**URL Pattern:** `/src/index.ui`
+
+**Resolution:**
+1. Join: `{appRoot}{url}`
+2. Example: `apps/alpine` + `/src/index.ui`
+
+**Location:** Always in app directory
+
+### 4. Generic Absolute URLs (`/*`)
+
+**URL Pattern:** `/some/path/file.js`
+
+**Resolution:**
+1. Try: workspace root first
+2. Check if file exists
+3. Fallback: app root
+
+**Location:** Depends on file existence
+
+## Extension Resolution
+
+The handlers try multiple extensions when a file isn't found:
+
+**For `.js` URL:** Try in order:
+1. `.js` - Actual JavaScript file
+2. `.ts` - TypeScript source (compiled on-the-fly)
+3. `.ui` - Swiss UI component (compiled on-the-fly)
+4. `.uix` - Swiss UIX component (compiled on-the-fly)
+
+**Example:**
+- Request: `/businessModules/cart/src/context/PosContext.js`
+- File exists as: `.../PosContext.uix`
+- Handler compiles `.uix` → JavaScript and returns it
+
+## Debugging Path Resolution
+
+### 1. Check Server Logs
+
+```bash
+tail -f /tmp/alpine-dev.log | grep "file-path-resolver"
+```
+
+Look for:
+```
+[file-path-resolver] Found SWISS package at: ...
+[file-path-resolver] SWISS package not found, using: ...
+```
+
+### 2. Check Handler Logs
+
+```bash
+tail -f /tmp/alpine-dev.log | grep "\[.js\]"
+```
+
+Look for:
+```
+[.js→.ts] C:\...\file.ts not found, trying next...
+[.js→.ui] C:\...\file.ui not found, trying next...
+[.js→.uix] C:\...\file.uix not found, trying next...
+[.js] File not found: /path/to/file.js (tried .js, .ts, .ui, .uix)
+[.js] filePath was: C:\actual\path\tried
+```
+
+### 3. Test Specific URLs
+
+```bash
+# Test workspace package
+curl -I http://localhost:3001/packages/ai-agents/src/index.ui
+
+# Test business module
+curl -I http://localhost:3001/businessModules/cart/src/context/PosContext.js
+
+# Test SWISS package
+curl -I http://localhost:3001/swiss-packages/core/src/index.ts
+
+# Test app file
+curl -I http://localhost:3001/src/index.ui
+```
+
+Expected: `200 OK` for all valid paths
+
+## Adding New Workspace Directories
+
+If you add a new workspace-level directory (like `/modules/` or `/components/`), add it to the resolver:
+
+1. **Edit:** `src/utils/file-path-resolver.ts`
+2. **Add to condition:**
+   ```typescript
+   if (url.startsWith("/lib/") || 
+       url.startsWith("/packages/") || 
+       url.startsWith("/businessModules/") ||
+       url.startsWith("/YOUR_NEW_DIR/")) {
+   ```
+3. **Rebuild:** `pnpm build`
+4. **Test:** Restart dev server and test URLs
+
+## Static Files vs. Compiled Files
+
+### Static Files (express.static)
+- **Served by:** Express static middleware
+- **Directories:** `/public`, `/node_modules`, some `/lib`, some `/packages`
+- **Processing:** None (direct file serving)
+- **Use for:** CSS, images, pre-built JS
+
+### Compiled Files (handlers)
+- **Served by:** SWITE middleware (handlers)
+- **Extensions:** `.ts`, `.ui`, `.uix`
+- **Processing:** Compilation + import rewriting
+- **Use for:** Source files that need compilation
+
+**Note:** `/businessModules/`, `/packages/`, and `/lib/` are NOT served as static files because they may contain `.ui`/`.uix` files that need compilation. The handlers process them on-demand.
+
+## Troubleshooting Checklist
+
+- [ ] URL starts with correct prefix (`/swiss-packages/`, `/packages/`, `/businessModules/`, `/src/`)
+- [ ] File exists at expected location (check filesystem)
+- [ ] File has correct extension (`.ts`, `.ui`, `.uix`, `.js`)
+- [ ] Workspace root is detected correctly (has `pnpm-workspace.yaml`)
+- [ ] Path resolver includes the directory in special handling
+- [ ] Server has been restarted after code changes
+- [ ] Browser cache has been cleared (hard refresh)
+
+## Related Files
+
+- `src/utils/file-path-resolver.ts` - Main path resolution logic
+- `src/handlers/base-handler.ts` - Handler base class with file resolution
+- `src/handlers/js-handler.ts` - Extension resolution for .js URLs
+- `src/middleware/static-files.ts` - Static file serving setup
+

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@swissjs/swite",
+  "version": "0.3.0",
+  "description": "SWITE - SWISS Development Server (Vite replacement)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "swite": "dist/cli.js"
+  },
+  "dependencies": {
+    "@swissjs/core": "link:../swiss-lib/runtime",
+    "@swissjs/compiler": "link:../swiss-lib/compiler",
+    "@swissjs/plugin-file-router": "link:../swiss-lib/plugins/file-router",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.5.3",
+    "es-module-lexer": "^1.3.1",
+    "esbuild": "^0.25.0",
+    "express": "^4.18.2",
+    "ws": "^8.20.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "18.19.121",
+    "@types/ws": "^8.5.8",
+    "@changesets/cli": "^2.29.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kibologic/alpine-erp-core.git"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "clean": "rm -rf dist node_modules && rm -f tsconfig.tsbuildinfo",
+    "generate-import-map": "tsx src/internal/generate-import-map-cli.ts",
+    "test": "node --import tsx --test __tests__/import-rewriter-bug.test.ts",
+    "changeset": "changeset",
+    "release:version": "changeset version",
+    "release:publish": "changeset publish"
+  }
+}

package/src/adapters/proxy/SwiteProxyError.ts

@@ -0,0 +1,12 @@
+export class SwiteProxyError extends Error {
+  readonly status: number;
+  readonly responseBody: unknown;
+
+  constructor(status: number, message: string, responseBody?: unknown) {
+    super(message);
+    this.name = "SwiteProxyError";
+    this.status = status;
+    this.responseBody = responseBody ?? null;
+    Object.setPrototypeOf(this, SwiteProxyError.prototype);
+  }
+}

package/src/adapters/proxy/proxyToPython.ts

@@ -0,0 +1,88 @@
+import type { PythonServiceConfig } from "../../config/config.js";
+import { SwiteProxyError } from "./SwiteProxyError.js";
+
+let _pythonConfig: PythonServiceConfig | null = null;
+let _productionMode = false;
+
+/**
+ * Called by swite start on startup.
+ * Disables localhost fallback — PYTHON_SERVICE_URL is the only valid base URL.
+ */
+export function setProductionMode(): void {
+  _productionMode = true;
+}
+
+/**
+ * Called by the swite dev process manager (S-03) on startup.
+ * Stores the resolved python service config for use by proxyToPython.
+ */
+export function initPythonProxy(config: PythonServiceConfig): void {
+  _pythonConfig = config;
+}
+
+export interface ProxyOptions {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Proxy a request from the Node server to the internal Python service.
+ *
+ * Resolves base URL from PYTHON_SERVICE_URL env var if set,
+ * otherwise falls back to http://localhost:{python.port} from config.
+ *
+ * Always injects X-Internal-Token header.
+ * Throws SwiteProxyError on non-2xx responses.
+ */
+export async function proxyToPython<T>(options: ProxyOptions): Promise<T> {
+  const envBaseUrl = process.env["PYTHON_SERVICE_URL"];
+
+  let baseUrl: string;
+  if (envBaseUrl) {
+    baseUrl = envBaseUrl.replace(/\/$/, "");
+  } else if (!_productionMode && _pythonConfig) {
+    baseUrl = `http://localhost:${_pythonConfig.port}`;
+  } else {
+    throw new Error(
+      _productionMode
+        ? "PYTHON_SERVICE_URL is required in production mode but is not set."
+        : "Python service not configured. Call initPythonProxy() before using proxyToPython, or set PYTHON_SERVICE_URL.",
+    );
+  }
+
+  const token = process.env["INTERNAL_API_TOKEN"] ?? "";
+  const url = `${baseUrl}${options.path}`;
+
+  const requestHeaders: Record<string, string> = {
+    "X-Internal-Token": token,
+    ...options.headers,
+  };
+
+  if (options.body !== undefined) {
+    requestHeaders["Content-Type"] = "application/json";
+  }
+
+  const response = await fetch(url, {
+    method: options.method,
+    headers: requestHeaders,
+    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+  });
+
+  if (!response.ok) {
+    let responseBody: unknown;
+    try {
+      responseBody = await response.json();
+    } catch {
+      responseBody = await response.text();
+    }
+    throw new SwiteProxyError(
+      response.status,
+      `Python service responded with ${response.status} on ${options.method} ${options.path}`,
+      responseBody,
+    );
+  }
+
+  return response.json() as Promise<T>;
+}