@launchfile/macos-dev 0.2.0 → 0.4.0

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, unsuppliedRequiredEnv, } 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
@@ -21,17 +24,23 @@ import { generateValue } from "./secret-generator.js";
 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;
+        // Only endpoints explicitly marked `exposed: true` are reachable from
+        // outside the host (D-27), so only they can be the app's public address.
+        // The docker provider derives `$app.*` by the same rule — `$app.url` is a
+        // portable value and the two providers must not disagree on it (P-5).
+        const hasExposed = component.provides?.some((p) => p.exposed === true) ?? 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: primaryPort > 0 ? `http://localhost:${primaryPort}` : "",
+        url,
+        ...deriveAppUrlProperties(url),
     };
 }
 /**
@@ -64,10 +73,19 @@ 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 ?? []) {
+        // A host capability (D-44) is never provisioned, so it has no properties
+        // to resolve against. An ungranted capability's set_env vars are omitted
+        // rather than resolved to empty strings.
+        if (req.host)
+            continue;
         const resourceName = req.name ?? req.type;
         const props = resourceMap[resourceName];
         if (!req.set_env || !props)
@@ -79,7 +97,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)) {
@@ -88,6 +106,8 @@ export function resolveComponentEnv(component, context, resourceMap) {
     }
     // 2. Resolve set_env from supports (only if resource was provisioned)
     for (const sup of component.supports ?? []) {
+        if (sup.host)
+            continue; // capability, not a backing service (D-44)
         const resourceName = sup.name ?? sup.type;
         const props = resourceMap[resourceName];
         if (!sup.set_env || !props)
@@ -98,7 +118,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)) {
@@ -110,19 +130,30 @@ export function resolveComponentEnv(component, context, resourceMap) {
         for (const [key, envVar] of Object.entries(component.env)) {
             if (env[key] !== undefined)
                 continue; // set_env takes precedence
+            // A generator outranks a default (D-49 provenance precedence). Filling
+            // the default here would win by arriving first — resolveGenerators
+            // skips any key already set — and this provider would mint nothing
+            // where docker and aws mint a secret, for the same file.
+            if (envVar.generator)
+                continue;
             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;
                 }
             }
-            // required + no default + no generator → left unset (provider should prompt)
         }
     }
-    return env;
+    // A `required:` var nothing above yielded is left ABSENT and reported, not
+    // silently dropped (D-52, PROVIDERS.md §10 rule 8). `generator:` keys were
+    // skipped just above but are not unsupplied — `resolveGenerators` mints them
+    // — and the shared predicate excludes them for that reason. The test runs
+    // after the `set_env` loops so it measures arrival, not declaration.
+    const unsupplied = unsuppliedRequiredEnv(component, Object.keys(env));
+    return { env, unsupplied };
 }
 /**
  * Generate all app-wide secrets, reusing values from state when available.
@@ -139,19 +170,46 @@ export async function generateSecrets(secretDefs, existingSecrets) {
     return secrets;
 }
 /**
- * Generate values for env vars that have generators.
- * Mutates the env record in place.
+ * Resolve values for env vars that declare generators, preserving minted
+ * values across runs (D-49: generate once, then preserve).
+ *
+ * A `secret` or `uuid` value is read from `generatedEnv` when present, and
+ * minted and written into it when absent. The store is keyed
+ * `<component>.<ENV_NAME>` — one entry per declaration (D-25), so two
+ * components declaring the same variable name hold independent values.
+ * `generator: port` is exempt: ports have their own preserved home
+ * (`state.ports`) and allocator, and a preserved port produces a bind
+ * conflict rather than continuity.
+ *
+ * Mutates `env` and `generatedEnv` in place. Returns true when a new value
+ * was minted into `generatedEnv` — the caller must then persist the state
+ * before handing the value to anything, so every site that mints persists.
  */
-export async function resolveGenerators(component, env) {
+export async function resolveGenerators(component, env, componentName, generatedEnv) {
     if (!component.env)
-        return;
+        return false;
+    let minted = false;
     for (const [key, envVar] of Object.entries(component.env)) {
         if (env[key] !== undefined)
             continue;
-        if (envVar.generator) {
+        if (!envVar.generator)
+            continue;
+        if (envVar.generator === "port") {
             env[key] = await generateValue(envVar.generator);
+            continue;
+        }
+        const stateKey = `${componentName}.${key}`;
+        const existing = generatedEnv[stateKey];
+        if (existing !== undefined) {
+            env[key] = existing;
+            continue;
         }
+        const value = await generateValue(envVar.generator);
+        env[key] = value;
+        generatedEnv[stateKey] = value;
+        minted = true;
     }
+    return minted;
 }
 /**
  * Write resolved env vars to a .env file.
@@ -160,9 +218,12 @@ export async function writeEnvFile(filePath, env) {
     const lines = Object.entries(env)
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([key, value]) => {
-        // Quote values that contain spaces, #, or newlines
+        // Quote values that contain spaces, #, or newlines. Escape backslashes
+        // first, then quotes — otherwise a value containing a backslash would
+        // produce broken or injectable quoting (CWE-116 incomplete escaping).
         if (/[\s#\n]/.test(value)) {
-            return `${key}="${value.replace(/"/g, '\\"')}"`;
+            const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+            return `${key}="${escaped}"`;
         }
         return `${key}=${value}`;
     });
@@ -175,13 +236,13 @@ export async function writeEnvFile(filePath, env) {
  * Single-component → .env.local at project root.
  * Multi-component → .launchfile/env/<component>.env per component.
  */
-export async function writeAllEnvFiles(launch, context, resourceMap, componentPorts, projectDir) {
+export async function writeAllEnvFiles(launch, context, resourceMap, componentPorts, projectDir, generatedEnv) {
     const allEnvs = {};
     const componentNames = Object.keys(launch.components);
     const isSingleComponent = componentNames.length === 1 && componentNames[0] === "default";
     for (const [name, component] of Object.entries(launch.components)) {
-        const env = resolveComponentEnv(component, context, resourceMap);
-        await resolveGenerators(component, env);
+        const { env } = resolveComponentEnv(component, context, resourceMap);
+        await resolveGenerators(component, env, name, generatedEnv);
         // Inject PORT if not already set and component has provides
         const port = componentPorts[name];
         if (port && !env.PORT) {

package/dist/health.d.ts

@@ -1,8 +1,14 @@
 /**
  * Health check polling for components.
  */
-import type { NormalizedHealth } from "@launchfile/sdk";
-/** Parse a duration string like "30s", "1m", "500ms" to milliseconds */
+import { type NormalizedHealth } from "@launchfile/sdk";
+/**
+ * Parse a health duration against the ratified grammar (D-48). Throws on an
+ * unparseable value — PROVIDERS.md §10.10 forbids silently substituting a
+ * default, and the previous local parser did exactly that in the worst
+ * possible way: it accepted no `h` unit and returned 0, so a spec-valid
+ * `interval: "1h"` became a zero-length poll that could never pass.
+ */
 export declare function parseDuration(duration: string): number;
 /**
  * Wait for a component to become healthy.

package/dist/health.js

@@ -1,23 +1,17 @@
 /**
  * Health check polling for components.
  */
-import { shell } from "./shell.js";
-/** Parse a duration string like "30s", "1m", "500ms" to milliseconds */
+import { parseDurationMs } from "@launchfile/sdk";
+import { shellScript } from "./shell.js";
+/**
+ * Parse a health duration against the ratified grammar (D-48). Throws on an
+ * unparseable value — PROVIDERS.md §10.10 forbids silently substituting a
+ * default, and the previous local parser did exactly that in the worst
+ * possible way: it accepted no `h` unit and returned 0, so a spec-valid
+ * `interval: "1h"` became a zero-length poll that could never pass.
+ */
 export function parseDuration(duration) {
-    const match = /^(\d+)(ms|s|m)$/.exec(duration);
-    if (!match)
-        return 0;
-    const value = Number.parseInt(match[1], 10);
-    switch (match[2]) {
-        case "ms":
-            return value;
-        case "s":
-            return value * 1000;
-        case "m":
-            return value * 60_000;
-        default:
-            return 0;
-    }
+    return parseDurationMs(duration);
 }
 /**
  * Wait for a component to become healthy.
@@ -45,7 +39,7 @@ export async function waitForHealthy(name, health, port, overallTimeout = 60_000
                 }
             }
             else if (health.command) {
-                await shell(health.command, { timeout: checkTimeout, silent: true });
+                await shellScript(health.command, { timeout: checkTimeout, silent: true });
                 console.log(`  [${name}] Healthy`);
                 return true;
             }

package/dist/prereqs.js

@@ -6,11 +6,11 @@ export async function checkPrereqs() {
     const missing = [];
     const warnings = [];
     // Homebrew is required
-    if (!(await shellOk("which brew"))) {
+    if (!(await shellOk("which", ["brew"]))) {
         missing.push("Homebrew — install from https://brew.sh");
     }
     // Git is required (for cloning)
-    if (!(await shellOk("which git"))) {
+    if (!(await shellOk("which", ["git"]))) {
         missing.push("git — install via: brew install git");
     }
     return {

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

@@ -8,6 +8,7 @@ import { spawn } from "node:child_process";
 import { createWriteStream, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { waitForHealthy } from "./health.js";
+import { redactSecrets } from "./redact.js";
 // ANSI colors for log prefixing
 const COLORS = [
     "\x1b[36m", // cyan
@@ -18,6 +19,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;
@@ -67,17 +90,26 @@ export class ProcessManager {
             // For "started" condition, the process is already spawned by the time we get here
         }
         proc.status = "starting";
-        console.log(`  [${name}] Starting: ${proc.command}`);
+        console.log(`  [${name}] Starting: ${redactSecrets(proc.command)}`);
         const logFile = createWriteStream(join(this.logDir, `${name}.log`), { flags: "a" });
         const colorIdx = [...this.processes.keys()].indexOf(name) % COLORS.length;
         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 +157,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 +211,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