@launchfile/macos-dev 0.10.0 → 0.12.0

package/dist/env-writer.d.ts

@@ -59,8 +59,13 @@ export declare function computeAppEndpoints(launch: NormalizedLaunch): Record<st
  * every named published endpoint resolving `""` — and the `uses` each
  * resource entry declares (`declaredUses`), which the resolver reads to
  * resolve `$<resource>.<use>.<property>` strictly.
+ *
+ * `declared` carries the declared components, whose `provides` entries are
+ * what the named-endpoint form `$components.<name>.<endpoint>.<prop>`
+ * (D-6, D-66) resolves against. Omit it and only the primary
+ * `url`/`host`/`port` are registered.
  */
-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;
+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[]>, declared?: Record<string, NormalizedComponent>): ResolverContext;
 /**
  * The use keys each resource entry declares (`db`, `db.cache`), keyed like
  * the resource namespace (`name ?? type`, app-global). Same-name entries pool

package/dist/env-writer.js

@@ -6,7 +6,7 @@
  */
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { deriveAppUrlProperties, resolveExpression, isExpression, parseUseKey, suppliedAppProperties, UNPUBLISHED_APP_ENDPOINT, unsuppliedRequiredEnv, useKeys, } from "@launchfile/sdk";
+import { deriveAppUrlProperties, endpointProperties, 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";
@@ -95,6 +95,25 @@ export function computeAppEndpoints(launch) {
     }
     return endpoints;
 }
+/**
+ * The `provides` entries this provider can name a reachable port for, or
+ * `undefined` when it can name none.
+ *
+ * macos-dev allocates exactly one host port per component and hands it to the
+ * process as `PORT`. That port belongs to whichever declared endpoint the
+ * allocator anchored on; the rest are unallocated, and the process binds the
+ * ports they declare. When the component's preferred port was taken, the
+ * allocator moves it to a free port outside the declared set — then no declared
+ * endpoint can be named at that port, so the component reports no per-endpoint
+ * properties rather than an endpoint address nothing listens on (L-4). A
+ * container provider has no such collapse: it binds every declared port.
+ */
+function allocatedEndpoints(component, allocatedPort) {
+    const provides = component?.provides;
+    if (!provides?.some((entry) => entry.port === allocatedPort))
+        return undefined;
+    return provides;
+}
 /**
  * Build a ResolverContext from provisioned resources, component ports,
  * secrets, (D-33) the platform-injected app properties, (D-63) the
@@ -102,8 +121,13 @@ export function computeAppEndpoints(launch) {
  * every named published endpoint resolving `""` — and the `uses` each
  * resource entry declares (`declaredUses`), which the resolver reads to
  * resolve `$<resource>.<use>.<property>` strictly.
+ *
+ * `declared` carries the declared components, whose `provides` entries are
+ * what the named-endpoint form `$components.<name>.<endpoint>.<prop>`
+ * (D-6, D-66) resolves against. Omit it and only the primary
+ * `url`/`host`/`port` are registered.
  */
-export function buildResolverContext(resourceMap, componentPorts, secrets, app, appEndpoints = {}, uses = {}) {
+export function buildResolverContext(resourceMap, componentPorts, secrets, app, appEndpoints = {}, uses = {}, declared) {
     // Build components map from ports
     const components = {};
     for (const [name, port] of Object.entries(componentPorts)) {
@@ -111,6 +135,7 @@ export function buildResolverContext(resourceMap, componentPorts, secrets, app,
             url: `http://localhost:${port}`,
             host: "localhost",
             port,
+            ...endpointProperties(allocatedEndpoints(declared?.[name], port), "localhost"),
         };
     }
     // Build named resources map
@@ -195,7 +220,7 @@ export async function resourceMapFromState(launch, state, projectDir) {
 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));
+    return buildResolverContext(resourceMap, state.ports, state.secrets, appProperties, computeAppEndpoints(launch), declaredUses(launch), launch.components);
 }
 /**
  * Resolve all environment variables for a single component.

package/dist/process-stopper.d.ts

@@ -16,9 +16,12 @@
  *   1. **Liveness** — `process.kill(pid, 0)` throws ESRCH if no such process
  *      exists. If it's dead, we skip (already stopped).
  *   2. **Identity** — we compare the recorded spawn time against the live
- *      process's actual start time via `ps -o lstart= -p <pid>`. If the live
- *      process started meaningfully later than we recorded, the pid was
- *      recycled and we REFUSE to signal it.
+ *      process's actual start time via `ps -o lstart= -p <pid>`. If the two
+ *      are further apart than the tolerance window, in either direction, the
+ *      record does not describe this process and we REFUSE to signal it. A
+ *      later live start means the pid was recycled; an earlier one means the
+ *      record itself is untrustworthy (a backward clock jump between spawn and
+ *      `down`, or a state file carried over from another run).
  *
  * This is a best-effort guarantee, not a cryptographic one. Its honest limits:
  *   - `ps lstart` has ~1s resolution, so we allow a small tolerance window. A
@@ -76,7 +79,8 @@ export declare const realSignalFns: SignalFns;
  *   - "alive-verified": process exists AND start time is consistent → safe to signal
  *   - "alive-unverified": process exists but start time couldn't be read → signal group only, cautiously
  *   - "dead": no such process (ESRCH) → already stopped, skip
- *   - "mismatch": process exists but started too late → recycled pid, DO NOT signal
+ *   - "mismatch": process exists but its start time is outside the tolerance
+ *     window on either side → the record does not describe it, DO NOT signal
  */
 export declare function checkIdentity(rec: RecordedProcess, fns: SignalFns): Promise<"alive-verified" | "alive-unverified" | "dead" | "mismatch">;
 /**

package/dist/process-stopper.js

@@ -16,9 +16,12 @@
  *   1. **Liveness** — `process.kill(pid, 0)` throws ESRCH if no such process
  *      exists. If it's dead, we skip (already stopped).
  *   2. **Identity** — we compare the recorded spawn time against the live
- *      process's actual start time via `ps -o lstart= -p <pid>`. If the live
- *      process started meaningfully later than we recorded, the pid was
- *      recycled and we REFUSE to signal it.
+ *      process's actual start time via `ps -o lstart= -p <pid>`. If the two
+ *      are further apart than the tolerance window, in either direction, the
+ *      record does not describe this process and we REFUSE to signal it. A
+ *      later live start means the pid was recycled; an earlier one means the
+ *      record itself is untrustworthy (a backward clock jump between spawn and
+ *      `down`, or a state file carried over from another run).
  *
  * This is a best-effort guarantee, not a cryptographic one. Its honest limits:
  *   - `ps lstart` has ~1s resolution, so we allow a small tolerance window. A
@@ -33,10 +36,12 @@
  */
 import { execFile } from "node:child_process";
 /**
- * Identity tolerance: how much later than `startedAt` a live process may report
- * having started before we treat it as a recycled pid. `ps lstart` rounds to
- * whole seconds and there's scheduling slop between our `Date.now()` snapshot
- * and the kernel's recorded start, so we allow a few seconds of forward drift.
+ * Identity tolerance: how far a live process's reported start time may sit from
+ * `startedAt`, on either side, before we stop believing the record describes
+ * that process. `spawn()` forks before we timestamp the record and `ps lstart`
+ * rounds down to whole seconds, so a genuine record reads a second or so
+ * *earlier* than `startedAt`; scheduling slop covers the rest. The window is
+ * symmetric because a record can be wrong in either direction.
  */
 const START_TIME_TOLERANCE_MS = 3000;
 /** Default real implementation backed by `process.kill` and `ps`. */
@@ -74,7 +79,8 @@ function queryStartTime(pid) {
  *   - "alive-verified": process exists AND start time is consistent → safe to signal
  *   - "alive-unverified": process exists but start time couldn't be read → signal group only, cautiously
  *   - "dead": no such process (ESRCH) → already stopped, skip
- *   - "mismatch": process exists but started too late → recycled pid, DO NOT signal
+ *   - "mismatch": process exists but its start time is outside the tolerance
+ *     window on either side → the record does not describe it, DO NOT signal
  */
 export async function checkIdentity(rec, fns) {
     // Liveness probe.
@@ -95,9 +101,11 @@ export async function checkIdentity(rec, fns) {
     const recordedStart = Date.parse(rec.startedAt);
     if (Number.isNaN(recordedStart))
         return "alive-unverified";
-    // If the live process started meaningfully *after* we recorded the spawn,
-    // the original exited and the pid was recycled. Refuse to signal it.
-    if (liveStart > recordedStart + START_TIME_TOLERANCE_MS)
+    // The live start time must sit within tolerance of the record on both sides.
+    // Later than the record: the original exited and the pid was recycled.
+    // Earlier than the record: the record cannot be describing this process.
+    // Either way the pid is not ours to signal.
+    if (Math.abs(liveStart - recordedStart) > START_TIME_TOLERANCE_MS)
         return "mismatch";
     return "alive-verified";
 }

package/dist/provider.d.ts

@@ -171,6 +171,19 @@ export declare function refusedResourceUses(launch: NormalizedLaunch): Map<strin
  * removal IS the refusal.
  */
 export declare function applyResourceUseRefusals(launch: NormalizedLaunch): "ok" | "none-left";
+/**
+ * The mandatory report for every `provides` entry that declares `at:` (D-68
+ * rule 5), one line per declaring entry. This provider starts each process on
+ * a local port with nothing in front that routes by host name, so every
+ * request reaches the listener with its `Host` intact and only name resolution
+ * is left to the operator. It launches and reports — never a silent launch,
+ * and never a refusal.
+ *
+ * `ports` maps a component to the local port its process listens on; an
+ * absent entry means the port is not known yet. Under a supplied publication
+ * 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[];
 export declare function launchUp(opts?: LaunchUpOpts): Promise<void>;
 export declare function launchDown(opts?: {
     destroy?: boolean;

package/dist/provider.js

@@ -7,7 +7,7 @@
 import { accessSync, constants as fsConstants } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve as resolvePath } from "node:path";
-import { CERTIFICATE, certificateBindings, indexOperatorStoragePaths, MissingOperatorStoragePathError, normalizeAppUrl, readLaunch, resolveSourcePrepareCommand, resolveSourceRunCommand, selectionClosure, UnboundOperatorStorageError, unsuppliedRequiredEnv, appEndpointReferences, useKeys, } from "@launchfile/sdk";
+import { AT_APP_HOST, atDeclarations, atEntryLabel, CERTIFICATE, certificateBindings, indexOperatorStoragePaths, 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";
@@ -306,6 +306,43 @@ export function applyResourceUseRefusals(launch) {
     launch.components = Object.fromEntries(Object.entries(launch.components).filter(([n]) => !refused.has(n)));
     return Object.keys(launch.components).length === 0 ? "none-left" : "ok";
 }
+/**
+ * The mandatory report for every `provides` entry that declares `at:` (D-68
+ * rule 5), one line per declaring entry. This provider starts each process on
+ * a local port with nothing in front that routes by host name, so every
+ * request reaches the listener with its `Host` intact and only name resolution
+ * is left to the operator. It launches and reports — never a silent launch,
+ * and never a refusal.
+ *
+ * `ports` maps a component to the local port its process listens on; an
+ * absent entry means the port is not known yet. Under a supplied publication
+ * URL (D-58) the names are whoever routes that URL's to send here (rule 7).
+ */
+export function atReports(launch, ports = {}, suppliedAppUrl) {
+    const host = suppliedAppUrl === undefined ? "localhost" : new URL(suppliedAppUrl).hostname;
+    return atDeclarations(launch).map((declaration) => {
+        const names = declaration.values
+            .map((value) => (value === AT_APP_HOST ? host : `${value}.${host}`))
+            .join(", ");
+        const head = `${atEntryLabel(declaration)} answers at ${names} (\`at:\`, D-68)`;
+        if (suppliedAppUrl !== undefined) {
+            return (`${head} — this provider sets up no host names, and the supplied publication URL ` +
+                `(${suppliedAppUrl}) says nothing about them; whatever routes that URL must send each ` +
+                "name to this endpoint with the requested `Host` intact");
+        }
+        const port = ports[declaration.component];
+        const target = port === undefined ? "the component's local port" : `localhost:${port}`;
+        return (`${head} — this provider starts the process on a local port and sets up no host names. ` +
+            `Every request that reaches ${target} reaches the listener with its \`Host\` intact, so ` +
+            "map each name that does not resolve to this machine (hosts file or DNS), or use a " +
+            "provider that routes host names");
+    });
+}
+/** Print {@link atReports} the way this provider prints every warning. */
+function printAtReports(reports) {
+    for (const report of reports)
+        console.warn(`  Warning: ${report}`);
+}
 export async function launchUp(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
     // Publication context (D-58): validated and normalized before anything is
@@ -415,6 +452,11 @@ export async function launchUp(opts = {}) {
         console.error("Every selected component requires a use of a resource this provider cannot cover.");
         process.exit(1);
     }
+    // 2a-sexies. A `provides` entry declaring `at:` is reported, not refused
+    // (D-68 rule 5). The report belongs at the end of provisioning, after the
+    // summary; a dry run never gets there, so it prints here.
+    if (opts.dryRun)
+        printAtReports(atReports(launch, {}, suppliedAppUrl));
     // An optional capability is not refused — the component runs, degraded.
     for (const [name, c] of Object.entries(launch.components)) {
         for (const sup of c.supports ?? []) {
@@ -832,6 +874,7 @@ export async function launchUp(opts = {}) {
     state.processes = pm2.getRecordedProcesses();
     // 17. Print summary
     printSummary(launch, componentPorts, resourceMap);
+    printAtReports(atReports(launch, componentPorts, suppliedAppUrl));
     // Save final state (now including recorded pids)
     await saveState(projectDir, state);
 }
@@ -866,7 +909,7 @@ export async function launchDown(opts = {}) {
                     console.log(`  ${o.component} was not running`);
                     break;
                 case "identity-mismatch":
-                    console.log(`  Skipped ${o.component} (pid recycled — left untouched)`);
+                    console.log(`  Skipped ${o.component} (live process start time does not match the recorded one — left untouched)`);
                     break;
                 case "error":
                     console.log(`  Failed to stop ${o.component}: ${o.error}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchfile/macos-dev",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "macOS dev provider for Launchfile — run apps locally via brew services and native runtimes",
   "os": [
     "darwin"
@@ -36,7 +36,7 @@
     "directory": "providers/macos-dev"
   },
   "dependencies": {
-    "@launchfile/sdk": "^0.10.0",
+    "@launchfile/sdk": "^0.12.0",
     "semver": "^7.7.4"
   },
   "devDependencies": {