@launchfile/macos-dev 0.12.0 → 0.14.0

package/dist/provider.d.ts

@@ -5,6 +5,7 @@
  * installs runtimes, and starts all components.
  */
 import { type NormalizedLaunch, type NormalizedComponent } from "@launchfile/sdk";
+import { type LaunchState } from "./state.js";
 /**
  * This provider runs apps from source. A component is source-runnable when
  * {@link resolveSourceRunCommand} (D-38) resolves a command — declares `dev`,
@@ -159,7 +160,8 @@ export declare function applyResourceTypeRefusals(launch: NormalizedLaunch): "ok
  * use its provisioner cannot cover (SPEC.md § Resource uses, D-56 rule 1,
  * D-64), mapped to `<entry>: <use>` lines. Graded after
  * {@link refusedResourceTypes}: a type with no provisioner is refused on the
- * type, so only entries whose type this provider stands up reach here. A
+ * type, so only entries whose type this provider stands up, or accepts
+ * through the publication context (`https-origin`), reach here. A
  * token this provider does not recognise is uncovered — no provider can
  * claim to cover a use it does not know. `supports:` entries are optional
  * (D-8) and are not graded here.
@@ -184,7 +186,73 @@ export declare function applyResourceUseRefusals(launch: NormalizedLaunch): "ok"
  * URL (D-58) the names are whoever routes that URL's to send here (rule 7).
  */
 export declare function atReports(launch: NormalizedLaunch, ports?: Record<string, number>, suppliedAppUrl?: string): string[];
+/** What {@link runSourcePrepare} needs from the surrounding `up`. */
+export interface SourcePrepareContext {
+    projectDir: string;
+    /** Mutated in place: successful runs are recorded under `state.prepared`. */
+    state: LaunchState;
+    /** Resolved environment per component, as `prepare` should see it. */
+    envs: Record<string, Record<string, string>>;
+    /** Package-manager install command used where a component declares none. */
+    fallbackCommand?: string;
+    /** Prefix progress lines with the component name (multi-component apps). */
+    labelComponents?: boolean;
+    /** Runs one command. Injected so tests can observe without a real shell. */
+    run?: (command: string, opts: {
+        cwd: string;
+        env?: Record<string, string>;
+        timeout?: number;
+    }) => Promise<unknown>;
+    /** Persists state whenever a component's `state.prepared` record changes. */
+    save?: (projectDir: string, state: LaunchState) => Promise<void>;
+}
+/**
+ * Run the source-mode prepare slot (`install ?? build`, D-38) for every
+ * component that declares one, **on demand**: on first launch, and afterwards
+ * only when the prepare inputs changed.
+ *
+ * The demand signal is {@link prepareFingerprint} — the command plus the
+ * dependency manifests and lockfiles in its working directory. `state.prepared`
+ * holds the fingerprint of each component's last successful run, so an
+ * unchanged component is skipped rather than reinstalled on every `up`.
+ *
+ * Components resolving to the same working directory and command share one
+ * prepare, so it runs once per `up` (D-38) even on a first launch, when neither
+ * has a recorded fingerprint yet.
+ *
+ * A failing command throws, which fails the launch (SPEC.md § Failure
+ * semantics): the prepare slot fails the invocation. Nothing is recorded for
+ * it, so the next `up` retries.
+ */
+export declare function runSourcePrepare(launch: NormalizedLaunch, ctx: SourcePrepareContext): Promise<void>;
 export declare function launchUp(opts?: LaunchUpOpts): Promise<void>;
+/**
+ * What a printout reads to place the orchestrator-supplied publication URL
+ * (D-58): the URL, and the `ports` key it asserts. One URL asserts the
+ * primary endpoint only (D-58 rule 4), so every other key keeps this
+ * provider's own address; with no URL every key does.
+ */
+export type PrintedPublication = Pick<LaunchState, "appUrl" | "primaryEndpoint">;
+/**
+ * The address to print for one `ports` key — the single definition `up` and
+ * `status` share. The supplied publication URL on the primary endpoint's key,
+ * as stored (`normalizeAppUrl` ran when `up` recorded it; nothing runs again
+ * here); this provider's own `http://localhost:<port>` on every other key,
+ * and on every key when no URL is supplied — byte-identical to a run with
+ * none. `up` records `primaryEndpoint` only for an `http`/`https` primary or
+ * one a declared `https-origin` names, so a positional `ws`/`tcp`/`udp`/`grpc`
+ * primary keeps this provider's own form (§7, `printedPrimaryEndpoint`).
+ */
+export declare function componentAddress(key: string, port: number, publication?: PrintedPublication): string;
+/**
+ * The "<component> is running at …" lines `up` prints, one per `ports` key.
+ * `verb` is the phrase between the label and the address; a dry run passes
+ * "would be reachable at" because nothing has started.
+ * Pure, so the placement of the supplied URL is testable without a launch.
+ */
+export declare function summaryLines(appName: string, ports: Record<string, number>, publication?: PrintedPublication, verb?: string): string[];
+/** The "Components:" lines `status` prints, one per `ports` key. */
+export declare function statusLines(ports: Record<string, number>, publication?: PrintedPublication): string[];
 export declare function launchDown(opts?: {
     destroy?: boolean;
     projectDir?: string;

package/dist/provider.js

@@ -7,17 +7,19 @@
 import { accessSync, constants as fsConstants } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve as resolvePath } from "node:path";
-import { AT_APP_HOST, atDeclarations, atEntryLabel, CERTIFICATE, certificateBindings, indexOperatorStoragePaths, MissingOperatorStoragePathError, normalizeAppUrl, readLaunch, resolveSourcePrepareCommand, resolveSourceRunCommand, selectionClosure, UnboundOperatorStorageError, unsuppliedRequiredEnv, appEndpointReferences, useKeys, } from "@launchfile/sdk";
+import { AT_APP_HOST, atDeclarations, atEntryLabel, buildLaunchErrorContext, CERTIFICATE, certificateBindings, indexOperatorStoragePaths, LaunchError, MissingOperatorStoragePathError, normalizeAppUrl, readLaunch, resolveSourcePrepareCommand, resolveSourceRunCommand, selectionClosure, UnboundOperatorStorageError, unsuppliedRequiredEnv, appEndpointReferences, useKeys, } from "@launchfile/sdk";
 import { checkPrereqs } from "./prereqs.js";
-import { HTTPS_ORIGIN, httpsOriginSatisfied, httpsOriginShortfall, } from "./https-origin.js";
-import { loadState, initState, saveState, ensureDirs, withRecordedDbIndexes } from "./state.js";
-import { declaredUses, registerResource, resolveComponentEnv, resolverContextFor, resourceMapFromState, generateSecrets, resolveGenerators, writeEnvFile, } from "./env-writer.js";
+import { declaredPrimary, HTTPS_ORIGIN, httpsOriginSatisfied, httpsOriginShortfall, uncoveredOriginUses, } from "./https-origin.js";
+import { loadState, initState, saveState, ensureDirs, withRecordedDbIndexes, } from "./state.js";
+import { declaredUses, printedPrimaryEndpoint, registerResource, resolveComponentEnv, resolverContextFor, resourceMapFromState, generateSecrets, resolveGenerators, writeEnvFile, } from "./env-writer.js";
 import { allocateDbIndexes, getProvisioner, namedDatabases, uncoveredUses, } from "./resources/index.js";
 import { allocatePorts } from "./port-allocator.js";
 import { getRuntimeInstaller } from "./runtimes/index.js";
 import { detectPackageManager } from "./lockfile-detect.js";
+import { prepareFingerprint } from "./prepare-fingerprint.js";
 import { provisionStorage, storagePaths } from "./storage.js";
-import { ProcessManager } from "./process-manager.js";
+import { HealthGateError, ProcessManager } from "./process-manager.js";
+import { redactSecrets } from "./redact.js";
 import { stopRecordedProcesses } from "./process-stopper.js";
 import { shellScript } from "./shell.js";
 import { parseDuration } from "./bootstrap.js";
@@ -266,7 +268,8 @@ export function applyResourceTypeRefusals(launch) {
  * use its provisioner cannot cover (SPEC.md § Resource uses, D-56 rule 1,
  * D-64), mapped to `<entry>: <use>` lines. Graded after
  * {@link refusedResourceTypes}: a type with no provisioner is refused on the
- * type, so only entries whose type this provider stands up reach here. A
+ * type, so only entries whose type this provider stands up, or accepts
+ * through the publication context (`https-origin`), reach here. A
  * token this provider does not recognise is uncovered — no provider can
  * claim to cover a use it does not know. `supports:` entries are optional
  * (D-8) and are not graded here.
@@ -276,7 +279,9 @@ export function refusedResourceUses(launch) {
     for (const [name, component] of Object.entries(launch.components)) {
         const entries = [];
         for (const req of component.requires ?? []) {
-            if (req.host || req.type === HTTPS_ORIGIN || !req.uses || !getProvisioner(req.type))
+            if (req.host || !req.uses)
+                continue;
+            if (req.type !== HTTPS_ORIGIN && !getProvisioner(req.type))
                 continue;
             const resourceName = req.name ?? req.type;
             for (const use of uncoveredUses(req.type, useKeys(req.uses))) {
@@ -343,6 +348,67 @@ function printAtReports(reports) {
     for (const report of reports)
         console.warn(`  Warning: ${report}`);
 }
+/**
+ * Run the source-mode prepare slot (`install ?? build`, D-38) for every
+ * component that declares one, **on demand**: on first launch, and afterwards
+ * only when the prepare inputs changed.
+ *
+ * The demand signal is {@link prepareFingerprint} — the command plus the
+ * dependency manifests and lockfiles in its working directory. `state.prepared`
+ * holds the fingerprint of each component's last successful run, so an
+ * unchanged component is skipped rather than reinstalled on every `up`.
+ *
+ * Components resolving to the same working directory and command share one
+ * prepare, so it runs once per `up` (D-38) even on a first launch, when neither
+ * has a recorded fingerprint yet.
+ *
+ * A failing command throws, which fails the launch (SPEC.md § Failure
+ * semantics): the prepare slot fails the invocation. Nothing is recorded for
+ * it, so the next `up` retries.
+ */
+export async function runSourcePrepare(launch, ctx) {
+    const run = ctx.run ?? shellScript;
+    const save = ctx.save ?? saveState;
+    ctx.state.prepared ??= {};
+    const prepared = ctx.state.prepared;
+    const ranThisUp = new Set();
+    for (const [name, component] of Object.entries(launch.components)) {
+        const prepare = resolveSourcePrepareCommand(component);
+        const command = prepare?.command ?? ctx.fallbackCommand;
+        if (!command)
+            continue;
+        const label = ctx.labelComponents ? ` [${name}]` : "";
+        const sourceDir = join(component.source ?? component.build?.context ?? ".");
+        const cwd = join(ctx.projectDir, sourceDir);
+        // Identifies a shared prepare: same directory, same command.
+        const sharedKey = `${sourceDir}\u0000${command}`;
+        const fingerprint = await prepareFingerprint(cwd, command);
+        if (prepared[name] === fingerprint || ranThisUp.has(sharedKey)) {
+            // A component sharing this prepare is covered by an up-to-date record
+            // as much as by a run this `up`.
+            ranThisUp.add(sharedKey);
+            if (prepared[name] !== fingerprint) {
+                prepared[name] = fingerprint;
+                await save(ctx.projectDir, ctx.state);
+            }
+            console.log(`  \u2713 Prepare up to date${label} (no dependency change)`);
+            continue;
+        }
+        console.log(`  \u2193 Preparing${label}...`);
+        await run(command, {
+            cwd,
+            env: ctx.envs[name],
+            // Installs/compiles routinely exceed the 2-minute shell default;
+            // honor a declared timeout, else allow 10 minutes.
+            timeout: declaredTimeout(prepare?.timeout, `prepare [${name}]`) ?? 600_000,
+        });
+        ranThisUp.add(sharedKey);
+        // Recorded as each command succeeds: a later component can fail the
+        // launch, and that must not discard the record of work already done.
+        prepared[name] = fingerprint;
+        await save(ctx.projectDir, ctx.state);
+    }
+}
 export async function launchUp(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
     // Publication context (D-58): validated and normalized before anything is
@@ -392,6 +458,28 @@ export async function launchUp(opts = {}) {
         const startSet = new Set(selection.start);
         launch.components = Object.fromEntries(Object.entries(launch.components).filter(([n]) => startSet.has(n)));
     }
+    // State is loaded ahead of every refusal (loading writes nothing; the
+    // first write is `ensureDirs`): the https-origin refusal at 2a-bis reads
+    // the recorded publication context, and the declared primary below is
+    // read against it.
+    let state = await loadState(projectDir);
+    if (!state) {
+        state = initState(launch.name, launchfileContent);
+    }
+    // Publication context (D-58), the same preservation rule the docker provider
+    // applies: a supplied value replaces the recorded one — the derived $app.*
+    // env recomputes below from it (D-49) — while omission keeps what is
+    // recorded, so a later plain `up` cannot silently flip a proxied deployment
+    // back to localhost.
+    if (suppliedAppUrl !== undefined)
+        state.appUrl = suppliedAppUrl;
+    // The primary an `https-origin` entry declares (D-60 rule 3), read now,
+    // while the start-set is whole: the refusals below remove a refused
+    // component from `launch.components`, and a primary read after that
+    // would fall back to a surviving sibling. Declaration fixes the primary;
+    // a refused one keeps its place and resolves the empty address at step
+    // 8 (D-72).
+    const primary = declaredPrimary(launch, state.appUrl);
     // 2a. Host capabilities are granted or refused, never provisioned (D-44,
     // PROVIDERS.md §11). This provider runs processes directly on the host and
     // grants none of them, so a component with a required capability is
@@ -407,21 +495,8 @@ export async function launchUp(opts = {}) {
     // 2a-bis. A required `https-origin` (D-60 rule 5, PROVIDERS.md §10 item 5)
     // is satisfied by the publication context when its scheme is https —
     // supplied on this run, or recorded by an earlier one and preserved on
-    // omission, which is why state is loaded here rather than after the
-    // refusals (loading writes nothing; the first write is `ensureDirs`).
-    // Otherwise it is refused in the same way as a host capability: starting
-    // the component anyway is the silent success the type removes.
-    let state = await loadState(projectDir);
-    if (!state) {
-        state = initState(launch.name, launchfileContent);
-    }
-    // Publication context (D-58), the same preservation rule the docker provider
-    // applies: a supplied value replaces the recorded one — the derived $app.*
-    // env recomputes below from it (D-49) — while omission keeps what is
-    // recorded, so a later plain `up` cannot silently flip a proxied deployment
-    // back to localhost.
-    if (suppliedAppUrl !== undefined)
-        state.appUrl = suppliedAppUrl;
+    // omission. Otherwise it is refused in the same way as a host capability:
+    // starting the component anyway is the silent success the type removes.
     if (applyHttpsOriginRefusals(launch, state.appUrl) === "none-left") {
         console.error("Every selected component requires a public HTTPS origin this provider cannot supply.");
         process.exit(1);
@@ -467,9 +542,22 @@ export async function launchUp(opts = {}) {
         }
         // The optional mood of `https-origin` (D-60 rule 6): satisfied, it is
         // wired like any other resource at step 8; unsatisfied, the component
-        // still runs, its set_env is absent, and the shortfall is named.
-        if (httpsOriginSatisfied(state.appUrl))
+        // still runs, its set_env is absent, and the shortfall is named. A
+        // declared use this provider cannot cover leaves a satisfied entry
+        // unfulfilled the same way (D-65 rule 4).
+        if (httpsOriginSatisfied(state.appUrl)) {
+            for (const sup of c.supports ?? []) {
+                if (sup.type !== HTTPS_ORIGIN)
+                    continue;
+                const uncovered = uncoveredOriginUses(sup);
+                if (uncovered.length === 0)
+                    continue;
+                console.warn(`  Warning: ${name}: optional public HTTPS origin ${sup.name ?? sup.type} not satisfied — ` +
+                    `this provider does not cover ${uncovered.length === 1 ? "a use" : "uses"} it declares ` +
+                    `(${uncovered.join(", ")}); running degraded`);
+            }
             continue;
+        }
         for (const sup of c.supports ?? []) {
             if (sup.type !== HTTPS_ORIGIN)
                 continue;
@@ -610,7 +698,7 @@ export async function launchUp(opts = {}) {
     for (const key of storageIndex.unusedKeys(usedStorageKeys)) {
         console.warn(`  Warning: --storage ${key} matches no \`content: operator\` volume — ignored`);
     }
-    // 3. State: loaded at step 2a-bis, where the https-origin refusal reads it.
+    // 3. State: loaded ahead of step 2a, where the refusals read it.
     // 4. Ensure directories
     await ensureDirs(projectDir);
     // 5. Generate secrets
@@ -712,10 +800,17 @@ export async function launchUp(opts = {}) {
     // 7. Allocate ports
     const componentPorts = await allocatePorts(launch.components, launch.name, state.ports);
     state.ports = componentPorts;
+    // The key the printouts place a supplied publication URL on (§7, D-58
+    // rules 2 and 4), recorded so `status` places it without the Launchfile.
+    // `primary` is the declared primary as read before the refusals, so a
+    // refused one places the URL on no key rather than a sibling's (D-72).
+    state.primaryEndpoint = printedPrimaryEndpoint(launch, componentPorts, state.appUrl, primary);
     // 8. Build resolver context (including $app.* properties from D-33). A
     // satisfied `https-origin` registers `url` — the same string as `$app.url`
     // (D-60 rule 4) — so its set_env resolves like any provisioned resource's.
-    const context = resolverContextFor(launch, resourceMap, state);
+    // `primary` is the declared primary as read before the refusals, so a
+    // refused one resolves the empty address rather than a sibling's (D-72).
+    const context = resolverContextFor(launch, resourceMap, state, primary);
     // `$app.endpoints.<name>.*` resolves "" here (D-63 rule 4, #294). Said
     // once per `up`, and only when the file asks, so the empty value is not a
     // silent one (PROVIDERS.md §10 item 8).
@@ -803,25 +898,20 @@ export async function launchUp(opts = {}) {
     await saveState(projectDir, state);
     if (opts.dryRun) {
         console.log("\n[dry-run] Would now run build, release, and start commands.");
-        printSummary(launch, componentPorts, resourceMap);
+        printSummary(launch.name, componentPorts, state, "would be reachable at");
         return;
     }
-    // 14. Run source-mode prepare \u2014 `install ?? build` (D-38), on demand
+    // 14. Run source-mode prepare \u2014 `install ?? build` (D-38), on demand.
+    // `--no-build` stays the explicit opt-out; it records nothing, since nothing
+    // ran, so a later `up` without it still prepares.
     if (!opts.noBuild) {
-        for (const [name, component] of Object.entries(launch.components)) {
-            const prepare = resolveSourcePrepareCommand(component);
-            const cmd = prepare?.command ?? pm?.installCommand;
-            if (cmd) {
-                console.log(`  \u2193 Preparing${componentNames.length > 1 ? ` [${name}]` : ""}...`);
-                await shellScript(cmd, {
-                    cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
-                    env: allEnvs[name],
-                    // Installs/compiles routinely exceed the 2-minute shell default;
-                    // honor a declared timeout, else allow 10 minutes.
-                    timeout: declaredTimeout(prepare?.timeout, `prepare [${name}]`) ?? 600_000,
-                });
-            }
-        }
+        await runSourcePrepare(launch, {
+            projectDir,
+            state,
+            envs: allEnvs,
+            fallbackCommand: pm?.installCommand,
+            labelComponents: componentNames.length > 1,
+        });
     }
     // 15. Run release commands (migrations) \u2014 mode-invariant (D-38)
     for (const [name, component] of Object.entries(launch.components)) {
@@ -865,24 +955,79 @@ export async function launchUp(opts = {}) {
         await saveState(projectDir, finalState);
         process.exit(0);
     });
-    await pm2.startAll();
+    try {
+        await pm2.startAll();
+    }
+    catch (err) {
+        // A failed health gate fails the invocation with the `health` phase
+        // (SPEC.md § Failure semantics), the same record the docker provider
+        // raises: the CLI registers the deployment as unhealthy so `down`
+        // reaches the processes left running, and `diagnose` finds the record.
+        if (err instanceof HealthGateError) {
+            throw new LaunchError(buildLaunchErrorContext({
+                phase: "health",
+                provider: "macos-dev",
+                key: launch.name,
+                app: launch.name,
+                message: err.message,
+            }, redactSecrets));
+        }
+        throw err;
+    }
+    finally {
+        // Record spawned pids so `launch down` can stop them from another shell or
+        // after this foreground session ends (closes #49). Backward compatible: the
+        // field is optional and absent in pre-existing state files. Recorded on
+        // the failure path too: a component that never became healthy fails the
+        // invocation (SPEC.md § Failure semantics) but its process is left
+        // running, and `status`/`logs`/`down` must still reach it.
+        state.processes = pm2.getRecordedProcesses();
+        await saveState(projectDir, state);
+    }
     console.log("");
     console.log(`  \u2713 All components started`);
-    // Record spawned pids so `launch down` can stop them from another shell or
-    // after this foreground session ends (closes #49). Backward compatible: the
-    // field is optional and absent in pre-existing state files.
-    state.processes = pm2.getRecordedProcesses();
     // 17. Print summary
-    printSummary(launch, componentPorts, resourceMap);
+    printSummary(launch.name, componentPorts, state);
     printAtReports(atReports(launch, componentPorts, suppliedAppUrl));
-    // Save final state (now including recorded pids)
-    await saveState(projectDir, state);
 }
-function printSummary(launch, ports, _resources) {
+/**
+ * The address to print for one `ports` key — the single definition `up` and
+ * `status` share. The supplied publication URL on the primary endpoint's key,
+ * as stored (`normalizeAppUrl` ran when `up` recorded it; nothing runs again
+ * here); this provider's own `http://localhost:<port>` on every other key,
+ * and on every key when no URL is supplied — byte-identical to a run with
+ * none. `up` records `primaryEndpoint` only for an `http`/`https` primary or
+ * one a declared `https-origin` names, so a positional `ws`/`tcp`/`udp`/`grpc`
+ * primary keeps this provider's own form (§7, `printedPrimaryEndpoint`).
+ */
+export function componentAddress(key, port, publication) {
+    if (publication?.appUrl !== undefined &&
+        publication.primaryEndpoint !== undefined &&
+        key === publication.primaryEndpoint) {
+        return publication.appUrl;
+    }
+    return `http://localhost:${port}`;
+}
+/**
+ * The "<component> is running at …" lines `up` prints, one per `ports` key.
+ * `verb` is the phrase between the label and the address; a dry run passes
+ * "would be reachable at" because nothing has started.
+ * Pure, so the placement of the supplied URL is testable without a launch.
+ */
+export function summaryLines(appName, ports, publication, verb = "is running at") {
+    return Object.entries(ports).map(([name, port]) => {
+        const label = name === "default" ? appName : name;
+        return `  ${label} ${verb} ${componentAddress(name, port, publication)}`;
+    });
+}
+/** The "Components:" lines `status` prints, one per `ports` key. */
+export function statusLines(ports, publication) {
+    return Object.entries(ports).map(([name, port]) => `  ${name}: ${componentAddress(name, port, publication)}`);
+}
+function printSummary(appName, ports, publication, verb) {
     console.log("");
-    for (const [name, port] of Object.entries(ports)) {
-        const label = name === "default" ? launch.name : name;
-        console.log(`  ${label} is running at http://localhost:${port}`);
+    for (const line of summaryLines(appName, ports, publication, verb)) {
+        console.log(line);
     }
     console.log("\n  Press Ctrl+C to stop all processes.");
 }
@@ -957,8 +1102,8 @@ export async function launchStatus(opts = {}) {
     console.log(`Updated: ${state.updatedAt}`);
     if (Object.keys(state.ports).length > 0) {
         console.log("\nComponents:");
-        for (const [name, port] of Object.entries(state.ports)) {
-            console.log(`  ${name}: http://localhost:${port}`);
+        for (const line of statusLines(state.ports, state)) {
+            console.log(line);
         }
     }
     if (Object.keys(state.resources).length > 0) {

package/dist/redact.js

@@ -73,7 +73,19 @@ export function clearRegisteredSecrets() {
 // `scheme://user:password@host` — the password group is everything between the
 // first `:` after the userinfo and the `@`. Userinfo cannot contain `/`, `@`,
 // or whitespace, which bounds the match to a single URL.
-const CREDENTIAL_URL = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/:@]+:)([^\s/@]+)(@)/g;
+//
+// The scheme repetition is bounded rather than `*`: unbounded, every starting
+// offset in a long run of scheme-legal characters rescans that whole run
+// looking for `://`, which is quadratic in the input and lets a log line DoS
+// the redactor that is supposed to protect it (CWE-1333).
+//
+// The bound excludes no URL, and not because schemes are short — RFC 3986 sets
+// no ceiling, and `microsoft.windows.camera.multipicker` is 36 characters. It
+// is because the pattern is unanchored: against a longer scheme the match
+// simply starts further into it and the password still redacts. Raising the
+// bound to "fit the longest scheme" would restore the quadratic scan for no
+// gain.
+const CREDENTIAL_URL = /([a-zA-Z][a-zA-Z0-9+.-]{0,31}:\/\/[^\s/:@]+:)([^\s/@]+)(@)/g;
 /**
  * Scrub registered secrets and URL-embedded credentials out of `text`.
  *

package/dist/shell.js

@@ -12,7 +12,7 @@
  *   own app (`commands:`, `health:`, `release:`), where shell syntax is the
  *   documented contract. Never build one of these by interpolation.
  */
-import { exec as cpExec, execFile as cpExecFile, } from "node:child_process";
+import { execFile as cpExecFile, } from "node:child_process";
 import { redactSecrets } from "./redact.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_BUFFER = 10 * 1024 * 1024;
@@ -35,11 +35,10 @@ function failure(display, result) {
     return Object.assign(new Error(`Command failed: ${redactSecrets(display)}\n${redactSecrets(result.stderr)}`), { result });
 }
 /**
- * Run a command with an argument array. Arguments reach the OS directly, so
- * they are never parsed as shell syntax.
+ * Spawn `cmd` with `args` via `execFile` and settle with a structured result.
+ * `display` is what the user sees echoed and what a failure message names.
  */
-export async function shell(cmd, args, opts = {}) {
-    const display = [cmd, ...args].join(" ");
+function run(cmd, args, display, opts) {
     if (!opts.silent) {
         // An argument can carry a resolved secret (a generated DB password, a
         // credential-bearing URL). Scrub before echo.
@@ -61,6 +60,13 @@ export async function shell(cmd, args, opts = {}) {
         });
     });
 }
+/**
+ * Run a command with an argument array. Arguments reach the OS directly, so
+ * they are never parsed as shell syntax.
+ */
+export async function shell(cmd, args, opts = {}) {
+    return run(cmd, args, [cmd, ...args].join(" "), opts);
+}
 /** Run a command with an argument array, return true if exit code is 0. */
 export async function shellOk(cmd, args, opts) {
     const result = await shell(cmd, args, {
@@ -79,23 +85,9 @@ export async function shellOk(cmd, args, opts) {
  * verbatim — building one by interpolating a value makes it injectable.
  */
 export async function shellScript(command, opts = {}) {
-    if (!opts.silent) {
-        console.log(`  $ ${redactSecrets(command)}`);
-    }
-    const execOpts = {
-        cwd: opts.cwd,
-        env: opts.env ? { ...process.env, ...opts.env } : undefined,
-        timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
-        maxBuffer: MAX_BUFFER,
-    };
-    return new Promise((resolve, reject) => {
-        cpExec(command, execOpts, (error, stdout, stderr) => {
-            const result = toResult(error, stdout, stderr);
-            if (error && !opts.allowFailure)
-                reject(failure(command, result));
-            else
-                resolve(result);
-        });
-    });
+    // The command string is one argv element of an explicit `/bin/sh -c`, the
+    // same shape `@launchfile/docker` uses. The shell parses the author's
+    // string; nothing this provider adds is ever spliced into it.
+    return run("/bin/sh", ["-c", command], command, opts);
 }
 //# sourceMappingURL=shell.js.map

package/dist/state.d.ts

@@ -108,6 +108,32 @@ export interface LaunchState {
      * answers.
      */
     appUrl?: string;
+    /**
+     * The `ports` key — this provider allocates one port per component, so a
+     * component name — of the app's primary endpoint, the one `$app.*` reads,
+     * when a declared `https-origin` names that endpoint (any protocol, D-60
+     * rule 4) or its effective listener is `http` or `https`; absent for a
+     * positional `ws`/`tcp`/`udp`/`grpc` primary (§7, D-58 rule 2). See
+     * `printedPrimaryEndpoint`. Recorded at `up` beside `appUrl`
+     * so `status`, which never reads the Launchfile, prints the supplied URL on
+     * that one key and no other (D-58 rule 4). Optional for backward
+     * compatibility: a state file without it prints this provider's own address
+     * on every key.
+     */
+    primaryEndpoint?: string;
+    /**
+     * Fingerprint of the prepare inputs (`install ?? build` command plus the
+     * dependency manifests and lockfiles in its working directory) at the last
+     * successful prepare, keyed by component name. It is what makes prepare run
+     * on demand rather than on every `up` (D-38): a component whose current
+     * fingerprint matches its recorded one has nothing to install.
+     *
+     * An entry is written only after its command exits zero, so a failed prepare
+     * is retried on the next `up`. Optional for backward compatibility: a state
+     * file written before this existed has no entries, so the next `up` prepares
+     * every component once and records them.
+     */
+    prepared?: Record<string, string>;
 }
 export declare function hashLaunchfile(content: string): string;
 /** Load state from disk, or return null if none exists */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchfile/macos-dev",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "macOS dev provider for Launchfile — run apps locally via brew services and native runtimes",
   "os": [
     "darwin"
@@ -36,14 +36,15 @@
     "directory": "providers/macos-dev"
   },
   "dependencies": {
-    "@launchfile/sdk": "^0.12.0",
+    "@launchfile/sdk": "^0.14.0",
     "semver": "^7.7.4"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
-    "@types/bun": "^1.3.11",
+    "@biomejs/biome": "^2.5.15",
+    "@launchfile/docker": "^0.14.0",
+    "@types/bun": "^1.4.2",
     "@types/semver": "^7.7.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.3"
+    "vitest": "^5.0.3"
   }
 }