@decohere/flux 0.0.1-dev.12 → 0.0.1-dev.121

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

@@ -1,5 +1,12 @@
 import { EventEmitter } from "node:events";
-import type { Workspace } from "@decohere/mesh";
+import type { Workspace } from "@decohere/workspace";
+/** 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,83 @@ 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}. Every reload waits this long, so a larger
+     * window only pays off for saves known to come at a steady pace inside it (#484).
+     */
+    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/workspace";
+import { type Action, ActionResponse } from "@decohere/devkit/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/devkit/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 { Workspace } from "@decohere/workspace";
+import { type Action, ActionResponse } from "@decohere/devkit/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

@@ -1,6 +1,12 @@
-import { DecohereCommand } from "@decohere/nexus/cli";
+import { DecohereCommand } from "@decohere/devkit/cli";
 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 workspace 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,96 @@
+import type { ResolveFnOutput } from "node:module";
+import type { Project, Workspace } from "@decohere/workspace";
+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;
+    /** Compiled code on disk across runs (#514); null when caching is off. */
+    private diskCache;
+    /** 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 commonJsConfigs;
+    private aliasPaths;
+    private aliasBaseUrl;
+    private versionFileUrl;
+    private onResolved?;
+    getWorkspace(): Workspace | undefined;
+    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;
+    /**
+     * Compiles a file for the load hook, through the disk cache (#514). Throws, naming the file,
+     * when it can't be read or doesn't compile.
+     */
+    private compileSync;
+    /**
+     * 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 (#514).
+     */
+    private compileAsync;
+    /**
+     * 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;
+    private esModuleConfigFor;
+}

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 {};

package/types/src/transpile-disk-cache.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Compiled code on disk, so a cold start doesn't compile files that haven't changed (#514).
+ * 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 declare class TranspileDiskCache {
+    private readonly dir;
+    private readonly logger;
+    private disabled;
+    private constructor();
+    /** The cache for a workspace, or null when caching is off (`DECOHERE_CACHE=0`). */
+    static forWorkspace(rootDir: string): TranspileDiskCache | null;
+    get directory(): string;
+    /**
+     * 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: string, source: string, baseOptions: object): string;
+    private readonly optionsHashes;
+    private optionsHash;
+    readSync(key: string): string | undefined;
+    read(key: string): Promise<string | undefined>;
+    writeSync(key: string, code: string): void;
+    write(key: string, code: string): Promise<void>;
+    /** Deletes entries older than 30 days, if it hasn't done so in the last day. */
+    pruneIfDue(now?: number): Promise<void>;
+    private entryPath;
+    private tempPath;
+    /** A missing entry is a miss; any other read error turns the cache off. */
+    private missOrDisable;
+    private disable;
+}