@launchfile/macos-dev 0.2.0 → 0.4.0

package/dist/process-stopper.js

@@ -0,0 +1,165 @@
+/**
+ * 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.
+ */
+import { execFile } from "node:child_process";
+/**
+ * Identity tolerance: how much later than `startedAt` a live process may report
+ * having started before we treat it as a recycled pid. `ps lstart` rounds to
+ * whole seconds and there's scheduling slop between our `Date.now()` snapshot
+ * and the kernel's recorded start, so we allow a few seconds of forward drift.
+ */
+const START_TIME_TOLERANCE_MS = 3000;
+/** Default real implementation backed by `process.kill` and `ps`. */
+export const realSignalFns = {
+    kill: (pid, signal) => {
+        process.kill(pid, signal);
+    },
+    startTime: (pid) => queryStartTime(pid),
+};
+/**
+ * Query a process's start time via `ps -o lstart= -p <pid>` using array args
+ * (no shell, no interpolation). Returns epoch ms, or null on any failure.
+ */
+function queryStartTime(pid) {
+    return new Promise((resolve) => {
+        execFile("ps", ["-o", "lstart=", "-p", String(pid)], (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const text = stdout.trim();
+            if (!text) {
+                resolve(null);
+                return;
+            }
+            const parsed = Date.parse(text);
+            resolve(Number.isNaN(parsed) ? null : parsed);
+        });
+    });
+}
+/**
+ * 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 async function checkIdentity(rec, fns) {
+    // Liveness probe.
+    try {
+        fns.kill(rec.pid, 0);
+    }
+    catch (err) {
+        if (isErrno(err) && err.code === "ESRCH")
+            return "dead";
+        // EPERM means it exists but we can't signal it — treat as alive-unverified.
+        if (isErrno(err) && err.code === "EPERM")
+            return "alive-unverified";
+        return "dead";
+    }
+    const liveStart = await fns.startTime(rec.pid);
+    if (liveStart === null)
+        return "alive-unverified";
+    const recordedStart = Date.parse(rec.startedAt);
+    if (Number.isNaN(recordedStart))
+        return "alive-unverified";
+    // If the live process started meaningfully *after* we recorded the spawn,
+    // the original exited and the pid was recycled. Refuse to signal it.
+    if (liveStart > recordedStart + START_TIME_TOLERANCE_MS)
+        return "mismatch";
+    return "alive-verified";
+}
+/**
+ * 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 async function stopProcess(component, rec, fns, opts = {}) {
+    const graceMs = opts.graceMs ?? 5000;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const identity = await checkIdentity(rec, fns);
+    if (identity === "dead")
+        return { component, result: "already-dead" };
+    if (identity === "mismatch")
+        return { component, result: "identity-mismatch" };
+    // Target the process group. pgid is the leader pid because we spawned detached.
+    const groupTarget = -rec.pgid;
+    try {
+        fns.kill(groupTarget, "SIGTERM");
+    }
+    catch (err) {
+        if (isErrno(err) && err.code === "ESRCH")
+            return { component, result: "already-dead" };
+        return { component, result: "error", error: errMessage(err) };
+    }
+    // Wait for graceful exit, then escalate if the leader is still alive.
+    await sleep(graceMs);
+    let stillAlive = true;
+    try {
+        fns.kill(rec.pid, 0);
+    }
+    catch {
+        stillAlive = false;
+    }
+    if (stillAlive) {
+        try {
+            fns.kill(groupTarget, "SIGKILL");
+        }
+        catch (err) {
+            if (!(isErrno(err) && err.code === "ESRCH")) {
+                return { component, result: "error", error: errMessage(err) };
+            }
+        }
+    }
+    return { component, result: "stopped" };
+}
+/**
+ * Stop every recorded process. Pure orchestration over `stopProcess`; returns
+ * one outcome per component so the caller can report and tests can assert.
+ */
+export async function stopRecordedProcesses(processes, fns = realSignalFns, opts = {}) {
+    const outcomes = [];
+    for (const [component, rec] of Object.entries(processes)) {
+        outcomes.push(await stopProcess(component, rec, fns, opts));
+    }
+    return outcomes;
+}
+function isErrno(err) {
+    return typeof err === "object" && err !== null && "code" in err;
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=process-stopper.js.map

package/dist/provider.d.ts

@@ -4,13 +4,63 @@
  * Reads a Launchfile, provisions resources, resolves env vars,
  * installs runtimes, and starts all components.
  */
+import { type NormalizedLaunch, type NormalizedComponent } from "@launchfile/sdk";
+/**
+ * This provider runs apps from source. A component is source-runnable when
+ * {@link resolveSourceRunCommand} (D-38) resolves a command — declares `dev`,
+ * or a `start` with no `image`. An `image` without a `dev` override stays
+ * artifact-mode, which this source-only provider can't launch.
+ */
+export declare function isSourceRunnable(component: NormalizedComponent): boolean;
 export interface LaunchUpOpts {
     withOptional?: boolean;
     noBuild?: boolean;
     detach?: boolean;
     dryRun?: boolean;
     projectDir?: string;
+    /**
+     * Component selector (#77): if non-empty, these components plus their
+     * transitive downward `depends_on` closure are started (D-41), and the
+     * `requires` of every closure member are provisioned. The start-set is the
+     * SDK's `selectionClosure` — the same definition the Docker provider uses —
+     * so both yield the identical running topology (P-5). Empty = all components.
+     */
+    components?: string[];
 }
+/**
+ * Components this provider must refuse, mapped to the capabilities it cannot
+ * grant (D-44, PROVIDERS.md §11). Both spellings fold together so the `host:`
+ * entry form and the legacy top-level block produce the same outcome.
+ *
+ * A refusal must remove the component from the run, not merely report it —
+ * this provider grants no host capabilities, so anything listed here cannot
+ * be installed, wired, registered, or started.
+ */
+export declare function refusedHostCapabilities(launch: NormalizedLaunch): Map<string, string[]>;
+/**
+ * The launch-time notice a provider without a scheduler owes for a declared
+ * `schedule` (D-51, PROVIDERS.md §10 item 8).
+ *
+ * States what *this provider* does, not what will happen to the app: a
+ * component may schedule itself — `catalog/drafts/diun` sets its own
+ * `DIUN_WATCH_SCHEDULE`, and nextcloud's `cron.sh` is a foreground `crond` —
+ * so claiming the job will not run would be false about those apps, and a
+ * warning that misstates the user's app is worse than the silence it replaces.
+ */
+export declare function scheduleWarning(component: string, schedule: string): string;
+/**
+ * Remove every component this provider must refuse, and say so on stderr.
+ *
+ * The removal is the refusal (D-44, PROVIDERS.md §11): a component left in the
+ * map goes on to be installed, env-wired, registered with the process manager
+ * and started, so logging alone would have the provider assert a refusal it
+ * did not perform. Mutates `launch.components` for exactly that reason —
+ * everything downstream reads it.
+ *
+ * Returns "none-left" when nothing survives, so the caller can fail rather than
+ * report success over an empty set.
+ */
+export declare function applyHostCapabilityRefusals(launch: NormalizedLaunch): "ok" | "none-left";
 export declare function launchUp(opts?: LaunchUpOpts): Promise<void>;
 export declare function launchDown(opts?: {
     destroy?: boolean;