feat(host): Add DockerHost version & image-prune APIs, extend network creation options, return exec inspect info, and improve image import/store and streaming

readme.hints.md

@@ -1,5 +1,201 @@
 # Docker Module - Development Hints
 
+## New Features (2025-11-25 - v5.1.0)
+
+### 1. Enhanced Network Creation with Full Configuration Support
+
+**Problem:** Users were unable to create non-overlay networks or customize network configuration. The `INetworkCreationDescriptor` interface only had a `Name` property, and `DockerNetwork._create()` hardcoded `Driver: 'overlay'`.
+
+**Solution:** Expanded the interface and implementation to support all Docker network configuration options:
+
+```typescript
+// New interface properties:
+export interface INetworkCreationDescriptor {
+  Name: string;
+  Driver?: 'bridge' | 'overlay' | 'host' | 'none' | 'macvlan';  // NEW
+  Attachable?: boolean;  // NEW
+  Labels?: Record<string, string>;  // NEW
+  IPAM?: {  // NEW - IP Address Management
+    Driver?: string;
+    Config?: Array<{
+      Subnet?: string;
+      Gateway?: string;
+      IPRange?: string;
+      AuxiliaryAddresses?: Record<string, string>;
+    }>;
+  };
+  Internal?: boolean;  // NEW
+  EnableIPv6?: boolean;  // NEW
+}
+```
+
+**Usage Example:**
+```typescript
+// Create bridge network with custom IPAM
+const network = await docker.createNetwork({
+  Name: 'custom-bridge',
+  Driver: 'bridge',
+  IPAM: {
+    Config: [{
+      Subnet: '172.20.0.0/16',
+      Gateway: '172.20.0.1',
+    }]
+  },
+  Labels: { environment: 'production' },
+});
+```
+
+**Files Modified:**
+- `ts/interfaces/network.ts` - Added all missing properties to interface
+- `ts/classes.network.ts` - Updated `_create()` to pass through descriptor properties instead of hardcoding
+
+### 2. Docker Daemon Version Information
+
+**Added:** `dockerHost.getVersion()` method to retrieve Docker daemon version information.
+
+**Purpose:** Essential for API compatibility checking, debugging, and ensuring minimum Docker version requirements.
+
+**Returns:**
+```typescript
+{
+  Version: string;         // e.g., "20.10.21"
+  ApiVersion: string;      // e.g., "1.41"
+  MinAPIVersion?: string;  // Minimum supported API version
+  GitCommit: string;
+  GoVersion: string;
+  Os: string;              // e.g., "linux"
+  Arch: string;            // e.g., "amd64"
+  KernelVersion: string;
+  BuildTime?: string;
+}
+```
+
+**Usage Example:**
+```typescript
+const version = await docker.getVersion();
+console.log(`Docker ${version.Version} (API ${version.ApiVersion})`);
+console.log(`Platform: ${version.Os}/${version.Arch}`);
+```
+
+**Files Modified:**
+- `ts/classes.host.ts` - Added `getVersion()` method after `ping()`
+
+### 3. Image Pruning for Disk Space Management
+
+**Added:** `dockerHost.pruneImages(options?)` method to clean up unused images.
+
+**Purpose:** Automated disk space management, CI/CD cleanup, scheduled maintenance tasks.
+
+**Options:**
+```typescript
+{
+  dangling?: boolean;  // Remove untagged images
+  filters?: Record<string, string[]>;  // Custom filters (until, label, etc.)
+}
+```
+
+**Returns:**
+```typescript
+{
+  ImagesDeleted: Array<{ Untagged?: string; Deleted?: string }>;
+  SpaceReclaimed: number;  // Bytes freed
+}
+```
+
+**Usage Example:**
+```typescript
+// Remove dangling images
+const result = await docker.pruneImages({ dangling: true });
+console.log(`Reclaimed: ${(result.SpaceReclaimed / 1024 / 1024).toFixed(2)} MB`);
+
+// Remove old images (older than 7 days)
+await docker.pruneImages({
+  filters: {
+    until: ['168h']
+  }
+});
+```
+
+**Files Modified:**
+- `ts/classes.host.ts` - Added `pruneImages()` method with filter support
+
+### 4. Exec Command Exit Codes and Inspection
+
+**Problem:** Users could not determine if exec commands succeeded or failed. The `container.exec()` method returned a stream but provided no way to access exit codes, which are essential for:
+- Health checks (e.g., `pg_isready` exit code)
+- Test automation (npm test success/failure)
+- Deployment validation (migration checks)
+- Container readiness probes
+
+**Solution:** Added `inspect()` method to `exec()` return value that provides comprehensive execution information.
+
+**New Return Type:**
+```typescript
+{
+  stream: Duplex;
+  close: () => Promise<void>;
+  inspect: () => Promise<IExecInspectInfo>;  // NEW
+}
+```
+
+**IExecInspectInfo Interface:**
+```typescript
+export interface IExecInspectInfo {
+  ExitCode: number;        // 0 = success, non-zero = failure
+  Running: boolean;        // Whether exec is still running
+  Pid: number;             // Process ID
+  ContainerID: string;     // Container where exec ran
+  ID: string;              // Exec instance ID
+  OpenStderr: boolean;
+  OpenStdin: boolean;
+  OpenStdout: boolean;
+  CanRemove: boolean;
+  DetachKeys: string;
+  ProcessConfig: {
+    tty: boolean;
+    entrypoint: string;
+    arguments: string[];
+    privileged: boolean;
+  };
+}
+```
+
+**Usage Example:**
+```typescript
+// Health check with exit code
+const { stream, close, inspect } = await container.exec('pg_isready -U postgres');
+
+stream.on('end', async () => {
+  const info = await inspect();
+
+  if (info.ExitCode === 0) {
+    console.log('✅ Database is ready');
+  } else {
+    console.log(`❌ Database check failed (exit code ${info.ExitCode})`);
+  }
+
+  await close();
+});
+```
+
+**Real-World Use Cases Enabled:**
+- Health checks: Verify service readiness with proper exit code handling
+- Test automation: Run tests in container and determine pass/fail
+- Deployment validation: Execute migration checks and verify success
+- CI/CD pipelines: Run build/test commands and get accurate results
+
+**Files Modified:**
+- `ts/interfaces/container.ts` - Added `IExecInspectInfo` interface
+- `ts/classes.container.ts` - Updated `exec()` return type and added `inspect()` implementation
+
+### Implementation Notes
+
+All changes are non-breaking additions that enhance existing functionality:
+- Network creation: New optional properties with sensible defaults
+- getVersion(): New method, no changes to existing APIs
+- pruneImages(): New method, no changes to existing APIs
+- exec() inspect(): Added to return value, existing stream/close properties unchanged
+
 ## getContainerById() Bug Fix (2025-11-24 - v5.0.1)
 
 ### Problem