@launchfile/macos-dev 0.3.0 → 0.7.0

package/dist/redact.js

@@ -0,0 +1,92 @@
+/**
+ * Secret redaction for anything this provider prints or embeds in an error.
+ *
+ * Two independent layers, because either alone leaves a hole:
+ *
+ * 1. A registry of exact secret values. Every generated secret, every
+ *    persisted `state.secrets` entry, and every resource password registers
+ *    itself at creation/load time; `redactSecrets` then scrubs those literals
+ *    out of any string on its way to stdout/stderr or an Error message.
+ * 2. A pattern scrub for credentials embedded in URLs
+ *    (`scheme://user:pass@host`), which catches secrets that never passed
+ *    through this provider — e.g. a connection string written literally in a
+ *    Launchfile `env:` value and interpolated into a bootstrap command.
+ *
+ * The registry is process-global on purpose: a command string is assembled in
+ * one module and printed in another, so the scrub has to be reachable from the
+ * sink without threading a context object through every call site.
+ */
+export const REDACTED = "[REDACTED]";
+/**
+ * Values shorter than this are not registered *by inference*. Short strings
+ * appear inside unrelated text by coincidence, and scrubbing them would corrupt
+ * the output it is meant to protect. Every secret this provider mints is far
+ * longer, so the floor never binds on a minted value.
+ *
+ * The floor is a heuristic, and a heuristic does not overrule an explicit
+ * declaration — see `registerDeclaredSecret`.
+ */
+const MIN_SECRET_LENGTH = 8;
+const registry = new Set();
+/**
+ * Register a value this provider *inferred* is a secret: one it minted itself,
+ * or read back out of its own state. Values below `MIN_SECRET_LENGTH` are
+ * dropped — nothing declared them sensitive, so a coincidental match would
+ * corrupt output for no gain.
+ */
+export function registerSecret(value) {
+    if (typeof value !== "string")
+        return;
+    if (value.length < MIN_SECRET_LENGTH)
+        return;
+    registry.add(value);
+}
+/**
+ * Register a value something *declared* is a secret: an `env:` literal marked
+ * `sensitive: true` (D-18), or a value handed over on the operator channel
+ * (D-52). No length floor applies.
+ *
+ * `sensitive: true` on a six-digit PIN is the author stating that value must be
+ * masked. Dropping it for being short writes the PIN to disk in plaintext
+ * (CWE-532) — the exact failure this registry exists to prevent. Honouring the
+ * declaration costs an over-redacted diagnostic where the value also occurs by
+ * chance, which is recoverable; the alternative is a leaked credential, which
+ * is not.
+ *
+ * The empty string is rejected: it is not a credential, and an empty separator
+ * would splice `[REDACTED]` between every character of the text.
+ */
+export function registerDeclaredSecret(value) {
+    if (typeof value !== "string" || value === "")
+        return;
+    registry.add(value);
+}
+/** Register many secret values at once. Non-string entries are ignored. */
+export function registerSecrets(values) {
+    for (const value of values)
+        registerSecret(value);
+}
+/** Drop every registered secret. Exists for test isolation. */
+export function clearRegisteredSecrets() {
+    registry.clear();
+}
+// `scheme://user:password@host` — the password group is everything between the
+// first `:` after the userinfo and the `@`. Userinfo cannot contain `/`, `@`,
+// or whitespace, which bounds the match to a single URL.
+const CREDENTIAL_URL = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/:@]+:)([^\s/@]+)(@)/g;
+/**
+ * Scrub registered secrets and URL-embedded credentials out of `text`.
+ *
+ * Longest registered values are replaced first so that a secret which is a
+ * substring of another (a password inside its own connection URL) cannot leave
+ * a partial value behind.
+ */
+export function redactSecrets(text) {
+    let out = text;
+    const values = [...registry].sort((a, b) => b.length - a.length);
+    for (const value of values) {
+        out = out.split(value).join(REDACTED);
+    }
+    return out.replace(CREDENTIAL_URL, `$1${REDACTED}$3`);
+}
+//# sourceMappingURL=redact.js.map

package/dist/resources/identifiers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Guards for values that reach a SQL statement by interpolation.
+ *
+ * On a first run these values are safe by construction: the database and user
+ * names derive from a schema-validated app name, and `generatePassword()`
+ * emits base64url. Every later run reuses whatever `.launchfile/state.json`
+ * holds, and `loadState()` (state.ts) `JSON.parse`s that file with no
+ * validation. The file sits inside the cloned repo, so on the reuse path every
+ * value below is attacker-controlled.
+ *
+ * Argv execution keeps the shell out of these commands; these checks keep the
+ * SQL parser out of them. Both are needed: `mysql -e` runs `;`-separated
+ * statements and connects as root, so a quote that escapes an identifier or a
+ * password literal is a full statement injection with no shell involved.
+ */
+/** Alphanumeric + underscore — safe as a SQL identifier and as a shell arg. */
+export declare const SAFE_IDENTIFIER: RegExp;
+/** base64url, the exact alphabet `generatePassword()` emits. No quote fits. */
+export declare const SAFE_PASSWORD: RegExp;
+export declare function assertSafeIdentifier(value: string, label: string): void;
+export declare function assertSafePassword(value: string): void;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/resources/identifiers.js

@@ -0,0 +1,31 @@
+/**
+ * Guards for values that reach a SQL statement by interpolation.
+ *
+ * On a first run these values are safe by construction: the database and user
+ * names derive from a schema-validated app name, and `generatePassword()`
+ * emits base64url. Every later run reuses whatever `.launchfile/state.json`
+ * holds, and `loadState()` (state.ts) `JSON.parse`s that file with no
+ * validation. The file sits inside the cloned repo, so on the reuse path every
+ * value below is attacker-controlled.
+ *
+ * Argv execution keeps the shell out of these commands; these checks keep the
+ * SQL parser out of them. Both are needed: `mysql -e` runs `;`-separated
+ * statements and connects as root, so a quote that escapes an identifier or a
+ * password literal is a full statement injection with no shell involved.
+ */
+/** Alphanumeric + underscore — safe as a SQL identifier and as a shell arg. */
+export const SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/** base64url, the exact alphabet `generatePassword()` emits. No quote fits. */
+export const SAFE_PASSWORD = /^[A-Za-z0-9_-]+$/;
+export function assertSafeIdentifier(value, label) {
+    if (!SAFE_IDENTIFIER.test(value)) {
+        throw new Error(`Invalid ${label} in .launchfile/state.json: ${JSON.stringify(value)}`);
+    }
+}
+export function assertSafePassword(value) {
+    // The value itself never reaches the message — it is a live credential.
+    if (!SAFE_PASSWORD.test(value)) {
+        throw new Error("Invalid database password in .launchfile/state.json: expected base64url");
+    }
+}
+//# sourceMappingURL=identifiers.js.map

package/dist/resources/index.d.ts

@@ -3,8 +3,8 @@
  *
  * Maps resource type names to their provisioner implementations.
  */
-import type { ResourceProvisioner } from "./types.js";
-export declare function getProvisioner(type: string): ResourceProvisioner | undefined;
+import type { ResourceProvisioner, ShellRunner } from "./types.js";
+export declare function getProvisioner(type: string, deps?: Partial<ShellRunner>): ResourceProvisioner | undefined;
 export declare function supportedResourceTypes(): string[];
-export type { ResourceProvisioner, ResourceProperties, ProvisionOpts } from "./types.js";
+export type { ResourceProvisioner, ResourceProperties, ProvisionOpts, ShellRunner, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/resources/index.js

@@ -7,17 +7,28 @@ import { PostgresProvisioner } from "./postgres.js";
 import { RedisProvisioner } from "./redis.js";
 import { SqliteProvisioner } from "./sqlite.js";
 import { MysqlProvisioner } from "./mysql.js";
-const provisioners = {
-    postgres: new PostgresProvisioner(),
-    redis: new RedisProvisioner(),
-    sqlite: new SqliteProvisioner(),
-    mysql: new MysqlProvisioner(),
-    mariadb: new MysqlProvisioner(), // MariaDB is MySQL-compatible
-};
-export function getProvisioner(type) {
-    return provisioners[type];
+/**
+ * One factory per supported type, rather than one instance, so a caller can
+ * supply the shell a provisioner runs against. The conformance test
+ * (`__tests__/resource-conformance.test.ts`) is the caller that needs it: it
+ * walks this registry so the check covers every supported type, and no type can
+ * fall out of the check by being listed in only one of two places.
+ *
+ * The map has a null prototype, so a lookup keyed by a resource type read out
+ * of a Launchfile resolves to `undefined` for `constructor`, `__proto__` and
+ * every other `Object.prototype` key rather than an inherited value.
+ */
+const factories = Object.assign(Object.create(null), {
+    postgres: (deps) => new PostgresProvisioner(deps),
+    redis: (deps) => new RedisProvisioner(deps),
+    sqlite: () => new SqliteProvisioner(),
+    mysql: (deps) => new MysqlProvisioner(deps),
+    mariadb: (deps) => new MysqlProvisioner(deps), // MariaDB is MySQL-compatible
+});
+export function getProvisioner(type, deps) {
+    return factories[type]?.(deps);
 }
 export function supportedResourceTypes() {
-    return Object.keys(provisioners);
+    return Object.keys(factories);
 }
 //# sourceMappingURL=index.js.map

package/dist/resources/mysql.d.ts

@@ -3,9 +3,11 @@
  */
 import type { NormalizedRequirement } from "@launchfile/sdk";
 import type { ResourceState } from "../state.js";
-import type { ProvisionOpts, ResourceProperties, ResourceProvisioner } from "./types.js";
+import type { ProvisionOpts, ResourceProperties, ResourceProvisioner, ShellRunner } from "./types.js";
 export declare class MysqlProvisioner implements ResourceProvisioner {
+    #private;
     readonly type = "mysql";
+    constructor(deps?: Partial<ShellRunner>);
     isRunning(): Promise<boolean>;
     provision(req: NormalizedRequirement, opts: ProvisionOpts, existingState?: ResourceState): Promise<{
         properties: ResourceProperties;

package/dist/resources/mysql.js

@@ -3,22 +3,40 @@
  */
 import { shell, shellOk } from "../shell.js";
 import { generatePassword } from "../secret-generator.js";
+import { assertSafeIdentifier, assertSafePassword, SAFE_IDENTIFIER, } from "./identifiers.js";
 const DEFAULT_PORT = 3306;
 const DEFAULT_HOST = "localhost";
-// Security: validate identifiers before interpolating into shell/SQL commands
-const SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/** Connection flags shared by every mysql invocation, as argv elements. */
+function mysqlArgs() {
+    return ["-h", DEFAULT_HOST, "-u", "root"];
+}
 export class MysqlProvisioner {
     type = "mysql";
+    #shell;
+    #shellOk;
+    constructor(deps = {}) {
+        this.#shell = deps.shell ?? shell;
+        this.#shellOk = deps.shellOk ?? shellOk;
+    }
     async isRunning() {
-        return shellOk("mysqladmin ping -h localhost --silent");
+        return this.#shellOk("mysqladmin", [
+            "ping",
+            "-h",
+            DEFAULT_HOST,
+            "--silent",
+        ]);
     }
     async provision(req, opts, existingState) {
         if (!(await this.isRunning())) {
             console.log("  Starting MySQL via brew...");
-            const started = await shellOk("brew services start mysql");
+            const started = await this.#shellOk("brew", [
+                "services",
+                "start",
+                "mysql",
+            ]);
             if (!started) {
-                await shell("brew install mysql");
-                await shell("brew services start mysql");
+                await this.#shell("brew", ["install", "mysql"]);
+                await this.#shell("brew", ["services", "start", "mysql"]);
             }
         }
         const resourceName = req.name ?? req.type;
@@ -26,11 +44,27 @@ export class MysqlProvisioner {
         const dbName = existingState?.dbName ?? `launchfile_${safeName}`;
         const user = existingState?.user ?? `launchfile_${safeName}`;
         const password = existingState?.password ?? generatePassword();
+        // Security: all three are interpolated into the SQL below, and `mysql -e`
+        // runs `;`-separated statements as root. Fresh values cannot fail these
+        // checks; values reused from state.json are unvalidated JSON (state.ts).
+        assertSafeIdentifier(dbName, "database name");
+        assertSafeIdentifier(user, "database user");
+        assertSafePassword(password);
         const port = DEFAULT_PORT;
         // Create database and user (idempotent)
-        await shell(`mysql -h ${DEFAULT_HOST} -u root -e "CREATE DATABASE IF NOT EXISTS \\\`${dbName}\\\`;"`, { allowFailure: true });
-        await shell(`mysql -h ${DEFAULT_HOST} -u root -e "CREATE USER IF NOT EXISTS '${user}'@'${DEFAULT_HOST}' IDENTIFIED BY '${password}';"`, { allowFailure: true });
-        await shell(`mysql -h ${DEFAULT_HOST} -u root -e "GRANT ALL PRIVILEGES ON \\\`${dbName}\\\`.* TO '${user}'@'${DEFAULT_HOST}';"`, { allowFailure: true });
+        await this.#shell("mysql", [...mysqlArgs(), "-e", `CREATE DATABASE IF NOT EXISTS \`${dbName}\`;`], { allowFailure: true });
+        await this.#shell("mysql", [
+            ...mysqlArgs(),
+            "-e",
+            `CREATE USER IF NOT EXISTS '${user}'@'${DEFAULT_HOST}' IDENTIFIED BY '${password}';`,
+        ], 
+        // silent: this command embeds the generated DB password; don't echo it (CWE-532).
+        { allowFailure: true, silent: true });
+        await this.#shell("mysql", [
+            ...mysqlArgs(),
+            "-e",
+            `GRANT ALL PRIVILEGES ON \`${dbName}\`.* TO '${user}'@'${DEFAULT_HOST}';`,
+        ], { allowFailure: true });
         const url = `mysql://${user}:${password}@${DEFAULT_HOST}:${port}/${dbName}`;
         const properties = {
             url,
@@ -54,10 +88,14 @@ export class MysqlProvisioner {
     async destroy(state) {
         // Security: state values come from disk (state.json) — validate before SQL interpolation
         if (state.dbName && SAFE_IDENTIFIER.test(state.dbName)) {
-            await shell(`mysql -h ${DEFAULT_HOST} -u root -e "DROP DATABASE IF EXISTS \\\`${state.dbName}\\\`;"`, { allowFailure: true });
+            await this.#shell("mysql", [...mysqlArgs(), "-e", `DROP DATABASE IF EXISTS \`${state.dbName}\`;`], { allowFailure: true });
         }
         if (state.user && SAFE_IDENTIFIER.test(state.user)) {
-            await shell(`mysql -h ${DEFAULT_HOST} -u root -e "DROP USER IF EXISTS '${state.user}'@'${DEFAULT_HOST}';"`, { allowFailure: true });
+            await this.#shell("mysql", [
+                ...mysqlArgs(),
+                "-e",
+                `DROP USER IF EXISTS '${state.user}'@'${DEFAULT_HOST}';`,
+            ], { allowFailure: true });
         }
     }
 }

package/dist/resources/postgres.d.ts

@@ -9,9 +9,12 @@
  */
 import type { NormalizedRequirement } from "@launchfile/sdk";
 import type { ResourceState } from "../state.js";
-import type { ProvisionOpts, ResourceProperties, ResourceProvisioner } from "./types.js";
+import type { ProvisionOpts, ResourceProperties, ResourceProvisioner, ShellRunner } from "./types.js";
+export type { ShellRunner };
 export declare class PostgresProvisioner implements ResourceProvisioner {
+    #private;
     readonly type = "postgres";
+    constructor(deps?: Partial<ShellRunner>);
     isRunning(): Promise<boolean>;
     provision(req: NormalizedRequirement, opts: ProvisionOpts, existingState?: ResourceState): Promise<{
         properties: ResourceProperties;

package/dist/resources/postgres.js

@@ -9,43 +9,81 @@
  */
 import { shell, shellOk } from "../shell.js";
 import { generatePassword } from "../secret-generator.js";
+import { assertSafeIdentifier, assertSafePassword, SAFE_IDENTIFIER, } from "./identifiers.js";
 const DEFAULT_PORT = 5432;
 const DEFAULT_HOST = "localhost";
-// Security: validate identifiers before interpolating into shell/SQL commands.
-// Only alphanumeric + underscore — safe for SQL identifiers and shell args.
-const SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const READY_TIMEOUT_SECONDS = 10;
+/** Connection flags shared by every psql invocation, as argv elements. */
+function psqlArgs(port, database) {
+    return ["-h", DEFAULT_HOST, "-p", String(port), database];
+}
 export class PostgresProvisioner {
     type = "postgres";
+    #shell;
+    #shellOk;
+    constructor(deps = {}) {
+        this.#shell = deps.shell ?? shell;
+        this.#shellOk = deps.shellOk ?? shellOk;
+    }
     async isRunning() {
-        return shellOk("pg_isready -q");
+        return this.#shellOk("pg_isready", ["-q"]);
     }
     async provision(req, opts, existingState) {
         // Ensure postgres is running
         if (!(await this.isRunning())) {
             console.log("  Starting PostgreSQL via brew...");
             // Try to start; if not installed, install first
-            const started = await shellOk("brew services start postgresql");
+            const started = await this.#shellOk("brew", [
+                "services",
+                "start",
+                "postgresql",
+            ]);
             if (!started) {
                 // Try versioned formula
-                await shell("brew install postgresql@16");
-                await shell("brew services start postgresql@16");
+                await this.#shell("brew", ["install", "postgresql@16"]);
+                await this.#shell("brew", ["services", "start", "postgresql@16"]);
             }
         }
-        // Wait for ready
-        await shell("pg_isready --timeout=10", { allowFailure: true });
+        // pg_isready blocks until the server answers or the timeout expires, so a
+        // false here means Postgres never came up — every psql call below would
+        // fail with a connection error that says nothing about the real cause.
+        const ready = await this.#shellOk("pg_isready", [
+            `--timeout=${READY_TIMEOUT_SECONDS}`,
+        ]);
+        if (!ready) {
+            throw new Error(`PostgreSQL did not accept connections within ${READY_TIMEOUT_SECONDS}s. ` +
+                `Check \`brew services list\` and \`pg_isready\`.`);
+        }
         // Determine database and user names
         const resourceName = req.name ?? req.type;
         const safeName = opts.appName.replace(/-/g, "_");
         const dbName = existingState?.dbName ?? `launchfile_${safeName}`;
         const user = existingState?.user ?? `launchfile_${safeName}`;
         const password = existingState?.password ?? generatePassword();
+        // Security: all three are interpolated into the psql commands below. A
+        // schema-validated app name and a generated password can never fail these
+        // checks, but existingState comes from the on-disk state file, which is
+        // JSON.parse'd without validation (state.ts).
+        assertSafeIdentifier(dbName, "database name");
+        assertSafeIdentifier(user, "database user");
+        assertSafePassword(password);
         const port = DEFAULT_PORT;
         // Create user (idempotent)
-        await shell(`psql -h ${DEFAULT_HOST} -p ${port} postgres -c "DO \\$\\$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${user}') THEN CREATE ROLE ${user} WITH LOGIN PASSWORD '${password}' CREATEDB; END IF; END \\$\\$;"`, { allowFailure: true });
+        await this.#shell("psql", [
+            ...psqlArgs(port, "postgres"),
+            "-c",
+            `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${user}') THEN CREATE ROLE ${user} WITH LOGIN PASSWORD '${password}' CREATEDB; END IF; END $$;`,
+        ], 
+        // silent: this command embeds the generated DB password; don't echo it (CWE-532).
+        { allowFailure: true, silent: true });
         // Create database (idempotent)
-        const dbExists = await shellOk(`psql -h ${DEFAULT_HOST} -p ${port} postgres -tAc "SELECT 1 FROM pg_database WHERE datname='${dbName}'"`);
+        const dbExists = await this.#shellOk("psql", [
+            ...psqlArgs(port, "postgres"),
+            "-tAc",
+            `SELECT 1 FROM pg_database WHERE datname='${dbName}'`,
+        ]);
         if (!dbExists) {
-            await shell(`createdb -h ${DEFAULT_HOST} -p ${port} -O ${user} ${dbName}`, { allowFailure: true });
+            await this.#shell("createdb", ["-h", DEFAULT_HOST, "-p", String(port), "-O", user, dbName], { allowFailure: true });
         }
         // Handle extensions from config
         // Security: extension names come from Launchfile config (untrusted input).
@@ -59,7 +97,11 @@ export class PostgresProvisioner {
                     console.warn(`  Skipping invalid extension name: ${ext}`);
                     continue;
                 }
-                await shell(`psql -h ${DEFAULT_HOST} -p ${port} ${dbName} -c "CREATE EXTENSION IF NOT EXISTS \\"${ext}\\";"`, { allowFailure: true });
+                await this.#shell("psql", [
+                    ...psqlArgs(port, dbName),
+                    "-c",
+                    `CREATE EXTENSION IF NOT EXISTS "${ext}";`,
+                ], { allowFailure: true });
             }
         }
         const url = `postgresql://${user}:${password}@${DEFAULT_HOST}:${port}/${dbName}`;
@@ -85,12 +127,16 @@ export class PostgresProvisioner {
     async destroy(state) {
         // Security: state values come from disk (state.json) — validate before SQL interpolation
         if (state.dbName && SAFE_IDENTIFIER.test(state.dbName)) {
-            await shell(`dropdb -h ${DEFAULT_HOST} --if-exists ${state.dbName}`, {
-                allowFailure: true,
-            });
+            await this.#shell("dropdb", ["-h", DEFAULT_HOST, "--if-exists", state.dbName], { allowFailure: true });
         }
         if (state.user && SAFE_IDENTIFIER.test(state.user)) {
-            await shell(`psql -h ${DEFAULT_HOST} postgres -c "DROP ROLE IF EXISTS ${state.user};"`, { allowFailure: true });
+            await this.#shell("psql", [
+                "-h",
+                DEFAULT_HOST,
+                "postgres",
+                "-c",
+                `DROP ROLE IF EXISTS ${state.user};`,
+            ], { allowFailure: true });
         }
         // Don't stop the brew service — it's shared
     }

package/dist/resources/redis.d.ts

@@ -3,9 +3,11 @@
  */
 import type { NormalizedRequirement } from "@launchfile/sdk";
 import type { ResourceState } from "../state.js";
-import type { ProvisionOpts, ResourceProperties, ResourceProvisioner } from "./types.js";
+import type { ProvisionOpts, ResourceProperties, ResourceProvisioner, ShellRunner } from "./types.js";
 export declare class RedisProvisioner implements ResourceProvisioner {
+    #private;
     readonly type = "redis";
+    constructor(deps?: Partial<ShellRunner>);
     isRunning(): Promise<boolean>;
     provision(req: NormalizedRequirement, _opts: ProvisionOpts, _existingState?: ResourceState): Promise<{
         properties: ResourceProperties;

package/dist/resources/redis.js

@@ -6,16 +6,26 @@ const DEFAULT_PORT = 6379;
 const DEFAULT_HOST = "localhost";
 export class RedisProvisioner {
     type = "redis";
+    #shell;
+    #shellOk;
+    constructor(deps = {}) {
+        this.#shell = deps.shell ?? shell;
+        this.#shellOk = deps.shellOk ?? shellOk;
+    }
     async isRunning() {
-        return shellOk("redis-cli ping");
+        return this.#shellOk("redis-cli", ["ping"]);
     }
     async provision(req, _opts, _existingState) {
         if (!(await this.isRunning())) {
             console.log("  Starting Redis via brew...");
-            const started = await shellOk("brew services start redis");
+            const started = await this.#shellOk("brew", [
+                "services",
+                "start",
+                "redis",
+            ]);
             if (!started) {
-                await shell("brew install redis");
-                await shell("brew services start redis");
+                await this.#shell("brew", ["install", "redis"]);
+                await this.#shell("brew", ["services", "start", "redis"]);
             }
         }
         const port = DEFAULT_PORT;

package/dist/resources/sqlite.js

@@ -14,10 +14,10 @@ export class SqliteProvisioner {
         const dataDir = join(opts.projectDir, ".launchfile", "data", "sqlite");
         await mkdir(dataDir, { recursive: true });
         const dbPath = join(dataDir, `${safeName}.db`);
+        // SPEC.md § Resource Property Vocabulary gives sqlite `url` and `path`
+        // only. A file has no host and no port, so neither is exposed.
         const properties = {
             url: `sqlite://${dbPath}`,
-            host: "",
-            port: 0,
             path: dbPath,
         };
         const state = {

package/dist/resources/types.d.ts

@@ -5,12 +5,22 @@
  * to handle install, start, database creation, and teardown.
  */
 import type { NormalizedRequirement } from "@launchfile/sdk";
+import type { shell, shellOk } from "../shell.js";
 import type { ResourceState } from "../state.js";
-/** Properties that a provisioned resource exposes for expression resolution */
+/**
+ * Properties that a provisioned resource exposes for expression resolution.
+ *
+ * Only `url` is required. A resource type addressed by something other than a
+ * network endpoint — sqlite is a file — has no host and no port, and fabricating
+ * `host: ""` / `port: 0` to satisfy the type would report a value an app could
+ * act on (PROVIDERS.md §10.8, D-52). Omitted properties resolve to the empty
+ * string through the standard unknown-property rule, so leaving them out costs
+ * the caller nothing.
+ */
 export interface ResourceProperties {
     url: string;
-    host: string;
-    port: number;
+    host?: string;
+    port?: number;
     user?: string;
     password?: string;
     name?: string;
@@ -21,6 +31,14 @@ export interface ResourceProperties {
     region?: string;
     [key: string]: string | number | undefined;
 }
+/**
+ * The shell surface a provisioner runs against. Injecting it lets tests drive
+ * the provisioning sequence without Homebrew or a live server.
+ */
+export interface ShellRunner {
+    shell: typeof shell;
+    shellOk: typeof shellOk;
+}
 export interface ProvisionOpts {
     appName: string;
     projectDir: string;

package/dist/runtimes/bun.js

@@ -9,8 +9,8 @@ export class BunInstaller {
         return undefined;
     }
     async install(_version) {
-        if (!(await shellOk("which bun"))) {
-            await shell("brew install bun");
+        if (!(await shellOk("which", ["bun"]))) {
+            await shell("brew", ["install", "bun"]);
         }
     }
     async shellEnv(_version) {

package/dist/runtimes/installed-versions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Exact-match lookup against a version manager's installed list.
+ *
+ * `rbenv versions --bare` and `pyenv versions --bare` both print one version
+ * per line, so the lines are compared directly. A
+ * `… --bare | grep -q "^${version}$"` pipe would be wrong twice over: it feeds
+ * an untrusted version string to a shell, and `grep` reads it as a regex, so
+ * every `.` matches any character — an installed `3x1` would satisfy a request
+ * for `3.1` and silently skip the install.
+ */
+export declare function isInstalled(tool: "rbenv" | "pyenv", version: string): Promise<boolean>;
+//# sourceMappingURL=installed-versions.d.ts.map

package/dist/runtimes/installed-versions.js

@@ -0,0 +1,21 @@
+/**
+ * Exact-match lookup against a version manager's installed list.
+ *
+ * `rbenv versions --bare` and `pyenv versions --bare` both print one version
+ * per line, so the lines are compared directly. A
+ * `… --bare | grep -q "^${version}$"` pipe would be wrong twice over: it feeds
+ * an untrusted version string to a shell, and `grep` reads it as a regex, so
+ * every `.` matches any character — an installed `3x1` would satisfy a request
+ * for `3.1` and silently skip the install.
+ */
+import { shell } from "../shell.js";
+export async function isInstalled(tool, version) {
+    const result = await shell(tool, ["versions", "--bare"], {
+        silent: true,
+        allowFailure: true,
+    });
+    if (result.exitCode !== 0)
+        return false;
+    return result.stdout.split("\n").some((line) => line.trim() === version);
+}
+//# sourceMappingURL=installed-versions.js.map

package/dist/runtimes/node.js

@@ -30,23 +30,28 @@ export class NodeInstaller {
         return undefined;
     }
     async install(version) {
+        // `version` is the verbatim contents of .nvmrc / .node-version /
+        // package.json engines.node in the target repo — untrusted input. It goes
+        // in as an argv element so it can never be read as shell syntax.
         // Prefer fnm (faster), fall back to nvm
-        if (await shellOk("which fnm")) {
-            await shell(`fnm install ${version}`);
+        if (await shellOk("which", ["fnm"])) {
+            await shell("fnm", ["install", version]);
         }
-        else if (await shellOk("which nvm")) {
-            await shell(`nvm install ${version}`);
+        else if (await shellOk("which", ["nvm"])) {
+            await shell("nvm", ["install", version]);
         }
         else {
             console.log("  Installing fnm via brew...");
-            await shell("brew install fnm");
-            await shell(`fnm install ${version}`);
+            await shell("brew", ["install", "fnm"]);
+            await shell("fnm", ["install", version]);
         }
     }
     async shellEnv(_version) {
-        if (await shellOk("which fnm")) {
+        if (await shellOk("which", ["fnm"])) {
             try {
-                const result = await shell("fnm env --shell bash", { silent: true });
+                const result = await shell("fnm", ["env", "--shell", "bash"], {
+                    silent: true,
+                });
                 return parseShellEnv(result.stdout);
             }
             catch {