vyft 0.2.0-alpha → 0.4.0-alpha

package/dist/local/runtime.js

@@ -0,0 +1,391 @@
+import { randomBytes } from "node:crypto";
+import { PassThrough } from "node:stream";
+import Docker from "dockerode";
+import { logger as defaultLogger } from "../logger.js";
+import { isInterpolation, isReference } from "../resource.js";
+/**
+ * Docker runtime for local development.
+ *
+ * Runs managed infrastructure (databases, caches, etc.) as plain Docker
+ * containers with ports published to localhost. Secrets are generated
+ * in-memory and injected as environment variables.
+ */
+export class LocalRuntime {
+    docker;
+    project;
+    log;
+    secretValues = new Map();
+    containers = [];
+    networkName;
+    constructor(project, opts) {
+        this.docker = new Docker({ socketPath: "/var/run/docker.sock" });
+        this.project = project;
+        this.networkName = `${project}-dev`;
+        this.log = (opts?.parentLogger ?? defaultLogger).child({
+            component: "local-runtime",
+            project,
+        });
+    }
+    /** Create bridge network for inter-container DNS. */
+    async ensureInfrastructure() {
+        const networks = await this.docker.listNetworks({
+            filters: JSON.stringify({ name: [this.networkName] }),
+        });
+        const exists = networks.some((n) => n.Name === this.networkName);
+        if (!exists) {
+            this.log.debug({ network: this.networkName }, "creating bridge network");
+            await this.docker.createNetwork({
+                Name: this.networkName,
+                Driver: "bridge",
+                Labels: {
+                    "vyft.dev": "true",
+                    "vyft.project": this.project,
+                },
+            });
+        }
+    }
+    /** Generate a random secret value and store it in memory. */
+    createSecret(secret) {
+        const length = secret.config.length || 32;
+        const value = randomBytes(length).toString("base64url");
+        this.secretValues.set(secret.id, value);
+        this.log.debug({ secretName: secret.id }, "secret generated");
+    }
+    /** Get the generated value for a secret. */
+    getSecretValue(id) {
+        return this.secretValues.get(id);
+    }
+    /** Create a Docker volume for persistent data. */
+    async createVolume(volume) {
+        const name = volume.id;
+        try {
+            await this.docker.getVolume(name).inspect();
+            this.log.debug({ volumeName: name }, "volume already exists");
+            return;
+        }
+        catch {
+            // Volume doesn't exist, create it
+        }
+        await this.docker.createVolume({
+            Name: name,
+            Labels: {
+                "vyft.dev": "true",
+                "vyft.project": this.project,
+            },
+        });
+        this.log.debug({ volumeName: name }, "volume created");
+    }
+    /**
+     * Resolve env vars for a managed service container.
+     *
+     * Secrets become plain `KEY=<value>` env vars.
+     * Interpolations are fully resolved with generated secret values.
+     */
+    resolveEnv(env) {
+        const result = [];
+        for (const [key, value] of Object.entries(env)) {
+            if (typeof value === "string") {
+                result.push(`${key}=${value}`);
+            }
+            else if (isReference(value)) {
+                const secretValue = this.secretValues.get(value.id);
+                if (!secretValue) {
+                    throw new Error(`Secret ${value.id} not yet generated`);
+                }
+                result.push(`${key}=${secretValue}`);
+            }
+            else if (isInterpolation(value)) {
+                const parts = [];
+                for (let i = 0; i < value.strings.length; i++) {
+                    parts.push(value.strings[i]);
+                    if (i < value.values.length) {
+                        const v = value.values[i];
+                        if (isReference(v)) {
+                            const secretValue = this.secretValues.get(v.id);
+                            if (!secretValue) {
+                                throw new Error(`Secret ${v.id} not yet generated`);
+                            }
+                            parts.push(secretValue);
+                        }
+                        else {
+                            parts.push(v);
+                        }
+                    }
+                }
+                result.push(`${key}=${parts.join("")}`);
+            }
+        }
+        return result;
+    }
+    /**
+     * Build an entrypoint wrapper that writes secret values to /run/secrets/
+     * before exec'ing the original entrypoint.
+     *
+     * This is needed because some factory images (e.g. redis) read passwords
+     * from `/run/secrets/*-password` via shell glob.
+     */
+    buildSecretInit(secrets, originalEntrypoint, originalCmd) {
+        if (secrets.length === 0) {
+            return { entrypoint: originalEntrypoint, cmd: originalCmd };
+        }
+        const writeCommands = secrets
+            .map((s) => `printf '%s' "$${s.envVar}" > /run/secrets/${s.name}`)
+            .join(" && ");
+        // Build the original command to exec
+        const original = [...originalEntrypoint, ...originalCmd];
+        const execCmd = original.length > 0 ? `exec ${original.map(shellEscape).join(" ")}` : "";
+        const script = `mkdir -p /run/secrets && ${writeCommands}${execCmd ? ` && ${execCmd}` : ""}`;
+        return {
+            entrypoint: ["sh", "-c", script],
+            cmd: [],
+        };
+    }
+    /** Pull, create, and start a container for a managed service. */
+    async createService(service) {
+        const config = service.config;
+        const image = typeof config.image === "string" ? config.image : `${service.id}:latest`;
+        const port = config.port || 3000;
+        // Stop and remove existing container if present
+        await this.removeContainer(service.id);
+        // Pull image
+        this.log.debug({ image }, "pulling image");
+        const pullStream = await this.docker.pull(image);
+        await new Promise((resolve, reject) => {
+            this.docker.modem.followProgress(pullStream, (err) => err ? reject(err) : resolve());
+        });
+        // Resolve env
+        const envList = config.env ? this.resolveEnv(config.env) : [];
+        // Collect secrets that need /run/secrets/ files
+        const secretMappings = [];
+        if (config.env) {
+            let idx = 0;
+            for (const [, value] of Object.entries(config.env)) {
+                if (isReference(value)) {
+                    const envVar = `__VYFT_S${idx}`;
+                    secretMappings.push({
+                        name: value.id.replace(/^.*-/, ""), // short name e.g. "db-password" -> "password"
+                        envVar,
+                    });
+                    // The full id as a file too, for glob patterns like *-password
+                    secretMappings.push({
+                        name: value.id,
+                        envVar,
+                    });
+                    const secretVal = this.secretValues.get(value.id);
+                    if (secretVal) {
+                        envList.push(`${envVar}=${secretVal}`);
+                    }
+                    idx++;
+                }
+            }
+        }
+        // Inspect image for default entrypoint/cmd
+        const imageInfo = await this.docker.getImage(image).inspect();
+        const rawEntrypoint = imageInfo.Config?.Entrypoint ?? [];
+        const defaultEntrypoint = Array.isArray(rawEntrypoint)
+            ? rawEntrypoint
+            : [rawEntrypoint];
+        const rawCmd = imageInfo.Config?.Cmd ?? [];
+        const defaultCmd = Array.isArray(rawCmd) ? rawCmd : [rawCmd];
+        // Use config.command if specified, otherwise image defaults
+        const userCmd = config.command ?? defaultCmd;
+        const { entrypoint, cmd } = this.buildSecretInit(secretMappings, defaultEntrypoint, userCmd);
+        // Build volume mounts
+        const mounts = config.volumes?.map(({ volume, mount }) => ({
+            Type: "volume",
+            Source: volume.id,
+            Target: mount,
+        }));
+        // Health check
+        const healthCheck = config.healthCheck
+            ? {
+                Test: ["CMD", ...config.healthCheck.command],
+                Interval: config.healthCheck.interval
+                    ? parseDurationNs(config.healthCheck.interval)
+                    : undefined,
+                Timeout: config.healthCheck.timeout
+                    ? parseDurationNs(config.healthCheck.timeout)
+                    : undefined,
+                Retries: config.healthCheck.retries,
+                StartPeriod: config.healthCheck.startPeriod
+                    ? parseDurationNs(config.healthCheck.startPeriod)
+                    : undefined,
+            }
+            : undefined;
+        const containerName = `${service.id}-dev`;
+        this.log.debug({ containerName, image, port }, "creating container");
+        const container = await this.docker.createContainer({
+            name: containerName,
+            Image: image,
+            Entrypoint: entrypoint.length > 0 ? entrypoint : undefined,
+            Cmd: cmd.length > 0 ? cmd : undefined,
+            Env: envList,
+            ExposedPorts: { [`${port}/tcp`]: {} },
+            Healthcheck: healthCheck,
+            Labels: {
+                "vyft.dev": "true",
+                "vyft.project": this.project,
+                "vyft.service": service.id,
+            },
+            HostConfig: {
+                PortBindings: {
+                    [`${port}/tcp`]: [{ HostIp: "127.0.0.1", HostPort: `${port}` }],
+                },
+                NetworkMode: this.networkName,
+                Mounts: mounts,
+            },
+        });
+        await container.start();
+        this.containers.push({
+            id: service.id,
+            name: containerName,
+            containerId: container.id,
+        });
+        this.log.debug({ containerName, port }, "container started");
+        return port;
+    }
+    /** Wait for a container to pass its health check. */
+    async waitForHealthy(id, timeoutMs = 120000) {
+        const info = this.containers.find((c) => c.id === id);
+        if (!info)
+            return;
+        const start = performance.now();
+        const interval = 1000;
+        this.log.debug({ resourceId: id }, "waiting for healthy");
+        while (performance.now() - start < timeoutMs) {
+            const container = this.docker.getContainer(info.containerId);
+            const data = await container.inspect();
+            const health = data.State?.Health?.Status;
+            if (health === "healthy") {
+                this.log.debug({ resourceId: id }, "container is healthy");
+                return;
+            }
+            if (health === undefined) {
+                // No health check configured, just check if running
+                if (data.State?.Running) {
+                    this.log.debug({ resourceId: id }, "container running (no health check)");
+                    return;
+                }
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        throw new Error(`Container ${id} did not become healthy within ${timeoutMs}ms`);
+    }
+    /** Stream logs from a container. */
+    async *containerLogs(id) {
+        const info = this.containers.find((c) => c.id === id);
+        if (!info)
+            return;
+        const container = this.docker.getContainer(info.containerId);
+        const stream = await container.logs({
+            stdout: true,
+            stderr: true,
+            follow: true,
+            tail: 0,
+        });
+        const buffer = [];
+        let notify = null;
+        let done = false;
+        const push = (entry) => {
+            buffer.push(entry);
+            if (notify) {
+                const n = notify;
+                notify = null;
+                n();
+            }
+        };
+        const stdoutPT = new PassThrough();
+        const stderrPT = new PassThrough();
+        stdoutPT.on("data", (chunk) => {
+            for (const line of chunk.toString().split("\n")) {
+                if (line)
+                    push({ stream: "stdout", text: line });
+            }
+        });
+        stderrPT.on("data", (chunk) => {
+            for (const line of chunk.toString().split("\n")) {
+                if (line)
+                    push({ stream: "stderr", text: line });
+            }
+        });
+        this.docker.modem.demuxStream(stream, stdoutPT, stderrPT);
+        stream.on("end", () => {
+            done = true;
+            if (notify) {
+                const n = notify;
+                notify = null;
+                n();
+            }
+        });
+        while (!done || buffer.length > 0) {
+            if (buffer.length === 0) {
+                await new Promise((r) => {
+                    notify = r;
+                });
+            }
+            while (buffer.length > 0) {
+                yield buffer.shift();
+            }
+        }
+    }
+    /** Stop and remove all managed containers (keep volumes). */
+    async stop() {
+        for (const info of this.containers) {
+            try {
+                const container = this.docker.getContainer(info.containerId);
+                await container.stop({ t: 5 });
+                await container.remove();
+                this.log.debug({ containerName: info.name }, "container stopped");
+            }
+            catch {
+                this.log.debug({ containerName: info.name }, "container already stopped");
+            }
+        }
+        this.containers = [];
+    }
+    /** List running dev containers for this project. */
+    async listContainers() {
+        const containers = await this.docker.listContainers({
+            filters: JSON.stringify({
+                label: ["vyft.dev=true", `vyft.project=${this.project}`],
+            }),
+        });
+        return containers.map((c) => ({
+            id: c.Labels["vyft.service"] || "",
+            name: c.Names[0]?.replace(/^\//, "") || "",
+            containerId: c.Id,
+        }));
+    }
+    async removeContainer(serviceId) {
+        const containerName = `${serviceId}-dev`;
+        try {
+            const container = this.docker.getContainer(containerName);
+            await container.stop({ t: 2 });
+            await container.remove();
+            this.log.debug({ containerName }, "removed existing container");
+        }
+        catch {
+            // Container didn't exist
+        }
+    }
+}
+function parseDurationNs(duration) {
+    const match = duration.match(/^(\d+)(ms|s|m|h)$/);
+    if (!match?.[1] || !match[2]) {
+        throw new Error(`Invalid duration format: ${duration}`);
+    }
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    const multipliers = {
+        ms: 1_000_000,
+        s: 1_000_000_000,
+        m: 60_000_000_000,
+        h: 3_600_000_000_000,
+    };
+    return value * multipliers[unit];
+}
+function shellEscape(s) {
+    if (/^[a-zA-Z0-9_./:=-]+$/.test(s))
+        return s;
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/dist/proxy.d.ts

@@ -0,0 +1,16 @@
+export interface ReverseProxy {
+    /** Ensure the proxy service is running and configured. */
+    ensure(): Promise<void>;
+    /** Register or update a route for a resource. */
+    addRoute(resourceId: string, route: string, target: {
+        host: string;
+        port: number;
+    }): Promise<void>;
+    /** Remove a route for a resource. No-op if it doesn't exist. */
+    removeRoute(resourceId: string): Promise<void>;
+    /** Stream proxy access logs. */
+    logs(options: {
+        follow?: boolean;
+        tail?: number;
+    }): Promise<void>;
+}

package/dist/resource.d.ts

@@ -1,78 +1,181 @@
 import type { RuntimeRef } from "./symbols.js";
+/** Discriminant for the four resource kinds. */
 export type ResourceType = "volume" | "secret" | "service" | "site";
-export type VolumeConfig = {};
+/** Configuration for a persistent volume. */
+export interface VolumeConfig {
+    /** Human-readable size hint (e.g. `"10GB"`). Informational only. */
+    size?: string;
+}
+/** Configuration for an auto-generated secret. */
 export interface SecretConfig {
+    /** Length of the generated random value in bytes. */
     length?: number;
 }
+/** Container health-check configuration. */
 export interface HealthCheckConfig {
+    /** Command to run inside the container (e.g. `["pg_isready", "-U", "postgres"]`). */
     command: string[];
+    /** Time between checks (e.g. `"5s"`, `"1m"`). */
     interval?: string;
+    /** Maximum time a single check may take. */
     timeout?: string;
+    /** Consecutive failures required to mark unhealthy. */
     retries?: number;
+    /** Grace period before the first check runs. */
     startPeriod?: string;
 }
+/** CPU and memory limits for a service. */
 export interface ResourceLimits {
+    /** Memory ceiling (e.g. `"512MB"`, `"2GB"`). */
     memory?: string;
+    /** CPU core limit (e.g. `0.5`, `2`). */
     cpus?: number;
 }
+/** A persistent storage volume. */
 export interface Volume extends RuntimeRef {
     type: "volume";
     id: string;
     config: VolumeConfig;
 }
+/** An auto-generated secret value, injected at deploy time. */
 export interface Secret extends RuntimeRef {
     type: "secret";
     id: string;
     config: SecretConfig;
 }
+/**
+ * A long-running service (container).
+ *
+ * Use `host` and `port` to reference this service from other services
+ * in the same project, or `url` for the full address.
+ */
 export interface Service extends RuntimeRef {
     type: "service";
     id: string;
     config: ServiceConfig;
+    /** Internal hostname reachable by other services. */
     host: string;
+    /** Port the service listens on. */
     port: number;
+    /** Full URL — `https://<route>` if routed, otherwise `http://<host>:<port>`. */
     url: string;
 }
+/** A static site served via Caddy. */
 export interface Site extends RuntimeRef {
     type: "site";
     id: string;
     config: SiteConfig;
+    /** Public URL derived from the route (e.g. `https://example.com`). */
     url: string;
 }
+/** Union of all deployable resource types. */
 export type Resource = Volume | Secret | Service | Site;
+/**
+ * A deferred reference to a value that isn't known until deploy time.
+ *
+ * Currently only {@link Secret} produces deferred values. Expand this
+ * union as more resources gain deferred outputs.
+ */
 export type Reference = Secret;
+/**
+ * A tagged-template interpolation that mixes literal strings with
+ * {@link Reference} values. Created via {@link interpolate}.
+ *
+ * @example
+ * ```ts
+ * const connStr = interpolate`postgres://user:${dbPassword}@${db.host}:5432/app`;
+ * ```
+ */
 export interface Interpolation {
     type: "interpolation";
     strings: TemplateStringsArray;
     values: Array<Reference | string>;
 }
+/**
+ * A value that can appear in a service's `env` map.
+ *
+ * - Plain `string` — set verbatim.
+ * - {@link Reference} — resolved at deploy time (e.g. a secret).
+ * - {@link Interpolation} — a template mixing strings and references.
+ */
 export type EnvValue = string | Reference | Interpolation;
+/** Type-guard: returns `true` if `value` is a {@link Reference}. */
 export declare function isReference(value: unknown): value is Reference;
+/** Type-guard: returns `true` if `value` is a {@link Secret}. */
 export declare function isSecret(value: unknown): value is Secret;
+/** Type-guard: returns `true` if `value` is an {@link Interpolation}. */
 export declare function isInterpolation(value: unknown): value is Interpolation;
+/** Configuration for a long-running service. */
 export interface ServiceConfig {
+    /**
+     * Container image to run.
+     *
+     * - `string` — a registry image (e.g. `"node:22"`).
+     * - `{ context, dockerfile }` — build from a local Dockerfile.
+     */
     image: string | {
         context?: string;
         dockerfile?: string;
     };
+    /** Public route to expose (e.g. `"api.example.com"` or `"example.com/api"`). */
     route?: string;
+    /** Port the container listens on. Defaults to `3000`. */
     port?: number;
+    /** Environment variables injected into the container. */
     env?: Record<string, EnvValue>;
+    /** Override the container's default command. */
     command?: string[];
+    /** Volumes to mount into the container. */
     volumes?: Array<{
         volume: Volume;
         mount: string;
     }>;
+    /** Services that must be healthy before this one starts. */
+    dependsOn?: Service[];
+    /** Container health check. */
+    healthCheck?: HealthCheckConfig;
+    /**
+     * Restart behaviour on failure.
+     * @defaultValue `"any"`
+     */
+    restartPolicy?: "none" | "on-failure" | "any";
+    /** Local development configuration. Used by `vyft dev`. */
+    dev?: {
+        /** Shell command to run (e.g. `"bun run dev"`). */
+        command: string;
+        /** Working directory relative to project root. */
+        cwd?: string;
+    };
 }
+/** Configuration for a static site. */
 export interface SiteConfig {
+    /** Domain (and optional path) to serve the site on. */
     route: string;
+    /**
+     * Enable single-page application mode. When `true`, all requests that
+     * don't match a static file are rewritten to `/index.html`.
+     * @defaultValue `true`
+     */
     spa?: boolean;
+    /** Build settings for the static site. */
     build: {
+        /** Working directory containing the source (relative to project root). */
         cwd: string;
+        /** Directory containing the built output (relative to `cwd`). Defaults to `"dist"`. */
         output?: string;
+        /** Build command to run (e.g. `"npm run build"`). */
         command?: string;
+        /** Environment variables passed to the build command. */
         env?: Record<string, string>;
     };
 }
+/**
+ * Validates a resource ID.
+ * @throws If the ID is empty, too long, or contains invalid characters.
+ */
 export declare function validateId(id: string): void;
+/**
+ * Validates a route string.
+ * @throws If the route is empty or not a valid domain with optional path.
+ */
 export declare function validateRoute(route: string): void;

package/dist/resource.js

@@ -1,19 +1,25 @@
+/** Type-guard: returns `true` if `value` is a {@link Reference}. */
 export function isReference(value) {
     return isSecret(value);
 }
+/** Type-guard: returns `true` if `value` is a {@link Secret}. */
 export function isSecret(value) {
     return (typeof value === "object" &&
         value !== null &&
         value.type === "secret");
 }
+/** Type-guard: returns `true` if `value` is an {@link Interpolation}. */
 export function isInterpolation(value) {
     return (typeof value === "object" &&
         value !== null &&
         value.type === "interpolation");
 }
-// Validation
 const ID_PATTERN = /^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$/;
 const ROUTE_PATTERN = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(\/.+)?$/;
+/**
+ * Validates a resource ID.
+ * @throws If the ID is empty, too long, or contains invalid characters.
+ */
 export function validateId(id) {
     if (!id || id.length < 1) {
         throw new Error("Resource ID cannot be empty");
@@ -25,6 +31,10 @@ export function validateId(id) {
         throw new Error(`Invalid resource ID "${id}": must start with a letter, contain only lowercase letters, numbers, and hyphens, and end with a letter or number`);
     }
 }
+/**
+ * Validates a route string.
+ * @throws If the route is empty or not a valid domain with optional path.
+ */
 export function validateRoute(route) {
     if (!route) {
         throw new Error("Route cannot be empty");

package/dist/runtime.d.ts

@@ -1,6 +1,16 @@
 import type { Resource } from "./resource.js";
+/** Structured result returned by {@link Runtime.create}. */
+export interface CreateResult {
+    action: "created" | "updated";
+    route?: string;
+    duration: number;
+}
+/** Backend that can deploy, query, and tear down resources. */
 export interface Runtime {
-    create(resource: Resource): Promise<void>;
+    /** Deploy or update a resource. */
+    create(resource: Resource): Promise<CreateResult>;
+    /** Check whether a resource currently exists. */
     exists(resource: Resource): Promise<boolean>;
+    /** Tear down a resource. */
     remove(resource: Resource): Promise<void>;
 }

package/dist/services/index.d.ts

@@ -0,0 +1,26 @@
+import type { Secret, SecretConfig, Service, ServiceConfig, Volume, VolumeConfig } from "../resource.js";
+export interface Primitives {
+    volume(id: string, config?: VolumeConfig): Volume;
+    service(id: string, config: ServiceConfig): Service;
+    secret(id: string, config?: SecretConfig): Secret;
+}
+/** Returns `true` if a resource was created by a built-in factory. */
+export declare function isManaged(resource: unknown): boolean;
+export declare function createServices(p: Primitives): {
+    postgres: (id: string, config?: import("./postgres.js").PostgresConfig) => import("./postgres.js").Postgres;
+    redis: (id: string, config?: import("./redis.js").RedisConfig) => import("./redis.js").Redis;
+    rabbitmq: (id: string, config?: import("./rabbitmq.js").RabbitmqConfig) => import("./rabbitmq.js").Rabbitmq;
+    nats: (id: string, config?: import("./nats.js").NatsConfig) => import("./nats.js").Nats;
+    mysql: (id: string, config?: import("./mysql.js").MysqlConfig) => import("./mysql.js").Mysql;
+    mongo: (id: string, config?: import("./mongo.js").MongoConfig) => import("./mongo.js").Mongo;
+    minio: (id: string, config?: import("./minio.js").MinioConfig) => import("./minio.js").Minio;
+    storage: (id: string, config?: import("./storage.js").StorageConfig) => import("./storage.js").Storage;
+};
+export type { Bucket, Minio, MinioConfig } from "./minio.js";
+export type { Mongo, MongoConfig } from "./mongo.js";
+export type { Mysql, MysqlConfig } from "./mysql.js";
+export type { Nats, NatsConfig } from "./nats.js";
+export type { Postgres, PostgresConfig } from "./postgres.js";
+export type { Rabbitmq, RabbitmqConfig } from "./rabbitmq.js";
+export type { Redis, RedisConfig } from "./redis.js";
+export type { BackupConfig, Storage, StorageConfig } from "./storage.js";