@decohere/flux 0.0.1-dev.97 → 0.0.1-dev.99

package/README.md

@@ -0,0 +1,247 @@
+# @decohere/flux
+
+In-process TypeScript load for Node.js ESM apps — either one-shot (`flux run`) or hot-reload serve (`flux serve`).
+
+Use Flux when you want to run source `.ts` directly. Flux transpiles with the **Forge** SWC compiler; that compiler uses path aliases Mesh builds dynamically from the workspace (`package.json` `name` → source `main`). Do not use Flux as a browser bundler, a worker-thread HMR, or a production process manager.
+
+Point Flux at a tree of TypeScript packages (`package.json` at each project root). [Mesh](../mesh/README.md) is how that tree is deduced — you do not run Flux against Mesh. Layout and glob overrides: [Mesh — workspace layout](../mesh/README.md#workspace-layout).
+
+This package is the Flux API. You use it through the `flux` CLI (`flux run` / `flux serve`), not by importing `@decohere/flux` from application code. The [Programmatic API](#programmatic-api) is only for embedding Flux in another tool.
+
+Related: [Mesh](../mesh/README.md) (package discovery), [Forge](../forge/README.md) (SWC + debug aliases). The `flux` command ships in `@decohere/cli`.
+
+## When to use
+
+| Use Flux | Use something else |
+|---|---|
+| Local debug of Node apps with HMR (`serve`) | Production (`node` on Forge release output, Docker, orchestrator) |
+| One-shot TS CLI / script without a pre-build (`run`) | Published package `bin` entries (stay built JS) |
+| Packages resolved by `package.json` name | Browser UI (Vite / `ng serve` / … via package scripts) |
+| Clean `Symbol.asyncDispose` on reboot (`serve`) | Worker threads / `createRequire` |
+
+## `run` vs `serve`
+
+| | `flux run <entry.ts>` | `flux serve` |
+|---|---|---|
+| Compiles `.ts` on load | ✅ | ✅ |
+| File watch / HMR reboot | ❌ | ✅ |
+| Entry | Any path you pass | Package `main` (`main.ts` / `main.tsx`) |
+| Process | Exits when the entry finishes | Long-lived until Ctrl+C (SIGINT) or SIGTERM |
+
+## Install
+
+The `flux` command is on `@decohere/cli` (this package is the API). Add the CLI with your package manager:
+
+```bash
+pnpm add -D @decohere/cli
+# npm install --save-dev @decohere/cli
+```
+
+That installs the `flux`, `forge`, and `decohere` bins. Then:
+
+```bash
+pnpm exec flux --help
+flux run projects/greeter/src/cli.ts
+flux serve
+```
+
+Scaffolded apps already depend on `@decohere/cli` — use those scripts (`pnpm dev`) or `pnpm exec flux`.
+
+## CLI
+
+Host options (`--config-file`, `--log-level`) are parsed before the subcommand. `--config-file` (default `.decohere.js` if present) is optional Mesh config for package discovery. Omit it to use [Mesh defaults](../mesh/README.md#workspace-layout).
+
+### `flux run` — one-shot script
+
+Any TypeScript file. The process exits when that module finishes evaluating.
+
+```ts
+// projects/greeter/src/cli.ts
+const name = process.argv[2] ?? "world";
+console.log(`hello ${name}`);
+```
+
+```bash
+flux run projects/greeter/src/cli.ts
+# hello world
+
+flux run projects/greeter/src/cli.ts -- Alice
+# hello Alice
+```
+
+| Flag / arg | Default | Meaning |
+|---|---|---|
+| `<entry>` | (required) | Path to a TypeScript entry file |
+| `[args…]` | — | Forwarded to the entry after argv rewrite (`process.argv.slice(2)`) |
+| `--configuration <name>` | `debug` | Build configuration name |
+
+Before import, `run` sets `process.argv` to `[node, absoluteEntry, …args]` so the file behaves like a real Node bin. Use `--` when the entry’s own flags would otherwise be parsed by Flux (`flux run ./src/cli.ts -- --verbose`).
+
+### `flux serve` — long-lived process (HMR)
+
+Use `serve` when the program should stay up until you kill it (HTTP server, worker). Flux watches source, disposes the previous entry, and re-imports on change.
+
+`serve` boots the file named in that package’s `package.json` `main`. It must be `main.ts` / `main.tsx` (see [Classification](#classification-convention)). Snippet from `projects/my-api/package.json`:
+
+```json
+{
+  "name": "my-api",
+  "main": "main.ts"
+}
+```
+
+```ts
+// projects/my-api/main.ts
+import { createServer } from "node:http";
+
+const server = createServer((_req, res) => {
+	res.end("ok\n");
+}).listen(3000);
+
+console.log("listening on 3000");
+
+export default {
+	async [Symbol.asyncDispose]() {
+		await new Promise<void>((resolve, reject) => {
+			server.close((err) => (err != null ? reject(err) : resolve()));
+		});
+	},
+};
+```
+
+These are three ways to start the same serve (flags combine; `flux serve --project my-api --reboot-debounce-ms 2000` is valid):
+
+```bash
+flux serve
+flux serve --project my-api
+flux serve --reboot-debounce-ms 2000
+```
+
+| | What it does |
+|---|---|
+| `flux serve` | Boots the first discovered project (Mesh lists packages by `package.json` `name`, A→Z). |
+| `--project my-api` | Boots that package by name. |
+| `--reboot-debounce-ms 2000` | Same serve, but waits 2s after the last save before rebooting (default 250ms). |
+
+Use `--project` or [directory slices](#directory-slice-flux-serve-token) when the first package is not the app you want.
+
+Ctrl+C (SIGINT) or SIGTERM (Docker, CI, process managers) disposes the entry, then the CLI exits with code 0.
+
+| Flag / arg | Default | Meaning |
+|---|---|---|
+| `[slices…]` | — | One or more module tokens among discovered packages (union; see **Directory slice**) |
+| `--configuration <name>` | `debug` | Build configuration name (not a file path) |
+| `--project <name>` | first discovered package | Single package name to serve (not with slices) |
+| `--reboot-debounce-ms <ms>` | `250` | Quiet window after the last affecting save before a reboot. Use ~2000 when an agent writes many files in sequence. |
+
+On a watched change that reaches a served entry, Flux invalidates that subgraph, calls `asyncDispose` on the previous default export, and re-imports. Rapid saves are trailing-debounced and serialized (overlapping dispose cannot run). A change that never reaches an entry does nothing. Each reboot logs `flux reboot` / `flux ready` at info (project names, triggering files, elapsed ms) so the event stays visible when the app boot is chatty. File-watch detail stays at trace.
+
+### Dispose on reboot
+
+`serve` loads the entry’s **default export**. If that object implements `Symbol.asyncDispose`, Flux calls it:
+
+- before each HMR reboot (so the next boot can bind the same port / reopen the DB)
+- on SIGINT / SIGTERM / CLI teardown
+
+The `export default { async [Symbol.asyncDispose]() { … } }` in the server example above is that contract. Close servers, pools, and timers there — not in a `process.on("SIGINT")` handler Flux does not own.
+
+**Cortex APIs** scaffold `export default app`. `App.dispose` disposes the Crucible root container, then Scribe. Constructed services that implement `Symbol.asyncDispose` (or `Symbol.dispose`) are torn down automatically — including the HTTP provider. Put teardown on the service; do not wrap the default export to close sockets or pools.
+
+Flux clears its reference to the object *before* calling dispose, so a failed boot cannot dispose the same instance twice.
+
+## Directory slice (`flux serve <token>…`)
+
+A slice is a path token. Flux keeps Mesh packages whose directory sits under that token, then [classifies](#classification-convention) each one. `flux serve shop` and `flux serve projects/shop` are the same token.
+
+Example workspace (every leaf directory here has its own `package.json`):
+
+```
+projects/
+  app.web/                   # scripts.dev: vite          → UI
+  shop/
+    api/                     # main: main.ts              → Node app
+    worker/                  # main: main.ts              → Node app
+    web/                     # scripts.dev: vite          → UI
+    domain/                  # main: src/index.ts         → library
+  shop-admin.api/            # main: main.ts              → other module
+  billing/
+    api/                     # main: main.ts              → Node app
+    domain/                  # main: src/index.ts         → library
+```
+
+`flux serve shop` matches `projects/shop` and children (and `projects/shop.*`). It does **not** match `shop-admin.api`.
+
+| | In-process (HMR) | Spawn `scripts.dev` / `serve` | Skip |
+|---|---|---|---|
+| `flux serve shop` | `shop/api`, `shop/worker` | `shop/web` | `shop/domain` |
+| `flux serve app` | — | `app.web` | — |
+| `flux serve shop-admin` | `shop-admin.api` | — | — |
+| `flux serve app shop billing` | `shop/api`, `shop/worker`, `billing/api` | `app.web`, `shop/web` | `shop/domain`, `billing/domain` |
+
+Multiple tokens are a union. Use slices **or** `--project`, not both.
+
+Matching is path-safe:
+
+- Nested: `shop` → `projects/shop`, `projects/shop/api`
+- Flat dotted packages: `shop` → `projects/shop.web`, `projects/shop.domain`; `app` → `projects/app.web`
+- Does **not** match siblings that only share a string prefix (`shop` ≠ `projects/shop-admin.api` — pass `shop-admin` explicitly)
+
+Named serve profiles in `.decohere.js` (e.g. `shop-stack: ["app", "shop", "billing"]`) are deferred.
+
+### Classification (convention)
+
+| Kind | How Flux decides | Behavior |
+|---|---|---|
+| **Foreign / UI** | `scripts.dev` or `scripts.serve` that does **not** invoke `flux` | Spawn `pnpm`/`npm`/`yarn` `run <script>` in that package cwd. Flux does not HMR-boot it. |
+| **Flux app** | `package.json` `main` ends in `main.ts` / `main.tsx`, and no foreign serve script | Boot in-process (one HMR graph per app). |
+| **Library** | Everything else (e.g. `main`: `src/index.ts`) | Skip — imported via debug aliases. |
+
+Foreign scripts win over `main.ts` so Vite (and similar) apps are never loaded in the Node HMR hook. The **package script** is the contract, not a hard-coded Vite check.
+
+Logs name skipped libraries and deferred packages (script + cwd). Child processes are stopped when the CLI exits (SIGINT or SIGTERM → dispose).
+
+## Limits
+
+Flux does not support `createRequire`, worker threads, or browser HMR. Reloads always dispose and re-import the entry — there is no `import.meta.hot.accept()` boundary yet.
+
+**Restart `flux serve` after changing any of these** — they're read once at start, and saving them doesn't reboot:
+
+- `tsconfig.json`, `.swcrc`, or `.decohere.js`
+- a `package.json` (name, `main`, dependencies)
+- adding or removing a package under `projects/`
+
+Only source files (`.ts`) that a served entry imports trigger a reboot.
+
+**Memory grows over a long session.** Each reboot imports changed modules under a new `?version=` URL, and Node's ES module cache never releases the old versions. That's fine for a working day; if a session runs for days with thousands of reboots, restart it.
+
+Flux uses **Forge’s compiler**. Forge debug builds path aliases from Mesh (`name` → source `main`) and rewrites `import "@scope/pkg"` to that `.ts` file. That is a debug rule so you can edit a library and hit HMR without a pre-build or `node_modules` workspace symlink. Release still resolves through real `node_modules` (published `exports` / `main`).
+
+Why aliases, and a tree of where a symlink misses `src/index.ts`: [Forge — debug path aliases](../forge/README.md#debug-path-aliases-not-node_modules-links).
+
+## Programmatic API
+
+Use this only when you need to **embed** Flux (tests, a custom host). Day-to-day, invoke `flux run` / `flux serve` — do not import `@decohere/flux` from application code.
+
+```ts
+import { flux } from "@decohere/flux";
+
+// One-shot compile-on-load (no watch) — same idea as `flux run`
+await flux.run("/abs/path/to/entry.ts");
+await flux.run("./tool.ts", { configuration: "debug", args: ["--flag"] });
+
+// Long-lived HMR — same idea as `flux serve` (in-process apps)
+const server = await flux.serve({
+  configuration: "debug",
+  project: "my-api", // optional single package
+  // projects: ["api", "svc"], // optional multi-entry
+  rebootDebounceMs: 2000, // optional; default 250
+});
+server.on("reboot", () => {}); // after dispose + boot attempt for affected entries
+await server.dispose();
+```
+
+`configuration` is the Mesh/Forge configuration **name** (`debug`, `release`, …), matching `--configuration`. Defaults to `debug`. Pass `workspace` in tests to skip `WorkspaceFactory`.
+
+`flux.run` keeps Node ESM hooks registered for the process so the imported graph can still load `.ts`. Do not dispose the loader after a successful run.
+
+Slice helpers (`classifySliceProjects`, `normalizeSlicePrefix`, …) and the engine types (`SourceModuleLoader`, `HotReloadServer`) stay exported for tests and tooling; the CLI and `flux` facade are the primary surfaces.

package/es6/src/run.action.js

@@ -8,7 +8,6 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { scribe } from "@decohere/scribe";

package/es6/src/serve.action.js

@@ -9,13 +9,10 @@ function _ts_metadata(k, v) {
 }
 import path from "node:path";
 import { injectable } from "@decohere/crucible/decorators";
-// biome-ignore lint/style/useImportType: <DI>
 import { Workspace } from "@decohere/mesh";
 import { ActionResponse } from "@decohere/nexus/cli";
 import { scribe } from "@decohere/scribe";
-// biome-ignore lint/style/useImportType: <DI>
 import { DeferredScriptRunner } from "./deferred-script-runner.js";
-// biome-ignore lint/style/useImportType: <DI>
 import { HotReloadServer } from "./hot-reload-server.js";
 import { classifySliceProjects, resolveDeferScript } from "./slice-serve.js";
 export class ServeAction {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/flux",
-  "version": "0.0.1-dev.97",
+  "version": "0.0.1-dev.99",
   "description": "Hot module reload server for Node.js ESM applications",
   "keywords": [
     "typescript",
@@ -25,11 +25,11 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/crucible": "0.0.1-dev.97",
-    "@decohere/forge": "0.0.1-dev.97",
-    "@decohere/mesh": "0.0.1-dev.97",
-    "@decohere/nexus": "0.0.1-dev.97",
-    "@decohere/scribe": "0.0.1-dev.97",
+    "@decohere/crucible": "0.0.1-dev.99",
+    "@decohere/forge": "0.0.1-dev.99",
+    "@decohere/mesh": "0.0.1-dev.99",
+    "@decohere/nexus": "0.0.1-dev.99",
+    "@decohere/scribe": "0.0.1-dev.99",
     "commander": "^13.1.0",
     "rxjs": "^7.8.2"
   },