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

package/es6/src/static-imports.js

@@ -1,27 +0,0 @@
-/**
- * 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/es6/src/transpile-disk-cache.js

@@ -1,142 +0,0 @@
-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 (#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 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/types/src/deferred-script-runner.d.ts

@@ -1,18 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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/rewrite-serve-specifier.d.ts

@@ -1,14 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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/slice-serve.d.ts

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-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

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

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

@@ -1,38 +0,0 @@
-/**
- * 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;
-}