@swissjs/swite 0.4.1 → 0.4.2

package/docs/architecture/resolution.md

@@ -1,92 +1,92 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Import Resolution
-
-SWITE resolves every bare module specifier to a browser-accessible URL before serving compiled source. This page describes the full resolution pipeline.
-
----
-
-## ModuleResolver
-
-`ModuleResolver` (`src/resolution/resolver.ts`) is the central resolution object. Each `SwiteServer` creates one instance per app root. It is injected into all file handlers and the import rewriter.
-
-`ModuleResolver.resolve(specifier, importer)` returns a URL string. Specifiers fall into four categories:
-
-1. **Import map hit** — If a pre-generated `.swite/import-map.json` is loaded and the specifier appears in its `imports` map, that URL is returned immediately without further resolution.
-2. **Bare import** — Starts with a letter or `@`. Delegated to `resolveBareImport`.
-3. **Absolute path** — Starts with `/`. Returned as-is.
-4. **Relative import** — Starts with `.`. Resolved relative to the importer's directory on disk, then converted to a URL via `toUrl`.
-
-### Variable reference detection
-
-Before delegating to `resolveBareImport`, the resolver checks whether the specifier looks like a variable reference rather than a module path. Specifiers containing a `.` but not starting with `@` (e.g. `def.componentUrl`) are returned unchanged with a warning. Specifiers that do not match the pattern `^[@a-zA-Z][a-zA-Z0-9_/@-]*(\.(js|ts|ui|uix|mjs|cjs|jsx|tsx))?$` are also returned unchanged.
-
----
-
-## Bare import resolution
-
-`resolveBareImport` (`src/resolution/bare-import-resolver.ts`) resolves a bare specifier by searching for the package's `package.json` in multiple `node_modules` locations:
-
-1. `<appRoot>/node_modules/<pkg>`
-2. `<parentOfAppRoot>/node_modules/<pkg>`
-3. `<workspaceRoot>/node_modules/<pkg>`
-4. `<frameworkMonorepo>/node_modules/<pkg>`
-
-If a `package.json` is found, the resolver reads the `exports` field (preferring the `import` condition), or falls back to `module` then `main`. In development, if the resolved path is inside a `dist/` directory, the resolver attempts to substitute `src/` and `.ts` extension and serves from source.
-
----
-
-## Workspace package resolution
-
-When a package is not found in any `node_modules`, `resolveWorkspacePackage` (`src/resolution/workspace-package-resolver.ts`) is called. It uses `PackageRegistry` (a process-wide singleton) to scan the workspace for `package.json` files. The registry recursively scans up to 15 directory levels deep, skipping `node_modules`, `dist`, `.git`, and `.swite`.
-
-If the package is still not found, the registry calls `rescan()` in case the package was added after the initial scan.
-
----
-
-## toUrl: converting filesystem paths to browser URLs
-
-`toUrl` (`src/resolution/url-resolver.ts`) converts an absolute filesystem path to a browser-relative URL. The resolution order is:
-
-1. **Symlink registry** — Looks up the path in the startup-built registry. If the path (or its `fs.realpath` equivalent) is within a registered symlink target, the corresponding `/node_modules/<pkg>` URL prefix is returned.
-2. **node_modules path** — If the normalized path contains `/node_modules/`, the substring from `/node_modules/` onward is used as the URL.
-3. **Workspace path** — If the path is inside the workspace root, the relative path from the workspace root is used.
-4. **App root path** — If the path is inside the app root, the relative path from the app root is used.
-5. **Framework monorepo packages** — If the path is inside the co-located framework monorepo's `packages/` directory, it is served under `/swiss-packages/`.
-
----
-
-## CDN fallback
-
-`shouldUseCdnFallback` (`src/resolution/cdn/cdn-fallback.ts`) determines whether a package may be redirected to jsDelivr when not found locally:
-
-- Unscoped packages (e.g. `react`, `reflect-metadata`) always allow CDN fallback.
-- Scoped packages (e.g. `@swissjs/core`) do not allow CDN fallback by default, since they may be private.
-- Scoped packages can be opted in by setting `SWITE_CDN_FALLBACK_SCOPES` to a comma-separated list of scopes (e.g. `@types,@tanstack`).
-
-CDN fallback URLs use the form `https://cdn.jsdelivr.net/npm/{pkg}/+esm`, which serves an ESM build.
-
----
-
-## Import map
-
-At dev server startup, `setupMiddleware` attempts to load `.swite/import-map.json`. If it exists, `ModuleResolver.setImportMap()` is called and the import map becomes the fast path for all bare import resolutions.
-
-The import map is generated by `generateImportMap` (`src/internal/generate-import-map.ts`), which:
-
-1. Uses `PackageRegistry` to discover all workspace packages.
-2. Calls `resolver.resolve(pkg.name, "")` for each package.
-3. Also resolves common subpaths: `/components`, `/tokens`, `/context`, `/shell`, `/jsx-runtime`, `/jsx-dev-runtime`.
-4. Saves the result as `{ version, generated, imports: { "@pkg/name": "/url" } }`.
-
-The import map is also injected into `public/index.html` by the SPA fallback handler. If HTML already contains a `<script type="importmap">`, SWITE merges the generated entries in, with existing HTML entries taking priority.
-
----
-
-## Path fixup
-
-`fixSwissLibPaths` (`src/resolution/path/path-fixup.ts`) is applied to every compiled output before import rewriting. It rewrites `/swiss-lib/packages/` to `/swiss-packages/` and `/swiss-lib/` to `/swiss-packages/`. This corrects paths emitted by older versions of `@swissjs/compiler` that referenced a previous directory structure.
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Import Resolution
+
+SWITE resolves every bare module specifier to a browser-accessible URL before serving compiled source. This page describes the full resolution pipeline.
+
+---
+
+## ModuleResolver
+
+`ModuleResolver` (`src/resolution/resolver.ts`) is the central resolution object. Each `SwiteServer` creates one instance per app root. It is injected into all file handlers and the import rewriter.
+
+`ModuleResolver.resolve(specifier, importer)` returns a URL string. Specifiers fall into four categories:
+
+1. **Import map hit** — If a pre-generated `.swite/import-map.json` is loaded and the specifier appears in its `imports` map, that URL is returned immediately without further resolution.
+2. **Bare import** — Starts with a letter or `@`. Delegated to `resolveBareImport`.
+3. **Absolute path** — Starts with `/`. Returned as-is.
+4. **Relative import** — Starts with `.`. Resolved relative to the importer's directory on disk, then converted to a URL via `toUrl`.
+
+### Variable reference detection
+
+Before delegating to `resolveBareImport`, the resolver checks whether the specifier looks like a variable reference rather than a module path. Specifiers containing a `.` but not starting with `@` (e.g. `def.componentUrl`) are returned unchanged with a warning. Specifiers that do not match the pattern `^[@a-zA-Z][a-zA-Z0-9_/@-]*(\.(js|ts|ui|uix|mjs|cjs|jsx|tsx))?$` are also returned unchanged.
+
+---
+
+## Bare import resolution
+
+`resolveBareImport` (`src/resolution/bare-import-resolver.ts`) resolves a bare specifier by searching for the package's `package.json` in multiple `node_modules` locations:
+
+1. `<appRoot>/node_modules/<pkg>`
+2. `<parentOfAppRoot>/node_modules/<pkg>`
+3. `<workspaceRoot>/node_modules/<pkg>`
+4. `<frameworkMonorepo>/node_modules/<pkg>`
+
+If a `package.json` is found, the resolver reads the `exports` field (preferring the `import` condition), or falls back to `module` then `main`. In development, if the resolved path is inside a `dist/` directory, the resolver attempts to substitute `src/` and `.ts` extension and serves from source.
+
+---
+
+## Workspace package resolution
+
+When a package is not found in any `node_modules`, `resolveWorkspacePackage` (`src/resolution/workspace-package-resolver.ts`) is called. It uses `PackageRegistry` (a process-wide singleton) to scan the workspace for `package.json` files. The registry recursively scans up to 15 directory levels deep, skipping `node_modules`, `dist`, `.git`, and `.swite`.
+
+If the package is still not found, the registry calls `rescan()` in case the package was added after the initial scan.
+
+---
+
+## toUrl: converting filesystem paths to browser URLs
+
+`toUrl` (`src/resolution/url-resolver.ts`) converts an absolute filesystem path to a browser-relative URL. The resolution order is:
+
+1. **Symlink registry** — Looks up the path in the startup-built registry. If the path (or its `fs.realpath` equivalent) is within a registered symlink target, the corresponding `/node_modules/<pkg>` URL prefix is returned.
+2. **node_modules path** — If the normalized path contains `/node_modules/`, the substring from `/node_modules/` onward is used as the URL.
+3. **Workspace path** — If the path is inside the workspace root, the relative path from the workspace root is used.
+4. **App root path** — If the path is inside the app root, the relative path from the app root is used.
+5. **Framework monorepo packages** — If the path is inside the co-located framework monorepo's `packages/` directory, it is served under `/swiss-packages/`.
+
+---
+
+## CDN fallback
+
+`shouldUseCdnFallback` (`src/resolution/cdn/cdn-fallback.ts`) determines whether a package may be redirected to jsDelivr when not found locally:
+
+- Unscoped packages (e.g. `react`, `reflect-metadata`) always allow CDN fallback.
+- Scoped packages (e.g. `@swissjs/core`) do not allow CDN fallback by default, since they may be private.
+- Scoped packages can be opted in by setting `SWITE_CDN_FALLBACK_SCOPES` to a comma-separated list of scopes (e.g. `@types,@tanstack`).
+
+CDN fallback URLs use the form `https://cdn.jsdelivr.net/npm/{pkg}/+esm`, which serves an ESM build.
+
+---
+
+## Import map
+
+At dev server startup, `setupMiddleware` attempts to load `.swite/import-map.json`. If it exists, `ModuleResolver.setImportMap()` is called and the import map becomes the fast path for all bare import resolutions.
+
+The import map is generated by `generateImportMap` (`src/internal/generate-import-map.ts`), which:
+
+1. Uses `PackageRegistry` to discover all workspace packages.
+2. Calls `resolver.resolve(pkg.name, "")` for each package.
+3. Also resolves common subpaths: `/components`, `/tokens`, `/context`, `/shell`, `/jsx-runtime`, `/jsx-dev-runtime`.
+4. Saves the result as `{ version, generated, imports: { "@pkg/name": "/url" } }`.
+
+The import map is also injected into `public/index.html` by the SPA fallback handler. If HTML already contains a `<script type="importmap">`, SWITE merges the generated entries in, with existing HTML entries taking priority.
+
+---
+
+## Path fixup
+
+`fixSwissLibPaths` (`src/resolution/path/path-fixup.ts`) is applied to every compiled output before import rewriting. It rewrites `/swiss-lib/packages/` to `/swiss-packages/` and `/swiss-lib/` to `/swiss-packages/`. This corrects paths emitted by older versions of `@swissjs/compiler` that referenced a previous directory structure.

package/docs/cli/build.md

@@ -1,78 +1,78 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# swite build
-
-Compiles the application for production.
-
-```bash
-swite build
-```
-
----
-
-## What it does
-
-`swite build` runs `SwiteBuilder` with a fixed configuration derived from the project root:
-
-| Parameter | Value |
-|-----------|-------|
-| Entry point | `<root>/src/index.ui` |
-| Output directory | `<root>/dist` |
-| Format | ESM |
-| Target | `es2020` |
-| Minify | `true` |
-| Sourcemap | `false` |
-
-These defaults are not yet configurable via `swiss.config.ts`; the builder reads config only for future extensibility.
-
----
-
-## Build pipeline
-
-The build runs in three phases:
-
-### Phase 1: Compile Swiss files
-
-All `.ui` and `.uix` files in `src/` are passed through `@swissjs/compiler` (`UiCompiler.compileAsync`), which outputs TypeScript/JSX. The resulting code is written to a temporary `.swite-build/` directory as `.tsx` files. Plain `.ts` files are copied as-is, with `.ui`/`.uix` import references rewritten to `.tsx`. CSS files are copied verbatim.
-
-Workspace dependencies declared as `workspace:*` in `package.json` are discovered and compiled into the same temp directory, preserving the workspace directory structure so esbuild can resolve cross-package imports.
-
-### Phase 2: Bundle with esbuild
-
-esbuild is invoked with `bundle: true`, targeting the compiled entry point in `.swite-build/`. Three custom plugins are active:
-
-- `js-tsx-fallback` — redirects `.js` import resolutions to `.tsx` when the `.tsx` file exists in the temp directory (handles UiCompiler emitting `.js` references)
-- `css-stub` — stubs all `.css` imports with `export {}` so they do not block the bundle
-- `workspace-resolver` — resolves `@scope/pkg` imports to compiled files in `.swite-build/`, using `package.json` exports fields and falling back to `src/index.js`
-
-Node built-in modules (`fs`, `path`, `os`, etc., including `node:` prefixed forms) are marked external.
-
-### Phase 3: Copy public assets
-
-The contents of `public/` are copied verbatim to `dist/`.
-
----
-
-## Output
-
-`dist/` contains the bundled JavaScript (one or more chunks for ESM splitting), copied public assets, and any CSS files the build chose to emit. The `.swite-build/` temporary directory is removed regardless of whether the build succeeded or failed.
-
-Build stats (file count and sizes) are printed to stdout after a successful bundle.
-
----
-
-## Workspace dependencies
-
-The builder scans `package.json` `dependencies`, `devDependencies`, and `peerDependencies` for `workspace:*` entries and also scans source files for `@scope/pkg` import patterns to discover transitive workspace dependencies. For each discovered package, it looks in these directories under the workspace root (in order):
-
-```
-lib/<pkgName>
-packages/<pkgName>
-packages/runtime/<pkgName>
-packages/plugins/<pkgName>
-packages/domain/<pkgName>
-```
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# swite build
+
+Compiles the application for production.
+
+```bash
+swite build
+```
+
+---
+
+## What it does
+
+`swite build` runs `SwiteBuilder` with a fixed configuration derived from the project root:
+
+| Parameter | Value |
+|-----------|-------|
+| Entry point | `<root>/src/index.ui` |
+| Output directory | `<root>/dist` |
+| Format | ESM |
+| Target | `es2020` |
+| Minify | `true` |
+| Sourcemap | `false` |
+
+These defaults are not yet configurable via `swiss.config.ts`; the builder reads config only for future extensibility.
+
+---
+
+## Build pipeline
+
+The build runs in three phases:
+
+### Phase 1: Compile Swiss files
+
+All `.ui` and `.uix` files in `src/` are passed through `@swissjs/compiler` (`UiCompiler.compileAsync`), which outputs TypeScript/JSX. The resulting code is written to a temporary `.swite-build/` directory as `.tsx` files. Plain `.ts` files are copied as-is, with `.ui`/`.uix` import references rewritten to `.tsx`. CSS files are copied verbatim.
+
+Workspace dependencies declared as `workspace:*` in `package.json` are discovered and compiled into the same temp directory, preserving the workspace directory structure so esbuild can resolve cross-package imports.
+
+### Phase 2: Bundle with esbuild
+
+esbuild is invoked with `bundle: true`, targeting the compiled entry point in `.swite-build/`. Three custom plugins are active:
+
+- `js-tsx-fallback` — redirects `.js` import resolutions to `.tsx` when the `.tsx` file exists in the temp directory (handles UiCompiler emitting `.js` references)
+- `css-stub` — stubs all `.css` imports with `export {}` so they do not block the bundle
+- `workspace-resolver` — resolves `@scope/pkg` imports to compiled files in `.swite-build/`, using `package.json` exports fields and falling back to `src/index.js`
+
+Node built-in modules (`fs`, `path`, `os`, etc., including `node:` prefixed forms) are marked external.
+
+### Phase 3: Copy public assets
+
+The contents of `public/` are copied verbatim to `dist/`.
+
+---
+
+## Output
+
+`dist/` contains the bundled JavaScript (one or more chunks for ESM splitting), copied public assets, and any CSS files the build chose to emit. The `.swite-build/` temporary directory is removed regardless of whether the build succeeded or failed.
+
+Build stats (file count and sizes) are printed to stdout after a successful bundle.
+
+---
+
+## Workspace dependencies
+
+The builder scans `package.json` `dependencies`, `devDependencies`, and `peerDependencies` for `workspace:*` entries and also scans source files for `@scope/pkg` import patterns to discover transitive workspace dependencies. For each discovered package, it looks in these directories under the workspace root (in order):
+
+```
+lib/<pkgName>
+packages/<pkgName>
+packages/runtime/<pkgName>
+packages/plugins/<pkgName>
+packages/domain/<pkgName>
+```

package/docs/cli/dev.md

@@ -1,90 +1,90 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# swite dev
-
-Starts the SWITE development server.
-
-```bash
-swite dev
-```
-
----
-
-## What it does
-
-1. Loads `swiss.config.ts` from the project root via esbuild transpilation.
-2. If `services.python.autoStart` is `true` in the config, spawns the Python process at `python3 {entry}` (or `python` on Windows), passes `PORT={port}` plus any `env` fields, and polls the health endpoint until it responds 200 or the 15-second timeout is reached.
-3. Registers `SIGINT` and `process.exit` handlers to send `SIGTERM` to the Python process when Node shuts down.
-4. Starts `SwiteServer` on the configured port and host, then begins the HMR WebSocket server on port 24678 (or the next available port).
-
----
-
-## Python autostart
-
-When `autoStart: true` is set, the Python process is started before the Node HTTP server. SWITE streams Python stdout prefixed with `[python]` (cyan) and stderr prefixed with `[python]` (yellow). If the health check times out, SWITE kills the Python process and exits with an error.
-
-```typescript
-// swiss.config.ts
-export default defineConfig({
-  services: {
-    python: {
-      entry: 'server/main.py',
-      port: 8000,
-      autoStart: true,
-      healthCheck: '/health',
-      env: { ENVIRONMENT: 'development' },
-    },
-  },
-});
-```
-
----
-
-## HMR
-
-The HMR WebSocket server starts on port 24678. If that port is occupied, SWITE probes the OS for the next free port. The actual port is embedded into the HMR client script served at `/__swite_hmr_client`.
-
-Every `.ui`, `.uix`, `.ts`, and `.js` file under the project root is watched by chokidar (excluding `node_modules/`, `.git/`, and `dist/`). When a file changes, SWITE broadcasts a JSON message to all connected WebSocket clients:
-
-```json
-{ "type": "update", "path": "/abs/path/to/file", "updateType": "hot|reload|style", "timestamp": 1234567890 }
-```
-
-Update type classification:
-
-| Update type | Condition |
-|-------------|-----------|
-| `style`     | `.css`, `.scss`, or `.sass` file |
-| `hot`       | `.js` or `.ts` file under `components/` or `pages/` |
-| `reload`    | everything else |
-
-The browser client handles `style` by cache-busting stylesheet `href` attributes. It handles `hot` by re-importing the module and calling `instance.update()` on registered instances. Everything else triggers `window.location.reload()`.
-
----
-
-## Development headers
-
-All compiled source files are served with aggressive no-cache headers:
-
-```
-Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
-Pragma: no-cache
-Expires: 0
-```
-
-This prevents browsers from serving stale compiled output between reloads.
-
----
-
-## Diagnostic endpoints
-
-| Endpoint | Description |
-|----------|-------------|
-| `/__swite_hmr_client` | HMR client JavaScript (injected by index.html) |
-| `/__swite_routes` | JSON array of route definitions from the file router |
-| `/__swite_diagnose?url=<path>` | Fetches the given path and reports bare imports found in the response |
-| `/__swite_clear_cache` | HTML page that clears browser caches and service workers, then redirects to `/` |
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# swite dev
+
+Starts the SWITE development server.
+
+```bash
+swite dev
+```
+
+---
+
+## What it does
+
+1. Loads `swiss.config.ts` from the project root via esbuild transpilation.
+2. If `services.python.autoStart` is `true` in the config, spawns the Python process at `python3 {entry}` (or `python` on Windows), passes `PORT={port}` plus any `env` fields, and polls the health endpoint until it responds 200 or the 15-second timeout is reached.
+3. Registers `SIGINT` and `process.exit` handlers to send `SIGTERM` to the Python process when Node shuts down.
+4. Starts `SwiteServer` on the configured port and host, then begins the HMR WebSocket server on port 24678 (or the next available port).
+
+---
+
+## Python autostart
+
+When `autoStart: true` is set, the Python process is started before the Node HTTP server. SWITE streams Python stdout prefixed with `[python]` (cyan) and stderr prefixed with `[python]` (yellow). If the health check times out, SWITE kills the Python process and exits with an error.
+
+```typescript
+// swiss.config.ts
+export default defineConfig({
+  services: {
+    python: {
+      entry: 'server/main.py',
+      port: 8000,
+      autoStart: true,
+      healthCheck: '/health',
+      env: { ENVIRONMENT: 'development' },
+    },
+  },
+});
+```
+
+---
+
+## HMR
+
+The HMR WebSocket server starts on port 24678. If that port is occupied, SWITE probes the OS for the next free port. The actual port is embedded into the HMR client script served at `/__swite_hmr_client`.
+
+Every `.ui`, `.uix`, `.ts`, and `.js` file under the project root is watched by chokidar (excluding `node_modules/`, `.git/`, and `dist/`). When a file changes, SWITE broadcasts a JSON message to all connected WebSocket clients:
+
+```json
+{ "type": "update", "path": "/abs/path/to/file", "updateType": "hot|reload|style", "timestamp": 1234567890 }
+```
+
+Update type classification:
+
+| Update type | Condition |
+|-------------|-----------|
+| `style`     | `.css`, `.scss`, or `.sass` file |
+| `hot`       | `.js` or `.ts` file under `components/` or `pages/` |
+| `reload`    | everything else |
+
+The browser client handles `style` by cache-busting stylesheet `href` attributes. It handles `hot` by re-importing the module and calling `instance.update()` on registered instances. Everything else triggers `window.location.reload()`.
+
+---
+
+## Development headers
+
+All compiled source files are served with aggressive no-cache headers:
+
+```
+Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
+Pragma: no-cache
+Expires: 0
+```
+
+This prevents browsers from serving stale compiled output between reloads.
+
+---
+
+## Diagnostic endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/__swite_hmr_client` | HMR client JavaScript (injected by index.html) |
+| `/__swite_routes` | JSON array of route definitions from the file router |
+| `/__swite_diagnose?url=<path>` | Fetches the given path and reports bare imports found in the response |
+| `/__swite_clear_cache` | HTML page that clears browser caches and service workers, then redirects to `/` |

package/docs/cli/index.md

@@ -1,15 +1,15 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# CLI
-
-SWITE is invoked as `swite <command>`. There are three commands:
-
-- [swite dev](./dev.md) — Start the development server with HMR and optional Python autostart
-- [swite build](./build.md) — Build the application for production using esbuild
-- [swite start](./start.md) — Start the development server in production mode (no HMR, no Python autostart)
-
-All three commands read `swiss.config.ts` (or `swiss.config.js`) from the current working directory before doing anything else. The current working directory is the project root; SWITE does not accept a path argument.
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# CLI
+
+SWITE is invoked as `swite <command>`. There are three commands:
+
+- [swite dev](./dev.md) — Start the development server with HMR and optional Python autostart
+- [swite build](./build.md) — Build the application for production using esbuild
+- [swite start](./start.md) — Start the development server in production mode (no HMR, no Python autostart)
+
+All three commands read `swiss.config.ts` (or `swiss.config.js`) from the current working directory before doing anything else. The current working directory is the project root; SWITE does not accept a path argument.

package/docs/cli/start.md

@@ -1,45 +1,45 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# swite start
-
-Starts the SWITE server in production mode.
-
-```bash
-swite start
-```
-
----
-
-## What it does
-
-`swite start` starts the same `SwiteServer` as `swite dev` but with one critical difference: it calls `setProductionMode()` before the server starts. Production mode changes how `proxyToPython` resolves the Python service URL:
-
-- **Dev mode**: if `PYTHON_SERVICE_URL` is not set, `proxyToPython` falls back to `http://localhost:{python.port}` from the config.
-- **Production mode**: if `PYTHON_SERVICE_URL` is not set, `proxyToPython` throws immediately with an error rather than attempting a localhost connection.
-
-`swite start` does not spawn the Python process. It does not start HMR. The HMR WebSocket server is still initialized (as part of `SwiteServer`), but since no file watcher is started and the client script is still served, the client will connect and wait — which is harmless in a production container.
-
----
-
-## PYTHON_SERVICE_URL warning
-
-If `services.python` is configured in `swiss.config.ts` and `PYTHON_SERVICE_URL` is not set in the environment at startup, SWITE prints a warning:
-
-```
-[swite] WARNING: services.python is configured but PYTHON_SERVICE_URL is not set.
-        Proxy calls to Python will fail. Set PYTHON_SERVICE_URL to the running service URL.
-```
-
-The server starts regardless. The warning is there because proxy calls that happen before `PYTHON_SERVICE_URL` is set will throw at request time.
-
----
-
-## Production deployment notes
-
-`swite start` serves source files through the same compilation and import-rewriting middleware as `swite dev`. It is not a static file server for pre-built output. If you want to serve the output of `swite build`, use a regular static HTTP server pointed at `dist/`.
-
-`swite start` is intended for fullstack deployments where the Node server handles server-side logic and proxies to a separately deployed Python service, while continuing to serve the SwissJS frontend from source.
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# swite start
+
+Starts the SWITE server in production mode.
+
+```bash
+swite start
+```
+
+---
+
+## What it does
+
+`swite start` starts the same `SwiteServer` as `swite dev` but with one critical difference: it calls `setProductionMode()` before the server starts. Production mode changes how `proxyToPython` resolves the Python service URL:
+
+- **Dev mode**: if `PYTHON_SERVICE_URL` is not set, `proxyToPython` falls back to `http://localhost:{python.port}` from the config.
+- **Production mode**: if `PYTHON_SERVICE_URL` is not set, `proxyToPython` throws immediately with an error rather than attempting a localhost connection.
+
+`swite start` does not spawn the Python process. It does not start HMR. The HMR WebSocket server is still initialized (as part of `SwiteServer`), but since no file watcher is started and the client script is still served, the client will connect and wait — which is harmless in a production container.
+
+---
+
+## PYTHON_SERVICE_URL warning
+
+If `services.python` is configured in `swiss.config.ts` and `PYTHON_SERVICE_URL` is not set in the environment at startup, SWITE prints a warning:
+
+```
+[swite] WARNING: services.python is configured but PYTHON_SERVICE_URL is not set.
+        Proxy calls to Python will fail. Set PYTHON_SERVICE_URL to the running service URL.
+```
+
+The server starts regardless. The warning is there because proxy calls that happen before `PYTHON_SERVICE_URL` is set will throw at request time.
+
+---
+
+## Production deployment notes
+
+`swite start` serves source files through the same compilation and import-rewriting middleware as `swite dev`. It is not a static file server for pre-built output. If you want to serve the output of `swite build`, use a regular static HTTP server pointed at `dist/`.
+
+`swite start` is intended for fullstack deployments where the Node server handles server-side logic and proxies to a separately deployed Python service, while continuing to serve the SwissJS frontend from source.