@decohere/flux 0.0.1-dev.13 → 0.0.1-dev.130

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

@@ -0,0 +1,332 @@
+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 { existsSync, readFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { injectable } from "@decohere/crucible/decorators";
+import { BuildTargets, createWorkspace, SwcTranspiler } from "@decohere/forge";
+import { packageAliases, sourceExtensions } from "@decohere/workspace";
+import { FileEx, io } from "@decohere/core/io";
+import { scribe } from "@decohere/scribe";
+import { rewriteServeSpecifier } from "./rewrite-serve-specifier.js";
+import { staticImports } from "./static-imports.js";
+import { TranspileDiskCache } from "./transpile-disk-cache.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();
+    /** Bumped when a file's cached code is dropped, so an up-front compile already running can't put it back. */ transpileVersions = new Map();
+    /** The source files each entry's walk reached, so a reboot only walks out from what changed. */ reachedFrom = new Map();
+    /** Compiled code on disk across runs; null when caching is off. */ diskCache = null;
+    /** Up-front compiles in flight, shared by entries booting at the same time. */ compilingAhead = new Map();
+    /** SWC options per project, built on first use and kept until the next `configure()`. */ swcConfigs = new Map();
+    commonJsConfigs = new Map();
+    aliasPaths = {};
+    aliasBaseUrl = path.resolve(".");
+    versionFileUrl = (fileUrl)=>fileUrl;
+    onResolved;
+    getWorkspace() {
+        return this.workspace;
+    }
+    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;
+        // A new Map, not clear(): an up-front compile from before can't write into this one.
+        this.transpileCache = new Map();
+        this.reachedFrom = new Map();
+        this.swcConfigs.clear();
+        this.commonJsConfigs.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);
+        this.diskCache = TranspileDiskCache.forWorkspace(this.workspace.rootDir);
+        // In the background; it turns the cache off, with a warning, rather than throw.
+        void this.diskCache?.pruneIfDue();
+        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.
+        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.sourceInfo(filePath) != null,
+                    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: result.format,
+                        source: result.source,
+                        shortCircuit: true
+                    };
+                }
+                return next(url, context);
+            }
+        });
+    }
+    async importEntry(absolutePath) {
+        await this.compileAhead(path.resolve(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.transpileVersions.set(fullPath, (this.transpileVersions.get(fullPath) ?? 0) + 1);
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        this.transpileCache = new Map();
+        this.reachedFrom = new Map();
+        this.swcConfigs.clear();
+        this.commonJsConfigs.clear();
+        this.fileInfoMap.clear();
+        this.workspace?.[Symbol.dispose]();
+        this.workspace = undefined;
+    }
+    /**
+	 * The file as a source flux compiles: a workspace package's file, or any other TypeScript
+	 * source on disk outside `node_modules`, which Node would otherwise only strip of types, failing
+	 * on enums, decorators and parameter properties. Null for everything else.
+	 */ sourceInfo(fullPath) {
+        const fileInfo = this.fileInfoMap.get(fullPath);
+        if (fileInfo != null) return fileInfo;
+        const outsidePackages = sourceExtensions.isSource(fullPath) && !fullPath.split(/[/\\]/).includes("node_modules") && existsSync(fullPath);
+        return outsidePackages ? {} : null;
+    }
+    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());
+    }
+    /**
+	 * Compiles the entry and the source files it imports, before Node imports it. The load
+	 * hook is synchronous, so it would compile one file at a time on the main thread; async SWC
+	 * runs on the thread pool. Walks out from the entry, compiling each file's imports in parallel,
+	 * so files the app never imports (tests, other apps) are not compiled. A reboot walks out only
+	 * from the files it reached before that are no longer cached (the saved ones), so their new
+	 * imports are found without visiting the rest of the graph again.
+	 *
+	 * A file that fails here is left out of the cache instead of failing the boot: the load hook
+	 * then compiles it again and throws as before, naming the file. The walk is a hint; whatever
+	 * it misses is compiled by the load hook when Node gets to it.
+	 */ async compileAhead(entryPath) {
+        const reached = this.reachedFrom.get(entryPath);
+        const starts = reached == null ? [
+            entryPath
+        ] : [
+            ...reached
+        ].filter((fullPath)=>!this.transpileCache.has(fullPath));
+        const seen = new Set(reached);
+        for (const start of starts)seen.delete(start);
+        const visit = async (fullPath)=>{
+            if (seen.has(fullPath)) return;
+            seen.add(fullPath);
+            const code = await this.compiledAhead(fullPath);
+            if (code == null) return;
+            const parentUrl = pathToFileURL(fullPath).toString();
+            await Promise.all(staticImports.scan(code).map((specifier)=>{
+                const target = this.sourcePathOf(specifier, parentUrl);
+                return target == null ? undefined : visit(target);
+            }));
+        };
+        await Promise.all(starts.map(visit));
+        this.reachedFrom.set(entryPath, seen);
+    }
+    /** The file's compiled code, from the cache or compiled now; undefined if it isn't a source. */ compiledAhead(fullPath) {
+        const fileInfo = this.sourceInfo(fullPath);
+        if (fileInfo == null) return Promise.resolve(undefined);
+        const cached = this.transpileCache.get(fullPath);
+        if (cached != null) return Promise.resolve(cached);
+        const inFlight = this.compilingAhead.get(fullPath);
+        if (inFlight != null) return inFlight;
+        const version = this.transpileVersions.get(fullPath);
+        const cache = this.transpileCache;
+        const compiling = this.compileAsync(fullPath, fileInfo.project).then((code)=>{
+            if (code == null) return undefined;
+            // Saved, reconfigured or disposed while compiling: don't cache stale code.
+            const current = !this.disposed && cache === this.transpileCache && version === this.transpileVersions.get(fullPath);
+            if (current) cache.set(fullPath, code);
+            return code;
+        }).finally(()=>this.compilingAhead.delete(fullPath));
+        this.compilingAhead.set(fullPath, compiling);
+        return compiling;
+    }
+    /** The source file a specifier names, mapped the way the resolve hook maps it. */ sourcePathOf(specifier, parentUrl) {
+        const url = rewriteServeSpecifier({
+            specifier,
+            parentUrl,
+            isWatchedTs: (filePath)=>this.sourceInfo(filePath) != null,
+            resolveBare: (bare)=>packageAliases.resolvePath(bare, this.aliasPaths, this.aliasBaseUrl),
+            versionFileUrl: (fileUrl)=>fileUrl
+        });
+        return url == null ? null : fileURLToPath(url);
+    }
+    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 the workspace's package list.
+        const cleanPath = fileURLToPath(url);
+        const fileInfo = this.sourceInfo(cleanPath);
+        if (fileInfo == null) return null;
+        const format = sourceExtensions.isCommonJs(cleanPath) ? "commonjs" : "module";
+        const cached = this.transpileCache.get(cleanPath);
+        if (cached != null) return {
+            source: cached,
+            format
+        };
+        const code = this.compileSync(cleanPath, fileInfo.project);
+        this.transpileCache.set(cleanPath, code);
+        return {
+            source: code,
+            format
+        };
+    }
+    /**
+	 * Compiles a file for the load hook, through the disk cache. Throws, naming the file,
+	 * when it can't be read or doesn't compile.
+	 */ compileSync(fullPath, project) {
+        const file = new FileEx({
+            fullPath
+        });
+        const baseConfig = this.swcConfigFor(project, fullPath);
+        let source;
+        try {
+            source = readFileSync(fullPath, "utf8");
+        } catch (error) {
+            this.logger.error(`Failed to transpile ${fullPath}`, error);
+            throw new Error(`Failed to transpile ${fullPath}`, {
+                cause: error
+            });
+        }
+        const key = this.diskCache?.keyFor(fullPath, source, baseConfig);
+        const hit = key == null ? undefined : this.diskCache?.readSync(key);
+        if (hit != null) return hit;
+        const response = this.transpiler.transformCodeSync(source, file, BuildTargets.es6, baseConfig);
+        if (response.outcome !== "success") {
+            this.logger.error(`Failed to transpile ${fullPath}`, response);
+            throw new Error(`Failed to transpile ${fullPath}`);
+        }
+        if (key != null) this.diskCache?.writeSync(key, response.code);
+        return response.code;
+    }
+    /**
+	 * Compiles a file ahead, through the disk cache; undefined when it doesn't compile, which the
+	 * load hook then reports (see {@link compileAhead}). The source and the cache entry are read
+	 * synchronously: for small files that is far cheaper than a trip through libuv's thread pool,
+	 * which async SWC needs for the compiles that miss.
+	 */ async compileAsync(fullPath, project) {
+        const file = new FileEx({
+            fullPath
+        });
+        const baseConfig = this.swcConfigFor(project, fullPath);
+        let source;
+        try {
+            source = readFileSync(fullPath, "utf8");
+        } catch  {
+            // Left to the load hook, which reads it again and fails naming it, as for a file
+            // that doesn't compile.
+            return undefined;
+        }
+        const key = this.diskCache?.keyFor(fullPath, source, baseConfig);
+        const hit = key == null ? undefined : this.diskCache?.readSync(key);
+        if (hit != null) return hit;
+        const response = await this.transpiler.transformCode(source, file, BuildTargets.es6, baseConfig);
+        if (response.outcome !== "success") return undefined;
+        if (key != null) await this.diskCache?.write(key, response.code);
+        return response.code;
+    }
+    /**
+	 * The project's SWC options, built once: rebuilding them for every file was about a quarter
+	 * of load time. Import specifiers are left as written, without `jsc.paths` or
+	 * `resolveFully`: the resolve hook maps them to source files (aliases, `.js` to `.ts`,
+	 * directory indexes), so SWC does not resolve them a second time against the disk.
+	 */ swcConfigFor(project, fullPath) {
+        const config = this.esModuleConfigFor(project);
+        if (!sourceExtensions.isCommonJs(fullPath)) return config;
+        // `.cts` is CommonJS: Node loads it with `require` semantics, so SWC emits CommonJS.
+        // Kept per project, like the ES module options, so the disk cache hashes them once.
+        const cached = this.commonJsConfigs.get(project);
+        if (cached != null) return cached;
+        const commonJs = {
+            ...config,
+            module: {
+                type: "commonjs"
+            }
+        };
+        this.commonJsConfigs.set(project, commonJs);
+        return commonJs;
+    }
+    /** Forge's defaults when there is no project: decorators and their metadata on. */ esModuleConfigFor(project) {
+        const cached = this.swcConfigs.get(project);
+        if (cached != null) return cached;
+        const base = this.transpiler.createBaseConfig(BuildTargets.es6, {
+            tsConfig: project?.getTsConfigSync(),
+            userConfig: project?.getSwcConfigSync(),
+            aliasPaths: false,
+            workspace: this.workspace
+        });
+        // `module` is the ES module config (`type: "es6"` above); the spread loses the narrowing.
+        const module = {
+            ...base.module,
+            resolveFully: false
+        };
+        const config = {
+            ...base,
+            module
+        };
+        this.swcConfigs.set(project, config);
+        return config;
+    }
+}
+SourceModuleLoader = _ts_decorate([
+    injectable()
+], SourceModuleLoader);

package/es6/src/static-imports.js

@@ -0,0 +1,27 @@
+/**
+ * The module specifiers a compiled ES module names in `import … from`, `export … from`, bare
+ * `import "x"` and literal `import("x")`.
+ *
+ * Only a hint for compiling ahead: a specifier it misses is compiled when Node loads it,
+ * and one it finds by mistake (an import written inside a string) costs one extra compile. So a
+ * scan of SWC's output is enough; it never decides what runs.
+ */ const STATIC = /\b(?:import|export)\s*(?:[\w$*{},\s]+?\s*from\s*)?["']([^"'\n]+)["']/g;
+const DYNAMIC = /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/g;
+function scan(code) {
+    const found = new Set();
+    for (const pattern of [
+        STATIC,
+        DYNAMIC
+    ]){
+        for (const match of code.matchAll(pattern)){
+            const specifier = match[1];
+            if (specifier != null) found.add(specifier);
+        }
+    }
+    return [
+        ...found
+    ];
+}
+export const staticImports = {
+    scan
+};

package/es6/src/transpile-disk-cache.js

@@ -0,0 +1,142 @@
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { transpileCache } from "@decohere/forge";
+import { scribe } from "@decohere/scribe";
+/** Bump when what flux stores changes, so older entries stop matching. */ const FORMAT = 1;
+/** Entries untouched for this long are pruned. */ const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+/** Pruning runs at most this often, recorded by the mtime of a marker file. */ const PRUNE_EVERY_MS = 24 * 60 * 60 * 1000;
+const PRUNE_MARKER = ".last-prune";
+/**
+ * Compiled code on disk, so a cold start doesn't compile files that haven't changed.
+ * Content-addressed: the key hashes the file's path and source, the SWC options it compiles
+ * with, SWC's version and this cache's format, so any change to those is a miss, never a stale
+ * hit. Entries are written to a temp file and renamed into place, so a process reading an entry
+ * another is writing sees all of it or none.
+ *
+ * The cache is an optimisation: if it can't read or write its directory, it says so once and
+ * turns itself off for the process, and flux compiles as it would without it.
+ */ export class TranspileDiskCache {
+    dir;
+    logger = scribe.logger(TranspileDiskCache.name);
+    disabled = false;
+    constructor(dir){
+        this.dir = dir;
+    }
+    /** The cache for a workspace, or null when caching is off (`DECOHERE_CACHE=0`). */ static forWorkspace(rootDir) {
+        const base = transpileCache.directory(rootDir);
+        return base == null ? null : new TranspileDiskCache(path.join(base, "flux"));
+    }
+    get directory() {
+        return this.dir;
+    }
+    /**
+	 * The key for a file compiled with `baseOptions`: the per-file options are those plus the
+	 * file's path (forge's `createFileConfig`), so hashing the base once per project and adding
+	 * the path covers them without serialising options for every file.
+	 */ keyFor(fullPath, source, baseOptions) {
+        return createHash("sha256").update(`${FORMAT}\0${transpileCache.swcVersion}\0${this.optionsHash(baseOptions)}\0`).update(`${fullPath}\0`).update(source).digest("hex");
+    }
+    optionsHashes = new WeakMap();
+    optionsHash(options) {
+        const cached = this.optionsHashes.get(options);
+        if (cached != null) return cached;
+        const hash = createHash("sha256").update(JSON.stringify(options)).digest("hex");
+        this.optionsHashes.set(options, hash);
+        return hash;
+    }
+    readSync(key) {
+        if (this.disabled) return undefined;
+        try {
+            return fs.readFileSync(this.entryPath(key), "utf8");
+        } catch (error) {
+            return this.missOrDisable(error);
+        }
+    }
+    async read(key) {
+        if (this.disabled) return undefined;
+        try {
+            return await fs.promises.readFile(this.entryPath(key), "utf8");
+        } catch (error) {
+            return this.missOrDisable(error);
+        }
+    }
+    writeSync(key, code) {
+        if (this.disabled) return;
+        const file = this.entryPath(key);
+        const temp = this.tempPath(file);
+        try {
+            fs.mkdirSync(path.dirname(file), {
+                recursive: true
+            });
+            fs.writeFileSync(temp, code);
+            fs.renameSync(temp, file);
+        } catch (error) {
+            this.disable("write", error);
+        }
+    }
+    async write(key, code) {
+        if (this.disabled) return;
+        const file = this.entryPath(key);
+        const temp = this.tempPath(file);
+        try {
+            await fs.promises.mkdir(path.dirname(file), {
+                recursive: true
+            });
+            await fs.promises.writeFile(temp, code);
+            await fs.promises.rename(temp, file);
+        } catch (error) {
+            this.disable("write", error);
+        }
+    }
+    /** Deletes entries older than 30 days, if it hasn't done so in the last day. */ async pruneIfDue(now = Date.now()) {
+        if (this.disabled) return;
+        const marker = path.join(this.dir, PRUNE_MARKER);
+        try {
+            const last = await fs.promises.stat(marker).then((stat)=>stat.mtimeMs, (error)=>{
+                if (error.code === "ENOENT") return 0;
+                throw error;
+            });
+            if (now - last < PRUNE_EVERY_MS) return;
+            await fs.promises.mkdir(this.dir, {
+                recursive: true
+            });
+            await fs.promises.writeFile(marker, "");
+            for (const shard of (await fs.promises.readdir(this.dir, {
+                withFileTypes: true
+            }))){
+                if (!shard.isDirectory()) continue;
+                const shardDir = path.join(this.dir, shard.name);
+                for (const entry of (await fs.promises.readdir(shardDir))){
+                    // Old entries, and temp files a crashed process left mid-write.
+                    const file = path.join(shardDir, entry);
+                    const mtime = await fs.promises.stat(file).then((stat)=>stat.mtimeMs, (error)=>{
+                        // Renamed or removed by another process since the listing: nothing to prune.
+                        if (error.code === "ENOENT") return undefined;
+                        throw error;
+                    });
+                    if (mtime != null && now - mtime > MAX_AGE_MS) await fs.promises.rm(file, {
+                        force: true
+                    });
+                }
+            }
+        } catch (error) {
+            this.disable("prune", error);
+        }
+    }
+    entryPath(key) {
+        return path.join(this.dir, key.slice(0, 2), `${key}.js`);
+    }
+    tempPath(file) {
+        return `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    }
+    /** A missing entry is a miss; any other read error turns the cache off. */ missOrDisable(error) {
+        if (error.code !== "ENOENT") this.disable("read", error);
+        return undefined;
+    }
+    disable(operation, error) {
+        if (this.disabled) return;
+        this.disabled = true;
+        this.logger.warn(`Transpile cache turned off for this run: could not ${operation} ${this.dir} (${String(error)}). ` + "Flux compiles without it. Set DECOHERE_CACHE_DIR to a writable directory, or DECOHERE_CACHE=0 to silence this.");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/flux",
-  "version": "0.0.1-dev.13",
+  "version": "0.0.1-dev.130",
   "description": "Hot module reload server for Node.js ESM applications",
   "keywords": [
     "typescript",
@@ -11,6 +11,15 @@
     "watch",
     "decohere"
   ],
+  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/flux#readme",
+  "bugs": {
+    "url": "https://github.com/typesmiths/decohere/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typesmiths/decohere.git",
+    "directory": "projects/flux"
+  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -25,11 +34,13 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/crucible": "0.0.1-dev.13",
-    "@decohere/forge": "0.0.1-dev.13",
-    "@decohere/mesh": "0.0.1-dev.13",
-    "@decohere/nexus": "0.0.1-dev.13",
-    "@decohere/scribe": "0.0.1-dev.13",
+    "@decohere/core": "0.0.1-dev.130",
+    "@decohere/crucible": "0.0.1-dev.130",
+    "@decohere/devkit": "0.0.1-dev.130",
+    "@decohere/forge": "0.0.1-dev.130",
+    "@decohere/scribe": "0.0.1-dev.130",
+    "@decohere/workspace": "0.0.1-dev.130",
+    "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.command.d.ts

@@ -1,5 +1,5 @@
-import type { Actions } from "@decohere/nexus/cli";
-import { type CommandHandler, type CommandResponse, type CommandType, DecohereCommand } from "@decohere/nexus/cli";
+import type { Actions } from "@decohere/devkit/cli";
+import { type CommandHandler, type CommandResponse, type CommandType, DecohereCommand } from "@decohere/devkit/cli";
 export declare class FluxCommand extends DecohereCommand {
     constructor(commands: Record<string, CommandType>, handler: CommandHandler);
     run(_actions: Actions, _options: never): Promise<CommandResponse>;

package/types/src/flux.d.ts

@@ -0,0 +1,43 @@
+import type { Workspace } from "@decohere/workspace";
+import { HotReloadServer } from "./hot-reload-server.js";
+export type FluxRunOptions = {
+    /** Workspace 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 = {
+    /** Workspace 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

@@ -1,14 +1,16 @@
-import type { WorkspaceFactoryOptions } from "@decohere/nexus/cli";
-import { ModuleManifest } from "@decohere/nexus/cli";
-import type { ContainerBuilder } from "@decohere/nexus/composition";
+import type { WorkspaceFactoryOptions } from "@decohere/devkit/cli";
+import { ModuleManifest } from "@decohere/devkit/cli";
+import type { ContainerBuilder } from "@decohere/core/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>;
+    createWorkspace(options: WorkspaceFactoryOptions): Promise<import("@decohere/workspace").Workspace>;
 }