@docker-harpoon/core 0.1.0

package/dist/resources/container.js

@@ -0,0 +1,256 @@
+/**
+ * Container Resource Module
+ *
+ * Manages Docker container lifecycle using Effect's acquireRelease pattern.
+ * Ensures containers are always cleaned up, even during interruption.
+ *
+ * Supports bindings for environment variable injection and lifecycle hooks.
+ */
+import { Effect, Schedule, Exit } from 'effect';
+import { toHarpoonError, ContainerError } from '../errors';
+import { mergeBindingsEnv } from '../bindings/types';
+const CLEANUP_TIMEOUT_MS = 10_000;
+const safeRemoveContainer = async (docker, containerId, containerName) => {
+    const container = docker.getContainer(containerId);
+    try {
+        const data = await container.inspect();
+        if (data.State.Running) {
+            console.log(`[Cleanup] Stopping container: ${containerName}`);
+            try {
+                await container.kill({ signal: 'SIGTERM' });
+                await new Promise((resolve) => {
+                    const checkStopped = async () => {
+                        try {
+                            const state = await container.inspect();
+                            if (!state.State.Running) {
+                                resolve();
+                                return;
+                            }
+                        }
+                        catch {
+                            resolve();
+                            return;
+                        }
+                        setTimeout(checkStopped, 100);
+                    };
+                    const timeout = setTimeout(() => {
+                        console.warn(`[Cleanup] Container ${containerName} did not stop gracefully, forcing`);
+                        container.kill({ signal: 'SIGKILL' }).catch(() => { });
+                        resolve();
+                    }, 5000);
+                    checkStopped().finally(() => clearTimeout(timeout));
+                });
+            }
+            catch (e) {
+                if (!e.message?.includes('is not running')) {
+                    console.warn(`[Cleanup] Error stopping ${containerName}: ${e.message}`);
+                }
+            }
+        }
+        await container.remove({ force: true });
+        console.log(`[Cleanup] Container removed: ${containerName}`);
+    }
+    catch (e) {
+        if (e.statusCode === 404) {
+            console.log(`[Cleanup] Container ${containerName} already removed`);
+        }
+        else {
+            console.error(`[Cleanup] Error removing container ${containerName}:`, e.message);
+        }
+    }
+};
+export const Container = (resourceId, config, docker) => Effect.acquireRelease(Effect.tryPromise({
+    try: async () => {
+        try {
+            const existingContainer = docker.getContainer(resourceId);
+            await existingContainer.inspect();
+            console.log(`[Container] Found existing container ${resourceId}, removing...`);
+            await safeRemoveContainer(docker, resourceId, resourceId);
+        }
+        catch (e) {
+            if (e.statusCode !== 404) {
+                console.warn(`[Container] Warning checking for existing container: ${e.message}`);
+            }
+        }
+        if (config.ports?.length) {
+            const externalPorts = config.ports.map(({ external }) => external);
+            try {
+                const containers = await docker.listContainers({ all: true });
+                for (const c of containers) {
+                    if (c.Names?.some((name) => name.includes(resourceId)))
+                        continue;
+                    const usesConflictingPort = (c.Ports || []).some((p) => p.PublicPort && externalPorts.includes(p.PublicPort));
+                    if (!usesConflictingPort)
+                        continue;
+                    const name = c.Names?.[0]?.replace(/^\//, '') ?? c.Id.substring(0, 12);
+                    console.log(`[Container] Found container "${name}" using port(s) ${externalPorts.join(', ')}, removing...`);
+                    await safeRemoveContainer(docker, c.Id, name);
+                }
+            }
+            catch (e) {
+                console.warn(`[Container] Warning checking for port conflicts: ${e.message}`);
+            }
+        }
+        const PortBindings = {};
+        const ExposedPorts = {};
+        for (const port of config.ports ?? []) {
+            const key = `${port.internal}/tcp`;
+            ExposedPorts[key] = {};
+            PortBindings[key] = [{ HostPort: String(port.external) }];
+        }
+        try {
+            const image = docker.getImage(config.image);
+            await image.inspect();
+            console.log(`[Container] Verified image exists: ${config.image}`);
+        }
+        catch (e) {
+            if (e.statusCode === 404) {
+                const images = await docker.listImages();
+                const imageName = config.image.split(':')[0] || config.image;
+                const imageTags = images
+                    .flatMap((img) => img.RepoTags || [])
+                    .filter((tag) => tag && tag.includes(imageName));
+                throw new Error(`Image "${config.image}" not found. Available images with similar tags: ${imageTags.join(', ') || 'none'}`);
+            }
+            throw new Error(`Failed to verify image "${config.image}": ${e.message}`);
+        }
+        // Merge env vars from bindings
+        const bindingsEnv = config.bindings
+            ? mergeBindingsEnv(config.bindings)
+            : {};
+        const finalEnv = {
+            ...bindingsEnv,
+            ...config.env, // User env takes precedence
+        };
+        const container = await docker.createContainer({
+            Image: config.image,
+            name: resourceId,
+            Env: Object.entries(finalEnv).map(([k, v]) => `${k}=${v}`),
+            HostConfig: {
+                NetworkMode: config.networks?.[0]?.name,
+                AutoRemove: false,
+                PortBindings,
+            },
+            ExposedPorts,
+            Cmd: config.cmd,
+            StopSignal: 'SIGTERM',
+            StopTimeout: 10,
+        });
+        await container.start();
+        const resource = {
+            id: container.id,
+            name: resourceId,
+            waitForLog: (pattern, timeoutMs = 30000) => Effect.gen(function* () {
+                const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+                const checkLogs = Effect.tryPromise({
+                    try: async () => {
+                        const buffer = await container.logs({
+                            stdout: true,
+                            stderr: true,
+                            tail: 1000,
+                        });
+                        const logContent = buffer.toString('utf-8');
+                        if (regex.test(logContent)) {
+                            return true;
+                        }
+                        throw new Error('Log pattern not found');
+                    },
+                    catch: (e) => new Error(`Log check failed: ${e}`),
+                });
+                yield* checkLogs.pipe(Effect.retry({
+                    schedule: Schedule.spaced('1 seconds').pipe(Schedule.intersect(Schedule.duration(`${timeoutMs} millis`))),
+                }));
+            }).pipe(Effect.mapError((e) => new Error(`waitForLog failed after ${timeoutMs}ms: ${e.message}`))),
+            stopGracefully: (signal = 'SIGTERM', timeoutMs = 10000) => Effect.gen(function* () {
+                const startTime = Date.now();
+                let signalCount = 0;
+                let graceful = false;
+                // Call onStop hooks for bindings
+                if (config.bindings) {
+                    for (const binding of Object.values(config.bindings)) {
+                        if (binding.onStop) {
+                            yield* binding.onStop(resource);
+                        }
+                    }
+                }
+                yield* Effect.tryPromise({
+                    try: () => {
+                        signalCount++;
+                        return container.kill({ signal });
+                    },
+                    catch: (e) => {
+                        if (e.message?.includes('is not running')) {
+                            graceful = true;
+                            return;
+                        }
+                        throw new Error(`Failed to send ${signal}: ${e.message}`);
+                    },
+                });
+                const check = Effect.suspend(() => Effect.tryPromise({
+                    try: () => container.inspect(),
+                    catch: () => null,
+                }).pipe(Effect.flatMap((data) => {
+                    if (!data || !data.State.Running) {
+                        graceful = true;
+                        return Effect.void;
+                    }
+                    return Effect.fail(new Error('Container still running'));
+                })));
+                try {
+                    yield* check.pipe(Effect.retry({
+                        schedule: Schedule.spaced('500 millis').pipe(Schedule.intersect(Schedule.duration(`${timeoutMs} millis`))),
+                    }));
+                    graceful = true;
+                }
+                catch {
+                    graceful = false;
+                }
+                const timeTakenMs = Date.now() - startTime;
+                return {
+                    signalCount,
+                    graceful,
+                    timeTakenMs,
+                    signal,
+                    timeoutMs,
+                };
+            }).pipe(Effect.mapError((e) => new Error(`stopGracefully failed: ${e}`))),
+            getIp: (networkName) => Effect.tryPromise({
+                try: async () => {
+                    const data = await container.inspect();
+                    return (data.NetworkSettings.Networks[networkName]?.IPAddress ??
+                        'localhost');
+                },
+                catch: (e) => new Error(`getIp failed: ${e}`),
+            }),
+        };
+        // Call onStart hooks for bindings
+        // This is done in Effect context for proper error handling
+        return resource;
+    },
+    catch: (e) => new Error(`Container "${resourceId}" creation failed: ${e}`),
+}).pipe(Effect.mapError((e) => toHarpoonError(e, resourceId, ContainerError)), 
+// Run onStart hooks after container creation
+Effect.tap((resource) => Effect.gen(function* () {
+    if (config.bindings) {
+        for (const binding of Object.values(config.bindings)) {
+            if (binding.onStart) {
+                yield* binding.onStart(resource);
+            }
+        }
+    }
+}))), (resource, exit) => Effect.gen(function* () {
+    const isInterrupted = Exit.isInterrupted(exit);
+    if (isInterrupted) {
+        console.log(`[Cleanup] Interrupted - force cleaning container: ${resource.name}`);
+    }
+    yield* Effect.tryPromise({
+        try: () => Promise.race([
+            safeRemoveContainer(docker, resource.id, resource.name),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Cleanup timeout')), CLEANUP_TIMEOUT_MS)),
+        ]),
+        catch: (e) => {
+            console.error(`[Cleanup] Failed to clean up container ${resource.name}:`, e);
+            return null;
+        },
+    });
+}).pipe(Effect.catchAll(() => Effect.void), Effect.uninterruptible));

package/dist/resources/image.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Docker Image Resource
+ *
+ * Builds Docker images using pluggable build strategies.
+ * The actual build context preparation is delegated to strategy implementations.
+ */
+import { Effect } from 'effect';
+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;
+}
+/**
+ * Result of building a Docker image.
+ */
+export interface ImageResource {
+    readonly tag: string;
+    readonly ref: string;
+}
+/**
+ * Build a Docker image using the configured strategy.
+ *
+ * @param tag Image tag (e.g., "my-app:latest")
+ * @param config Image build configuration
+ * @returns Effect yielding the built image resource
+ */
+export declare const Image: (tag: string, config: ImageConfig) => Effect.Effect<ImageResource, Error>;
+//# sourceMappingURL=image.d.ts.map

package/dist/resources/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/resources/image.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAChB,KAAK,MAAM,EACX,QAAQ,WAAW,KAClB,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,CAyHgC,CAAC"}

package/dist/resources/image.js

@@ -0,0 +1,113 @@
+/**
+ * Docker Image Resource
+ *
+ * Builds Docker images using pluggable build strategies.
+ * The actual build context preparation is delegated to strategy implementations.
+ */
+import { Effect } from 'effect';
+import * as fs from 'fs/promises';
+import { toHarpoonError, ImageError } from '../errors';
+import { getBuildStrategy } from '../build-strategies';
+/**
+ * Build a Docker image using the configured strategy.
+ *
+ * @param tag Image tag (e.g., "my-app:latest")
+ * @param config Image build configuration
+ * @returns Effect yielding the built image resource
+ */
+export const Image = (tag, config) => Effect.gen(function* () {
+    // Determine which strategy to use
+    const strategyName = config.buildStrategy ?? 'standard';
+    const strategy = getBuildStrategy(strategyName);
+    if (!strategy) {
+        yield* Effect.fail(new Error(`Unknown build strategy: ${strategyName}`));
+        // TypeScript needs this for type narrowing
+        throw new Error('unreachable');
+    }
+    // Prepare build context using strategy
+    const input = {
+        tag,
+        context: config.context,
+        ...(config.dockerfile && { dockerfile: config.dockerfile }),
+        ...(config.buildArgs && { buildArgs: config.buildArgs }),
+        ...(config.monorepoAppName && { monorepoAppName: config.monorepoAppName }),
+        ...(config.monorepoSource && { monorepoSource: config.monorepoSource }),
+    };
+    const buildContext = yield* strategy.prepare(input);
+    // Execute docker build
+    const result = yield* Effect.tryPromise({
+        try: async () => {
+            const args = ['docker', 'build', '-t', tag];
+            args.push('-f', buildContext.dockerfilePath);
+            if (config.buildArgs) {
+                for (const [key, value] of Object.entries(config.buildArgs)) {
+                    args.push('--build-arg', `${key}=${value}`);
+                }
+            }
+            args.push(buildContext.contextPath);
+            const proc = Bun.spawn(args, {
+                stdout: 'ignore',
+                stderr: 'pipe',
+            });
+            const stderrOutput = [];
+            const errorReader = async () => {
+                if (!proc.stderr)
+                    return;
+                const reader = proc.stderr.getReader();
+                const decoder = new TextDecoder();
+                try {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        const output = decoder.decode(value);
+                        stderrOutput.push(output);
+                        if (output.toLowerCase().includes('error')) {
+                            console.error(`[${tag}] ${output.trim()}`);
+                        }
+                    }
+                }
+                catch (e) {
+                    console.error(`[${tag}] Error reading stderr:`, e);
+                }
+            };
+            await errorReader();
+            const exitCode = await proc.exited;
+            // Cleanup temp directory if needed
+            if (buildContext.requiresCleanup && buildContext.tempDir) {
+                await fs.rm(buildContext.tempDir, { recursive: true, force: true });
+            }
+            if (exitCode !== 0) {
+                const errorOutput = stderrOutput.join('');
+                throw new Error(`Build exited with code ${exitCode}${errorOutput ? `\n${errorOutput}` : ''}`);
+            }
+            // Verify image was created
+            let verified = false;
+            for (let attempt = 0; attempt < 5; attempt++) {
+                const verifyProc = Bun.spawn(['docker', 'images', '-q', tag], {
+                    stdout: 'pipe',
+                    stderr: 'pipe',
+                });
+                let verifyOutput = '';
+                if (verifyProc.stdout) {
+                    verifyOutput = await Bun.readableStreamToText(verifyProc.stdout);
+                }
+                const verifyExitCode = await verifyProc.exited;
+                if (verifyExitCode === 0 && verifyOutput.trim()) {
+                    verified = true;
+                    break;
+                }
+                if (attempt < 4) {
+                    await new Promise((resolve) => setTimeout(resolve, 200));
+                }
+            }
+            if (!verified) {
+                const errorOutput = stderrOutput.join('');
+                throw new Error(`Build completed but image ${tag} not found after verification attempts${errorOutput ? `\nBuild output: ${errorOutput}` : ''}`);
+            }
+            return { tag, ref: tag };
+        },
+        catch: (e) => new Error(`Image "${tag}" build failed: ${e}`),
+    });
+    return result;
+}).pipe(Effect.mapError((e) => toHarpoonError(e, tag, ImageError)));

package/dist/resources/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resources Module
+ *
+ * Exports Docker resource constructors and types.
+ */
+export { Network } from './network';
+export type { NetworkConfig, NetworkResource } from './network';
+export { Container } from './container';
+export type { ContainerConfig, ContainerResource, PortMapping, ShutdownMetadata, } from './container';
+export { Image } from './image';
+export type { ImageConfig, ImageResource } from './image';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEhE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/resources/index.js

@@ -0,0 +1,8 @@
+/**
+ * Resources Module
+ *
+ * Exports Docker resource constructors and types.
+ */
+export { Network } from './network';
+export { Container } from './container';
+export { Image } from './image';

package/dist/resources/network.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Network Resource Module
+ *
+ * Manages Docker network lifecycle using Effect's acquireRelease pattern.
+ * Ensures networks are always cleaned up, even during interruption.
+ */
+import { Effect, Scope } from 'effect';
+import Docker from 'dockerode';
+export interface NetworkConfig {
+    name: string;
+    driver?: string;
+}
+export interface NetworkResource {
+    readonly id: string;
+    readonly name: string;
+}
+/**
+ * Creates a Docker network resource with automatic lifecycle management.
+ */
+export declare const Network: (resourceId: string, config: NetworkConfig, docker: Docker) => Effect.Effect<NetworkResource, Error, Scope.Scope>;
+//# sourceMappingURL=network.d.ts.map

package/dist/resources/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/resources/network.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAQ,MAAM,QAAQ,CAAC;AAC7C,OAAO,MAAM,MAAM,WAAW,CAAC;AAG/B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAiCD;;GAEG;AACH,eAAO,MAAM,OAAO,GAClB,YAAY,MAAM,EAClB,QAAQ,aAAa,EACrB,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CA+EjD,CAAC"}

package/dist/resources/network.js

@@ -0,0 +1,86 @@
+/**
+ * Network Resource Module
+ *
+ * Manages Docker network lifecycle using Effect's acquireRelease pattern.
+ * Ensures networks are always cleaned up, even during interruption.
+ */
+import { Effect, Exit } from 'effect';
+import { toHarpoonError, NetworkError } from '../errors';
+// Constants
+const CLEANUP_TIMEOUT_MS = 5_000; // 5 seconds max for network cleanup
+/**
+ * Safely removes a network, handling all possible states.
+ */
+const safeRemoveNetwork = async (docker, networkId, networkName) => {
+    try {
+        const network = docker.getNetwork(networkId);
+        await network.remove();
+        console.log(`[Cleanup] Network removed: ${networkName}`);
+    }
+    catch (e) {
+        if (e.statusCode === 404) {
+            console.log(`[Cleanup] Network ${networkName} already removed`);
+        }
+        else if (e.message?.includes('has active endpoints')) {
+            console.warn(`[Cleanup] Network ${networkName} has active endpoints, skipping removal`);
+        }
+        else {
+            console.error(`[Cleanup] Error removing network ${networkName}:`, e.message);
+        }
+    }
+};
+/**
+ * Creates a Docker network resource with automatic lifecycle management.
+ */
+export const Network = (resourceId, config, docker) => Effect.acquireRelease(
+// ACQUIRE: Create the network
+Effect.tryPromise({
+    try: async () => {
+        // Check if network already exists
+        const networks = await docker.listNetworks({
+            filters: { name: [config.name] },
+        });
+        const existing = networks.find((n) => n.Name === config.name);
+        if (existing) {
+            // Try to remove existing network for clean state
+            try {
+                const net = docker.getNetwork(existing.Id);
+                await net.remove();
+                console.log(`[Network] Removed existing network: ${config.name}`);
+            }
+            catch (e) {
+                if (e.message?.includes('has active endpoints')) {
+                    // Network in use - try to reuse it
+                    console.warn(`[Network] ${config.name} in use, reusing existing network`);
+                    return { id: existing.Id, name: config.name };
+                }
+                // Other errors - try to proceed with creation anyway
+                console.warn(`[Network] Could not remove ${config.name}: ${e.message}`);
+            }
+        }
+        // Create new network
+        const network = await docker.createNetwork({
+            Name: config.name,
+            Driver: config.driver ?? 'bridge',
+        });
+        return { id: network.id, name: config.name };
+    },
+    catch: (e) => new Error(`Network "${resourceId}" creation failed: ${e}`),
+}).pipe(Effect.mapError((e) => toHarpoonError(e, resourceId, NetworkError))), 
+// RELEASE: Cleanup function
+(resource, exit) => Effect.gen(function* () {
+    const isInterrupted = Exit.isInterrupted(exit);
+    if (isInterrupted) {
+        console.log(`[Cleanup] Interrupted - cleaning up network: ${resource.name}`);
+    }
+    yield* Effect.tryPromise({
+        try: () => Promise.race([
+            safeRemoveNetwork(docker, resource.id, resource.name),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Network cleanup timeout')), CLEANUP_TIMEOUT_MS)),
+        ]),
+        catch: (e) => {
+            console.error(`[Cleanup] Failed to clean up network ${resource.name}:`, e);
+            return null;
+        },
+    });
+}).pipe(Effect.catchAll(() => Effect.void), Effect.uninterruptible));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@docker-harpoon/core",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Core Docker resource primitives and binding interface",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "dockerode": "^4.0.9",
+    "effect": "^3.19.14",
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}