@launchfile/macos-dev 0.2.0 → 0.4.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,50 +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;
-        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}`);
@@ -206,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,14 +4,17 @@
  * 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 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
@@ -23,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>): 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.
  */
@@ -45,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