@swissjs/swite 0.3.5 → 0.4.2

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.

package/docs/development/contributing.md

@@ -1,74 +1,74 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Contributing
-
----
-
-## Build
-
-SWITE is compiled from TypeScript to `dist/` using the TypeScript compiler:
-
-```bash
-pnpm build          # single build
-pnpm dev            # watch mode (tsc -b --watch)
-```
-
-The `bin.swite` field in `package.json` points to `dist/cli.js`. After a build, the CLI is runnable as `node dist/cli.js dev` from the package root, or via the `swite` binary when the package is installed.
-
-To clean build artifacts and `node_modules`:
-
-```bash
-pnpm clean
-```
-
----
-
-## Running tests
-
-```bash
-pnpm test
-```
-
-Tests run via Node's built-in test runner (`node --import tsx --test`). Test files live in `__tests__/`. Add new test files with a `.test.ts` extension.
-
----
-
-## Generating an import map
-
-The import map generation CLI is separate from the main build:
-
-```bash
-pnpm generate-import-map
-```
-
-This runs `src/internal/generate-import-map-cli.ts` via `tsx` and writes `.swite/import-map.json` in the current directory. Run this from the project root of an application, not from the SWITE package root.
-
----
-
-## Changesets and releases
-
-SWITE uses `@changesets/cli` for versioning.
-
-```bash
-pnpm changeset              # create a changeset for your changes
-pnpm release:version        # bump versions from pending changesets
-pnpm release:publish        # publish to npm
-```
-
----
-
-## Branch conventions
-
-- Work in feature branches named `feat/<topic>` or `fix/<topic>`.
-- Do not push directly to the default branch.
-- Each PR should include a changeset unless the change is documentation-only.
-
----
-
-## Package scope
-
-SWITE is published as `@swissjs/swite`. The npm registry is `registry.npmjs.org` with `access: public`. The repository is part of the `kibologic/alpine-erp-core` GitHub repo.
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Contributing
+
+---
+
+## Build
+
+SWITE is compiled from TypeScript to `dist/` using the TypeScript compiler:
+
+```bash
+pnpm build          # single build
+pnpm dev            # watch mode (tsc -b --watch)
+```
+
+The `bin.swite` field in `package.json` points to `dist/cli.js`. After a build, the CLI is runnable as `node dist/cli.js dev` from the package root, or via the `swite` binary when the package is installed.
+
+To clean build artifacts and `node_modules`:
+
+```bash
+pnpm clean
+```
+
+---
+
+## Running tests
+
+```bash
+pnpm test
+```
+
+Tests run via Node's built-in test runner (`node --import tsx --test`). Test files live in `__tests__/`. Add new test files with a `.test.ts` extension.
+
+---
+
+## Generating an import map
+
+The import map generation CLI is separate from the main build:
+
+```bash
+pnpm generate-import-map
+```
+
+This runs `src/internal/generate-import-map-cli.ts` via `tsx` and writes `.swite/import-map.json` in the current directory. Run this from the project root of an application, not from the SWITE package root.
+
+---
+
+## Changesets and releases
+
+SWITE uses `@changesets/cli` for versioning.
+
+```bash
+pnpm changeset              # create a changeset for your changes
+pnpm release:version        # bump versions from pending changesets
+pnpm release:publish        # publish to npm
+```
+
+---
+
+## Branch conventions
+
+- Work in feature branches named `feat/<topic>` or `fix/<topic>`.
+- Do not push directly to the default branch.
+- Each PR should include a changeset unless the change is documentation-only.
+
+---
+
+## Package scope
+
+SWITE is published as `@swissjs/swite`. The npm registry is `registry.npmjs.org` with `access: public`. The repository is part of the `kibologic/alpine-erp-core` GitHub repo.

package/docs/development/index.md

@@ -1,12 +1,12 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Development
-
-Notes for contributors and maintainers working on SWITE itself.
-
-- [Contributing](./contributing.md) — local build, running tests, branch conventions
-- [Internals](./internals.md) — workspace root detection algorithm, import map generation, symlink registry, package registry
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Development
+
+Notes for contributors and maintainers working on SWITE itself.
+
+- [Contributing](./contributing.md) — local build, running tests, branch conventions
+- [Internals](./internals.md) — workspace root detection algorithm, import map generation, symlink registry, package registry