@swissjs/swite 0.4.1 → 0.4.2

package/docs/architecture/hmr.md

@@ -1,78 +1,78 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# HMR
-
-`HMREngine` (`src/dev-engine/hmr/hmr.ts`) manages the WebSocket server and file watcher that power hot module replacement.
-
----
-
-## WebSocket server
-
-The WebSocket server is created by the `ws` package. The default port is 24678. On initialization, SWITE checks whether that port is available by attempting to bind a temporary TCP server. If the port is occupied, `findFreePort()` asks the OS for an available port by binding to port 0 and reading the assigned port back.
-
-All connected browser clients are tracked in a `Set<WebSocket>`. When a client disconnects, it is removed from the set.
-
-The HMR client script is served at `/__swite_hmr_client` as plain JavaScript. The actual WebSocket port is embedded into this script at server startup so the browser client connects to the correct port even when it differs from 24678.
-
----
-
-## File watcher
-
-`HMREngine.start()` creates a chokidar watcher on the project root with these options:
-
-- Ignored: `node_modules/`, `.git/`, `dist/`
-- `ignoreInitial: true` — no events are fired for files that exist at startup
-- `awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 100 }` — waits for the file to stop changing before firing, which prevents partial-write events
-
-On each `change` event, SWITE determines the update type from the file extension and broadcasts a message to all connected clients.
-
----
-
-## Update type classification
-
-| File extension | Update type | Browser action |
-|---------------|-------------|----------------|
-| `.css`, `.scss`, `.sass` | `style` | Cache-busts `href` on all `<link rel="stylesheet">` elements by appending `?t={timestamp}` |
-| `.js`, `.ts` in `components/` or `pages/` | `hot` | Re-imports the module and calls `instance.update(newModule)` on registered component instances |
-| Everything else | `reload` | `window.location.reload()` |
-
----
-
-## Broadcast message format
-
-```json
-{
-  "type": "update",
-  "path": "/absolute/path/to/changed/file",
-  "updateType": "hot | reload | style",
-  "timestamp": 1716211234567
-}
-```
-
-Messages are sent only to clients whose `readyState` is `WebSocket.OPEN`. Clients in any other state are skipped.
-
----
-
-## HMR client
-
-`buildHmrClientScript(port)` (`src/dev-engine/hmr/hmr-client-template.ts`) returns the browser-side JavaScript as a string with the port number substituted at runtime.
-
-The client:
-
-1. Opens a WebSocket connection to `ws://{hostname}:{port}`.
-2. On `message`, dispatches to `updateStyles()`, the hot-update path, or `window.location.reload()`.
-3. Maintains a `moduleGraph` map (module name → dependents) and a `hotModules` map (module name → module object) for the hot path.
-4. On hot update: removes the module from `window.__swiss_modules__`, re-imports it with a cache-busting `?t={timestamp}` suffix, and calls `instance.update(newModule)` on each registered instance in `window.__swiss_instances__`.
-5. If the hot update throws, falls back to `window.location.reload()`.
-
-`window.__swiss_modules__` and `window.__swiss_instances__` are initialized to empty objects if not already present. The SwissJS runtime populates `__swiss_instances__` with component instance arrays keyed by component name.
-
----
-
-## notifyChange
-
-`HMREngine.notifyChange(filePath)` is a programmatic interface for triggering HMR broadcasts without a file system event. It is available for use by other server-side logic (such as the file router) that needs to signal a module change.
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# HMR
+
+`HMREngine` (`src/dev-engine/hmr/hmr.ts`) manages the WebSocket server and file watcher that power hot module replacement.
+
+---
+
+## WebSocket server
+
+The WebSocket server is created by the `ws` package. The default port is 24678. On initialization, SWITE checks whether that port is available by attempting to bind a temporary TCP server. If the port is occupied, `findFreePort()` asks the OS for an available port by binding to port 0 and reading the assigned port back.
+
+All connected browser clients are tracked in a `Set<WebSocket>`. When a client disconnects, it is removed from the set.
+
+The HMR client script is served at `/__swite_hmr_client` as plain JavaScript. The actual WebSocket port is embedded into this script at server startup so the browser client connects to the correct port even when it differs from 24678.
+
+---
+
+## File watcher
+
+`HMREngine.start()` creates a chokidar watcher on the project root with these options:
+
+- Ignored: `node_modules/`, `.git/`, `dist/`
+- `ignoreInitial: true` — no events are fired for files that exist at startup
+- `awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 100 }` — waits for the file to stop changing before firing, which prevents partial-write events
+
+On each `change` event, SWITE determines the update type from the file extension and broadcasts a message to all connected clients.
+
+---
+
+## Update type classification
+
+| File extension | Update type | Browser action |
+|---------------|-------------|----------------|
+| `.css`, `.scss`, `.sass` | `style` | Cache-busts `href` on all `<link rel="stylesheet">` elements by appending `?t={timestamp}` |
+| `.js`, `.ts` in `components/` or `pages/` | `hot` | Re-imports the module and calls `instance.update(newModule)` on registered component instances |
+| Everything else | `reload` | `window.location.reload()` |
+
+---
+
+## Broadcast message format
+
+```json
+{
+  "type": "update",
+  "path": "/absolute/path/to/changed/file",
+  "updateType": "hot | reload | style",
+  "timestamp": 1716211234567
+}
+```
+
+Messages are sent only to clients whose `readyState` is `WebSocket.OPEN`. Clients in any other state are skipped.
+
+---
+
+## HMR client
+
+`buildHmrClientScript(port)` (`src/dev-engine/hmr/hmr-client-template.ts`) returns the browser-side JavaScript as a string with the port number substituted at runtime.
+
+The client:
+
+1. Opens a WebSocket connection to `ws://{hostname}:{port}`.
+2. On `message`, dispatches to `updateStyles()`, the hot-update path, or `window.location.reload()`.
+3. Maintains a `moduleGraph` map (module name → dependents) and a `hotModules` map (module name → module object) for the hot path.
+4. On hot update: removes the module from `window.__swiss_modules__`, re-imports it with a cache-busting `?t={timestamp}` suffix, and calls `instance.update(newModule)` on each registered instance in `window.__swiss_instances__`.
+5. If the hot update throws, falls back to `window.location.reload()`.
+
+`window.__swiss_modules__` and `window.__swiss_instances__` are initialized to empty objects if not already present. The SwissJS runtime populates `__swiss_instances__` with component instance arrays keyed by component name.
+
+---
+
+## notifyChange
+
+`HMREngine.notifyChange(filePath)` is a programmatic interface for triggering HMR broadcasts without a file system event. It is available for use by other server-side logic (such as the file router) that needs to signal a module change.

package/docs/architecture/import-rewriting.md

@@ -1,101 +1,101 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Import Rewriting
-
-The browser cannot fetch bare module specifiers like `@swissjs/core` or `react`. SWITE rewrites every bare import in compiled source to an absolute browser URL before serving.
-
----
-
-## How it works
-
-`rewriteImports` (`src/resolution/rewriting/import-rewriter.ts`) is called by every file handler after compilation. It uses `es-module-lexer` to find all imports in the code, then applies a collect-and-replace strategy:
-
-1. Parse the code with `es-module-lexer` to get the position of every import specifier.
-2. For each specifier, determine the quoted span in the original string (including the surrounding quote characters).
-3. Collect each replacement as `{ start, end, text }` in original-string coordinates.
-4. Sort replacements by descending start position.
-5. Apply replacements right-to-left, so that each substitution does not shift the positions of specifiers to its left.
-
-This approach eliminates the offset-tracking errors that arise when applying replacements left-to-right.
-
----
-
-## What is rewritten
-
-Only bare module specifiers (those not starting with `.` or `/`) are passed to `ModuleResolver.resolve`. Relative and absolute path imports are left unchanged.
-
-CSS imports are skipped entirely — they are not ES modules.
-
----
-
-## Variable references are not rewritten
-
-SWITE only rewrites **string literal** specifiers. Variable references in dynamic imports are left unchanged.
-
-```javascript
-// This WILL be rewritten — string literal
-const mod = await import('@swissjs/router');
-
-// This will NOT be rewritten — variable reference
-const mod = await import(def.componentUrl);
-```
-
-`es-module-lexer` identifies only string literals in import positions. Variable references do not appear as import specifiers in the lexer output.
-
-`ModuleResolver.resolve` also guards against variable-like specifiers: a specifier containing `.` but not starting with `@` (e.g. `def.componentUrl`) is returned unchanged with a warning log rather than being resolved as a module path.
-
-### Required pattern for runtime-determined paths
-
-When the import target is a runtime value, assign it to a simple local variable first:
-
-```typescript
-// Correct
-const url = def.componentUrl;
-const mod = await import(url);
-
-// Avoid — property access may pass the lexer differently across compiler versions
-const mod = await import(def.componentUrl);
-```
-
----
-
-## Extension fixup
-
-The `@swissjs/compiler` occasionally emits `.js` or `.tsx` extensions in relative import paths for files that exist on disk as `.ui` or `.uix`. Before collecting replacements, `rewriteImports` checks each relative import ending in `.js` or `.tsx`: if the corresponding `.ui` or `.uix` file exists on disk, the extension is corrected.
-
-The correction depends on the importer context:
-
-- If the importer is a file in `swiss-packages/` or `lib/`, the extension is rewritten to `.ts`.
-- If the importer is a `.ui` or `.uix` file, the extension is rewritten to `.ui` or `.uix` based on which file exists on disk.
-- Otherwise `.ts`.
-
-A regex fallback pass applies the same logic for any `.js`/`.tsx` relative imports the lexer may have missed.
-
----
-
-## Safety net
-
-After the primary lexer pass, `rewriteImports` scans the result with a regex for any remaining bare scoped imports (`@scope/pkg/…`). If any are found, they are rewritten using the CDN fallback or `/node_modules/` URL. This catches cases where the lexer silently failed to parse a particular import form.
-
----
-
-## Debugging bare imports
-
-If compiled output still contains bare imports after rewriting, SWITE logs:
-
-```
-[SWITE] import-rewriter: CRITICAL — bare import "@scope/pkg" still present after rewriting
-```
-
-Each handler also checks its final output and logs any remaining bare imports:
-
-```
-[.ui] Bare imports still present after rewriting: /src/MyComponent.ui
-[.ui] Unresolved import: @scope/pkg
-```
-
-The `/__swite_diagnose?url=<path>` endpoint fetches any URL the server serves and reports whether bare imports are present in the response, along with the first ten import specifiers found.
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Import Rewriting
+
+The browser cannot fetch bare module specifiers like `@swissjs/core` or `react`. SWITE rewrites every bare import in compiled source to an absolute browser URL before serving.
+
+---
+
+## How it works
+
+`rewriteImports` (`src/resolution/rewriting/import-rewriter.ts`) is called by every file handler after compilation. It uses `es-module-lexer` to find all imports in the code, then applies a collect-and-replace strategy:
+
+1. Parse the code with `es-module-lexer` to get the position of every import specifier.
+2. For each specifier, determine the quoted span in the original string (including the surrounding quote characters).
+3. Collect each replacement as `{ start, end, text }` in original-string coordinates.
+4. Sort replacements by descending start position.
+5. Apply replacements right-to-left, so that each substitution does not shift the positions of specifiers to its left.
+
+This approach eliminates the offset-tracking errors that arise when applying replacements left-to-right.
+
+---
+
+## What is rewritten
+
+Only bare module specifiers (those not starting with `.` or `/`) are passed to `ModuleResolver.resolve`. Relative and absolute path imports are left unchanged.
+
+CSS imports are skipped entirely — they are not ES modules.
+
+---
+
+## Variable references are not rewritten
+
+SWITE only rewrites **string literal** specifiers. Variable references in dynamic imports are left unchanged.
+
+```javascript
+// This WILL be rewritten — string literal
+const mod = await import('@swissjs/router');
+
+// This will NOT be rewritten — variable reference
+const mod = await import(def.componentUrl);
+```
+
+`es-module-lexer` identifies only string literals in import positions. Variable references do not appear as import specifiers in the lexer output.
+
+`ModuleResolver.resolve` also guards against variable-like specifiers: a specifier containing `.` but not starting with `@` (e.g. `def.componentUrl`) is returned unchanged with a warning log rather than being resolved as a module path.
+
+### Required pattern for runtime-determined paths
+
+When the import target is a runtime value, assign it to a simple local variable first:
+
+```typescript
+// Correct
+const url = def.componentUrl;
+const mod = await import(url);
+
+// Avoid — property access may pass the lexer differently across compiler versions
+const mod = await import(def.componentUrl);
+```
+
+---
+
+## Extension fixup
+
+The `@swissjs/compiler` occasionally emits `.js` or `.tsx` extensions in relative import paths for files that exist on disk as `.ui` or `.uix`. Before collecting replacements, `rewriteImports` checks each relative import ending in `.js` or `.tsx`: if the corresponding `.ui` or `.uix` file exists on disk, the extension is corrected.
+
+The correction depends on the importer context:
+
+- If the importer is a file in `swiss-packages/` or `lib/`, the extension is rewritten to `.ts`.
+- If the importer is a `.ui` or `.uix` file, the extension is rewritten to `.ui` or `.uix` based on which file exists on disk.
+- Otherwise `.ts`.
+
+A regex fallback pass applies the same logic for any `.js`/`.tsx` relative imports the lexer may have missed.
+
+---
+
+## Safety net
+
+After the primary lexer pass, `rewriteImports` scans the result with a regex for any remaining bare scoped imports (`@scope/pkg/…`). If any are found, they are rewritten using the CDN fallback or `/node_modules/` URL. This catches cases where the lexer silently failed to parse a particular import form.
+
+---
+
+## Debugging bare imports
+
+If compiled output still contains bare imports after rewriting, SWITE logs:
+
+```
+[SWITE] import-rewriter: CRITICAL — bare import "@scope/pkg" still present after rewriting
+```
+
+Each handler also checks its final output and logs any remaining bare imports:
+
+```
+[.ui] Bare imports still present after rewriting: /src/MyComponent.ui
+[.ui] Unresolved import: @scope/pkg
+```
+
+The `/__swite_diagnose?url=<path>` endpoint fetches any URL the server serves and reports whether bare imports are present in the response, along with the first ten import specifiers found.

package/docs/architecture/index.md

@@ -1,16 +1,16 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Architecture
-
-Internal design of SWITE.
-
-- [Dev server](./dev-server.md) — SwiteServer, workspace root detection, middleware chain, file handlers
-- [Import resolution](./resolution.md) — ModuleResolver, bare-import resolution, workspace packages, CDN fallback, import map
-- [Import rewriting](./import-rewriting.md) — how module specifiers in compiled output are rewritten to browser URLs
-- [Build pipeline](./build-pipeline.md) — SwiteBuilder, esbuild integration, `.ui`/`.uix` compilation
-- [HMR](./hmr.md) — WebSocket server, chokidar watcher, client injection, file-change-to-reload flow
-- [Python integration](./python-integration.md) — Python service lifecycle, health polling, proxy adapter, production mode
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Architecture
+
+Internal design of SWITE.
+
+- [Dev server](./dev-server.md) — SwiteServer, workspace root detection, middleware chain, file handlers
+- [Import resolution](./resolution.md) — ModuleResolver, bare-import resolution, workspace packages, CDN fallback, import map
+- [Import rewriting](./import-rewriting.md) — how module specifiers in compiled output are rewritten to browser URLs
+- [Build pipeline](./build-pipeline.md) — SwiteBuilder, esbuild integration, `.ui`/`.uix` compilation
+- [HMR](./hmr.md) — WebSocket server, chokidar watcher, client injection, file-change-to-reload flow
+- [Python integration](./python-integration.md) — Python service lifecycle, health polling, proxy adapter, production mode

package/docs/architecture/python-integration.md

@@ -1,93 +1,93 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Python Integration
-
-SWITE supports a co-located Python backend service. The integration has two parts: lifecycle management during development and a proxy adapter used by application code to forward requests.
-
----
-
-## Dev lifecycle
-
-`startPythonDevService(config, projectRoot)` (`src/dev-engine/pythonDevManager.ts`) is called by `swite dev` when `services.python.autoStart` is `true`.
-
-### Process spawning
-
-```
-python3 {config.entry}     (python on Windows)
-```
-
-The process is spawned with:
-- `stdio: ['ignore', 'pipe', 'pipe']` — stdin is closed; stdout and stderr are piped
-- Environment: current process environment merged with `config.env`, plus `PORT={config.port}`
-
-Stdout and stderr are read line-buffered and printed to Node's stdout with `[python]` prefixes.
-
-### Health polling
-
-After spawning, `pollHealth(url)` polls `http://localhost:{port}{config.healthCheck}` every 500 ms. The request uses a 1-second `AbortSignal` timeout per attempt. When the response is `ok`, polling stops and the Node server proceeds.
-
-After five attempts the poll interval grows exponentially (doubling with each attempt) up to a maximum of 3 seconds per attempt. The total deadline is 15 seconds. If the deadline passes, SWITE calls `stopPythonDevService()` and throws.
-
-### Shutdown
-
-`stopPythonDevService()` sends `SIGTERM` to the child process. It is registered on both `SIGINT` (Ctrl-C) and the Node `exit` event so the Python process is always cleaned up.
-
----
-
-## initPythonProxy
-
-`initPythonProxy(config)` stores the `PythonServiceConfig` in module-level state. It is called immediately after `startPythonDevService` resolves, so `proxyToPython` can derive the base URL from the config's port before `PYTHON_SERVICE_URL` is set.
-
----
-
-## proxyToPython
-
-`proxyToPython<T>(options)` (`src/adapters/proxy/proxyToPython.ts`) is the adapter application code uses to forward requests to the Python service.
-
-### Base URL resolution
-
-| Condition | Base URL |
-|-----------|----------|
-| `PYTHON_SERVICE_URL` env var is set | `PYTHON_SERVICE_URL` (trailing slash stripped) |
-| Not set, dev mode, config initialized | `http://localhost:{config.port}` |
-| Not set, production mode | throws immediately |
-
-### Request
-
-Every call injects the `X-Internal-Token` header with the value of `INTERNAL_API_TOKEN` (empty string if not set). When `options.body` is provided, `Content-Type: application/json` is added and the body is serialized with `JSON.stringify`.
-
-Non-2xx responses throw `SwiteProxyError` with the HTTP status, a description, and the parsed response body.
-
-### Options
-
-```typescript
-interface ProxyOptions {
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  path: string;       // e.g. '/api/orders'
-  body?: unknown;     // JSON-serializable
-  headers?: Record<string, string>;
-}
-```
-
----
-
-## Production mode
-
-`setProductionMode()` is called by `swite start` before the server starts. In production mode:
-
-- The localhost fallback is disabled. If `PYTHON_SERVICE_URL` is not set, `proxyToPython` throws `"PYTHON_SERVICE_URL is required in production mode but is not set."` rather than attempting a localhost connection.
-- The Python process is never spawned. The `services.python` config is read only to emit the startup warning if `PYTHON_SERVICE_URL` is absent.
-
----
-
-## Environment variable summary
-
-| Variable | Used by | Description |
-|----------|---------|-------------|
-| `PYTHON_SERVICE_URL` | `proxyToPython` | Base URL of the Python service. Required in production. Overrides localhost fallback in dev. |
-| `INTERNAL_API_TOKEN` | `proxyToPython` | Value of the `X-Internal-Token` header on every proxy request |
-| `PORT` | Python process | Set automatically to `config.port` by SWITE when spawning the Python process |
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Python Integration
+
+SWITE supports a co-located Python backend service. The integration has two parts: lifecycle management during development and a proxy adapter used by application code to forward requests.
+
+---
+
+## Dev lifecycle
+
+`startPythonDevService(config, projectRoot)` (`src/dev-engine/pythonDevManager.ts`) is called by `swite dev` when `services.python.autoStart` is `true`.
+
+### Process spawning
+
+```
+python3 {config.entry}     (python on Windows)
+```
+
+The process is spawned with:
+- `stdio: ['ignore', 'pipe', 'pipe']` — stdin is closed; stdout and stderr are piped
+- Environment: current process environment merged with `config.env`, plus `PORT={config.port}`
+
+Stdout and stderr are read line-buffered and printed to Node's stdout with `[python]` prefixes.
+
+### Health polling
+
+After spawning, `pollHealth(url)` polls `http://localhost:{port}{config.healthCheck}` every 500 ms. The request uses a 1-second `AbortSignal` timeout per attempt. When the response is `ok`, polling stops and the Node server proceeds.
+
+After five attempts the poll interval grows exponentially (doubling with each attempt) up to a maximum of 3 seconds per attempt. The total deadline is 15 seconds. If the deadline passes, SWITE calls `stopPythonDevService()` and throws.
+
+### Shutdown
+
+`stopPythonDevService()` sends `SIGTERM` to the child process. It is registered on both `SIGINT` (Ctrl-C) and the Node `exit` event so the Python process is always cleaned up.
+
+---
+
+## initPythonProxy
+
+`initPythonProxy(config)` stores the `PythonServiceConfig` in module-level state. It is called immediately after `startPythonDevService` resolves, so `proxyToPython` can derive the base URL from the config's port before `PYTHON_SERVICE_URL` is set.
+
+---
+
+## proxyToPython
+
+`proxyToPython<T>(options)` (`src/adapters/proxy/proxyToPython.ts`) is the adapter application code uses to forward requests to the Python service.
+
+### Base URL resolution
+
+| Condition | Base URL |
+|-----------|----------|
+| `PYTHON_SERVICE_URL` env var is set | `PYTHON_SERVICE_URL` (trailing slash stripped) |
+| Not set, dev mode, config initialized | `http://localhost:{config.port}` |
+| Not set, production mode | throws immediately |
+
+### Request
+
+Every call injects the `X-Internal-Token` header with the value of `INTERNAL_API_TOKEN` (empty string if not set). When `options.body` is provided, `Content-Type: application/json` is added and the body is serialized with `JSON.stringify`.
+
+Non-2xx responses throw `SwiteProxyError` with the HTTP status, a description, and the parsed response body.
+
+### Options
+
+```typescript
+interface ProxyOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;       // e.g. '/api/orders'
+  body?: unknown;     // JSON-serializable
+  headers?: Record<string, string>;
+}
+```
+
+---
+
+## Production mode
+
+`setProductionMode()` is called by `swite start` before the server starts. In production mode:
+
+- The localhost fallback is disabled. If `PYTHON_SERVICE_URL` is not set, `proxyToPython` throws `"PYTHON_SERVICE_URL is required in production mode but is not set."` rather than attempting a localhost connection.
+- The Python process is never spawned. The `services.python` config is read only to emit the startup warning if `PYTHON_SERVICE_URL` is absent.
+
+---
+
+## Environment variable summary
+
+| Variable | Used by | Description |
+|----------|---------|-------------|
+| `PYTHON_SERVICE_URL` | `proxyToPython` | Base URL of the Python service. Required in production. Overrides localhost fallback in dev. |
+| `INTERNAL_API_TOKEN` | `proxyToPython` | Value of the `X-Internal-Token` header on every proxy request |
+| `PORT` | Python process | Set automatically to `config.port` by SWITE when spawning the Python process |