@launchfile/macos-dev 0.8.0 → 0.10.0

package/dist/bootstrap.d.ts

@@ -101,6 +101,13 @@ export type BootstrapExec = (cmd: string, args: string[], opts: {
 export declare function launchBootstrap(opts?: {
     component?: string;
     projectDir?: string;
+    /**
+     * Print sensitive captures instead of masking them — the operator's
+     * explicit act on the invoking command (`launchfile bootstrap
+     * --reveal`). Display only: the values are registered with the
+     * redactor either way.
+     */
+    reveal?: boolean;
     exec?: BootstrapExec;
 }): Promise<BootstrapResult[]>;
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.js

@@ -16,11 +16,10 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
-import { parseDurationMs, readLaunch, resolveExpression, } from "@launchfile/sdk";
+import { formatCaptures, parseDurationMs, readLaunch, resolveExpression, sensitiveCaptureValues, } 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";
+import { resolveComponentEnv, resolveGenerators, resolverContextFor, resourceMapFromState, } from "./env-writer.js";
+import { redactSecrets, registerDeclaredSecret } from "./redact.js";
 /** Default budget for a bootstrap command when no `timeout` is declared. */
 export const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 120_000;
 /**
@@ -184,29 +183,20 @@ const defaultExec = (cmd, args, opts) => new Promise((resolveP) => {
  */
 export async function launchBootstrap(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
+    const reveal = opts.reveal === true;
     const launchfileContent = await readFile(join(projectDir, "Launchfile"), "utf8");
     const launch = readLaunch(launchfileContent);
     const state = await loadState(projectDir);
     if (!state) {
         throw new Error("No active launch state. Run `launch up` first.");
     }
-    // Rebuild resource map from state so the resolver context has real
-    // values at invocation time (same pattern as launchEnv). This calls
-    // provisioner.provision() on already-provisioned resources to retrieve
-    // their current property values — relies on every provisioner being
-    // idempotent: re-running provision() must not corrupt state or
-    // re-create the resource. All current provisioners satisfy this; new
-    // provisioners must as well.
-    const resourceMap = {};
-    for (const [name, res] of Object.entries(state.resources)) {
-        const provisioner = getProvisioner(res.type);
-        if (provisioner) {
-            const result = await provisioner.provision({ type: res.type, name: res.name }, { appName: state.appName, projectDir }, res);
-            resourceMap[name] = result.properties;
-        }
-    }
-    const appProperties = computeAppProperties(launch, state.ports);
-    const context = buildResolverContext(resourceMap, state.ports, state.secrets, appProperties);
+    // A bootstrap command reads the same values the app's env was written
+    // with: the resources registered as `up` registered them — declared uses
+    // included — and `$app.*` from the publication context the last `up`
+    // recorded (D-58), not this provider's localhost answer under an upstream
+    // proxy.
+    const resourceMap = await resourceMapFromState(launch, state, projectDir);
+    const context = resolverContextFor(launch, resourceMap, state);
     const exec = opts.exec ?? defaultExec;
     const plan = planBootstraps(launch, context, { component: opts.component });
     const results = [];
@@ -259,26 +249,31 @@ export async function launchBootstrap(opts = {}) {
             env,
             timeoutMs: item.timeoutMs,
         });
+        const captureMeta = item.capture ?? {};
         const captures = item.capture ? extractCaptures(stdout, item.capture) : {};
+        // A `sensitive: true` capture is a declared secret (D-18): it registers
+        // before any result or printed line is built, so the value can leak
+        // through neither (CWE-532). `--reveal` changes what the display loop
+        // below prints, never this.
+        for (const value of sensitiveCaptureValues(captures, captureMeta)) {
+            registerDeclaredSecret(value);
+        }
         results.push({
             component: name,
             command: item.command,
             ok: exitCode === 0,
             exitCode,
             captures,
-            captureMeta: item.capture ?? {},
+            captureMeta,
             stdout,
             stderr,
         });
         // 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 = item.capture?.[key];
-                const displayValue = meta?.sensitive ? "***" : value;
-                const desc = meta?.description ? ` — ${meta.description}` : "";
-                console.log(`    ${key}: ${displayValue}${desc}`);
-            }
+        const lines = formatCaptures(captures, captureMeta, reveal);
+        if (lines.length > 0) {
+            console.log("");
+            for (const line of lines)
+                console.log(line);
         }
         if (exitCode !== 0) {
             console.error(`  \u2717 Bootstrap [${name}] failed with exit code ${exitCode}`);

package/dist/env-writer.d.ts

@@ -4,28 +4,101 @@
  * 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, type UnsuppliedRequiredEnv } from "@launchfile/sdk";
+import { type AppEndpointProperties, type NormalizedComponent, type NormalizedLaunch, type ResolverContext, type Secret, type UnsuppliedRequiredEnv } from "@launchfile/sdk";
 import type { ResourceProperties } from "./resources/types.js";
+import { type DbIndexes } from "./resources/uses.js";
+import { type LaunchState } from "./state.js";
 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
- * (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.
+ * macos-dev provider.
+ *
+ * With no `appUrl`, this provider's own routing strategy answers: the app's
+ * "primary" port is the port of 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 at least one
+ * `exposed: true` provides entry, and `http://localhost:<port>` is the address.
  * Apps with no exposed component get `port: 0` and `url: ""` (and empty
  * authority/scheme/tls).
  *
+ * 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,
+ * so one Launchfile behind one proxy resolves identical `$app.*` under either
+ * provider (P-5). The allocated local ports stay orthogonal — still bound, just
+ * not the address anyone reaches the app at.
+ *
+ * Either way 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 from one definition (D-35).
+ *
  * For multi-exposed-component apps that need a specific component's URL,
  * use `$components.<name>.url` instead — `$app.*` always points at the
- * first exposed component to give a single, predictable answer.
+ * primary endpoint to give a single, predictable answer (D-58 rule 4). This
+ * 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>): Record<string, string | number>;
+export declare function computeAppProperties(launch: NormalizedLaunch, componentPorts: Record<string, number>, appUrl?: string): Record<string, string | number>;
+/**
+ * `$app.endpoints.<name>.*` under this provider (D-63 rule 4): every
+ * property of every named published endpoint resolves `""`. The allocator
+ * hands out one port per **component** (`allocatePorts`, keyed by component
+ * name), so a second `exposed: true` entry on a component has no host-side
+ * address to publish — not the primary's, and not its own (#294). The
+ * primary's entry is `""` too, rather than a copy of `$app.*`, because the
+ * per-endpoint form promises a per-endpoint publication this provider does
+ * not perform; `$app.*` keeps its own routing answer. Registering the empty
+ * answer explicitly, rather than nothing, records that the provider has read
+ * the namespace and declined it.
+ */
+export declare function computeAppEndpoints(launch: NormalizedLaunch): Record<string, AppEndpointProperties>;
 /**
  * Build a ResolverContext from provisioned resources, component ports,
- * secrets, and (D-33) the platform-injected app properties.
+ * secrets, (D-33) the platform-injected app properties, (D-63) the
+ * per-endpoint map — `computeAppEndpoints`, which under this provider is
+ * every named published endpoint resolving `""` — and the `uses` each
+ * resource entry declares (`declaredUses`), which the resolver reads to
+ * resolve `$<resource>.<use>.<property>` strictly.
+ */
+export declare function buildResolverContext(resourceMap: Record<string, ResourceProperties>, componentPorts: Record<string, number>, secrets: Record<string, string>, app: Record<string, string | number>, appEndpoints?: Record<string, AppEndpointProperties>, uses?: Record<string, readonly string[]>): ResolverContext;
+/**
+ * The use keys each resource entry declares (`db`, `db.cache`), keyed like
+ * the resource namespace (`name ?? type`, app-global). Same-name entries pool
+ * their keys — D-24 says they describe one resource. Host-capability entries
+ * have none.
+ */
+export declare function declaredUses(launch: NormalizedLaunch): Record<string, string[]>;
+/**
+ * A resource's property map as `up`, `env` and `bootstrap` all register it:
+ * the provisioner's instance vocabulary plus every pooled use this provider
+ * covers under `<use>.<property>` / `<use>.<name>.<property>` (D-24:
+ * same-name entries describe one resource). `dbIndexes` carries the numbered
+ * database each redis `db` use key selects. A pooled `db` key with no index
+ * in it stays unregistered, so a `$<resource>.db.<property>` (or
+ * `$<resource>.db.<name>.<property>`) reference throws `UnresolvedUseError`
+ * instead of falling through to the instance url.
+ */
+export declare function registerResource(type: string, resourceName: string, uses: Record<string, readonly string[]>, base: ResourceProperties, dbIndexes: DbIndexes): ResourceProperties;
+/**
+ * The resource map a subcommand run after `up` (`env`, `bootstrap`) resolves
+ * against, rebuilt from state and registered exactly as `up` registered it.
+ * Each recorded resource is re-provisioned to read its current properties —
+ * every provisioner is idempotent, so this neither re-creates nor corrupts
+ * the resource — and a redis `db` use reads back the index `up` recorded
+ * rather than one re-derived from the file, which may have changed since. A
+ * state file written before the index was recorded leaves `db.*`
+ * unregistered, so the strict resolver throws for `$<resource>.db.*` — never
+ * the instance url — until the next `up` records it.
+ */
+export declare function resourceMapFromState(launch: NormalizedLaunch, state: LaunchState, projectDir: string): Promise<Record<string, ResourceProperties>>;
+/**
+ * The resolver context `up`, `env` and `bootstrap` share, built from the same
+ * 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.
  */
-export declare function buildResolverContext(resourceMap: Record<string, ResourceProperties>, componentPorts: Record<string, number>, secrets: Record<string, string>, app: Record<string, string | number>): ResolverContext;
+export declare function resolverContextFor(launch: NormalizedLaunch, resourceMap: Record<string, ResourceProperties>, state: LaunchState): ResolverContext;
 /**
  * The resolved environment for one component, plus what the file did not supply.
  */

package/dist/env-writer.js

@@ -6,34 +6,61 @@
  */
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { deriveAppUrlProperties, resolveExpression, isExpression, unsuppliedRequiredEnv, } from "@launchfile/sdk";
+import { deriveAppUrlProperties, resolveExpression, isExpression, parseUseKey, suppliedAppProperties, UNPUBLISHED_APP_ENDPOINT, unsuppliedRequiredEnv, useKeys, } from "@launchfile/sdk";
+import { declaredPrimaryComponent, 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";
+import { recordedDbIndexes } from "./state.js";
 /**
  * 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.
+ * macos-dev provider.
+ *
+ * With no `appUrl`, this provider's own routing strategy answers: the app's
+ * "primary" port is the port of 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 at least one
+ * `exposed: true` provides entry, and `http://localhost:<port>` is the address.
  * Apps with no exposed component get `port: 0` and `url: ""` (and empty
  * authority/scheme/tls).
  *
+ * 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,
+ * so one Launchfile behind one proxy resolves identical `$app.*` under either
+ * provider (P-5). The allocated local ports stay orthogonal — still bound, just
+ * not the address anyone reaches the app at.
+ *
+ * Either way 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 from one definition (D-35).
+ *
  * For multi-exposed-component apps that need a specific component's URL,
  * use `$components.<name>.url` instead — `$app.*` always points at the
- * first exposed component to give a single, predictable answer.
+ * primary endpoint to give a single, predictable answer (D-58 rule 4). This
+ * provider allocates one port per component, so the named endpoint's address
+ * is its component's port.
  */
-export function computeAppProperties(launch, componentPorts) {
+export function computeAppProperties(launch, componentPorts, appUrl) {
+    if (appUrl !== undefined)
+        return suppliedAppProperties(launch.name, appUrl);
     let primaryPort = 0;
-    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.
-        // 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;
+    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 url = primaryPort > 0 ? `http://localhost:${primaryPort}` : "";
@@ -45,11 +72,38 @@ export function computeAppProperties(launch, componentPorts) {
         ...deriveAppUrlProperties(url),
     };
 }
+/**
+ * `$app.endpoints.<name>.*` under this provider (D-63 rule 4): every
+ * property of every named published endpoint resolves `""`. The allocator
+ * hands out one port per **component** (`allocatePorts`, keyed by component
+ * name), so a second `exposed: true` entry on a component has no host-side
+ * address to publish — not the primary's, and not its own (#294). The
+ * primary's entry is `""` too, rather than a copy of `$app.*`, because the
+ * per-endpoint form promises a per-endpoint publication this provider does
+ * not perform; `$app.*` keeps its own routing answer. Registering the empty
+ * answer explicitly, rather than nothing, records that the provider has read
+ * the namespace and declined it.
+ */
+export function computeAppEndpoints(launch) {
+    const endpoints = {};
+    for (const component of Object.values(launch.components)) {
+        for (const p of component.provides ?? []) {
+            if (p.name === undefined || p.exposed !== true)
+                continue;
+            endpoints[p.name] ??= UNPUBLISHED_APP_ENDPOINT;
+        }
+    }
+    return endpoints;
+}
 /**
  * Build a ResolverContext from provisioned resources, component ports,
- * secrets, and (D-33) the platform-injected app properties.
+ * secrets, (D-33) the platform-injected app properties, (D-63) the
+ * per-endpoint map — `computeAppEndpoints`, which under this provider is
+ * every named published endpoint resolving `""` — and the `uses` each
+ * resource entry declares (`declaredUses`), which the resolver reads to
+ * resolve `$<resource>.<use>.<property>` strictly.
  */
-export function buildResolverContext(resourceMap, componentPorts, secrets, app) {
+export function buildResolverContext(resourceMap, componentPorts, secrets, app, appEndpoints = {}, uses = {}) {
     // Build components map from ports
     const components = {};
     for (const [name, port] of Object.entries(componentPorts)) {
@@ -70,7 +124,78 @@ export function buildResolverContext(resourceMap, componentPorts, secrets, app)
         }
         resources[name] = record;
     }
-    return { resources, components, secrets, app };
+    return { resources, components, secrets, app, appEndpoints, uses };
+}
+/**
+ * The use keys each resource entry declares (`db`, `db.cache`), keyed like
+ * the resource namespace (`name ?? type`, app-global). Same-name entries pool
+ * their keys — D-24 says they describe one resource. Host-capability entries
+ * have none.
+ */
+export function declaredUses(launch) {
+    const uses = {};
+    for (const component of Object.values(launch.components)) {
+        for (const entry of [...(component.requires ?? []), ...(component.supports ?? [])]) {
+            if (entry.host || !entry.uses)
+                continue;
+            const pooled = (uses[entry.name ?? entry.type] ??= []);
+            for (const key of useKeys(entry.uses)) {
+                if (!pooled.includes(key))
+                    pooled.push(key);
+            }
+        }
+    }
+    return uses;
+}
+/**
+ * A resource's property map as `up`, `env` and `bootstrap` all register it:
+ * the provisioner's instance vocabulary plus every pooled use this provider
+ * covers under `<use>.<property>` / `<use>.<name>.<property>` (D-24:
+ * same-name entries describe one resource). `dbIndexes` carries the numbered
+ * database each redis `db` use key selects. A pooled `db` key with no index
+ * in it stays unregistered, so a `$<resource>.db.<property>` (or
+ * `$<resource>.db.<name>.<property>`) reference throws `UnresolvedUseError`
+ * instead of falling through to the instance url.
+ */
+export function registerResource(type, resourceName, uses, base, dbIndexes) {
+    const pooled = coveredUses(type, uses[resourceName] ?? []);
+    const registered = pooled.filter((key) => parseUseKey(key).use !== "db" || Object.hasOwn(dbIndexes, key));
+    return withCoveredUses(type, registered, base, dbIndexes);
+}
+/**
+ * The resource map a subcommand run after `up` (`env`, `bootstrap`) resolves
+ * against, rebuilt from state and registered exactly as `up` registered it.
+ * Each recorded resource is re-provisioned to read its current properties —
+ * every provisioner is idempotent, so this neither re-creates nor corrupts
+ * the resource — and a redis `db` use reads back the index `up` recorded
+ * rather than one re-derived from the file, which may have changed since. A
+ * state file written before the index was recorded leaves `db.*`
+ * unregistered, so the strict resolver throws for `$<resource>.db.*` — never
+ * the instance url — until the next `up` records it.
+ */
+export async function resourceMapFromState(launch, state, projectDir) {
+    const uses = declaredUses(launch);
+    const resourceMap = {};
+    for (const [name, res] of Object.entries(state.resources)) {
+        const provisioner = getProvisioner(res.type);
+        if (!provisioner)
+            continue;
+        const result = await provisioner.provision({ type: res.type, name: res.name }, { appName: state.appName, projectDir, databases: namedDatabases(uses[name] ?? []) }, res);
+        resourceMap[name] = registerResource(res.type, name, uses, result.properties, recordedDbIndexes(res));
+    }
+    return resourceMap;
+}
+/**
+ * The resolver context `up`, `env` and `bootstrap` share, built from the same
+ * 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.
+ */
+export function resolverContextFor(launch, resourceMap, state) {
+    const appProperties = computeAppProperties(launch, state.ports, state.appUrl);
+    wireHttpsOrigins(launch, resourceMap, state.appUrl);
+    return buildResolverContext(resourceMap, state.ports, state.secrets, appProperties, computeAppEndpoints(launch), declaredUses(launch));
 }
 /**
  * Resolve all environment variables for a single component.
@@ -256,7 +381,7 @@ export async function writeAllEnvFiles(launch, context, resourceMap, componentPo
         }
         else {
             const envDir = join(projectDir, ".launchfile", "env");
-            await mkdir(envDir, { recursive: true });
+            await mkdir(envDir, { recursive: true, mode: 0o700 });
             await writeEnvFile(join(envDir, `${name}.env`), env);
         }
     }

package/dist/https-origin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `https-origin` (D-60) under this provider — the one backing service that
+ * sits in FRONT of the app.
+ *
+ * This provider runs no edge of its own, so it cannot provision an origin. It
+ * can accept one the orchestrator already owns, through the publication-context
+ * channel (`LaunchUpOpts.appUrl`, D-58), which for this type IS the D-56
+ * supplied-resource channel (D-60 rule 5, PROVIDERS.md §7) — not a second one.
+ * Satisfaction is decided on the supplied scheme alone: no request is made, and
+ * 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 { 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";
+/**
+ * Whether a supplied publication URL satisfies an `https-origin` entry: its
+ * scheme is `https`. Syntactic only — `undefined` (nothing supplied and nothing
+ * recorded) and an `http` URL both fail. Expects a normalized value, as
+ * `launchUp` records it.
+ */
+export declare function httpsOriginSatisfied(appUrl: string | undefined): boolean;
+/**
+ * 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
+ * behind one proxy reads the same message under either provider (P-5).
+ */
+export declare function httpsOriginShortfall(entry: NormalizedRequirement, appUrl: string | undefined): string;
+/**
+ * The component an `https-origin` entry sits on, 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.
+ */
+export declare function declaredPrimaryComponent(launch: NormalizedLaunch): string | 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.
+ */
+export declare function wireHttpsOrigins(launch: NormalizedLaunch, resourceMap: Record<string, ResourceProperties>, appUrl: string | undefined): void;
+//# sourceMappingURL=https-origin.d.ts.map

package/dist/https-origin.js

@@ -0,0 +1,81 @@
+/**
+ * `https-origin` (D-60) under this provider — the one backing service that
+ * sits in FRONT of the app.
+ *
+ * This provider runs no edge of its own, so it cannot provision an origin. It
+ * can accept one the orchestrator already owns, through the publication-context
+ * channel (`LaunchUpOpts.appUrl`, D-58), which for this type IS the D-56
+ * supplied-resource channel (D-60 rule 5, PROVIDERS.md §7) — not a second one.
+ * Satisfaction is decided on the supplied scheme alone: no request is made, and
+ * D-56 rule 3 stands — the provider does not verify the origin exists or is
+ * ready.
+ */
+import { suppliedAppAddress, } from "@launchfile/sdk";
+/** The backing-service type that declares the app's public HTTPS origin (D-60). */
+export const HTTPS_ORIGIN = "https-origin";
+/**
+ * Whether a supplied publication URL satisfies an `https-origin` entry: its
+ * scheme is `https`. Syntactic only — `undefined` (nothing supplied and nothing
+ * recorded) and an `http` URL both fail. Expects a normalized value, as
+ * `launchUp` records it.
+ */
+export function httpsOriginSatisfied(appUrl) {
+    return appUrl !== undefined && suppliedAppAddress(appUrl).scheme === "https";
+}
+/**
+ * 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
+ * behind one proxy reads the same message under either provider (P-5).
+ */
+export function httpsOriginShortfall(entry, appUrl) {
+    const label = `${entry.name ?? entry.type} (endpoint "${entry.endpoint ?? "?"}")`;
+    return appUrl === undefined
+        ? `${label}: no publication URL was supplied, and this provider has no edge of its own`
+        : `${label}: the supplied publication URL's scheme is "${suppliedAppAddress(appUrl).scheme}", not https`;
+}
+/**
+ * The component an `https-origin` entry sits on, 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.
+ */
+export function declaredPrimaryComponent(launch) {
+    for (const [name, component] of Object.entries(launch.components)) {
+        for (const entry of [
+            ...(component.requires ?? []),
+            ...(component.supports ?? []),
+        ]) {
+            if (entry.type === HTTPS_ORIGIN && entry.endpoint !== undefined)
+                return name;
+        }
+    }
+    return 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.
+ */
+export function wireHttpsOrigins(launch, resourceMap, appUrl) {
+    if (appUrl === undefined)
+        return;
+    const { scheme, url } = suppliedAppAddress(appUrl);
+    if (scheme !== "https")
+        return;
+    for (const component of Object.values(launch.components)) {
+        for (const entry of [
+            ...(component.requires ?? []),
+            ...(component.supports ?? []),
+        ]) {
+            if (entry.type !== HTTPS_ORIGIN)
+                continue;
+            resourceMap[entry.name ?? entry.type] = { url };
+        }
+    }
+}
+//# sourceMappingURL=https-origin.js.map

package/dist/index.d.ts

@@ -7,5 +7,6 @@
 export { launchUp, launchDown, launchStatus, launchEnv } from "./provider.js";
 export type { LaunchUpOpts } from "./provider.js";
 export { launchBootstrap } from "./bootstrap.js";
+export { InvalidAppUrlError, normalizeAppUrl } from "@launchfile/sdk";
 export type { BootstrapResult } from "./bootstrap.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -6,4 +6,8 @@
  */
 export { launchUp, launchDown, launchStatus, launchEnv } from "./provider.js";
 export { launchBootstrap } from "./bootstrap.js";
+// Re-exported so a caller of this provider catches the publication-URL refusal
+// (D-58 rule 3) without also depending on the SDK, matching
+// `@launchfile/docker`. The SDK owns both.
+export { InvalidAppUrlError, normalizeAppUrl } from "@launchfile/sdk";
 //# sourceMappingURL=index.js.map

package/dist/port-allocator.d.ts

@@ -16,6 +16,7 @@ export declare function allocatePort(key: string, existingPorts: Set<number>): P
 export declare function allocatePorts(components: Record<string, {
     provides?: Array<{
         port: number;
+        exposed?: boolean;
     }>;
 }>, appName: string, savedPorts?: Record<string, number>): Promise<Record<string, number>>;
 //# sourceMappingURL=port-allocator.d.ts.map

package/dist/port-allocator.js

@@ -61,8 +61,22 @@ export async function allocatePorts(components, appName, savedPorts) {
             allocated.add(saved);
             continue;
         }
-        // Use the component's declared port if free
-        const declaredPort = component.provides?.[0]?.port;
+        // Use the component's declared port if free.
+        //
+        // D-27: only an `exposed: true` endpoint is reachable from outside the
+        // host, so it anchors the single port this provider allocates. Fully
+        // internal components keep provides[0]. The docker provider answers
+        // $app.* by this same rule (app-url.ts), and this line is what makes the
+        // two agree on a file whose first entry is not the exposed one.
+        //
+        // Residual: this provider runs one host process per component and
+        // allocates it one port, so a component declaring several endpoints
+        // collapses to the anchor — every non-anchor endpoint is unallocated
+        // here. The allocated port also need not equal any declared port: when
+        // the preferred one is taken, the fall-through below picks a
+        // deterministic free port instead. See #276 for what that costs
+        // `$components.<name>.<endpoint>.*` on this provider.
+        const declaredPort = (component.provides?.find((p) => p.exposed === true) ?? component.provides?.[0])?.port;
         if (declaredPort && !allocated.has(declaredPort) && (await isPortFree(declaredPort))) {
             result[name] = declaredPort;
             allocated.add(declaredPort);