@git.zone/tsdocker 1.3.0 → 1.4.1

package/readme.md

@@ -1,6 +1,6 @@
 # @git.zone/tsdocker
 
-> 🐳 Cross-platform npm module development with Docker — test your packages in clean, reproducible Linux environments every time.
+> 🐳 The ultimate Docker development toolkit for TypeScript projects — build, test, and ship containerized applications with ease.
 
 ## Issue Reporting and Security
 
@@ -8,313 +8,454 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## What is tsdocker?
 
-**tsdocker** provides containerized testing environments for npm packages, ensuring your code works consistently across different systems. It's perfect for:
+**tsdocker** is a comprehensive Docker development and building tool that handles everything from testing npm packages in clean environments to building and pushing multi-architecture Docker images across multiple registries.
 
-- 🧪 **Testing in clean environments** — Every test run starts fresh, just like CI
-- 🔄 **Reproducing CI behavior locally** — No more "works on my machine" surprises
-- 🐧 **Cross-platform development** — Develop on macOS/Windows, test on Linux
-- 🚀 **Quick validation** — Spin up isolated containers for testing without polluting your system
+### 🎯 Key Capabilities
 
-## Features
+- 🧪 **Containerized Testing** — Run your tests in pristine Docker environments
+- 🏗️ **Smart Docker Builds** — Automatically discover, sort, and build Dockerfiles by dependency
+- 🚀 **Multi-Registry Push** — Ship to Docker Hub, GitLab, GitHub Container Registry, and more
+- 🔧 **Multi-Architecture** — Build for `amd64` and `arm64` with Docker Buildx
+- ⚡ **Zero Config Start** — Works out of the box, scales with your needs
 
-✨ **Works Everywhere Docker Does**
+## Installation
 
-- Docker Toolbox
-- Native Docker Desktop
-- Docker-in-Docker (DinD)
-- Mounted docker.sock scenarios
+```bash
+# Global installation (recommended for CLI usage)
+npm install -g @git.zone/tsdocker
 
-🔧 **Flexible Configuration**
+# Or project-local installation
+pnpm install --save-dev @git.zone/tsdocker
+```
 
-- Custom base images
-- Configurable test commands
-- Environment variable injection via qenv
-- Optional docker.sock mounting for nested container tests
+## Quick Start
 
-📦 **TypeScript-First**
+### 🧪 Run Tests in Docker
 
-- Full TypeScript support with excellent IntelliSense
-- Type-safe configuration
-- Modern ESM with async/await patterns throughout
+The simplest use case — run your tests in a clean container:
 
-## Installation
+```bash
+tsdocker
+```
+
+This pulls your configured base image, mounts your project, and executes your test command in isolation.
+
+### 🏗️ Build Docker Images
+
+Got `Dockerfile` files? Build them all with automatic dependency ordering:
 
 ```bash
-npm install -g @git.zone/tsdocker
-# or for project-local installation
-pnpm install --save-dev @git.zone/tsdocker
+tsdocker build
 ```
 
-## Quick Start
+tsdocker will:
+1. 🔍 Discover all `Dockerfile*` files in your project
+2. 📊 Analyze `FROM` dependencies between them
+3. 🔄 Sort them topologically
+4. 🏗️ Build each image in the correct order
+
+### 📤 Push to Registries
 
-### 1. Configure Your Project
+Ship your images to one or all configured registries:
 
-Create an `npmextra.json` file in your project root:
+```bash
+# Push to all configured registries
+tsdocker push
+
+# Push to a specific registry
+tsdocker push registry.gitlab.com
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `tsdocker` | Run tests in a fresh Docker container |
+| `tsdocker build` | Build all Dockerfiles with dependency ordering |
+| `tsdocker push [registry]` | Push images to configured registries |
+| `tsdocker pull <registry>` | Pull images from a specific registry |
+| `tsdocker test` | Run container test scripts (test_*.sh) |
+| `tsdocker login` | Authenticate with configured registries |
+| `tsdocker list` | Display discovered Dockerfiles and their dependencies |
+| `tsdocker clean --all` | ⚠️ Aggressively clean Docker environment |
+| `tsdocker vscode` | Launch containerized VS Code in browser |
+
+## Configuration
+
+Configure tsdocker in your `package.json` or `npmextra.json`:
 
 ```json
 {
   "@git.zone/tsdocker": {
     "baseImage": "node:20",
     "command": "npm test",
-    "dockerSock": false
+    "dockerSock": false,
+    "registries": ["registry.gitlab.com", "docker.io"],
+    "registryRepoMap": {
+      "registry.gitlab.com": "myorg/myproject"
+    },
+    "buildArgEnvMap": {
+      "NODE_VERSION": "NODE_VERSION"
+    },
+    "platforms": ["linux/amd64", "linux/arm64"],
+    "push": false,
+    "testDir": "./test"
   }
 }
 ```
 
-### 2. Run Your Tests
+### Configuration Options
 
-```bash
-tsdocker
-```
+#### Testing Options (Legacy)
 
-That's it! tsdocker will:
+| Option | Type | Description |
+|--------|------|-------------|
+| `baseImage` | `string` | Docker image for test environment (default: `hosttoday/ht-docker-node:npmdocker`) |
+| `command` | `string` | Command to run inside container (default: `npmci npm test`) |
+| `dockerSock` | `boolean` | Mount Docker socket for DinD scenarios (default: `false`) |
 
-1. ✅ Verify Docker is available
-2. 🏗️ Build a test container with your specified base image
-3. 📂 Mount your project directory
-4. 🚀 Execute your test command
-5. 🧹 Clean up automatically
+#### Build & Push Options
 
-## Configuration Options
+| Option | Type | Description |
+|--------|------|-------------|
+| `registries` | `string[]` | Registry URLs to push to |
+| `registryRepoMap` | `object` | Map registries to different repository paths |
+| `buildArgEnvMap` | `object` | Map Docker build ARGs to environment variables |
+| `platforms` | `string[]` | Target architectures (default: `["linux/amd64"]`) |
+| `push` | `boolean` | Auto-push after build (default: `false`) |
+| `testDir` | `string` | Directory containing test scripts |
 
-| Option       | Type      | Description                                                            |
-| ------------ | --------- | ---------------------------------------------------------------------- |
-| `baseImage`  | `string`  | Docker image to use as the test environment base                       |
-| `command`    | `string`  | CLI command to execute inside the container                            |
-| `dockerSock` | `boolean` | Whether to mount `/var/run/docker.sock` for Docker-in-Docker scenarios |
+## Registry Authentication
 
 ### Environment Variables
 
-If you have a `qenv.yml` file in your project, tsdocker automatically loads and injects those environment variables into your test container.
+```bash
+# Pipe-delimited format (supports DOCKER_REGISTRY_1 through DOCKER_REGISTRY_10)
+export DOCKER_REGISTRY_1="registry.gitlab.com|username|password"
+export DOCKER_REGISTRY_2="docker.io|username|password"
+
+# Individual registry format
+export DOCKER_REGISTRY_URL="registry.gitlab.com"
+export DOCKER_REGISTRY_USER="username"
+export DOCKER_REGISTRY_PASSWORD="password"
+```
 
-Example `qenv.yml`:
+### Login Command
 
-```yaml
-demoKey: demoValue
-API_KEY: your-key-here
+```bash
+tsdocker login
 ```
 
-## CLI Commands
+Authenticates with all configured registries.
+
+## Advanced Usage
 
-### Standard Test Run
+### 🔀 Multi-Architecture Builds
 
-```bash
-tsdocker
+Build for multiple platforms using Docker Buildx:
+
+```json
+{
+  "@git.zone/tsdocker": {
+    "platforms": ["linux/amd64", "linux/arm64"]
+  }
+}
 ```
 
-Runs your configured test command in a fresh Docker container.
+tsdocker automatically sets up a Buildx builder when multiple platforms are specified.
 
-### Clean Docker Environment
+### 📦 Dockerfile Naming Conventions
 
-```bash
-tsdocker clean --all
-```
+tsdocker discovers files matching `Dockerfile*`:
 
-⚠️ **WARNING**: This aggressively cleans your Docker environment by:
+| File Name | Version Tag |
+|-----------|-------------|
+| `Dockerfile` | `latest` |
+| `Dockerfile_v1.0.0` | `v1.0.0` |
+| `Dockerfile_alpine` | `alpine` |
+| `Dockerfile_##version##` | Uses `package.json` version |
 
-- Killing all running containers
-- Removing all stopped containers
-- Removing dangling images
-- Removing all images
-- Removing dangling volumes
+### 🔗 Dependency-Aware Builds
 
-Use with caution!
+If you have multiple Dockerfiles that depend on each other:
 
-### VSCode in Docker
+```dockerfile
+# Dockerfile_base
+FROM node:20-alpine
+RUN npm install -g typescript
 
-```bash
-tsdocker vscode
+# Dockerfile_app
+FROM myproject:base
+COPY . .
+RUN npm run build
 ```
 
-Launches a containerized VS Code instance accessible via browser at `testing-vscode.git.zone:8443`.
+tsdocker automatically detects that `Dockerfile_app` depends on `Dockerfile_base` and builds them in the correct order.
+
+### 🧪 Container Test Scripts
 
-### Speed Test
+Create test scripts in your test directory:
 
 ```bash
-tsdocker speedtest
+# test/test_latest.sh
+#!/bin/bash
+node --version
+npm --version
+echo "Container tests passed!"
 ```
 
-Runs a network speed test inside a Docker container.
+Run with:
 
-## Advanced Usage
+```bash
+tsdocker test
+```
 
-### Docker-in-Docker Testing
+### 🔧 Build Args from Environment
 
-If you need to run Docker commands inside your test container (e.g., testing Docker-related tools):
+Pass environment variables as Docker build arguments:
 
 ```json
 {
   "@git.zone/tsdocker": {
-    "baseImage": "docker:latest",
-    "command": "docker run hello-world",
-    "dockerSock": true
+    "buildArgEnvMap": {
+      "NPM_TOKEN": "NPM_TOKEN",
+      "NODE_VERSION": "NODE_VERSION"
+    }
   }
 }
 ```
 
-Setting `"dockerSock": true` mounts the host's Docker socket into the container.
+```dockerfile
+ARG NPM_TOKEN
+ARG NODE_VERSION=20
+FROM node:${NODE_VERSION}
+RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+```
 
-### Custom Base Images
+### 🐳 Docker-in-Docker Testing
 
-You can use any Docker image as your base:
+Test Docker-related tools by mounting the Docker socket:
 
 ```json
 {
   "@git.zone/tsdocker": {
-    "baseImage": "node:20-alpine",
-    "command": "npm test"
+    "baseImage": "docker:latest",
+    "command": "docker version && docker ps",
+    "dockerSock": true
   }
 }
 ```
 
-Popular choices:
+### 📋 Listing Dockerfiles
 
-- `node:20` — Official Node.js images
-- `node:20-alpine` — Lightweight Alpine-based images
-- `node:lts` — Long-term support Node.js version
+Inspect your project's Dockerfiles and their relationships:
 
-### CI Integration
+```bash
+tsdocker list
+```
 
-tsdocker automatically detects CI environments (via `CI=true` env var) and adjusts behavior:
+Output:
+```
+Discovered Dockerfiles:
+========================
+
+1. Dockerfile_base
+   Tag: myproject:base
+   Base Image: node:20-alpine
+   Version: base
+
+2. Dockerfile_app
+   Tag: myproject:app
+   Base Image: myproject:base
+   Version: app
+   Depends on: myproject:base
+```
 
-- Copies project files into container in CI (instead of mounting)
-- Optimizes for CI execution patterns
+### 🗺️ Registry Repo Mapping
 
-## Why tsdocker?
+Use different repository names for different registries:
+
+```json
+{
+  "@git.zone/tsdocker": {
+    "registries": ["registry.gitlab.com", "docker.io"],
+    "registryRepoMap": {
+      "registry.gitlab.com": "mygroup/myproject",
+      "docker.io": "myuser/myproject"
+    }
+  }
+}
+```
 
-### The Problem
+## Environment Variables
 
-Local development environments drift over time. You might have:
+### qenv Integration
 
-- Stale global packages
-- Modified system configurations
-- Cached dependencies
-- Different Node.js versions
+tsdocker automatically loads environment variables from `qenv.yml`:
 
-Your tests pass locally but fail in CI — or vice versa.
+```yaml
+# qenv.yml
+API_KEY: your-api-key
+DATABASE_URL: postgres://localhost/test
+```
 
-### The Solution
+These are injected into your test container automatically.
 
-tsdocker ensures every test run happens in a **clean, reproducible environment**, just like your CI pipeline. This means:
+## Examples
 
-✅ Consistent behavior between local and CI
-✅ No dependency pollution between test runs
-✅ Easy cross-platform testing
-✅ Reproducible bug investigations
+### Basic Test Configuration
 
-## TypeScript Usage
+```json
+{
+  "@git.zone/tsdocker": {
+    "baseImage": "node:20",
+    "command": "npm test"
+  }
+}
+```
 
-tsdocker is built with TypeScript and provides full type definitions:
+### Full Production Setup
 
-```typescript
-import type { IConfig } from '@git.zone/tsdocker/dist_ts/tsdocker.config.js';
+```json
+{
+  "@git.zone/tsdocker": {
+    "baseImage": "node:20-alpine",
+    "command": "pnpm test",
+    "registries": ["registry.gitlab.com", "ghcr.io", "docker.io"],
+    "registryRepoMap": {
+      "registry.gitlab.com": "myorg/myapp",
+      "ghcr.io": "myorg/myapp",
+      "docker.io": "myuser/myapp"
+    },
+    "buildArgEnvMap": {
+      "NPM_TOKEN": "NPM_TOKEN"
+    },
+    "platforms": ["linux/amd64", "linux/arm64"],
+    "testDir": "./docker-tests"
+  }
+}
+```
 
-const config: IConfig = {
-  baseImage: 'node:20',
-  command: 'npm test',
-  dockerSock: false,
-  keyValueObject: {
-    NODE_ENV: 'test',
-  },
-};
+### CI/CD Integration
+
+```yaml
+# .gitlab-ci.yml
+build:
+  stage: build
+  script:
+    - npm install -g @git.zone/tsdocker
+    - tsdocker build
+    - tsdocker push
+
+# GitHub Actions
+- name: Build and Push
+  run: |
+    npm install -g @git.zone/tsdocker
+    tsdocker login
+    tsdocker build
+    tsdocker push
+  env:
+    DOCKER_REGISTRY_1: "ghcr.io|${{ github.actor }}|${{ secrets.GITHUB_TOKEN }}"
 ```
 
 ## Requirements
 
-- **Docker**: Docker must be installed and accessible via CLI
-- **Node.js**: Version 18 or higher (ESM support required)
+- **Docker** — Docker Engine or Docker Desktop must be installed
+- **Node.js** — Version 18 or higher (ESM support required)
+- **Docker Buildx** — Required for multi-architecture builds (included in Docker Desktop)
 
-## How It Works
+## Why tsdocker?
 
-Under the hood, tsdocker:
+### 🎯 The Problem
 
-1. 📋 Reads your `npmextra.json` configuration
-2. 🔍 Optionally loads environment variables from `qenv.yml`
-3. 🐳 Generates a temporary Dockerfile
-4. 🏗️ Builds a Docker image with your base image
-5. 📦 Mounts your project directory (unless in CI)
-6. ▶️ Runs your test command inside the container
-7. 📊 Captures the exit code
-8. 🧹 Cleans up containers and images
-9. ✅ Exits with the same code as your tests
+Managing Docker workflows manually is tedious:
+- Remembering build order for dependent images
+- Pushing to multiple registries with different credentials
+- Setting up Buildx for multi-arch builds
+- Ensuring consistent test environments
 
-## Troubleshooting
+### ✨ The Solution
 
-### "docker not found on this machine"
+tsdocker automates the entire workflow:
+- **One command** to build all images in dependency order
+- **One command** to push to all registries
+- **Automatic** Buildx setup for multi-platform builds
+- **Consistent** containerized test environments
 
-Make sure Docker is installed and the `docker` command is in your PATH:
+## TypeScript API
 
-```bash
-docker --version
-```
+tsdocker exposes its types for programmatic use:
+
+```typescript
+import type { ITsDockerConfig } from '@git.zone/tsdocker/dist_ts/interfaces/index.js';
+import { TsDockerManager } from '@git.zone/tsdocker/dist_ts/classes.tsdockermanager.js';
 
-### Tests fail in container but work locally
+const config: ITsDockerConfig = {
+  baseImage: 'node:20',
+  command: 'npm test',
+  dockerSock: false,
+  keyValueObject: {},
+  registries: ['docker.io'],
+  platforms: ['linux/amd64'],
+};
 
-This often indicates environment-specific issues. Check:
+const manager = new TsDockerManager(config);
+await manager.prepare();
+await manager.build();
+await manager.push();
+```
 
-- Are all dependencies in `package.json`? (not relying on global packages)
-- Does your code have hardcoded paths?
-- Are environment variables set correctly?
+## Troubleshooting
 
-### Permission errors with docker.sock
+### "docker not found"
 
-If using `dockerSock: true`, ensure your user has permissions to access `/var/run/docker.sock`:
+Ensure Docker is installed and in your PATH:
 
 ```bash
-sudo usermod -aG docker $USER
-# Then log out and back in
+docker --version
 ```
 
-## Examples
+### Multi-arch build fails
 
-### Basic npm test
+Make sure Docker Buildx is available:
 
-```json
-{
-  "@git.zone/tsdocker": {
-    "baseImage": "node:20",
-    "command": "npm test"
-  }
-}
+```bash
+docker buildx version
+docker buildx create --use
 ```
 
-### Running pnpm tests
+### Registry authentication fails
 
-```json
-{
-  "@git.zone/tsdocker": {
-    "baseImage": "node:20",
-    "command": "corepack enable && pnpm install && pnpm test"
-  }
-}
+Check your environment variables are set correctly:
+
+```bash
+echo $DOCKER_REGISTRY_1
+tsdocker login
 ```
 
-### Testing Docker-based tools
+### Circular dependency detected
 
-```json
-{
-  "@git.zone/tsdocker": {
-    "baseImage": "docker:latest",
-    "command": "sh -c 'docker version && docker ps'",
-    "dockerSock": true
-  }
-}
-```
+Review your Dockerfiles' `FROM` statements — you have images depending on each other in a loop.
 
 ## Performance Tips
 
-🚀 **Use specific base images**: `node:20-alpine` is much faster to pull than `node:latest`
-🚀 **Layer caching**: Docker caches image layers — your base image only downloads once
-🚀 **Prune regularly**: Run `docker system prune` periodically to reclaim disk space
+🚀 **Use specific tags**: `node:20-alpine` is smaller and faster than `node:latest`
+
+🚀 **Leverage caching**: Docker layers are cached — your builds get faster over time
+
+🚀 **Prune regularly**: `docker system prune` reclaims disk space
+
+🚀 **Use .dockerignore**: Exclude `node_modules`, `.git`, etc. from build context
 
-## Migration from legacy npmdocker
+## Migration from Legacy
 
-This package was previously published under the `npmdocker` name. It is now available as `@git.zone/tsdocker` with modernized ESM support and updated dependencies.
+Previously published as `npmdocker`, now `@git.zone/tsdocker`:
 
-Key changes:
-- Configuration key changed from `npmdocker` to `@git.zone/tsdocker` in `npmextra.json`
-- CLI command is now `tsdocker` instead of `npmdocker`
-- Full ESM support with `.js` extensions in imports
+| Old | New |
+|-----|-----|
+| `npmdocker` command | `tsdocker` command |
+| `"npmdocker"` config key | `"@git.zone/tsdocker"` config key |
+| CommonJS | ESM with `.js` imports |
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsdocker',
-  version: '1.3.0',
+  version: '1.4.1',
   description: 'develop npm modules cross platform with docker'
 }