@kensio/yulin 1.6.1 → 1.8.0

package/dist/util/process/close-on-signal.js

@@ -0,0 +1,54 @@
+/**
+ * The signals a process is asked to stop with, when nothing else is said.
+ *
+ * Ctrl-C in a terminal, and the `SIGTERM` a supervisor or a container runtime
+ * sends. Any other signal a script wants handled it names for itself.
+ */
+const defaultSignals = ["SIGINT", "SIGTERM"];
+/**
+ * A handler that closes something once, and then gets out of the way.
+ *
+ * The handlers come off as the first signal arrives, so closing runs once and a
+ * second Ctrl-C from someone who has waited long enough lands on Node's own
+ * default and ends the process. Nothing here exits the process: closing lets go
+ * of what was holding the event loop open, and a process with nothing else to
+ * do then exits on its own.
+ */
+class SimCloseOnSignal {
+    close;
+    signals;
+    stopListening = () => {
+        for (const signal of this.signals) {
+            process.off(signal, this.handle);
+        }
+    };
+    handle = () => {
+        this.stopListening();
+        void this.close();
+    };
+    constructor(close, options = {}) {
+        this.close = close;
+        this.signals = options.signals ?? defaultSignals;
+    }
+    /**
+     * Take the signals on, and hand back the way to give them up again.
+     */
+    listen() {
+        for (const signal of this.signals) {
+            process.on(signal, this.handle);
+        }
+        return this.stopListening;
+    }
+}
+/**
+ * Close something when the process is signalled, having been asked to.
+ *
+ * Yulin installs no signal handlers of its own, since a library taking over
+ * process signals gets in the way of whatever else the process is doing. This
+ * is how a script that wants one says so, and what comes back takes the
+ * handlers off again.
+ */
+export function closeOnSignal(close, options = {}) {
+    return new SimCloseOnSignal(close, options).listen();
+}
+//# sourceMappingURL=close-on-signal.js.map

package/dist/util/process/close-on-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-on-signal.js","sourceRoot":"","sources":["../../../src/util/process/close-on-signal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,cAAc,GAA8B,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AASxE;;;;;;;;GAQG;AACH,MAAM,gBAAgB;IACH,KAAK,CAAsB;IAC3B,OAAO,CAA4B;IAEnC,aAAa,GAAG,GAAS,EAAE;QAC1C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;IACH,CAAC,CAAC;IAEe,MAAM,GAAG,GAAS,EAAE;QACnC,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC,CAAC;IAEF,YACE,KAA0B,EAC1B,OAAO,GAA4B,EAAE;QAErC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA0B,EAC1B,OAAO,GAA4B,EAAE;IAErC,OAAO,IAAI,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;AACvD,CAAC"}

package/dist/watch/index.d.ts

@@ -0,0 +1,3 @@
+export { simWatch } from "./sim-watch-runtime.js";
+export type { SimWatchRuntime } from "./sim-watch-runtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/watch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/watch/index.js

@@ -0,0 +1,2 @@
+export { simWatch } from "./sim-watch-runtime.js";
+//# sourceMappingURL=index.js.map

package/dist/watch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/watch/sim-watch-runtime.d.ts

@@ -0,0 +1,76 @@
+type SimWatchStoppingListener = () => void;
+type SimWatchMessageListener = (message: unknown) => void;
+/**
+ * The part of the running process this needs, so a test can stand in for it
+ * without touching the process its own test runner is talking over.
+ */
+export interface SimWatchProcess {
+    readonly env: NodeJS.ProcessEnv;
+    readonly send?: ((message: unknown) => boolean) | undefined;
+    on(event: "message", listener: SimWatchMessageListener): unknown;
+    off(event: "message", listener: SimWatchMessageListener): unknown;
+}
+interface SimWatchRuntimeProperties {
+    readonly host?: SimWatchProcess;
+}
+/**
+ * The half of watch mode that lives in the supervised process.
+ *
+ * It is inert unless `yulin watch` started this process, so nothing here
+ * changes what a test run or an ordinary script does. Under a supervisor it
+ * does two things: it names the paths Yulin is reading, so the supervisor can
+ * watch them without the user listing paths Yulin is already holding, and it
+ * passes on the warning that a restart is coming, so a served page hears about
+ * it before the connection goes.
+ */
+export declare class SimWatchRuntime {
+    private readonly host;
+    private readonly stoppingListeners;
+    private listening;
+    private readonly onMessage;
+    constructor(properties?: SimWatchRuntimeProperties);
+    /**
+     * Whether a `yulin watch` supervisor started this process.
+     */
+    supervised(): boolean;
+    /**
+     * Name a path the supervisor should watch, such as a directory mounted into a
+     * Bucket or a synthesized template being deployed.
+     *
+     * Best effort by design. Nothing depends on the message arriving, and a
+     * process with no supervisor drops it.
+     */
+    reportPath(reportedPath: string): void;
+    /**
+     * Name a path this process is watching itself, and answering without needing
+     * a restart, such as a deployed template being updated in place.
+     *
+     * The supervisor leaves it alone from then on. Being told that a path is
+     * handled here is more specific than any rule the supervisor has about which
+     * paths are worth restarting for, so it wins over having reported the same
+     * path for watching.
+     *
+     * Best effort, as reportPath is: a process with no supervisor drops it.
+     */
+    reportHeldPath(heldPath: string): void;
+    /**
+     * Run something when the supervisor says this process is about to restart.
+     */
+    onStopping(listener: SimWatchStoppingListener): void;
+    /**
+     * Stop running something on a restart.
+     */
+    offStopping(listener: SimWatchStoppingListener): void;
+    private listen;
+    private unlisten;
+}
+/**
+ * The watch runtime for this process.
+ *
+ * One per process rather than one per `SimAws`, because it is about the process
+ * a supervisor started, not about any one simulated environment. Several
+ * simulations in the same process all report to the same supervisor.
+ */
+export declare const simWatch: SimWatchRuntime;
+export {};
+//# sourceMappingURL=sim-watch-runtime.d.ts.map

package/dist/watch/sim-watch-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-runtime.d.ts","sourceRoot":"","sources":["../../src/watch/sim-watch-runtime.ts"],"names":[],"mappings":"AAGA,KAAK,wBAAwB,GAAG,MAAM,IAAI,CAAC;AAC3C,KAAK,uBAAuB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5D,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC;IACjE,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC;CACnE;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuC;IACzE,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAYxB;IAEF,YAAY,UAAU,GAAE,yBAA8B,EAGrD;IAED;;OAEG;IACH,UAAU,IAAI,OAAO,CAMpB;IAED;;;;;;OAMG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CASrC;IAED;;;;;;;;;;OAUG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CASrC;IAED;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAOnD;IAED;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAMpD;IAED,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,QAAQ;CAQjB;AAWD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,iBAAwB,CAAC"}

package/dist/watch/sim-watch-runtime.js

@@ -0,0 +1,124 @@
+import path from "node:path";
+import { simWatchConfig, simWatchMessages } from "./sim-watch.config.js";
+/**
+ * The half of watch mode that lives in the supervised process.
+ *
+ * It is inert unless `yulin watch` started this process, so nothing here
+ * changes what a test run or an ordinary script does. Under a supervisor it
+ * does two things: it names the paths Yulin is reading, so the supervisor can
+ * watch them without the user listing paths Yulin is already holding, and it
+ * passes on the warning that a restart is coming, so a served page hears about
+ * it before the connection goes.
+ */
+export class SimWatchRuntime {
+    host;
+    stoppingListeners = new Set();
+    listening = false;
+    onMessage = (message) => {
+        if (!isStoppingMessage(message)) {
+            return;
+        }
+        for (const listener of this.stoppingListeners) {
+            listener();
+        }
+        // The supervisor waits for this before killing the process, so whatever the
+        // listeners wrote has left this end first.
+        this.host.send?.({ type: simWatchMessages.stopped });
+    };
+    constructor(properties = {}) {
+        const { host = process } = properties;
+        this.host = host;
+    }
+    /**
+     * Whether a `yulin watch` supervisor started this process.
+     */
+    supervised() {
+        return (this.host.env[simWatchConfig.environmentVariableName] ===
+            simWatchConfig.environmentVariableValue &&
+            typeof this.host.send === "function");
+    }
+    /**
+     * Name a path the supervisor should watch, such as a directory mounted into a
+     * Bucket or a synthesized template being deployed.
+     *
+     * Best effort by design. Nothing depends on the message arriving, and a
+     * process with no supervisor drops it.
+     */
+    reportPath(reportedPath) {
+        if (!this.supervised()) {
+            return;
+        }
+        this.host.send?.({
+            type: simWatchMessages.path,
+            path: path.resolve(reportedPath),
+        });
+    }
+    /**
+     * Name a path this process is watching itself, and answering without needing
+     * a restart, such as a deployed template being updated in place.
+     *
+     * The supervisor leaves it alone from then on. Being told that a path is
+     * handled here is more specific than any rule the supervisor has about which
+     * paths are worth restarting for, so it wins over having reported the same
+     * path for watching.
+     *
+     * Best effort, as reportPath is: a process with no supervisor drops it.
+     */
+    reportHeldPath(heldPath) {
+        if (!this.supervised()) {
+            return;
+        }
+        this.host.send?.({
+            type: simWatchMessages.heldPath,
+            path: path.resolve(heldPath),
+        });
+    }
+    /**
+     * Run something when the supervisor says this process is about to restart.
+     */
+    onStopping(listener) {
+        if (!this.supervised()) {
+            return;
+        }
+        this.stoppingListeners.add(listener);
+        this.listen();
+    }
+    /**
+     * Stop running something on a restart.
+     */
+    offStopping(listener) {
+        this.stoppingListeners.delete(listener);
+        if (this.stoppingListeners.size === 0) {
+            this.unlisten();
+        }
+    }
+    listen() {
+        if (this.listening) {
+            return;
+        }
+        this.listening = true;
+        this.host.on("message", this.onMessage);
+    }
+    unlisten() {
+        if (!this.listening) {
+            return;
+        }
+        this.listening = false;
+        this.host.off("message", this.onMessage);
+    }
+}
+function isStoppingMessage(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        "type" in message &&
+        message.type === simWatchMessages.stopping);
+}
+/**
+ * The watch runtime for this process.
+ *
+ * One per process rather than one per `SimAws`, because it is about the process
+ * a supervisor started, not about any one simulated environment. Several
+ * simulations in the same process all report to the same supervisor.
+ */
+export const simWatch = new SimWatchRuntime();
+//# sourceMappingURL=sim-watch-runtime.js.map

package/dist/watch/sim-watch-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-runtime.js","sourceRoot":"","sources":["../../src/watch/sim-watch-runtime.ts"],"names":[],"mappings":"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"}

package/dist/watch/sim-watch-settle.d.ts

@@ -0,0 +1,45 @@
+interface SimWatchSettleProperties {
+    readonly settleMs: number;
+    readonly maxWaitMs: number;
+    readonly onSettled: (changedPath: string) => void;
+}
+/**
+ * Turns a burst of writes into one change.
+ *
+ * Saving one file in an editor is several filesystem events: a temporary file
+ * written, renamed over the original, and often the directory touched as well.
+ * Acting on each of those would be several restarts, or several Stack updates,
+ * for one save, so the changes are held until they stop arriving.
+ *
+ * A burst that never stops arriving would otherwise be held for as long as it
+ * went on, since every event pushes the wait back. `maxWaitMs` is how long that
+ * pushing back is allowed to last: a build that writes without a pause is acted
+ * on during it rather than only once it finishes.
+ *
+ * The path reported is the first of the burst, which is the one that actually
+ * changed rather than whatever the editor did around it.
+ */
+export declare class SimWatchSettle {
+    private readonly settleMs;
+    private readonly maxWaitMs;
+    private readonly onSettled;
+    private pendingPath;
+    private settleBy;
+    private timer;
+    constructor(properties: SimWatchSettleProperties);
+    /**
+     * Note a change, and wait to see whether more are coming.
+     */
+    record(changedPath: string): void;
+    /**
+     * Drop anything waiting, for a watcher that is shutting down.
+     */
+    cancel(): void;
+    /**
+     * How long to wait for the next event: the settle window, or whatever is left
+     * of the maximum, whichever runs out first.
+     */
+    private waitMs;
+}
+export {};
+//# sourceMappingURL=sim-watch-settle.d.ts.map

package/dist/watch/sim-watch-settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-settle.d.ts","sourceRoot":"","sources":["../../src/watch/sim-watch-settle.ts"],"names":[],"mappings":"AAAA,UAAU,wBAAwB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,KAAK,CAA6B;IAE1C,YAAY,UAAU,EAAE,wBAAwB,EAQ/C;IAED;;OAEG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAWhC;IAED;;OAEG;IACH,MAAM,IAAI,IAAI,CAKb;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM;CAKf"}

package/dist/watch/sim-watch-settle.js

@@ -0,0 +1,65 @@
+/**
+ * Turns a burst of writes into one change.
+ *
+ * Saving one file in an editor is several filesystem events: a temporary file
+ * written, renamed over the original, and often the directory touched as well.
+ * Acting on each of those would be several restarts, or several Stack updates,
+ * for one save, so the changes are held until they stop arriving.
+ *
+ * A burst that never stops arriving would otherwise be held for as long as it
+ * went on, since every event pushes the wait back. `maxWaitMs` is how long that
+ * pushing back is allowed to last: a build that writes without a pause is acted
+ * on during it rather than only once it finishes.
+ *
+ * The path reported is the first of the burst, which is the one that actually
+ * changed rather than whatever the editor did around it.
+ */
+export class SimWatchSettle {
+    settleMs;
+    maxWaitMs;
+    onSettled;
+    pendingPath;
+    settleBy;
+    timer;
+    constructor(properties) {
+        const { settleMs, maxWaitMs, onSettled } = properties;
+        this.settleMs = settleMs;
+        // A maximum shorter than the window it caps would end every burst early,
+        // including the one editor save the window is there for, so an unusually
+        // long window is its own maximum.
+        this.maxWaitMs = Math.max(maxWaitMs, settleMs);
+        this.onSettled = onSettled;
+    }
+    /**
+     * Note a change, and wait to see whether more are coming.
+     */
+    record(changedPath) {
+        this.pendingPath ??= changedPath;
+        this.settleBy ??= Date.now() + this.maxWaitMs;
+        const burstPath = this.pendingPath;
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.pendingPath = undefined;
+            this.settleBy = undefined;
+            this.onSettled(burstPath);
+        }, this.waitMs());
+    }
+    /**
+     * Drop anything waiting, for a watcher that is shutting down.
+     */
+    cancel() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.pendingPath = undefined;
+        this.settleBy = undefined;
+    }
+    /**
+     * How long to wait for the next event: the settle window, or whatever is left
+     * of the maximum, whichever runs out first.
+     */
+    waitMs() {
+        const left = (this.settleBy ?? 0) - Date.now();
+        return Math.max(0, Math.min(this.settleMs, left));
+    }
+}
+//# sourceMappingURL=sim-watch-settle.js.map

package/dist/watch/sim-watch-settle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-settle.js","sourceRoot":"","sources":["../../src/watch/sim-watch-settle.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,cAAc;IACR,QAAQ,CAAS;IACjB,SAAS,CAAS;IAClB,SAAS,CAAgC;IAClD,WAAW,CAAqB;IAChC,QAAQ,CAAqB;IAC7B,KAAK,CAA6B;IAE1C,YAAY,UAAoC;QAC9C,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,UAAU,CAAC;QACtD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,yEAAyE;QACzE,yEAAyE;QACzE,kCAAkC;QAClC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAmB;QACxB,IAAI,CAAC,WAAW,KAAK,WAAW,CAAC;QACjC,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC;QAEnC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC3B,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;YAC1B,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACK,MAAM;QACZ,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE/C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/watch/sim-watch.config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Configuration shared by `yulin watch` and the process it supervises.
+ */
+export declare const simWatchConfig: {
+    environmentVariableName: string;
+    environmentVariableValue: string;
+    settleMs: number;
+    settleMaxWaitMs: number;
+    stoppingMs: number;
+    exitMs: number;
+    selfInflictedMs: number;
+    loopRestarts: number;
+};
+/**
+ * The messages the supervisor and the supervised process send each other.
+ */
+export declare const simWatchMessages: {
+    readonly path: "yulin:watch-path";
+    readonly heldPath: "yulin:watch-held-path";
+    readonly stopping: "yulin:watch-stopping";
+    readonly stopped: "yulin:watch-stopped";
+};
+//# sourceMappingURL=sim-watch.config.d.ts.map

package/dist/watch/sim-watch.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch.config.d.ts","sourceRoot":"","sources":["../../src/watch/sim-watch.config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc;IAIzB,uBAAuB;IACvB,wBAAwB;IAaxB,QAAQ;IAUR,eAAe;IAIf,UAAU;IAEV,MAAM;IAGN,eAAe;IAEf,YAAY;CACb,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB;aAE3B,IAAI,EAAE,kBAAkB;aAGxB,QAAQ,EAAE,uBAAuB;aAEjC,QAAQ,EAAE,sBAAsB;aAEhC,OAAO,EAAE,qBAAqB;CACtB,CAAC"}

package/dist/watch/sim-watch.config.js

@@ -0,0 +1,59 @@
+/**
+ * Configuration shared by `yulin watch` and the process it supervises.
+ */
+export const simWatchConfig = {
+    // Set on a supervised process, so the runtime in it knows there is a
+    // supervisor to talk to. Absent everywhere else, which is what makes watch
+    // mode inert unless it was asked for.
+    environmentVariableName: "YULIN_WATCH",
+    environmentVariableValue: "1",
+    // How long a burst of writes has to go quiet before it counts as one change.
+    // One save from an editor is several writes, and a rename over the original.
+    //
+    // The number is what a real build needs rather than what one save needs.
+    // macOS hands a recursive watch its events in waves rather than one at a
+    // time: a build writing several thousand files was measured arriving as tens
+    // of waves up to 49ms apart, so a window near that turns one build into
+    // several restarts, and 120 was close enough to it to be split by a build
+    // that pauses between its own phases. 250 clears the waves several times
+    // over, and covers the short pauses a multi-stage build takes. It is also
+    // well inside `selfInflictedMs`, so a file the process wrote on startup is
+    // still recognised as one it wrote itself.
+    settleMs: 250,
+    // How long a burst is allowed to defer the change that started it. Every
+    // event pushes the settle window back, so without this a build that writes
+    // for a minute is acted on a minute late, having held everything off for the
+    // whole of it.
+    //
+    // Longer than `selfInflictedMs`, so a change taken during a burst is never
+    // mistaken for one the process made itself, and longer than an ordinary build
+    // takes, so it is a backstop for a stream that will not stop rather than
+    // something a build runs into.
+    settleMaxWaitMs: 5000,
+    // How long the supervisor waits for a process to say it has told its browsers
+    // a reload is coming. A process not running Yulin's runtime never answers, so
+    // this is a short wait rather than a requirement.
+    stoppingMs: 250,
+    // How long a process gets to exit on its own before it is killed outright.
+    exitMs: 2000,
+    // A change arriving sooner than this after a start is a change the process
+    // itself is likely to have made.
+    selfInflictedMs: 1500,
+    // How many self-inflicted restarts in a row before the loop is called.
+    loopRestarts: 3,
+};
+/**
+ * The messages the supervisor and the supervised process send each other.
+ */
+export const simWatchMessages = {
+    // Child to parent: a path Yulin is reading that is worth watching.
+    path: "yulin:watch-path",
+    // Child to parent: a path Yulin is watching itself and answering in place, so
+    // a change to it is not something to restart the process for.
+    heldPath: "yulin:watch-held-path",
+    // Parent to child: this process is about to be restarted.
+    stopping: "yulin:watch-stopping",
+    // Child to parent: the browsers have been told, go ahead.
+    stopped: "yulin:watch-stopped",
+};
+//# sourceMappingURL=sim-watch.config.js.map

package/dist/watch/sim-watch.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch.config.js","sourceRoot":"","sources":["../../src/watch/sim-watch.config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,qEAAqE;IACrE,2EAA2E;IAC3E,sCAAsC;IACtC,uBAAuB,EAAE,aAAa;IACtC,wBAAwB,EAAE,GAAG;IAC7B,6EAA6E;IAC7E,6EAA6E;IAC7E,EAAE;IACF,yEAAyE;IACzE,yEAAyE;IACzE,6EAA6E;IAC7E,wEAAwE;IACxE,0EAA0E;IAC1E,yEAAyE;IACzE,0EAA0E;IAC1E,2EAA2E;IAC3E,2CAA2C;IAC3C,QAAQ,EAAE,GAAG;IACb,yEAAyE;IACzE,2EAA2E;IAC3E,6EAA6E;IAC7E,eAAe;IACf,EAAE;IACF,2EAA2E;IAC3E,8EAA8E;IAC9E,yEAAyE;IACzE,+BAA+B;IAC/B,eAAe,EAAE,IAAI;IACrB,8EAA8E;IAC9E,8EAA8E;IAC9E,kDAAkD;IAClD,UAAU,EAAE,GAAG;IACf,2EAA2E;IAC3E,MAAM,EAAE,IAAI;IACZ,2EAA2E;IAC3E,iCAAiC;IACjC,eAAe,EAAE,IAAI;IACrB,uEAAuE;IACvE,YAAY,EAAE,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,mEAAmE;IACnE,IAAI,EAAE,kBAAkB;IACxB,8EAA8E;IAC9E,8DAA8D;IAC9D,QAAQ,EAAE,uBAAuB;IACjC,0DAA0D;IAC1D,QAAQ,EAAE,sBAAsB;IAChC,0DAA0D;IAC1D,OAAO,EAAE,qBAAqB;CACtB,CAAC"}

package/package.json

@@ -1,15 +1,34 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "description": "AWS system behaviour simulation for isolated unit testing",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/KensioSoftware/yulin"
-  },
+  "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "yulin": "./dist/cli/yulin.js"
+  },
+  "scripts": {
+    "clean": "rm -rf ./dist/ ./*.tsbuildinfo",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "build:check": "tsc -p tsconfig.json --noEmit",
+    "prepack": "pnpm build",
+    "verify:pack": "pnpm tsx scripts/mts/verify-pack.mts",
+    "fmt": "eslint --cache --cache-location node_modules/.cache/eslint/main --fix . && prettier --cache --write . && prettier --cache --cache-location node_modules/.cache/prettier/settled --check .",
+    "lint": "eslint --cache --cache-location node_modules/.cache/eslint/main . && prettier --cache --check .",
+    "test": "vitest run",
+    "test:coverage": "rm -rf './.tmp/' && vitest run --coverage",
+    "test:iso": "vitest run --project isolatedTests",
+    "test:local": "rm -rf './.tmp/' && vitest run --project localTests",
+    "examples:extract": "pnpm tsx scripts/mts/extract-documentation-examples.mts",
+    "examples:tsc": "tsc -p docs/tsconfig.json",
+    "examples:lint": "eslint --cache --cache-location node_modules/.cache/eslint/examples \"docs/**/*.example.ts\"",
+    "examples:check": "pnpm examples:extract && pnpm examples:tsc && pnpm examples:lint",
+    "fta": "./scripts/sh/fta.sh",
+    "check": "pnpm fmt && pnpm fta && pnpm build:check && pnpm examples:check && pnpm test:coverage"
+  },
   "keywords": [
     "aws",
     "test",
@@ -98,6 +117,10 @@
     "./serve": {
       "import": "./dist/serve/index.js",
       "types": "./dist/serve/index.d.ts"
+    },
+    "./watch": {
+      "import": "./dist/watch/index.js",
+      "types": "./dist/watch/index.d.ts"
     }
   },
   "files": [
@@ -107,6 +130,7 @@
   ],
   "author": "Kensio Software",
   "license": "Apache-2.0",
+  "packageManager": "pnpm@11.17.0+sha512.cca3cea332ad254bb84145f966d19f4879615210346fc92c79a047f23a0d7b3cca3c3792f0076ba1f1831d277efbcf0a9119b31a9a60eca7fb3d6231f331ef72",
   "devDependencies": {
     "@aws-crypto/sha256-js": "^5.2.0",
     "@aws-sdk/client-acm": "^3.1101.0",
@@ -130,6 +154,7 @@
     "@aws-sdk/s3-request-presigner": "^3.1101.0",
     "@eslint/js": "^10.0.1",
     "@kensio/smartass": "^1.36.0",
+    "@semantic-release/exec": "7.1.0",
     "@smithy/signature-v4": "^5.6.12",
     "@smithy/smithy-client": "^4.14.16",
     "@smithy/types": "^4.16.1",
@@ -155,6 +180,7 @@
     "globals": "^17.8.0",
     "jiti": "^2.7.0",
     "prettier": "^3.9.6",
+    "semantic-release": "25.0.9",
     "tsx": "^4.23.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.65.0",
@@ -176,23 +202,5 @@
     "typescript-eslint": {
       "optional": true
     }
-  },
-  "scripts": {
-    "clean": "rm -rf ./dist/ ./*.tsbuildinfo",
-    "build": "pnpm clean && tsc -p tsconfig.build.json",
-    "build:check": "tsc -p tsconfig.json --noEmit",
-    "verify:pack": "pnpm tsx scripts/mts/verify-pack.mts",
-    "fmt": "eslint --cache --cache-location node_modules/.cache/eslint/main --fix . && prettier --cache --write . && prettier --cache --cache-location node_modules/.cache/prettier/settled --check .",
-    "lint": "eslint --cache --cache-location node_modules/.cache/eslint/main . && prettier --cache --check .",
-    "test": "vitest run",
-    "test:coverage": "rm -rf './.tmp/' && vitest run --coverage",
-    "test:iso": "vitest run --project isolatedTests",
-    "test:local": "rm -rf './.tmp/' && vitest run --project localTests",
-    "examples:extract": "pnpm tsx scripts/mts/extract-documentation-examples.mts",
-    "examples:tsc": "tsc -p docs/tsconfig.json",
-    "examples:lint": "eslint --cache --cache-location node_modules/.cache/eslint/examples \"docs/**/*.example.ts\"",
-    "examples:check": "pnpm examples:extract && pnpm examples:tsc && pnpm examples:lint",
-    "fta": "./scripts/sh/fta.sh",
-    "check": "pnpm fmt && pnpm fta && pnpm build:check && pnpm examples:check && pnpm test:coverage"
   }
-}
+}