@launchfile/macos-dev 0.4.0 → 0.7.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

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 { 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:`
@@ -245,6 +256,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 +422,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 +462,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 +667,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.7.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.7.0",
     "semver": "^7.7.4"
   },
   "devDependencies": {