@procedures/mark 0.41.0 → 0.42.0

package/dist/args.d.ts

@@ -8,7 +8,7 @@
 import { type CommandLike, type ParsedCommandLine as KitParsedCommandLine } from "@procedures/cli-kit";
 export { findChildren, findProcedure, procedureFlags } from "@procedures/cli-kit";
 /** The long names of the global flags */
-export type GlobalName = "help" | "version" | "verbose" | "format" | "local" | "json" | "no-input" | "fs-root" | "interactive" | "server" | "port" | "host" | "transport" | "events" | "probe-port";
+export type GlobalName = "help" | "version" | "verbose" | "format" | "local" | "json" | "no-input" | "fs-root" | "interactive" | "server" | "port" | "host" | "transport" | "events" | "probe-port" | "idle-timeout";
 /** The global flags that the command line gives: true for a flag, text for a flag with a value */
 export type Globals = Partial<Record<GlobalName, string | boolean>>;
 export interface ParsedCommandLine<T extends CommandLike = CommandLike> extends Omit<KitParsedCommandLine<T>, "globals"> {

package/dist/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,iBAAiB,IAAI,oBAAoB,EAC/C,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAElF,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,SAAS,GACT,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,GACN,UAAU,GACV,SAAS,GACT,aAAa,GACb,QAAQ,GACR,MAAM,GACN,MAAM,GACN,WAAW,GACX,QAAQ,GACR,YAAY,CAAC;AAEjB,kGAAkG;AAClG,MAAM,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;AAEpE,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,CAAE,SAAQ,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;IACtH,uBAAuB;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAKD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAEnH;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAE/H"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,iBAAiB,IAAI,oBAAoB,EAC/C,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAElF,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,SAAS,GACT,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,GACN,UAAU,GACV,SAAS,GACT,aAAa,GACb,QAAQ,GACR,MAAM,GACN,MAAM,GACN,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,cAAc,CAAC;AAEnB,kGAAkG;AAClG,MAAM,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;AAEpE,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,CAAE,SAAQ,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;IACtH,uBAAuB;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAKD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAEnH;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAE/H"}

package/dist/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EACL,gBAAgB,IAAI,mBAAmB,EACvC,mBAAmB,IAAI,sBAAsB,GAG9C,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA4BlF,qGAAqG;AACrG,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAW,CAAC;AAElE;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,OAAO,sBAAsB,CAAC,IAAI,EAAE,IAAI,CAA2D,CAAC;AACtG,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAwB,IAAuB,EAAE,UAAwB;IACvG,OAAO,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAyB,CAAC;AAC7E,CAAC"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EACL,gBAAgB,IAAI,mBAAmB,EACvC,mBAAmB,IAAI,sBAAsB,GAG9C,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA6BlF,qGAAqG;AACrG,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAW,CAAC;AAElE;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,OAAO,sBAAsB,CAAC,IAAI,EAAE,IAAI,CAA2D,CAAC;AACtG,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAwB,IAAuB,EAAE,UAAwB;IACvG,OAAO,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAyB,CAAC;AAC7E,CAAC"}

package/dist/auto-warm.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The auto-warm of `mark` (CLI-27): start the background host after a cold command.
+ *
+ * - The setting `MARK_AUTO_WARM` has the values `never` (the default) and `after-cold`. The
+ *   default is `never`, because each background host holds the procedures in memory.
+ * - With `after-cold`, a command that ran in this process (the cold mode) starts `mark --server`
+ *   as a detached process before it exits. Thus the next command in this folder finds a warm host.
+ * - The background host stops by itself after `MARK_IDLE_TIMEOUT_MS` with no call (the default is
+ *   10 minutes). The spawn gives it `--idle-timeout`. A host that a user starts has no idle stop.
+ * - The command does not start a host when a warm host of this folder runs, or when another
+ *   command starts one (the start claim). It also does not start one when another program holds the port.
+ * - The auto-warm does not change the result or the exit code of the command at any time.
+ *
+ * The spawn is `spawnMarkServer()` of `@procedures/server`, the start of `server.start`. It does
+ * not use `runCommand()` or `shell.run`, because the host must outlive the command.
+ * `SERVER-LAYERS.md` records this exception.
+ */
+/** The values of the setting `MARK_AUTO_WARM`. */
+export declare const AUTO_WARM_SETTINGS: readonly ["never", "after-cold"];
+/** The setting of the auto-warm: `never`, or `after-cold`. */
+export type AutoWarmSetting = (typeof AUTO_WARM_SETTINGS)[number];
+/** The environment variable of the setting. */
+export declare const AUTO_WARM_ENV = "MARK_AUTO_WARM";
+/** The environment variable of the idle stop of the host that the auto-warm starts, in milliseconds. */
+export declare const IDLE_TIMEOUT_ENV = "MARK_IDLE_TIMEOUT_MS";
+/** The environment variable of the port of the host that the auto-warm starts. */
+export declare const AUTO_WARM_PORT_ENV = "MARK_AUTO_WARM_PORT";
+/** The default idle stop of the host that the auto-warm starts: 10 minutes. */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 600000;
+/** The default port of the host that the auto-warm starts: the default port of `mark --server`. */
+export declare const DEFAULT_AUTO_WARM_PORT = 3000;
+/**
+ * The age after which a start claim is stale: 60 s. The startup of a host has a cap of 30 s. A
+ * claim also goes stale when its process ended.
+ */
+export declare const START_CLAIM_MAX_AGE_MS = 60000;
+/** The configuration of the auto-warm. */
+export interface AutoWarmConfig {
+    readonly setting: AutoWarmSetting;
+    /** The idle stop of the host, in milliseconds. */
+    readonly idleTimeoutMs: number;
+    /** The port of the host. */
+    readonly port: number;
+    /** The address of the host: loopback. */
+    readonly host: string;
+}
+/**
+ * This function reads the milliseconds of an idle stop: a whole number of 1 or more. An
+ * invalid value is an error, and the error names the option.
+ */
+export declare function parseIdleTimeout(value: string, option?: string): number;
+/**
+ * This function gives the configuration of the auto-warm from the environment. An unset or empty
+ * variable gives its default. An invalid value is an error.
+ */
+export declare function autoWarmConfig(env?: Readonly<Record<string, string | undefined>>): AutoWarmConfig;
+/** The facts of the decision of the auto-warm. */
+export interface WarmFacts {
+    readonly setting: AutoWarmSetting;
+    /** True when a warm host of this folder, build and root runs (`findServer()`). */
+    readonly warmHost: boolean;
+    /** True when another command claimed the start of a host, and the claim is not stale. */
+    readonly starting: boolean;
+    /** True when a server or another program holds the port. */
+    readonly portBusy: boolean;
+}
+/** The decision of the auto-warm: start a host, or not, and why. */
+export type WarmDecision = {
+    readonly spawn: true;
+} | {
+    readonly spawn: false;
+    readonly reason: string;
+};
+/** This function decides if a cold command starts the background host. */
+export declare function decideAutoWarm(facts: WarmFacts): WarmDecision;
+/** The steps of the auto-warm. The tests give fakes, so no test starts a process or opens a port. */
+export interface AutoWarmSteps {
+    /** This function tells if a warm host of this folder, build and root runs. */
+    findWarmHost(): Promise<boolean>;
+    /** This function claims the start of the host. It gives false when another command has a claim that is not stale. */
+    claimStart(): boolean;
+    /** This function writes the process ID of the new host in the claim. */
+    recordStart(pid: number): void;
+    /** This function removes the claim of this command. */
+    releaseStart(): void;
+    /** This function tells if a server or another program holds the port. */
+    portBusy(): Promise<boolean>;
+    /** This function starts the host as a detached process, and gives its process ID. */
+    spawn(): number | undefined;
+}
+/**
+ * This function does the auto-warm after a cold command, and gives the decision. The claim
+ * makes the decision atomic: of two cold commands at the same time, only one starts a host.
+ */
+export declare function autoWarm(setting: AutoWarmSetting, steps: AutoWarmSteps): Promise<WarmDecision>;
+/** The options of `startClaim()`. */
+export interface StartClaimOptions {
+    /** The folder of the claim. The default is `~/.mark`. */
+    readonly dir?: string | undefined;
+    /** This function gives the time, in milliseconds. The default is `Date.now`. */
+    readonly now?: (() => number) | undefined;
+    /** This function tells if a process runs. The default is `process.kill(pid, 0)`. */
+    readonly alive?: ((pid: number) => boolean) | undefined;
+    /** The age after which a claim is stale. The default is `START_CLAIM_MAX_AGE_MS`. */
+    readonly maxAgeMs?: number | undefined;
+}
+/**
+ * This function gives the start claim of a port: the file `~/.mark/auto-warm-<port>.claim`. The
+ * file is made with the flag `wx`, so only one command gets the claim. A claim is stale after
+ * `maxAgeMs`, or when its process ended. A stale claim goes, and the next command can claim again.
+ */
+export declare function startClaim(port: number, options?: StartClaimOptions): Pick<AutoWarmSteps, "claimStart" | "recordStart" | "releaseStart">;
+/** This function tells if something accepts a connection on a port, within the time limit. */
+export declare function portAnswers(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+/** Where a cold command runs: the folder, the build of `mark` and the root of the files. */
+export interface WarmContext {
+    readonly cwd: string;
+    readonly build: string;
+    readonly fsRoot?: string | undefined;
+}
+/**
+ * This function gives the steps of the auto-warm with the lockfiles, the start claim of the port
+ * and `spawnMarkServer()` of `@procedures/server`.
+ */
+export declare function autoWarmSteps(config: AutoWarmConfig, context: WarmContext, spawnHost: (options: {
+    port: number;
+    host: string;
+    idleTimeoutMs: number;
+    fsRoot?: string | undefined;
+}) => {
+    readonly pid?: number | undefined;
+}): AutoWarmSteps;
+//# sourceMappingURL=auto-warm.d.ts.map

package/dist/auto-warm.d.ts.map

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

package/dist/auto-warm.js

@@ -0,0 +1,230 @@
+/**
+ * The auto-warm of `mark` (CLI-27): start the background host after a cold command.
+ *
+ * - The setting `MARK_AUTO_WARM` has the values `never` (the default) and `after-cold`. The
+ *   default is `never`, because each background host holds the procedures in memory.
+ * - With `after-cold`, a command that ran in this process (the cold mode) starts `mark --server`
+ *   as a detached process before it exits. Thus the next command in this folder finds a warm host.
+ * - The background host stops by itself after `MARK_IDLE_TIMEOUT_MS` with no call (the default is
+ *   10 minutes). The spawn gives it `--idle-timeout`. A host that a user starts has no idle stop.
+ * - The command does not start a host when a warm host of this folder runs, or when another
+ *   command starts one (the start claim). It also does not start one when another program holds the port.
+ * - The auto-warm does not change the result or the exit code of the command at any time.
+ *
+ * The spawn is `spawnMarkServer()` of `@procedures/server`, the start of `server.start`. It does
+ * not use `runCommand()` or `shell.run`, because the host must outlive the command.
+ * `SERVER-LAYERS.md` records this exception.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { connect } from "node:net";
+import { checkServer, findServer, getMarkDir, readLockfileForPort } from "@procedures/peer/lockfile";
+/** The values of the setting `MARK_AUTO_WARM`. */
+export const AUTO_WARM_SETTINGS = ["never", "after-cold"];
+/** The environment variable of the setting. */
+export const AUTO_WARM_ENV = "MARK_AUTO_WARM";
+/** The environment variable of the idle stop of the host that the auto-warm starts, in milliseconds. */
+export const IDLE_TIMEOUT_ENV = "MARK_IDLE_TIMEOUT_MS";
+/** The environment variable of the port of the host that the auto-warm starts. */
+export const AUTO_WARM_PORT_ENV = "MARK_AUTO_WARM_PORT";
+/** The default idle stop of the host that the auto-warm starts: 10 minutes. */
+export const DEFAULT_IDLE_TIMEOUT_MS = 600_000;
+/** The default port of the host that the auto-warm starts: the default port of `mark --server`. */
+export const DEFAULT_AUTO_WARM_PORT = 3000;
+/**
+ * The age after which a start claim is stale: 60 s. The startup of a host has a cap of 30 s. A
+ * claim also goes stale when its process ended.
+ */
+export const START_CLAIM_MAX_AGE_MS = 60_000;
+/**
+ * This function reads the milliseconds of an idle stop: a whole number of 1 or more. An
+ * invalid value is an error, and the error names the option.
+ */
+export function parseIdleTimeout(value, option = "--idle-timeout") {
+    const timeout = /^\d+$/.test(value.trim()) ? Number(value.trim()) : Number.NaN;
+    if (!Number.isSafeInteger(timeout) || timeout < 1) {
+        throw new Error(`Invalid ${option}: "${value}". Give a number of milliseconds of 1 or more.`);
+    }
+    return timeout;
+}
+/**
+ * This function gives the configuration of the auto-warm from the environment. An unset or empty
+ * variable gives its default. An invalid value is an error.
+ */
+export function autoWarmConfig(env = process.env) {
+    const given = env[AUTO_WARM_ENV]?.trim() ?? "";
+    const setting = given === "" ? "never" : AUTO_WARM_SETTINGS.find((each) => each === given);
+    if (setting === undefined) {
+        throw new Error(`Invalid ${AUTO_WARM_ENV}: "${given}". Give one of: ${AUTO_WARM_SETTINGS.join(", ")}.`);
+    }
+    const idle = env[IDLE_TIMEOUT_ENV]?.trim() ?? "";
+    const portText = env[AUTO_WARM_PORT_ENV]?.trim() ?? "";
+    const port = portText === "" ? DEFAULT_AUTO_WARM_PORT : Number(portText);
+    if (!/^\d+$/.test(portText === "" ? "0" : portText) || !Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid ${AUTO_WARM_PORT_ENV}: "${portText}". Give a number from 1 to 65535.`);
+    }
+    return {
+        setting,
+        idleTimeoutMs: idle === "" ? DEFAULT_IDLE_TIMEOUT_MS : parseIdleTimeout(idle, IDLE_TIMEOUT_ENV),
+        port,
+        host: "127.0.0.1",
+    };
+}
+/** This function decides if a cold command starts the background host. */
+export function decideAutoWarm(facts) {
+    if (facts.setting === "never")
+        return { spawn: false, reason: `${AUTO_WARM_ENV} is never` };
+    if (facts.warmHost)
+        return { spawn: false, reason: "a warm host runs" };
+    if (facts.starting)
+        return { spawn: false, reason: "another command starts the host" };
+    if (facts.portBusy)
+        return { spawn: false, reason: "the port is in use" };
+    return { spawn: true };
+}
+/**
+ * This function does the auto-warm after a cold command, and gives the decision. The claim
+ * makes the decision atomic: of two cold commands at the same time, only one starts a host.
+ */
+export async function autoWarm(setting, steps) {
+    const facts = { setting, warmHost: false, starting: false, portBusy: false };
+    if (setting === "never")
+        return decideAutoWarm(facts);
+    facts.warmHost = await steps.findWarmHost();
+    if (facts.warmHost)
+        return decideAutoWarm(facts);
+    facts.starting = !steps.claimStart();
+    if (facts.starting)
+        return decideAutoWarm(facts);
+    try {
+        facts.portBusy = await steps.portBusy();
+        const decision = decideAutoWarm(facts);
+        if (!decision.spawn) {
+            steps.releaseStart();
+            return decision;
+        }
+        const pid = steps.spawn();
+        if (pid === undefined) {
+            steps.releaseStart();
+            return { spawn: false, reason: "the host process did not start" };
+        }
+        steps.recordStart(pid);
+        return decision;
+    }
+    catch (error) {
+        steps.releaseStart();
+        throw error;
+    }
+}
+/** True when a process runs. A process of another user also runs (`EPERM`). */
+function processRuns(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * This function gives the start claim of a port: the file `~/.mark/auto-warm-<port>.claim`. The
+ * file is made with the flag `wx`, so only one command gets the claim. A claim is stale after
+ * `maxAgeMs`, or when its process ended. A stale claim goes, and the next command can claim again.
+ */
+export function startClaim(port, options = {}) {
+    const dir = options.dir ?? getMarkDir();
+    const file = path.join(dir, `auto-warm-${port}.claim`);
+    const now = options.now ?? Date.now;
+    const alive = options.alive ?? processRuns;
+    const maxAgeMs = options.maxAgeMs ?? START_CLAIM_MAX_AGE_MS;
+    let owned = false;
+    const write = (claim, flag) => {
+        fs.writeFileSync(file, JSON.stringify(claim), { flag, mode: 0o600 });
+    };
+    const stale = () => {
+        let claim;
+        try {
+            claim = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            // No file: the claim went at this time. A file that does not parse is stale.
+            return error.code !== "ENOENT";
+        }
+        if (typeof claim.at !== "number" || now() - claim.at >= maxAgeMs)
+            return true;
+        return claim.pid !== undefined && !alive(claim.pid);
+    };
+    const tryClaim = () => {
+        try {
+            write({ at: now() }, "wx");
+            return true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+    };
+    return {
+        claimStart() {
+            fs.mkdirSync(dir, { recursive: true });
+            if (tryClaim()) {
+                owned = true;
+                return true;
+            }
+            if (!stale())
+                return false;
+            fs.rmSync(file, { force: true });
+            owned = tryClaim();
+            return owned;
+        },
+        recordStart(pid) {
+            if (owned)
+                write({ at: now(), pid }, "w");
+        },
+        releaseStart() {
+            if (!owned)
+                return;
+            owned = false;
+            fs.rmSync(file, { force: true });
+        },
+    };
+}
+/** This function tells if something accepts a connection on a port, within the time limit. */
+export function portAnswers(host, port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const socket = connect({ host, port });
+        const done = (answers) => {
+            socket.destroy();
+            resolve(answers);
+        };
+        socket.setTimeout(timeoutMs, () => done(false));
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+    });
+}
+/**
+ * This function gives the steps of the auto-warm with the lockfiles, the start claim of the port
+ * and `spawnMarkServer()` of `@procedures/server`.
+ */
+export function autoWarmSteps(config, context, spawnHost) {
+    const claim = startClaim(config.port);
+    return {
+        ...claim,
+        findWarmHost: async () => (await findServer({ cwd: context.cwd, build: context.build, fsRoot: context.fsRoot })) !== null,
+        portBusy: async () => {
+            // A server of a lockfile on the port: of another folder, build or root
+            const lockfile = readLockfileForPort(config.port);
+            if (lockfile !== null && (await checkServer(lockfile)) !== "dead")
+                return true;
+            return portAnswers(config.host, config.port);
+        },
+        spawn: () => spawnHost({
+            port: config.port,
+            host: config.host,
+            idleTimeoutMs: config.idleTimeoutMs,
+            ...(context.fsRoot !== undefined ? { fsRoot: context.fsRoot } : {}),
+        }).pid,
+    };
+}
+//# sourceMappingURL=auto-warm.js.map

package/dist/auto-warm.js.map

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

package/dist/cli.d.ts

@@ -9,6 +9,7 @@ import type { AnyProcedure, ProcedureRegistry } from "@procedures/client";
 import type { RunOptions } from "@mark1russell7/service";
 import { type ManifestCommand } from "./manifest.js";
 import { type Asker, type Terminal } from "./ask.js";
+import { type AutoWarmConfig } from "./auto-warm.js";
 /**
  * CLI execution context, created once and reused
  */
@@ -55,6 +56,11 @@ export interface ExecuteOptions {
      * then installs no signal handler, does not end the process, and records its exit code in `process.exitCode`.
      */
     ownsProcess?: boolean | undefined;
+    /**
+     * The auto-warm (CLI-27). With the setting `after-cold`, a cold command starts the background
+     * host before it ends. Without it, no command starts a host. The bin reads it from `MARK_AUTO_WARM`.
+     */
+    autoWarm?: AutoWarmConfig | undefined;
 }
 /**
  * Initialize the CLI context (load ecosystem, create client)
@@ -81,7 +87,7 @@ export declare function initCli(verbose?: boolean, fsRoot?: string): Promise<Cli
  */
 export declare function executeArgs(argv: string[], ctx: CliContext | ManifestContext, options?: ExecuteOptions): Promise<void>;
 /** The options of `run()` and `main()`: the process of the service of each command (CLI-26). */
-export type RunCliOptions = Pick<ExecuteOptions, "run" | "ownsProcess">;
+export type RunCliOptions = Pick<ExecuteOptions, "run" | "ownsProcess" | "autoWarm">;
 /**
  * Run the CLI. By default, the caller owns the process: a command records its exit code in
  * `process.exitCode`, and the process does not end. The bin gives `ownsProcess: true`.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAGH,OAAO,KAAK,EAAU,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKrE,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAqE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AA+FxH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC,cAAc,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACjE,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;CACjC;AAED,uHAAuH;AACvH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAgBD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,OAAO,UAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBnF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,UAAU,GAAG,eAAe,EACjC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAiQf;AAkID,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,aAAa,CAAC,CAAC;AAExE;;;GAGG;AACH,iBAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsG7E;AAED;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9F;AA2BD,OAAO,EAAE,GAAG,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAGH,OAAO,KAAK,EAAU,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKrE,OAAO,EAAoC,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,OAAO,EAAqE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAMxH,OAAO,EAA6D,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA0FhH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC,cAAc,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACjE,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;CACjC;AAED,uHAAuH;AACvH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CACvC;AAgBD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,OAAO,UAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBnF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,UAAU,GAAG,eAAe,EACjC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmQf;AA4KD,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,aAAa,GAAG,UAAU,CAAC,CAAC;AAErF;;;GAGG;AACH,iBAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6G7E;AAED;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9F;AA2BD,OAAO,EAAE,GAAG,EAAE,CAAC"}

package/dist/cli.js

@@ -16,6 +16,7 @@ import { formatOutput } from "./format.js";
 import { loadEcosystemRegistry } from "./ecosystem.js";
 import { startServerMode, parsePort, parseTransport } from "./server-mode.js";
 import { connectCliServer } from "./client-mode.js";
+import { autoWarm, autoWarmConfig, autoWarmSteps, parseIdleTimeout } from "./auto-warm.js";
 import { startRepl } from "./repl.js";
 import { findChildren, findProcedure, parseCommandLine, parseLeadingGlobals } from "./args.js";
 import { groupHelp, rootHelp, validationMessage } from "@procedures/cli-kit";
@@ -74,7 +75,7 @@ function showRootHelp(procedures) {
         footer: [
             "Hosts: 'mark serve [--procedures pkgs] [--port N] [--expose patterns] [--events topics]' (the procedure server),",
             "       'mark mcp' (the dev-tools MCP server over stdio).",
-            "Modes: 'mark --server [--port N] [--host H] [--transport http|websocket|both] [--events topics] [--probe-port N]' and 'mark -i' (the REPL).",
+            "Modes: 'mark --server [--port N] [--host H] [--transport http|websocket|both] [--events topics] [--probe-port N] [--idle-timeout ms]' and 'mark -i' (the REPL).",
             "Root:  'mark --fs-root <folder> <command>' keeps each path of each procedure in the folder, also in each mode and host.",
             "       It refuses the procedures that it cannot confine: git, pnpm, docker run, a program (FORBIDDEN, outside-root).",
         ],
@@ -83,7 +84,7 @@ function showRootHelp(procedures) {
         print.info(line);
 }
 /** The global flags that only `--server` takes. */
-const SERVER_OPTIONS = ["port", "host", "transport", "events", "probe-port"];
+const SERVER_OPTIONS = ["port", "host", "transport", "events", "probe-port", "idle-timeout"];
 /** True when the global flags give an option of `--server`. */
 function hasServerOption(globals) {
     return SERVER_OPTIONS.some((name) => globals[name] !== undefined);
@@ -175,7 +176,7 @@ export async function executeArgs(argv, ctx, options = {}) {
         return;
     }
     if (hasServerOption(globals)) {
-        fail("--port, --host, --transport, --events and --probe-port are options of --server.");
+        fail("--port, --host, --transport, --events, --probe-port and --idle-timeout are options of --server.");
         return;
     }
     // The root applies to the whole run: the procedures load with it, and a warm server must have it
@@ -235,6 +236,7 @@ export async function executeArgs(argv, ctx, options = {}) {
                 fail(`Error: ${messageOf(error)}`);
             }
         });
+        await warmAfterCold(cold, options, path, globals.local === true, ctx);
         await endCommand(cold.command, end, failed);
         return;
     }
@@ -387,8 +389,48 @@ export async function executeArgs(argv, ctx, options = {}) {
             failCommand(`Error: ${messageOf(error)}`);
         }
     });
+    await warmAfterCold(cold, options, path, globals.local === true, ctx);
     await endCommand(cold.command, end, failed);
 }
+/**
+ * This function does the auto-warm after a cold command (CLI-27), before the end of its service:
+ * with the process of Node, `endCommand()` ends the process. The auto-warm does not operate with
+ * `--local`, for a `server.*` command, or after a signal started the stop. An error of the
+ * auto-warm does not change the command: with `--verbose`, it prints a warning.
+ */
+async function warmAfterCold(cold, options, path, local, ctx) {
+    const config = options.autoWarm;
+    if (config === undefined || config.setting === "never" || local || path[0] === "server")
+        return;
+    if (cold.command.life.state !== "running")
+        return;
+    try {
+        const { currentBuild } = await import("./lockfile.js");
+        const { spawnMarkServer } = await import("@procedures/server");
+        const steps = autoWarmSteps(config, { cwd: process.cwd(), build: currentBuild(), fsRoot: ctx.fsRoot }, (spawn) => spawnMarkServer(spawn).child);
+        const decision = await autoWarm(config.setting, steps);
+        if (ctx.verbose) {
+            print.muted(decision.spawn ? `mark: the background host starts on port ${config.port} (${config.setting})` : `mark: no background host: ${decision.reason}`);
+        }
+    }
+    catch (error) {
+        if (ctx.verbose)
+            print.warning(`mark: the auto-warm failed: ${messageOf(error)}`);
+    }
+}
+/**
+ * This function reads the auto-warm from the environment. An invalid value gives a message on the
+ * standard error and no auto-warm, because the auto-warm does not change the result of a command.
+ */
+function readAutoWarm() {
+    try {
+        return autoWarmConfig();
+    }
+    catch (error) {
+        print.error(`mark: no auto-warm: ${messageOf(error)}`);
+        return undefined;
+    }
+}
 /**
  * This function starts the cold mode of a command: the procedures host of the CLI server, in this
  * process, under `run()` (CLI-26). After a startup that failed, it prints the errors, waits for the
@@ -568,6 +610,8 @@ async function run(argv, options = {}) {
         const events = await eventPatterns(globals.events);
         // --probe-port: the probes answer on a port of their own (CLI-9, decision D5)
         const probePort = globals["probe-port"] === undefined ? undefined : parsePort(String(globals["probe-port"]));
+        // --idle-timeout: the server stops by itself after this time with no call (CLI-27)
+        const idleTimeoutMs = globals["idle-timeout"] === undefined ? undefined : parseIdleTimeout(String(globals["idle-timeout"]));
         await startServerMode({
             port,
             host,
@@ -575,13 +619,14 @@ async function run(argv, options = {}) {
             verbose,
             events,
             ...(probePort !== undefined ? { probePort } : {}),
+            ...(idleTimeoutMs !== undefined ? { idleTimeoutMs } : {}),
             ...(fsRoot !== undefined ? { fsRoot } : {}),
         });
         return;
     }
     // Before, `mark --port 4000 serve` ignored --port without a word
     if (hasServerOption(globals)) {
-        fail("--port, --host, --transport, --events and --probe-port are options of --server.", "For mark serve, give them after serve.");
+        fail("--port, --host, --transport, --events, --probe-port and --idle-timeout are options of --server.", "For mark serve, give them after serve.");
         return;
     }
     // Handle -i / --interactive flag: start REPL
@@ -612,11 +657,14 @@ async function run(argv, options = {}) {
         await startMcp(commandArgs, fsRoot);
         return;
     }
+    // The auto-warm (CLI-27): the bin reads MARK_AUTO_WARM. Another caller gives the option, or has none.
+    const warm = options.autoWarm ?? (options.ownsProcess === true ? readAutoWarm() : undefined);
+    const execute = { ...options, ...(warm !== undefined ? { autoWarm: warm } : {}) };
     // The manifest gives the commands without the procedures: the help and a call to the CLI
     // server do not load them (roadmap 1.3)
     const manifest = readFreshManifest();
     if (manifest) {
-        await executeArgs(argv, { commands: manifest.commands, verbose, fsRoot, load: () => initCli(verbose, fsRoot) }, options);
+        await executeArgs(argv, { commands: manifest.commands, verbose, fsRoot, load: () => initCli(verbose, fsRoot) }, execute);
         return;
     }
     // No manifest, or a stale one (a package was built again): load the procedures as before, and
@@ -630,7 +678,7 @@ async function run(argv, options = {}) {
             print.warning(`mark: the manifest was not written: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    await executeArgs(argv, ctx, options);
+    await executeArgs(argv, ctx, execute);
 }
 /**
  * Run the CLI and report an error that escapes it as one line, with exit code 1. With