@decohere/flux 0.0.1-dev.11 → 0.0.1-dev.111

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 (#661): 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/flux",
-  "version": "0.0.1-dev.11",
+  "version": "0.0.1-dev.111",
   "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.11",
-    "@decohere/forge": "0.0.1-dev.11",
-    "@decohere/mesh": "0.0.1-dev.11",
-    "@decohere/nexus": "0.0.1-dev.11",
-    "@decohere/scribe": "0.0.1-dev.11",
+    "@decohere/crucible": "0.0.1-dev.111",
+    "@decohere/forge": "0.0.1-dev.111",
+    "@decohere/mesh": "0.0.1-dev.111",
+    "@decohere/nexus": "0.0.1-dev.111",
+    "@decohere/scribe": "0.0.1-dev.111",
+    "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>;

package/types/src/hot-reload-server.d.ts

@@ -1,5 +1,12 @@
 import { EventEmitter } from "node:events";
 import type { Workspace } from "@decohere/mesh";
+/** Default quiet window before a file-change reboot. */
+export declare const DEFAULT_REBOOT_DEBOUNCE_MS = 250;
+export declare function resolveRebootDebounceMs(value: number | undefined): number;
+/** Info-level HMR start block — keep `flux reboot` in the text so operators can search the buffer. */
+export declare function formatFluxRebootStart(labels: readonly string[], triggers?: readonly string[]): string;
+/** Info-level HMR finish block. */
+export declare function formatFluxRebootReady(labels: readonly string[], elapsedMs: number): string;
 export interface HotReloadServerEvents {
     start: [];
     reboot: [];
@@ -9,56 +16,82 @@ export interface HotReloadServerOptions {
     buildConfig: 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 instance to use instead of running WorkspaceFactory.
      * Useful in tests to bypass filesystem-based workspace discovery.
      */
     workspace?: Workspace;
+    /**
+     * Quiet window in milliseconds after the last affecting save before a reboot.
+     * Defaults to {@link DEFAULT_REBOOT_DEBOUNCE_MS}. Raise this for agent save trains.
+     */
+    rebootDebounceMs?: number;
 }
 export declare class HotReloadServer extends EventEmitter<HotReloadServerEvents> {
     private readonly logger;
+    private readonly loader;
     private disposed;
-    private hooksRegistered;
-    private entryModulePath;
-    private entryModule?;
-    private workspace?;
+    /** Absolute entry paths currently served (one or more Flux apps). */
+    private entries;
+    private pendingEntryReboots;
+    /** Source paths that scheduled the next reboot (cleared when that reboot starts). */
+    private pendingTriggers;
     private watchSubscription?;
-    /** Map from absolute .ts source file path to project info */
-    private fileInfoMap;
     private moduleCache;
     private dependencies;
-    private transpileCache;
-    private transpiler;
+    private rebootTail;
+    private rebootDebounceGen;
+    private rebootInFlight;
+    private rebootFollowUp;
+    private rebootQueued;
+    /** Modules whose reverse-graph edges are pruned at reboot, not on schedule. */
+    private pendingGraphPrune;
+    private scheduleReboot;
     start(options: HotReloadServerOptions): Promise<void>;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
+    private bootEntries;
     private bootEntry;
-    private reboot;
+    private bindScheduleReboot;
+    private requestReboot;
+    private runReboot;
+    private disposeEntries;
     private disposeEntry;
-    private scheduleReboot;
-    private resolveWorkspace;
-    private resolveProject;
-    private buildFileInfoMap;
-    private registerHooks;
-    /**
-     * Pre-next specifier rewriter: if specifier is a .js import that maps to a
-     * known .ts source file, returns the versioned .ts file URL so next() never
-     * tries to load a non-existent .js file from disk.
-     */
-    private rewriteJsToTs;
+    private requireWorkspace;
+    private resolveProjects;
     /**
      * Post-next dependency tracker: records which source files import which
      * other source files so that reloadIfAffected can traverse the graph.
      */
     private onPostResolve;
-    private loadTs;
     private onFileChange;
+    /**
+     * A failed boot (e.g. importing a file that doesn't exist yet) may have recorded no
+     * dependency edges, so the graph can't tell whether this save fixes it. Any source
+     * add or change retries failed entries (#512).
+     */
+    private retryFailedEntries;
     private reloadIfAffected;
+    /**
+     * Every module that imports `moduleId`, directly or transitively. Visits each module
+     * once: import graphs share modules (diamonds) and may legally contain cycles (#515).
+     */
     private getDependencyGraph;
     private trackDependency;
     private getCachedOrNew;
     private versionModule;
-    private invalidateModule;
+    private invalidateModuleCaches;
+    private prunePendingDependencyEdges;
+    /** Remove these modules as parents so boot can rebuild edges without stale importers. */
+    private pruneDependencyParents;
     private invalidateAllSourceFiles;
     private isSelf;
+    private labelsFor;
+    private takeTriggers;
+    private formatTrigger;
 }

package/types/src/index.d.ts

@@ -1,4 +1,11 @@
+export { DeferredScriptRunner } from "./deferred-script-runner.js";
+export type { FluxRunOptions, FluxServeOptions } from "./flux.js";
+export { flux } from "./flux.js";
 export { FluxModule } from "./flux.module.js";
 export type { HotReloadServerOptions } from "./hot-reload-server.js";
-export { HotReloadServer } from "./hot-reload-server.js";
+export { DEFAULT_REBOOT_DEBOUNCE_MS, HotReloadServer } from "./hot-reload-server.js";
+export type { RunOptions } from "./run.action.js";
 export type { ServeOptions } from "./serve.action.js";
+export { type ClassifiedSlice, classifySliceProject, classifySliceProjects, normalizeSlicePrefix, projectsInSlice, projectsInSlices, resolveDeferScript, type SliceKind, type SliceProjectView, } from "./slice-serve.js";
+export type { SourceModuleLoaderOptions } from "./source-module-loader.js";
+export { SourceModuleLoader } from "./source-module-loader.js";

package/types/src/rewrite-serve-specifier.d.ts

@@ -0,0 +1,14 @@
+export type RewriteServeSpecifierOptions = {
+    specifier: string;
+    parentUrl: string;
+    isWatchedTs: (absolutePath: string) => boolean;
+    resolveBare: (specifier: string) => string | null;
+    versionFileUrl: (fileUrl: string) => string;
+};
+/**
+ * Map a resolve-hook specifier to a versioned watched `.ts` file URL.
+ * Covers relative `.js` / `.ts` / extensionless imports, directory imports (`./models` is
+ * `./models/index.ts`), and bare workspace package names and subpaths. Flux compiles without
+ * SWC's own path resolution, so this is the only place imports are mapped to sources (#513).
+ */
+export declare function rewriteServeSpecifier(options: RewriteServeSpecifierOptions): string | null;

package/types/src/run.action.d.ts

@@ -0,0 +1,15 @@
+import { Workspace } from "@decohere/mesh";
+import { type Action, ActionResponse } from "@decohere/nexus/cli";
+export type RunOptions = {
+    /** Absolute or cwd-relative path to a `.ts` entry file. */
+    entry: string;
+    configuration: string;
+    /** Arguments forwarded to the entry (bin-style `process.argv.slice(2)`). */
+    args?: string[];
+};
+export declare class RunAction implements Action<RunOptions> {
+    private readonly workspace;
+    private readonly logger;
+    constructor(workspace: Workspace);
+    run(options: RunOptions): Promise<ActionResponse>;
+}

package/types/src/run.command.d.ts

@@ -0,0 +1,11 @@
+import { DecohereCommand } from "@decohere/nexus/cli";
+import { RunAction } from "./run.action.js";
+export declare class RunCommand extends DecohereCommand {
+    get actions(): (typeof RunAction)[];
+    constructor(name: string);
+    /**
+     * 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: (...args: any[]) => void | Promise<void>): this;
+}

package/types/src/serve.action.d.ts

@@ -1,13 +1,23 @@
 import { Workspace } from "@decohere/mesh";
 import { type Action, ActionResponse } from "@decohere/nexus/cli";
+import { DeferredScriptRunner } from "./deferred-script-runner.js";
 import { HotReloadServer } from "./hot-reload-server.js";
 export type ServeOptions = {
     configuration: string;
     project?: string;
+    /** One or more module directory tokens (`funding`, `shell`, `projects/funding`). */
+    slices?: string[];
+    rebootDebounceMs?: number;
 };
 export declare class ServeAction implements Action<ServeOptions> {
     private readonly server;
     private readonly workspace;
-    constructor(server: HotReloadServer, workspace: Workspace);
+    private readonly deferredScripts;
+    private readonly logger;
+    constructor(server: HotReloadServer, workspace: Workspace, deferredScripts: DeferredScriptRunner);
     run(options: ServeOptions): Promise<ActionResponse>;
+    private runSlices;
+    private toSliceViews;
+    private toSliceView;
+    private findProject;
 }

package/types/src/serve.command.d.ts

@@ -3,4 +3,10 @@ import { ServeAction } from "./serve.action.js";
 export declare class ServeCommand extends DecohereCommand {
     get actions(): (typeof ServeAction)[];
     constructor(name: string);
+    runsUntilStopped(): boolean;
+    /**
+     * Commander passes positional args before options when `[slices...]` is declared.
+     * The CLI host ModuleFactory expects `(opts, cmd)` — normalize here.
+     */
+    action(fn: (...args: any[]) => void | Promise<void>): this;
 }

package/types/src/slice-serve.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Directory-slice helpers for `flux serve <dir>…` — classify Mesh packages as
+ * Flux apps, Nixpacks-style script deferrals, or libraries to skip.
+ */
+export type SliceProjectView = {
+    readonly name: string;
+    /** Relative project dir from workspace root (e.g. `projects/funding/api`). */
+    readonly projectDirectory: string;
+    readonly main: string;
+    readonly scripts: Record<string, string>;
+};
+export type SliceKind = "flux" | "defer" | "skip";
+export type ClassifiedSlice = {
+    readonly flux: SliceProjectView[];
+    readonly defer: SliceProjectView[];
+    readonly skip: SliceProjectView[];
+};
+/** Preferred package scripts for foreign toolchains (Nixpacks-style). */
+export declare const DEFER_SCRIPT_CANDIDATES: readonly ["dev", "serve"];
+/**
+ * Normalize a CLI slice token to a `projects/…` prefix without a trailing slash.
+ * `funding` and `projects/funding` both become `projects/funding`.
+ */
+export declare function normalizeSlicePrefix(slice: string): string;
+/**
+ * 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 declare function isUnderSlice(projectDirectory: string, slicePrefix: string): boolean;
+export declare function projectsInSlice(projects: readonly SliceProjectView[], slice: string): SliceProjectView[];
+/** Union of packages under any of the slice tokens (deduped by package name). */
+export declare function projectsInSlices(projects: readonly SliceProjectView[], slices: readonly string[]): SliceProjectView[];
+/** Script invokes Flux (in-process serve stays on Flux, not deferred). */
+export declare function isFluxOwnedScript(script: string): boolean;
+/**
+ * First Nixpacks-style serve script that is not Flux-owned.
+ * Prefers `dev`, then `serve`.
+ */
+export declare function resolveDeferScript(scripts: Record<string, string>): string | undefined;
+/** Convention: Flux Node apps use `main` ending in `main.ts` / `main.tsx`. */
+export declare function isFluxAppMain(main: string): boolean;
+/**
+ * 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 declare function classifySliceProject(project: SliceProjectView): SliceKind;
+export declare function classifySliceProjects(projects: readonly SliceProjectView[], slices: string | readonly string[]): ClassifiedSlice;

package/types/src/source-module-loader.d.ts

@@ -0,0 +1,81 @@
+import type { ResolveFnOutput } from "node:module";
+import type { Project, Workspace } from "@decohere/mesh";
+export interface SourceModuleLoaderOptions {
+    /** Build configuration name. */
+    buildConfig: string;
+    /**
+     * Pre-built Workspace instance to use instead of running WorkspaceFactory.
+     * Useful in tests to bypass filesystem-based workspace discovery.
+     */
+    workspace?: Workspace;
+    /**
+     * Map a watched `.ts` file URL for ESM resolution.
+     * Hot reload passes a `?version=` bust; one-shot run uses identity.
+     */
+    versionFileUrl?: (fileUrl: string) => string;
+    /** Optional post-resolve hook (e.g. dependency tracking for HMR). */
+    onResolved?: (result: ResolveFnOutput, parentUrl: string) => void;
+}
+/**
+ * Registers Node ESM resolve/load hooks and SWC-transpiles workspace `.ts`
+ * on the fly. No file watching and no entry reboot — that belongs to
+ * {@link HotReloadServer}.
+ */
+export declare class SourceModuleLoader {
+    private readonly logger;
+    private readonly transpiler;
+    private disposed;
+    private hooksRegistered;
+    private workspace?;
+    private buildConfig;
+    private fileInfoMap;
+    private transpileCache;
+    /** Bumped when a file's cached code is dropped, so an up-front compile already running can't put it back. */
+    private transpileVersions;
+    /** The source files each entry's walk reached, so a reboot only walks out from what changed. */
+    private reachedFrom;
+    /** Up-front compiles in flight, shared by entries booting at the same time. */
+    private compilingAhead;
+    /** SWC options per project, built on first use and kept until the next `configure()`. */
+    private swcConfigs;
+    private aliasPaths;
+    private aliasBaseUrl;
+    private versionFileUrl;
+    private onResolved?;
+    getWorkspace(): Workspace | undefined;
+    getBuildConfig(): string;
+    hasSourceFile(absolutePath: string): boolean;
+    sourceFilePaths(): IterableIterator<string>;
+    setSourceFile(absolutePath: string, project: Project): void;
+    configure(options: SourceModuleLoaderOptions): Promise<void>;
+    registerHooks(): void;
+    importEntry(absolutePath: string): Promise<unknown>;
+    invalidateTranspile(...absolutePaths: string[]): void;
+    dispose(): void;
+    private buildFileInfoMap;
+    /**
+     * Compiles the entry and the source files it imports, before Node imports it (#661). 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.
+     */
+    private compileAhead;
+    /** The file's compiled code, from the cache or compiled now; undefined if it isn't a source. */
+    private compiledAhead;
+    /** The source file a specifier names, mapped the way the resolve hook maps it. */
+    private sourcePathOf;
+    private loadTs;
+    /**
+     * The project's SWC options, built once: rebuilding them for every file was about a quarter
+     * of load time (#513). 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.
+     */
+    private swcConfigFor;
+}

package/types/src/static-imports.d.ts

@@ -0,0 +1,5 @@
+declare function scan(code: string): string[];
+export declare const staticImports: {
+    scan: typeof scan;
+};
+export {};