@launchfile/macos-dev 0.3.0 → 0.7.0

package/dist/bootstrap.d.ts

@@ -6,13 +6,21 @@
  * 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.
+ * The command runs through a POSIX shell (SPEC.md § Command interpretation,
+ * PROVIDERS.md §10 item 11), so `&&`, `;`, pipes, redirection, grouping and
+ * variable expansion behave as authors write them. It is passed as a single
+ * argv element to `/bin/sh -c` via spawn({ shell: false }) — it is never
+ * interpolated into a command string on this side, so the only interpreter
+ * that sees it is the `sh` this provider spawns.
  */
-import { type CaptureEntry } from "@launchfile/sdk";
+import { parseDurationMs, type CaptureEntry, type NormalizedLaunch, type ResolverContext } from "@launchfile/sdk";
+/** Default budget for a bootstrap command when no `timeout` is declared. */
+export declare const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 120000;
+/**
+ * The interpreter every bootstrap command runs under. `/bin/sh` is the POSIX
+ * shell guaranteed present on macOS.
+ */
+export declare const BOOTSTRAP_SHELL = "/bin/sh";
 /**
  * Result of running one bootstrap command. Captures may be empty even on
  * success (the command may not produce matching output), and may be
@@ -38,8 +46,47 @@ export interface BootstrapResult {
  * 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;
+/**
+ * Parse a simple duration string like "5m", "30s", "1h" into milliseconds
+ * using the ratified grammar (D-48). Throws on an unparseable value —
+ * PROVIDERS.md §10.10 forbids silently substituting a default. Re-exported
+ * for unit testing.
+ */
+export declare const parseDuration: typeof parseDurationMs;
+/** One planned bootstrap execution, in component declaration order. */
+export interface BootstrapPlanItem {
+    component: string;
+    /** The $-resolved command string. */
+    command: string;
+    /** `["/bin/sh", "-c", command]` — the command as a single argv element. */
+    argv: string[];
+    timeoutMs: number;
+    capture?: Record<string, CaptureEntry>;
+    /**
+     * Set when the item cannot run at all (empty command, unparseable
+     * timeout). Bootstrap failures are reported, never thrown
+     * (SPEC.md § Failure semantics), so a bad item stays in the plan and
+     * carries its own diagnosis.
+     */
+    error?: string;
+}
+/**
+ * Build the bootstrap plan for a launch. Pure — no I/O — so selection,
+ * expression resolution, argv shape and timeout handling are unit-testable.
+ */
+export declare function planBootstraps(launch: NormalizedLaunch, context: ResolverContext, opts?: {
+    component?: string;
+}): BootstrapPlanItem[];
+/** Minimal exec contract so tests can inject a fake runner. */
+export type BootstrapExec = (cmd: string, args: string[], opts: {
+    cwd: string;
+    env: Record<string, string>;
+    timeoutMs: number;
+}) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
 /**
  * Public entry point for `launch bootstrap`. Loads the Launchfile, rebuilds
  * the resolver context from persisted state (so $app.url resolves to the
@@ -54,5 +101,6 @@ export declare function parseDuration(s: string): number;
 export declare function launchBootstrap(opts?: {
     component?: string;
     projectDir?: string;
+    exec?: BootstrapExec;
 }): Promise<BootstrapResult[]>;
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.js

@@ -6,19 +6,28 @@
  * 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.
+ * The command runs through a POSIX shell (SPEC.md § Command interpretation,
+ * PROVIDERS.md §10 item 11), so `&&`, `;`, pipes, redirection, grouping and
+ * variable expansion behave as authors write them. It is passed as a single
+ * argv element to `/bin/sh -c` via spawn({ shell: false }) — it is never
+ * interpolated into a command string on this side, so the only interpreter
+ * that sees it is the `sh` this provider spawns.
  */
 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 { parseDurationMs, readLaunch, resolveExpression, } from "@launchfile/sdk";
+import { loadState, saveState } from "./state.js";
 import { buildResolverContext, computeAppProperties, resolveComponentEnv, resolveGenerators, } from "./env-writer.js";
+import { redactSecrets } from "./redact.js";
 import { getProvisioner } from "./resources/index.js";
+/** Default budget for a bootstrap command when no `timeout` is declared. */
+export const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 120_000;
+/**
+ * The interpreter every bootstrap command runs under. `/bin/sh` is the POSIX
+ * shell guaranteed present on macOS.
+ */
+export const BOOTSTRAP_SHELL = "/bin/sh";
 /**
  * Strip ANSI escape sequences from captured stdout before regex matching.
  * CLI tools that detect a TTY will emit color codes that would otherwise
@@ -51,73 +60,117 @@ export function extractCaptures(stdout, captures) {
     }
     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;
+/**
+ * Parse a simple duration string like "5m", "30s", "1h" into milliseconds
+ * using the ratified grammar (D-48). Throws on an unparseable value —
+ * PROVIDERS.md §10.10 forbids silently substituting a default. Re-exported
+ * for unit testing.
+ */
+export const parseDuration = parseDurationMs;
+/**
+ * Build the bootstrap plan for a launch. Pure — no I/O — so selection,
+ * expression resolution, argv shape and timeout handling are unit-testable.
+ */
+export function planBootstraps(launch, context, opts = {}) {
+    const plan = [];
+    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. A `$$` escape becomes a
+        // literal `$` here and reaches the shell intact (SPEC.md § References).
+        const command = resolveExpression(bootstrap.command, context);
+        const base = {
+            component: name,
+            command,
+            // `/bin/sh -c <command>` — one argv element, so the shell interprets
+            // the command and nothing else (SPEC.md § Command interpretation).
+            argv: [BOOTSTRAP_SHELL, "-c", command],
+            capture: bootstrap.capture,
+        };
+        if (command.trim() === "") {
+            plan.push({
+                ...base,
+                timeoutMs: DEFAULT_BOOTSTRAP_TIMEOUT_MS,
+                error: "empty command",
+            });
+            continue;
+        }
+        let timeoutMs = DEFAULT_BOOTSTRAP_TIMEOUT_MS;
+        if (bootstrap.timeout !== undefined) {
+            try {
+                timeoutMs = parseDuration(bootstrap.timeout);
+            }
+            catch (err) {
+                // An unparseable timeout is surfaced, never silently replaced
+                // with a default (PROVIDERS.md §10.10).
+                plan.push({
+                    ...base,
+                    timeoutMs: DEFAULT_BOOTSTRAP_TIMEOUT_MS,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                continue;
+            }
+        }
+        plan.push({ ...base, timeoutMs });
     }
+    return plan;
 }
 /**
- * Run one command using argv-split (no-shell) execution. Returns the
+ * Run one command. `cmd`/`args` cross the process boundary as an argv vector
+ * with shell:false — the command string is a single element of it, never
+ * interpolated into a string another shell would re-parse. 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 });
-            }
-        });
+const defaultExec = (cmd, args, opts) => new Promise((resolveP) => {
+    const child = spawn(cmd, 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
@@ -154,53 +207,74 @@ export async function launchBootstrap(opts = {}) {
     }
     const appProperties = computeAppProperties(launch, state.ports);
     const context = buildResolverContext(resourceMap, state.ports, state.secrets, appProperties);
+    const exec = opts.exec ?? defaultExec;
+    const plan = planBootstraps(launch, context, { component: opts.component });
     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)
+    for (const item of plan) {
+        const name = item.component;
+        // Bootstrap failures are reported, not thrown (SPEC.md \u00a7 Failure
+        // semantics) \u2014 an unparseable timeout is surfaced the same way,
+        // never silently replaced with a default (PROVIDERS.md \u00a710.10).
+        if (item.error) {
+            console.error(`  \u2717 Bootstrap [${name}]: ${item.error}`);
+            results.push({
+                component: name,
+                command: item.command,
+                ok: false,
+                exitCode: 1,
+                captures: {},
+                captureMeta: item.capture ?? {},
+                stdout: "",
+                stderr: item.error,
+            });
             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);
+        // the running component. Minted generator values come from the store
+        // `up` persists (D-49); a value minted here (a generator declared
+        // after the last `up`) is persisted before the command runs, so
+        // `up`/`env`/`bootstrap` keep agreeing on it.
+        const component = launch.components[name];
+        const { env, unsupplied } = resolveComponentEnv(component, context, resourceMap);
+        const minted = await resolveGenerators(component, env, name, (state.generatedEnv ??= {}));
+        if (minted)
+            await saveState(projectDir, state);
+        // `up` took its `required:` values from the launching environment; read the
+        // same channel so bootstrap really does see the running component's env.
+        for (const { key } of unsupplied) {
+            const supplied = process.env[key];
+            if (supplied !== undefined)
+                env[key] = supplied;
+        }
         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, {
+        // `$secrets.*` / `$<resource>.password` / `$<resource>.url` resolve to live
+        // credentials here, so the echoed command is scrubbed (CWE-532).
+        console.log(`    $ ${redactSecrets(item.command)}`);
+        const [file, ...args] = item.argv;
+        const { exitCode, stdout, stderr } = await exec(file, args, {
             cwd: projectDir,
             env,
-            timeoutMs: bootstrap.timeout ? parseDuration(bootstrap.timeout) : 120_000,
+            timeoutMs: item.timeoutMs,
         });
-        const captures = bootstrap.capture
-            ? extractCaptures(stdout, bootstrap.capture)
-            : {};
-        const result = {
+        const captures = item.capture ? extractCaptures(stdout, item.capture) : {};
+        results.push({
             component: name,
-            command: resolvedCommand,
+            command: item.command,
             ok: exitCode === 0,
             exitCode,
             captures,
-            captureMeta: bootstrap.capture ?? {},
+            captureMeta: item.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 meta = item.capture?.[key];
                 const displayValue = meta?.sensitive ? "***" : value;
                 const desc = meta?.description ? ` — ${meta.description}` : "";
                 console.log(`    ${key}: ${displayValue}${desc}`);
@@ -209,7 +283,7 @@ export async function launchBootstrap(opts = {}) {
         if (exitCode !== 0) {
             console.error(`  \u2717 Bootstrap [${name}] failed with exit code ${exitCode}`);
             if (stderr)
-                console.error(stderr);
+                console.error(redactSecrets(stderr));
         }
         else {
             console.log(`  \u2713 Bootstrap [${name}] complete`);

package/dist/env-writer.d.ts

@@ -4,9 +4,9 @@
  * Connects provisioned resource properties to the SDK's expression resolver,
  * then writes the results to .env files.
  */
-import { type NormalizedComponent, type NormalizedLaunch, type ResolverContext, type Secret } from "@launchfile/sdk";
+import { type NormalizedComponent, type NormalizedLaunch, type ResolverContext, type Secret, type UnsuppliedRequiredEnv } from "@launchfile/sdk";
 import type { ResourceProperties } from "./resources/types.js";
-export type { ResolverContext };
+export type { ResolverContext, UnsuppliedRequiredEnv };
 /**
  * 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
@@ -26,19 +26,45 @@ export declare function computeAppProperties(launch: NormalizedLaunch, component
  * 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>, app: Record<string, string | number>): ResolverContext;
+/**
+ * The resolved environment for one component, plus what the file did not supply.
+ */
+export interface ComponentEnvResult {
+    /** Keys that actually arrived. An unsupplied `required:` key is ABSENT, never `""`. */
+    env: Record<string, string>;
+    /**
+     * `required:` variables with no `generator:`, no `default:`, and no
+     * `set_env:` binding that injected (D-52, PROVIDERS.md §10 rule 8). The
+     * caller decides: `up` reads its operator channel then fails by name, `env`
+     * reports them without breaking `eval`.
+     */
+    unsupplied: UnsuppliedRequiredEnv[];
+}
 /**
  * Resolve all environment variables for a single component.
  */
-export declare function resolveComponentEnv(component: NormalizedComponent, context: ResolverContext, resourceMap: Record<string, ResourceProperties>, storage?: Record<string, Record<string, string>>): Record<string, string>;
+export declare function resolveComponentEnv(component: NormalizedComponent, context: ResolverContext, resourceMap: Record<string, ResourceProperties>, storage?: Record<string, Record<string, string>>): ComponentEnvResult;
 /**
  * Generate all app-wide secrets, reusing values from state when available.
  */
 export declare function generateSecrets(secretDefs: Record<string, Secret> | undefined, existingSecrets: Record<string, string>): Promise<Record<string, string>>;
 /**
- * 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 declare function resolveGenerators(component: NormalizedComponent, env: Record<string, string>): Promise<void>;
+export declare function resolveGenerators(component: NormalizedComponent, env: Record<string, string>, componentName: string, generatedEnv: Record<string, string>): Promise<boolean>;
 /**
  * Write resolved env vars to a .env file.
  */
@@ -48,5 +74,5 @@ export declare function writeEnvFile(filePath: string, env: Record<string, strin
  * Single-component → .env.local at project root.
  * Multi-component → .launchfile/env/<component>.env per component.
  */
-export declare function writeAllEnvFiles(launch: NormalizedLaunch, context: ResolverContext, resourceMap: Record<string, ResourceProperties>, componentPorts: Record<string, number>, projectDir: string): Promise<Record<string, Record<string, string>>>;
+export declare function writeAllEnvFiles(launch: NormalizedLaunch, context: ResolverContext, resourceMap: Record<string, ResourceProperties>, componentPorts: Record<string, number>, projectDir: string, generatedEnv: Record<string, string>): Promise<Record<string, Record<string, string>>>;
 //# sourceMappingURL=env-writer.d.ts.map

package/dist/env-writer.js

@@ -6,7 +6,7 @@
  */
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { deriveAppUrlProperties, resolveExpression, isExpression, } from "@launchfile/sdk";
+import { deriveAppUrlProperties, resolveExpression, isExpression, unsuppliedRequiredEnv, } from "@launchfile/sdk";
 import { generateValue } from "./secret-generator.js";
 /**
  * Compute the $app.* property set (D-33, D-35) for a Launchfile under the
@@ -24,7 +24,13 @@ 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.
+        // This provider has no orchestrator-facing publication channel (#294), so
+        // $app.* always comes from its own routing strategy. The docker provider
+        // answers by this same rule only when no orchestrator supplies an appUrl
+        // (PROVIDERS.md §7).
+        const hasExposed = component.provides?.some((p) => p.exposed === true) ?? false;
         if (hasExposed && componentPorts[name]) {
             primaryPort = componentPorts[name];
             break;
@@ -77,6 +83,11 @@ export function resolveComponentEnv(component, context, resourceMap, storage) {
     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)
@@ -97,6 +108,8 @@ export function resolveComponentEnv(component, context, resourceMap, storage) {
     }
     // 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)
@@ -119,6 +132,12 @@ export function resolveComponentEnv(component, context, resourceMap, storage) {
         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)) {
@@ -128,10 +147,15 @@ export function resolveComponentEnv(component, context, resourceMap, storage) {
                     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.
@@ -148,19 +172,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.
@@ -169,9 +220,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}`;
     });
@@ -184,13 +238,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.