@launchfile/macos-dev 0.2.0 → 0.3.0

package/dist/provider.js

@@ -6,7 +6,24 @@
  */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { readLaunch } from "@launchfile/sdk";
+import { readLaunch, selectionClosure } from "@launchfile/sdk";
+/**
+ * Source-mode run resolution (D-38, precedence `dev` > `image` > `start`).
+ * This provider runs apps from source. A component is source-runnable when it
+ * declares `dev`, or a `start` with no `image` — an `image` without a `dev`
+ * override stays artifact-mode, which this source-only provider can't launch.
+ */
+export function isSourceRunnable(component) {
+    return Boolean(component.commands?.dev || (component.commands?.start && !component.image));
+}
+/** The command run from source, or undefined if the component resolves to its artifact. */
+export function sourceRunCommand(component) {
+    if (component.commands?.dev?.command)
+        return component.commands.dev.command;
+    if (component.image)
+        return undefined; // image, no `dev` override → artifact
+    return component.commands?.start?.command;
+}
 import { checkPrereqs } from "./prereqs.js";
 import { loadState, initState, saveState, ensureDirs } from "./state.js";
 import { buildResolverContext, computeAppProperties, resolveComponentEnv, generateSecrets, resolveGenerators, writeEnvFile, } from "./env-writer.js";
@@ -14,9 +31,11 @@ import { getProvisioner } from "./resources/index.js";
 import { allocatePorts } from "./port-allocator.js";
 import { getRuntimeInstaller } from "./runtimes/index.js";
 import { detectPackageManager } from "./lockfile-detect.js";
-import { provisionStorage } from "./storage.js";
+import { provisionStorage, storagePaths } from "./storage.js";
 import { ProcessManager } from "./process-manager.js";
+import { stopRecordedProcesses } from "./process-stopper.js";
 import { shell } from "./shell.js";
+import { parseDuration } from "./bootstrap.js";
 export async function launchUp(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
     // 1. Check prerequisites
@@ -38,7 +57,52 @@ export async function launchUp(opts = {}) {
         process.exit(1);
     }
     const launch = readLaunch(launchfileContent);
+    const allComponentNames = Object.keys(launch.components);
+    // Resolve component selector (#77) into its D-41 start-set: selected
+    // components + their transitive downward `depends_on` closure (and, by
+    // narrowing to that set, every closure member's `requires`). Narrowing
+    // launch.components here makes every downstream phase loop in launchUp honor
+    // the closure without per-loop edits — dropping it would hand back an app
+    // missing the very dependencies a selected component needs to start (D-16).
+    // down/status/env re-read the file, so they are unaffected.
+    const selection = selectionClosure(launch, opts.components ?? []);
+    if (selection.unknown.length > 0 || selection.resources.length > 0) {
+        console.error(`\nCannot select: ${[...selection.unknown, ...selection.resources].join(", ")}`);
+        for (const r of selection.resources) {
+            console.error(`  - "${r}" is a backing resource, not a component; select the component that requires it.`);
+        }
+        for (const u of selection.unknown) {
+            console.error(`  - "${u}" matches no component. Available: ${allComponentNames.join(", ")}`);
+        }
+        process.exit(1);
+    }
+    if (opts.components && opts.components.length > 0) {
+        const startSet = new Set(selection.start);
+        launch.components = Object.fromEntries(Object.entries(launch.components).filter(([n]) => startSet.has(n)));
+    }
     const componentNames = Object.keys(launch.components);
+    // 2b. Source-mode guard (D-38) — fail fast before provisioning anything.
+    // Run precedence is `dev` > `image` > `start`: a component runs from source
+    // when it declares `dev`, or a `start` with no `image`. An `image` without a
+    // `dev` override stays artifact-mode — which this source-only provider can't
+    // launch. If nothing is source-runnable, the app belongs on `launchfile up`.
+    const sourceRunnable = Object.values(launch.components).filter(isSourceRunnable);
+    if (sourceRunnable.length === 0) {
+        const hasImage = Object.values(launch.components).some((c) => c.image);
+        console.error("Nothing to run from source: no component declares `dev` (or a `start` without an `image`).");
+        console.error(hasImage
+            ? "This app runs from an image — use `launchfile up` to launch the built artifact."
+            : "Add a `dev` (or `start`) command to run it from source.");
+        process.exit(1);
+    }
+    // Mixed app: warn about artifact components (image, no `dev` override) that
+    // this source-only provider can't launch — they need `launchfile up`.
+    for (const [name, c] of Object.entries(launch.components)) {
+        if (!isSourceRunnable(c) && c.image) {
+            console.warn(`  ! [${name}] has an image and no \`dev\` override — runs as an artifact, ` +
+                "skipped in source mode; use `launchfile up` to run it.");
+        }
+    }
     // 3. Load or init state
     let state = await loadState(projectDir);
     if (!state) {
@@ -134,15 +198,22 @@ export async function launchUp(opts = {}) {
     }
     // 10. Detect package manager
     const pm = await detectPackageManager(projectDir);
-    // 11. Create storage directories
+    // 11. Create storage directories, capturing each volume's resolved local path
+    // 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)) {
-        await provisionStorage(component.storage, name, projectDir);
+        const volumeMap = await provisionStorage(component.storage, name, projectDir);
+        const storageCtx = {};
+        for (const [volName, localPath] of Object.entries(volumeMap)) {
+            storageCtx[volName] = { path: localPath };
+        }
+        componentStorage[name] = storageCtx;
     }
     // 12. Resolve env vars and write .env files
     const allEnvs = {};
     const isSingleComponent = componentNames.length === 1 && componentNames[0] === "default";
     for (const [name, component] of Object.entries(launch.components)) {
-        const env = resolveComponentEnv(component, context, resourceMap);
+        const env = resolveComponentEnv(component, context, resourceMap, componentStorage[name]);
         await resolveGenerators(component, env);
         const port = componentPorts[name];
         if (port && !env.PORT) {
@@ -171,62 +242,75 @@ export async function launchUp(opts = {}) {
         printSummary(launch, componentPorts, resourceMap);
         return;
     }
-    // 14. Run build commands
+    // 14. Run source-mode prepare \u2014 `install ?? build` (D-38), on demand
     if (!opts.noBuild) {
         for (const [name, component] of Object.entries(launch.components)) {
-            const buildCmd = component.commands?.build?.command;
-            const cmd = buildCmd ?? pm?.installCommand;
+            const prepare = component.commands?.install ?? component.commands?.build;
+            const cmd = prepare?.command ?? pm?.installCommand;
             if (cmd) {
-                console.log(`  \u2193 Building${componentNames.length > 1 ? ` [${name}]` : ""}...`);
+                console.log(`  \u2193 Preparing${componentNames.length > 1 ? ` [${name}]` : ""}...`);
                 await shell(cmd, {
-                    cwd: projectDir,
+                    cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
                     env: allEnvs[name],
+                    // Installs/compiles routinely exceed the 2-minute shell default;
+                    // honor a declared timeout, else allow 10 minutes.
+                    timeout: prepare?.timeout ? parseDuration(prepare.timeout) : 600_000,
                 });
             }
         }
     }
-    // 15. Run release commands (migrations)
+    // 15. Run release commands (migrations) \u2014 mode-invariant (D-38)
     for (const [name, component] of Object.entries(launch.components)) {
-        const releaseCmd = component.commands?.release?.command;
-        if (releaseCmd) {
+        const release = component.commands?.release;
+        if (release?.command) {
             console.log(`  \u2193 Running release${componentNames.length > 1 ? ` [${name}]` : ""}...`);
-            await shell(releaseCmd, {
-                cwd: projectDir,
+            await shell(release.command, {
+                cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
                 env: allEnvs[name],
+                timeout: release.timeout ? parseDuration(release.timeout) : undefined,
             });
         }
     }
-    // 16. Start all components
+    // 16. Run components from source \u2014 `dev` over `start` (D-38; this provider ignores `image`)
     process.stdout.write(`  \u2193 Starting services...`);
     const pm2 = new ProcessManager(projectDir);
     for (const [name, component] of Object.entries(launch.components)) {
-        const startCmd = component.commands?.start?.command;
-        if (!startCmd) {
-            console.warn(`\n  ! [${name}] No start command — skipping`);
+        // Resolve the source-mode run command (D-38 precedence `dev` > `image` >
+        // `start`). Artifact components (image, no `dev` override) resolve to
+        // undefined — they were warned by the guard; skip them.
+        const startCmd = sourceRunCommand(component);
+        if (!startCmd)
             continue;
-        }
         pm2.register(name, {
             command: startCmd,
             env: { ...process.env, ...allEnvs[name] },
-            cwd: projectDir,
+            cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
             dependsOn: component.depends_on,
             health: component.health,
             port: componentPorts[name],
         });
     }
     // Handle Ctrl+C gracefully
+    const finalState = state;
     process.on("SIGINT", async () => {
         console.log("\n\nShutting down...");
         await pm2.stopAll();
-        await saveState(projectDir, state);
+        // Processes are now dead; clear the recorded pids so a later `launch down`
+        // doesn't try to signal stale (and possibly recycled) pids.
+        finalState.processes = {};
+        await saveState(projectDir, finalState);
         process.exit(0);
     });
     await pm2.startAll();
     console.log("");
     console.log(`  \u2713 All components started`);
+    // Record spawned pids so `launch down` can stop them from another shell or
+    // after this foreground session ends (closes #49). Backward compatible: the
+    // field is optional and absent in pre-existing state files.
+    state.processes = pm2.getRecordedProcesses();
     // 17. Print summary
     printSummary(launch, componentPorts, resourceMap);
-    // Save final state
+    // Save final state (now including recorded pids)
     await saveState(projectDir, state);
 }
 function printSummary(launch, ports, _resources) {
@@ -244,6 +328,35 @@ export async function launchDown(opts = {}) {
         console.log("No active launch state found.");
         return;
     }
+    // Stop recorded app processes (closes #49). Backward compatible: state files
+    // written before pid persistence simply have no `processes`, so we skip this
+    // and behave exactly as before (resources-only down).
+    const recorded = state.processes ?? {};
+    if (Object.keys(recorded).length > 0) {
+        console.log("Stopping app processes...");
+        const outcomes = await stopRecordedProcesses(recorded);
+        for (const o of outcomes) {
+            switch (o.result) {
+                case "stopped":
+                    console.log(`  Stopped ${o.component}`);
+                    break;
+                case "already-dead":
+                    console.log(`  ${o.component} was not running`);
+                    break;
+                case "identity-mismatch":
+                    console.log(`  Skipped ${o.component} (pid recycled — left untouched)`);
+                    break;
+                case "error":
+                    console.log(`  Failed to stop ${o.component}: ${o.error}`);
+                    break;
+            }
+        }
+        // Clear recorded pids now that we've handled them.
+        state.processes = {};
+        if (!opts.destroy) {
+            await saveState(projectDir, state);
+        }
+    }
     if (opts.destroy) {
         console.log("Destroying resources...");
         for (const [name, resourceState] of Object.entries(state.resources)) {
@@ -262,6 +375,11 @@ export async function launchDown(opts = {}) {
         console.log("Stopped. Resources are still running (use --destroy to remove them).");
     }
 }
+// --detach is intentionally left as a follow-up: persisting pids (this PR) is
+// the prerequisite for it. With pids now recorded and a working cross-session
+// `down`, detach becomes "spawn detached + unref + don't install the SIGINT
+// foreground loop, then return" — a self-contained change best done separately
+// so the kill-path fix lands reviewable on its own.
 export async function launchStatus(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
     const state = await loadState(projectDir);
@@ -310,7 +428,13 @@ export async function launchEnv(opts = {}) {
     for (const [name, component] of Object.entries(launch.components)) {
         if (opts.component && name !== opts.component)
             continue;
-        const env = resolveComponentEnv(component, context, resourceMap);
+        // Resolved storage paths (D-39) — computed, not provisioned (no mkdir):
+        // `launchfile env` only prints, and the dirs already exist from `up`.
+        const storageCtx = {};
+        for (const [volName, localPath] of Object.entries(storagePaths(component.storage, name, projectDir))) {
+            storageCtx[volName] = { path: localPath };
+        }
+        const env = resolveComponentEnv(component, context, resourceMap, storageCtx);
         await resolveGenerators(component, env);
         const port = state.ports[name];
         if (port && !env.PORT)

package/dist/shell.js

@@ -19,7 +19,7 @@ export async function shell(command, opts = {}) {
     return new Promise((resolve, reject) => {
         cpExec(command, execOpts, (error, stdout, stderr) => {
             const result = {
-                exitCode: error?.code ?? (typeof error?.code === "number" ? error.code : 0),
+                exitCode: typeof error?.code === "number" ? error.code : 0,
                 stdout: typeof stdout === "string" ? stdout : "",
                 stderr: typeof stderr === "string" ? stderr : "",
             };

package/dist/state.d.ts

@@ -13,6 +13,28 @@ export interface ResourceState {
     user?: string;
     password?: string;
 }
+/**
+ * Records a spawned app component process so `launch down` can stop it
+ * from a different shell or after the foreground `launch up` session ends.
+ *
+ * Identity is captured at spawn time so `down` can re-verify the recorded
+ * pid still belongs to the process we started before signaling it — guarding
+ * against pid-reuse (a recycled pid belonging to an unrelated process).
+ */
+export interface ProcessState {
+    /** Leader pid of the spawned shell (`sh -c <command>`). */
+    pid: number;
+    /**
+     * Process group id. Because we spawn detached, the child is its own group
+     * leader, so pgid === pid. We persist it explicitly so `down` can signal the
+     * whole group (negative pid) and take down child processes too.
+     */
+    pgid: number;
+    /** ISO timestamp captured immediately after spawn — part of the identity check. */
+    startedAt: string;
+    /** The shell command string we launched — used as a best-effort identity cross-check. */
+    command: string;
+}
 export interface LaunchState {
     version: 1;
     appName: string;
@@ -22,6 +44,12 @@ export interface LaunchState {
     resources: Record<string, ResourceState>;
     secrets: Record<string, string>;
     ports: Record<string, number>;
+    /**
+     * App component processes recorded at spawn time, keyed by component name.
+     * Optional for backward compatibility: state files written before pid
+     * persistence existed simply omit this, and `down` tolerates its absence.
+     */
+    processes?: Record<string, ProcessState>;
 }
 export declare function hashLaunchfile(content: string): string;
 /** Load state from disk, or return null if none exists */

package/dist/storage.d.ts

@@ -1,12 +1,25 @@
 /**
  * Local storage provisioning for Launchfile volumes.
  *
- * Maps container paths to local directories under .launchfile/.
+ * 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).
  */
 import type { StorageVolume } from "@launchfile/sdk";
 /**
- * Create local directories for a component's storage volumes.
- * Returns a map of container path → local path.
+ * Compute the local path this provider uses for each of a component's storage
+ * volumes — keyed by **volume name** (the `storage:` key), which is what
+ * `$storage.<name>.path` resolves against (D-39). Pure: no filesystem side
+ * 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/...`.
+ */
+export declare function storagePaths(storage: Record<string, StorageVolume> | undefined, componentName: string, projectDir: 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>>;
 /** Clean up ephemeral (non-persistent) storage for a component */

package/dist/storage.js

@@ -1,25 +1,42 @@
 /**
  * Local storage provisioning for Launchfile volumes.
  *
- * Maps container paths to local directories under .launchfile/.
+ * 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).
  */
 import { mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 const STATE_DIR = ".launchfile";
 /**
- * Create local directories for a component's storage volumes.
- * Returns a map of container path → local path.
+ * Compute the local path this provider uses for each of a component's storage
+ * volumes — keyed by **volume name** (the `storage:` key), which is what
+ * `$storage.<name>.path` resolves against (D-39). Pure: no filesystem side
+ * 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/...`.
  */
-export async function provisionStorage(storage, componentName, projectDir) {
+export function storagePaths(storage, componentName, projectDir) {
     if (!storage)
         return {};
     const volumeMap = {};
     for (const [name, volume] of Object.entries(storage)) {
         const persistent = volume.persistent !== false; // default true
         const subdir = persistent ? "storage" : "tmp";
-        const localPath = join(projectDir, STATE_DIR, subdir, componentName, name);
+        volumeMap[name] = join(projectDir, STATE_DIR, subdir, componentName, name);
+    }
+    return volumeMap;
+}
+/**
+ * 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 async function provisionStorage(storage, componentName, projectDir) {
+    const volumeMap = storagePaths(storage, componentName, projectDir);
+    for (const localPath of Object.values(volumeMap)) {
         await mkdir(localPath, { recursive: true });
-        volumeMap[volume.path] = localPath;
     }
     return volumeMap;
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@launchfile/macos-dev",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "macOS dev provider for Launchfile — run apps locally via brew services and native runtimes",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
@@ -33,7 +33,7 @@
     "directory": "providers/macos-dev"
   },
   "dependencies": {
-    "@launchfile/sdk": "^0.2.0",
+    "@launchfile/sdk": "^0.3.0",
     "semver": "^7.7.4"
   },
   "devDependencies": {

package/dist/__tests__/bootstrap.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=bootstrap.test.d.ts.map

package/dist/__tests__/bootstrap.test.js

@@ -1,90 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { extractCaptures, parseDuration } from "../bootstrap.js";
-describe("extractCaptures (D-34)", () => {
-    it("extracts a single-group regex from stdout", () => {
-        const captures = {
-            invite_link: {
-                pattern: "https?://\\S+",
-                description: "One-time invite link",
-                sensitive: true,
-            },
-        };
-        const stdout = "Admin created.\nInvite URL: https://example.com/invite/abc123\n";
-        expect(extractCaptures(stdout, captures)).toEqual({
-            invite_link: "https://example.com/invite/abc123",
-        });
-    });
-    it("uses first capture group when present", () => {
-        const captures = {
-            password: {
-                pattern: "Admin password: (.+)",
-            },
-        };
-        const stdout = "Admin password: s3cret!\n";
-        expect(extractCaptures(stdout, captures)).toEqual({
-            password: "s3cret!",
-        });
-    });
-    it("returns empty result when no patterns match", () => {
-        const captures = {
-            token: { pattern: "token=(\\S+)" },
-        };
-        expect(extractCaptures("nothing to see here", captures)).toEqual({});
-    });
-    it("strips ANSI escape codes before matching", () => {
-        const captures = {
-            url: { pattern: "https?://\\S+" },
-        };
-        // Simulates colorized output from a CLI tool that detects a TTY
-        const stdout = "\x1b[32mSuccess:\x1b[0m visit \x1b[4mhttps://example.com/admin\x1b[0m to continue";
-        expect(extractCaptures(stdout, captures)).toEqual({
-            url: "https://example.com/admin",
-        });
-    });
-    it("skips invalid regex without throwing", () => {
-        const captures = {
-            bad: { pattern: "(unclosed" },
-            good: { pattern: "ok" },
-        };
-        const result = extractCaptures("ok here", captures);
-        // good matches; bad is skipped
-        expect(result.good).toBe("ok");
-        expect(result.bad).toBeUndefined();
-    });
-    it("handles multiple captures in one stdout", () => {
-        const captures = {
-            user: { pattern: "user=(\\S+)" },
-            pw: { pattern: "pw=(\\S+)" },
-        };
-        const stdout = "Created user=alice pw=hunter2 expires=1h\n";
-        expect(extractCaptures(stdout, captures)).toEqual({
-            user: "alice",
-            pw: "hunter2",
-        });
-    });
-    it("returns full match when pattern has no capture group", () => {
-        const captures = {
-            hash: { pattern: "[a-f0-9]{8}" },
-        };
-        const stdout = "Commit: deadbeef\n";
-        expect(extractCaptures(stdout, captures)).toEqual({
-            hash: "deadbeef",
-        });
-    });
-});
-describe("parseDuration", () => {
-    it("parses ms, s, m, h units", () => {
-        expect(parseDuration("500ms")).toBe(500);
-        expect(parseDuration("30s")).toBe(30_000);
-        expect(parseDuration("5m")).toBe(300_000);
-        expect(parseDuration("2h")).toBe(7_200_000);
-    });
-    it("tolerates whitespace", () => {
-        expect(parseDuration(" 10s ")).toBe(10_000);
-    });
-    it("falls back to default for invalid input", () => {
-        expect(parseDuration("bogus")).toBe(120_000);
-        expect(parseDuration("")).toBe(120_000);
-    });
-});
-//# sourceMappingURL=bootstrap.test.js.map

package/dist/__tests__/dry-run.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=dry-run.test.d.ts.map