@launchfile/macos-dev 0.4.0 → 0.8.0

package/dist/env-writer.js

@@ -26,8 +26,10 @@ export function computeAppProperties(launch, componentPorts) {
     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.
-        // The docker provider derives `$app.*` by the same rule — `$app.url` is a
-        // portable value and the two providers must not disagree on it (P-5).
+        // 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];

package/dist/provider.d.ts

@@ -26,6 +26,12 @@ export interface LaunchUpOpts {
      * so both yield the identical running topology (P-5). Empty = all components.
      */
     components?: string[];
+    /**
+     * Host paths for `content: operator` volumes (D-50 rule 1), keyed as the
+     * operator typed them: `<volume>`, or `<component>.<volume>` where a volume
+     * name is ambiguous. Relative paths resolve against the current directory.
+     */
+    storage?: Record<string, string>;
 }
 /**
  * Components this provider must refuse, mapped to the capabilities it cannot
@@ -61,6 +67,48 @@ export declare function scheduleWarning(component: string, schedule: string): st
  * report success over an empty set.
  */
 export declare function applyHostCapabilityRefusals(launch: NormalizedLaunch): "ok" | "none-left";
+/**
+ * Components this provider must refuse because they require a public HTTPS
+ * origin (D-60 rule 5), mapped to the entries it cannot satisfy.
+ *
+ * This provider has no orchestrator-facing publication channel ([#294]) and no
+ * edge of its own, so it can neither provision the origin nor accept a supplied
+ * one — it refuses, which PROVIDERS.md §10 item 5 makes conformant. `supports:`
+ * entries are not refused: the component runs, degraded.
+ */
+export declare function refusedHttpsOrigins(launch: NormalizedLaunch): Map<string, string[]>;
+/**
+ * Remove every component whose required `https-origin` this provider cannot
+ * satisfy, and say so on stderr. Same shape and same reason as
+ * {@link applyHostCapabilityRefusals}: the removal IS the refusal — a component
+ * left in the map goes on to be installed, wired, registered and started, and
+ * an app that declared it needs HTTPS would run over plain HTTP behind a
+ * message nobody acted on.
+ */
+export declare function applyHttpsOriginRefusals(launch: NormalizedLaunch): "ok" | "none-left";
+/**
+ * Components this provider must refuse because native TLS was selected on a
+ * listener it cannot activate (D-61 rule 5), mapped to the entries.
+ *
+ * Selection on this provider is `--with-optional`: it is the only way a
+ * `supports:` entry is ever turned on here. Without the flag a certificate
+ * binding is simply inactive and the component runs its declared HTTP
+ * baseline, which is correct (D-8) — so this returns nothing.
+ *
+ * With the flag, the operator asked for the optional capability and this
+ * provider has no way to deliver it: it has no supplied-resource channel to
+ * receive `cert_file`/`key_file` through, and no certificate of its own to
+ * offer. Refusing is what PROVIDERS.md §10 item 5 makes conformant; falling
+ * back to HTTP on a listener the operator asked to secure is the silent
+ * success the decision forbids.
+ */
+export declare function refusedCertificates(launch: NormalizedLaunch, withOptional: boolean): Map<string, string[]>;
+/**
+ * Remove every component whose selected certificate binding this provider
+ * cannot activate, and say so on stderr. Same shape and same reason as
+ * {@link applyHostCapabilityRefusals}: the removal IS the refusal.
+ */
+export declare function applyCertificateRefusals(launch: NormalizedLaunch, withOptional: boolean): "ok" | "none-left";
 export declare function launchUp(opts?: LaunchUpOpts): Promise<void>;
 export declare function launchDown(opts?: {
     destroy?: boolean;

package/dist/provider.js

@@ -4,9 +4,10 @@
  * Reads a Launchfile, provisions resources, resolves env vars,
  * installs runtimes, and starts all components.
  */
+import { accessSync, constants as fsConstants } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { readLaunch, resolveSourcePrepareCommand, resolveSourceRunCommand, selectionClosure, unsuppliedRequiredEnv, } from "@launchfile/sdk";
+import { join, resolve as resolvePath } from "node:path";
+import { CERTIFICATE, certificateBindings, indexOperatorStoragePaths, MissingOperatorStoragePathError, readLaunch, resolveSourcePrepareCommand, resolveSourceRunCommand, selectionClosure, UnboundOperatorStorageError, unsuppliedRequiredEnv, } from "@launchfile/sdk";
 import { checkPrereqs } from "./prereqs.js";
 import { loadState, initState, saveState, ensureDirs } from "./state.js";
 import { buildResolverContext, computeAppProperties, resolveComponentEnv, generateSecrets, resolveGenerators, writeEnvFile, } from "./env-writer.js";
@@ -44,6 +45,16 @@ function declaredTimeout(timeout, label) {
         throw new Error(`${label}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/** Whether a path exists and this process can read it (D-50 rule 2, row 3). */
+function isReadable(path) {
+    try {
+        accessSync(path, fsConstants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Components this provider must refuse, mapped to the capabilities it cannot
  * grant (D-44, PROVIDERS.md §11). Both spellings fold together so the `host:`
@@ -110,6 +121,96 @@ export function applyHostCapabilityRefusals(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 backing-service type that declares the app's public HTTPS origin (D-60). */
+const HTTPS_ORIGIN = "https-origin";
+/**
+ * Components this provider must refuse because they require a public HTTPS
+ * origin (D-60 rule 5), mapped to the entries it cannot satisfy.
+ *
+ * This provider has no orchestrator-facing publication channel ([#294]) and no
+ * edge of its own, so it can neither provision the origin nor accept a supplied
+ * one — it refuses, which PROVIDERS.md §10 item 5 makes conformant. `supports:`
+ * entries are not refused: the component runs, degraded.
+ */
+export function refusedHttpsOrigins(launch) {
+    const refused = new Map();
+    for (const [name, c] of Object.entries(launch.components)) {
+        const entries = (c.requires ?? [])
+            .filter((r) => r.type === HTTPS_ORIGIN)
+            .map((r) => `${r.name ?? r.type} (endpoint "${r.endpoint ?? "?"}")`);
+        if (entries.length > 0)
+            refused.set(name, entries);
+    }
+    return refused;
+}
+/**
+ * Remove every component whose required `https-origin` this provider cannot
+ * satisfy, and say so on stderr. Same shape and same reason as
+ * {@link applyHostCapabilityRefusals}: the removal IS the refusal — a component
+ * left in the map goes on to be installed, wired, registered and started, and
+ * an app that declared it needs HTTPS would run over plain HTTP behind a
+ * message nobody acted on.
+ */
+export function applyHttpsOriginRefusals(launch) {
+    const refused = refusedHttpsOrigins(launch);
+    for (const [name, entries] of refused) {
+        console.error(`  Refused: ${name} requires a public HTTPS origin this provider cannot supply ` +
+            `(${entries.join("; ")}) — it has no edge and no publication channel — component not started`);
+    }
+    if (refused.size === 0)
+        return "ok";
+    launch.components = Object.fromEntries(Object.entries(launch.components).filter(([n]) => !refused.has(n)));
+    return Object.keys(launch.components).length === 0 ? "none-left" : "ok";
+}
+/**
+ * Components this provider must refuse because native TLS was selected on a
+ * listener it cannot activate (D-61 rule 5), mapped to the entries.
+ *
+ * Selection on this provider is `--with-optional`: it is the only way a
+ * `supports:` entry is ever turned on here. Without the flag a certificate
+ * binding is simply inactive and the component runs its declared HTTP
+ * baseline, which is correct (D-8) — so this returns nothing.
+ *
+ * With the flag, the operator asked for the optional capability and this
+ * provider has no way to deliver it: it has no supplied-resource channel to
+ * receive `cert_file`/`key_file` through, and no certificate of its own to
+ * offer. Refusing is what PROVIDERS.md §10 item 5 makes conformant; falling
+ * back to HTTP on a listener the operator asked to secure is the silent
+ * success the decision forbids.
+ */
+export function refusedCertificates(launch, withOptional) {
+    const refused = new Map();
+    if (!withOptional)
+        return refused;
+    for (const [name, component] of Object.entries(launch.components)) {
+        const declared = new Set((component.supports ?? [])
+            .filter((s) => !s.host && s.type === CERTIFICATE)
+            .map((s) => s.name ?? s.type));
+        const entries = certificateBindings(component)
+            .filter(({ certificate }) => declared.has(certificate))
+            .map(({ entry, certificate }) => `${certificate} (endpoint ${entry.name === undefined ? "(unnamed)" : `"${entry.name}"`})`);
+        if (entries.length > 0)
+            refused.set(name, entries);
+    }
+    return refused;
+}
+/**
+ * Remove every component whose selected certificate binding this provider
+ * cannot activate, and say so on stderr. Same shape and same reason as
+ * {@link applyHostCapabilityRefusals}: the removal IS the refusal.
+ */
+export function applyCertificateRefusals(launch, withOptional) {
+    const refused = refusedCertificates(launch, withOptional);
+    for (const [name, entries] of refused) {
+        console.error(`  Refused: ${name} selected native TLS and this provider cannot activate it ` +
+            `(${entries.join("; ")}) — it has no channel to receive cert_file/key_file — ` +
+            "component not started; it never falls back to HTTP");
+    }
+    if (refused.size === 0)
+        return "ok";
+    launch.components = Object.fromEntries(Object.entries(launch.components).filter(([n]) => !refused.has(n)));
+    return Object.keys(launch.components).length === 0 ? "none-left" : "ok";
+}
 export async function launchUp(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
     // 1. Check prerequisites
@@ -166,6 +267,22 @@ export async function launchUp(opts = {}) {
         console.error("Every selected component requires a host capability this provider cannot grant.");
         process.exit(1);
     }
+    // 2a-bis. A required `https-origin` is refused for the same reason and in
+    // the same way (D-60 rule 5, PROVIDERS.md §10 item 5): this provider has
+    // no edge and no publication channel, so it cannot satisfy the entry, and
+    // starting the component anyway is the silent success the type removes.
+    if (applyHttpsOriginRefusals(launch) === "none-left") {
+        console.error("Every selected component requires a public HTTPS origin this provider cannot supply.");
+        process.exit(1);
+    }
+    // 2a-ter. A SELECTED certificate binding (`--with-optional`) is refused on
+    // the same grounds (D-61 rule 5): no channel to receive the material, so
+    // the listener the operator asked to secure would come up cleartext.
+    // Unselected, the binding is inactive and the baseline is correct (D-8).
+    if (applyCertificateRefusals(launch, opts.withOptional === true) === "none-left") {
+        console.error("Every selected component selected native TLS this provider cannot activate.");
+        process.exit(1);
+    }
     // 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 ?? []) {
@@ -174,6 +291,12 @@ export async function launchUp(opts = {}) {
                     `${capability}=${String(value)} not granted — running degraded`);
             }
         }
+        for (const sup of c.supports ?? []) {
+            if (sup.type !== HTTPS_ORIGIN)
+                continue;
+            console.warn(`  Warning: ${name}: optional public HTTPS origin ` +
+                `${sup.name ?? sup.type} (endpoint "${sup.endpoint ?? "?"}") not satisfied — running degraded`);
+        }
     }
     const componentNames = Object.keys(launch.components);
     // 2b. Source-mode guard (D-38) — fail fast before provisioning anything.
@@ -245,6 +368,69 @@ export async function launchUp(opts = {}) {
         console.error(`  ${missingRequired[0].key}=<value> launch up`);
         process.exit(1);
     }
+    // 2d. Operator-supplied storage (D-50 rules 1–2), settled here — before
+    // state, directories, resources, ports, runtimes or processes exist, and so
+    // before `--dry-run` returns. A marked volume with no path, or with one that
+    // is not on disk, fails the launch: an empty directory where the operator's
+    // library belongs is D-52's fabrication in storage form, and this provider
+    // creates neither.
+    //
+    // Scoped to the components this provider will actually run. An artifact
+    // component is warned about and skipped at step 16, so refusing the whole
+    // launch over storage it will never read would be a refusal about nothing —
+    // the same reason `@launchfile/docker` only examines components it
+    // translates. Its volumes simply stay unprovisioned at step 11.
+    //
+    // Unlike the host-capability refusal above, this throws rather than dropping
+    // the component: `@launchfile/docker` fails the whole launch for the same
+    // file, and one Launchfile must not yield two topologies (P-5).
+    const suppliedStorage = opts.storage
+        ? Object.fromEntries(Object.entries(opts.storage).map(([key, path]) => [key, resolvePath(path)]))
+        : undefined;
+    const storageIndex = indexOperatorStoragePaths(launch, suppliedStorage);
+    const usedStorageKeys = new Set();
+    const unboundVolumes = [];
+    const storageBinds = [];
+    const operatorStorage = {};
+    for (const [name, component] of Object.entries(launch.components)) {
+        if (!isSourceRunnable(component))
+            continue;
+        for (const [volName, vol] of Object.entries(component.storage ?? {})) {
+            if (vol.content !== "operator")
+                continue;
+            const supplied = storageIndex.lookup(name, volName);
+            if (!supplied) {
+                unboundVolumes.push({
+                    component: name,
+                    volume: volName,
+                    flag: storageIndex.flagFor(name, volName),
+                });
+                continue;
+            }
+            usedStorageKeys.add(supplied.key);
+            storageBinds.push({
+                component: name,
+                volume: volName,
+                key: supplied.key,
+                hostPath: supplied.path,
+                containerPath: vol.path,
+            });
+            (operatorStorage[name] ??= {})[volName] = supplied.path;
+        }
+    }
+    if (unboundVolumes.length > 0) {
+        throw new UnboundOperatorStorageError(unboundVolumes);
+    }
+    const unreadableBinds = storageBinds.filter((bind) => !isReadable(bind.hostPath));
+    if (unreadableBinds.length > 0) {
+        throw new MissingOperatorStoragePathError(unreadableBinds);
+    }
+    // A supplied key that bound nothing would otherwise vanish without a trace,
+    // so a typo'd name surfaces here. Row 4 keeps unmarked volumes untouched, so
+    // a key naming one is unused too.
+    for (const key of storageIndex.unusedKeys(usedStorageKeys)) {
+        console.warn(`  Warning: --storage ${key} matches no \`content: operator\` volume — ignored`);
+    }
     // 3. Load or init state
     let state = await loadState(projectDir);
     if (!state) {
@@ -348,7 +534,7 @@ export async function launchUp(opts = {}) {
     // so it can be injected as $storage.<name>.path (D-39). Scoped per component.
     const componentStorage = {};
     for (const [name, component] of Object.entries(launch.components)) {
-        const volumeMap = await provisionStorage(component.storage, name, projectDir);
+        const volumeMap = await provisionStorage(component.storage, name, projectDir, operatorStorage[name]);
         const storageCtx = {};
         for (const [volName, localPath] of Object.entries(volumeMap)) {
             storageCtx[volName] = { path: localPath };
@@ -388,6 +574,9 @@ export async function launchUp(opts = {}) {
         }
     }
     // 13. Save state before build (in case build fails, we still have resource state)
+    // The bound operator paths ride along so `env` can report the directory the
+    // app actually reads (D-50); a later `up` still has to supply them again.
+    state.operatorStorage = operatorStorage;
     await saveState(projectDir, state);
     if (opts.dryRun) {
         console.log("\n[dry-run] Would now run build, release, and start commands.");
@@ -590,8 +779,10 @@ export async function launchEnv(opts = {}) {
             continue;
         // Resolved storage paths (D-39) — computed, not provisioned (no mkdir):
         // `launchfile env` only prints, and the dirs already exist from `up`.
+        // A `content: operator` volume reads back the host path `up` bound
+        // (D-50), so what prints here is what the running app was given.
         const storageCtx = {};
-        for (const [volName, localPath] of Object.entries(storagePaths(component.storage, name, projectDir))) {
+        for (const [volName, localPath] of Object.entries(storagePaths(component.storage, name, projectDir, state.operatorStorage?.[name]))) {
             storageCtx[volName] = { path: localPath };
         }
         const { env, unsupplied } = resolveComponentEnv(component, context, resourceMap, storageCtx);

package/dist/state.d.ts

@@ -60,6 +60,18 @@ export interface LaunchState {
      * compatibility: older state files omit it and load as a first run.
      */
     generatedEnv?: Record<string, string>;
+    /**
+     * Host paths bound to `content: operator` volumes on the last successful
+     * `up` (D-50), as `component → volume → path`. Recorded so `env` reports
+     * the directory the app actually reads, not the `.launchfile/` path an
+     * unmarked volume would have taken.
+     *
+     * It is not a substitute for supplying the paths: a later `up` without them
+     * refuses again, matching `@launchfile/docker`, which persists `appUrl` but
+     * never its storage paths. Optional for backward compatibility: state files
+     * written before this existed omit it.
+     */
+    operatorStorage?: Record<string, Record<string, string>>;
 }
 export declare function hashLaunchfile(content: string): string;
 /** Load state from disk, or return null if none exists */

package/dist/storage.d.ts

@@ -4,6 +4,11 @@
  * Maps named volumes to local directories under .launchfile/, and exposes the
  * resolved local path per volume so the provider can inject it as
  * `$storage.<name>.path` (D-39).
+ *
+ * A `content: operator` volume (D-50) is the exception: its content comes from
+ * a directory the operator already keeps, so this provider names that path and
+ * creates nothing. `up` refuses before provisioning when such a volume has no
+ * path, or has one that is not there.
  */
 import type { StorageVolume } from "@launchfile/sdk";
 /**
@@ -13,15 +18,18 @@ import type { StorageVolume } from "@launchfile/sdk";
  * effects, so callers that only need the resolved paths (e.g. `launchfile env`)
  * can use it without provisioning. Persistent volumes live under
  * `.launchfile/storage/<component>/<name>`; ephemeral ones under `.../tmp/...`.
+ *
+ * `operatorPaths` carries the host paths supplied for this component's
+ * `content: operator` volumes, keyed by volume name.
  */
-export declare function storagePaths(storage: Record<string, StorageVolume> | undefined, componentName: string, projectDir: string): Record<string, string>;
+export declare function storagePaths(storage: Record<string, StorageVolume> | undefined, componentName: string, projectDir: string, operatorPaths?: Readonly<Record<string, string>>): Record<string, string>;
 /**
  * Create the local directories for a component's storage volumes and return the
  * volume-name → local-path map (the home-#3 value the resolver injects as
  * `$storage.<name>.path`, D-39). Previously the return was keyed by container
  * path and discarded at the call site — the path is now captured and delivered.
  */
-export declare function provisionStorage(storage: Record<string, StorageVolume> | undefined, componentName: string, projectDir: string): Promise<Record<string, string>>;
+export declare function provisionStorage(storage: Record<string, StorageVolume> | undefined, componentName: string, projectDir: string, operatorPaths?: Readonly<Record<string, string>>): Promise<Record<string, string>>;
 /** Clean up ephemeral (non-persistent) storage for a component */
 export declare function cleanEphemeralStorage(storage: Record<string, StorageVolume> | undefined, componentName: string, projectDir: string): Promise<void>;
 /** Clean up all storage (persistent + ephemeral) for a component */

package/dist/storage.js

@@ -4,6 +4,11 @@
  * Maps named volumes to local directories under .launchfile/, and exposes the
  * resolved local path per volume so the provider can inject it as
  * `$storage.<name>.path` (D-39).
+ *
+ * A `content: operator` volume (D-50) is the exception: its content comes from
+ * a directory the operator already keeps, so this provider names that path and
+ * creates nothing. `up` refuses before provisioning when such a volume has no
+ * path, or has one that is not there.
  */
 import { mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
@@ -15,12 +20,26 @@ const STATE_DIR = ".launchfile";
  * effects, so callers that only need the resolved paths (e.g. `launchfile env`)
  * can use it without provisioning. Persistent volumes live under
  * `.launchfile/storage/<component>/<name>`; ephemeral ones under `.../tmp/...`.
+ *
+ * `operatorPaths` carries the host paths supplied for this component's
+ * `content: operator` volumes, keyed by volume name.
  */
-export function storagePaths(storage, componentName, projectDir) {
+export function storagePaths(storage, componentName, projectDir, operatorPaths = {}) {
     if (!storage)
         return {};
     const volumeMap = {};
     for (const [name, volume] of Object.entries(storage)) {
+        if (volume.content === "operator") {
+            // D-50 row 1: the operator's directory IS the volume — this provider
+            // runs processes on the host, so binding it means naming that path.
+            // A marked volume with nothing supplied is left out of the map
+            // entirely rather than handed a `.launchfile/` path the operator's
+            // content is not in; `up` refuses that case before it gets here.
+            const supplied = operatorPaths[name];
+            if (supplied)
+                volumeMap[name] = supplied;
+            continue;
+        }
         const persistent = volume.persistent !== false; // default true
         const subdir = persistent ? "storage" : "tmp";
         volumeMap[name] = join(projectDir, STATE_DIR, subdir, componentName, name);
@@ -33,9 +52,15 @@ export function storagePaths(storage, componentName, projectDir) {
  * `$storage.<name>.path`, D-39). Previously the return was keyed by container
  * path and discarded at the call site — the path is now captured and delivered.
  */
-export async function provisionStorage(storage, componentName, projectDir) {
-    const volumeMap = storagePaths(storage, componentName, projectDir);
-    for (const localPath of Object.values(volumeMap)) {
+export async function provisionStorage(storage, componentName, projectDir, operatorPaths = {}) {
+    const volumeMap = storagePaths(storage, componentName, projectDir, operatorPaths);
+    for (const [name, localPath] of Object.entries(volumeMap)) {
+        // A `content: operator` volume is never created (D-50 rule 2, row 3):
+        // an empty directory where the operator's library belongs is the
+        // failure the marker exists to catch, and minting one here would
+        // reintroduce it through the channel's own flag.
+        if (storage?.[name]?.content === "operator")
+            continue;
         await mkdir(localPath, { recursive: true });
     }
     return volumeMap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchfile/macos-dev",
-  "version": "0.4.0",
+  "version": "0.8.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.4.0",
+    "@launchfile/sdk": "^0.8.0",
     "semver": "^7.7.4"
   },
   "devDependencies": {