v2.1.0

.serena/project.yml

@@ -1,68 +0,0 @@
-# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
-#  * For C, use cpp
-#  * For JavaScript, use typescript
-# Special requirements:
-#  * csharp: Requires the presence of a .sln file in the project folder.
-language: typescript
-
-# whether to use the project's gitignore file to ignore files
-# Added on 2025-04-07
-ignore_all_files_in_gitignore: true
-# list of additional paths to ignore
-# same syntax as gitignore, so you can use * and **
-# Was previously called `ignored_dirs`, please update your config if you are using that.
-# Added (renamed) on 2025-04-07
-ignored_paths: []
-
-# whether the project is in read-only mode
-# If set to true, all editing tools will be disabled and attempts to use them will result in an error
-# Added on 2025-04-18
-read_only: false
-
-
-# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
-# Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
-# execute `uv run scripts/print_tool_overview.py`.
-#
-#  * `activate_project`: Activates a project by name.
-#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
-#  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_lines`: Deletes a range of lines within a file.
-#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
-#  * `execute_shell_command`: Executes a shell command.
-#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
-#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
-#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
-#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Gets the initial instructions for the current project.
-#     Should only be used in settings where the system prompt cannot be set,
-#     e.g. in clients you have no control over, like Claude Desktop.
-#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_at_line`: Inserts content at a given line in a file.
-#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: Lists memories in Serena's project-specific memory store.
-#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
-#  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
-#  * `remove_project`: Removes a project from the Serena configuration.
-#  * `replace_lines`: Replaces a range of lines within a file with new content.
-#  * `replace_symbol_body`: Replaces the full definition of a symbol.
-#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
-#  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
-#  * `switch_modes`: Activates modes by providing a list of their names
-#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
-#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
-#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
-#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
-excluded_tools: []
-
-# initial prompt for the project. It will always be given to the LLM upon activating the project
-# (contrary to the memories, which are loaded on demand).
-initial_prompt: ""
-
-project_name: "docker"

changelog.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2025-11-18 - 2.1.0 - feat(DockerHost)
+Add DockerHost.ping() to check Docker daemon availability and document health-check usage
+
+- Add DockerHost.ping() method that issues a GET to /_ping and throws an error if the response status is not 200
+- Update README: show ping() in Quick Start, add health check examples (isDockerHealthy, waitForDocker) and mention Health Checks in Key Concepts
+
+## 2025-11-18 - 2.0.0 - BREAKING CHANGE(DockerHost)
+Rename DockerHost constructor option 'dockerSockPath' to 'socketPath' and update internal socket path handling
+
+- Breaking: constructor option renamed from 'dockerSockPath' to 'socketPath' — callers must update their code.
+- Constructor now reads the provided 'socketPath' option first, then falls back to DOCKER_HOST, CI, and finally the default unix socket.
+- README examples and documentation updated to use 'socketPath'.
+
+## 2025-11-17 - 1.3.6 - fix(streaming)
+Convert smartrequest v5 web ReadableStreams to Node.js streams and update deps for streaming compatibility
+
+- Upgrade @push.rocks/smartrequest to ^5.0.1 and bump @git.zone dev tooling (@git.zone/tsbuild, tsrun, tstest).
+- requestStreaming now uses response.stream() (web ReadableStream) and converts it to a Node.js Readable via plugins.smartstream.nodewebhelpers.convertWebReadableToNodeReadable for backward compatibility.
+- Updated consumers of streaming responses (DockerHost.getEventObservable, DockerImage.createFromTarStream, DockerImage.exportToTarStream) to work with the converted Node.js stream and preserve event/backpressure semantics (.on, .pause, .resume).
+- Added readme.hints.md documenting the smartrequest v5 migration, conversion approach, modified files, and test/build status (type errors resolved and Node.js tests passing).
+- Removed project metadata file (.serena/project.yml) from the repository.
+
 ## 2025-08-19 - 1.3.5 - fix(core)
 Stabilize CI/workflows and runtime: update CI images/metadata, improve streaming requests and image handling, and fix tests & package metadata
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apiclient.xyz/docker",
-  "version": "1.3.5",
+  "version": "2.1.0",
   "description": "Provides easy communication with Docker remote API from Node.js, with TypeScript support.",
   "private": false,
   "main": "dist_ts/index.js",
@@ -37,23 +37,23 @@
     "@push.rocks/smartarchive": "^4.2.2",
     "@push.rocks/smartbucket": "^3.3.10",
     "@push.rocks/smartfile": "^11.2.7",
-    "@push.rocks/smartjson": "^5.0.20",
-    "@push.rocks/smartlog": "^3.1.8",
-    "@push.rocks/smartnetwork": "^4.1.2",
+    "@push.rocks/smartjson": "^5.2.0",
+    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/smartnetwork": "^4.4.0",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartrequest": "^4.3.1",
+    "@push.rocks/smartrequest": "^5.0.1",
     "@push.rocks/smartstream": "^3.2.5",
-    "@push.rocks/smartstring": "^4.0.15",
+    "@push.rocks/smartstring": "^4.1.0",
     "@push.rocks/smartunique": "^3.0.9",
     "@push.rocks/smartversion": "^3.0.5",
-    "@tsclass/tsclass": "^9.2.0",
+    "@tsclass/tsclass": "^9.3.0",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.6.7",
-    "@git.zone/tsrun": "^1.3.3",
-    "@git.zone/tstest": "^2.3.5",
+    "@git.zone/tsbuild": "^3.1.0",
+    "@git.zone/tsrun": "^2.0.0",
+    "@git.zone/tstest": "^2.8.2",
     "@push.rocks/qenv": "^6.1.3",
     "@types/node": "22.7.5"
   },

readme.hints.md

@@ -0,0 +1,29 @@
+# Docker Module - Development Hints
+
+## smartrequest v5+ Migration (2025-11-17)
+
+### Breaking Change
+smartrequest v5.0.0+ returns web `ReadableStream` objects (Web Streams API) instead of Node.js streams.
+
+### Solution Implemented
+All streaming methods now convert web ReadableStreams to Node.js streams using:
+```typescript
+plugins.smartstream.nodewebhelpers.convertWebReadableToNodeReadable(webStream)
+```
+
+### Files Modified
+- `ts/classes.host.ts`:
+  - `requestStreaming()` - Converts web stream to Node.js stream before returning
+  - `getEventObservable()` - Works with converted Node.js stream
+
+- `ts/classes.image.ts`:
+  - `createFromTarStream()` - Uses converted Node.js stream for event handling
+  - `exportToTarStream()` - Uses converted Node.js stream for backpressure management
+
+### Testing
+- Build:  All 11 type errors resolved
+- Tests:  Node.js tests pass (DockerHost, DockerContainer, DockerImage, DockerImageStore)
+
+### Notes
+- The conversion maintains backward compatibility with existing code expecting Node.js stream methods (`.on()`, `.emit()`, `.pause()`, `.resume()`)
+- smartstream's `nodewebhelpers` module provides bidirectional conversion utilities between web and Node.js streams

readme.md

@@ -1,29 +1,30 @@
 # @apiclient.xyz/docker 🐳
 
-> **Powerful TypeScript client for Docker Remote API** - Build, manage, and orchestrate Docker containers, images, networks, and more with type-safe elegance.
+> **Powerful TypeScript client for Docker Remote API** - Build, manage, and orchestrate Docker containers, images, networks, and swarm services with type-safe elegance.
 
 ## 🚀 Features
 
-- 🎯 **Full TypeScript Support** - Complete type definitions for Docker API entities
+- 🎯 **Full TypeScript Support** - Complete type definitions for all Docker API entities
 - 🔄 **Async/Await Ready** - Modern promise-based architecture for seamless async operations
-- 📦 **Container Management** - Create, list, inspect, and remove containers effortlessly
+- 📦 **Container Management** - Create, list, inspect, and manage containers effortlessly
 - 🖼️ **Image Handling** - Pull from registries, build from tarballs, export, and manage tags
 - 🌐 **Network Operations** - Create and manage Docker networks with full IPAM support
 - 🔐 **Secrets Management** - Handle Docker secrets securely in swarm mode
 - 🎭 **Service Orchestration** - Deploy and manage services in Docker Swarm
-- 💾 **S3 Image Storage** - Built-in support for storing/retrieving images from S3
+- 💾 **S3 Image Storage** - Built-in support for storing/retrieving images from S3-compatible storage
 - 📊 **Event Streaming** - Real-time Docker event monitoring with RxJS observables
-- 🔧 **Registry Authentication** - Seamless authentication with Docker registries
+- 🔧 **Registry Authentication** - Seamless authentication with Docker registries including private registries
+- 🐝 **Swarm Mode** - Full support for Docker Swarm initialization and management
 
 ## 📦 Installation
 
 ```bash
-# Using npm
-npm install @apiclient.xyz/docker --save
-
 # Using pnpm (recommended)
 pnpm add @apiclient.xyz/docker
 
+# Using npm
+npm install @apiclient.xyz/docker --save
+
 # Using yarn
 yarn add @apiclient.xyz/docker
 ```
@@ -33,12 +34,43 @@ yarn add @apiclient.xyz/docker
 ```typescript
 import { DockerHost } from '@apiclient.xyz/docker';
 
-// Connect to local Docker daemon
-const docker = new DockerHost();
+// Connect to local Docker daemon (default: /var/run/docker.sock)
+const docker = new DockerHost({});
+await docker.start();
 
-// Or connect to remote Docker host
-const remoteDocker = new DockerHost({
-  socketPath: 'tcp://remote-docker-host:2375',
+// Check if Docker is accessible
+await docker.ping();
+console.log('✅ Docker is running');
+
+// List all containers
+const containers = await docker.getContainers();
+console.log(`Found ${containers.length} containers`);
+
+// Don't forget to clean up
+await docker.stop();
+```
+
+## 🔌 Socket Path Configuration
+
+The library determines which Docker socket to use in the following priority order:
+
+1. **Constructor option** - `socketPath` parameter (highest priority)
+2. **Environment variable** - `DOCKER_HOST` environment variable
+3. **CI environment** - If `CI` env var is set, uses `http://docker:2375/`
+4. **Default** - Falls back to `http://unix:/var/run/docker.sock:`
+
+```typescript
+// Explicit socket path (highest priority)
+const docker1 = new DockerHost({
+  socketPath: 'tcp://remote-host:2375',
+});
+
+// Uses DOCKER_HOST environment variable if set
+const docker2 = new DockerHost({});
+
+// Custom image store directory
+const docker3 = new DockerHost({
+  imageStoreDir: '/custom/path/to/image-store',
 });
 ```
 
@@ -51,32 +83,72 @@ The `DockerHost` class is your primary interface to interact with the Docker dae
 ```typescript
 import { DockerHost } from '@apiclient.xyz/docker';
 
-// Initialize with default local socket
-const docker = new DockerHost();
-
-// Custom initialization options
-const customDocker = new DockerHost({
-  socketPath: '/var/run/docker.sock', // Unix socket path
-  // or
-  socketPath: 'tcp://192.168.1.100:2375', // TCP connection
+// Initialize with options
+const docker = new DockerHost({
+  socketPath: '/var/run/docker.sock', // Optional: custom socket path
+  imageStoreDir: './docker-images',   // Optional: custom image store location
 });
 
-// Start and stop (for lifecycle management)
+// Start the docker host (initializes image store)
 await docker.start();
-// ... do your work
+
+// ... perform operations ...
+
+// Stop and clean up
 await docker.stop();
 ```
 
+#### Health Check / Ping Docker
+
+Check if the Docker daemon is running and accessible:
+
+```typescript
+// Ping Docker daemon
+try {
+  await docker.ping();
+  console.log('✅ Docker is running and accessible');
+} catch (error) {
+  console.error('❌ Docker is not accessible:', error.message);
+}
+
+// Use in health check function
+async function isDockerHealthy(): Promise<boolean> {
+  try {
+    await docker.ping();
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+// Example: Wait for Docker to be ready
+async function waitForDocker(timeoutMs = 10000): Promise<void> {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    try {
+      await docker.ping();
+      console.log('✅ Docker is ready');
+      return;
+    } catch (error) {
+      console.log('⏳ Waiting for Docker...');
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+  }
+
+  throw new Error('Docker did not become available within timeout');
+}
+```
+
 ### 📦 Container Management
 
 #### List All Containers
 
 ```typescript
-// Get all containers (including stopped ones)
-const allContainers = await docker.getContainers();
+// Get all containers (running and stopped)
+const containers = await docker.getContainers();
 
-// Each container includes detailed information
-allContainers.forEach((container) => {
+containers.forEach((container) => {
   console.log(`Container: ${container.Names[0]}`);
   console.log(`  ID: ${container.Id}`);
   console.log(`  Status: ${container.Status}`);
@@ -85,48 +157,15 @@ allContainers.forEach((container) => {
 });
 ```
 
-#### Create and Manage Containers
+#### Get Container by ID
 
 ```typescript
 import { DockerContainer } from '@apiclient.xyz/docker';
 
-// Create a container with detailed configuration
-const container = await DockerContainer.create(docker, {
-  Image: 'nginx:latest',
-  name: 'my-nginx-server',
-  HostConfig: {
-    PortBindings: {
-      '80/tcp': [{ HostPort: '8080' }],
-    },
-    RestartPolicy: {
-      Name: 'unless-stopped',
-    },
-    Memory: 512 * 1024 * 1024, // 512MB memory limit
-  },
-  Env: ['NODE_ENV=production', 'LOG_LEVEL=info'],
-  Labels: {
-    app: 'web-server',
-    environment: 'production',
-  },
-});
-
-console.log(`Container created: ${container.Id}`);
-
-// Container operations (these would need to be implemented)
-// await container.start();
-// await container.stop();
-// await container.remove();
-```
-
-#### Get Container by ID
-
-```typescript
-const container = await DockerContainer.getContainerById(
-  docker,
-  'container-id-here',
-);
+const container = await DockerContainer.getContainerById(docker, 'abc123');
 if (container) {
-  console.log(`Found container: ${container.Names[0]}`);
+  console.log(`Found: ${container.Names[0]}`);
+  console.log(`Running: ${container.State === 'running'}`);
 }
 ```
 
@@ -137,54 +176,86 @@ if (container) {
 ```typescript
 import { DockerImage } from '@apiclient.xyz/docker';
 
-// Pull an image from Docker Hub
+// Pull from Docker Hub
 const image = await DockerImage.createFromRegistry(docker, {
-  imageName: 'node',
-  imageTag: '18-alpine',
-  // Optional: provide registry authentication
-  authToken: 'your-registry-auth-token',
+  creationObject: {
+    imageUrl: 'nginx',
+    imageTag: 'alpine', // Optional, defaults to 'latest'
+  },
 });
 
 console.log(`Image pulled: ${image.RepoTags[0]}`);
 console.log(`Size: ${(image.Size / 1024 / 1024).toFixed(2)} MB`);
-```
 
-#### Import Images from Tar
-
-```typescript
-import * as fs from 'fs';
-
-// Import from a tar stream
-const tarStream = fs.createReadStream('./my-image.tar');
-const importedImage = await DockerImage.createFromTarStream(docker, {
-  tarStream,
-  imageUrl: 'file://./my-image.tar',
-  imageTag: 'my-app:v1.0.0',
+// Pull from private registry
+const privateImage = await DockerImage.createFromRegistry(docker, {
+  creationObject: {
+    imageUrl: 'registry.example.com/my-app',
+    imageTag: 'v2.0.0',
+  },
 });
 ```
 
-#### Export Images to Tar
+#### Import Images from Tar Stream
 
 ```typescript
-// Export an image to a tar stream
-const image = await DockerImage.getImageByName(docker, 'nginx:latest');
+import * as fs from 'fs';
+import { DockerImage } from '@apiclient.xyz/docker';
+
+// Import from a tar file
+const tarStream = fs.createReadStream('./my-image.tar');
+const importedImage = await DockerImage.createFromTarStream(docker, {
+  tarStream,
+  creationObject: {
+    imageUrl: 'my-app',
+    imageTag: 'v1.0.0',
+  },
+});
+
+console.log(`Imported: ${importedImage.RepoTags[0]}`);
+```
+
+#### Export Images to Tar Stream
+
+```typescript
+// Get image by name
+const image = await DockerImage.getImageByName(docker, 'nginx:alpine');
+
+// Export to tar stream
 const exportStream = await image.exportToTarStream();
 
 // Save to file
 const writeStream = fs.createWriteStream('./nginx-export.tar');
 exportStream.pipe(writeStream);
+
+writeStream.on('finish', () => {
+  console.log('Image exported successfully');
+});
 ```
 
 #### Tag Images
 
 ```typescript
 // Tag an existing image
-await DockerImage.tagImageByIdOrName(docker, 'node:18-alpine', {
+await DockerImage.tagImageByIdOrName(docker, 'nginx:alpine', {
   registry: 'myregistry.com',
-  imageName: 'my-node-app',
-  imageTag: 'v2.0.0',
+  imageName: 'web-server',
+  imageTag: 'v1.0.0',
+});
+// Result: myregistry.com/web-server:v1.0.0
+```
+
+#### List All Images
+
+```typescript
+const images = await docker.getImages();
+
+images.forEach((img) => {
+  console.log(`Image: ${img.RepoTags ? img.RepoTags.join(', ') : '<none>'}`);
+  console.log(`  ID: ${img.Id}`);
+  console.log(`  Size: ${(img.Size / 1024 / 1024).toFixed(2)} MB`);
+  console.log(`  Created: ${new Date(img.Created * 1000).toISOString()}`);
 });
-// Result: myregistry.com/my-node-app:v2.0.0
 ```
 
 ### 🌐 Network Management
@@ -214,7 +285,7 @@ const network = await DockerNetwork.createNetwork(docker, {
   },
 });
 
-console.log(`Network created: ${network.Id}`);
+console.log(`Network created: ${network.Name} (${network.Id})`);
 ```
 
 #### List and Inspect Networks
@@ -222,75 +293,96 @@ console.log(`Network created: ${network.Id}`);
 ```typescript
 // Get all networks
 const networks = await docker.getNetworks();
+
 networks.forEach((net) => {
   console.log(`Network: ${net.Name} (${net.Driver})`);
   console.log(`  Scope: ${net.Scope}`);
   console.log(`  Internal: ${net.Internal}`);
 });
 
-// Get specific network
-const appNetwork = await DockerNetwork.getNetworkByName(
-  docker,
-  'my-app-network',
-);
+// Get specific network by name
+const appNetwork = await DockerNetwork.getNetworkByName(docker, 'my-app-network');
 
-// Get containers on network
+// Get containers connected to this network
 const containers = await appNetwork.getContainersOnNetwork();
 console.log(`Containers on network: ${containers.length}`);
 ```
 
+#### Remove a Network
+
+```typescript
+const network = await DockerNetwork.getNetworkByName(docker, 'my-app-network');
+await network.remove();
+console.log('Network removed');
+```
+
 ### 🎭 Service Management (Swarm Mode)
 
+#### Activate Swarm Mode
+
+```typescript
+// Initialize swarm mode first
+await docker.activateSwarm('192.168.1.100'); // Optional: advertisement IP
+console.log('Swarm mode activated');
+```
+
 #### Deploy Services
 
 ```typescript
-import { DockerService } from '@apiclient.xyz/docker';
+import { DockerService, DockerImage, DockerNetwork, DockerSecret } from '@apiclient.xyz/docker';
 
-// Create a replicated service
+// Create prerequisites
+const network = await DockerNetwork.createNetwork(docker, {
+  Name: 'app-network',
+  Driver: 'overlay', // Use overlay for swarm
+});
+
+const image = await DockerImage.createFromRegistry(docker, {
+  creationObject: {
+    imageUrl: 'nginx',
+    imageTag: 'latest',
+  },
+});
+
+const secret = await DockerSecret.createSecret(docker, {
+  name: 'api-key',
+  version: '1.0.0',
+  contentArg: 'super-secret-key',
+  labels: { app: 'my-app' },
+});
+
+// Create a service
 const service = await DockerService.createService(docker, {
   name: 'web-api',
-  image: 'my-api:latest',
-  replicas: 3,
-  ports: [
-    {
-      Protocol: 'tcp',
-      PublishedPort: 80,
-      TargetPort: 3000,
-    },
-  ],
-  networks: ['my-app-network'],
+  image: image,
   labels: {
     app: 'api',
-    version: '2.0.0',
+    version: '1.0.0',
   },
+  networks: [network],
+  networkAlias: 'api',
+  secrets: [secret],
+  ports: ['80:3000'], // host:container
   resources: {
-    limits: {
-      Memory: 256 * 1024 * 1024, // 256MB
-      CPUs: 0.5,
-    },
+    memorySizeMB: 512,
   },
-  secrets: ['api-key', 'db-password'],
-  mounts: [
-    {
-      Target: '/data',
-      Source: 'app-data',
-      Type: 'volume',
-    },
-  ],
 });
 
 console.log(`Service deployed: ${service.ID}`);
 ```
 
-#### Manage Services
+#### List and Manage Services
 
 ```typescript
 // List all services
 const services = await docker.getServices();
+
 services.forEach((service) => {
   console.log(`Service: ${service.Spec.Name}`);
-  console.log(`  Replicas: ${service.Spec.Mode.Replicated.Replicas}`);
   console.log(`  Image: ${service.Spec.TaskTemplate.ContainerSpec.Image}`);
+  if (service.Spec.Mode.Replicated) {
+    console.log(`  Replicas: ${service.Spec.Mode.Replicated.Replicas}`);
+  }
 });
 
 // Get service by name
@@ -299,46 +391,50 @@ const myService = await DockerService.getServiceByName(docker, 'web-api');
 // Check if service needs update
 const needsUpdate = await myService.needsUpdate();
 if (needsUpdate) {
-  console.log('Service configuration has changed, update needed');
+  console.log('⚠️  Service configuration has changed, update needed');
 }
 
 // Remove service
 await myService.remove();
+console.log('Service removed');
 ```
 
 ### 🔐 Secrets Management
 
+Secrets are only available in Docker Swarm mode.
+
 ```typescript
 import { DockerSecret } from '@apiclient.xyz/docker';
 
 // Create a secret
 const secret = await DockerSecret.createSecret(docker, {
-  name: 'api-key',
-  data: Buffer.from('super-secret-key-123').toString('base64'),
+  name: 'database-password',
+  version: '1.0.0',
+  contentArg: 'my-super-secret-password',
   labels: {
     app: 'my-app',
-    type: 'api-key',
+    type: 'credential',
   },
 });
 
 console.log(`Secret created: ${secret.ID}`);
 
-// List secrets
+// List all secrets
 const secrets = await DockerSecret.getSecrets(docker);
-secrets.forEach((secret) => {
-  console.log(`Secret: ${secret.Spec.Name}`);
+secrets.forEach((s) => {
+  console.log(`Secret: ${s.Spec.Name}`);
+  console.log(`  Labels:`, s.Spec.Labels);
 });
 
 // Get secret by name
-const apiKeySecret = await DockerSecret.getSecretByName(docker, 'api-key');
+const dbSecret = await DockerSecret.getSecretByName(docker, 'database-password');
 
-// Update secret
-await apiKeySecret.update({
-  data: Buffer.from('new-secret-key-456').toString('base64'),
-});
+// Update secret content
+await dbSecret.update('new-password-value');
 
 // Remove secret
-await apiKeySecret.remove();
+await dbSecret.remove();
+console.log('Secret removed');
 ```
 
 ### 💾 S3 Image Storage
@@ -346,20 +442,19 @@ await apiKeySecret.remove();
 Store and retrieve Docker images from S3-compatible storage:
 
 ```typescript
-// Configure S3 storage
+// Configure S3 storage for the image store
 await docker.addS3Storage({
   endpoint: 's3.amazonaws.com',
-  accessKeyId: 'your-access-key',
-  secretAccessKey: 'your-secret-key',
-  bucket: 'docker-images',
+  accessKey: 'AKIAIOSFODNN7EXAMPLE',
+  accessSecret: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+  bucketName: 'my-docker-images',
 });
 
 // Store an image to S3
-const imageStore = docker.imageStore;
-await imageStore.storeImage('my-app:v1.0.0');
+const imageStream = fs.createReadStream('./my-app.tar');
+await docker.imageStore.storeImage('my-app-v1', imageStream);
 
-// Retrieve an image from S3
-const retrievedImage = await imageStore.getImage('my-app:v1.0.0');
+console.log('Image stored to S3');
 ```
 
 ### 📊 Event Monitoring
@@ -368,137 +463,270 @@ Monitor Docker events in real-time using RxJS observables:
 
 ```typescript
 // Subscribe to Docker events
-const eventStream = docker.getEventObservable();
+const eventObservable = await docker.getEventObservable();
 
-const subscription = eventStream.subscribe({
+const subscription = eventObservable.subscribe({
   next: (event) => {
-    console.log(`Event: ${event.Type} - ${event.Action}`);
-    console.log(`Actor: ${event.Actor.ID}`);
-    console.log(`Time: ${new Date(event.time * 1000).toISOString()}`);
+    console.log(`📡 Event: ${event.Type} - ${event.Action}`);
+    console.log(`   Actor: ${event.Actor.ID}`);
+    console.log(`   Time: ${new Date(event.time * 1000).toISOString()}`);
+
+    if (event.Type === 'container') {
+      console.log(`   Container: ${event.Actor.Attributes.name}`);
+    }
   },
-  error: (err) => console.error('Event stream error:', err),
+  error: (err) => console.error('❌ Event stream error:', err),
   complete: () => console.log('Event stream completed'),
 });
 
 // Unsubscribe when done
-subscription.unsubscribe();
+// subscription.unsubscribe();
 ```
 
 ### 🔧 Registry Authentication
 
-Authenticate with Docker registries for private images:
+Authenticate with Docker registries to pull private images:
 
 ```typescript
-// Authenticate with Docker Hub
+// Authenticate with a registry
 await docker.auth({
   username: 'your-username',
   password: 'your-password',
-  serveraddress: 'https://index.docker.io/v1/',
+  serveraddress: 'https://index.docker.io/v1/', // Docker Hub
 });
 
-// Or use existing Docker config
-const authToken = await docker.getAuthTokenFromDockerConfig('myregistry.com');
+console.log('✅ Authenticated with registry');
 
-// Use auth token when pulling images
+// Or read credentials from Docker config file
+const authToken = await docker.getAuthTokenFromDockerConfig('registry.example.com');
+
+// Now you can pull private images
 const privateImage = await DockerImage.createFromRegistry(docker, {
-  imageName: 'myregistry.com/private/image',
-  imageTag: 'latest',
-  authToken,
-});
-```
-
-### 🔄 Swarm Mode
-
-Initialize and manage Docker Swarm:
-
-```typescript
-// Initialize swarm mode
-await docker.activateSwarm({
-  ListenAddr: '0.0.0.0:2377',
-  AdvertiseAddr: '192.168.1.100:2377',
-  ForceNewCluster: false,
-});
-
-// Now you can create services, secrets, and use swarm features
-const service = await DockerService.createService(docker, {
-  name: 'my-swarm-service',
-  image: 'nginx:latest',
-  replicas: 5,
-  // ... more service config
+  creationObject: {
+    imageUrl: 'registry.example.com/private/app',
+    imageTag: 'latest',
+  },
 });
 ```
 
 ## 🏗️ Advanced Examples
 
-### Complete Application Stack
+### Complete Application Stack with Swarm
+
+Deploy a complete multi-service application stack:
 
 ```typescript
-async function deployStack() {
-  const docker = new DockerHost();
+import { DockerHost, DockerNetwork, DockerSecret, DockerService, DockerImage } from '@apiclient.xyz/docker';
 
-  // Create network
+async function deployStack() {
+  const docker = new DockerHost({});
+  await docker.start();
+
+  // Initialize swarm
+  await docker.activateSwarm();
+  console.log('✅ Swarm initialized');
+
+  // Create overlay network for service communication
   const network = await DockerNetwork.createNetwork(docker, {
     Name: 'app-network',
-    Driver: 'overlay', // for swarm mode
+    Driver: 'overlay',
+    Attachable: true,
   });
+  console.log('✅ Network created');
 
   // Create secrets
   const dbPassword = await DockerSecret.createSecret(docker, {
     name: 'db-password',
-    data: Buffer.from('strong-password').toString('base64'),
+    version: '1.0.0',
+    contentArg: 'strong-database-password',
+    labels: { app: 'stack' },
   });
+  console.log('✅ Secrets created');
+
+  // Pull images
+  const postgresImage = await DockerImage.createFromRegistry(docker, {
+    creationObject: {
+      imageUrl: 'postgres',
+      imageTag: '14-alpine',
+    },
+  });
+
+  const appImage = await DockerImage.createFromRegistry(docker, {
+    creationObject: {
+      imageUrl: 'my-app',
+      imageTag: 'latest',
+    },
+  });
+  console.log('✅ Images pulled');
 
   // Deploy database service
   const dbService = await DockerService.createService(docker, {
-    name: 'postgres',
-    image: 'postgres:14',
-    networks: ['app-network'],
-    secrets: ['db-password'],
-    env: ['POSTGRES_PASSWORD_FILE=/run/secrets/db-password'],
+    name: 'postgres-db',
+    image: postgresImage,
+    labels: { tier: 'database' },
+    networks: [network],
+    networkAlias: 'postgres',
+    secrets: [dbPassword],
+    ports: [],
+    resources: {
+      memorySizeMB: 1024,
+    },
   });
+  console.log('✅ Database service deployed');
 
   // Deploy application service
   const appService = await DockerService.createService(docker, {
     name: 'web-app',
-    image: 'my-app:latest',
-    replicas: 3,
-    networks: ['app-network'],
-    ports: [{ Protocol: 'tcp', PublishedPort: 80, TargetPort: 3000 }],
+    image: appImage,
+    labels: { tier: 'application' },
+    networks: [network],
+    networkAlias: 'app',
+    secrets: [dbPassword],
+    ports: ['80:3000'],
+    resources: {
+      memorySizeMB: 512,
+    },
   });
+  console.log('✅ Application service deployed');
 
-  console.log('Stack deployed successfully!');
+  console.log('🚀 Stack deployment complete!');
+}
+
+deployStack().catch(console.error);
+```
+
+### Image Pipeline: Pull, Tag, Export
+
+```typescript
+async function imagePipeline() {
+  const docker = new DockerHost({});
+  await docker.start();
+
+  // Pull latest image
+  const image = await DockerImage.createFromRegistry(docker, {
+    creationObject: {
+      imageUrl: 'node',
+      imageTag: '18-alpine',
+    },
+  });
+  console.log('✅ Image pulled');
+
+  // Tag for private registry
+  await DockerImage.tagImageByIdOrName(docker, 'node:18-alpine', {
+    registry: 'registry.company.com',
+    imageName: 'base/node',
+    imageTag: 'v18-alpine',
+  });
+  console.log('✅ Image tagged');
+
+  // Export to tar
+  const exportStream = await image.exportToTarStream();
+  const writeStream = fs.createWriteStream('./node-18-alpine.tar');
+
+  exportStream.pipe(writeStream);
+
+  await new Promise((resolve, reject) => {
+    writeStream.on('finish', resolve);
+    writeStream.on('error', reject);
+  });
+  console.log('✅ Image exported to tar');
+
+  await docker.stop();
 }
 ```
 
 ## 🔍 TypeScript Support
 
-This package provides comprehensive TypeScript definitions for all Docker API entities:
+Full TypeScript definitions for all Docker API entities:
 
 ```typescript
 import type {
-  IContainerCreationDescriptor,
-  IServiceCreationDescriptor,
-  INetworkCreationDescriptor,
+  IDockerHostConstructorOptions,
   IImageCreationDescriptor,
+  IServiceCreationDescriptor,
   ISecretCreationDescriptor,
+  TLabels,
 } from '@apiclient.xyz/docker';
 
-// Full IntelliSense support for all configuration options
-const containerConfig: IContainerCreationDescriptor = {
-  Image: 'node:18',
-  // Your IDE will provide full autocomplete here
+// Full IntelliSense support
+const options: IDockerHostConstructorOptions = {
+  socketPath: '/var/run/docker.sock',
+  imageStoreDir: '/tmp/docker-images',
+};
+
+const imageConfig: IImageCreationDescriptor = {
+  imageUrl: 'nginx',
+  imageTag: 'alpine',
+};
+
+const labels: TLabels = {
+  app: 'my-app',
+  environment: 'production',
 };
 ```
 
-## 🤝 Contributing
+## 🎯 Real-World Use Cases
 
-We welcome contributions! Please feel free to submit issues and pull requests.
+### CI/CD Pipeline Integration
+
+```typescript
+// In your CI/CD pipeline
+const docker = new DockerHost({
+  socketPath: process.env.DOCKER_HOST || '/var/run/docker.sock',
+});
+
+await docker.start();
+
+// Build and push process
+const image = await DockerImage.createFromTarStream(docker, {
+  tarStream: buildArtifactStream,
+  creationObject: {
+    imageUrl: 'my-app',
+    imageTag: process.env.CI_COMMIT_SHA,
+  },
+});
+
+await DockerImage.tagImageByIdOrName(docker, `my-app:${process.env.CI_COMMIT_SHA}`, {
+  registry: 'registry.company.com',
+  imageName: 'production/my-app',
+  imageTag: 'latest',
+});
+
+// Push to registry (authentication required)
+// Note: Pushing requires proper registry authentication
+```
+
+### Dynamic Service Scaling
+
+```typescript
+// Monitor and scale services based on load
+const services = await docker.getServices();
+const webService = services.find(s => s.Spec.Name === 'web-app');
+
+if (webService && webService.Spec.Mode.Replicated) {
+  const currentReplicas = webService.Spec.Mode.Replicated.Replicas;
+  console.log(`Current replicas: ${currentReplicas}`);
+
+  // Scale based on your metrics
+  // (Scaling API would need to be implemented)
+}
+```
 
 ## 📖 API Documentation
 
-For complete API documentation, visit [https://apiclient.xyz/docker](https://apiclient.xyz/docker)
+- **Package Repository**: [https://code.foss.global/apiclient.xyz/docker](https://code.foss.global/apiclient.xyz/docker)
+- **Docker Engine API Reference**: [https://docs.docker.com/engine/api/latest/](https://docs.docker.com/engine/api/latest/)
+- **Issues & Bug Reports**: [https://code.foss.global/apiclient.xyz/docker/issues](https://code.foss.global/apiclient.xyz/docker/issues)
 
-For Docker Remote API reference, see [Docker Engine API Documentation](https://docs.docker.com/engine/api/latest/)
+## 🔑 Key Concepts
+
+- **DockerHost**: Main entry point for Docker API communication
+- **Health Checks**: Use `ping()` method to verify Docker daemon accessibility
+- **Socket Path Priority**: Constructor option → `DOCKER_HOST` env → CI mode → default socket
+- **Swarm Mode Required**: Services and secrets require Docker Swarm to be activated
+- **Type Safety**: Full TypeScript support with comprehensive interfaces
+- **Streaming Support**: Real-time event monitoring and tar stream operations
+- **S3 Integration**: Built-in image storage/retrieval from S3-compatible storage
 
 ## License and Legal Information
 
@@ -512,7 +740,7 @@ This project is owned and maintained by Task Venture Capital GmbH. The names and
 
 ### Company Information
 
-Task Venture Capital GmbH  
+Task Venture Capital GmbH
 Registered at District court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@apiclient.xyz/docker',
-  version: '1.3.5',
+  version: '2.1.0',
   description: 'Provides easy communication with Docker remote API from Node.js, with TypeScript support.'
 }

ts/classes.host.ts

@@ -4,7 +4,6 @@ import { DockerContainer } from './classes.container.js';
 import { DockerNetwork } from './classes.network.js';
 import { DockerService } from './classes.service.js';
 import { logger } from './logger.js';
-import path from 'path';
 import { DockerImageStore } from './classes.imagestore.js';
 import { DockerImage } from './classes.image.js';
 
@@ -15,7 +14,7 @@ export interface IAuthData {
 }
 
 export interface IDockerHostConstructorOptions {
-  dockerSockPath?: string;
+  socketPath?: string;
   imageStoreDir?: string;
 }
 
@@ -45,8 +44,8 @@ export class DockerHost {
       ...optionsArg,
     };
     let pathToUse: string;
-    if (optionsArg.dockerSockPath) {
-      pathToUse = optionsArg.dockerSockPath;
+    if (optionsArg.socketPath) {
+      pathToUse = optionsArg.socketPath;
     } else if (process.env.DOCKER_HOST) {
       pathToUse = process.env.DOCKER_HOST;
     } else if (process.env.CI) {
@@ -75,6 +74,18 @@ export class DockerHost {
     await this.imageStore.stop();
   }
 
+  /**
+   * Ping the Docker daemon to check if it's running and accessible
+   * @returns Promise that resolves if Docker is available, rejects otherwise
+   * @throws Error if Docker ping fails
+   */
+  public async ping(): Promise<void> {
+    const response = await this.request('GET', '/_ping');
+    if (response.statusCode !== 200) {
+      throw new Error(`Docker ping failed with status ${response.statusCode}`);
+    }
+  }
+
   /**
    * authenticate against a registry
    * @param userArg
@@ -183,8 +194,12 @@ export class DockerHost {
    */
   public async getEventObservable(): Promise<plugins.rxjs.Observable<any>> {
     const response = await this.requestStreaming('GET', '/events');
+
+    // requestStreaming now returns Node.js stream, not web stream
+    const nodeStream = response as plugins.smartstream.stream.Readable;
+
     return plugins.rxjs.Observable.create((observer) => {
-      response.on('data', (data) => {
+      nodeStream.on('data', (data) => {
         const eventString = data.toString();
         try {
           const eventObject = JSON.parse(eventString);
@@ -194,7 +209,7 @@ export class DockerHost {
         }
       });
       return () => {
-        response.emit('end');
+        nodeStream.emit('end');
       };
     });
   }
@@ -348,7 +363,7 @@ export class DockerHost {
     }
 
     // Execute the request based on method
-    let response;
+    let response: plugins.smartrequest.ICoreResponse;
     switch (methodArg.toUpperCase()) {
       case 'GET':
         response = await smartRequest.get();
@@ -368,10 +383,10 @@ export class DockerHost {
 
     console.log(response.status);
 
-    // For streaming responses, get the Node.js stream
-    const nodeStream = response.streamNode();
+    // For streaming responses, get the web stream
+    const webStream = response.stream();
 
-    if (!nodeStream) {
+    if (!webStream) {
       // If no stream is available, consume the body as text
       const body = await response.text();
       console.log(body);
@@ -384,7 +399,10 @@ export class DockerHost {
       };
     }
 
-    // For streaming responses, return the stream with added properties
+    // Convert web ReadableStream to Node.js stream for backward compatibility
+    const nodeStream = plugins.smartstream.nodewebhelpers.convertWebReadableToNodeReadable(webStream);
+
+    // Add properties for compatibility
     (nodeStream as any).statusCode = response.status;
     (nodeStream as any).body = ''; // For compatibility
 

ts/classes.image.ts

@@ -105,6 +105,9 @@ export class DockerImage {
       optionsArg.tarStream,
     );
 
+    // requestStreaming now returns Node.js stream
+    const nodeStream = response as plugins.smartstream.stream.Readable;
+
     /**
      * Docker typically returns lines like:
      * {"stream":"Loaded image: myrepo/myimage:latest"}
@@ -112,16 +115,16 @@ export class DockerImage {
      * So we will collect those lines and parse out the final image name.
      */
     let rawOutput = '';
-    response.on('data', (chunk) => {
+    nodeStream.on('data', (chunk) => {
       rawOutput += chunk.toString();
     });
 
     // Wrap the end event in a Promise for easier async/await usage
     await new Promise<void>((resolve, reject) => {
-      response.on('end', () => {
+      nodeStream.on('end', () => {
         resolve();
       });
-      response.on('error', (err) => {
+      nodeStream.on('error', (err) => {
         reject(err);
       });
     });
@@ -260,10 +263,8 @@ export class DockerImage {
       `/images/${encodeURIComponent(this.RepoTags[0])}/get`,
     );
 
-    // Check if response is a Node.js stream
-    if (!response || typeof response.on !== 'function') {
-      throw new Error('Failed to get streaming response for image export');
-    }
+    // requestStreaming now returns Node.js stream
+    const nodeStream = response as plugins.smartstream.stream.Readable;
 
     let counter = 0;
     const webduplexStream = new plugins.smartstream.SmartDuplex({
@@ -274,20 +275,20 @@ export class DockerImage {
       },
     });
 
-    response.on('data', (chunk) => {
+    nodeStream.on('data', (chunk) => {
       if (!webduplexStream.write(chunk)) {
-        response.pause();
+        nodeStream.pause();
         webduplexStream.once('drain', () => {
-          response.resume();
+          nodeStream.resume();
         });
       }
     });
 
-    response.on('end', () => {
+    nodeStream.on('end', () => {
       webduplexStream.end();
     });
 
-    response.on('error', (error) => {
+    nodeStream.on('error', (error) => {
       logger.log('error', `Error during image export: ${error.message}`);
       webduplexStream.destroy(error);
     });

ts/plugins.ts

@@ -1,5 +1,5 @@
 // node native path
-import * as path from 'path';
+import * as path from 'node:path';
 
 export { path };