@swissjs/swite 0.4.1 → 0.4.2

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

package/docs/development/internals.md

@@ -1,101 +1,101 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Internals
-
-Implementation notes for the non-obvious parts of SWITE.
-
----
-
-## Workspace root detection algorithm
-
-Two separate implementations exist: one in `SwiteServer` (used at server startup) and one in `src/kernel/workspace.ts` (used by handlers and resolution code at request time). They are slightly different.
-
-### SwiteServer.findWorkspaceRoot
-
-Walks up to six directory levels from `startDir`. At each level it looks for:
-1. A `pnpm-workspace.yaml` file, or
-2. A `package.json` with a `workspaces` field
-
-The first directory matching either condition is returned. `SwiteConfig.rootDir` short-circuits this search if set.
-
-### kernel/workspace.findWorkspaceRoot
-
-Walks up to ten directory levels from `root`. At each level it additionally requires the candidate directory to have either a `lib/` or `packages/` subdirectory alongside the workspace marker file. This stricter check ensures the resolved workspace root is the SWS root (the monorepo that owns the `lib/` directory with compiled packages), not an intermediate workspace.
-
-If a directory has `pnpm-workspace.yaml` but no `lib/` or `packages/`, the walk continues upward. This handles nested monorepo layouts where an inner workspace exists inside an outer SWS root.
-
-### file-path-resolver /lib/ path resolution
-
-For `/lib/` URLs specifically, `resolveFilePath` walks from the app root upward looking for a directory that has both `pnpm-workspace.yaml` and a `lib/` subdirectory present simultaneously. This is the most precise check and handles the case where `findWorkspaceRoot` returns an intermediate directory.
-
----
-
-## Import map generation
-
-`generateImportMap` (`src/internal/generate-import-map.ts`) runs at the request of the CLI or the `generate-import-map` script, not automatically at dev server startup.
-
-The generated file format:
-
-```json
-{
-  "version": "1.0",
-  "generated": 1716211234567,
-  "imports": {
-    "@scope/pkg": "/swiss-packages/pkg/src/index.ts",
-    "@scope/pkg/components": "/swiss-packages/pkg/src/components/index.ts"
-  }
-}
-```
-
-At dev server startup, `setupMiddleware` calls `loadImportMap` to read this file. If found, it is passed to `ModuleResolver.setImportMap()` and becomes the fast path for all bare import resolutions. A cache miss falls through to the full `resolveBareImport` pipeline.
-
-The SPA fallback handler also reads this file directly and merges it into the HTML importmap.
-
----
-
-## Symlink registry
-
-`buildSymlinkRegistry` (`src/resolution/symlink-registry.ts`) is called once during server startup. It scans up to four `node_modules` directories:
-
-1. `<appRoot>/node_modules`
-2. `<parentOfAppRoot>/node_modules`
-3. `<workspaceRoot>/node_modules`
-4. `<frameworkMonorepoRoot>/node_modules`
-
-For each directory, it reads all entries. For scoped entries (starting with `@`), it recurses one level and registers each symlink found there. For unscoped entries, it registers each symlink directly.
-
-Registration: `fs.realpath(symlinkPath)` is resolved and stored in a `Map<string, string>` as `realpath → /node_modules/<pkgName>`.
-
-`lookupInSymlinkRegistry(absolutePath)` iterates the map and returns the browser URL if the path starts with any registered realpath. This is called by `toUrl` as the very first step when an absolute path is received.
-
-The registry is consulted before any other logic in `toUrl` because `fs.realpath()` is called throughout the handler chain (in `resolveFilePath` for `/node_modules/` URLs, in `NodeModuleHandler`, and elsewhere) and the resulting absolute paths would otherwise bypass all the workspace-relative URL conversion logic.
-
----
-
-## Package registry
-
-`PackageRegistry` (`src/kernel/package-registry.ts`) is a process-wide singleton. It is first populated when `resolveWorkspacePackage` is called and the registry is empty. After that, it serves as a cache for the workspace scan.
-
-The scan is recursive up to 15 levels deep and skips: `node_modules`, `dist`, `.git`, `.swite`, and hidden directories. Any directory containing a `package.json` with a `name` field is registered. Duplicates keep the first-found entry.
-
-`rescan()` clears the cache and re-scans from the same root directories. It is called when a package is not found after the initial scan, in case new packages were added since the server started.
-
----
-
-## Compilation cache
-
-`compilationCache` (`src/internal/cache/compilation-cache.ts`) is an in-memory cache keyed by absolute file path. Each entry stores the compiled source output and tracks the set of dependency URLs. Handlers call `compilationCache.get(filePath, getDependencies)` before compiling; if the file's mtime has not changed since the last compile, the cached output is returned.
-
-Cache writes happen after every successful compilation via `compilationCache.set(filePath, rawCompiled, finalCode, getDependencies)`.
-
----
-
-## path-fixup rationale
-
-`fixSwissLibPaths` exists because `@swissjs/compiler` was originally written when the framework packages directory was named `swiss-lib/packages/`. When the directory was renamed to be served under `/swiss-packages/`, the compiler was not updated at the same time. Rather than forking every handler to patch its own output, a single central fixup is applied once per compilation.
-
-The fixup replaces `/swiss-lib/packages/` before `/swiss-lib/` to avoid double-substitution if the function were called more than once on already-patched output.
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Internals
+
+Implementation notes for the non-obvious parts of SWITE.
+
+---
+
+## Workspace root detection algorithm
+
+Two separate implementations exist: one in `SwiteServer` (used at server startup) and one in `src/kernel/workspace.ts` (used by handlers and resolution code at request time). They are slightly different.
+
+### SwiteServer.findWorkspaceRoot
+
+Walks up to six directory levels from `startDir`. At each level it looks for:
+1. A `pnpm-workspace.yaml` file, or
+2. A `package.json` with a `workspaces` field
+
+The first directory matching either condition is returned. `SwiteConfig.rootDir` short-circuits this search if set.
+
+### kernel/workspace.findWorkspaceRoot
+
+Walks up to ten directory levels from `root`. At each level it additionally requires the candidate directory to have either a `lib/` or `packages/` subdirectory alongside the workspace marker file. This stricter check ensures the resolved workspace root is the SWS root (the monorepo that owns the `lib/` directory with compiled packages), not an intermediate workspace.
+
+If a directory has `pnpm-workspace.yaml` but no `lib/` or `packages/`, the walk continues upward. This handles nested monorepo layouts where an inner workspace exists inside an outer SWS root.
+
+### file-path-resolver /lib/ path resolution
+
+For `/lib/` URLs specifically, `resolveFilePath` walks from the app root upward looking for a directory that has both `pnpm-workspace.yaml` and a `lib/` subdirectory present simultaneously. This is the most precise check and handles the case where `findWorkspaceRoot` returns an intermediate directory.
+
+---
+
+## Import map generation
+
+`generateImportMap` (`src/internal/generate-import-map.ts`) runs at the request of the CLI or the `generate-import-map` script, not automatically at dev server startup.
+
+The generated file format:
+
+```json
+{
+  "version": "1.0",
+  "generated": 1716211234567,
+  "imports": {
+    "@scope/pkg": "/swiss-packages/pkg/src/index.ts",
+    "@scope/pkg/components": "/swiss-packages/pkg/src/components/index.ts"
+  }
+}
+```
+
+At dev server startup, `setupMiddleware` calls `loadImportMap` to read this file. If found, it is passed to `ModuleResolver.setImportMap()` and becomes the fast path for all bare import resolutions. A cache miss falls through to the full `resolveBareImport` pipeline.
+
+The SPA fallback handler also reads this file directly and merges it into the HTML importmap.
+
+---
+
+## Symlink registry
+
+`buildSymlinkRegistry` (`src/resolution/symlink-registry.ts`) is called once during server startup. It scans up to four `node_modules` directories:
+
+1. `<appRoot>/node_modules`
+2. `<parentOfAppRoot>/node_modules`
+3. `<workspaceRoot>/node_modules`
+4. `<frameworkMonorepoRoot>/node_modules`
+
+For each directory, it reads all entries. For scoped entries (starting with `@`), it recurses one level and registers each symlink found there. For unscoped entries, it registers each symlink directly.
+
+Registration: `fs.realpath(symlinkPath)` is resolved and stored in a `Map<string, string>` as `realpath → /node_modules/<pkgName>`.
+
+`lookupInSymlinkRegistry(absolutePath)` iterates the map and returns the browser URL if the path starts with any registered realpath. This is called by `toUrl` as the very first step when an absolute path is received.
+
+The registry is consulted before any other logic in `toUrl` because `fs.realpath()` is called throughout the handler chain (in `resolveFilePath` for `/node_modules/` URLs, in `NodeModuleHandler`, and elsewhere) and the resulting absolute paths would otherwise bypass all the workspace-relative URL conversion logic.
+
+---
+
+## Package registry
+
+`PackageRegistry` (`src/kernel/package-registry.ts`) is a process-wide singleton. It is first populated when `resolveWorkspacePackage` is called and the registry is empty. After that, it serves as a cache for the workspace scan.
+
+The scan is recursive up to 15 levels deep and skips: `node_modules`, `dist`, `.git`, `.swite`, and hidden directories. Any directory containing a `package.json` with a `name` field is registered. Duplicates keep the first-found entry.
+
+`rescan()` clears the cache and re-scans from the same root directories. It is called when a package is not found after the initial scan, in case new packages were added since the server started.
+
+---
+
+## Compilation cache
+
+`compilationCache` (`src/internal/cache/compilation-cache.ts`) is an in-memory cache keyed by absolute file path. Each entry stores the compiled source output and tracks the set of dependency URLs. Handlers call `compilationCache.get(filePath, getDependencies)` before compiling; if the file's mtime has not changed since the last compile, the cached output is returned.
+
+Cache writes happen after every successful compilation via `compilationCache.set(filePath, rawCompiled, finalCode, getDependencies)`.
+
+---
+
+## path-fixup rationale
+
+`fixSwissLibPaths` exists because `@swissjs/compiler` was originally written when the framework packages directory was named `swiss-lib/packages/`. When the directory was renamed to be served under `/swiss-packages/`, the compiler was not updated at the same time. Rather than forking every handler to patch its own output, a single central fixup is applied once per compilation.
+
+The fixup replaces `/swiss-lib/packages/` before `/swiss-lib/` to avoid double-substitution if the function were called more than once on already-patched output.

package/docs/guide/configuration.md

@@ -1,89 +1,89 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Configuration
-
-SWITE reads `swiss.config.ts` (or `swiss.config.js`) from the project root. The file must export a `SwiteUserConfig` object as its default export, typically via the `defineConfig` helper.
-
-```typescript
-// swiss.config.ts
-import { defineConfig } from '@swissjs/swite';
-
-export default defineConfig({
-  server: {
-    port: 3000,
-    host: 'localhost',
-  },
-  services: {
-    python: {
-      entry: 'server/main.py',
-      port: 8000,
-      autoStart: true,
-      healthCheck: '/health',
-    },
-  },
-});
-```
-
-The config file is transpiled to ESM by esbuild at startup (bundling disabled, `platform: node`). The temporary output file is cleaned up before the server starts.
-
----
-
-## SwiteUserConfig
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `server` | `ServerConfig` | `{}` | HTTP server options |
-| `services` | `ServicesConfig` | `{}` | External service options |
-
----
-
-## ServerConfig
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `port` | `number` | `3000` | Port for the HTTP server |
-| `host` | `string` | `"localhost"` | Host to bind. When `"localhost"`, SWITE binds to `0.0.0.0` internally so both IPv4 and IPv6 loopback addresses work |
-
----
-
-## ServicesConfig
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `python` | `PythonServiceConfig` | — | Python service definition. Omit if you have no Python backend |
-
----
-
-## PythonServiceConfig
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `entry` | `string` | Yes | Path to the Python entry file, relative to the project root (e.g. `"server/main.py"`) |
-| `port` | `number` | Yes | Port the Python service listens on |
-| `autoStart` | `boolean` | Yes | When `true`, `swite dev` spawns the Python process automatically before starting the Node server |
-| `healthCheck` | `string` | Yes | URL path polled to determine when the Python service is ready (e.g. `"/health"`). SWITE polls `http://localhost:{port}{healthCheck}` every 500 ms, with exponential back-off after five attempts, timing out after 15 seconds |
-| `env` | `Record<string, string>` | No | Additional environment variables merged into the Python process environment alongside `PORT={port}` |
-
----
-
-## defineConfig
-
-`defineConfig(config: SwiteUserConfig): SwiteUserConfig` is a pass-through identity function that provides TypeScript type checking at the call site. Unknown fields are rejected at compile time.
-
----
-
-## Environment variables
-
-In addition to `swiss.config.ts`, SWITE reads `.env` files at the project root for `import.meta.env` inlining. Variables are inlined at compile time into each compiled module; they are not available at runtime via a global object. SWITE loads both a base `.env` and a mode-specific `.env.development` or `.env.production` depending on whether the server is running in dev or production mode.
-
-The following environment variables affect SWITE's own runtime behavior:
-
-| Variable | Description |
-|----------|-------------|
-| `PYTHON_SERVICE_URL` | Base URL of the Python service in production. Required when running `swite start` with a Python service configured. Overrides the localhost fallback used in dev. |
-| `INTERNAL_API_TOKEN` | Value injected as the `X-Internal-Token` header on every `proxyToPython` call |
-| `SWITE_CDN_FALLBACK_SCOPES` | Comma-separated list of scoped package prefixes (e.g. `@types,@tanstack`) that are allowed to fall back to jsDelivr when not found locally. Unscoped packages always fall back. Scoped packages do not fall back by default. |
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Configuration
+
+SWITE reads `swiss.config.ts` (or `swiss.config.js`) from the project root. The file must export a `SwiteUserConfig` object as its default export, typically via the `defineConfig` helper.
+
+```typescript
+// swiss.config.ts
+import { defineConfig } from '@swissjs/swite';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+    host: 'localhost',
+  },
+  services: {
+    python: {
+      entry: 'server/main.py',
+      port: 8000,
+      autoStart: true,
+      healthCheck: '/health',
+    },
+  },
+});
+```
+
+The config file is transpiled to ESM by esbuild at startup (bundling disabled, `platform: node`). The temporary output file is cleaned up before the server starts.
+
+---
+
+## SwiteUserConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `server` | `ServerConfig` | `{}` | HTTP server options |
+| `services` | `ServicesConfig` | `{}` | External service options |
+
+---
+
+## ServerConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `port` | `number` | `3000` | Port for the HTTP server |
+| `host` | `string` | `"localhost"` | Host to bind. When `"localhost"`, SWITE binds to `0.0.0.0` internally so both IPv4 and IPv6 loopback addresses work |
+
+---
+
+## ServicesConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `python` | `PythonServiceConfig` | — | Python service definition. Omit if you have no Python backend |
+
+---
+
+## PythonServiceConfig
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `entry` | `string` | Yes | Path to the Python entry file, relative to the project root (e.g. `"server/main.py"`) |
+| `port` | `number` | Yes | Port the Python service listens on |
+| `autoStart` | `boolean` | Yes | When `true`, `swite dev` spawns the Python process automatically before starting the Node server |
+| `healthCheck` | `string` | Yes | URL path polled to determine when the Python service is ready (e.g. `"/health"`). SWITE polls `http://localhost:{port}{healthCheck}` every 500 ms, with exponential back-off after five attempts, timing out after 15 seconds |
+| `env` | `Record<string, string>` | No | Additional environment variables merged into the Python process environment alongside `PORT={port}` |
+
+---
+
+## defineConfig
+
+`defineConfig(config: SwiteUserConfig): SwiteUserConfig` is a pass-through identity function that provides TypeScript type checking at the call site. Unknown fields are rejected at compile time.
+
+---
+
+## Environment variables
+
+In addition to `swiss.config.ts`, SWITE reads `.env` files at the project root for `import.meta.env` inlining. Variables are inlined at compile time into each compiled module; they are not available at runtime via a global object. SWITE loads both a base `.env` and a mode-specific `.env.development` or `.env.production` depending on whether the server is running in dev or production mode.
+
+The following environment variables affect SWITE's own runtime behavior:
+
+| Variable | Description |
+|----------|-------------|
+| `PYTHON_SERVICE_URL` | Base URL of the Python service in production. Required when running `swite start` with a Python service configured. Overrides the localhost fallback used in dev. |
+| `INTERNAL_API_TOKEN` | Value injected as the `X-Internal-Token` header on every `proxyToPython` call |
+| `SWITE_CDN_FALLBACK_SCOPES` | Comma-separated list of scoped package prefixes (e.g. `@types,@tanstack`) that are allowed to fall back to jsDelivr when not found locally. Unscoped packages always fall back. Scoped packages do not fall back by default. |

package/docs/guide/index.md

@@ -1,13 +1,13 @@
-<!--
-Copyright (c) 2024 Themba Mzumara
-SWITE - SWISS Development Server
-Licensed under the MIT License.
--->
-
-# Guide
-
-Start here. This guide covers installing SWITE, laying out a project, configuring it, and building for production.
-
-- [Quickstart](./quickstart.md) — install, run `swite dev`, write your first component, build
-- [Project structure](./project-structure.md) — recommended directory layout, public dir, config file location
-- [Configuration](./configuration.md) — full `SwiteUserConfig` and `PythonServiceConfig` reference
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Guide
+
+Start here. This guide covers installing SWITE, laying out a project, configuring it, and building for production.
+
+- [Quickstart](./quickstart.md) — install, run `swite dev`, write your first component, build
+- [Project structure](./project-structure.md) — recommended directory layout, public dir, config file location
+- [Configuration](./configuration.md) — full `SwiteUserConfig` and `PythonServiceConfig` reference