@launchfile/macos-dev 0.3.0 → 0.7.0

package/dist/runtimes/python.js

@@ -4,6 +4,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { shell, shellOk } from "../shell.js";
+import { isInstalled } from "./installed-versions.js";
 export class PythonInstaller {
     runtime = "python";
     async detectVersion(projectDir) {
@@ -16,17 +17,23 @@ export class PythonInstaller {
         }
     }
     async install(version) {
-        if (!(await shellOk("which pyenv"))) {
-            await shell("brew install pyenv");
+        // `version` is the verbatim contents of .python-version in the target repo
+        // — untrusted input. It goes in as an argv element so it can never be read
+        // as shell syntax.
+        if (!(await shellOk("which", ["pyenv"]))) {
+            await shell("brew", ["install", "pyenv"]);
         }
-        if (!(await shellOk(`pyenv versions --bare | grep -q "^${version}$"`))) {
-            await shell(`pyenv install ${version}`);
+        if (!(await isInstalled("pyenv", version))) {
+            await shell("pyenv", ["install", version]);
         }
-        await shell(`pyenv local ${version}`);
+        await shell("pyenv", ["local", version]);
     }
     async shellEnv(_version) {
-        if (await shellOk("which pyenv")) {
-            const result = await shell("pyenv root", { silent: true, allowFailure: true });
+        if (await shellOk("which", ["pyenv"])) {
+            const result = await shell("pyenv", ["root"], {
+                silent: true,
+                allowFailure: true,
+            });
             if (result.exitCode === 0) {
                 const root = result.stdout.trim();
                 return { PATH: `${root}/shims:${process.env.PATH ?? ""}` };

package/dist/runtimes/ruby.js

@@ -4,6 +4,7 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { shell, shellOk } from "../shell.js";
+import { isInstalled } from "./installed-versions.js";
 export class RubyInstaller {
     runtime = "ruby";
     async detectVersion(projectDir) {
@@ -16,19 +17,23 @@ export class RubyInstaller {
         }
     }
     async install(version) {
-        if (!(await shellOk("which rbenv"))) {
-            await shell("brew install rbenv ruby-build");
+        // `version` is the verbatim contents of .ruby-version in the target repo —
+        // untrusted input. It goes in as an argv element so it can never be read
+        // as shell syntax.
+        if (!(await shellOk("which", ["rbenv"]))) {
+            await shell("brew", ["install", "rbenv", "ruby-build"]);
         }
-        const installed = await shellOk(`rbenv versions --bare | grep -q "^${version}$"`);
-        if (!installed) {
-            await shell(`rbenv install ${version}`);
+        if (!(await isInstalled("rbenv", version))) {
+            await shell("rbenv", ["install", version]);
         }
-        await shell(`rbenv local ${version}`);
+        await shell("rbenv", ["local", version]);
     }
     async shellEnv(_version) {
-        if (await shellOk("which rbenv")) {
+        if (await shellOk("which", ["rbenv"])) {
             try {
-                const result = await shell("rbenv init - bash", { silent: true });
+                const result = await shell("rbenv", ["init", "-", "bash"], {
+                    silent: true,
+                });
                 return parseRbenvEnv(result.stdout);
             }
             catch {

package/dist/secret-generator.js

@@ -3,13 +3,19 @@
  */
 import { randomBytes, randomUUID } from "node:crypto";
 import { allocatePort } from "./port-allocator.js";
+import { registerSecret } from "./redact.js";
 /**
  * Generate a value based on the generator type.
  */
 export async function generateValue(generator, existingPorts) {
     switch (generator) {
-        case "secret":
-            return randomBytes(32).toString("base64url");
+        case "secret": {
+            // Spec-defined output: 32 bytes of cryptographically random data,
+            // hex-encoded (64 characters). See spec/DESIGN.md D-47.
+            const secret = randomBytes(32).toString("hex");
+            registerSecret(secret);
+            return secret;
+        }
         case "uuid":
             return randomUUID();
         case "port": {
@@ -21,6 +27,8 @@ export async function generateValue(generator, existingPorts) {
 /** Generate a password suitable for database users */
 export function generatePassword() {
     // URL-safe so it can go in connection strings without encoding
-    return randomBytes(24).toString("base64url");
+    const password = randomBytes(24).toString("base64url");
+    registerSecret(password);
+    return password;
 }
 //# sourceMappingURL=secret-generator.js.map

package/dist/shell.d.ts

@@ -1,5 +1,16 @@
 /**
- * Shell execution helper with timeout, logging, and structured results.
+ * Command execution helpers with timeout, logging, and structured results.
+ *
+ * Two entry points, and the difference between them is a security boundary:
+ *
+ * - `shell(cmd, args, opts)` passes arguments straight to the OS via
+ *   `execFile`. No shell is involved, so metacharacters in an argument are
+ *   inert. Every command this provider builds itself uses this form — a value
+ *   spliced into a command string would be CWE-78.
+ * - `shellScript(command, opts)` runs a command string through `/bin/sh -c`.
+ *   It exists only for command strings the Launchfile author wrote for their
+ *   own app (`commands:`, `health:`, `release:`), where shell syntax is the
+ *   documented contract. Never build one of these by interpolation.
  */
 export interface ShellResult {
     exitCode: number;
@@ -14,12 +25,23 @@ export interface ShellOpts {
     silent?: boolean;
 }
 /**
- * Run a shell command and return structured output.
- * Throws on non-zero exit code unless `allowFailure` is set.
+ * Run a command with an argument array. Arguments reach the OS directly, so
+ * they are never parsed as shell syntax.
  */
-export declare function shell(command: string, opts?: ShellOpts & {
+export declare function shell(cmd: string, args: string[], opts?: ShellOpts & {
+    allowFailure?: boolean;
+}): Promise<ShellResult>;
+/** Run a command with an argument array, return true if exit code is 0. */
+export declare function shellOk(cmd: string, args: string[], opts?: ShellOpts): Promise<boolean>;
+/**
+ * Run an author-written command string through `/bin/sh -c`.
+ *
+ * The shell is the point here: `commands:`, `health:` and `release:` values are
+ * documented as shell commands, and app authors rely on pipes, `&&` and
+ * variable expansion in them. The string must come from the Launchfile
+ * verbatim — building one by interpolating a value makes it injectable.
+ */
+export declare function shellScript(command: string, opts?: ShellOpts & {
     allowFailure?: boolean;
 }): Promise<ShellResult>;
-/** Run a command, return true if exit code is 0 */
-export declare function shellOk(command: string, opts?: ShellOpts): Promise<boolean>;
 //# sourceMappingURL=shell.d.ts.map

package/dist/shell.js

@@ -1,46 +1,101 @@
 /**
- * Shell execution helper with timeout, logging, and structured results.
+ * Command execution helpers with timeout, logging, and structured results.
+ *
+ * Two entry points, and the difference between them is a security boundary:
+ *
+ * - `shell(cmd, args, opts)` passes arguments straight to the OS via
+ *   `execFile`. No shell is involved, so metacharacters in an argument are
+ *   inert. Every command this provider builds itself uses this form — a value
+ *   spliced into a command string would be CWE-78.
+ * - `shellScript(command, opts)` runs a command string through `/bin/sh -c`.
+ *   It exists only for command strings the Launchfile author wrote for their
+ *   own app (`commands:`, `health:`, `release:`), where shell syntax is the
+ *   documented contract. Never build one of these by interpolation.
  */
-import { exec as cpExec } from "node:child_process";
+import { exec as cpExec, execFile as cpExecFile, } from "node:child_process";
+import { redactSecrets } from "./redact.js";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_BUFFER = 10 * 1024 * 1024;
+function toResult(error, stdout, stderr) {
+    const result = {
+        exitCode: typeof error?.code === "number" ? error.code : 0,
+        stdout: typeof stdout === "string" ? stdout : "",
+        stderr: typeof stderr === "string" ? stderr : "",
+    };
+    // Node sets error.code to the exit code on non-zero; a signal or a spawn
+    // failure leaves it non-numeric, so surface those as a generic failure.
+    if (error && result.exitCode === 0)
+        result.exitCode = 1;
+    return result;
+}
+function failure(display, result) {
+    // The message reaches the user and may be logged by a caller; both the
+    // command and the child's stderr can echo a secret back, so neither goes
+    // in unscrubbed (D-18, CWE-532).
+    return Object.assign(new Error(`Command failed: ${redactSecrets(display)}\n${redactSecrets(result.stderr)}`), { result });
+}
 /**
- * Run a shell command and return structured output.
- * Throws on non-zero exit code unless `allowFailure` is set.
+ * Run a command with an argument array. Arguments reach the OS directly, so
+ * they are never parsed as shell syntax.
  */
-export async function shell(command, opts = {}) {
+export async function shell(cmd, args, opts = {}) {
+    const display = [cmd, ...args].join(" ");
     if (!opts.silent) {
-        console.log(`  $ ${command}`);
+        // An argument can carry a resolved secret (a generated DB password, a
+        // credential-bearing URL). Scrub before echo.
+        console.log(`  $ ${redactSecrets(display)}`);
     }
     const execOpts = {
         cwd: opts.cwd,
         env: opts.env ? { ...process.env, ...opts.env } : undefined,
-        timeout: opts.timeout ?? 120_000,
-        maxBuffer: 10 * 1024 * 1024,
+        timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+        maxBuffer: MAX_BUFFER,
     };
     return new Promise((resolve, reject) => {
-        cpExec(command, execOpts, (error, stdout, stderr) => {
-            const result = {
-                exitCode: typeof error?.code === "number" ? error.code : 0,
-                stdout: typeof stdout === "string" ? stdout : "",
-                stderr: typeof stderr === "string" ? stderr : "",
-            };
-            // Node's exec sets error.code to the exit code on non-zero
-            if (error && result.exitCode === 0) {
-                result.exitCode = 1;
-            }
-            if (error && !opts.allowFailure) {
-                reject(Object.assign(new Error(`Command failed: ${command}\n${result.stderr}`), {
-                    result,
-                }));
-            }
-            else {
+        cpExecFile(cmd, args, execOpts, (error, stdout, stderr) => {
+            const result = toResult(error, stdout, stderr);
+            if (error && !opts.allowFailure)
+                reject(failure(display, result));
+            else
                 resolve(result);
-            }
         });
     });
 }
-/** Run a command, return true if exit code is 0 */
-export async function shellOk(command, opts) {
-    const result = await shell(command, { ...opts, allowFailure: true, silent: true });
+/** Run a command with an argument array, return true if exit code is 0. */
+export async function shellOk(cmd, args, opts) {
+    const result = await shell(cmd, args, {
+        ...opts,
+        allowFailure: true,
+        silent: true,
+    });
     return result.exitCode === 0;
 }
+/**
+ * Run an author-written command string through `/bin/sh -c`.
+ *
+ * The shell is the point here: `commands:`, `health:` and `release:` values are
+ * documented as shell commands, and app authors rely on pipes, `&&` and
+ * variable expansion in them. The string must come from the Launchfile
+ * verbatim — building one by interpolating a value makes it injectable.
+ */
+export async function shellScript(command, opts = {}) {
+    if (!opts.silent) {
+        console.log(`  $ ${redactSecrets(command)}`);
+    }
+    const execOpts = {
+        cwd: opts.cwd,
+        env: opts.env ? { ...process.env, ...opts.env } : undefined,
+        timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+        maxBuffer: MAX_BUFFER,
+    };
+    return new Promise((resolve, reject) => {
+        cpExec(command, execOpts, (error, stdout, stderr) => {
+            const result = toResult(error, stdout, stderr);
+            if (error && !opts.allowFailure)
+                reject(failure(command, result));
+            else
+                resolve(result);
+        });
+    });
+}
 //# sourceMappingURL=shell.js.map

package/dist/state.d.ts

@@ -50,6 +50,28 @@ export interface LaunchState {
      * persistence existed simply omit this, and `down` tolerates its absence.
      */
     processes?: Record<string, ProcessState>;
+    /**
+     * Minted `env:`-level generator values (D-49: generate once, then
+     * preserve), keyed `<component>.<ENV_NAME>` — one entry per declaration
+     * (D-25), so same-named variables on different components hold independent
+     * values. `generator: port` values are never stored here (ports are
+     * re-allocated each run). Disjoint from `secrets` on purpose: these names
+     * must not become resolvable as `$secrets.<name>`. Optional for backward
+     * 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/state.js

@@ -7,6 +7,7 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
+import { registerSecrets } from "./redact.js";
 const STATE_DIR = ".launchfile";
 const STATE_FILE = "state.json";
 function stateDir(projectDir) {
@@ -22,7 +23,17 @@ export function hashLaunchfile(content) {
 export async function loadState(projectDir) {
     try {
         const raw = await readFile(statePath(projectDir), "utf8");
-        return JSON.parse(raw);
+        const state = JSON.parse(raw);
+        // Persisted credentials are reused verbatim in provisioning commands and
+        // in `$secrets.*` / `$<resource>.*` expressions, so they must be known to
+        // the redactor before anything can echo them.
+        registerSecrets(Object.values(state.secrets ?? {}));
+        registerSecrets(Object.values(state.resources ?? {}).map((r) => r.password));
+        // A value minted in an earlier run and merely reused in this one never
+        // passes through generateValue()'s registration, so the loader is the
+        // only place it can become scrubbable (D-18).
+        registerSecrets(Object.values(state.generatedEnv ?? {}));
+        return state;
     }
     catch {
         return null;

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,7 +1,10 @@
 {
   "name": "@launchfile/macos-dev",
-  "version": "0.3.0",
+  "version": "0.7.0",
   "description": "macOS dev provider for Launchfile — run apps locally via brew services and native runtimes",
+  "os": [
+    "darwin"
+  ],
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,14 +36,14 @@
     "directory": "providers/macos-dev"
   },
   "dependencies": {
-    "@launchfile/sdk": "^0.3.0",
+    "@launchfile/sdk": "^0.7.0",
     "semver": "^7.7.4"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
     "@types/bun": "^1.3.11",
     "@types/semver": "^7.7.1",
-    "typescript": "^6.0.0",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.3"
   }
 }