@launchfile/macos-dev 0.2.0 → 0.3.0

package/dist/bootstrap.js

@@ -158,6 +158,9 @@ export async function launchBootstrap(opts = {}) {
     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;

package/dist/env-writer.d.ts

@@ -8,10 +8,13 @@ import { type NormalizedComponent, type NormalizedLaunch, type ResolverContext,
 import type { ResourceProperties } from "./resources/types.js";
 export type { ResolverContext };
 /**
- * Compute the $app.* property set 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.
- * Apps with no exposed component get `port: 0` and `url: ""`.
+ * 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
@@ -26,7 +29,7 @@ export declare function buildResolverContext(resourceMap: Record<string, Resourc
 /**
  * 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,13 +6,16 @@
  */
 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";
 /**
- * Compute the $app.* property set 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.
- * Apps with no exposed component get `port: 0` and `url: ""`.
+ * 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
@@ -27,11 +30,13 @@ export function computeAppProperties(launch, componentPorts) {
             break;
         }
     }
+    const url = primaryPort > 0 ? `http://localhost:${primaryPort}` : "";
     return {
         name: launch.name,
         host: "localhost",
         port: primaryPort,
-        url: primaryPort > 0 ? `http://localhost:${primaryPort}` : "",
+        url,
+        ...deriveAppUrlProperties(url),
     };
 }
 /**
@@ -64,8 +69,12 @@ export function buildResolverContext(resourceMap, componentPorts, 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;
@@ -79,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)) {
@@ -98,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)) {
@@ -113,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/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

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,12 +4,30 @@
  * Reads a Launchfile, provisions resources, resolves env vars,
  * installs runtimes, and starts all components.
  */
+import { type NormalizedComponent } from "@launchfile/sdk";
+/**
+ * Source-mode run resolution (D-38, precedence `dev` > `image` > `start`).
+ * This provider runs apps from source. A component is source-runnable when it
+ * 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;
+/** The command run from source, or undefined if the component resolves to its artifact. */
+export declare function sourceRunCommand(component: NormalizedComponent): string | undefined;
 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[];
 }
 export declare function launchUp(opts?: LaunchUpOpts): Promise<void>;
 export declare function launchDown(opts?: {