@launchfile/macos-dev 0.12.0 → 0.13.0

package/dist/bootstrap.d.ts

@@ -29,6 +29,13 @@ export declare const BOOTSTRAP_SHELL = "/bin/sh";
  */
 export interface BootstrapResult {
     component: string;
+    /**
+     * The resolved command in redacted form — never the pre-scrub string
+     * (D-18, D-71). `$secrets.*` and `$<resource>.password` resolve to live
+     * credentials before the command runs, and this type is a public export:
+     * a consumer in another process holds an empty redaction registry and
+     * cannot scrub what it is handed.
+     */
     command: string;
     ok: boolean;
     exitCode: number;

package/dist/bootstrap.js

@@ -32,9 +32,33 @@ export const BOOTSTRAP_SHELL = "/bin/sh";
  * CLI tools that detect a TTY will emit color codes that would otherwise
  * break simple patterns like `https?://\S+`.
  */
+// CSI, OSC, and the single-character escapes a terminal writes into captured
+// output. Every repetition is bounded, and the OSC payload stops at ESC.
+//
+// Unbounded, the OSC branch `\][^\u0007]*` is quadratic: each `ESC ]` in the
+// input rescans the whole remainder looking for a BEL that a hostile log line
+// never supplies, and bootstrap stdout is exactly where a hostile log line
+// arrives (CWE-1333). Through `extractCaptures`, 40 000 `ESC ]` pairs took
+// 366 ms under Bun 1.4.0 on an Apple-silicon Mac; bounded they take 0 ms.
+//
+// Excluding ESC from the payload also closes a swallow: ECMA-48 ends an OSC
+// string at BEL or ST (`ESC \`), and nothing between may contain ESC. The
+// unbounded class ran straight past an ST into the next OSC, so an OSC 8
+// hyperlink lost its link text — and with it the URL a `capture` pattern is
+// looking for.
+//
+// The parameter bound is 64 because 32 is not enough: one SGR that sets a
+// truecolor foreground and background together —
+// `ESC [ 38;2;255;255;255;48;2;240;240;240 m` — carries 33 parameter bytes, and a
+// theme-aware CLI emits it. Past the bound the sequence is not stripped at all
+// and its bytes reach the string `extractCaptures` matches against. ECMA-48
+// permits only a few intermediates; an OSC 8 hyperlink URL is the longest
+// realistic payload and sits far under 1024.
+const ANSI_ESCAPE = 
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI match
+/\u001B(?:\[[0-9;?]{0,64}[ -/]{0,8}[@-~]|\][^\u0007\u001B]{0,1024}(?:\u0007|\u001B\\)|[@-Z\\-_])/g;
 function stripAnsi(s) {
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI match
-    return s.replace(/\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07/g, "");
+    return s.replace(ANSI_ESCAPE, "");
 }
 /**
  * Apply a set of capture patterns to a command's stdout. If a pattern has
@@ -209,7 +233,7 @@ export async function launchBootstrap(opts = {}) {
             console.error(`  \u2717 Bootstrap [${name}]: ${item.error}`);
             results.push({
                 component: name,
-                command: item.command,
+                command: redactSecrets(item.command),
                 ok: false,
                 exitCode: 1,
                 captures: {},
@@ -260,7 +284,7 @@ export async function launchBootstrap(opts = {}) {
         }
         results.push({
             component: name,
-            command: item.command,
+            command: redactSecrets(item.command),
             ok: exitCode === 0,
             exitCode,
             captures,

package/dist/cli-args.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Argument parsing for this provider's own CLI entry point.
+ *
+ * Split from `cli.ts` so the rules are testable: importing `cli.ts` runs
+ * `main()`, and its helpers read a module-level `args`. This package has no
+ * dependency edge to `packages/launchfile`, so the unified CLI's parser cannot
+ * be imported — these rules are deliberately duplicated and must stay in step
+ * with `packages/launchfile/src/cli-args.ts`, or one Launchfile yields two
+ * running topologies depending on which entry point ran it (P-5, D-41).
+ */
+/**
+ * The D-41 component selector, or undefined when no name is given — an absent
+ * flag and an empty value both mean every component. The comma-separated and
+ * repeatable forms compose; blanks and duplicates are dropped.
+ */
+export declare function parseComponentsFlag(args: readonly string[]): string[] | undefined;
+/**
+ * The refusal a verb owes when the selector appears on it but nothing reads
+ * the value. `down` and `status` act on the whole deployment and have no set
+ * to narrow, so accepting the flag and ignoring it would stop or report every
+ * component while the operator named one.
+ */
+export declare function selectorRefusal(args: readonly string[], verb: string, action: string): readonly [string, string] | undefined;
+//# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.js

@@ -0,0 +1,51 @@
+/**
+ * Argument parsing for this provider's own CLI entry point.
+ *
+ * Split from `cli.ts` so the rules are testable: importing `cli.ts` runs
+ * `main()`, and its helpers read a module-level `args`. This package has no
+ * dependency edge to `packages/launchfile`, so the unified CLI's parser cannot
+ * be imported — these rules are deliberately duplicated and must stay in step
+ * with `packages/launchfile/src/cli-args.ts`, or one Launchfile yields two
+ * running topologies depending on which entry point ran it (P-5, D-41).
+ */
+/**
+ * The D-41 component selector, or undefined when no name is given — an absent
+ * flag and an empty value both mean every component. The comma-separated and
+ * repeatable forms compose; blanks and duplicates are dropped.
+ */
+export function parseComponentsFlag(args) {
+    const names = [];
+    const inlinePrefix = "--components=";
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        let raw;
+        if (arg === "--components")
+            raw = args[i + 1];
+        else if (arg?.startsWith(inlinePrefix))
+            raw = arg.slice(inlinePrefix.length);
+        if (raw === undefined)
+            continue;
+        for (const part of raw.split(",")) {
+            const name = part.trim();
+            if (name.length > 0 && !names.includes(name))
+                names.push(name);
+        }
+    }
+    return names.length > 0 ? names : undefined;
+}
+/**
+ * The refusal a verb owes when the selector appears on it but nothing reads
+ * the value. `down` and `status` act on the whole deployment and have no set
+ * to narrow, so accepting the flag and ignoring it would stop or report every
+ * component while the operator named one.
+ */
+export function selectorRefusal(args, verb, action) {
+    const present = args.some((arg) => arg === "--components" || arg.startsWith("--components="));
+    if (!present)
+        return undefined;
+    return [
+        `--components selects which components \`up\` starts; \`${verb}\` ${action}.`,
+        `Run \`${verb}\` with no selector.`,
+    ];
+}
+//# sourceMappingURL=cli-args.js.map

package/dist/cli.d.ts

@@ -3,7 +3,7 @@
  * CLI entry point for the macOS dev provider.
  *
  * Usage:
- *   launch up [--with-optional] [--no-build] [--dry-run]
+ *   launch up [--with-optional] [--no-build] [--dry-run] [--components <a,b>]
  *   launch down [--destroy]
  *   launch status
  *   launch env [component]

package/dist/cli.js

@@ -3,12 +3,13 @@
  * CLI entry point for the macOS dev provider.
  *
  * Usage:
- *   launch up [--with-optional] [--no-build] [--dry-run]
+ *   launch up [--with-optional] [--no-build] [--dry-run] [--components <a,b>]
  *   launch down [--destroy]
  *   launch status
  *   launch env [component]
  */
 import { launchUp, launchDown, launchStatus, launchEnv } from "./provider.js";
+import { parseComponentsFlag, selectorRefusal } from "./cli-args.js";
 const args = process.argv.slice(2);
 const command = args[0];
 function hasFlag(flag) {
@@ -17,6 +18,19 @@ function hasFlag(flag) {
 function getArg(index) {
     return args[index];
 }
+/** The D-41 component selector for this invocation. */
+function componentsFlag() {
+    return parseComponentsFlag(args);
+}
+/** Exit 1 when the selector reaches a verb that acts on the whole deployment. */
+function refuseSelector(verb, action) {
+    const lines = selectorRefusal(args, verb, action);
+    if (lines === undefined)
+        return;
+    for (const line of lines)
+        console.error(line);
+    process.exit(1);
+}
 async function main() {
     switch (command) {
         case "up":
@@ -25,14 +39,17 @@ async function main() {
                 noBuild: hasFlag("no-build"),
                 dryRun: hasFlag("dry-run"),
                 detach: hasFlag("detach"),
+                components: componentsFlag(),
             });
             break;
         case "down":
+            refuseSelector("down", "stops the whole deployment");
             await launchDown({
                 destroy: hasFlag("destroy"),
             });
             break;
         case "status":
+            refuseSelector("status", "reports the whole deployment");
             await launchStatus();
             break;
         case "env":
@@ -44,8 +61,10 @@ async function main() {
             console.log(`launch — macOS dev provider for Launchfile
 
 Usage:
-  launch up [--with-optional] [--no-build] [--dry-run]
+  launch up [--with-optional] [--no-build] [--dry-run] [--components <a,b>]
     Provision resources, install deps, and start the app.
+    --components starts only the named components plus their downward
+    dependency closure (D-41); omit it to start every component.
 
   launch down [--destroy]
     Stop processes. --destroy also drops databases and cleans up.

package/dist/env-writer.d.ts

@@ -5,6 +5,7 @@
  * then writes the results to .env files.
  */
 import { type AppEndpointProperties, type NormalizedComponent, type NormalizedLaunch, type ResolverContext, type Secret, type UnsuppliedRequiredEnv } from "@launchfile/sdk";
+import { type DeclaredPrimary } from "./https-origin.js";
 import type { ResourceProperties } from "./resources/types.js";
 import { type DbIndexes } from "./resources/uses.js";
 import { type LaunchState } from "./state.js";
@@ -21,6 +22,14 @@ export type { ResolverContext, UnsuppliedRequiredEnv };
  * Apps with no exposed component get `port: 0` and `url: ""` (and empty
  * authority/scheme/tls).
  *
+ * A declared primary whose component `up` refuses — a `requires:` entry the
+ * publication context does not satisfy — keeps its place and has no address:
+ * every property is `REFUSED_PRIMARY_ADDRESS` (D-72), never a surviving
+ * sibling's port and never the URL that failed to satisfy the entry. `up`
+ * passes `primary` as it read it before the refusal removed the component
+ * from `launch.components`; `env` and `bootstrap` read the file whole and let
+ * the default compute it, so the three answer alike.
+ *
  * With an `appUrl` — the orchestrator-supplied publication context (D-58) —
  * routing has moved upstream and the supplied URL answers instead, via the
  * SDK's `suppliedAppProperties`: the same derivation `@launchfile/docker` uses,
@@ -38,7 +47,39 @@ export type { ResolverContext, UnsuppliedRequiredEnv };
  * provider allocates one port per component, so the named endpoint's address
  * is its component's port.
  */
-export declare function computeAppProperties(launch: NormalizedLaunch, componentPorts: Record<string, number>, appUrl?: string): Record<string, string | number>;
+export declare function computeAppProperties(launch: NormalizedLaunch, componentPorts: Record<string, number>, appUrl?: string, primary?: DeclaredPrimary | undefined): Record<string, string | number>;
+/**
+ * The component whose port is the app's primary endpoint — the one `$app.*`
+ * reads and the one a supplied publication URL asserts (D-58 rule 4): the
+ * component that declares an `https-origin` entry (D-60 rule 3 — declaration
+ * fixes the primary, fulfilled or not), else the first component in
+ * declaration order that has an `exposed: true` provides entry and an
+ * allocated port. `undefined` when the app publishes nothing, and when the
+ * declared component has no allocated port (the answer is always a
+ * `componentPorts` key or nothing). `up` records
+ * the answer in state so `status`, which never reads the Launchfile, places
+ * the supplied URL on the same component.
+ */
+export declare function primaryComponent(launch: NormalizedLaunch, componentPorts: Record<string, number>, primary?: DeclaredPrimary | undefined): string | undefined;
+/**
+ * The `ports` key `up` and `status` print the supplied publication URL on
+ * (§7): the primary component, when a declared `https-origin` names its
+ * endpoint — that entry's `url` is the `https` origin for every listener it
+ * admits, `ws` and `grpc` included (D-60 rule 4) — or, with no such entry,
+ * when its first `exposed: true` entry's effective listener is `http` or
+ * `https`. `undefined` for a positional `ws`, `tcp`, `udp` or `grpc`
+ * primary: a supplied URL is an `http`/`https` address and asserts nothing
+ * about what those listeners speak (D-58 rule 2), so that key keeps this
+ * provider's own printed form while `$app.url` still reads the supplied URL.
+ * This provider activates no certificate, so the effective protocol is the
+ * declared one.
+ *
+ * `undefined` for a refused declared primary (D-72): it has no address and
+ * no `ports` key, and no surviving sibling takes its place. `up` passes
+ * `primary` as it read it before its refusals removed the component from
+ * `launch.components`, as for `computeAppProperties`.
+ */
+export declare function printedPrimaryEndpoint(launch: NormalizedLaunch, componentPorts: Record<string, number>, appUrl?: string, primary?: DeclaredPrimary | undefined): string | undefined;
 /**
  * `$app.endpoints.<name>.*` under this provider (D-63 rule 4): every
  * property of every named published endpoint resolves `""`. The allocator
@@ -101,9 +142,11 @@ export declare function resourceMapFromState(launch: NormalizedLaunch, state: La
  * inputs: the registered resources, the recorded ports and secrets, `$app.*`
  * from the recorded publication context (D-58) with a satisfied
  * `https-origin` wired to the same string (D-60 rule 4), and the declared
- * uses the resolver applies strictly.
+ * uses the resolver applies strictly. `primary` is the declared primary as
+ * `up` read it before its refusals; the other two verbs omit it and read the
+ * whole file.
  */
-export declare function resolverContextFor(launch: NormalizedLaunch, resourceMap: Record<string, ResourceProperties>, state: LaunchState): ResolverContext;
+export declare function resolverContextFor(launch: NormalizedLaunch, resourceMap: Record<string, ResourceProperties>, state: LaunchState, primary?: DeclaredPrimary): ResolverContext;
 /**
  * The resolved environment for one component, plus what the file did not supply.
  */

package/dist/env-writer.js

@@ -6,8 +6,8 @@
  */
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { deriveAppUrlProperties, endpointProperties, resolveExpression, isExpression, parseUseKey, suppliedAppProperties, UNPUBLISHED_APP_ENDPOINT, unsuppliedRequiredEnv, useKeys, } from "@launchfile/sdk";
-import { declaredPrimaryComponent, wireHttpsOrigins } from "./https-origin.js";
+import { deriveAppUrlProperties, effectiveListener, endpointProperties, resolveExpression, isExpression, parseUseKey, suppliedAppProperties, UNPUBLISHED_APP_ENDPOINT, unsuppliedRequiredEnv, useKeys, } from "@launchfile/sdk";
+import { declaredPrimary, REFUSED_PRIMARY_ADDRESS, wireHttpsOrigins, } from "./https-origin.js";
 import { getProvisioner } from "./resources/index.js";
 import { coveredUses, namedDatabases, withCoveredUses } from "./resources/uses.js";
 import { generateValue } from "./secret-generator.js";
@@ -24,6 +24,14 @@ import { recordedDbIndexes } from "./state.js";
  * Apps with no exposed component get `port: 0` and `url: ""` (and empty
  * authority/scheme/tls).
  *
+ * A declared primary whose component `up` refuses — a `requires:` entry the
+ * publication context does not satisfy — keeps its place and has no address:
+ * every property is `REFUSED_PRIMARY_ADDRESS` (D-72), never a surviving
+ * sibling's port and never the URL that failed to satisfy the entry. `up`
+ * passes `primary` as it read it before the refusal removed the component
+ * from `launch.components`; `env` and `bootstrap` read the file whole and let
+ * the default compute it, so the three answer alike.
+ *
  * With an `appUrl` — the orchestrator-supplied publication context (D-58) —
  * routing has moved upstream and the supplied URL answers instead, via the
  * SDK's `suppliedAppProperties`: the same derivation `@launchfile/docker` uses,
@@ -41,28 +49,13 @@ import { recordedDbIndexes } from "./state.js";
  * provider allocates one port per component, so the named endpoint's address
  * is its component's port.
  */
-export function computeAppProperties(launch, componentPorts, appUrl) {
+export function computeAppProperties(launch, componentPorts, appUrl, primary = declaredPrimary(launch, appUrl)) {
+    if (primary?.refused)
+        return { name: launch.name, ...REFUSED_PRIMARY_ADDRESS };
     if (appUrl !== undefined)
         return suppliedAppProperties(launch.name, appUrl);
-    let primaryPort = 0;
-    const declared = declaredPrimaryComponent(launch);
-    if (declared !== undefined) {
-        // A declared `https-origin` names the primary explicitly, so the
-        // positional answer below does not run — the point of D-60 rule 3. The
-        // SDK requires the named endpoint to be `exposed: true` on this component.
-        primaryPort = componentPorts[declared] ?? 0;
-    }
-    else {
-        for (const [name, component] of Object.entries(launch.components)) {
-            // Only endpoints explicitly marked `exposed: true` are reachable from
-            // outside the host (D-27), so only they can be the app's public address.
-            const hasExposed = component.provides?.some((p) => p.exposed === true) ?? false;
-            if (hasExposed && componentPorts[name]) {
-                primaryPort = componentPorts[name];
-                break;
-            }
-        }
-    }
+    const component = primaryComponent(launch, componentPorts, primary);
+    const primaryPort = component === undefined ? 0 : (componentPorts[component] ?? 0);
     const url = primaryPort > 0 ? `http://localhost:${primaryPort}` : "";
     return {
         name: launch.name,
@@ -72,6 +65,69 @@ export function computeAppProperties(launch, componentPorts, appUrl) {
         ...deriveAppUrlProperties(url),
     };
 }
+/**
+ * The component whose port is the app's primary endpoint — the one `$app.*`
+ * reads and the one a supplied publication URL asserts (D-58 rule 4): the
+ * component that declares an `https-origin` entry (D-60 rule 3 — declaration
+ * fixes the primary, fulfilled or not), else the first component in
+ * declaration order that has an `exposed: true` provides entry and an
+ * allocated port. `undefined` when the app publishes nothing, and when the
+ * declared component has no allocated port (the answer is always a
+ * `componentPorts` key or nothing). `up` records
+ * the answer in state so `status`, which never reads the Launchfile, places
+ * the supplied URL on the same component.
+ */
+export function primaryComponent(launch, componentPorts, primary = declaredPrimary(launch)) {
+    if (primary !== undefined) {
+        // A declared `https-origin` names the primary explicitly, so the
+        // positional answer below does not run — the point of D-60 rule 3. The
+        // SDK requires the named endpoint to be `exposed: true` on this component.
+        // Without an allocated port it is still the primary, so the search stays
+        // off — but it is not a `ports` key, and `primaryEndpoint` must name one
+        // or nothing, so answer `undefined` rather than a key `state.ports` lacks.
+        return componentPorts[primary.component] ? primary.component : undefined;
+    }
+    for (const [name, component] of Object.entries(launch.components)) {
+        // Only endpoints explicitly marked `exposed: true` are reachable from
+        // outside the host (D-27), so only they can be the app's public address.
+        const hasExposed = component.provides?.some((p) => p.exposed === true) ?? false;
+        if (hasExposed && componentPorts[name])
+            return name;
+    }
+    return undefined;
+}
+/**
+ * The `ports` key `up` and `status` print the supplied publication URL on
+ * (§7): the primary component, when a declared `https-origin` names its
+ * endpoint — that entry's `url` is the `https` origin for every listener it
+ * admits, `ws` and `grpc` included (D-60 rule 4) — or, with no such entry,
+ * when its first `exposed: true` entry's effective listener is `http` or
+ * `https`. `undefined` for a positional `ws`, `tcp`, `udp` or `grpc`
+ * primary: a supplied URL is an `http`/`https` address and asserts nothing
+ * about what those listeners speak (D-58 rule 2), so that key keeps this
+ * provider's own printed form while `$app.url` still reads the supplied URL.
+ * This provider activates no certificate, so the effective protocol is the
+ * declared one.
+ *
+ * `undefined` for a refused declared primary (D-72): it has no address and
+ * no `ports` key, and no surviving sibling takes its place. `up` passes
+ * `primary` as it read it before its refusals removed the component from
+ * `launch.components`, as for `computeAppProperties`.
+ */
+export function printedPrimaryEndpoint(launch, componentPorts, appUrl, primary = declaredPrimary(launch, appUrl)) {
+    if (primary?.refused)
+        return undefined;
+    const component = primaryComponent(launch, componentPorts, primary);
+    if (component === undefined)
+        return undefined;
+    if (primary !== undefined)
+        return component;
+    const entry = launch.components[component]?.provides?.find((p) => p.exposed === true);
+    if (entry === undefined)
+        return undefined;
+    const { protocol } = effectiveListener(entry);
+    return protocol === "http" || protocol === "https" ? component : undefined;
+}
 /**
  * `$app.endpoints.<name>.*` under this provider (D-63 rule 4): every
  * property of every named published endpoint resolves `""`. The allocator
@@ -215,10 +271,12 @@ export async function resourceMapFromState(launch, state, projectDir) {
  * inputs: the registered resources, the recorded ports and secrets, `$app.*`
  * from the recorded publication context (D-58) with a satisfied
  * `https-origin` wired to the same string (D-60 rule 4), and the declared
- * uses the resolver applies strictly.
+ * uses the resolver applies strictly. `primary` is the declared primary as
+ * `up` read it before its refusals; the other two verbs omit it and read the
+ * whole file.
  */
-export function resolverContextFor(launch, resourceMap, state) {
-    const appProperties = computeAppProperties(launch, state.ports, state.appUrl);
+export function resolverContextFor(launch, resourceMap, state, primary) {
+    const appProperties = computeAppProperties(launch, state.ports, state.appUrl, primary);
     wireHttpsOrigins(launch, resourceMap, state.appUrl);
     return buildResolverContext(resourceMap, state.ports, state.secrets, appProperties, computeAppEndpoints(launch), declaredUses(launch), launch.components);
 }

package/dist/health.d.ts

@@ -10,9 +10,30 @@ import { type NormalizedHealth } from "@launchfile/sdk";
  * `interval: "1h"` became a zero-length poll that could never pass.
  */
 export declare function parseDuration(duration: string): number;
+/**
+ * Whether a check can run without a port: only a `command` check can. A
+ * `path` check and the no-check fallback both poll `http://localhost:<port>`.
+ */
+export declare function healthCheckNeedsPort(health: NormalizedHealth): boolean;
+/**
+ * What a check polls, for the failure message: the operator reading
+ * "did not become healthy" needs to know which probe was asked.
+ */
+export declare function describeHealthCheck(health: NormalizedHealth, port: number | undefined): string;
+/**
+ * How long a check gets before the component counts as never healthy. A
+ * declared `retries` is the file's own window — that many consecutive failures,
+ * each costing up to one `timeout` plus one `interval` (SPEC.md § health, the
+ * window docker's compose healthcheck gives it). The provider default fills in
+ * only when the file declares no `retries`: PROVIDERS.md §10 rule 10 keeps
+ * defaults for absent values, never over declared ones. `start_period` is
+ * waited in full before the window opens and is not part of it.
+ */
+export declare function healthBudgetMs(health: NormalizedHealth, fallbackMs: number): number;
 /**
  * Wait for a component to become healthy.
- * Returns true if healthy, false if timed out.
+ * Returns true if healthy, false if timed out. `overallTimeout` is the polling
+ * window after `start_period`; callers derive it with `healthBudgetMs`.
  */
 export declare function waitForHealthy(name: string, health: NormalizedHealth, port: number, overallTimeout?: number): Promise<boolean>;
 //# sourceMappingURL=health.d.ts.map

package/dist/health.js

@@ -2,6 +2,7 @@
  * Health check polling for components.
  */
 import { parseDurationMs } from "@launchfile/sdk";
+import { redactSecrets } from "./redact.js";
 import { shellScript } from "./shell.js";
 /**
  * Parse a health duration against the ratified grammar (D-48). Throws on an
@@ -13,9 +14,43 @@ import { shellScript } from "./shell.js";
 export function parseDuration(duration) {
     return parseDurationMs(duration);
 }
+/**
+ * Whether a check can run without a port: only a `command` check can. A
+ * `path` check and the no-check fallback both poll `http://localhost:<port>`.
+ */
+export function healthCheckNeedsPort(health) {
+    return !health.command;
+}
+/**
+ * What a check polls, for the failure message: the operator reading
+ * "did not become healthy" needs to know which probe was asked.
+ */
+export function describeHealthCheck(health, port) {
+    if (health.command)
+        return `command \`${redactSecrets(health.command)}\``;
+    const host = port === undefined ? "localhost:<unallocated>" : `localhost:${port}`;
+    return `GET http://${host}${health.path ?? "/"}`;
+}
+/**
+ * How long a check gets before the component counts as never healthy. A
+ * declared `retries` is the file's own window — that many consecutive failures,
+ * each costing up to one `timeout` plus one `interval` (SPEC.md § health, the
+ * window docker's compose healthcheck gives it). The provider default fills in
+ * only when the file declares no `retries`: PROVIDERS.md §10 rule 10 keeps
+ * defaults for absent values, never over declared ones. `start_period` is
+ * waited in full before the window opens and is not part of it.
+ */
+export function healthBudgetMs(health, fallbackMs) {
+    if (health.retries === undefined)
+        return fallbackMs;
+    const interval = parseDuration(health.interval ?? "3s");
+    const checkTimeout = parseDuration(health.timeout ?? "5s");
+    return health.retries * (interval + checkTimeout);
+}
 /**
  * Wait for a component to become healthy.
- * Returns true if healthy, false if timed out.
+ * Returns true if healthy, false if timed out. `overallTimeout` is the polling
+ * window after `start_period`; callers derive it with `healthBudgetMs`.
  */
 export async function waitForHealthy(name, health, port, overallTimeout = 60_000) {
     const startPeriod = parseDuration(health.start_period ?? "0s");

package/dist/https-origin.d.ts

@@ -10,7 +10,7 @@
  * D-56 rule 3 stands — the provider does not verify the origin exists or is
  * ready.
  */
-import { type NormalizedLaunch, type NormalizedRequirement } from "@launchfile/sdk";
+import { type AppEndpointProperties, type NormalizedLaunch, type NormalizedRequirement } from "@launchfile/sdk";
 import type { ResourceProperties } from "./resources/types.js";
 /** The backing-service type that declares the app's public HTTPS origin (D-60). */
 export declare const HTTPS_ORIGIN = "https-origin";
@@ -21,6 +21,12 @@ export declare const HTTPS_ORIGIN = "https-origin";
  * `launchUp` records it.
  */
 export declare function httpsOriginSatisfied(appUrl: string | undefined): boolean;
+/**
+ * The uses an `https-origin` entry declares that this provider cannot cover,
+ * spelled as the file spells them. Asked of the use registry, never assumed:
+ * a use registered for the type later is covered with no change here.
+ */
+export declare function uncoveredOriginUses(entry: NormalizedRequirement): string[];
 /**
  * Why one `https-origin` entry is not satisfied, for a refusal or a degraded
  * note — the same two reasons `@launchfile/docker` gives, so one Launchfile
@@ -28,21 +34,51 @@ export declare function httpsOriginSatisfied(appUrl: string | undefined): boolea
  */
 export declare function httpsOriginShortfall(entry: NormalizedRequirement, appUrl: string | undefined): string;
 /**
- * The component an `https-origin` entry sits on, when the file declares one
+ * The `$app.*` address of a primary whose component is refused (D-72):
+ * every field `""` — the answer D-63 rule 4 gives an endpoint the provider
+ * publishes no address for — with `tls` reading `false`, as D-63 rule 3 has
+ * a listener with no origin read it, so a literal on/off flag
+ * (`USE_SSL: $app.tls`) still receives a boolean. The same object
+ * `@launchfile/docker` resolves (P-5).
+ */
+export declare const REFUSED_PRIMARY_ADDRESS: Readonly<AppEndpointProperties>;
+/** The primary an `https-origin` entry declares (D-60 rule 3). */
+export interface DeclaredPrimary {
+    /** The component the entry sits on — the one that owns the named endpoint. */
+    component: string;
+    /**
+     * The entry is `requires:` and the publication context does not satisfy
+     * it, so `up` refuses the component (D-60 rule 5). It stays the primary; it
+     * has no address (D-72).
+     */
+    refused: boolean;
+}
+/**
+ * The primary an `https-origin` entry declares, when the file declares one
  * (D-60 rule 3), else `undefined`. **Declaration** fixes the primary, not
  * fulfillment: a `supports:` entry this provider leaves unsatisfied still
- * names it, so `$app.*` does not change value with the provider's capability.
- * The SDK caps the app at one such entry and requires it to sit on the
- * component that owns the named endpoint, so the first match is the only one.
+ * names it, and so does a `requires:` entry whose component this provider
+ * refuses — `refused` says which, and `computeAppProperties` then resolves
+ * the empty address rather than a surviving sibling's (D-72). Either way
+ * `$app.*` does not move with the provider's capability. The SDK caps the app
+ * at one such entry and requires it to sit on the component that owns the
+ * named endpoint, so the first match is the only one.
+ *
+ * `up` reads this before its refusals remove anything from
+ * `launch.components`; `env` and `bootstrap` read the file whole. `appUrl` is
+ * the effective publication context — supplied or recorded — normalized.
  */
-export declare function declaredPrimaryComponent(launch: NormalizedLaunch): string | undefined;
+export declare function declaredPrimary(launch: NormalizedLaunch, appUrl?: string): DeclaredPrimary | undefined;
 /**
  * Register every satisfied `https-origin` entry as a resource so its `set_env`
  * resolves. One registered property, `url` (D-60 rule 4), holding the same
- * string as `$app.url`. Mutates `resourceMap`; a no-op when the recorded
- * publication URL does not satisfy the type, so an unsatisfied entry's
- * `set_env` stays absent (never `""`) exactly as for any other resource this
- * provider did not provision.
+ * string as `$app.url`, plus the properties of each declared use. Mutates
+ * `resourceMap`; a no-op when the recorded publication URL does not satisfy
+ * the type, so an unsatisfied entry's `set_env` stays absent (never `""`)
+ * exactly as for any other resource this provider did not provision. An entry
+ * declaring a use this provider cannot cover is unsatisfied the same way
+ * (D-65): a `supports:` entry runs degraded, and a `requires:` one refused its
+ * component before launch.
  */
 export declare function wireHttpsOrigins(launch: NormalizedLaunch, resourceMap: Record<string, ResourceProperties>, appUrl: string | undefined): void;
 //# sourceMappingURL=https-origin.d.ts.map