@swissjs/swite 0.3.1 → 0.3.2

package/docs/cli/start.md

@@ -0,0 +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.

package/docs/development/contributing.md

@@ -0,0 +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.

package/docs/development/index.md

@@ -0,0 +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

package/docs/development/internals.md

@@ -0,0 +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.

package/docs/guide/configuration.md

@@ -0,0 +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. |

package/docs/guide/index.md

@@ -0,0 +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

package/docs/guide/project-structure.md

@@ -0,0 +1,75 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Project Structure
+
+Conventions for a SWITE-powered application.
+
+---
+
+## Application layout
+
+```
+my-app/
+├── src/
+│   ├── index.ui              # entry point — referenced by public/index.html
+│   ├── App.ui                # root component
+│   ├── components/           # reusable UI components
+│   └── types/                # shared TypeScript types
+├── public/
+│   └── index.html            # HTML shell — SWITE injects import map and CSS links
+├── .swite/
+│   └── import-map.json       # generated at build time; optional at dev time
+├── dist/                     # production build output (gitignored)
+├── package.json
+└── swiss.config.ts           # optional config
+```
+
+---
+
+## Source file conventions
+
+| Extension | Handler | Description |
+|-----------|---------|-------------|
+| `.ui`     | UIHandler | SwissJS component syntax; compiled by `@swissjs/compiler` then TypeScript-stripped by esbuild |
+| `.uix`    | UIXHandler | JSX variant of SwissJS component syntax; same pipeline as `.ui` |
+| `.ts`     | TSHandler | Plain TypeScript; TypeScript-stripped by esbuild only |
+| `.js`     | JSHandler | Plain JavaScript; import-rewritten but not compiled |
+| `.mjs`    | MJSHandler | Same as `.js`; falls back to `.js` if `.mjs` does not exist |
+
+SWITE handles extension negotiation: a request for `/src/Foo.js` will be served from `Foo.ts`, `Foo.ui`, or `Foo.uix` if the `.js` file does not exist on disk. Similarly, a request for `/src/Foo.ts` falls back to `.ui` or `.uix`.
+
+---
+
+## public/ directory
+
+The `public/` directory is served as static files. SWITE's SPA fallback reads `public/index.html` and:
+
+- Injects cache-busting query parameters on the entry point `<script>` tag
+- Injects an `<script type="importmap">` block from `.swite/import-map.json` (merging with any existing importmap in HTML)
+- Injects `<link rel="stylesheet">` tags for CSS files discovered in the entry point source
+
+Files under `public/` are served with `no-cache` headers during development.
+
+---
+
+## Config file
+
+SWITE looks for `swiss.config.ts` (preferred) or `swiss.config.js` at the project root. Both are optional. If neither exists, SWITE starts with defaults: port 3000, host `localhost`, no Python service.
+
+See [Configuration](./configuration.md) for the full field reference.
+
+---
+
+## Workspace layout
+
+When SWITE detects a monorepo (by walking up the directory tree looking for `pnpm-workspace.yaml` or a `package.json` with `workspaces`), it:
+
+- Scans workspace `node_modules` for package resolution
+- Serves `lib/`, `libraries/`, and `modules/` directories as static file prefixes
+- Compiles source files under `packages/` through the handler pipeline
+
+The workspace root is detected automatically; it can also be set explicitly via `SwiteConfig.rootDir`.

package/docs/guide/quickstart.md

@@ -0,0 +1,113 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Quickstart
+
+Get a SwissJS application running under SWITE in a few minutes.
+
+---
+
+## Prerequisites
+
+- Node.js 18.19.x or later
+- pnpm 10.x
+- A SwissJS application (`src/index.ui` as entry point)
+
+---
+
+## 1. Install SWITE
+
+In your application package:
+
+```bash
+pnpm add -D @swissjs/swite
+```
+
+Add the CLI commands to `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "swite dev",
+    "build": "swite build",
+    "start": "swite start"
+  }
+}
+```
+
+---
+
+## 2. Start the dev server
+
+```bash
+pnpm dev
+```
+
+SWITE starts on `http://localhost:3000` by default. Every `.ui`, `.uix`, `.ts`, and `.js` request is compiled and import-rewritten on demand. HMR is active on port 24678.
+
+---
+
+## 3. Project layout
+
+A minimal SWITE project:
+
+```
+my-app/
+├── src/
+│   ├── index.ui          # entry point — mounted by public/index.html
+│   ├── App.ui            # root component
+│   └── components/
+├── public/
+│   └── index.html        # shell HTML — SWITE injects import map here
+├── package.json
+└── swiss.config.ts       # optional
+```
+
+SWITE resolves files relative to the directory where `swite dev` is invoked (the project root). The `src/` prefix in URLs maps directly to `<root>/src/` on disk.
+
+---
+
+## 4. Write a component
+
+```typescript
+// src/components/Counter.ui
+
+component Counter {
+  state {
+    let count: number = 0;
+  }
+
+  render() {
+    return html`
+      <div>
+        <p>Count: ${this.count}</p>
+        <button onclick="${() => this.count++}">+1</button>
+      </div>
+    `;
+  }
+}
+```
+
+SWITE pipes `.ui` files through `@swissjs/compiler` (the SwissJS syntax transformer), then through esbuild's TypeScript stripper, rewrites all bare imports to browser-resolvable URLs, and serves the result as `application/javascript`.
+
+---
+
+## 5. Build for production
+
+```bash
+pnpm build
+```
+
+Output goes to `dist/`. The build entry is fixed to `src/index.ui`. See [`swite build`](../cli/build.md) for details.
+
+---
+
+## Next
+
+- [Project structure](./project-structure.md) — layout conventions
+- [Configuration](./configuration.md) — server port, Python service options
+- [CLI reference](../cli/index.md) — all commands
+- [Architecture](../architecture/index.md) — how SWITE works internally

package/docs/index.md

@@ -0,0 +1,16 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# SWITE Documentation
+
+SWITE (`@swissjs/swite`) is the development server and production build tool for SwissJS applications. It provides on-demand TypeScript and SwissJS source compilation, bare-import rewriting, HMR, Python service lifecycle management, and an esbuild-powered production pipeline.
+
+## Sections
+
+- [Guide](./guide/index.md) — Installation, project layout, configuration reference, and first steps
+- [CLI](./cli/index.md) — `swite dev`, `swite build`, and `swite start` command reference
+- [Architecture](./architecture/index.md) — Internals: dev server, import resolution, HMR, build pipeline, Python integration
+- [Development](./development/index.md) — Contributing, local build, and internal implementation notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swissjs/swite",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "SWITE - SWISS Development Server (Vite replacement)",
   "type": "module",
   "main": "dist/index.js",
@@ -8,19 +8,9 @@
   "bin": {
     "swite": "dist/cli.js"
   },
-  "scripts": {
-    "build": "tsc -b",
-    "dev": "tsc -b --watch",
-    "clean": "rm -rf dist node_modules && rm -f tsconfig.tsbuildinfo",
-    "generate-import-map": "tsx src/internal/generate-import-map-cli.ts",
-    "test": "node --import tsx --test __tests__/import-rewriter-bug.test.ts",
-    "changeset": "changeset",
-    "release:version": "changeset version",
-    "release:publish": "changeset publish"
-  },
   "dependencies": {
-    "@swissjs/core": "0.1.5",
-    "@swissjs/compiler": "0.1.4",
+    "@swissjs/core": "0.1.8",
+    "@swissjs/compiler": "0.1.5",
     "@swissjs/plugin-file-router": "1.0.2",
     "chalk": "^5.3.0",
     "chokidar": "^3.5.3",
@@ -42,17 +32,18 @@
     "access": "public"
   },
   "license": "MIT",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ],
-    "overrides": {
-      "path-to-regexp": "^0.1.13",
-      "picomatch": "^2.3.2"
-    }
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kibologic/alpine-erp-core.git"
+    "url": "git+https://github.com/kibologic/swite.git"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "clean": "rm -rf dist node_modules && rm -f tsconfig.tsbuildinfo",
+    "generate-import-map": "tsx src/internal/generate-import-map-cli.ts",
+    "test": "node --import tsx --test __tests__/import-rewriter-bug.test.ts",
+    "changeset": "changeset",
+    "release:version": "changeset version",
+    "release:publish": "changeset publish"
   }
-}
+}

package/src/config/config.ts

@@ -23,6 +23,17 @@ export interface ServerConfig {
 export interface SwiteUserConfig {
   server?: ServerConfig;
   services?: ServicesConfig;
+  /**
+   * Package scopes that should be treated as "internal" or "private".
+   * These scopes prioritize local/monorepo resolution and are forbidden from CDN redirects.
+   * e.g. ["@kibologic", "@alpine"]
+   */
+  internalScopes?: string[];
+  /**
+   * Manual override for sibling repository lookup.
+   * Swite will search these directories for local package source code.
+   */
+  siblingRepositories?: string[];
 }
 
 /**

package/src/dev-engine/handlers/base-handler.ts

@@ -8,12 +8,14 @@ import type { Response } from "express";
 import { promises as fs } from "node:fs";
 import { ModuleResolver } from "../../resolution/resolver.js";
 import { resolveFilePath } from "../../resolution/path/file-path-resolver.js";
+import type { SwiteUserConfig } from "../../config/config.js";
 
 export interface HandlerContext {
   resolver: ModuleResolver;
   root: string;
   workspaceRoot: string | null;
-  env: Record<string, string>;
+  env?: Record<string, string>;
+  userConfig?: SwiteUserConfig;
 }
 
 /**
@@ -34,7 +36,7 @@ export class BaseHandler {
   constructor(protected context: HandlerContext) {}
 
   protected async resolveFilePath(url: string): Promise<string> {
-    return resolveFilePath(url, this.context.root, this.context.workspaceRoot);
+    return resolveFilePath(url, this.context.root, this.context.workspaceRoot, this.context.userConfig);
   }
 
   protected async fileExists(filePath: string): Promise<boolean> {