@devfn/processes 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @devfn/processes
+
+Native process groups, durable logs, HTTP/TCP/command/log readiness, PID-birth ownership checks, and graceful termination. It is deliberately browser- and artifact-model-neutral so ProbeFn can adopt it later without depending on DevFn orchestration.

package/dist/adapters.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessSpec } from "@devfn/config";
+export declare function resolveAdapterCommand(spec: ProcessSpec): string[];
+export declare function createProcessEnvironment(spec: ProcessSpec, generated?: Record<string, string>, source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/adapters.js

@@ -0,0 +1,31 @@
+export function resolveAdapterCommand(spec) {
+    const extra = spec.command ?? [];
+    switch (spec.adapter) {
+        case "command": return [...extra];
+        case "npm": return ["npm", "run", spec.script, ...(extra.length ? ["--", ...extra] : [])];
+        case "pnpm": return ["corepack", "pnpm", "run", spec.script, ...extra];
+        case "turbo": return ["npm", "exec", "--offline", "--", "turbo", ...extra];
+        case "wrangler": return ["npm", "exec", "--offline", "--", "wrangler", ...(extra.length ? extra : ["dev"])];
+        case "xcode": return ["xcodebuild", ...extra];
+        case "extfn": return ["npm", "exec", "--offline", "--", "extfn", ...(extra.length ? extra : ["dev"])];
+        default: {
+            const unsupported = spec.adapter;
+            throw new Error(`Unsupported process adapter: ${String(unsupported)}`);
+        }
+    }
+}
+const BASE_ENV = ["PATH", "SHELL", "HOME", "USER", "LOGNAME", "TMPDIR", "TMP", "TEMP", "SystemRoot", "ComSpec", "PATHEXT"];
+export function createProcessEnvironment(spec, generated = {}, source = process.env) {
+    const result = {};
+    for (const key of [...BASE_ENV, ...(spec.envAllowlist ?? [])])
+        if (source[key] !== undefined)
+            result[key] = source[key];
+    Object.assign(result, spec.env ?? {}, generated);
+    if (spec.exposure !== "public") {
+        result.HOST = "127.0.0.1";
+        result.DEVFN_HOST = "127.0.0.1";
+    }
+    if (spec.adapter === "pnpm")
+        result.COREPACK_ENABLE_NETWORK = "0";
+    return result;
+}

package/dist/identity.d.ts

@@ -0,0 +1 @@
+export { matchesProcessIdentity, processBirthSignature, processExists } from "@devfn/config";

package/dist/identity.js

@@ -0,0 +1 @@
+export { matchesProcessIdentity, processBirthSignature, processExists } from "@devfn/config";

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createProcessEnvironment, resolveAdapterCommand } from "./adapters.js";
+export { matchesProcessIdentity, processBirthSignature, processExists } from "./identity.js";
+export { checkReadinessNow, waitForReadiness, type ReadinessInput } from "./readiness.js";
+export { createStreamingRedactor, type StreamingRedactor } from "./redaction.js";
+export { ProcessSupervisor } from "./supervisor.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createProcessEnvironment, resolveAdapterCommand } from "./adapters.js";
+export { matchesProcessIdentity, processBirthSignature, processExists } from "./identity.js";
+export { checkReadinessNow, waitForReadiness } from "./readiness.js";
+export { createStreamingRedactor } from "./redaction.js";
+export { ProcessSupervisor } from "./supervisor.js";
+export * from "./types.js";

package/dist/readiness.d.ts

@@ -0,0 +1,14 @@
+import type { HealthCheck } from "@devfn/config";
+export type ReadinessInput = {
+    health?: HealthCheck;
+    ports: Record<string, number>;
+    logPath: string;
+    logOffset?: number;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    isAlive: () => boolean | Promise<boolean>;
+    readLog?: () => Promise<string>;
+    previouslyReady?: boolean;
+};
+export declare function checkReadinessNow(input: ReadinessInput): Promise<boolean>;
+export declare function waitForReadiness(input: ReadinessInput): Promise<void>;

package/dist/readiness.js

@@ -0,0 +1,216 @@
+import { execFile } from "node:child_process";
+import { open } from "node:fs/promises";
+import net from "node:net";
+import { promisify } from "node:util";
+import { ProcessError } from "./types.js";
+const execFileAsync = promisify(execFile);
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const LOG_CHUNK_BYTES = 256 * 1024;
+const LOG_WINDOW_BYTES = 1024 * 1024;
+async function withinDeadline(promise, remainingMs) {
+    if (remainingMs <= 0)
+        throw new Error("Readiness deadline elapsed.");
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error("Readiness operation exceeded the remaining deadline.")), remainingMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function tcpReady(port, timeoutMs = 500) {
+    return await new Promise((resolve) => {
+        const socket = net.createConnection({ host: "127.0.0.1", port });
+        socket.setTimeout(timeoutMs);
+        const done = (value) => { socket.destroy(); resolve(value); };
+        socket.once("connect", () => done(true));
+        socket.once("timeout", () => done(false));
+        socket.once("error", () => done(false));
+    });
+}
+async function readNewLog(logPath, offset) {
+    const handle = await open(logPath, "r").catch(() => undefined);
+    if (!handle)
+        return { bytes: Buffer.alloc(0), nextOffset: offset, reset: false };
+    try {
+        const size = (await handle.stat()).size;
+        if (size <= offset)
+            return { bytes: Buffer.alloc(0), nextOffset: Math.min(size, offset), reset: size < offset };
+        const length = Math.min(size - offset, LOG_CHUNK_BYTES);
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, offset);
+        return { bytes: buffer.subarray(0, bytesRead), nextOffset: offset + bytesRead, reset: false };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readLogWindow(logPath) {
+    const handle = await open(logPath, "r").catch(() => undefined);
+    if (!handle)
+        return "";
+    try {
+        const size = (await handle.stat()).size;
+        const length = Math.min(size, LOG_WINDOW_BYTES);
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, size - length);
+        return new TextDecoder().decode(buffer.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+function resolveHttpUrl(health, input) {
+    const port = health.port ? input.ports[health.port] : undefined;
+    let url = health.url ?? `http://127.0.0.1:${port}${health.path ?? "/"}`;
+    if (health.url && health.path) {
+        const parsed = new URL(health.url);
+        const baseSearch = parsed.search;
+        const baseHash = parsed.hash;
+        parsed.search = "";
+        parsed.hash = "";
+        parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/`;
+        const appended = new URL(health.path.replace(/^\/+/, ""), parsed);
+        if (appended.origin !== parsed.origin)
+            throw new Error("HTTP readiness path must stay on the configured URL origin.");
+        if (!appended.search)
+            appended.search = baseSearch;
+        if (!appended.hash)
+            appended.hash = baseHash;
+        url = appended.toString();
+    }
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        throw new Error("HTTP readiness URL must use http or https.");
+    return parsed.toString();
+}
+async function httpReady(health, input, timeoutMs) {
+    const url = resolveHttpUrl(health, input);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return (await fetch(url, { signal: controller.signal })).status === (health.expectedStatus ?? 200);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function checkReadinessNow(input) {
+    const defaultTimeoutMs = input.health?.type === "tcp" ? 500 : input.health?.type === "command" ? 2000 : 1000;
+    const timeoutMs = Math.max(1, input.health?.timeoutMs ?? defaultTimeoutMs);
+    const deadline = Date.now() + timeoutMs;
+    try {
+        if (!await withinDeadline(Promise.resolve(input.isAlive()), deadline - Date.now()))
+            return false;
+        if (!input.health)
+            return true;
+        if ((input.health.type === "tcp" || input.health.type === "http") && input.health.port && input.ports[input.health.port] === undefined)
+            return false;
+        let ready;
+        if (input.health.type === "log") {
+            if (input.previouslyReady)
+                ready = true;
+            else {
+                const output = input.readLog
+                    ? await withinDeadline(input.readLog(), deadline - Date.now())
+                    : await withinDeadline(readLogWindow(input.logPath), deadline - Date.now());
+                ready = new RegExp(input.health.pattern, "i").test(output.slice(-LOG_WINDOW_BYTES));
+            }
+        }
+        else
+            ready = await withinDeadline(checkReadiness(input.health, input, deadline - Date.now()), deadline - Date.now());
+        if (!ready || Date.now() >= deadline)
+            return false;
+        return await withinDeadline(Promise.resolve(input.isAlive()), deadline - Date.now());
+    }
+    catch {
+        return false;
+    }
+}
+async function checkReadiness(health, input, remainingMs) {
+    switch (health.type) {
+        case "tcp": return await tcpReady(input.ports[health.port], Math.max(1, Math.min(health.timeoutMs ?? 500, remainingMs)));
+        case "http": return await httpReady(health, input, Math.max(1, Math.min(health.timeoutMs ?? 1000, remainingMs)));
+        case "command": {
+            const [file, ...args] = health.command;
+            await execFileAsync(file, args, { cwd: input.cwd, env: input.environment, timeout: Math.max(1, Math.min(health.timeoutMs ?? 2000, remainingMs)) });
+            return true;
+        }
+    }
+}
+export async function waitForReadiness(input) {
+    if (!input.health) {
+        await delay(500);
+        if (!await withinDeadline(Promise.resolve(input.isAlive()), 1000))
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", "Process exited before startup completed.");
+        return;
+    }
+    const timeoutMs = input.health.timeoutMs ?? 120_000;
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    let logPattern;
+    let logOffset = input.logOffset ?? 0;
+    let logWindow = "";
+    let logDecoder = new TextDecoder();
+    if (input.health.type === "log") {
+        try {
+            logPattern = new RegExp(input.health.pattern, "i");
+        }
+        catch (error) {
+            throw new ProcessError("DEVFN_PROCESS_NOT_READY", `Invalid readiness pattern ${input.health.pattern}.`, { cause: String(error) });
+        }
+    }
+    if ((input.health.type === "tcp" || input.health.type === "http") && input.health.port && input.ports[input.health.port] === undefined) {
+        throw new ProcessError("DEVFN_PROCESS_NOT_READY", `Readiness check references unallocated port ${input.health.port}.`);
+    }
+    if (input.health.type === "http") {
+        try {
+            resolveHttpUrl(input.health, input);
+        }
+        catch (error) {
+            throw new ProcessError("DEVFN_PROCESS_NOT_READY", "Invalid HTTP readiness configuration.", { cause: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    while (Date.now() < deadline) {
+        try {
+            if (!await withinDeadline(Promise.resolve(input.isAlive()), deadline - Date.now()))
+                throw new ProcessError("DEVFN_PROCESS_START_FAILED", "Process exited while waiting for readiness.");
+        }
+        catch (error) {
+            if (error instanceof ProcessError)
+                throw error;
+            lastError = error;
+            break;
+        }
+        if (Date.now() >= deadline)
+            break;
+        try {
+            if (input.health.type === "log") {
+                if (input.readLog)
+                    logWindow = (await withinDeadline(input.readLog(), deadline - Date.now())).slice(-LOG_WINDOW_BYTES);
+                else {
+                    const chunk = await readNewLog(input.logPath, logOffset);
+                    logOffset = chunk.nextOffset;
+                    if (chunk.reset) {
+                        logDecoder = new TextDecoder();
+                        logWindow = "";
+                    }
+                    logWindow = `${logWindow}${logDecoder.decode(chunk.bytes, { stream: true })}`.slice(-LOG_WINDOW_BYTES);
+                }
+                if (logPattern?.test(logWindow) && Date.now() < deadline)
+                    return;
+            }
+            else if (await checkReadiness(input.health, input, Math.max(1, deadline - Date.now())) && Date.now() < deadline)
+                return;
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await delay(Math.min(100, Math.max(1, deadline - Date.now())));
+    }
+    throw new ProcessError("DEVFN_PROCESS_NOT_READY", `Readiness check timed out after ${timeoutMs} ms.`, { cause: lastError instanceof Error ? lastError.message : String(lastError ?? "not ready") });
+}

package/dist/redaction.d.ts

@@ -0,0 +1,5 @@
+export interface StreamingRedactor {
+    push(chunk: string): void;
+    end(): void;
+}
+export declare function createStreamingRedactor(values: readonly string[], write: (value: string) => void): StreamingRedactor;

package/dist/redaction.js

@@ -0,0 +1,22 @@
+export function createStreamingRedactor(values, write) {
+    const secrets = [...new Set(values)].filter(Boolean).sort((a, b) => b.length - a.length);
+    let buffer = "";
+    const longest = Math.max(1, ...secrets.map((secret) => secret.length));
+    const flush = (ending) => {
+        while (buffer.length >= (ending ? 1 : longest)) {
+            const match = secrets.find((secret) => buffer.startsWith(secret));
+            if (match) {
+                write("[REDACTED]");
+                buffer = buffer.slice(match.length);
+            }
+            else {
+                write(buffer[0]);
+                buffer = buffer.slice(1);
+            }
+        }
+    };
+    return {
+        push(chunk) { buffer += chunk; flush(false); },
+        end() { flush(true); },
+    };
+}

package/dist/supervisor.d.ts

@@ -0,0 +1,10 @@
+import { type ManagedProcess, type StartProcessInput } from "./types.js";
+export declare function prepareProcessLog(logPath: string, resetSensitiveHistory: boolean): Promise<{
+    logFd: number;
+    logOffset: number;
+}>;
+export declare class ProcessSupervisor {
+    start(input: StartProcessInput): Promise<ManagedProcess>;
+    stop(managed: ManagedProcess, timeoutMs?: number): Promise<void>;
+    status(managed: ManagedProcess): Promise<"running" | "stopped" | "identity-mismatch">;
+}

package/dist/supervisor.js

@@ -0,0 +1,149 @@
+import { spawn } from "node:child_process";
+import { closeSync, constants, fchmodSync, mkdirSync, openSync } from "node:fs";
+import { lstat, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveContainedPath } from "@devfn/config";
+import { createProcessEnvironment, resolveAdapterCommand } from "./adapters.js";
+import { matchesProcessIdentity, processBirthSignature, processExists } from "./identity.js";
+import { waitForReadiness } from "./readiness.js";
+import { ProcessError } from "./types.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function terminateProcess(pid, force = false) {
+    if (process.platform !== "win32") {
+        process.kill(-pid, force ? "SIGKILL" : "SIGTERM");
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const child = spawn("taskkill", ["/pid", String(pid), "/T", ...(force ? ["/F"] : [])], { stdio: "ignore", windowsHide: true });
+        child.once("error", reject);
+        child.once("exit", (code) => code === 0 || !processExists(pid) ? resolve() : reject(new Error(`taskkill exited with ${code}`)));
+    });
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && processExists(pid))
+        await delay(50);
+    return !processExists(pid);
+}
+export async function prepareProcessLog(logPath, resetSensitiveHistory) {
+    const existing = await lstat(logPath).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (existing?.isSymbolicLink())
+        throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Refusing symlinked process log ${logPath}.`);
+    const logOffset = resetSensitiveHistory ? 0 : existing?.size ?? 0;
+    const flags = constants.O_WRONLY | constants.O_CREAT | (resetSensitiveHistory ? constants.O_TRUNC : constants.O_APPEND) | (constants.O_NOFOLLOW ?? 0);
+    let logFd;
+    try {
+        logFd = openSync(logPath, flags, 0o600);
+        fchmodSync(logFd, 0o600);
+        return { logFd, logOffset };
+    }
+    catch (error) {
+        if (logFd !== undefined)
+            closeSync(logFd);
+        if (error instanceof ProcessError)
+            throw error;
+        throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Unable to open process log ${logPath} safely.`, { cause: error instanceof Error ? error.message : String(error) });
+    }
+}
+export class ProcessSupervisor {
+    async start(input) {
+        const command = resolveAdapterCommand(input.spec);
+        if (command.length === 0)
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Process ${input.name} has no command.`);
+        const cwd = await resolveContainedPath(input.root, input.spec.cwd ?? ".", `processes.${input.name}.cwd`).catch((error) => {
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Process cwd escapes repository: ${input.spec.cwd ?? "."}`, { cause: error instanceof Error ? error.message : String(error) });
+        });
+        const logsDir = path.join(input.runtimeDir, "logs");
+        await mkdir(logsDir, { recursive: true, mode: 0o700 });
+        if (!/^[A-Za-z0-9_.-]+$/.test(input.name) || input.name !== input.name.trim())
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Invalid process name ${input.name}.`);
+        const logPath = path.join(logsDir, `${input.name}.log`);
+        mkdirSync(path.dirname(logPath), { recursive: true });
+        const { logFd, logOffset } = await prepareProcessLog(logPath, Boolean(input.spec.secretEnv?.length));
+        const environment = createProcessEnvironment(input.spec, input.environment);
+        const wrapperPath = fileURLToPath(new URL("./wrapper.js", import.meta.url));
+        const child = spawn(process.execPath, [wrapperPath], {
+            cwd,
+            env: { ...environment, DEVFN_WRAPPED_COMMAND: JSON.stringify(command), DEVFN_REDACT_KEYS: JSON.stringify(input.spec.secretEnv ?? []) },
+            detached: process.platform !== "win32",
+            windowsHide: true,
+            stdio: ["ignore", logFd, logFd],
+        });
+        let exited = false;
+        child.once("exit", () => { exited = true; });
+        closeSync(logFd);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(resolve, 50);
+            child.once("error", (error) => { clearTimeout(timer); reject(error); });
+            child.once("spawn", () => { clearTimeout(timer); resolve(); });
+        }).catch((error) => { throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Unable to start ${input.name}.`, { cause: error instanceof Error ? error.message : String(error) }); });
+        if (!child.pid)
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Process ${input.name} did not receive a PID.`);
+        child.unref();
+        let birthSignature;
+        for (let attempt = 0; attempt < 10 && !birthSignature; attempt += 1) {
+            birthSignature = await processBirthSignature(child.pid);
+            if (!birthSignature)
+                await delay(20);
+        }
+        if (!birthSignature) {
+            try {
+                if (process.platform !== "win32")
+                    process.kill(-child.pid, "SIGTERM");
+                else
+                    child.kill();
+            }
+            catch { /* process may already have exited */ }
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Could not establish a birth identity for ${input.name}; refusing unmanaged supervision.`);
+        }
+        const managed = {
+            name: input.name,
+            pid: child.pid,
+            birthSignature,
+            command,
+            cwd,
+            logPath,
+            startedAt: new Date().toISOString(),
+            ...(input.spec.shutdownTimeoutMs === undefined ? {} : { shutdownTimeoutMs: input.spec.shutdownTimeoutMs }),
+        };
+        try {
+            await input.onStarted?.(managed);
+            await waitForReadiness({ health: input.spec.health, ports: input.ports ?? {}, logPath, logOffset, cwd, environment, isAlive: () => !exited && processExists(managed.pid) });
+            managed.readyAt = new Date().toISOString();
+            return managed;
+        }
+        catch (error) {
+            await this.stop(managed, input.spec.shutdownTimeoutMs).catch(() => undefined);
+            throw error;
+        }
+    }
+    async stop(managed, timeoutMs = managed.shutdownTimeoutMs ?? 10_000) {
+        if (!processExists(managed.pid))
+            return;
+        if (!await matchesProcessIdentity(managed.pid, managed.birthSignature)) {
+            throw new ProcessError("DEVFN_PROCESS_OWNERSHIP_MISMATCH", `PID ${managed.pid} no longer matches the DevFn process identity.`, { name: managed.name, pid: managed.pid });
+        }
+        try {
+            await terminateProcess(managed.pid);
+            if (!await waitForProcessExit(managed.pid, timeoutMs)) {
+                await terminateProcess(managed.pid, true);
+                if (!await waitForProcessExit(managed.pid, 5_000))
+                    throw new ProcessError("DEVFN_PROCESS_STOP_FAILED", `Process ${managed.name} did not exit after forced termination.`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw new ProcessError("DEVFN_PROCESS_STOP_FAILED", `Unable to stop ${managed.name}.`, { cause: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    async status(managed) {
+        if (!processExists(managed.pid))
+            return "stopped";
+        return await matchesProcessIdentity(managed.pid, managed.birthSignature) ? "running" : "identity-mismatch";
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+import type { ProcessSpec } from "@devfn/config";
+export interface ManagedProcess {
+    name: string;
+    pid: number;
+    birthSignature?: string;
+    command: string[];
+    cwd: string;
+    logPath: string;
+    startedAt: string;
+    readyAt?: string;
+    shutdownTimeoutMs?: number;
+}
+export interface StartProcessInput {
+    name: string;
+    spec: ProcessSpec;
+    root: string;
+    runtimeDir: string;
+    environment?: Record<string, string>;
+    ports?: Record<string, number>;
+    onStarted?: (process: ManagedProcess) => Promise<void>;
+}
+export declare class ProcessError extends Error {
+    readonly code: "DEVFN_PROCESS_START_FAILED" | "DEVFN_PROCESS_NOT_READY" | "DEVFN_PROCESS_OWNERSHIP_MISMATCH" | "DEVFN_PROCESS_STOP_FAILED";
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: "DEVFN_PROCESS_START_FAILED" | "DEVFN_PROCESS_NOT_READY" | "DEVFN_PROCESS_OWNERSHIP_MISMATCH" | "DEVFN_PROCESS_STOP_FAILED", message: string, details?: Record<string, unknown> | undefined);
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+export class ProcessError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "ProcessError";
+    }
+}

package/dist/wrapper.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wrapper.js

@@ -0,0 +1,38 @@
+import { spawn } from "node:child_process";
+import { createStreamingRedactor } from "./redaction.js";
+function requiredJson(name) {
+    const raw = process.env[name];
+    if (!raw)
+        throw new Error(`Missing ${name}.`);
+    return JSON.parse(raw);
+}
+const command = requiredJson("DEVFN_WRAPPED_COMMAND");
+const keys = requiredJson("DEVFN_REDACT_KEYS");
+if (!Array.isArray(command) || command.length === 0 || !command.every((item) => typeof item === "string"))
+    throw new Error("Invalid wrapped command.");
+if (!Array.isArray(keys) || !keys.every((item) => typeof item === "string"))
+    throw new Error("Invalid redaction keys.");
+const environment = { ...process.env };
+delete environment.DEVFN_WRAPPED_COMMAND;
+delete environment.DEVFN_REDACT_KEYS;
+const secrets = [...new Set(keys.map((key) => environment[key]).filter((value) => typeof value === "string" && value.length > 0))].sort((a, b) => b.length - a.length);
+const child = spawn(command[0], command.slice(1), { cwd: process.cwd(), env: environment, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+function pipeRedacted(stream, destination) {
+    if (secrets.length === 0) {
+        stream.pipe(destination, { end: false });
+        return;
+    }
+    const redactor = createStreamingRedactor(secrets, (value) => destination.write(value));
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => redactor.push(chunk));
+    stream.on("end", () => redactor.end());
+}
+pipeRedacted(child.stdout, process.stdout);
+pipeRedacted(child.stderr, process.stderr);
+child.once("error", (error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
+child.once("close", (code, signal) => {
+    if (signal)
+        process.kill(process.pid, signal);
+    else
+        process.exitCode = code ?? 1;
+});

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@devfn/processes",
+  "version": "0.1.0",
+  "description": "Browser-neutral native process supervision and readiness for DevFn and ProbeFn consumers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md"],
+  "scripts": { "build": "tsc -p tsconfig.json", "typecheck": "tsc --noEmit -p tsconfig.json", "test": "vitest run", "lint": "echo 'lint not configured'", "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"" },
+  "dependencies": { "@devfn/config": "0.1.0" },
+  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0", "vitest": "^3.2.4" },
+  "engines": { "node": ">=22" },
+  "license": "MIT"
+}