@decohere/flux 0.0.1-dev.10 → 0.0.1-dev.100

package/es6/src/rewrite-serve-specifier.js

@@ -0,0 +1,38 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { packageAliases } from "@decohere/mesh";
+/**
+ * Map a resolve-hook specifier to a versioned watched `.ts` file URL.
+ * Covers relative `.js` / `.ts` / extensionless imports and bare workspace
+ * package names (dynamic `import()` never goes through SWC path rewrite).
+ */ export function rewriteServeSpecifier(options) {
+    const { specifier, parentUrl, isWatchedTs, resolveBare, versionFileUrl } = options;
+    const relativeTs = resolveRelativeWatchedTs(specifier, parentUrl, isWatchedTs);
+    if (relativeTs != null) {
+        return versionFileUrl(pathToFileURL(relativeTs).toString());
+    }
+    const bareTarget = resolveBare(specifier);
+    if (bareTarget != null && isWatchedTs(bareTarget)) {
+        return versionFileUrl(pathToFileURL(bareTarget).toString());
+    }
+    return null;
+}
+function resolveRelativeWatchedTs(specifier, parentUrl, isWatchedTs) {
+    if (packageAliases.isBareSpecifier(specifier)) return null;
+    if (!(specifier.startsWith(".") || specifier.startsWith("/"))) return null;
+    const parentClean = parentUrl.split("?")[0];
+    if (parentClean == null || parentClean === "") return null;
+    let resolved;
+    try {
+        resolved = new URL(specifier, parentClean);
+    } catch  {
+        return null;
+    }
+    if (resolved.protocol !== "file:") return null;
+    let filePath = fileURLToPath(resolved);
+    if (filePath.endsWith(".js")) {
+        filePath = `${filePath.slice(0, -3)}.ts`;
+    } else if (!filePath.endsWith(".ts")) {
+        filePath = `${filePath}.ts`;
+    }
+    return isWatchedTs(filePath) ? filePath : null;
+}

package/es6/src/run.action.js

@@ -0,0 +1,37 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+import { injectable } from "@decohere/crucible/decorators";
+import { Workspace } from "@decohere/mesh";
+import { ActionResponse } from "@decohere/nexus/cli";
+import { scribe } from "@decohere/scribe";
+import { flux } from "./flux.js";
+export class RunAction {
+    workspace;
+    logger = scribe.logger(RunAction.name);
+    constructor(workspace){
+        this.workspace = workspace;
+    }
+    async run(options) {
+        this.logger.trace(`Running ${options.entry}`);
+        await flux.run(options.entry, {
+            configuration: options.configuration,
+            args: options.args,
+            workspace: this.workspace
+        });
+        return ActionResponse.Success(RunAction.name);
+    }
+}
+RunAction = _ts_decorate([
+    injectable(),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Workspace === "undefined" ? Object : Workspace
+    ])
+], RunAction);

package/es6/src/run.command.js

@@ -0,0 +1,55 @@
+import { ConfigurationOption, DecohereCommand } from "@decohere/nexus/cli";
+import { RunAction } from "./run.action.js";
+export class RunCommand extends DecohereCommand {
+    get actions() {
+        return [
+            RunAction
+        ];
+    }
+    constructor(name){
+        super(name);
+        this.description("Compile and run a TypeScript entry on the fly (no watch / HMR)");
+        this.argument("<entry>", "Path to the TypeScript entry file");
+        this.argument("[args...]", "Arguments forwarded to the entry after rewriting argv");
+        this.addOption(new ConfigurationOption("debug"));
+    }
+    /**
+	 * Commander passes positionals before options when `<entry> [args...]` is declared.
+	 * The CLI host ModuleFactory expects `(opts, cmd)` — normalize and stash entry/args on opts.
+	 */ action(fn) {
+        return super.action((...args)=>{
+            const cmd = args.at(-1);
+            const opts = args.at(-2);
+            const { entry, entryArgs } = normalizeRunPositionals(args.slice(0, -2));
+            cmd.setOptionValue("entry", entry);
+            cmd.setOptionValue("args", entryArgs);
+            return fn(opts, cmd);
+        });
+    }
+}
+/** Commander yields `[entry, args[]]` or sometimes a flat list depending on arity. */ function normalizeRunPositionals(positionals) {
+    if (positionals.length === 0) {
+        return {
+            entry: "",
+            entryArgs: []
+        };
+    }
+    const first = positionals[0];
+    if (typeof first !== "string" || first === "") {
+        return {
+            entry: "",
+            entryArgs: []
+        };
+    }
+    const second = positionals[1];
+    if (Array.isArray(second)) {
+        return {
+            entry: first,
+            entryArgs: second.filter((s)=>typeof s === "string")
+        };
+    }
+    return {
+        entry: first,
+        entryArgs: positionals.slice(1).filter((s)=>typeof s === "string" && s !== "")
+    };
+}

package/es6/src/serve.action.js

@@ -7,35 +7,99 @@ function _ts_decorate(decorators, target, key, desc) {
 function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.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";
-// biome-ignore lint/style/useImportType: <DI>
+import { scribe } from "@decohere/scribe";
+import { DeferredScriptRunner } from "./deferred-script-runner.js";
 import { HotReloadServer } from "./hot-reload-server.js";
+import { classifySliceProjects, resolveDeferScript } from "./slice-serve.js";
 export class ServeAction {
     server;
     workspace;
-    constructor(server, workspace){
+    deferredScripts;
+    logger = scribe.logger(ServeAction.name);
+    constructor(server, workspace, deferredScripts){
         this.server = server;
         this.workspace = workspace;
+        this.deferredScripts = deferredScripts;
     }
     async run(options) {
+        const slices = (options.slices ?? []).filter((s)=>s !== "");
+        if (slices.length > 0 && options.project != null) {
+            throw new Error("Use either directory slices or --project, not both");
+        }
+        if (slices.length > 0) {
+            return this.runSlices(options, slices);
+        }
         await this.server.start({
             workspace: this.workspace,
             buildConfig: options.configuration,
-            project: options.project
+            project: options.project,
+            rebootDebounceMs: options.rebootDebounceMs
         });
         return ActionResponse.Blocking(ServeAction.name);
     }
+    async runSlices(options, slices) {
+        const views = await this.toSliceViews(options.configuration);
+        const classified = classifySliceProjects(views, slices);
+        const label = slices.join(" ");
+        for (const skipped of classified.skip){
+            this.logger.info(`skipped ${skipped.projectDirectory} — library (no Flux entry / scripts)`);
+        }
+        if (classified.flux.length === 0 && classified.defer.length === 0) {
+            throw new Error(`No runnable projects in slice(s) "${label}" (need Flux main.ts apps and/or package scripts.dev/serve)`);
+        }
+        const workspaceRoot = path.resolve(this.workspace.rootDir ?? process.cwd());
+        for (const deferred of classified.defer){
+            const script = resolveDeferScript(deferred.scripts);
+            if (script == null) continue;
+            const project = this.findProject(options.configuration, deferred.name);
+            this.deferredScripts.start({
+                label: deferred.projectDirectory,
+                cwd: project.projectRoot,
+                script,
+                workspaceRoot
+            });
+        }
+        if (classified.flux.length > 0) {
+            await this.server.start({
+                workspace: this.workspace,
+                buildConfig: options.configuration,
+                projects: classified.flux.map((p)=>p.name),
+                rebootDebounceMs: options.rebootDebounceMs
+            });
+        }
+        return ActionResponse.Blocking(ServeAction.name);
+    }
+    async toSliceViews(configuration) {
+        const projects = this.workspace.getProjects(configuration);
+        return Promise.all(projects.map((project)=>this.toSliceView(project)));
+    }
+    async toSliceView(project) {
+        const pkg = await project.getPackageJson();
+        return {
+            name: project.name,
+            projectDirectory: project.projectDirectory.replaceAll("\\", "/"),
+            main: pkg.main ?? "src/index.ts",
+            scripts: pkg.scripts ?? {}
+        };
+    }
+    findProject(configuration, name) {
+        const found = this.workspace.getProjects(configuration).find((p)=>p.name === name);
+        if (found == null) {
+            throw new Error(`Project "${name}" not found in workspace`);
+        }
+        return found;
+    }
 }
 ServeAction = _ts_decorate([
     injectable(),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
         typeof HotReloadServer === "undefined" ? Object : HotReloadServer,
-        typeof Workspace === "undefined" ? Object : Workspace
+        typeof Workspace === "undefined" ? Object : Workspace,
+        typeof DeferredScriptRunner === "undefined" ? Object : DeferredScriptRunner
     ])
 ], ServeAction);
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2ZsdXgvc3JjL3NlcnZlLmFjdGlvbi50cyJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBpbmplY3RhYmxlIH0gZnJvbSBcIkBkZWNvaGVyZS9jcnVjaWJsZS9kZWNvcmF0b3JzXCI7XG4vLyBiaW9tZS1pZ25vcmUgbGludC9zdHlsZS91c2VJbXBvcnRUeXBlOiA8REk+XG5pbXBvcnQgeyBXb3Jrc3BhY2UgfSBmcm9tIFwiQGRlY29oZXJlL21lc2hcIjtcbmltcG9ydCB7IHR5cGUgQWN0aW9uLCBBY3Rpb25SZXNwb25zZSB9IGZyb20gXCJAZGVjb2hlcmUvbmV4dXMvY2xpXCI7XG4vLyBiaW9tZS1pZ25vcmUgbGludC9zdHlsZS91c2VJbXBvcnRUeXBlOiA8REk+XG5pbXBvcnQgeyBIb3RSZWxvYWRTZXJ2ZXIgfSBmcm9tIFwiLi9ob3QtcmVsb2FkLXNlcnZlci5qc1wiO1xuXG5leHBvcnQgdHlwZSBTZXJ2ZU9wdGlvbnMgPSB7XG5cdGNvbmZpZ3VyYXRpb246IHN0cmluZztcblx0cHJvamVjdD86IHN0cmluZztcbn07XG5cbkBpbmplY3RhYmxlKClcbmV4cG9ydCBjbGFzcyBTZXJ2ZUFjdGlvbiBpbXBsZW1lbnRzIEFjdGlvbjxTZXJ2ZU9wdGlvbnM+IHtcblx0cHVibGljIGNvbnN0cnVjdG9yKFxuXHRcdHByaXZhdGUgcmVhZG9ubHkgc2VydmVyOiBIb3RSZWxvYWRTZXJ2ZXIsXG5cdFx0cHJpdmF0ZSByZWFkb25seSB3b3Jrc3BhY2U6IFdvcmtzcGFjZSxcblx0KSB7fVxuXG5cdHB1YmxpYyBhc3luYyBydW4ob3B0aW9uczogU2VydmVPcHRpb25zKTogUHJvbWlzZTxBY3Rpb25SZXNwb25zZT4ge1xuXHRcdGF3YWl0IHRoaXMuc2VydmVyLnN0YXJ0KHtcblx0XHRcdHdvcmtzcGFjZTogdGhpcy53b3Jrc3BhY2UsXG5cdFx0XHRidWlsZENvbmZpZzogb3B0aW9ucy5jb25maWd1cmF0aW9uLFxuXHRcdFx0cHJvamVjdDogb3B0aW9ucy5wcm9qZWN0LFxuXHRcdH0pO1xuXHRcdHJldHVybiBBY3Rpb25SZXNwb25zZS5CbG9ja2luZyhTZXJ2ZUFjdGlvbi5uYW1lKTtcblx0fVxufVxuIl0sIm5hbWVzIjpbImluamVjdGFibGUiLCJXb3Jrc3BhY2UiLCJBY3Rpb25SZXNwb25zZSIsIkhvdFJlbG9hZFNlcnZlciIsIlNlcnZlQWN0aW9uIiwic2VydmVyIiwid29ya3NwYWNlIiwicnVuIiwib3B0aW9ucyIsInN0YXJ0IiwiYnVpbGRDb25maWciLCJjb25maWd1cmF0aW9uIiwicHJvamVjdCIsIkJsb2NraW5nIiwibmFtZSJdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7O0FBQUEsU0FBU0EsVUFBVSxRQUFRLGdDQUFnQztBQUMzRCw4Q0FBOEM7QUFDOUMsU0FBU0MsU0FBUyxRQUFRLGlCQUFpQjtBQUMzQyxTQUFzQkMsY0FBYyxRQUFRLHNCQUFzQjtBQUNsRSw4Q0FBOEM7QUFDOUMsU0FBU0MsZUFBZSxRQUFRLHlCQUF5QjtBQVF6RCxPQUFPLE1BQU1DOzs7SUFDWixZQUNDLEFBQWlCQyxNQUF1QixFQUN4QyxBQUFpQkMsU0FBb0IsQ0FDcEM7YUFGZ0JELFNBQUFBO2FBQ0FDLFlBQUFBO0lBQ2Y7SUFFSCxNQUFhQyxJQUFJQyxPQUFxQixFQUEyQjtRQUNoRSxNQUFNLElBQUksQ0FBQ0gsTUFBTSxDQUFDSSxLQUFLLENBQUM7WUFDdkJILFdBQVcsSUFBSSxDQUFDQSxTQUFTO1lBQ3pCSSxhQUFhRixRQUFRRyxhQUFhO1lBQ2xDQyxTQUFTSixRQUFRSSxPQUFPO1FBQ3pCO1FBQ0EsT0FBT1YsZUFBZVcsUUFBUSxDQUFDVCxZQUFZVSxJQUFJO0lBQ2hEO0FBQ0QifQ==

package/es6/src/serve.command.js

@@ -1,4 +1,5 @@
 import { ConfigurationOption, DecohereCommand, ProjectOption } from "@decohere/nexus/cli";
+import { DEFAULT_REBOOT_DEBOUNCE_MS, resolveRebootDebounceMs } from "./hot-reload-server.js";
 import { ServeAction } from "./serve.action.js";
 export class ServeCommand extends DecohereCommand {
     get actions() {
@@ -8,10 +9,37 @@ export class ServeCommand extends DecohereCommand {
     }
     constructor(name){
         super(name);
-        this.description("Serve a project in a workspace configuration");
+        this.description("Serve a project or directory slices (Flux apps in-process; foreign packages via package scripts)");
+        this.argument("[slices...]", "Module directories to serve (e.g. funding shell secmaster, or projects/funding)");
         this.addOption(new ConfigurationOption("debug"));
         this.addOption(new ProjectOption());
+        this.option("--reboot-debounce-ms <ms>", "Quiet window in milliseconds after the last affecting save before a reboot", (value)=>resolveRebootDebounceMs(Number(value)), DEFAULT_REBOOT_DEBOUNCE_MS);
     }
+    /**
+	 * Commander passes positional args before options when `[slices...]` is declared.
+	 * The CLI host ModuleFactory expects `(opts, cmd)` — normalize here.
+	 */ action(fn) {
+        return super.action((...args)=>{
+            const cmd = args.at(-1);
+            const first = args[0];
+            const hasPositionalSlices = Array.isArray(first) || typeof first === "string" || first === undefined;
+            const opts = hasPositionalSlices ? args[1] : args[0];
+            const slices = normalizePositionalSlices(first);
+            if (slices.length > 0) {
+                cmd.setOptionValue("slices", slices);
+            }
+            return fn(opts, cmd);
+        });
+    }
+}
+function normalizePositionalSlices(first) {
+    if (Array.isArray(first)) {
+        return first.filter((s)=>typeof s === "string" && s !== "");
+    }
+    if (typeof first === "string" && first !== "") {
+        return [
+            first
+        ];
+    }
+    return [];
 }
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL2ZsdXgvc3JjL3NlcnZlLmNvbW1hbmQudHMiXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgQ29uZmlndXJhdGlvbk9wdGlvbiwgRGVjb2hlcmVDb21tYW5kLCBQcm9qZWN0T3B0aW9uIH0gZnJvbSBcIkBkZWNvaGVyZS9uZXh1cy9jbGlcIjtcbmltcG9ydCB7IFNlcnZlQWN0aW9uIH0gZnJvbSBcIi4vc2VydmUuYWN0aW9uLmpzXCI7XG5cbmV4cG9ydCBjbGFzcyBTZXJ2ZUNvbW1hbmQgZXh0ZW5kcyBEZWNvaGVyZUNvbW1hbmQge1xuXHRwdWJsaWMgb3ZlcnJpZGUgZ2V0IGFjdGlvbnMoKSB7XG5cdFx0cmV0dXJuIFtTZXJ2ZUFjdGlvbl07XG5cdH1cblxuXHRwdWJsaWMgY29uc3RydWN0b3IobmFtZTogc3RyaW5nKSB7XG5cdFx0c3VwZXIobmFtZSk7XG5cdFx0dGhpcy5kZXNjcmlwdGlvbihcIlNlcnZlIGEgcHJvamVjdCBpbiBhIHdvcmtzcGFjZSBjb25maWd1cmF0aW9uXCIpO1xuXHRcdHRoaXMuYWRkT3B0aW9uKG5ldyBDb25maWd1cmF0aW9uT3B0aW9uKFwiZGVidWdcIikpO1xuXHRcdHRoaXMuYWRkT3B0aW9uKG5ldyBQcm9qZWN0T3B0aW9uKCkpO1xuXHR9XG59XG4iXSwibmFtZXMiOlsiQ29uZmlndXJhdGlvbk9wdGlvbiIsIkRlY29oZXJlQ29tbWFuZCIsIlByb2plY3RPcHRpb24iLCJTZXJ2ZUFjdGlvbiIsIlNlcnZlQ29tbWFuZCIsImFjdGlvbnMiLCJuYW1lIiwiZGVzY3JpcHRpb24iLCJhZGRPcHRpb24iXSwibWFwcGluZ3MiOiJBQUFBLFNBQVNBLG1CQUFtQixFQUFFQyxlQUFlLEVBQUVDLGFBQWEsUUFBUSxzQkFBc0I7QUFDMUYsU0FBU0MsV0FBVyxRQUFRLG9CQUFvQjtBQUVoRCxPQUFPLE1BQU1DLHFCQUFxQkg7SUFDakMsSUFBb0JJLFVBQVU7UUFDN0IsT0FBTztZQUFDRjtTQUFZO0lBQ3JCO0lBRUEsWUFBbUJHLElBQVksQ0FBRTtRQUNoQyxLQUFLLENBQUNBO1FBQ04sSUFBSSxDQUFDQyxXQUFXLENBQUM7UUFDakIsSUFBSSxDQUFDQyxTQUFTLENBQUMsSUFBSVIsb0JBQW9CO1FBQ3ZDLElBQUksQ0FBQ1EsU0FBUyxDQUFDLElBQUlOO0lBQ3BCO0FBQ0QifQ==

package/es6/src/slice-serve.js

@@ -0,0 +1,105 @@
+/**
+ * Directory-slice helpers for `flux serve <dir>…` — classify Mesh packages as
+ * Flux apps, Nixpacks-style script deferrals, or libraries to skip.
+ */ /** Preferred package scripts for foreign toolchains (Nixpacks-style). */ export const DEFER_SCRIPT_CANDIDATES = [
+    "dev",
+    "serve"
+];
+/**
+ * Normalize a CLI slice token to a `projects/…` prefix without a trailing slash.
+ * `funding` and `projects/funding` both become `projects/funding`.
+ */ export function normalizeSlicePrefix(slice) {
+    const trimmed = slice.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (trimmed === "" || trimmed === ".") {
+        throw new Error("Slice directory must be a non-empty path");
+    }
+    if (trimmed === "projects" || trimmed.startsWith("projects/")) {
+        return trimmed;
+    }
+    return `projects/${trimmed}`;
+}
+/**
+ * True when `projectDirectory` belongs to the slice token.
+ *
+ * Matches:
+ * - nested: `projects/funding`, `projects/funding/api`
+ * - flat dotted package dirs: `projects/funding.web` for token `funding`
+ *
+ * Does not match siblings that only share a string prefix (`funding` vs `funding-fee.api`).
+ */ export function isUnderSlice(projectDirectory, slicePrefix) {
+    const dir = projectDirectory.replaceAll("\\", "/").replace(/\/+$/, "");
+    const prefix = slicePrefix.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (dir === prefix || dir.startsWith(`${prefix}/`)) {
+        return true;
+    }
+    // Flat monorepo packages: projects/<module>.<role>
+    return dir.startsWith(`${prefix}.`);
+}
+export function projectsInSlice(projects, slice) {
+    const prefix = normalizeSlicePrefix(slice);
+    return projects.filter((p)=>isUnderSlice(p.projectDirectory, prefix));
+}
+/** Union of packages under any of the slice tokens (deduped by package name). */ export function projectsInSlices(projects, slices) {
+    const byName = new Map();
+    for (const slice of slices){
+        for (const project of projectsInSlice(projects, slice)){
+            byName.set(project.name, project);
+        }
+    }
+    return [
+        ...byName.values()
+    ];
+}
+/** Script invokes Flux (in-process serve stays on Flux, not deferred). */ export function isFluxOwnedScript(script) {
+    return /\bflux\b/i.test(script);
+}
+/**
+ * First Nixpacks-style serve script that is not Flux-owned.
+ * Prefers `dev`, then `serve`.
+ */ export function resolveDeferScript(scripts) {
+    for (const name of DEFER_SCRIPT_CANDIDATES){
+        const body = scripts[name];
+        if (body != null && body !== "" && !isFluxOwnedScript(body)) {
+            return name;
+        }
+    }
+    return undefined;
+}
+/** Convention: Flux Node apps use `main` ending in `main.ts` / `main.tsx`. */ export function isFluxAppMain(main) {
+    const normalized = main.replaceAll("\\", "/");
+    return /(^|\/)main\.tsx?$/.test(normalized);
+}
+/**
+ * Classify one package. Foreign serve scripts win over `main.ts` (Vite apps
+ * often have a main entry but must not be HMR-booted by Flux).
+ */ export function classifySliceProject(project) {
+    if (resolveDeferScript(project.scripts) != null) {
+        return "defer";
+    }
+    if (isFluxAppMain(project.main)) {
+        return "flux";
+    }
+    return "skip";
+}
+export function classifySliceProjects(projects, slices) {
+    const tokens = typeof slices === "string" ? [
+        slices
+    ] : [
+        ...slices
+    ];
+    const inSlice = projectsInSlices(projects, tokens);
+    const flux = [];
+    const defer = [];
+    const skip = [];
+    for (const project of inSlice){
+        const kind = classifySliceProject(project);
+        if (kind === "flux") flux.push(project);
+        else if (kind === "defer") defer.push(project);
+        else skip.push(project);
+    }
+    return {
+        flux,
+        defer,
+        skip
+    };
+}

package/es6/src/source-module-loader.js

@@ -0,0 +1,161 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { registerHooks } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { injectable } from "@decohere/crucible/decorators";
+import { BuildTargets, createWorkspace, SwcTranspiler } from "@decohere/forge";
+import { packageAliases } from "@decohere/mesh";
+import { FileEx, io } from "@decohere/nexus/io";
+import { scribe } from "@decohere/scribe";
+import { rewriteServeSpecifier } from "./rewrite-serve-specifier.js";
+export class SourceModuleLoader {
+    logger = scribe.logger(SourceModuleLoader.name);
+    transpiler = new SwcTranspiler();
+    disposed = false;
+    hooksRegistered = false;
+    workspace;
+    buildConfig = "debug";
+    fileInfoMap = new Map();
+    transpileCache = new Map();
+    aliasPaths = {};
+    aliasBaseUrl = path.resolve(".");
+    versionFileUrl = (fileUrl)=>fileUrl;
+    onResolved;
+    getWorkspace() {
+        return this.workspace;
+    }
+    getBuildConfig() {
+        return this.buildConfig;
+    }
+    hasSourceFile(absolutePath) {
+        return this.fileInfoMap.has(absolutePath);
+    }
+    sourceFilePaths() {
+        return this.fileInfoMap.keys();
+    }
+    setSourceFile(absolutePath, project) {
+        this.fileInfoMap.set(absolutePath, {
+            project
+        });
+    }
+    async configure(options) {
+        this.disposed = false;
+        this.transpileCache.clear();
+        this.buildConfig = options.buildConfig;
+        this.workspace = options.workspace ?? await createWorkspace();
+        this.versionFileUrl = options.versionFileUrl ?? ((fileUrl)=>fileUrl);
+        this.onResolved = options.onResolved;
+        this.fileInfoMap = await this.buildFileInfoMap(this.buildConfig);
+        const aliases = this.workspace.getPackageAliases(this.buildConfig);
+        this.aliasBaseUrl = aliases.baseUrl;
+        this.aliasPaths = aliases.paths;
+    }
+    registerHooks() {
+        if (this.hooksRegistered) return;
+        this.hooksRegistered = true;
+        // Compiled code carries inline source maps; Node only applies them to stack traces when
+        // this is on. Without it, errors point at compiled line numbers (#506).
+        process.setSourceMapsEnabled(true);
+        registerHooks({
+            resolve: (specifier, context, next)=>{
+                if (this.disposed) return next(specifier, context);
+                const parentUrl = context.parentURL ?? "";
+                const rewritten = rewriteServeSpecifier({
+                    specifier,
+                    parentUrl,
+                    isWatchedTs: (filePath)=>this.fileInfoMap.has(filePath),
+                    resolveBare: (bare)=>packageAliases.resolvePath(bare, this.aliasPaths, this.aliasBaseUrl),
+                    versionFileUrl: this.versionFileUrl
+                }) ?? specifier;
+                const result = next(rewritten, context);
+                this.onResolved?.(result, parentUrl);
+                return result;
+            },
+            load: (url, context, next)=>{
+                if (this.disposed) return next(url, context);
+                const result = this.loadTs(url);
+                if (result != null) {
+                    return {
+                        format: "module",
+                        source: result.source,
+                        shortCircuit: true
+                    };
+                }
+                return next(url, context);
+            }
+        });
+    }
+    async importEntry(absolutePath) {
+        const url = this.versionFileUrl(io.pathToFileUrl(path.resolve(absolutePath)));
+        return import(url);
+    }
+    invalidateTranspile(...absolutePaths) {
+        for (const fullPath of absolutePaths){
+            this.transpileCache.delete(fullPath);
+            this.transpiler.invalidateContentCache(new FileEx({
+                fullPath
+            }));
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        this.transpileCache.clear();
+        this.fileInfoMap.clear();
+        this.workspace?.[Symbol.dispose]();
+        this.workspace = undefined;
+    }
+    async buildFileInfoMap(buildConfig) {
+        const projects = this.workspace?.getProjects(buildConfig) ?? [];
+        const entries = await Promise.all(projects.map(async (project)=>{
+            const files = await project.getAllFiles();
+            return files.map((file)=>[
+                    file.fullPath,
+                    {
+                        project
+                    }
+                ]);
+        }));
+        return new Map(entries.flat());
+    }
+    loadTs(url) {
+        if (!url.startsWith("file:")) return null;
+        // fileURLToPath, not URL.pathname: decodes %20 and gives Windows paths, so files
+        // whose path has a space still match Mesh's list (#511).
+        const cleanPath = fileURLToPath(url);
+        const fileInfo = this.fileInfoMap.get(cleanPath);
+        if (fileInfo == null) return null;
+        const cached = this.transpileCache.get(cleanPath);
+        if (cached != null) return {
+            source: cached
+        };
+        const { project } = fileInfo;
+        const tsConfig = project.getTsConfigSync();
+        const userConfig = project.getSwcConfigSync();
+        const file = new FileEx({
+            fullPath: cleanPath
+        });
+        const response = this.transpiler.transformFileSync(file, BuildTargets.es6, {
+            tsConfig,
+            aliasPaths: true,
+            userConfig,
+            workspace: this.workspace,
+            projects: this.workspace?.getProjects(this.buildConfig)
+        });
+        if (response.outcome !== "success") {
+            this.logger.error(`Failed to transpile ${cleanPath}`, response);
+            throw new Error(`Failed to transpile ${cleanPath}`);
+        }
+        this.transpileCache.set(cleanPath, response.code);
+        return {
+            source: response.code
+        };
+    }
+}
+SourceModuleLoader = _ts_decorate([
+    injectable()
+], SourceModuleLoader);

package/package.json

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

package/types/src/deferred-script-runner.d.ts

@@ -0,0 +1,18 @@
+import { type ChildProcess } from "node:child_process";
+export type DeferredScriptStart = {
+    readonly label: string;
+    readonly cwd: string;
+    readonly script: string;
+    /** Workspace root used to detect pnpm/npm/yarn. */
+    readonly workspaceRoot: string;
+};
+/**
+ * Nixpacks-style child processes for foreign packages in a flux serve slice.
+ * Killed when the Flux container disposes (SIGINT → RootModule teardown).
+ */
+export declare class DeferredScriptRunner implements AsyncDisposable {
+    private readonly logger;
+    private readonly children;
+    start(options: DeferredScriptStart): ChildProcess;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/types/src/flux.d.ts

@@ -0,0 +1,43 @@
+import type { Workspace } from "@decohere/mesh";
+import { HotReloadServer } from "./hot-reload-server.js";
+export type FluxRunOptions = {
+    /** Mesh/Forge configuration name. Defaults to `debug` (`--configuration`). */
+    configuration?: string;
+    /** Arguments forwarded to the entry (bin-style `process.argv.slice(2)`). */
+    args?: string[];
+    /**
+     * Pre-built Workspace instead of `WorkspaceFactory`.
+     * Useful in tests to skip filesystem discovery.
+     */
+    workspace?: Workspace;
+};
+export type FluxServeOptions = {
+    /** Mesh/Forge configuration name. Defaults to `debug` (`--configuration`). */
+    configuration?: string;
+    /** Name of the project to serve. Defaults to the first project in the workspace. */
+    project?: string;
+    /**
+     * Multiple Flux app package names to boot in one process (directory slice).
+     * When set, takes precedence over {@link project}.
+     */
+    projects?: readonly string[];
+    /**
+     * Pre-built Workspace instead of `WorkspaceFactory`.
+     * Useful in tests to skip filesystem discovery.
+     */
+    workspace?: Workspace;
+    /**
+     * Quiet window in milliseconds after the last affecting save before a reboot.
+     * Raise this for agent save trains.
+     */
+    rebootDebounceMs?: number;
+};
+declare function run(entry: string, options?: FluxRunOptions): Promise<unknown>;
+declare function serve(options?: FluxServeOptions): Promise<HotReloadServer>;
+declare function dispose(): void;
+export declare const flux: {
+    run: typeof run;
+    serve: typeof serve;
+    dispose: typeof dispose;
+};
+export {};

package/types/src/flux.module.d.ts

@@ -2,12 +2,14 @@ import type { WorkspaceFactoryOptions } from "@decohere/nexus/cli";
 import { ModuleManifest } from "@decohere/nexus/cli";
 import type { ContainerBuilder } from "@decohere/nexus/composition";
 import { FluxCommand } from "./flux.command.js";
+import { RunAction } from "./run.action.js";
 import { ServeAction } from "./serve.action.js";
 export declare class FluxModule extends ModuleManifest {
     readonly id = "flux";
     readonly command: typeof FluxCommand;
     readonly actions: {
         serve: typeof ServeAction;
+        run: typeof RunAction;
     };
     registerServices(builder: ContainerBuilder): void;
     createWorkspace(options: WorkspaceFactoryOptions): Promise<import("@decohere/mesh").Workspace>;