@kensio/yulin 1.6.1 → 1.7.0

package/README.md

@@ -38,6 +38,7 @@ npm i -D @kensio/yulin
 ## Feature specific docs
 
 - [AWS SDK interception](./docs/sdk "Simulated AWS SDK docs")
+- [Serving on localhost](./docs/serve "Serving simulated AWS on localhost docs")
 - [Simulated time](./docs/time "Simulated time docs")
 
 ## Usage
@@ -185,6 +186,77 @@ console.log(bucketWebsiteUrl.toString());
 const res = await fetch(new URL("/foo/", bucketWebsiteUrl));
 ```
 
+#### Restarting a served environment
+
+A served environment takes an available port by default, so the URL changes every time the process
+starts. Pin a port to keep the URL the same across restarts:
+
+```typescript
+const srv = await serveSimAws({ simAws, port: 4599 });
+```
+
+Closing the server ends the connections it is holding, so the process can exit rather than being
+kept alive by a browser tab. Yulin does not install signal handlers, so call `close()` from your
+own:
+
+```typescript
+process.on("SIGTERM", () => {
+  srv.close();
+});
+```
+
+A restart usually overlaps the process it is replacing. `listen` waits a couple of seconds for a
+pinned port that is still held, then throws `SimAwsLocalPortInUse` naming the port, which means
+something other than the outgoing process owns it.
+
+#### Reload the browser on a restart
+
+Yulin is the only thing in the response path of a page it serves, so it can tell the browser to
+reload. Turning `liveReload` on puts a small script into the HTML pages served to browsers, and the
+page reloads itself when the process restarts:
+
+```typescript
+const srv = await serveSimAws({ simAws, port: 4599, liveReload: true });
+```
+
+`srv.reload()` reloads connected browsers for a change that needs no restart. Live reload is off by
+default, since an injected page is not byte for byte what the real service returns.
+
+Run the dev script through `yulin watch` and a save is the whole loop, with the process restarted and
+the page refreshed:
+
+```bash
+yulin watch -- tsx dev.ts
+```
+
+It watches the working directory, plus the paths Yulin is holding that a module graph never mentions:
+a directory mounted into a Bucket, and a synthesized template. See the
+[serving docs](./docs/serve "Serving simulated AWS on localhost docs") for what gets the script, what
+is watched, and what is not.
+
+#### Update a stack when its template changes
+
+A synthesized template is data rather than code, so a change to one does not need the process
+restarted. Deploy it with `watch` and Yulin applies the file again whenever it changes, updating the
+stack in place:
+
+```typescript
+await simAws.cloudFormation().deployTemplateFile({
+  templatePath: "cdk.out/SiteStack.template.json",
+  watch: {
+    onUpdated: () => {
+      srv.reload();
+    },
+  },
+});
+```
+
+Resources the change left alone keep what they hold, so simulated S3, DynamoDB and SQS survive a
+`cdk synth`. Under `yulin watch` the template is left to the process watching it rather than being a
+reason to restart. See the
+[CloudFormation docs](./docs/services/cloudformation "Simulated CloudFormation docs") for what an
+update does to each resource.
+
 ### Control simulated time
 
 Each simulated AWS has its own clock, which you can freeze, set, or advance. This lets a test

package/dist/cli/sim-cli.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Thrown for a command the CLI does not have.
+ */
+export declare class SimCliUnknownCommand extends Error {
+    readonly name = "SimCliUnknownCommand";
+    constructor(command: string);
+}
+/**
+ * The `yulin` command line.
+ *
+ * One command so far. It exists because a local dev loop needs a process
+ * outside the one being restarted, which is not something a library can be.
+ */
+export declare class SimCli {
+    /**
+     * Run the CLI, and report the exit code it should leave behind.
+     */
+    run(argv: readonly string[]): Promise<number>;
+}
+//# sourceMappingURL=sim-cli.d.ts.map

package/dist/cli/sim-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-cli.d.ts","sourceRoot":"","sources":["../../src/cli/sim-cli.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAyB,IAAI,0BAA0B;IAEvD,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED;;;;;GAKG;AACH,qBAAa,MAAM;IACjB;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBlD;CACF"}

package/dist/cli/sim-cli.js

@@ -0,0 +1,42 @@
+import { SimWatchCommand } from "./watch/sim-watch-command.js";
+const usage = `Usage: yulin <command>
+
+Commands:
+  watch [--inspect[=port]] -- <command>   Run a command, and run it again when project files change
+`;
+/**
+ * Thrown for a command the CLI does not have.
+ */
+export class SimCliUnknownCommand extends Error {
+    name = "SimCliUnknownCommand";
+    constructor(command) {
+        super(`Unknown command ${command}.\n\n${usage}`);
+    }
+}
+/**
+ * The `yulin` command line.
+ *
+ * One command so far. It exists because a local dev loop needs a process
+ * outside the one being restarted, which is not something a library can be.
+ */
+export class SimCli {
+    /**
+     * Run the CLI, and report the exit code it should leave behind.
+     */
+    async run(argv) {
+        const [command, ...rest] = argv;
+        if (command === undefined) {
+            process.stdout.write(usage);
+            return 1;
+        }
+        if (["--help", "-h", "help"].includes(command)) {
+            process.stdout.write(usage);
+            return 0;
+        }
+        if (command !== "watch") {
+            throw new SimCliUnknownCommand(command);
+        }
+        return await new SimWatchCommand().run(rest);
+    }
+}
+//# sourceMappingURL=sim-cli.js.map

package/dist/cli/sim-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-cli.js","sourceRoot":"","sources":["../../src/cli/sim-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,MAAM,KAAK,GAAG;;;;CAIb,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpB,IAAI,GAAG,sBAAsB,CAAC;IAEvD,YAAY,OAAe;QACzB,KAAK,CAAC,mBAAmB,OAAO,QAAQ,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,MAAM;IACjB;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,IAAuB;QAC/B,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAEhC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,CAAC,CAAC;QACX,CAAC;QAED,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC5B,OAAO,CAAC,CAAC;QACX,CAAC;QAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YACxB,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,MAAM,IAAI,eAAe,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/dist/cli/watch/sim-watch-arguments.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Thrown when `yulin watch` was not given something to run.
+ */
+export declare class SimWatchUsageError extends Error {
+    readonly name = "SimWatchUsageError";
+    constructor(message: string);
+}
+/**
+ * What `yulin watch` was asked to do.
+ *
+ * Everything after `--` is the command, passed through untouched. The CLI does
+ * not import the command, look for an exported setup function, or care whether
+ * the simulation it builds came from SDK commands, a template, or several
+ * `SimAws` instances at once. It runs it and runs it again.
+ */
+export declare class SimWatchArguments {
+    readonly command: string;
+    readonly commandArguments: readonly string[];
+    readonly inspect: string | undefined;
+    private constructor();
+    /**
+     * Read the arguments given after `yulin watch`.
+     */
+    static parse(argv: readonly string[]): SimWatchArguments;
+    /**
+     * The command as it was written, for reporting.
+     */
+    describe(): string;
+}
+//# sourceMappingURL=sim-watch-arguments.d.ts.map

package/dist/cli/watch/sim-watch-arguments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-arguments.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-arguments.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAyB,IAAI,wBAAwB;IAErD,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,OAAO,eAQN;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,CAoBvD;IAED;;OAEG;IACH,QAAQ,IAAI,MAAM,CAEjB;CACF"}

package/dist/cli/watch/sim-watch-arguments.js

@@ -0,0 +1,67 @@
+const inspectorFlags = new Set([
+    "--inspect",
+    "--inspect-brk",
+    "--inspect-wait",
+]);
+/**
+ * Thrown when `yulin watch` was not given something to run.
+ */
+export class SimWatchUsageError extends Error {
+    name = "SimWatchUsageError";
+    constructor(message) {
+        super(`${message}\n\nUsage: yulin watch [--inspect[=port]] -- <command>`);
+    }
+}
+/**
+ * What `yulin watch` was asked to do.
+ *
+ * Everything after `--` is the command, passed through untouched. The CLI does
+ * not import the command, look for an exported setup function, or care whether
+ * the simulation it builds came from SDK commands, a template, or several
+ * `SimAws` instances at once. It runs it and runs it again.
+ */
+export class SimWatchArguments {
+    command;
+    commandArguments;
+    inspect;
+    constructor(command, commandArguments, inspect) {
+        this.command = command;
+        this.commandArguments = commandArguments;
+        this.inspect = inspect;
+    }
+    /**
+     * Read the arguments given after `yulin watch`.
+     */
+    static parse(argv) {
+        const separator = argv.indexOf("--");
+        if (separator === -1) {
+            throw new SimWatchUsageError("No command given. Put the command to run after --, so that its own options are not read as options to watch.");
+        }
+        const [command, ...rest] = argv.slice(separator + 1);
+        if (command === undefined) {
+            throw new SimWatchUsageError("No command given after --.");
+        }
+        return new SimWatchArguments(command, rest, inspectorFlag(argv.slice(0, separator)));
+    }
+    /**
+     * The command as it was written, for reporting.
+     */
+    describe() {
+        return [this.command, ...this.commandArguments].join(" ");
+    }
+}
+/**
+ * The inspector flag to pass through to each run, if one was asked for.
+ */
+function inspectorFlag(options) {
+    const unknown = options.find((option) => !isInspectorFlag(option));
+    if (unknown !== undefined) {
+        throw new SimWatchUsageError(`Unknown option ${unknown}.`);
+    }
+    return options.at(-1);
+}
+function isInspectorFlag(option) {
+    const [flag = ""] = option.split("=");
+    return inspectorFlags.has(flag);
+}
+//# sourceMappingURL=sim-watch-arguments.js.map

package/dist/cli/watch/sim-watch-arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-arguments.js","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-arguments.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,WAAW;IACX,eAAe;IACf,gBAAgB;CACjB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClB,IAAI,GAAG,oBAAoB,CAAC;IAErD,YAAY,OAAe;QACzB,KAAK,CAAC,GAAG,OAAO,wDAAwD,CAAC,CAAC;IAC5E,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IACnB,OAAO,CAAS;IAChB,gBAAgB,CAAoB;IACpC,OAAO,CAAqB;IAErC,YACE,OAAe,EACf,gBAAmC,EACnC,OAA2B;QAE3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,IAAuB;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAErC,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,kBAAkB,CAC1B,8GAA8G,CAC/G,CAAC;QACJ,CAAC;QAED,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QAErD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,kBAAkB,CAAC,4BAA4B,CAAC,CAAC;QAC7D,CAAC;QAED,OAAO,IAAI,iBAAiB,CAC1B,OAAO,EACP,IAAI,EACJ,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CACxC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5D,CAAC;CACF;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,OAA0B;IAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IAEnE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,kBAAkB,CAAC,kBAAkB,OAAO,GAAG,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACrC,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEtC,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/cli/watch/sim-watch-child-environment.d.ts

@@ -0,0 +1,30 @@
+interface SimWatchChildEnvironmentProperties {
+    readonly cwd: string;
+    readonly inspect?: string | undefined;
+    readonly environment?: NodeJS.ProcessEnv;
+}
+/**
+ * The environment a supervised process runs in.
+ *
+ * Three things are added to the environment the supervisor was given. The
+ * project's own `node_modules/.bin` goes on `PATH`, so `yulin watch -- tsx
+ * dev.ts` works from a plain shell as well as from a package script. A marker
+ * says a supervisor is listening, which is what makes the runtime in the child
+ * report paths at all. An inspector flag goes through `NODE_OPTIONS` rather
+ * than on the command line, because the command being run is often not `node`
+ * itself.
+ */
+export declare class SimWatchChildEnvironment {
+    private readonly cwd;
+    private readonly inspect;
+    private readonly environment;
+    constructor(properties: SimWatchChildEnvironmentProperties);
+    /**
+     * Build the environment for one run of the supervised command.
+     */
+    build(): NodeJS.ProcessEnv;
+    private pathWithLocalBin;
+    private nodeOptionsWithInspector;
+}
+export {};
+//# sourceMappingURL=sim-watch-child-environment.d.ts.map

package/dist/cli/watch/sim-watch-child-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-environment.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-environment.ts"],"names":[],"mappings":"AAKA,UAAU,kCAAkC;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD,YAAY,UAAU,EAAE,kCAAkC,EAKzD;IAED;;OAEG;IACH,KAAK,IAAI,MAAM,CAAC,UAAU,CAUzB;IAED,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,wBAAwB;CAKjC"}

package/dist/cli/watch/sim-watch-child-environment.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { simWatchConfig } from "../../watch/sim-watch.config.js";
+const nodeOptionsName = "NODE_OPTIONS";
+/**
+ * The environment a supervised process runs in.
+ *
+ * Three things are added to the environment the supervisor was given. The
+ * project's own `node_modules/.bin` goes on `PATH`, so `yulin watch -- tsx
+ * dev.ts` works from a plain shell as well as from a package script. A marker
+ * says a supervisor is listening, which is what makes the runtime in the child
+ * report paths at all. An inspector flag goes through `NODE_OPTIONS` rather
+ * than on the command line, because the command being run is often not `node`
+ * itself.
+ */
+export class SimWatchChildEnvironment {
+    cwd;
+    inspect;
+    environment;
+    constructor(properties) {
+        const { cwd, inspect, environment = process.env } = properties;
+        this.cwd = cwd;
+        this.inspect = inspect;
+        this.environment = environment;
+    }
+    /**
+     * Build the environment for one run of the supervised command.
+     */
+    build() {
+        return {
+            ...this.environment,
+            PATH: this.pathWithLocalBin(),
+            [simWatchConfig.environmentVariableName]: simWatchConfig.environmentVariableValue,
+            ...(this.inspect !== undefined && {
+                [nodeOptionsName]: this.nodeOptionsWithInspector(this.inspect),
+            }),
+        };
+    }
+    pathWithLocalBin() {
+        const localBin = path.join(this.cwd, "node_modules", ".bin");
+        const existing = this.environment["PATH"] ?? "";
+        if (existing.split(path.delimiter).includes(localBin)) {
+            return existing;
+        }
+        return `${localBin}${path.delimiter}${existing}`;
+    }
+    nodeOptionsWithInspector(inspect) {
+        const existing = this.environment["NODE_OPTIONS"] ?? "";
+        return `${existing} ${inspect}`.trim();
+    }
+}
+//# sourceMappingURL=sim-watch-child-environment.js.map

package/dist/cli/watch/sim-watch-child-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-environment.js","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-environment.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,MAAM,eAAe,GAAG,cAAc,CAAC;AAQvC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,wBAAwB;IAClB,GAAG,CAAS;IACZ,OAAO,CAAqB;IAC5B,WAAW,CAAoB;IAEhD,YAAY,UAA8C;QACxD,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC;QAC/D,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,OAAO;YACL,GAAG,IAAI,CAAC,WAAW;YACnB,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE;YAC7B,CAAC,cAAc,CAAC,uBAAuB,CAAC,EACtC,cAAc,CAAC,wBAAwB;YACzC,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI;gBAChC,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC;aAC/D,CAAC;SACH,CAAC;IACJ,CAAC;IAEO,gBAAgB;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAEhD,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtD,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC,SAAS,GAAG,QAAQ,EAAE,CAAC;IACnD,CAAC;IAEO,wBAAwB,CAAC,OAAe;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAExD,OAAO,GAAG,QAAQ,IAAI,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;CACF"}

package/dist/cli/watch/sim-watch-child-message.d.ts

@@ -0,0 +1,19 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * Whether an IPC message is one of the kind named.
+ */
+export declare function isWatchMessage(message: unknown, type: string): boolean;
+/**
+ * Whether an IPC message names a path to watch.
+ */
+export declare function isWatchPathMessage(message: unknown, type: string): message is {
+    readonly path: string;
+};
+/**
+ * Wait for a process to send a message of one kind, and give up after a while.
+ *
+ * A process not running Yulin's runtime never answers, so this is a short wait
+ * rather than a requirement.
+ */
+export declare function waitWatchMessage(childProcess: ChildProcess, type: string, withinMs: number): Promise<void>;
+//# sourceMappingURL=sim-watch-child-message.d.ts.map

package/dist/cli/watch/sim-watch-child-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-message.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOtE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,IAAI;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAQtC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/cli/watch/sim-watch-child-message.js

@@ -0,0 +1,42 @@
+/**
+ * Whether an IPC message is one of the kind named.
+ */
+export function isWatchMessage(message, type) {
+    return (typeof message === "object" &&
+        message !== null &&
+        "type" in message &&
+        message.type === type);
+}
+/**
+ * Whether an IPC message names a path to watch.
+ */
+export function isWatchPathMessage(message, type) {
+    return (isWatchMessage(message, type) &&
+        typeof message === "object" &&
+        message !== null &&
+        "path" in message &&
+        typeof message.path === "string");
+}
+/**
+ * Wait for a process to send a message of one kind, and give up after a while.
+ *
+ * A process not running Yulin's runtime never answers, so this is a short wait
+ * rather than a requirement.
+ */
+export async function waitWatchMessage(childProcess, type, withinMs) {
+    await new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            childProcess.off("message", onMessage);
+            resolve();
+        };
+        const onMessage = (message) => {
+            if (isWatchMessage(message, type)) {
+                done();
+            }
+        };
+        const timer = setTimeout(done, withinMs);
+        childProcess.on("message", onMessage);
+    });
+}
+//# sourceMappingURL=sim-watch-child-message.js.map

package/dist/cli/watch/sim-watch-child-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-message.js","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-message.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,IAAY;IAC3D,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,MAAM,IAAI,OAAO;QACjB,OAAO,CAAC,IAAI,KAAK,IAAI,CACtB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAgB,EAChB,IAAY;IAEZ,OAAO,CACL,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC;QAC7B,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,MAAM,IAAI,OAAO;QACjB,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CACjC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,YAA0B,EAC1B,IAAY,EACZ,QAAgB;IAEhB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACvC,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QAEF,MAAM,SAAS,GAAG,CAAC,OAAgB,EAAQ,EAAE;YAC3C,IAAI,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;gBAClC,IAAI,EAAE,CAAC;YACT,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAEzC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/watch/sim-watch-child-process.d.ts

@@ -0,0 +1,22 @@
+import { type ChildProcess } from "node:child_process";
+interface SimWatchChildProcessProperties {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * A spawned command, and the two moments in its life a supervisor waits on.
+ *
+ * Standard input, output and error are the supervisor's own, so the process
+ * being watched prints where it would have printed if it had been started by
+ * hand. The fourth channel is what the runtime inside it reports paths over.
+ */
+export declare class SimWatchChildProcess {
+    readonly process: ChildProcess;
+    readonly spawned: Promise<void>;
+    readonly finished: Promise<void>;
+    constructor(properties: SimWatchChildProcessProperties);
+}
+export {};
+//# sourceMappingURL=sim-watch-child-process.d.ts.map

package/dist/cli/watch/sim-watch-child-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-process.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAE9D,UAAU,8BAA8B;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC,YAAY,UAAU,EAAE,8BAA8B,EAqBrD;CACF"}

package/dist/cli/watch/sim-watch-child-process.js

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+/**
+ * A spawned command, and the two moments in its life a supervisor waits on.
+ *
+ * Standard input, output and error are the supervisor's own, so the process
+ * being watched prints where it would have printed if it had been started by
+ * hand. The fourth channel is what the runtime inside it reports paths over.
+ */
+export class SimWatchChildProcess {
+    process;
+    spawned;
+    finished;
+    constructor(properties) {
+        const { command, args, cwd, env } = properties;
+        this.process = spawn(command, [...args], {
+            cwd,
+            env,
+            stdio: ["inherit", "inherit", "inherit", "ipc"],
+        });
+        this.spawned = new Promise((resolve, reject) => {
+            this.process.once("spawn", resolve);
+            this.process.once("error", (error) => {
+                reject(new Error(`Could not run ${command}: ${error.message}`));
+            });
+        });
+        this.finished = new Promise((resolve) => {
+            this.process.once("exit", () => {
+                resolve();
+            });
+        });
+    }
+}
+//# sourceMappingURL=sim-watch-child-process.js.map

package/dist/cli/watch/sim-watch-child-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-process.js","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAS9D;;;;;;GAMG;AACH,MAAM,OAAO,oBAAoB;IACtB,OAAO,CAAe;IACtB,OAAO,CAAgB;IACvB,QAAQ,CAAgB;IAEjC,YAAY,UAA0C;QACpD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,UAAU,CAAC;QAE/C,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;YACvC,GAAG;YACH,GAAG;YACH,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC;SAChD,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACpC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;gBAC1C,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAClE,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;gBAC7B,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/cli/watch/sim-watch-child-shutdown.d.ts

@@ -0,0 +1,28 @@
+import type { ChildProcess } from "node:child_process";
+interface SimWatchChildShutdownProperties {
+    readonly process: ChildProcess;
+    readonly finished: Promise<void>;
+}
+/**
+ * Takes a supervised process down, in the order that lets it say goodbye.
+ *
+ * A process running Yulin's runtime is warned first, so a served page hears
+ * that a reload is coming rather than only seeing its connection go, and is
+ * killed as soon as it says it has passed that on. One that does not answer,
+ * because it is serving nothing or is not a Yulin process at all, is killed
+ * when the short wait runs out. Either way it is killed, and killed harder if
+ * it will not go, because the port has to be free for the process replacing it.
+ */
+export declare class SimWatchChildShutdown {
+    private readonly process;
+    private readonly finished;
+    constructor(properties: SimWatchChildShutdownProperties);
+    /**
+     * Stop the process, and wait until it has gone.
+     */
+    stop(): Promise<void>;
+    private warn;
+    private gone;
+}
+export {};
+//# sourceMappingURL=sim-watch-child-shutdown.d.ts.map

package/dist/cli/watch/sim-watch-child-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-shutdown.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOvD,UAAU,+BAA+B;IACvC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,YAAY,UAAU,EAAE,+BAA+B,EAItD;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAI1B;YAEa,IAAI;YA0BJ,IAAI;CAWnB"}

package/dist/cli/watch/sim-watch-child-shutdown.js

@@ -0,0 +1,59 @@
+import { simWatchConfig, simWatchMessages, } from "../../watch/sim-watch.config.js";
+import { waitWatchMessage } from "./sim-watch-child-message.js";
+/**
+ * Takes a supervised process down, in the order that lets it say goodbye.
+ *
+ * A process running Yulin's runtime is warned first, so a served page hears
+ * that a reload is coming rather than only seeing its connection go, and is
+ * killed as soon as it says it has passed that on. One that does not answer,
+ * because it is serving nothing or is not a Yulin process at all, is killed
+ * when the short wait runs out. Either way it is killed, and killed harder if
+ * it will not go, because the port has to be free for the process replacing it.
+ */
+export class SimWatchChildShutdown {
+    process;
+    finished;
+    constructor(properties) {
+        const { process: childProcess, finished } = properties;
+        this.process = childProcess;
+        this.finished = finished;
+    }
+    /**
+     * Stop the process, and wait until it has gone.
+     */
+    async stop() {
+        await this.warn();
+        this.process.kill("SIGTERM");
+        await this.gone();
+    }
+    async warn() {
+        if (!this.process.connected) {
+            return;
+        }
+        const acknowledged = Promise.race([
+            this.finished,
+            waitWatchMessage(this.process, simWatchMessages.stopped, simWatchConfig.stoppingMs),
+        ]);
+        // The channel can close between being asked whether it is open and being
+        // written to, because the process is free to exit in between. The callback
+        // is where that failure goes; without one it reaches the process as an
+        // error event, and a warning that could not be delivered is not a reason to
+        // stop taking the process down.
+        this.process.send({ type: simWatchMessages.stopping }, () => {
+            // Nothing to do about a process that has already gone.
+        });
+        await acknowledged;
+    }
+    async gone() {
+        const timer = setTimeout(() => {
+            this.process.kill("SIGKILL");
+        }, simWatchConfig.exitMs);
+        try {
+            await this.finished;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=sim-watch-child-shutdown.js.map

package/dist/cli/watch/sim-watch-child-shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child-shutdown.js","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child-shutdown.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAOhE;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAqB;IACf,OAAO,CAAe;IACtB,QAAQ,CAAgB;IAEzC,YAAY,UAA2C;QACrD,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC;QACvD,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAChC,IAAI,CAAC,QAAQ;YACb,gBAAgB,CACd,IAAI,CAAC,OAAO,EACZ,gBAAgB,CAAC,OAAO,EACxB,cAAc,CAAC,UAAU,CAC1B;SACF,CAAC,CAAC;QAEH,yEAAyE;QACzE,2EAA2E;QAC3E,uEAAuE;QACvE,4EAA4E;QAC5E,gCAAgC;QAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE;YAC1D,uDAAuD;QACzD,CAAC,CAAC,CAAC;QAEH,MAAM,YAAY,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;QAE1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;CACF"}

package/dist/cli/watch/sim-watch-child.d.ts

@@ -0,0 +1,42 @@
+interface SimWatchChildProperties {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly onPath: (reportedPath: string) => void;
+    readonly onHeldPath: (heldPath: string) => void;
+    readonly onExit: (code: number | null, signal: NodeJS.Signals | null) => void;
+}
+/**
+ * One run of the supervised command.
+ *
+ * A restart is a new instance of this rather than anything swapped in place. A
+ * handler is a function reference out of the user's own module graph, and a new
+ * process re-imports it with no module cache to defeat, so a restart is correct
+ * by construction where an in-process swap would have to invalidate an import
+ * graph that ESM does not expose.
+ */
+export declare class SimWatchChild {
+    private readonly properties;
+    private readonly run;
+    private readonly startedAt;
+    private stopping;
+    private readonly onMessage;
+    private readonly onProcessExit;
+    constructor(properties: SimWatchChildProperties);
+    /**
+     * How long this process has been running.
+     */
+    ranForMs(): number;
+    /**
+     * Fail if the command could not be run at all, rather than letting it look
+     * like a process that started and stopped.
+     */
+    started(): Promise<void>;
+    /**
+     * Stop this process, giving it a moment to tell its browsers first.
+     */
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=sim-watch-child.d.ts.map

package/dist/cli/watch/sim-watch-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-watch-child.d.ts","sourceRoot":"","sources":["../../../src/cli/watch/sim-watch-child.ts"],"names":[],"mappings":"AAKA,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;CAC/E;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAQxB;IAEF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAO5B;IAEF,YAAY,UAAU,EAAE,uBAAuB,EAM9C;IAED;;OAEG;IACH,QAAQ,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7B;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1B;CACF"}