@launchfile/macos-dev 0.1.4 → 0.3.0

package/dist/bootstrap.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Bootstrap command execution for the macOS Dev provider.
+ *
+ * Implements the `commands.bootstrap` lifecycle stage introduced by D-34:
+ * user-invoked, runs after `start` against the running component, captures
+ * stdout via regex patterns, re-runnable, and reports failures rather than
+ * deploy-failing. Spec: /spec/SPEC.md § Bootstrap stage.
+ *
+ * The command is split into argv via whitespace and run through spawn()
+ * with shell:false to avoid shell-injection exposure. This means shell
+ * metacharacters (pipes, redirects, &&, quoted args with spaces) are not
+ * supported — apps that need shell features should wrap them in an
+ * image-level script and invoke that script.
+ */
+import { type CaptureEntry } from "@launchfile/sdk";
+/**
+ * Result of running one bootstrap command. Captures may be empty even on
+ * success (the command may not produce matching output), and may be
+ * partially populated even on failure (some patterns matched before
+ * the command errored out).
+ */
+export interface BootstrapResult {
+    component: string;
+    command: string;
+    ok: boolean;
+    exitCode: number;
+    captures: Record<string, string>;
+    /** Per-capture metadata (description, sensitive) for display. */
+    captureMeta: Record<string, CaptureEntry>;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Apply a set of capture patterns to a command's stdout. If a pattern has
+ * a capture group, the first group is used; otherwise the full match is
+ * used. Invalid regexes are skipped (schema validation catches them earlier).
+ *
+ * Exported for unit testing.
+ */
+export declare function extractCaptures(stdout: string, captures: Record<string, CaptureEntry>): Record<string, string>;
+/** Parse a simple duration string like "5m", "30s", "1h" into milliseconds. Exported for unit testing. */
+export declare function parseDuration(s: string): number;
+/**
+ * Public entry point for `launch bootstrap`. Loads the Launchfile, rebuilds
+ * the resolver context from persisted state (so $app.url resolves to the
+ * same value the running component sees), resolves $-expressions in each
+ * bootstrap command, runs them in declaration order, and returns structured
+ * results.
+ *
+ * Does not fail the process on command error — the caller (CLI) decides
+ * how to display failures. This matches the "reported, not deploy-failing"
+ * semantics in SPEC.md § Bootstrap stage.
+ */
+export declare function launchBootstrap(opts?: {
+    component?: string;
+    projectDir?: string;
+}): Promise<BootstrapResult[]>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.js

@@ -0,0 +1,224 @@
+/**
+ * Bootstrap command execution for the macOS Dev provider.
+ *
+ * Implements the `commands.bootstrap` lifecycle stage introduced by D-34:
+ * user-invoked, runs after `start` against the running component, captures
+ * stdout via regex patterns, re-runnable, and reports failures rather than
+ * deploy-failing. Spec: /spec/SPEC.md § Bootstrap stage.
+ *
+ * The command is split into argv via whitespace and run through spawn()
+ * with shell:false to avoid shell-injection exposure. This means shell
+ * metacharacters (pipes, redirects, &&, quoted args with spaces) are not
+ * supported — apps that need shell features should wrap them in an
+ * image-level script and invoke that script.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { readLaunch, resolveExpression, } from "@launchfile/sdk";
+import { loadState } from "./state.js";
+import { buildResolverContext, computeAppProperties, resolveComponentEnv, resolveGenerators, } from "./env-writer.js";
+import { getProvisioner } from "./resources/index.js";
+/**
+ * Strip ANSI escape sequences from captured stdout before regex matching.
+ * CLI tools that detect a TTY will emit color codes that would otherwise
+ * break simple patterns like `https?://\S+`.
+ */
+function stripAnsi(s) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI match
+    return s.replace(/\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07/g, "");
+}
+/**
+ * Apply a set of capture patterns to a command's stdout. If a pattern has
+ * a capture group, the first group is used; otherwise the full match is
+ * used. Invalid regexes are skipped (schema validation catches them earlier).
+ *
+ * Exported for unit testing.
+ */
+export function extractCaptures(stdout, captures) {
+    const result = {};
+    const clean = stripAnsi(stdout);
+    for (const [name, def] of Object.entries(captures)) {
+        try {
+            const match = clean.match(new RegExp(def.pattern));
+            if (match) {
+                result[name] = (match[1] ?? match[0] ?? "").trim();
+            }
+        }
+        catch {
+            // Invalid regex — skip. CaptureEntrySchema validation catches this.
+        }
+    }
+    return result;
+}
+/** Parse a simple duration string like "5m", "30s", "1h" into milliseconds. Exported for unit testing. */
+export function parseDuration(s) {
+    const match = /^(\d+)\s*(ms|s|m|h)$/.exec(s.trim());
+    if (!match)
+        return 120_000;
+    const n = Number.parseInt(match[1], 10);
+    switch (match[2]) {
+        case "ms": return n;
+        case "s": return n * 1000;
+        case "m": return n * 60 * 1000;
+        case "h": return n * 60 * 60 * 1000;
+        default: return 120_000;
+    }
+}
+/**
+ * Run one command using argv-split (no-shell) execution. Returns the
+ * structured result; does not throw on command failure.
+ */
+async function runOnce(command, opts) {
+    const parts = command.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0) {
+        return { exitCode: 1, stdout: "", stderr: "empty command" };
+    }
+    const [file, ...args] = parts;
+    return new Promise((resolveP) => {
+        const child = spawn(file, args, {
+            cwd: opts.cwd,
+            env: { ...process.env, ...opts.env },
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                child.kill("SIGTERM");
+                resolveP({
+                    exitCode: 124,
+                    stdout,
+                    stderr: stderr + `\n(killed after ${opts.timeoutMs}ms timeout)`,
+                });
+            }
+        }, opts.timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolveP({ exitCode: 1, stdout, stderr: `${stderr}\n${err.message}` });
+            }
+        });
+        child.on("close", (code) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolveP({ exitCode: code ?? 1, stdout, stderr });
+            }
+        });
+    });
+}
+/**
+ * Public entry point for `launch bootstrap`. Loads the Launchfile, rebuilds
+ * the resolver context from persisted state (so $app.url resolves to the
+ * same value the running component sees), resolves $-expressions in each
+ * bootstrap command, runs them in declaration order, and returns structured
+ * results.
+ *
+ * Does not fail the process on command error — the caller (CLI) decides
+ * how to display failures. This matches the "reported, not deploy-failing"
+ * semantics in SPEC.md § Bootstrap stage.
+ */
+export async function launchBootstrap(opts = {}) {
+    const projectDir = opts.projectDir ?? process.cwd();
+    const launchfileContent = await readFile(join(projectDir, "Launchfile"), "utf8");
+    const launch = readLaunch(launchfileContent);
+    const state = await loadState(projectDir);
+    if (!state) {
+        throw new Error("No active launch state. Run `launch up` first.");
+    }
+    // Rebuild resource map from state so the resolver context has real
+    // values at invocation time (same pattern as launchEnv). This calls
+    // provisioner.provision() on already-provisioned resources to retrieve
+    // their current property values — relies on every provisioner being
+    // idempotent: re-running provision() must not corrupt state or
+    // re-create the resource. All current provisioners satisfy this; new
+    // provisioners must as well.
+    const resourceMap = {};
+    for (const [name, res] of Object.entries(state.resources)) {
+        const provisioner = getProvisioner(res.type);
+        if (provisioner) {
+            const result = await provisioner.provision({ type: res.type, name: res.name }, { appName: state.appName, projectDir }, res);
+            resourceMap[name] = result.properties;
+        }
+    }
+    const appProperties = computeAppProperties(launch, state.ports);
+    const context = buildResolverContext(resourceMap, state.ports, state.secrets, appProperties);
+    const results = [];
+    for (const [name, component] of Object.entries(launch.components)) {
+        if (opts.component && name !== opts.component)
+            continue;
+        // `bootstrap` is mode-invariant (D-38): the same command runs from
+        // source or artifact. A path or binary that differs by mode belongs in
+        // storage:/env/PATH, not a separate command.
+        const bootstrap = component.commands?.bootstrap;
+        if (!bootstrap)
+            continue;
+        // Resolve $-expressions in the command string (e.g. $app.url) at
+        // invocation time. Bootstrap runs after start, so the resolved URL
+        // already reflects the actual allocated port.
+        const resolvedCommand = resolveExpression(bootstrap.command, context);
+        // Resolve env vars so the subprocess gets the same environment as
+        // the running component.
+        const env = resolveComponentEnv(component, context, resourceMap);
+        await resolveGenerators(component, env);
+        const port = state.ports[name];
+        if (port && !env.PORT)
+            env.PORT = String(port);
+        console.log(`\n  \u2193 Bootstrap [${name}]`);
+        console.log(`    $ ${resolvedCommand}`);
+        const { exitCode, stdout, stderr } = await runOnce(resolvedCommand, {
+            cwd: projectDir,
+            env,
+            timeoutMs: bootstrap.timeout ? parseDuration(bootstrap.timeout) : 120_000,
+        });
+        const captures = bootstrap.capture
+            ? extractCaptures(stdout, bootstrap.capture)
+            : {};
+        const result = {
+            component: name,
+            command: resolvedCommand,
+            ok: exitCode === 0,
+            exitCode,
+            captures,
+            captureMeta: bootstrap.capture ?? {},
+            stdout,
+            stderr,
+        };
+        results.push(result);
+        // Print captures inline so the user sees them immediately.
+        if (Object.keys(captures).length > 0) {
+            console.log("\n  Captured:");
+            for (const [key, value] of Object.entries(captures)) {
+                const meta = bootstrap.capture?.[key];
+                const displayValue = meta?.sensitive ? "***" : value;
+                const desc = meta?.description ? ` — ${meta.description}` : "";
+                console.log(`    ${key}: ${displayValue}${desc}`);
+            }
+        }
+        if (exitCode !== 0) {
+            console.error(`  \u2717 Bootstrap [${name}] failed with exit code ${exitCode}`);
+            if (stderr)
+                console.error(stderr);
+        }
+        else {
+            console.log(`  \u2713 Bootstrap [${name}] complete`);
+        }
+    }
+    if (results.length === 0) {
+        const target = opts.component ? ` for component "${opts.component}"` : "";
+        console.log(`No bootstrap command declared${target}.`);
+    }
+    return results;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/env-writer.d.ts

@@ -4,26 +4,32 @@
  * Connects provisioned resource properties to the SDK's expression resolver,
  * then writes the results to .env files.
  */
-import { type NormalizedComponent, type NormalizedLaunch, type Secret } from "@launchfile/sdk";
+import { type NormalizedComponent, type NormalizedLaunch, type ResolverContext, type Secret } from "@launchfile/sdk";
 import type { ResourceProperties } from "./resources/types.js";
-/**
- * Context for the SDK's resolveExpression().
- * Mirrors the interface from sdk/src/resolver.ts since it's not exported.
+export type { ResolverContext };
+/**
+ * Compute the $app.* property set (D-33, D-35) for a Launchfile under the
+ * macos-dev provider. The app's "primary" port comes from the first component
+ * (in declaration order) that has at least one `exposed: true` provides entry.
+ * The `authority`/`scheme`/`tls` trio is derived from the resulting URL via the
+ * SDK so split-field tokens (e.g. `CMD_DOMAIN: $app.authority`) resolve.
+ * Apps with no exposed component get `port: 0` and `url: ""` (and empty
+ * authority/scheme/tls).
+ *
+ * For multi-exposed-component apps that need a specific component's URL,
+ * use `$components.<name>.url` instead — `$app.*` always points at the
+ * first exposed component to give a single, predictable answer.
  */
-export interface ResolverContext {
-    resource?: Record<string, string | number>;
-    resources?: Record<string, Record<string, string | number>>;
-    components?: Record<string, Record<string, string | number>>;
-    secrets?: Record<string, string>;
-}
+export declare function computeAppProperties(launch: NormalizedLaunch, componentPorts: Record<string, number>): Record<string, string | number>;
 /**
- * Build a ResolverContext from provisioned resources, component ports, and secrets.
+ * Build a ResolverContext from provisioned resources, component ports,
+ * secrets, and (D-33) the platform-injected app properties.
  */
-export declare function buildResolverContext(resourceMap: Record<string, ResourceProperties>, componentPorts: Record<string, number>, secrets: Record<string, string>): ResolverContext;
+export declare function buildResolverContext(resourceMap: Record<string, ResourceProperties>, componentPorts: Record<string, number>, secrets: Record<string, string>, app: Record<string, string | number>): ResolverContext;
 /**
  * Resolve all environment variables for a single component.
  */
-export declare function resolveComponentEnv(component: NormalizedComponent, context: ResolverContext, resourceMap: Record<string, ResourceProperties>): Record<string, string>;
+export declare function resolveComponentEnv(component: NormalizedComponent, context: ResolverContext, resourceMap: Record<string, ResourceProperties>, storage?: Record<string, Record<string, string>>): Record<string, string>;
 /**
  * Generate all app-wide secrets, reusing values from state when available.
  */

package/dist/env-writer.js

@@ -6,12 +6,44 @@
  */
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { resolveExpression, isExpression, } from "@launchfile/sdk";
+import { deriveAppUrlProperties, resolveExpression, isExpression, } from "@launchfile/sdk";
 import { generateValue } from "./secret-generator.js";
 /**
- * Build a ResolverContext from provisioned resources, component ports, and secrets.
+ * Compute the $app.* property set (D-33, D-35) for a Launchfile under the
+ * macos-dev provider. The app's "primary" port comes from the first component
+ * (in declaration order) that has at least one `exposed: true` provides entry.
+ * The `authority`/`scheme`/`tls` trio is derived from the resulting URL via the
+ * SDK so split-field tokens (e.g. `CMD_DOMAIN: $app.authority`) resolve.
+ * Apps with no exposed component get `port: 0` and `url: ""` (and empty
+ * authority/scheme/tls).
+ *
+ * For multi-exposed-component apps that need a specific component's URL,
+ * use `$components.<name>.url` instead — `$app.*` always points at the
+ * first exposed component to give a single, predictable answer.
+ */
+export function computeAppProperties(launch, componentPorts) {
+    let primaryPort = 0;
+    for (const [name, component] of Object.entries(launch.components)) {
+        const hasExposed = component.provides?.some((p) => p.exposed !== false) ?? false;
+        if (hasExposed && componentPorts[name]) {
+            primaryPort = componentPorts[name];
+            break;
+        }
+    }
+    const url = primaryPort > 0 ? `http://localhost:${primaryPort}` : "";
+    return {
+        name: launch.name,
+        host: "localhost",
+        port: primaryPort,
+        url,
+        ...deriveAppUrlProperties(url),
+    };
+}
+/**
+ * Build a ResolverContext from provisioned resources, component ports,
+ * secrets, and (D-33) the platform-injected app properties.
  */
-export function buildResolverContext(resourceMap, componentPorts, secrets) {
+export function buildResolverContext(resourceMap, componentPorts, secrets, app) {
     // Build components map from ports
     const components = {};
     for (const [name, port] of Object.entries(componentPorts)) {
@@ -32,13 +64,17 @@ export function buildResolverContext(resourceMap, componentPorts, secrets) {
         }
         resources[name] = record;
     }
-    return { resources, components, secrets };
+    return { resources, components, secrets, app };
 }
 /**
  * Resolve all environment variables for a single component.
  */
-export function resolveComponentEnv(component, context, resourceMap) {
+export function resolveComponentEnv(component, context, resourceMap, storage) {
     const env = {};
+    // This component's provider-resolved storage paths (D-39). Scoped per
+    // component because volume names are component-local — component A's
+    // `$storage.cache.path` must not see component B's `cache`.
+    const ctx = storage ? { ...context, storage } : context;
     // 1. Resolve set_env from requires
     for (const req of component.requires ?? []) {
         const resourceName = req.name ?? req.type;
@@ -52,7 +88,7 @@ export function resolveComponentEnv(component, context, resourceMap) {
                 resourceRecord[k] = v;
         }
         const scopedContext = {
-            ...context,
+            ...ctx,
             resource: resourceRecord,
         };
         for (const [envKey, expr] of Object.entries(req.set_env)) {
@@ -71,7 +107,7 @@ export function resolveComponentEnv(component, context, resourceMap) {
                 resourceRecord[k] = v;
         }
         const scopedContext = {
-            ...context,
+            ...ctx,
             resource: resourceRecord,
         };
         for (const [envKey, expr] of Object.entries(sup.set_env)) {
@@ -86,7 +122,7 @@ export function resolveComponentEnv(component, context, resourceMap) {
             if (envVar.default !== undefined) {
                 const defaultStr = String(envVar.default);
                 if (isExpression(defaultStr)) {
-                    env[key] = resolveExpression(defaultStr, context);
+                    env[key] = resolveExpression(defaultStr, ctx);
                 }
                 else {
                     env[key] = defaultStr;

package/dist/index.d.ts

@@ -6,4 +6,6 @@
  */
 export { launchUp, launchDown, launchStatus, launchEnv } from "./provider.js";
 export type { LaunchUpOpts } from "./provider.js";
+export { launchBootstrap } from "./bootstrap.js";
+export type { BootstrapResult } from "./bootstrap.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -5,4 +5,5 @@
  * and native runtimes for the app itself.
  */
 export { launchUp, launchDown, launchStatus, launchEnv } from "./provider.js";
+export { launchBootstrap } from "./bootstrap.js";
 //# sourceMappingURL=index.js.map

package/dist/process-manager.d.ts

@@ -5,6 +5,13 @@
  * health check waits, and graceful shutdown.
  */
 import type { NormalizedHealth, NormalizedDependsOnEntry } from "@launchfile/sdk";
+/** A spawned component process recorded for cross-session shutdown. */
+export interface RecordedProcessInfo {
+    pid: number;
+    pgid: number;
+    startedAt: string;
+    command: string;
+}
 export declare class ProcessManager {
     private processes;
     private logDir;
@@ -32,6 +39,12 @@ export declare class ProcessManager {
      * Returns batches of component names that can start concurrently.
      */
     private topologicalSort;
+    /**
+     * Snapshot the live, spawned processes for persistence to state.json.
+     * Only includes components that actually spawned (have a pid). Because we
+     * spawn detached, the child is its own group leader, so pgid === pid.
+     */
+    getRecordedProcesses(): Record<string, RecordedProcessInfo>;
     /** Get status summary for all processes */
     getStatus(): Array<{
         name: string;

package/dist/process-manager.js

@@ -18,6 +18,28 @@ const COLORS = [
     "\x1b[31m", // red
 ];
 const RESET = "\x1b[0m";
+/**
+ * Signal a detached child's whole process group (negative pid). Falls back to
+ * signaling just the child handle if the group signal fails (e.g. the group is
+ * already gone). Best-effort: swallows ESRCH so shutdown stays idempotent.
+ */
+function killGroupOrSelf(proc, pid, signal) {
+    if (pid !== undefined) {
+        try {
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // Group gone or not a group leader — fall through to handle kill.
+        }
+    }
+    try {
+        proc?.kill(signal);
+    }
+    catch {
+        // Already exited.
+    }
+}
 export class ProcessManager {
     processes = new Map();
     logDir;
@@ -73,11 +95,20 @@ export class ProcessManager {
         const color = COLORS[colorIdx];
         const maxNameLen = Math.max(...[...this.processes.keys()].map((n) => n.length));
         const paddedName = name.padEnd(maxNameLen);
+        // `detached: true` makes the child the leader of a new process group
+        // (pgid === pid). That lets `launch down` signal the whole group later via
+        // a negative pid, killing the app AND any children it spawned — matching
+        // the foreground SIGINT behavior across sessions. We still keep the handle
+        // so the foreground session can kill it directly on Ctrl+C.
         proc.process = spawn("sh", ["-c", proc.command], {
             env: { ...process.env, ...proc.env },
             cwd: proc.cwd,
             stdio: ["ignore", "pipe", "pipe"],
+            detached: true,
         });
+        if (proc.process.pid !== undefined) {
+            proc.startedAt = new Date().toISOString();
+        }
         // Pipe stdout with prefix
         proc.process.stdout?.on("data", (data) => {
             const lines = data.toString().split("\n");
@@ -125,15 +156,19 @@ export class ProcessManager {
                 resolve();
                 return;
             }
+            const pid = proc.process.pid;
             const timeout = setTimeout(() => {
-                proc.process?.kill("SIGKILL");
+                // Escalate to the whole group so stray children die too.
+                killGroupOrSelf(proc.process, pid, "SIGKILL");
             }, 10_000);
             proc.process.once("exit", () => {
                 clearTimeout(timeout);
                 proc.status = "stopped";
                 resolve();
             });
-            proc.process.kill("SIGTERM");
+            // Children are spawned detached (own process group), so signal the
+            // group (negative pid) to reap any grandchildren too.
+            killGroupOrSelf(proc.process, pid, "SIGTERM");
         });
     }
     /**
@@ -175,6 +210,26 @@ export class ProcessManager {
         }
         return batches;
     }
+    /**
+     * Snapshot the live, spawned processes for persistence to state.json.
+     * Only includes components that actually spawned (have a pid). Because we
+     * spawn detached, the child is its own group leader, so pgid === pid.
+     */
+    getRecordedProcesses() {
+        const out = {};
+        for (const [name, proc] of this.processes) {
+            const pid = proc.process?.pid;
+            if (pid === undefined || proc.startedAt === undefined)
+                continue;
+            out[name] = {
+                pid,
+                pgid: pid,
+                startedAt: proc.startedAt,
+                command: proc.command,
+            };
+        }
+        return out;
+    }
     /** Get status summary for all processes */
     getStatus() {
         return [...this.processes.entries()].map(([name, proc]) => ({

package/dist/process-stopper.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Cross-session app-process termination for `launch down`.
+ *
+ * The foreground `launch up` session kills its children directly via the
+ * ProcessManager on Ctrl+C. But `launch down` may run from a *different* shell
+ * (or after the up-session has exited), so it has no live ChildProcess handles —
+ * only the pids recorded in `.launchfile/state.json`. This module signals those
+ * recorded process groups, with liveness + identity checks to avoid killing an
+ * unrelated process that happens to have inherited a recycled pid.
+ *
+ * ## pid-reuse identity guarantee (read this before trusting the kill)
+ *
+ * macOS recycles pids. A pid we recorded at `up` time may, by `down` time,
+ * belong to a completely unrelated process. Before sending any signal we:
+ *
+ *   1. **Liveness** — `process.kill(pid, 0)` throws ESRCH if no such process
+ *      exists. If it's dead, we skip (already stopped).
+ *   2. **Identity** — we compare the recorded spawn time against the live
+ *      process's actual start time via `ps -o lstart= -p <pid>`. If the live
+ *      process started meaningfully later than we recorded, the pid was
+ *      recycled and we REFUSE to signal it.
+ *
+ * This is a best-effort guarantee, not a cryptographic one. Its honest limits:
+ *   - `ps lstart` has ~1s resolution, so we allow a small tolerance window. A
+ *     recycled process that started within that window of the original spawn
+ *     could theoretically slip through — vanishingly unlikely in practice.
+ *   - If `ps` is unavailable/fails, we fall back to liveness-only and signal
+ *     conservatively ONLY the process group (never a bare pid), accepting the
+ *     small residual risk rather than orphaning the user's processes forever.
+ *   - We signal the process GROUP (negative pgid) to also reap children the app
+ *     spawned, matching the foreground SIGINT behavior. A recycled *group*
+ *     leader is the residual risk the start-time check exists to close.
+ */
+/** Signal-sending surface, injectable so tests never touch real processes. */
+export interface SignalFns {
+    /**
+     * Mirror of `process.kill`. Sending signal `0` performs a liveness probe
+     * (throws ESRCH if the target does not exist). A negative pid targets a
+     * process group.
+     */
+    kill: (pid: number, signal: NodeJS.Signals | 0) => void;
+    /**
+     * Returns the live process's start time (epoch ms) for `pid`, or null if the
+     * process is gone or the start time can't be determined.
+     */
+    startTime: (pid: number) => Promise<number | null>;
+}
+/** Outcome of attempting to stop one recorded process, for logging/tests. */
+export type StopOutcome = {
+    component: string;
+    result: "stopped";
+} | {
+    component: string;
+    result: "already-dead";
+} | {
+    component: string;
+    result: "identity-mismatch";
+} | {
+    component: string;
+    result: "error";
+    error: string;
+};
+/** A short-lived recorded process, structurally matching ProcessState. */
+export interface RecordedProcess {
+    pid: number;
+    pgid: number;
+    startedAt: string;
+    command: string;
+}
+/** Default real implementation backed by `process.kill` and `ps`. */
+export declare const realSignalFns: SignalFns;
+/**
+ * Verify a recorded process is still the one we started.
+ *
+ * Returns:
+ *   - "alive-verified": process exists AND start time is consistent → safe to signal
+ *   - "alive-unverified": process exists but start time couldn't be read → signal group only, cautiously
+ *   - "dead": no such process (ESRCH) → already stopped, skip
+ *   - "mismatch": process exists but started too late → recycled pid, DO NOT signal
+ */
+export declare function checkIdentity(rec: RecordedProcess, fns: SignalFns): Promise<"alive-verified" | "alive-unverified" | "dead" | "mismatch">;
+/**
+ * Stop one recorded process: graceful SIGTERM to the group, then escalate to
+ * SIGKILL after `graceMs` if it's still alive. Always targets the process GROUP
+ * (negative pgid) so child processes the app spawned die too.
+ */
+export declare function stopProcess(component: string, rec: RecordedProcess, fns: SignalFns, opts?: {
+    graceMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<StopOutcome>;
+/**
+ * Stop every recorded process. Pure orchestration over `stopProcess`; returns
+ * one outcome per component so the caller can report and tests can assert.
+ */
+export declare function stopRecordedProcesses(processes: Record<string, RecordedProcess>, fns?: SignalFns, opts?: {
+    graceMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<StopOutcome[]>;
+//# sourceMappingURL=process-stopper.d.ts.map