@docker-harpoon/core 0.1.0 → 0.1.2

package/dist/api/index.d.ts

@@ -3,5 +3,5 @@
  *
  * 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';
+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, type ContainerStats, type ExecOptions, type ExecResult, type LogOptions, type LogLine, } from './promise';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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,EAGlB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,GACb,MAAM,WAAW,CAAC"}

package/dist/api/promise.d.ts

@@ -7,6 +7,8 @@
  * Inspired by Alchemy.run and Pulumi's IAC patterns.
  */
 import Docker from 'dockerode';
+import { type ContainerStats, type ExecOptions, type ExecResult, type LogOptions, type LogLine } from '../resources';
+export type { ContainerStats, ExecOptions, ExecResult, LogOptions, LogLine, } from '../resources';
 import type { Binding } from '../bindings/types';
 export interface NetworkConfig {
     /** Network driver (default: 'bridge') */
@@ -49,6 +51,12 @@ export interface ContainerResource {
     stop(signal?: string, timeoutMs?: number): Promise<ShutdownMetadata>;
     /** Get container IP in a network */
     getIp(networkName: string): Promise<string>;
+    /** Get container resource statistics (CPU, memory, network) */
+    stats(): Promise<ContainerStats>;
+    /** Execute a command inside the container */
+    exec(cmd: string[], options?: Omit<ExecOptions, 'cmd'>): Promise<ExecResult>;
+    /** Stream container logs as an async iterable */
+    streamLogs(options?: LogOptions): Promise<AsyncIterable<LogLine>>;
     /** Remove this container */
     destroy(): Promise<void>;
 }

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

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

package/dist/api/promise.js

@@ -7,8 +7,9 @@
  * Inspired by Alchemy.run and Pulumi's IAC patterns.
  */
 import { Effect, Scope, Exit } from 'effect';
-import { homedir } from 'os';
+import { homedir, platform } from 'os';
 import { existsSync } from 'fs';
+import { spawn } from 'child_process';
 import Docker from 'dockerode';
 // Import Effect-based resources (internal only)
 import { Network as EffectNetwork, Container as EffectContainer, Image as EffectImage, } from '../resources';
@@ -44,6 +45,92 @@ function getDocker() {
     }
     return dockerClient;
 }
+// ============ Docker Auto-Start (Alchemy.run Style) ============
+const DOCKER_STARTUP_TIMEOUT_MS = 60_000;
+let dockerEnsured = false;
+/**
+ * Start Docker Desktop on macOS/Windows if not running.
+ */
+function startDockerDesktop() {
+    const os = platform();
+    if (os === 'darwin') {
+        console.log('[Harpoon] Starting Docker Desktop...');
+        const child = spawn('open', ['-a', 'Docker', '--background'], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    else if (os === 'win32') {
+        console.log('[Harpoon] Starting Docker Desktop...');
+        const child = spawn('cmd', ['/c', 'start', '', 'Docker Desktop'], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    // Linux: Docker daemon managed by systemd, no auto-start
+}
+/**
+ * Wait for Docker daemon to be ready with polling.
+ */
+async function waitForDockerReady(socketPath, timeoutMs) {
+    const start = Date.now();
+    let lastError = null;
+    while (Date.now() - start < timeoutMs) {
+        try {
+            if (existsSync(socketPath)) {
+                const docker = new Docker({ socketPath });
+                await docker.ping();
+                console.log('[Harpoon] Docker is ready');
+                return;
+            }
+        }
+        catch (e) {
+            lastError = e;
+        }
+        await new Promise(r => setTimeout(r, 500));
+    }
+    throw new Error(`[Harpoon] Docker not ready after ${timeoutMs}ms: ${lastError?.message}`);
+}
+/**
+ * Ensure Docker is running, auto-starting if needed.
+ * This is the Alchemy.run-style declarative approach.
+ */
+async function ensureDockerRunning() {
+    if (dockerEnsured)
+        return;
+    const socketPath = detectDockerSocket();
+    // Check if already running
+    if (existsSync(socketPath)) {
+        try {
+            const docker = new Docker({ socketPath });
+            await docker.ping();
+            dockerEnsured = true;
+            return; // Docker is ready
+        }
+        catch {
+            // Socket exists but daemon not responding, wait for it
+            console.log('[Harpoon] Docker socket exists but daemon not responding, waiting...');
+        }
+    }
+    else {
+        // Socket doesn't exist, start Docker
+        console.log('[Harpoon] Docker not running, attempting auto-start...');
+        startDockerDesktop();
+    }
+    // Wait for Docker to be ready
+    await waitForDockerReady(socketPath, DOCKER_STARTUP_TIMEOUT_MS);
+    dockerEnsured = true;
+}
+/**
+ * Get Docker client with auto-start support.
+ * Ensures Docker is running before returning client.
+ */
+async function getDockerAsync() {
+    await ensureDockerRunning();
+    return getDocker();
+}
 /**
  * Set a custom Docker client.
  * Useful for testing or custom configurations.
@@ -100,7 +187,7 @@ function registerCleanup() {
  */
 export async function Network(name, config = {}) {
     registerCleanup();
-    const docker = getDocker();
+    const docker = await getDockerAsync();
     const scope = Effect.runSync(Scope.make());
     const effectConfig = {
         name,
@@ -139,7 +226,7 @@ export async function Network(name, config = {}) {
  */
 export async function Container(name, config) {
     registerCleanup();
-    const docker = getDocker();
+    const docker = await getDockerAsync();
     const scope = Effect.runSync(Scope.make());
     // Convert NetworkResource to { name: string }
     const networks = config.networks?.map((n) => 'destroy' in n ? { name: n.name } : n);
@@ -169,6 +256,15 @@ export async function Container(name, config) {
         async getIp(networkName) {
             return Effect.runPromise(effectResource.getIp(networkName));
         },
+        async stats() {
+            return Effect.runPromise(effectResource.stats());
+        },
+        async exec(cmd, options) {
+            return Effect.runPromise(effectResource.exec({ cmd, ...options }));
+        },
+        async streamLogs(options) {
+            return Effect.runPromise(effectResource.streamLogs(options));
+        },
         async destroy() {
             await cleanup();
             resources.delete(resourceId);
@@ -199,7 +295,7 @@ export async function Container(name, config) {
  */
 export async function database(name, config) {
     registerCleanup();
-    const docker = getDocker();
+    const docker = await getDockerAsync();
     const scope = Effect.runSync(Scope.make());
     // Convert NetworkResource to { name: string }
     const networks = config.networks?.map((n) => 'destroy' in n ? { name: n.name } : n);
@@ -232,6 +328,15 @@ export async function database(name, config) {
         async getIp(networkName) {
             return Effect.runPromise(effectResource.getIp(networkName));
         },
+        async stats() {
+            return Effect.runPromise(effectResource.stats());
+        },
+        async exec(cmd, options) {
+            return Effect.runPromise(effectResource.exec({ cmd, ...options }));
+        },
+        async streamLogs(options) {
+            return Effect.runPromise(effectResource.streamLogs(options));
+        },
         async destroy() {
             await cleanup();
             resources.delete(resourceId);

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * @harpoon/core
+ * @docker-harpoon/core
  *
  * Infrastructure as Code for Docker testing environments.
  *
  * Simple Promise-based API:
  *
  * ```typescript
- * import { Network, Container, database } from '@harpoon/core';
+ * import { Network, Container, database } from '@docker-harpoon/core';
  *
  * const network = await Network("my-net");
  * const db = await database("postgres", { image: "postgres:16" });
@@ -27,7 +27,7 @@
  * - Binding interface for env var injection and lifecycle hooks
  * - BuildBinding interface for Dockerfile transformations
  */
-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 './api';
+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, type ContainerStats, type ExecOptions, type ExecResult, type LogOptions, type LogLine, } from './api';
 export type { Binding, BuildBinding, BindingsEnv, FlatBindingsEnv, } from './bindings';
 export { isBuildBinding, mergeBindingsEnv, createEnvBinding, } from './bindings';
 export { HarpoonError, NetworkError, ImageError, ContainerError, ScopeError, BindingError, toHarpoonError, asCause, isHarpoonError, isNetworkError, isImageError, isContainerError, isScopeError, isBindingError, } from './errors';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,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,OAAO,CAAC;AAIf,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,cAAc,EACd,OAAO,EACP,cAAc,EACd,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,UAAU,CAAC;AAElB,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAIhD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,EAC9B,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,GAChB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,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,EAGlB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,GACb,MAAM,OAAO,CAAC;AAIf,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,cAAc,EACd,OAAO,EACP,cAAc,EACd,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,UAAU,CAAC;AAElB,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAIhD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,EAC9B,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,GAChB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -1,12 +1,12 @@
 /**
- * @harpoon/core
+ * @docker-harpoon/core
  *
  * Infrastructure as Code for Docker testing environments.
  *
  * Simple Promise-based API:
  *
  * ```typescript
- * import { Network, Container, database } from '@harpoon/core';
+ * import { Network, Container, database } from '@docker-harpoon/core';
  *
  * const network = await Network("my-net");
  * const db = await database("postgres", { image: "postgres:16" });

package/dist/resources/container.d.ts

@@ -9,6 +9,7 @@
 import { Effect, Scope } from 'effect';
 import Docker from 'dockerode';
 import type { Binding } from '../bindings/types';
+import { type ContainerStats, type ExecOptions, type ExecResult, type LogOptions, type LogLine } from './schemas';
 export interface PortMapping {
     internal: number;
     external: number;
@@ -34,9 +35,18 @@ export interface ShutdownMetadata {
 export interface ContainerResource {
     readonly id: string;
     readonly name: string;
+    /** Wait for a log pattern to appear */
     readonly waitForLog: (pattern: string | RegExp, timeoutMs?: number) => Effect.Effect<void, Error>;
+    /** Stop container gracefully with signal */
     readonly stopGracefully: (signal?: string, timeoutMs?: number) => Effect.Effect<ShutdownMetadata, Error>;
+    /** Get container IP in a specific network */
     readonly getIp: (networkName: string) => Effect.Effect<string, Error>;
+    /** Get container resource statistics (CPU, memory, network) */
+    readonly stats: () => Effect.Effect<ContainerStats, Error>;
+    /** Execute a command inside the container */
+    readonly exec: (options: ExecOptions) => Effect.Effect<ExecResult, Error>;
+    /** Stream container logs as an async iterable */
+    readonly streamLogs: (options?: LogOptions) => Effect.Effect<AsyncIterable<LogLine>, Error>;
 }
 export declare const Container: (resourceId: string, config: ContainerConfig, docker: Docker) => Effect.Effect<ContainerResource, Error, Scope.Scope>;
 //# sourceMappingURL=container.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/resources/container.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAkB,MAAM,QAAQ,CAAC;AACvD,OAAO,MAAM,MAAM,WAAW,CAAC;AAE/B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,CACnB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,CAAC,EAAE,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,CACvB,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACvE;AAgED,eAAO,MAAM,SAAS,GACpB,YAAY,MAAM,EAClB,QAAQ,eAAe,EACvB,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAsSnD,CAAC"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/resources/container.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,EAA0B,MAAM,QAAQ,CAAC;AAC/D,OAAO,MAAM,MAAM,WAAW,CAAC;AAE/B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,EACb,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,CACnB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,CAAC,EAAE,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,CACvB,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IAC5C,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtE,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IAC3D,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAC1E,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;CAC7F;AA6ED,eAAO,MAAM,SAAS,GACpB,YAAY,MAAM,EAClB,QAAQ,eAAe,EACvB,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAuhBnD,CAAC"}

package/dist/resources/container.js

@@ -9,7 +9,8 @@
 import { Effect, Schedule, Exit } from 'effect';
 import { toHarpoonError, ContainerError } from '../errors';
 import { mergeBindingsEnv } from '../bindings/types';
-const CLEANUP_TIMEOUT_MS = 10_000;
+import { containerStatsSchema, execOptionsSchema, execResultSchema, logOptionsSchema, } from './schemas';
+const CLEANUP_TIMEOUT_MS = 30_000; // 30 seconds for database graceful shutdown
 const safeRemoveContainer = async (docker, containerId, containerName) => {
     const container = docker.getContainer(containerId);
     try {
@@ -19,16 +20,27 @@ const safeRemoveContainer = async (docker, containerId, containerName) => {
             try {
                 await container.kill({ signal: 'SIGTERM' });
                 await new Promise((resolve) => {
+                    let resolved = false;
+                    const safeResolve = () => {
+                        if (!resolved) {
+                            resolved = true;
+                            clearTimeout(timeout);
+                            resolve();
+                        }
+                    };
                     const checkStopped = async () => {
+                        if (resolved)
+                            return;
                         try {
                             const state = await container.inspect();
                             if (!state.State.Running) {
-                                resolve();
+                                safeResolve();
                                 return;
                             }
                         }
                         catch {
-                            resolve();
+                            // Container gone or error - consider it stopped
+                            safeResolve();
                             return;
                         }
                         setTimeout(checkStopped, 100);
@@ -36,9 +48,9 @@ const safeRemoveContainer = async (docker, containerId, containerName) => {
                     const timeout = setTimeout(() => {
                         console.warn(`[Cleanup] Container ${containerName} did not stop gracefully, forcing`);
                         container.kill({ signal: 'SIGKILL' }).catch(() => { });
-                        resolve();
+                        safeResolve();
                     }, 5000);
-                    checkStopped().finally(() => clearTimeout(timeout));
+                    checkStopped();
                 });
             }
             catch (e) {
@@ -222,6 +234,211 @@ export const Container = (resourceId, config, docker) => Effect.acquireRelease(E
                 },
                 catch: (e) => new Error(`getIp failed: ${e}`),
             }),
+            /**
+             * Get container resource statistics (CPU, memory, network).
+             * Uses dockerode stats() with one-shot mode for a single snapshot.
+             */
+            stats: () => Effect.tryPromise({
+                try: async () => {
+                    const statsData = await container.stats({ stream: false });
+                    // Calculate CPU percentage
+                    const cpuDelta = statsData.cpu_stats.cpu_usage.total_usage -
+                        statsData.precpu_stats.cpu_usage.total_usage;
+                    const systemDelta = statsData.cpu_stats.system_cpu_usage -
+                        statsData.precpu_stats.system_cpu_usage;
+                    const cpuCores = statsData.cpu_stats.online_cpus || 1;
+                    const cpuPercent = systemDelta > 0
+                        ? (cpuDelta / systemDelta) * cpuCores * 100
+                        : 0;
+                    // Calculate memory stats
+                    const memUsage = statsData.memory_stats?.usage ?? 0;
+                    const memLimit = statsData.memory_stats?.limit ?? 0;
+                    const memPercent = memLimit > 0 ? (memUsage / memLimit) * 100 : 0;
+                    // Calculate network stats (sum all interfaces)
+                    const networks = statsData.networks ?? {};
+                    let rxBytes = 0;
+                    let txBytes = 0;
+                    let rxPackets = 0;
+                    let txPackets = 0;
+                    for (const iface of Object.values(networks)) {
+                        rxBytes += iface.rx_bytes ?? 0;
+                        txBytes += iface.tx_bytes ?? 0;
+                        rxPackets += iface.rx_packets ?? 0;
+                        txPackets += iface.tx_packets ?? 0;
+                    }
+                    const result = {
+                        cpu: {
+                            usage: statsData.cpu_stats.cpu_usage.total_usage,
+                            system: statsData.cpu_stats.system_cpu_usage,
+                            percent: Math.round(cpuPercent * 100) / 100,
+                            cores: cpuCores,
+                        },
+                        memory: {
+                            usage: memUsage,
+                            limit: memLimit,
+                            percent: Math.round(memPercent * 100) / 100,
+                            usageMB: Math.round((memUsage / 1024 / 1024) * 100) / 100,
+                            limitMB: Math.round((memLimit / 1024 / 1024) * 100) / 100,
+                        },
+                        network: {
+                            rxBytes,
+                            txBytes,
+                            rxPackets,
+                            txPackets,
+                        },
+                        timestamp: new Date().toISOString(),
+                        containerId: container.id,
+                    };
+                    // Validate with Zod schema
+                    return containerStatsSchema.parse(result);
+                },
+                catch: (e) => new Error(`stats failed: ${e}`),
+            }),
+            /**
+             * Execute a command inside the container.
+             * Returns stdout, stderr, and exit code.
+             */
+            exec: (options) => Effect.tryPromise({
+                try: async () => {
+                    const startTime = Date.now();
+                    // Validate input with Zod
+                    const validated = execOptionsSchema.parse(options);
+                    // Create exec instance
+                    const exec = await container.exec({
+                        Cmd: validated.cmd,
+                        AttachStdout: true,
+                        AttachStderr: true,
+                        Env: validated.env
+                            ? Object.entries(validated.env).map(([k, v]) => `${k}=${v}`)
+                            : undefined,
+                        WorkingDir: validated.workingDir,
+                        User: validated.user,
+                        Privileged: validated.privileged,
+                        Tty: validated.tty,
+                    });
+                    // Start exec and capture output
+                    const stream = await exec.start({ Detach: false, Tty: validated.tty ?? false });
+                    // Collect output chunks
+                    const stdoutChunks = [];
+                    const stderrChunks = [];
+                    await new Promise((resolve, reject) => {
+                        // Docker multiplexes stdout/stderr in the stream
+                        // First 8 bytes of each frame indicate stream type and size
+                        stream.on('data', (chunk) => {
+                            // For TTY mode, all output goes to stdout
+                            if (validated.tty) {
+                                stdoutChunks.push(chunk);
+                                return;
+                            }
+                            // Parse multiplexed stream (Docker stream format)
+                            let offset = 0;
+                            while (offset < chunk.length) {
+                                if (offset + 8 > chunk.length)
+                                    break;
+                                const streamType = chunk.readUInt8(offset);
+                                const size = chunk.readUInt32BE(offset + 4);
+                                const payload = chunk.slice(offset + 8, offset + 8 + size);
+                                if (streamType === 1) {
+                                    stdoutChunks.push(payload);
+                                }
+                                else if (streamType === 2) {
+                                    stderrChunks.push(payload);
+                                }
+                                offset += 8 + size;
+                            }
+                        });
+                        stream.on('end', resolve);
+                        stream.on('error', reject);
+                    });
+                    // Get exit code
+                    const inspection = await exec.inspect();
+                    const exitCode = inspection.ExitCode ?? 0;
+                    const durationMs = Date.now() - startTime;
+                    const result = {
+                        exitCode,
+                        stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+                        stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+                        durationMs,
+                    };
+                    // Validate output with Zod
+                    return execResultSchema.parse(result);
+                },
+                catch: (e) => new Error(`exec failed: ${e}`),
+            }),
+            /**
+             * Stream container logs as an async iterable.
+             * Yields LogLine objects with stream type and message.
+             */
+            streamLogs: (options) => Effect.tryPromise({
+                try: async () => {
+                    // Validate and apply defaults
+                    const opts = logOptionsSchema.parse(options ?? {});
+                    const stdout = opts.stdout ?? true;
+                    const stderr = opts.stderr ?? true;
+                    const timestamps = opts.timestamps ?? false;
+                    const stream = await container.logs({
+                        follow: true,
+                        stdout,
+                        stderr,
+                        since: opts.since,
+                        until: opts.until,
+                        tail: opts.tail,
+                        timestamps,
+                    });
+                    // Create a wrapper to make the stream async iterable
+                    const readable = stream;
+                    // Convert NodeJS.ReadableStream to AsyncIterable<LogLine>
+                    async function* logIterator() {
+                        const chunks = [];
+                        // Use Promise-based iteration for ReadableStream
+                        for await (const chunk of readable) {
+                            // Parse Docker log format (8-byte header + payload)
+                            let offset = 0;
+                            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                            while (offset < buffer.length) {
+                                if (offset + 8 > buffer.length) {
+                                    // Incomplete header, yield rest as stdout
+                                    yield {
+                                        stream: 'stdout',
+                                        message: buffer.slice(offset).toString('utf-8').trim(),
+                                    };
+                                    break;
+                                }
+                                const streamType = buffer.readUInt8(offset);
+                                const size = buffer.readUInt32BE(offset + 4);
+                                if (offset + 8 + size > buffer.length) {
+                                    // Incomplete payload
+                                    yield {
+                                        stream: streamType === 2 ? 'stderr' : 'stdout',
+                                        message: buffer.slice(offset + 8).toString('utf-8').trim(),
+                                    };
+                                    break;
+                                }
+                                const payload = buffer.slice(offset + 8, offset + 8 + size);
+                                const message = payload.toString('utf-8');
+                                // Parse timestamp if present (format: "2024-01-14T21:00:00.000000000Z message")
+                                let timestamp;
+                                let content = message;
+                                if (timestamps) {
+                                    const match = message.match(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\s+(.*)$/s);
+                                    if (match) {
+                                        timestamp = match[1];
+                                        content = match[2] ?? '';
+                                    }
+                                }
+                                yield {
+                                    stream: streamType === 2 ? 'stderr' : 'stdout',
+                                    timestamp,
+                                    message: content.trim(),
+                                };
+                                offset += 8 + size;
+                            }
+                        }
+                    }
+                    return logIterator();
+                },
+                catch: (e) => new Error(`streamLogs failed: ${e}`),
+            }),
         };
         // Call onStart hooks for bindings
         // This is done in Effect context for proper error handling

package/dist/resources/index.d.ts

@@ -7,6 +7,8 @@ export { Network } from './network';
 export type { NetworkConfig, NetworkResource } from './network';
 export { Container } from './container';
 export type { ContainerConfig, ContainerResource, PortMapping, ShutdownMetadata, } from './container';
+export { containerStatsSchema, execOptionsSchema, execResultSchema, logOptionsSchema, logLineSchema, cpuStatsSchema, memoryStatsSchema, networkStatsSchema, statsOptionsSchema, } from './schemas';
+export type { ContainerStats, CpuStats, MemoryStats, NetworkStats, ExecOptions, ExecResult, LogOptions, LogLine, StatsOptions, } from './schemas';
 export { Image } from './image';
 export type { ImageConfig, ImageResource } from './image';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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;AAGrB,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,cAAc,EACd,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,UAAU,EACV,OAAO,EACP,YAAY,GACb,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/resources/index.js

@@ -5,4 +5,6 @@
  */
 export { Network } from './network';
 export { Container } from './container';
+// Container resource schemas and types
+export { containerStatsSchema, execOptionsSchema, execResultSchema, logOptionsSchema, logLineSchema, cpuStatsSchema, memoryStatsSchema, networkStatsSchema, statsOptionsSchema, } from './schemas';
 export { Image } from './image';

package/dist/resources/schemas.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Zod Schemas for Container Resources
+ *
+ * Defines validation schemas for container stats, exec, and log streaming.
+ * Following Alchemy.run patterns for declarative resource definitions.
+ */
+import { z } from 'zod';
+/**
+ * CPU statistics from Docker container
+ */
+export declare const cpuStatsSchema: z.ZodObject<{
+    usage: z.ZodNumber;
+    system: z.ZodNumber;
+    percent: z.ZodNumber;
+    cores: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Memory statistics from Docker container
+ */
+export declare const memoryStatsSchema: z.ZodObject<{
+    usage: z.ZodNumber;
+    limit: z.ZodNumber;
+    percent: z.ZodNumber;
+    usageMB: z.ZodNumber;
+    limitMB: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Network I/O statistics from Docker container
+ */
+export declare const networkStatsSchema: z.ZodObject<{
+    rxBytes: z.ZodNumber;
+    txBytes: z.ZodNumber;
+    rxPackets: z.ZodNumber;
+    txPackets: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Complete container statistics
+ */
+export declare const containerStatsSchema: z.ZodObject<{
+    cpu: z.ZodObject<{
+        usage: z.ZodNumber;
+        system: z.ZodNumber;
+        percent: z.ZodNumber;
+        cores: z.ZodNumber;
+    }, z.core.$strip>;
+    memory: z.ZodObject<{
+        usage: z.ZodNumber;
+        limit: z.ZodNumber;
+        percent: z.ZodNumber;
+        usageMB: z.ZodNumber;
+        limitMB: z.ZodNumber;
+    }, z.core.$strip>;
+    network: z.ZodObject<{
+        rxBytes: z.ZodNumber;
+        txBytes: z.ZodNumber;
+        rxPackets: z.ZodNumber;
+        txPackets: z.ZodNumber;
+    }, z.core.$strip>;
+    timestamp: z.ZodString;
+    containerId: z.ZodString;
+}, z.core.$strip>;
+export type ContainerStats = z.infer<typeof containerStatsSchema>;
+export type CpuStats = z.infer<typeof cpuStatsSchema>;
+export type MemoryStats = z.infer<typeof memoryStatsSchema>;
+export type NetworkStats = z.infer<typeof networkStatsSchema>;
+/**
+ * Options for executing a command in a container
+ */
+export declare const execOptionsSchema: z.ZodObject<{
+    cmd: z.ZodArray<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workingDir: z.ZodOptional<z.ZodString>;
+    user: z.ZodOptional<z.ZodString>;
+    privileged: z.ZodOptional<z.ZodBoolean>;
+    tty: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Result of executing a command in a container
+ */
+export declare const execResultSchema: z.ZodObject<{
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    durationMs: z.ZodNumber;
+}, z.core.$strip>;
+export type ExecOptions = z.infer<typeof execOptionsSchema>;
+export type ExecResult = z.infer<typeof execResultSchema>;
+/**
+ * Options for streaming container logs
+ */
+export declare const logOptionsSchema: z.ZodObject<{
+    stdout: z.ZodOptional<z.ZodBoolean>;
+    stderr: z.ZodOptional<z.ZodBoolean>;
+    since: z.ZodOptional<z.ZodNumber>;
+    until: z.ZodOptional<z.ZodNumber>;
+    tail: z.ZodOptional<z.ZodNumber>;
+    timestamps: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * A single log line from a container
+ */
+export declare const logLineSchema: z.ZodObject<{
+    stream: z.ZodEnum<{
+        stdout: "stdout";
+        stderr: "stderr";
+    }>;
+    timestamp: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type LogOptions = z.infer<typeof logOptionsSchema>;
+export type LogLine = z.infer<typeof logLineSchema>;
+/**
+ * Options for getting container stats
+ */
+export declare const statsOptionsSchema: z.ZodObject<{
+    stream: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    oneShot: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type StatsOptions = z.infer<typeof statsOptionsSchema>;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/resources/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;iBAKzB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;iBAM5B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;iBAM/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;iBAO5B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAK3B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;iBAO3B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;iBAIxB,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAIpD;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/resources/schemas.js

@@ -0,0 +1,95 @@
+/**
+ * Zod Schemas for Container Resources
+ *
+ * Defines validation schemas for container stats, exec, and log streaming.
+ * Following Alchemy.run patterns for declarative resource definitions.
+ */
+import { z } from 'zod';
+// ============ Container Stats Schema ============
+/**
+ * CPU statistics from Docker container
+ */
+export const cpuStatsSchema = z.object({
+    usage: z.number().min(0).describe('CPU usage in nanoseconds'),
+    system: z.number().min(0).describe('System CPU usage in nanoseconds'),
+    percent: z.number().min(0).max(100).describe('CPU usage as percentage'),
+    cores: z.number().int().min(0).describe('Number of CPU cores available'),
+});
+/**
+ * Memory statistics from Docker container
+ */
+export const memoryStatsSchema = z.object({
+    usage: z.number().min(0).describe('Current memory usage in bytes'),
+    limit: z.number().min(0).describe('Memory limit in bytes'),
+    percent: z.number().min(0).max(100).describe('Memory usage as percentage'),
+    usageMB: z.number().min(0).describe('Current memory usage in megabytes'),
+    limitMB: z.number().min(0).describe('Memory limit in megabytes'),
+});
+/**
+ * Network I/O statistics from Docker container
+ */
+export const networkStatsSchema = z.object({
+    rxBytes: z.number().min(0).describe('Bytes received'),
+    txBytes: z.number().min(0).describe('Bytes transmitted'),
+    rxPackets: z.number().min(0).describe('Packets received'),
+    txPackets: z.number().min(0).describe('Packets transmitted'),
+});
+/**
+ * Complete container statistics
+ */
+export const containerStatsSchema = z.object({
+    cpu: cpuStatsSchema,
+    memory: memoryStatsSchema,
+    network: networkStatsSchema,
+    timestamp: z.string().datetime().describe('ISO 8601 timestamp of stats collection'),
+    containerId: z.string().describe('Docker container ID'),
+});
+// ============ Exec Schemas ============
+/**
+ * Options for executing a command in a container
+ */
+export const execOptionsSchema = z.object({
+    cmd: z.array(z.string()).min(1).describe('Command and arguments to execute'),
+    env: z.record(z.string(), z.string()).optional().describe('Environment variables'),
+    workingDir: z.string().optional().describe('Working directory for the command'),
+    user: z.string().optional().describe('User to run the command as'),
+    privileged: z.boolean().optional().describe('Run with elevated privileges'),
+    tty: z.boolean().optional().describe('Allocate a pseudo-TTY'),
+});
+/**
+ * Result of executing a command in a container
+ */
+export const execResultSchema = z.object({
+    exitCode: z.number().int().describe('Exit code of the command'),
+    stdout: z.string().describe('Standard output'),
+    stderr: z.string().describe('Standard error'),
+    durationMs: z.number().min(0).describe('Execution duration in milliseconds'),
+});
+// ============ Log Streaming Schemas ============
+/**
+ * Options for streaming container logs
+ */
+export const logOptionsSchema = z.object({
+    stdout: z.boolean().optional().describe('Include stdout (default: true)'),
+    stderr: z.boolean().optional().describe('Include stderr (default: true)'),
+    since: z.number().optional().describe('Unix timestamp to start from'),
+    until: z.number().optional().describe('Unix timestamp to end at'),
+    tail: z.number().int().min(0).optional().describe('Number of lines to tail'),
+    timestamps: z.boolean().optional().describe('Include timestamps (default: false)'),
+});
+/**
+ * A single log line from a container
+ */
+export const logLineSchema = z.object({
+    stream: z.enum(['stdout', 'stderr']).describe('Which stream this line came from'),
+    timestamp: z.string().datetime().optional().describe('Timestamp if enabled'),
+    message: z.string().describe('Log message content'),
+});
+// ============ Stats Options Schema ============
+/**
+ * Options for getting container stats
+ */
+export const statsOptionsSchema = z.object({
+    stream: z.boolean().optional().default(false).describe('Stream continuous stats'),
+    oneShot: z.boolean().optional().default(true).describe('Get single stats snapshot'),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docker-harpoon/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
   "description": "Core Docker resource primitives and binding interface",
   "type": "module",
@@ -12,7 +12,9 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit"