@dailephd/my-dev-kit-lab 0.4.6 → 0.4.8

package/dist/src/core/processTree.js

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+/**
+ * Asks a process to terminate normally.
+ *
+ * Sends SIGTERM on every platform. On Windows Node maps SIGTERM to
+ * TerminateProcess, so the named process is terminated but its descendants are
+ * not; this is a best-effort "please stop" step, not a tree operation.
+ *
+ * Never throws: the process may already have exited between the caller's
+ * liveness check and this call.
+ */
+export function requestProcessTermination(pid) {
+    if (!pid) {
+        return;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // The process may have exited between the liveness check and this signal.
+    }
+}
+/**
+ * Forced cleanup for a process that did not stop on request.
+ *
+ * Windows: `taskkill /pid <pid> /T /F` with shell:false. `/T` makes this a real
+ * descendant-tree termination on Windows.
+ *
+ * Other platforms: a single `process.kill(pid, signal)` on the known process ID.
+ * This deliberately does NOT walk or signal the descendant tree -- no process
+ * group or `pgid` traversal is performed here -- so a child that spawned its own
+ * grandchildren may leave those grandchildren running. The file name reflects
+ * the Windows capability and the shared call site, not a POSIX tree guarantee.
+ *
+ * Never throws.
+ */
+export function forceTerminateProcess(pid, options = {}) {
+    if (!pid) {
+        return;
+    }
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { shell: false, stdio: "ignore" });
+        killer.on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(pid, options.posixSignal ?? "SIGTERM");
+    }
+    catch {
+        // The process may have exited between the liveness check and this signal.
+    }
+}

package/dist/src/core/resolveCommand.js

@@ -159,3 +159,37 @@ function isExecutableFile(candidatePath) {
         return false;
     }
 }
+/**
+ * Builds the spawn-ready invocation for an already-resolved command.
+ *
+ * Exposed separately from `resolveCommandInvocation` so callers that legitimately
+ * bypass PATH resolution (for example `runMeasuredCommand({ resolveCommand: false })`)
+ * still share one argument-assembly rule.
+ *
+ * `windows-cmd-shim` resolutions run `cmd.exe /d /s /c call <resolvedPath> ...`,
+ * so the resolved shim path is inserted after the prefix. Every other resolution
+ * kind (including `windows-powershell-shim`, whose `argsPrefix` already ends with
+ * `-File <resolvedPath>`) only needs prefix + caller arguments.
+ */
+export function buildResolvedCommandInvocation(resolvedCommand, args) {
+    const trailingArgs = [...args];
+    const invocationArgs = resolvedCommand.resolutionKind === "windows-cmd-shim" && resolvedCommand.resolvedPath
+        ? [...resolvedCommand.argsPrefix, resolvedCommand.resolvedPath, ...trailingArgs]
+        : [...resolvedCommand.argsPrefix, ...trailingArgs];
+    return {
+        executable: resolvedCommand.command,
+        args: invocationArgs,
+        resolvedCommand
+    };
+}
+/**
+ * Resolves `executable` through `resolveCommand()` and returns the spawn-ready
+ * executable/argument pair. Never introduces `shell: true`.
+ *
+ * An unavailable command is returned as a structured invocation whose
+ * `resolvedCommand.resolutionKind` is "unavailable"; callers decide whether that
+ * is a skip or a failure.
+ */
+export function resolveCommandInvocation(executable, args, options = {}) {
+    return buildResolvedCommandInvocation(resolveCommand(executable, options), args);
+}

package/dist/src/core/runMeasuredCommand.js

@@ -1,31 +1,35 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { parseCommandString } from "./commandLine.js";
-import { resolveCommand } from "./resolveCommand.js";
+import { parseCommandString, serializeCommand } from "./commandLine.js";
+import { forceTerminateProcess } from "./processTree.js";
+import { buildResolvedCommandInvocation, resolveCommandInvocation } from "./resolveCommand.js";
 export { parseCommandString } from "./commandLine.js";
 export async function runMeasuredCommand(options) {
     await mkdir(options.outDir, { recursive: true });
-    const parsed = parseCommandString(options.commandString);
-    const resolution = options.resolveCommand === false
-        ? {
-            originalCommand: parsed.executable,
-            command: parsed.executable,
+    const named = readCommandName(options);
+    const commandString = named.commandString;
+    const trailingArgs = [...named.args, ...(options.extraArgs ?? [])];
+    // Windows .cmd/.bat/.ps1 argument assembly is owned by resolveCommand.ts so
+    // that every spawn site (measured commands and managed long-running processes)
+    // shares exactly one shim rule.
+    const invocation = options.resolveCommand === false
+        ? buildResolvedCommandInvocation({
+            originalCommand: named.executable,
+            command: named.executable,
             argsPrefix: [],
             resolutionKind: "direct",
-            resolvedPath: parsed.executable,
+            resolvedPath: named.executable,
             warnings: []
-        }
-        : resolveCommand(parsed.executable, {
+        }, trailingArgs)
+        : resolveCommandInvocation(named.executable, trailingArgs, {
             cwd: options.cwd,
             env: { ...process.env, ...options.env },
             allowPowerShellShim: options.allowPowerShellShim
         });
-    const executable = resolution.command;
-    const trailingArgs = [...parsed.args, ...(options.extraArgs ?? [])];
-    const args = resolution.resolutionKind === "windows-cmd-shim" && resolution.resolvedPath
-        ? [...resolution.argsPrefix, resolution.resolvedPath, ...trailingArgs]
-        : [...resolution.argsPrefix, ...trailingArgs];
+    const resolution = invocation.resolvedCommand;
+    const executable = invocation.executable;
+    const args = invocation.args;
     const stdoutPath = path.join(options.outDir, `${options.commandId}.stdout.txt`);
     const stderrPath = path.join(options.outDir, `${options.commandId}.stderr.txt`);
     const telemetryPath = path.join(options.outDir, `${options.commandId}.telemetry.json`);
@@ -52,7 +56,7 @@ export async function runMeasuredCommand(options) {
             const message = error instanceof Error ? error.message : String(error);
             const measured = {
                 commandId: options.commandId,
-                commandString: options.commandString,
+                commandString,
                 executable,
                 args,
                 cwd: options.cwd,
@@ -89,7 +93,7 @@ export async function runMeasuredCommand(options) {
             timeout = setTimeout(() => {
                 timedOut = true;
                 spawnError = `Command timed out after ${options.timeoutMs}ms.`;
-                killProcessTree(child.pid);
+                forceTerminateProcess(child.pid);
             }, options.timeoutMs);
         }
         child.on("close", async (exitCode) => {
@@ -102,7 +106,7 @@ export async function runMeasuredCommand(options) {
             await writeArtifact(stderrPath, stderr);
             const measured = {
                 commandId: options.commandId,
-                commandString: options.commandString,
+                commandString,
                 executable,
                 args,
                 cwd: options.cwd,
@@ -129,19 +133,23 @@ async function writeArtifact(filePath, value) {
     await mkdir(path.dirname(filePath), { recursive: true });
     await writeFile(filePath, value, "utf8");
 }
-function killProcessTree(pid) {
-    if (!pid) {
-        return;
-    }
-    if (process.platform === "win32") {
-        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { shell: false, stdio: "ignore" });
-        killer.on("error", () => undefined);
-        return;
-    }
-    try {
-        process.kill(pid, "SIGTERM");
+/**
+ * Normalizes either input form into an executable, its arguments, and a
+ * human-readable command line for the telemetry record. The serialized string is
+ * for display only -- it is never parsed back into arguments.
+ */
+function readCommandName(options) {
+    if (options.commandString !== undefined) {
+        const parsed = parseCommandString(options.commandString);
+        return { executable: parsed.executable, args: parsed.args, commandString: options.commandString };
     }
-    catch {
-        // The child may have exited between timeout scheduling and kill.
+    if (options.executable !== undefined) {
+        const args = [...(options.args ?? [])];
+        return {
+            executable: options.executable,
+            args,
+            commandString: serializeCommand([options.executable, ...args])
+        };
     }
+    throw new Error("runMeasuredCommand requires either a commandString or an executable.");
 }

package/dist/src/runtime/index.js

@@ -1,3 +1,4 @@
 export * from "./packageRoot.js";
 export * from "./labExecutionContext.js";
 export * from "./packageResource.js";
+export * from "./managedProcess.js";

package/dist/src/runtime/managedProcess.js

@@ -0,0 +1,380 @@
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { mkdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { forceTerminateProcess, requestProcessTermination } from "../core/processTree.js";
+import { resolveCommandInvocation } from "../core/resolveCommand.js";
+/**
+ * Long-running child process lifecycle.
+ *
+ * This owner is deliberately NOT a replacement for `runMeasuredCommand`.
+ * `runMeasuredCommand` owns bounded commands that are expected to terminate and
+ * whose full output is a measurement artifact. `startManagedProcess` owns
+ * commands that are expected to stay alive until explicitly stopped (local demo
+ * servers and viewers), so it returns a handle instead of a completed result and
+ * streams its logs to disk instead of accumulating them in memory.
+ *
+ * It reuses the canonical command resolver and the shared process-termination
+ * primitive; it does not implement a second command resolver and never uses a
+ * shell.
+ */
+/** Bounded in-memory diagnostic tail retained per stream. Disk logs stay complete. */
+export const MANAGED_PROCESS_CAPTURE_LIMIT_BYTES = 256 * 1024;
+export const MANAGED_PROCESS_DEFAULT_GRACE_PERIOD_MS = 1500;
+export const MANAGED_PROCESS_DEFAULT_READINESS_INTERVAL_MS = 100;
+export const MANAGED_PROCESS_DEFAULT_REQUEST_TIMEOUT_MS = 1000;
+export const MANAGED_PROCESS_DEFAULT_ACCEPTED_STATUS_MIN = 200;
+export const MANAGED_PROCESS_DEFAULT_ACCEPTED_STATUS_MAX = 399;
+/** Hostnames a readiness probe is permitted to contact. Loopback only, by design. */
+const ALLOWED_READINESS_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+/**
+ * Thrown by `startManagedProcess` when the spec cannot produce a process at all.
+ *
+ * Start-time problems throw because there is no handle to return. Runtime states
+ * a caller is expected to handle -- readiness timeout, the child exiting before
+ * readiness, an invalid probe -- are returned as structured results instead.
+ */
+export class ManagedProcessStartError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ManagedProcessStartError";
+    }
+}
+export async function startManagedProcess(spec) {
+    const id = validateProcessId(spec.id);
+    const executable = typeof spec.executable === "string" ? spec.executable.trim() : "";
+    if (executable.length === 0) {
+        throw new ManagedProcessStartError("Managed process executable must be a non-empty string.");
+    }
+    if (typeof spec.cwd !== "string" || spec.cwd.trim().length === 0) {
+        throw new ManagedProcessStartError("Managed process cwd must be a non-empty path.");
+    }
+    if (typeof spec.outDir !== "string" || spec.outDir.trim().length === 0) {
+        throw new ManagedProcessStartError("Managed process outDir must be a non-empty path.");
+    }
+    const cwd = path.resolve(spec.cwd);
+    try {
+        if (!(await stat(cwd)).isDirectory()) {
+            throw new Error("not a directory");
+        }
+    }
+    catch {
+        throw new ManagedProcessStartError(`Managed process cwd is not an existing directory: ${cwd}`);
+    }
+    const outDir = path.resolve(spec.outDir);
+    try {
+        await mkdir(outDir, { recursive: true });
+    }
+    catch (error) {
+        throw new ManagedProcessStartError(`Managed process outDir could not be created: ${outDir} (${messageOf(error)})`);
+    }
+    const env = { ...process.env, ...spec.env };
+    const invocation = resolveCommandInvocation(executable, spec.args ?? [], {
+        cwd,
+        env,
+        allowPowerShellShim: spec.allowPowerShellShim
+    });
+    if (invocation.resolvedCommand.resolutionKind === "unavailable") {
+        const warnings = invocation.resolvedCommand.warnings;
+        throw new ManagedProcessStartError(`Managed process command is unavailable: ${executable}${warnings.length > 0 ? ` (${warnings.join("; ")})` : ""}`);
+    }
+    const stdoutPath = path.join(outDir, `${id}.stdout.txt`);
+    const stderrPath = path.join(outDir, `${id}.stderr.txt`);
+    // stdio ["ignore", "pipe", "pipe"]: stdin is deliberately not held open.
+    let child;
+    try {
+        child = spawn(invocation.executable, invocation.args, {
+            cwd,
+            env,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+    }
+    catch (error) {
+        throw new ManagedProcessStartError(`Managed process failed to spawn: ${executable} (${messageOf(error)})`);
+    }
+    let exited = false;
+    let exitResult;
+    let spawnError;
+    const exitWaiters = [];
+    // Attached before any early return so a spawn failure can never surface as an
+    // unhandled 'error' event.
+    child.on("error", (error) => {
+        spawnError = error.message;
+    });
+    if (child.pid === undefined) {
+        throw new ManagedProcessStartError(`Managed process did not start and reported no pid: ${executable}${spawnError ? ` (${spawnError})` : ""}`);
+    }
+    const pid = child.pid;
+    const stdoutStream = createWriteStream(stdoutPath, { flags: "w" });
+    const stderrStream = createWriteStream(stderrPath, { flags: "w" });
+    // Log-file write errors must not crash the host process; they are recorded and
+    // surfaced through the exit result instead.
+    stdoutStream.on("error", (error) => {
+        spawnError = spawnError ?? `stdout log write failed: ${messageOf(error)}`;
+    });
+    stderrStream.on("error", (error) => {
+        spawnError = spawnError ?? `stderr log write failed: ${messageOf(error)}`;
+    });
+    const stdoutTail = createBoundedTail();
+    const stderrTail = createBoundedTail();
+    attachStream(child.stdout, stdoutStream, stdoutTail);
+    attachStream(child.stderr, stderrStream, stderrTail);
+    child.on("close", (code, signal) => {
+        exited = true;
+        exitResult = {
+            exitCode: code,
+            signal: signal ?? null,
+            ...(spawnError ? { error: spawnError } : {})
+        };
+        stdoutStream.end();
+        stderrStream.end();
+        const finalResult = exitResult;
+        for (const waiter of exitWaiters.splice(0)) {
+            waiter(finalResult);
+        }
+    });
+    function waitForExit() {
+        if (exited && exitResult) {
+            return Promise.resolve(exitResult);
+        }
+        return new Promise((resolve) => {
+            exitWaiters.push(resolve);
+        });
+    }
+    async function waitForExitWithin(timeoutMs) {
+        if (exited && exitResult) {
+            return exitResult;
+        }
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(undefined), timeoutMs);
+        });
+        try {
+            return await Promise.race([waitForExit(), timedOut]);
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    let stopInFlight;
+    async function stop(options) {
+        if (exited && exitResult) {
+            return { status: "already-exited", exit: exitResult };
+        }
+        if (stopInFlight) {
+            return stopInFlight;
+        }
+        const gracePeriodMs = options?.gracePeriodMs ?? MANAGED_PROCESS_DEFAULT_GRACE_PERIOD_MS;
+        const pending = (async () => {
+            requestProcessTermination(pid);
+            const gracefulExit = await waitForExitWithin(Math.max(0, gracePeriodMs));
+            if (gracefulExit) {
+                return { status: "stopped", exit: gracefulExit };
+            }
+            // Escalation only: SIGKILL here is safe because the graceful SIGTERM grace
+            // period has already elapsed. On Windows this is taskkill /T /F.
+            forceTerminateProcess(pid, { posixSignal: "SIGKILL" });
+            return { status: "forced", exit: await waitForExit() };
+        })();
+        stopInFlight = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            stopInFlight = undefined;
+        }
+    }
+    async function waitForReadiness(probe) {
+        const startedAt = Date.now();
+        const validation = validateReadinessProbe(probe);
+        if (!validation.ok) {
+            return {
+                status: "probe-failed",
+                url: typeof probe?.url === "string" ? probe.url : "",
+                attempts: 0,
+                elapsedMs: Date.now() - startedAt,
+                error: validation.error
+            };
+        }
+        const { url, acceptedStatusMin, acceptedStatusMax, intervalMs } = validation;
+        let attempts = 0;
+        let lastStatusCode;
+        let lastError;
+        for (;;) {
+            if (exited) {
+                return {
+                    status: "process-exited",
+                    url: probe.url,
+                    attempts,
+                    elapsedMs: Date.now() - startedAt,
+                    ...(lastStatusCode !== undefined ? { lastStatusCode } : {}),
+                    error: `Managed process "${id}" exited before readiness was reached.`
+                };
+            }
+            const remainingMs = probe.timeoutMs - (Date.now() - startedAt);
+            if (remainingMs <= 0) {
+                return {
+                    status: "timeout",
+                    url: probe.url,
+                    attempts,
+                    elapsedMs: Date.now() - startedAt,
+                    ...(lastStatusCode !== undefined ? { lastStatusCode } : {}),
+                    ...(lastError ? { error: lastError } : {})
+                };
+            }
+            attempts += 1;
+            const requestTimeoutMs = Math.max(1, Math.min(probe.requestTimeoutMs ?? MANAGED_PROCESS_DEFAULT_REQUEST_TIMEOUT_MS, remainingMs));
+            try {
+                const response = await fetch(url, {
+                    // "manual" keeps a 3xx observable as a 3xx: a redirect is a legitimate
+                    // sign of a live server and is accepted by the default 200..399 range.
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(requestTimeoutMs)
+                });
+                lastStatusCode = response.status;
+                await response.body?.cancel().catch(() => undefined);
+                if (response.status >= acceptedStatusMin && response.status <= acceptedStatusMax) {
+                    return {
+                        status: "ready",
+                        url: probe.url,
+                        attempts,
+                        elapsedMs: Date.now() - startedAt,
+                        lastStatusCode: response.status
+                    };
+                }
+                lastError = `Readiness probe received status ${response.status}.`;
+            }
+            catch (error) {
+                // Connection refused / socket reset / per-attempt abort are all expected
+                // while a local server is still starting, so they are retried.
+                lastError = messageOf(error);
+            }
+            const remainingAfterAttempt = probe.timeoutMs - (Date.now() - startedAt);
+            if (remainingAfterAttempt <= 0) {
+                continue;
+            }
+            await delay(Math.min(intervalMs, remainingAfterAttempt));
+        }
+    }
+    return Object.freeze({
+        id,
+        pid,
+        executable: invocation.executable,
+        args: Object.freeze([...invocation.args]),
+        cwd,
+        stdoutPath,
+        stderrPath,
+        resolvedCommand: invocation.resolvedCommand,
+        waitForReadiness,
+        waitForExit,
+        stop,
+        readRecentOutput: () => ({
+            stdout: stdoutTail.read(),
+            stderr: stderrTail.read(),
+            truncated: stdoutTail.truncated() || stderrTail.truncated()
+        })
+    });
+}
+/**
+ * Readiness is a bounded local-server liveness check, not a general network
+ * fetch primitive: only http/https to a loopback host is permitted.
+ */
+function validateReadinessProbe(probe) {
+    if (!probe || probe.kind !== "http") {
+        return { ok: false, error: 'Readiness probe kind must be "http".' };
+    }
+    if (typeof probe.url !== "string" || probe.url.trim().length === 0) {
+        return { ok: false, error: "Readiness probe url must be a non-empty string." };
+    }
+    if (!Number.isFinite(probe.timeoutMs) || probe.timeoutMs <= 0) {
+        return { ok: false, error: "Readiness probe timeoutMs must be a positive number." };
+    }
+    let parsed;
+    try {
+        parsed = new URL(probe.url);
+    }
+    catch {
+        return { ok: false, error: `Readiness probe url is not a valid URL: ${probe.url}` };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return {
+            ok: false,
+            error: `Readiness probe protocol must be http: or https:, received ${parsed.protocol}`
+        };
+    }
+    // URL parsing renders an IPv6 host as "[::1]"; compare on the unbracketed form.
+    const hostname = parsed.hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+    if (!ALLOWED_READINESS_HOSTS.has(hostname)) {
+        return {
+            ok: false,
+            error: `Readiness probe host must be loopback (localhost, 127.0.0.1, ::1), received ${parsed.hostname}`
+        };
+    }
+    const acceptedStatusMin = probe.acceptedStatusMin ?? MANAGED_PROCESS_DEFAULT_ACCEPTED_STATUS_MIN;
+    const acceptedStatusMax = probe.acceptedStatusMax ?? MANAGED_PROCESS_DEFAULT_ACCEPTED_STATUS_MAX;
+    if (!Number.isFinite(acceptedStatusMin) || !Number.isFinite(acceptedStatusMax)) {
+        return { ok: false, error: "Readiness probe accepted status range must be numeric." };
+    }
+    if (acceptedStatusMin > acceptedStatusMax) {
+        return {
+            ok: false,
+            error: `Readiness probe accepted status range is inverted: ${acceptedStatusMin}..${acceptedStatusMax}`
+        };
+    }
+    const intervalMs = probe.intervalMs ?? MANAGED_PROCESS_DEFAULT_READINESS_INTERVAL_MS;
+    if (!Number.isFinite(intervalMs) || intervalMs < 0) {
+        return { ok: false, error: "Readiness probe intervalMs must be a non-negative number." };
+    }
+    return { ok: true, url: parsed.href, acceptedStatusMin, acceptedStatusMax, intervalMs };
+}
+function validateProcessId(id) {
+    const trimmed = typeof id === "string" ? id.trim() : "";
+    if (trimmed.length === 0) {
+        throw new ManagedProcessStartError("Managed process id must be a non-empty string.");
+    }
+    // The id becomes a log file name, so it must stay a single path segment.
+    if (trimmed !== path.basename(trimmed) || trimmed === "." || trimmed === "..") {
+        throw new ManagedProcessStartError(`Managed process id must be a single path segment without separators: ${id}`);
+    }
+    return trimmed;
+}
+function createBoundedTail(limitBytes = MANAGED_PROCESS_CAPTURE_LIMIT_BYTES) {
+    let buffer = Buffer.alloc(0);
+    let dropped = false;
+    return {
+        push(chunk) {
+            buffer = Buffer.concat([buffer, chunk]);
+            if (buffer.length > limitBytes) {
+                buffer = buffer.subarray(buffer.length - limitBytes);
+                dropped = true;
+            }
+        },
+        read() {
+            return buffer.toString("utf8");
+        },
+        truncated() {
+            return dropped;
+        }
+    };
+}
+function attachStream(source, sink, tail) {
+    source.on("data", (chunk) => {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+        tail.push(buffer);
+        // Written as it arrives: a managed process may live for minutes and its log
+        // must be readable while it runs.
+        sink.write(buffer);
+    });
+    source.on("error", () => undefined);
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}