@docker-harpoon/core 0.1.0

package/dist/api/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public API Module
+ *
+ * Re-exports the Promise-based API for cleaner imports.
+ */
+export { Network, Container, database, Image, setDocker, resetDocker, destroyAll, type NetworkConfig, type NetworkResource, type ContainerConfig, type ContainerResource, type PortMapping, type ShutdownMetadata, type DatabaseConfig, type DatabaseResource, type ImageConfig, type ImageResource, } from './promise';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,OAAO,EACP,SAAS,EACT,QAAQ,EACR,KAAK,EAGL,SAAS,EACT,WAAW,EACX,UAAU,EAGV,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public API Module
+ *
+ * Re-exports the Promise-based API for cleaner imports.
+ */
+export { 
+// Resource constructors
+Network, Container, database, Image, 
+// Docker client management
+setDocker, resetDocker, destroyAll, } from './promise';

package/dist/api/promise.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Promise-based API Layer
+ *
+ * This module wraps the Effect-based resources with a simple Promise API.
+ * Effect is completely hidden from users - they just use async/await.
+ *
+ * Inspired by Alchemy.run and Pulumi's IAC patterns.
+ */
+import Docker from 'dockerode';
+import type { Binding } from '../bindings/types';
+export interface NetworkConfig {
+    /** Network driver (default: 'bridge') */
+    driver?: string;
+}
+export interface NetworkResource {
+    readonly id: string;
+    readonly name: string;
+    /** Remove this network */
+    destroy(): Promise<void>;
+}
+export interface PortMapping {
+    internal: number;
+    external: number;
+}
+export interface ShutdownMetadata {
+    signalCount: number;
+    graceful: boolean;
+    timeTakenMs: number;
+    signal: string;
+    timeoutMs: number;
+}
+export interface ContainerConfig {
+    image: string;
+    networks?: Array<NetworkResource | {
+        name: string;
+    }>;
+    ports?: PortMapping[];
+    env?: Record<string, string>;
+    cmd?: string[];
+    /** Bindings that provide env vars and lifecycle hooks */
+    bindings?: Record<string, Binding>;
+}
+export interface ContainerResource {
+    readonly id: string;
+    readonly name: string;
+    /** Wait for a log pattern to appear */
+    waitForLog(pattern: string | RegExp, timeoutMs?: number): Promise<void>;
+    /** Stop container gracefully */
+    stop(signal?: string, timeoutMs?: number): Promise<ShutdownMetadata>;
+    /** Get container IP in a network */
+    getIp(networkName: string): Promise<string>;
+    /** Remove this container */
+    destroy(): Promise<void>;
+}
+export interface DatabaseConfig {
+    /** Docker image (e.g., "postgres:15", "mysql:8", "redis:7") */
+    image: string;
+    /** Override default port for this database type */
+    port?: number;
+    /** Host port to expose (defaults to same as internal port) */
+    hostPort?: number;
+    /** Environment variables (e.g., { POSTGRES_PASSWORD: 'secret' }) */
+    env?: Record<string, string>;
+    /** Networks to connect to */
+    networks?: Array<NetworkResource | {
+        name: string;
+    }>;
+    /** Bindings for this database */
+    bindings?: Record<string, Binding>;
+}
+export interface DatabaseResource extends ContainerResource {
+    /** Connection string for this database */
+    readonly connectionString: string;
+    /** Internal port the database is listening on */
+    readonly port: number;
+    /** Host port mapped to the database */
+    readonly hostPort: number;
+}
+export interface ImageConfig {
+    /** Path to the build context directory */
+    context: string;
+    /** Path to Dockerfile relative to context */
+    dockerfile?: string;
+    /** Docker build arguments */
+    buildArgs?: Record<string, string>;
+    /** Build strategy to use (default: 'standard') */
+    buildStrategy?: string;
+    /** App name for monorepo strategies */
+    monorepoAppName?: string;
+    /** Source directory for shared monorepo folders */
+    monorepoSource?: string;
+}
+export interface ImageResource {
+    readonly tag: string;
+    readonly ref: string;
+}
+/**
+ * Set a custom Docker client.
+ * Useful for testing or custom configurations.
+ */
+export declare function setDocker(docker: Docker): void;
+/**
+ * Reset Docker client (mainly for testing).
+ */
+export declare function resetDocker(): void;
+/**
+ * Create a Docker network.
+ *
+ * @example
+ * ```typescript
+ * const network = await Network("my-app-net");
+ * // ... use network
+ * await network.destroy();
+ * ```
+ */
+export declare function Network(name: string, config?: NetworkConfig): Promise<NetworkResource>;
+/**
+ * Create a Docker container.
+ *
+ * @example
+ * ```typescript
+ * const container = await Container("my-app", {
+ *   image: "node:20-alpine",
+ *   cmd: ["node", "server.js"],
+ *   ports: [{ internal: 3000, external: 3000 }],
+ * });
+ *
+ * await container.waitForLog(/listening on/);
+ * // ... use container
+ * await container.destroy();
+ * ```
+ */
+export declare function Container(name: string, config: ContainerConfig): Promise<ContainerResource>;
+/**
+ * Create a database container with sensible defaults.
+ *
+ * Automatically infers database type from image name and provides:
+ * - Default port mappings
+ * - Connection string generation
+ *
+ * @example
+ * ```typescript
+ * const db = await database("my-postgres", {
+ *   image: "postgres:16-alpine",
+ *   env: { POSTGRES_PASSWORD: "secret", POSTGRES_DB: "mydb" },
+ * });
+ *
+ * console.log(db.connectionString);
+ * // postgresql://postgres:secret@localhost:5432/mydb
+ *
+ * await db.waitForLog(/ready to accept connections/);
+ * // ... use database
+ * await db.destroy();
+ * ```
+ */
+export declare function database(name: string, config: DatabaseConfig): Promise<DatabaseResource>;
+/**
+ * Build a Docker image.
+ *
+ * @example
+ * ```typescript
+ * const image = await Image("my-app:latest", {
+ *   context: "./",
+ *   dockerfile: "Dockerfile",
+ * });
+ *
+ * const container = await Container("app", {
+ *   image: image.tag,
+ *   // ...
+ * });
+ * ```
+ */
+export declare function Image(tag: string, config: ImageConfig): Promise<ImageResource>;
+/**
+ * Clean up all tracked resources.
+ * Called automatically on process exit, but can be called manually.
+ */
+export declare function destroyAll(): Promise<void>;
+//# sourceMappingURL=promise.d.ts.map

package/dist/api/promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise.d.ts","sourceRoot":"","sources":["../../src/api/promise.ts"],"names":[],"mappings":"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"}

package/dist/api/promise.js

@@ -0,0 +1,282 @@
+/**
+ * Promise-based API Layer
+ *
+ * This module wraps the Effect-based resources with a simple Promise API.
+ * Effect is completely hidden from users - they just use async/await.
+ *
+ * Inspired by Alchemy.run and Pulumi's IAC patterns.
+ */
+import { Effect, Scope, Exit } from 'effect';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+import Docker from 'dockerode';
+// Import Effect-based resources (internal only)
+import { Network as EffectNetwork, Container as EffectContainer, Image as EffectImage, } from '../resources';
+import { database as effectDatabase, } from '../helpers';
+// Binding type is used as-is from internal types
+// Pre-built bindings like PrismaBinding handle Effect internally
+// Users creating simple bindings can use createEnvBinding()
+// ============ Docker Client Management ============
+let dockerClient = null;
+/**
+ * Detect Docker socket path for the current platform.
+ */
+function detectDockerSocket() {
+    const candidates = [
+        '/var/run/docker.sock',
+        `${homedir()}/.docker/run/docker.sock`,
+    ];
+    for (const path of candidates) {
+        if (existsSync(path)) {
+            return path;
+        }
+    }
+    // Windows uses named pipes, let dockerode handle it
+    return '/var/run/docker.sock';
+}
+/**
+ * Get the Docker client, auto-detecting the socket if needed.
+ */
+function getDocker() {
+    if (!dockerClient) {
+        const socketPath = detectDockerSocket();
+        dockerClient = new Docker({ socketPath });
+    }
+    return dockerClient;
+}
+/**
+ * Set a custom Docker client.
+ * Useful for testing or custom configurations.
+ */
+export function setDocker(docker) {
+    dockerClient = docker;
+}
+/**
+ * Reset Docker client (mainly for testing).
+ */
+export function resetDocker() {
+    dockerClient = null;
+}
+const resources = new Map();
+/**
+ * Register cleanup on process exit.
+ */
+let cleanupRegistered = false;
+function registerCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    const cleanup = async () => {
+        for (const [id, resource] of resources) {
+            try {
+                await resource.cleanup();
+            }
+            catch (e) {
+                console.error(`[Cleanup] Error cleaning up ${id}:`, e);
+            }
+        }
+        resources.clear();
+    };
+    process.on('beforeExit', cleanup);
+    process.on('SIGINT', async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    process.on('SIGTERM', async () => {
+        await cleanup();
+        process.exit(0);
+    });
+}
+// ============ Promise-based Resource Constructors ============
+/**
+ * Create a Docker network.
+ *
+ * @example
+ * ```typescript
+ * const network = await Network("my-app-net");
+ * // ... use network
+ * await network.destroy();
+ * ```
+ */
+export async function Network(name, config = {}) {
+    registerCleanup();
+    const docker = getDocker();
+    const scope = Effect.runSync(Scope.make());
+    const effectConfig = {
+        name,
+        ...(config.driver !== undefined && { driver: config.driver }),
+    };
+    const effectResource = await Effect.runPromise(EffectNetwork(name, effectConfig, docker).pipe(Scope.extend(scope)));
+    const resourceId = `network:${effectResource.id}`;
+    const cleanup = async () => {
+        await Effect.runPromise(Scope.close(scope, Exit.void));
+    };
+    resources.set(resourceId, { scope, cleanup });
+    return {
+        id: effectResource.id,
+        name: effectResource.name,
+        async destroy() {
+            await cleanup();
+            resources.delete(resourceId);
+        },
+    };
+}
+/**
+ * Create a Docker container.
+ *
+ * @example
+ * ```typescript
+ * const container = await Container("my-app", {
+ *   image: "node:20-alpine",
+ *   cmd: ["node", "server.js"],
+ *   ports: [{ internal: 3000, external: 3000 }],
+ * });
+ *
+ * await container.waitForLog(/listening on/);
+ * // ... use container
+ * await container.destroy();
+ * ```
+ */
+export async function Container(name, config) {
+    registerCleanup();
+    const docker = getDocker();
+    const scope = Effect.runSync(Scope.make());
+    // Convert NetworkResource to { name: string }
+    const networks = config.networks?.map((n) => 'destroy' in n ? { name: n.name } : n);
+    const effectConfig = {
+        image: config.image,
+        ...(networks !== undefined && { networks }),
+        ...(config.ports !== undefined && { ports: config.ports }),
+        ...(config.env !== undefined && { env: config.env }),
+        ...(config.cmd !== undefined && { cmd: config.cmd }),
+        ...(config.bindings !== undefined && { bindings: config.bindings }),
+    };
+    const effectResource = await Effect.runPromise(EffectContainer(name, effectConfig, docker).pipe(Scope.extend(scope)));
+    const resourceId = `container:${effectResource.id}`;
+    const cleanup = async () => {
+        await Effect.runPromise(Scope.close(scope, Exit.void));
+    };
+    resources.set(resourceId, { scope, cleanup });
+    return {
+        id: effectResource.id,
+        name: effectResource.name,
+        async waitForLog(pattern, timeoutMs = 30000) {
+            await Effect.runPromise(effectResource.waitForLog(pattern, timeoutMs));
+        },
+        async stop(signal = 'SIGTERM', timeoutMs = 10000) {
+            return Effect.runPromise(effectResource.stopGracefully(signal, timeoutMs));
+        },
+        async getIp(networkName) {
+            return Effect.runPromise(effectResource.getIp(networkName));
+        },
+        async destroy() {
+            await cleanup();
+            resources.delete(resourceId);
+        },
+    };
+}
+/**
+ * Create a database container with sensible defaults.
+ *
+ * Automatically infers database type from image name and provides:
+ * - Default port mappings
+ * - Connection string generation
+ *
+ * @example
+ * ```typescript
+ * const db = await database("my-postgres", {
+ *   image: "postgres:16-alpine",
+ *   env: { POSTGRES_PASSWORD: "secret", POSTGRES_DB: "mydb" },
+ * });
+ *
+ * console.log(db.connectionString);
+ * // postgresql://postgres:secret@localhost:5432/mydb
+ *
+ * await db.waitForLog(/ready to accept connections/);
+ * // ... use database
+ * await db.destroy();
+ * ```
+ */
+export async function database(name, config) {
+    registerCleanup();
+    const docker = getDocker();
+    const scope = Effect.runSync(Scope.make());
+    // Convert NetworkResource to { name: string }
+    const networks = config.networks?.map((n) => 'destroy' in n ? { name: n.name } : n);
+    const effectConfig = {
+        image: config.image,
+        ...(config.port !== undefined && { port: config.port }),
+        ...(config.hostPort !== undefined && { hostPort: config.hostPort }),
+        ...(config.env !== undefined && { env: config.env }),
+        ...(networks !== undefined && { networks }),
+        ...(config.bindings !== undefined && { bindings: config.bindings }),
+    };
+    const effectResource = await Effect.runPromise(effectDatabase(name, effectConfig, docker).pipe(Scope.extend(scope)));
+    const resourceId = `database:${effectResource.id}`;
+    const cleanup = async () => {
+        await Effect.runPromise(Scope.close(scope, Exit.void));
+    };
+    resources.set(resourceId, { scope, cleanup });
+    return {
+        id: effectResource.id,
+        name: effectResource.name,
+        connectionString: effectResource.connectionString,
+        port: effectResource.port,
+        hostPort: effectResource.hostPort,
+        async waitForLog(pattern, timeoutMs = 30000) {
+            await Effect.runPromise(effectResource.waitForLog(pattern, timeoutMs));
+        },
+        async stop(signal = 'SIGTERM', timeoutMs = 10000) {
+            return Effect.runPromise(effectResource.stopGracefully(signal, timeoutMs));
+        },
+        async getIp(networkName) {
+            return Effect.runPromise(effectResource.getIp(networkName));
+        },
+        async destroy() {
+            await cleanup();
+            resources.delete(resourceId);
+        },
+    };
+}
+/**
+ * Build a Docker image.
+ *
+ * @example
+ * ```typescript
+ * const image = await Image("my-app:latest", {
+ *   context: "./",
+ *   dockerfile: "Dockerfile",
+ * });
+ *
+ * const container = await Container("app", {
+ *   image: image.tag,
+ *   // ...
+ * });
+ * ```
+ */
+export async function Image(tag, config) {
+    const effectConfig = {
+        context: config.context,
+        ...(config.dockerfile !== undefined && { dockerfile: config.dockerfile }),
+        ...(config.buildArgs !== undefined && { buildArgs: config.buildArgs }),
+        ...(config.buildStrategy !== undefined && { buildStrategy: config.buildStrategy }),
+        ...(config.monorepoAppName !== undefined && { monorepoAppName: config.monorepoAppName }),
+        ...(config.monorepoSource !== undefined && { monorepoSource: config.monorepoSource }),
+    };
+    return Effect.runPromise(EffectImage(tag, effectConfig));
+}
+/**
+ * Clean up all tracked resources.
+ * Called automatically on process exit, but can be called manually.
+ */
+export async function destroyAll() {
+    for (const [id, resource] of resources) {
+        try {
+            await resource.cleanup();
+        }
+        catch (e) {
+            console.error(`[Cleanup] Error cleaning up ${id}:`, e);
+        }
+    }
+    resources.clear();
+}

package/dist/bindings/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bindings Module
+ *
+ * Exports binding types and utilities for creating resource bindings.
+ */
+export type { Binding, BuildBinding, BindingsEnv, FlatBindingsEnv, } from './types';
+export { isBuildBinding, mergeBindingsEnv, createEnvBinding, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/bindings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/bindings/index.js

@@ -0,0 +1,6 @@
+/**
+ * Bindings Module
+ *
+ * Exports binding types and utilities for creating resource bindings.
+ */
+export { isBuildBinding, mergeBindingsEnv, createEnvBinding, } from './types';

package/dist/bindings/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Binding Types
+ *
+ * Bindings connect resources to containers, providing:
+ * - Environment variables
+ * - Lifecycle hooks
+ * - Build-time transformations
+ *
+ * Inspired by CloudFlare Workers bindings pattern.
+ */
+import { Effect } from 'effect';
+import type { DockerfileInstruction, TransformContext } from '../dockerfile-transformers/types';
+import type { PatchContext, PatchResult } from '../config-patchers/types';
+import type { BuildContext, BuildStrategyInput } from '../build-strategies/types';
+/**
+ * Base binding interface.
+ *
+ * Bindings attach to resources and provide environment variables
+ * and lifecycle hooks to containers.
+ */
+export interface Binding<TResource = unknown, TEnv extends Record<string, string> = Record<string, string>> {
+    /** Unique binding type identifier */
+    readonly type: string;
+    /** The resource this binding is attached to (optional) */
+    readonly resource?: TResource;
+    /**
+     * Get environment variables this binding provides.
+     * These are merged into the container's environment.
+     */
+    getEnv(): TEnv;
+    /**
+     * Called when the binding is attached to a container config.
+     * Can modify the container config before creation.
+     */
+    onAttach?<TConfig>(config: TConfig): TConfig | Effect.Effect<TConfig, Error>;
+    /**
+     * Called after the container starts.
+     * Use for initialization tasks like running migrations.
+     */
+    onStart?<TContainer>(container: TContainer): Effect.Effect<void, Error>;
+    /**
+     * Called before the container stops.
+     * Use for cleanup tasks.
+     */
+    onStop?<TContainer>(container: TContainer): Effect.Effect<void, Error>;
+}
+/**
+ * Build-time binding interface.
+ *
+ * Extends Binding with build-time transformation capabilities
+ * for Dockerfile modifications and config patching.
+ */
+export interface BuildBinding<TEnv extends Record<string, string> = Record<string, string>> extends Binding<undefined, TEnv> {
+    /**
+     * Transform Dockerfile instructions during image build.
+     * Return modified instructions or the same instructions unchanged.
+     */
+    transformDockerfile?(instructions: readonly DockerfileInstruction[], ctx: TransformContext): readonly DockerfileInstruction[];
+    /**
+     * Patch project configuration files before build.
+     */
+    patchConfig?(ctx: PatchContext): Effect.Effect<PatchResult, Error>;
+    /**
+     * Prepare or modify the build context.
+     * Called during image build strategy execution.
+     */
+    prepareBuildContext?(input: BuildStrategyInput, ctx: BuildContext): Effect.Effect<BuildContext, Error>;
+}
+/**
+ * Utility type to extract the combined env type from a bindings record.
+ *
+ * @example
+ * ```typescript
+ * const bindings = {
+ *   DB: PrismaBinding(db),      // { DATABASE_URL: string }
+ *   CACHE: RedisBinding(redis), // { REDIS_URL: string }
+ * };
+ *
+ * type Env = BindingsEnv<typeof bindings>;
+ * // { DB: { DATABASE_URL: string }, CACHE: { REDIS_URL: string } }
+ * ```
+ */
+export type BindingsEnv<B extends Record<string, Binding<unknown, Record<string, string>>>> = {
+    [K in keyof B]: B[K] extends Binding<unknown, infer E> ? E : never;
+};
+/**
+ * Flatten bindings env into a single record of all env vars.
+ *
+ * @example
+ * ```typescript
+ * type FlatEnv = FlatBindingsEnv<typeof bindings>;
+ * // { DATABASE_URL: string, REDIS_URL: string }
+ * ```
+ */
+export type FlatBindingsEnv<B extends Record<string, Binding<unknown, Record<string, string>>>> = B[keyof B] extends Binding<unknown, infer E> ? E : never;
+/**
+ * Check if a binding is a build-time binding.
+ */
+export declare function isBuildBinding(binding: Binding): binding is BuildBinding;
+/**
+ * Merge environment variables from multiple bindings.
+ */
+export declare function mergeBindingsEnv(bindings: Record<string, Binding>): Record<string, string>;
+/**
+ * Create a simple binding from environment variables.
+ *
+ * @example
+ * ```typescript
+ * const configBinding = createEnvBinding('config', {
+ *   NODE_ENV: 'production',
+ *   LOG_LEVEL: 'info',
+ * });
+ * ```
+ */
+export declare function createEnvBinding<TEnv extends Record<string, string>>(type: string, env: TEnv): Binding<undefined, TEnv>;
+//# sourceMappingURL=types.d.ts.map

package/dist/bindings/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bindings/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAElF;;;;;GAKG;AACH,MAAM,WAAW,OAAO,CACtB,SAAS,GAAG,OAAO,EACnB,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAE5D,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAE9B;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAE7E;;;OAGG;IACH,OAAO,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAExE;;;OAGG;IACH,MAAM,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;CACxE;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAC3B,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAC5D,SAAQ,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;IAChC;;;OAGG;IACH,mBAAmB,CAAC,CAClB,YAAY,EAAE,SAAS,qBAAqB,EAAE,EAC9C,GAAG,EAAE,gBAAgB,GACpB,SAAS,qBAAqB,EAAE,CAAC;IAEpC;;OAEG;IACH,WAAW,CAAC,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAEnE;;;OAGG;IACH,mBAAmB,CAAC,CAClB,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,YAAY,GAChB,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI;KAC3F,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACnE,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,IAC5F,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3D;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,YAAY,CAMxE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClE,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAK1B"}

package/dist/bindings/types.js

@@ -0,0 +1,46 @@
+/**
+ * Binding Types
+ *
+ * Bindings connect resources to containers, providing:
+ * - Environment variables
+ * - Lifecycle hooks
+ * - Build-time transformations
+ *
+ * Inspired by CloudFlare Workers bindings pattern.
+ */
+/**
+ * Check if a binding is a build-time binding.
+ */
+export function isBuildBinding(binding) {
+    return ('transformDockerfile' in binding ||
+        'patchConfig' in binding ||
+        'prepareBuildContext' in binding);
+}
+/**
+ * Merge environment variables from multiple bindings.
+ */
+export function mergeBindingsEnv(bindings) {
+    const env = {};
+    for (const binding of Object.values(bindings)) {
+        const bindingEnv = binding.getEnv();
+        Object.assign(env, bindingEnv);
+    }
+    return env;
+}
+/**
+ * Create a simple binding from environment variables.
+ *
+ * @example
+ * ```typescript
+ * const configBinding = createEnvBinding('config', {
+ *   NODE_ENV: 'production',
+ *   LOG_LEVEL: 'info',
+ * });
+ * ```
+ */
+export function createEnvBinding(type, env) {
+    return {
+        type,
+        getEnv: () => env,
+    };
+}