v1.6.0

changelog.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 2026-02-06 - 1.6.0 - feat(docker)
+add support for no-cache builds and tag built images for local dependency resolution
+
+- Introduce IBuildCommandOptions.noCache to control --no-cache behavior
+- Propagate noCache from CLI (via cache flag) through TsDockerManager to Dockerfile.build
+- Append --no-cache to docker build/buildx commands when noCache is true
+- After building an image, tag it with full base image references used by dependent Dockerfiles so their FROM lines resolve to the locally-built image
+- Log tagging actions and execute docker tag via smartshellInstance
+
+## 2026-02-06 - 1.5.0 - feat(build)
+add support for selective builds, platform override and build timeout
+
+- Introduce IBuildCommandOptions with patterns, platform and timeout to control build behavior
+- Allow manager.build() to accept options and build only matching Dockerfiles (including dependencies) preserving topological order
+- Add CLI parsing for build/push to accept positional Dockerfile patterns and --platform/--timeout flags
+- Support single-platform override via docker buildx and multi-platform buildx detection
+- Implement streaming exec with timeout to kill long-running builds and surface timeout errors
+
+## 2026-02-04 - 1.4.3 - fix(dockerfile)
+fix matching of base images to local Dockerfiles by stripping registry prefixes when comparing image references
+
+- Added Dockerfile.extractRepoVersion(imageRef) to normalize image references by removing registry prefixes (detects registries containing '.' or ':' or 'localhost').
+- Use extractRepoVersion when checking tagToDockerfile and when mapping local base dockerfiles to ensure comparisons use repo:tag keys rather than full registry-prefixed references.
+- Prevents mismatches when baseImage includes a registry (e.g. "host.today/repo:version") so it correctly matches a local cleanTag like "repo:version".
+
+## 2026-01-21 - 1.4.2 - fix(classes.dockerfile)
+use a single top-level fs import instead of requiring fs inside methods
+
+- Added top-level import: import * as fs from 'fs' in ts/classes.dockerfile.ts
+- Removed inline require('fs') calls and replaced with the imported fs in constructor and test() to keep imports consistent
+- No behavioral change expected; this is a cleanup/refactor to standardize module usage
+
+## 2026-01-20 - 1.4.1 - fix(docs)
+update README: expand usage, installation, quick start, features, troubleshooting and migration notes
+
+- Expanded README content: new Quick Start, Installation examples, and detailed Features section (containerized testing, smart Docker builds, multi-registry push, multi-architecture support, zero-config start)
+- Added troubleshooting and performance tips including registry login guidance and circular dependency advice
+- Updated migration notes from legacy npmdocker to @git.zone/tsdocker (command and config key changes, ESM guidance)
+- Documentation-only change — no source code modified
+
 ## 2026-01-20 - 1.4.0 - feat(tsdocker)
 add multi-registry and multi-arch Docker build/push/pull manager, registry storage, Dockerfile handling, and new CLI commands
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tsdocker",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "private": false,
   "description": "develop npm modules cross platform with docker",
   "main": "dist_ts/index.js",

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,305 +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
-
-✨ **Works Everywhere Docker Does**
-
-- Docker Toolbox
-- Native Docker Desktop
-- Docker-in-Docker (DinD)
-- Mounted docker.sock scenarios
-
-🔧 **Flexible Configuration**
-
-- Custom base images
-- Configurable test commands
-- Environment variable injection via qenv
-- Optional docker.sock mounting for nested container tests
-
-📦 **TypeScript-First**
-
-- Full TypeScript support with excellent IntelliSense
-- Type-safe configuration
-- Modern ESM with async/await patterns throughout
+- 🧪 **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
 
 ## Installation
 
 ```bash
+# Global installation (recommended for CLI usage)
 npm install -g @git.zone/tsdocker
-# or for project-local installation
+
+# Or project-local installation
 pnpm install --save-dev @git.zone/tsdocker
 ```
 
 ## Quick Start
 
-### 1. Configure Your Project
+### 🧪 Run Tests in Docker
 
-Create an `npmextra.json` file in your project root:
+The simplest use case — run your tests in a clean container:
+
+```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
+tsdocker build
+```
+
+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
+
+Ship your images to one or all configured registries:
+
+```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"
 
-Example `qenv.yml`:
-
-```yaml
-demoKey: demoValue
-API_KEY: your-key-here
+# Individual registry format
+export DOCKER_REGISTRY_URL="registry.gitlab.com"
+export DOCKER_REGISTRY_USER="username"
+export DOCKER_REGISTRY_PASSWORD="password"
 ```
 
-## CLI Commands
-
-### Standard Test Run
+### Login Command
 
 ```bash
-tsdocker
+tsdocker login
 ```
 
-Runs your configured test command in a fresh Docker container.
-
-### Clean Docker Environment
-
-```bash
-tsdocker clean --all
-```
-
-⚠️ **WARNING**: This aggressively cleans your Docker environment by:
-
-- Killing all running containers
-- Removing all stopped containers
-- Removing dangling images
-- Removing all images
-- Removing dangling volumes
-
-Use with caution!
-
-### VSCode in Docker
-
-```bash
-tsdocker vscode
-```
-
-Launches a containerized VS Code instance accessible via browser at `testing-vscode.git.zone:8443`.
+Authenticates with all configured registries.
 
 ## Advanced Usage
 
-### Docker-in-Docker Testing
+### 🔀 Multi-Architecture Builds
 
-If you need to run Docker commands inside your test container (e.g., testing Docker-related tools):
+Build for multiple platforms using Docker Buildx:
+
+```json
+{
+  "@git.zone/tsdocker": {
+    "platforms": ["linux/amd64", "linux/arm64"]
+  }
+}
+```
+
+tsdocker automatically sets up a Buildx builder when multiple platforms are specified.
+
+### 📦 Dockerfile Naming Conventions
+
+tsdocker discovers files matching `Dockerfile*`:
+
+| File Name | Version Tag |
+|-----------|-------------|
+| `Dockerfile` | `latest` |
+| `Dockerfile_v1.0.0` | `v1.0.0` |
+| `Dockerfile_alpine` | `alpine` |
+| `Dockerfile_##version##` | Uses `package.json` version |
+
+### 🔗 Dependency-Aware Builds
+
+If you have multiple Dockerfiles that depend on each other:
+
+```dockerfile
+# Dockerfile_base
+FROM node:20-alpine
+RUN npm install -g typescript
+
+# Dockerfile_app
+FROM myproject:base
+COPY . .
+RUN npm run build
+```
+
+tsdocker automatically detects that `Dockerfile_app` depends on `Dockerfile_base` and builds them in the correct order.
+
+### 🧪 Container Test Scripts
+
+Create test scripts in your test directory:
+
+```bash
+# test/test_latest.sh
+#!/bin/bash
+node --version
+npm --version
+echo "Container tests passed!"
+```
+
+Run with:
+
+```bash
+tsdocker test
+```
+
+### 🔧 Build Args from Environment
+
+Pass environment variables as Docker build arguments:
+
+```json
+{
+  "@git.zone/tsdocker": {
+    "buildArgEnvMap": {
+      "NPM_TOKEN": "NPM_TOKEN",
+      "NODE_VERSION": "NODE_VERSION"
+    }
+  }
+}
+```
+
+```dockerfile
+ARG NPM_TOKEN
+ARG NODE_VERSION=20
+FROM node:${NODE_VERSION}
+RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+```
+
+### 🐳 Docker-in-Docker Testing
+
+Test Docker-related tools by mounting the Docker socket:
 
 ```json
 {
   "@git.zone/tsdocker": {
     "baseImage": "docker:latest",
-    "command": "docker run hello-world",
+    "command": "docker version && docker ps",
     "dockerSock": true
   }
 }
 ```
 
-Setting `"dockerSock": true` mounts the host's Docker socket into the container.
+### 📋 Listing Dockerfiles
 
-### Custom Base Images
+Inspect your project's Dockerfiles and their relationships:
 
-You can use any Docker image as your base:
+```bash
+tsdocker list
+```
+
+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
+```
+
+### 🗺️ Registry Repo Mapping
+
+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"
+    }
+  }
+}
+```
+
+## Environment Variables
+
+### qenv Integration
+
+tsdocker automatically loads environment variables from `qenv.yml`:
+
+```yaml
+# qenv.yml
+API_KEY: your-api-key
+DATABASE_URL: postgres://localhost/test
+```
+
+These are injected into your test container automatically.
+
+## Examples
+
+### Basic Test Configuration
+
+```json
+{
+  "@git.zone/tsdocker": {
+    "baseImage": "node:20",
+    "command": "npm test"
+  }
+}
+```
+
+### Full Production Setup
 
 ```json
 {
   "@git.zone/tsdocker": {
     "baseImage": "node:20-alpine",
-    "command": "npm test"
+    "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"
   }
 }
 ```
 
-Popular choices:
+### CI/CD Integration
 
-- `node:20` — Official Node.js images
-- `node:20-alpine` — Lightweight Alpine-based images
-- `node:lts` — Long-term support Node.js version
+```yaml
+# .gitlab-ci.yml
+build:
+  stage: build
+  script:
+    - npm install -g @git.zone/tsdocker
+    - tsdocker build
+    - tsdocker push
 
-### CI Integration
-
-tsdocker automatically detects CI environments (via `CI=true` env var) and adjusts behavior:
-
-- Copies project files into container in CI (instead of mounting)
-- Optimizes for CI execution patterns
-
-## Why tsdocker?
-
-### The Problem
-
-Local development environments drift over time. You might have:
-
-- Stale global packages
-- Modified system configurations
-- Cached dependencies
-- Different Node.js versions
-
-Your tests pass locally but fail in CI — or vice versa.
-
-### The Solution
-
-tsdocker ensures every test run happens in a **clean, reproducible environment**, just like your CI pipeline. This means:
-
-✅ Consistent behavior between local and CI
-✅ No dependency pollution between test runs
-✅ Easy cross-platform testing
-✅ Reproducible bug investigations
-
-## TypeScript Usage
-
-tsdocker is built with TypeScript and provides full type definitions:
-
-```typescript
-import type { IConfig } from '@git.zone/tsdocker/dist_ts/tsdocker.config.js';
-
-const config: IConfig = {
-  baseImage: 'node:20',
-  command: 'npm test',
-  dockerSock: false,
-  keyValueObject: {
-    NODE_ENV: 'test',
-  },
-};
+# 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
+
+### ✨ The Solution
+
+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
+
+## TypeScript API
+
+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';
+
+const config: ITsDockerConfig = {
+  baseImage: 'node:20',
+  command: 'npm test',
+  dockerSock: false,
+  keyValueObject: {},
+  registries: ['docker.io'],
+  platforms: ['linux/amd64'],
+};
+
+const manager = new TsDockerManager(config);
+await manager.prepare();
+await manager.build();
+await manager.push();
+```
 
 ## Troubleshooting
 
-### "docker not found on this machine"
+### "docker not found"
 
-Make sure Docker is installed and the `docker` command is in your PATH:
+Ensure Docker is installed and in your PATH:
 
 ```bash
 docker --version
 ```
 
-### Tests fail in container but work locally
+### Multi-arch build fails
 
-This often indicates environment-specific issues. Check:
-
-- Are all dependencies in `package.json`? (not relying on global packages)
-- Does your code have hardcoded paths?
-- Are environment variables set correctly?
-
-### Permission errors with docker.sock
-
-If using `dockerSock: true`, ensure your user has permissions to access `/var/run/docker.sock`:
+Make sure Docker Buildx is available:
 
 ```bash
-sudo usermod -aG docker $USER
-# Then log out and back in
+docker buildx version
+docker buildx create --use
 ```
 
-## Examples
+### Registry authentication fails
 
-### Basic npm test
+Check your environment variables are set correctly:
 
-```json
-{
-  "@git.zone/tsdocker": {
-    "baseImage": "node:20",
-    "command": "npm test"
-  }
-}
+```bash
+echo $DOCKER_REGISTRY_1
+tsdocker login
 ```
 
-### Running pnpm tests
+### Circular dependency detected
 
-```json
-{
-  "@git.zone/tsdocker": {
-    "baseImage": "node:20",
-    "command": "corepack enable && pnpm install && pnpm test"
-  }
-}
-```
-
-### Testing Docker-based tools
-
-```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`
 
-## Migration from legacy npmdocker
+🚀 **Leverage caching**: Docker layers are cached — your builds get faster over time
 
-This package was previously published under the `npmdocker` name. It is now available as `@git.zone/tsdocker` with modernized ESM support and updated dependencies.
+🚀 **Prune regularly**: `docker system prune` reclaims disk space
 
-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
+🚀 **Use .dockerignore**: Exclude `node_modules`, `.git`, etc. from build context
+
+## Migration from Legacy
+
+Previously published as `npmdocker`, now `@git.zone/tsdocker`:
+
+| Old | New |
+|-----|-----|
+| `npmdocker` command | `tsdocker` command |
+| `"npmdocker"` config key | `"@git.zone/tsdocker"` config key |
+| CommonJS | ESM with `.js` imports |
 
 ## License and Legal Information
 

ts/00_commitinfo_data.ts

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

ts/classes.dockerfile.ts

@@ -2,8 +2,9 @@ import * as plugins from './tsdocker.plugins.js';
 import * as paths from './tsdocker.paths.js';
 import { logger } from './tsdocker.logging.js';
 import { DockerRegistry } from './classes.dockerregistry.js';
-import type { IDockerfileOptions, ITsDockerConfig } from './interfaces/index.js';
+import type { IDockerfileOptions, ITsDockerConfig, IBuildCommandOptions } from './interfaces/index.js';
 import type { TsDockerManager } from './classes.tsdockermanager.js';
+import * as fs from 'fs';
 
 const smartshellInstance = new plugins.smartshell.Smartshell({
   executor: 'bash',
@@ -57,9 +58,14 @@ export class Dockerfile {
       const dependencies: Dockerfile[] = [];
       const baseImage = dockerfile.baseImage;
 
+      // Extract repo:version from baseImage for comparison with cleanTag
+      // baseImage may include a registry prefix (e.g., "host.today/repo:version")
+      // but cleanTag is just "repo:version", so we strip the registry prefix
+      const baseImageKey = Dockerfile.extractRepoVersion(baseImage);
+
       // Check if the baseImage is among the local Dockerfiles
-      if (tagToDockerfile.has(baseImage)) {
-        const baseDockerfile = tagToDockerfile.get(baseImage)!;
+      if (tagToDockerfile.has(baseImageKey)) {
+        const baseDockerfile = tagToDockerfile.get(baseImageKey)!;
         dependencies.push(baseDockerfile);
         dockerfile.localBaseImageDependent = true;
         dockerfile.localBaseDockerfile = baseDockerfile;
@@ -115,8 +121,10 @@ export class Dockerfile {
   public static async mapDockerfiles(sortedDockerfileArray: Dockerfile[]): Promise<Dockerfile[]> {
     sortedDockerfileArray.forEach((dockerfileArg) => {
       if (dockerfileArg.localBaseImageDependent) {
+        // Extract repo:version from baseImage for comparison with cleanTag
+        const baseImageKey = Dockerfile.extractRepoVersion(dockerfileArg.baseImage);
         sortedDockerfileArray.forEach((dockfile2: Dockerfile) => {
-          if (dockfile2.cleanTag === dockerfileArg.baseImage) {
+          if (dockfile2.cleanTag === baseImageKey) {
             dockerfileArg.localBaseDockerfile = dockfile2;
           }
         });
@@ -128,9 +136,25 @@ export class Dockerfile {
   /**
    * Builds the corresponding real docker image for each Dockerfile class instance
    */
-  public static async buildDockerfiles(sortedArrayArg: Dockerfile[]): Promise<Dockerfile[]> {
+  public static async buildDockerfiles(
+    sortedArrayArg: Dockerfile[],
+    options?: { platform?: string; timeout?: number; noCache?: boolean },
+  ): Promise<Dockerfile[]> {
     for (const dockerfileArg of sortedArrayArg) {
-      await dockerfileArg.build();
+      await dockerfileArg.build(options);
+
+      // Tag the built image with the full base image references used by dependent Dockerfiles,
+      // so their FROM lines resolve to the locally-built image instead of pulling from a registry.
+      const dependentBaseImages = new Set<string>();
+      for (const other of sortedArrayArg) {
+        if (other.localBaseDockerfile === dockerfileArg && other.baseImage !== dockerfileArg.buildTag) {
+          dependentBaseImages.add(other.baseImage);
+        }
+      }
+      for (const fullTag of dependentBaseImages) {
+        logger.log('info', `Tagging ${dockerfileArg.buildTag} as ${fullTag} for local dependency resolution`);
+        await smartshellInstance.exec(`docker tag ${dockerfileArg.buildTag} ${fullTag}`);
+      }
     }
     return sortedArrayArg;
   }
@@ -230,6 +254,34 @@ export class Dockerfile {
     });
   }
 
+  /**
+   * Extracts the repo:version part from a full image reference, stripping any registry prefix.
+   * Examples:
+   *   "registry.example.com/repo:version" -> "repo:version"
+   *   "repo:version" -> "repo:version"
+   *   "host.today/ht-docker-node:npmci" -> "ht-docker-node:npmci"
+   */
+  private static extractRepoVersion(imageRef: string): string {
+    const parts = imageRef.split('/');
+    if (parts.length === 1) {
+      // No registry prefix: "repo:version"
+      return imageRef;
+    }
+
+    // Check if first part looks like a registry (contains '.' or ':' or is 'localhost')
+    const firstPart = parts[0];
+    const looksLikeRegistry =
+      firstPart.includes('.') || firstPart.includes(':') || firstPart === 'localhost';
+
+    if (looksLikeRegistry) {
+      // Strip registry: "registry.example.com/repo:version" -> "repo:version"
+      return parts.slice(1).join('/');
+    }
+
+    // No registry prefix, could be "org/repo:version"
+    return imageRef;
+  }
+
   /**
    * Returns the docker tag string for a given registry and repo
    */
@@ -314,7 +366,6 @@ export class Dockerfile {
     this.containerName = 'dockerfile-' + this.version;
 
     if (options.filePath && options.read) {
-      const fs = require('fs');
       this.content = fs.readFileSync(plugins.path.resolve(options.filePath), 'utf-8');
     } else if (options.fileContents) {
       this.content = options.fileContents;
@@ -327,18 +378,23 @@ export class Dockerfile {
   /**
    * Builds the Dockerfile
    */
-  public async build(): Promise<void> {
+  public async build(options?: { platform?: string; timeout?: number; noCache?: boolean }): Promise<void> {
     logger.log('info', 'now building Dockerfile for ' + this.cleanTag);
     const buildArgsString = await Dockerfile.getDockerBuildArgs(this.managerRef);
     const config = this.managerRef.config;
+    const platformOverride = options?.platform;
+    const timeout = options?.timeout;
+    const noCacheFlag = options?.noCache ? ' --no-cache' : '';
 
     let buildCommand: string;
 
-    // Check if multi-platform build is needed
-    if (config.platforms && config.platforms.length > 1) {
+    if (platformOverride) {
+      // Single platform override via buildx
+      buildCommand = `docker buildx build --platform ${platformOverride}${noCacheFlag} --load -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
+    } else if (config.platforms && config.platforms.length > 1) {
       // Multi-platform build using buildx
       const platformString = config.platforms.join(',');
-      buildCommand = `docker buildx build --platform ${platformString} -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
+      buildCommand = `docker buildx build --platform ${platformString}${noCacheFlag} -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
 
       if (config.push) {
         buildCommand += ' --push';
@@ -348,14 +404,30 @@ export class Dockerfile {
     } else {
       // Standard build
       const versionLabel = this.managerRef.projectInfo?.npm?.version || 'unknown';
-      buildCommand = `docker build --label="version=${versionLabel}" -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
+      buildCommand = `docker build --label="version=${versionLabel}"${noCacheFlag} -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
     }
 
-    const result = await smartshellInstance.exec(buildCommand);
-    if (result.exitCode !== 0) {
-      logger.log('error', `Build failed for ${this.cleanTag}`);
-      console.log(result.stdout);
-      throw new Error(`Build failed for ${this.cleanTag}`);
+    if (timeout) {
+      // Use streaming execution with timeout
+      const streaming = await smartshellInstance.execStreaming(buildCommand);
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => {
+          streaming.childProcess.kill();
+          reject(new Error(`Build timed out after ${timeout}s for ${this.cleanTag}`));
+        }, timeout * 1000);
+      });
+      const result = await Promise.race([streaming.finalPromise, timeoutPromise]);
+      if (result.exitCode !== 0) {
+        logger.log('error', `Build failed for ${this.cleanTag}`);
+        throw new Error(`Build failed for ${this.cleanTag}`);
+      }
+    } else {
+      const result = await smartshellInstance.exec(buildCommand);
+      if (result.exitCode !== 0) {
+        logger.log('error', `Build failed for ${this.cleanTag}`);
+        console.log(result.stdout);
+        throw new Error(`Build failed for ${this.cleanTag}`);
+      }
     }
 
     logger.log('ok', `Built ${this.cleanTag}`);
@@ -419,7 +491,6 @@ export class Dockerfile {
     const testDir = this.managerRef.config.testDir || plugins.path.join(paths.cwd, 'test');
     const testFile = plugins.path.join(testDir, 'test_' + this.version + '.sh');
 
-    const fs = require('fs');
     const testFileExists = fs.existsSync(testFile);
 
     if (testFileExists) {

ts/classes.tsdockermanager.ts

@@ -4,7 +4,7 @@ import { logger } from './tsdocker.logging.js';
 import { Dockerfile } from './classes.dockerfile.js';
 import { DockerRegistry } from './classes.dockerregistry.js';
 import { RegistryStorage } from './classes.registrystorage.js';
-import type { ITsDockerConfig } from './interfaces/index.js';
+import type { ITsDockerConfig, IBuildCommandOptions } from './interfaces/index.js';
 
 const smartshellInstance = new plugins.smartshell.Smartshell({
   executor: 'bash',
@@ -90,9 +90,10 @@ export class TsDockerManager {
   }
 
   /**
-   * Builds all discovered Dockerfiles in dependency order
+   * Builds discovered Dockerfiles in dependency order.
+   * When options.patterns is provided, only matching Dockerfiles (and their dependencies) are built.
    */
-  public async build(): Promise<Dockerfile[]> {
+  public async build(options?: IBuildCommandOptions): Promise<Dockerfile[]> {
     if (this.dockerfiles.length === 0) {
       await this.discoverDockerfiles();
     }
@@ -102,16 +103,64 @@ export class TsDockerManager {
       return [];
     }
 
+    // Determine which Dockerfiles to build
+    let toBuild = this.dockerfiles;
+
+    if (options?.patterns && options.patterns.length > 0) {
+      // Filter to matching Dockerfiles
+      const matched = this.dockerfiles.filter((df) => {
+        const basename = plugins.path.basename(df.filePath);
+        return options.patterns!.some((pattern) => {
+          if (pattern.includes('*') || pattern.includes('?')) {
+            // Convert glob pattern to regex
+            const regexStr = '^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$';
+            return new RegExp(regexStr).test(basename);
+          }
+          return basename === pattern;
+        });
+      });
+
+      if (matched.length === 0) {
+        logger.log('warn', `No Dockerfiles matched patterns: ${options.patterns.join(', ')}`);
+        return [];
+      }
+
+      // Resolve dependency chain and preserve topological order
+      toBuild = this.resolveWithDependencies(matched, this.dockerfiles);
+      logger.log('info', `Matched ${matched.length} Dockerfile(s), building ${toBuild.length} (including dependencies)`);
+    }
+
     // Check if buildx is needed
-    if (this.config.platforms && this.config.platforms.length > 1) {
+    if (options?.platform || (this.config.platforms && this.config.platforms.length > 1)) {
       await this.ensureBuildx();
     }
 
-    logger.log('info', `Building ${this.dockerfiles.length} Dockerfiles...`);
-    await Dockerfile.buildDockerfiles(this.dockerfiles);
+    logger.log('info', `Building ${toBuild.length} Dockerfiles...`);
+    await Dockerfile.buildDockerfiles(toBuild, {
+      platform: options?.platform,
+      timeout: options?.timeout,
+      noCache: options?.noCache,
+    });
     logger.log('success', 'All Dockerfiles built successfully');
 
-    return this.dockerfiles;
+    return toBuild;
+  }
+
+  /**
+   * Resolves a set of target Dockerfiles to include all their local base image dependencies,
+   * preserving the original topological build order.
+   */
+  private resolveWithDependencies(targets: Dockerfile[], allSorted: Dockerfile[]): Dockerfile[] {
+    const needed = new Set<Dockerfile>();
+    const addWithDeps = (df: Dockerfile) => {
+      if (needed.has(df)) return;
+      needed.add(df);
+      if (df.localBaseImageDependent && df.localBaseDockerfile) {
+        addWithDeps(df.localBaseDockerfile);
+      }
+    };
+    for (const df of targets) addWithDeps(df);
+    return allSorted.filter((df) => needed.has(df));
   }
 
   /**

ts/interfaces/index.ts

@@ -68,3 +68,13 @@ export interface IPushResult {
   digest?: string;
   error?: string;
 }
+
+/**
+ * Options for the build command
+ */
+export interface IBuildCommandOptions {
+  patterns?: string[];  // Dockerfile name patterns (e.g., ['Dockerfile_base', 'Dockerfile_*'])
+  platform?: string;    // Single platform override (e.g., 'linux/arm64')
+  timeout?: number;     // Build timeout in seconds
+  noCache?: boolean;    // Force rebuild without Docker layer cache (--no-cache)
+}

ts/tsdocker.cli.ts

@@ -7,6 +7,7 @@ import * as DockerModule from './tsdocker.docker.js';
 
 import { logger, ora } from './tsdocker.logging.js';
 import { TsDockerManager } from './classes.tsdockermanager.js';
+import type { IBuildCommandOptions } from './interfaces/index.js';
 
 const tsdockerCli = new plugins.smartcli.Smartcli();
 
@@ -23,14 +24,31 @@ export let run = () => {
   });
 
   /**
-   * Build all Dockerfiles in dependency order
+   * Build Dockerfiles in dependency order
+   * Usage: tsdocker build [Dockerfile_patterns...] [--platform=linux/arm64] [--timeout=600]
    */
   tsdockerCli.addCommand('build').subscribe(async argvArg => {
     try {
       const config = await ConfigModule.run();
       const manager = new TsDockerManager(config);
       await manager.prepare();
-      await manager.build();
+
+      const buildOptions: IBuildCommandOptions = {};
+      const patterns = argvArg._.slice(1) as string[];
+      if (patterns.length > 0) {
+        buildOptions.patterns = patterns;
+      }
+      if (argvArg.platform) {
+        buildOptions.platform = argvArg.platform as string;
+      }
+      if (argvArg.timeout) {
+        buildOptions.timeout = Number(argvArg.timeout);
+      }
+      if (argvArg.cache === false) {
+        buildOptions.noCache = true;
+      }
+
+      await manager.build(buildOptions);
       logger.log('success', 'Build completed successfully');
     } catch (err) {
       logger.log('error', `Build failed: ${(err as Error).message}`);
@@ -40,6 +58,7 @@ export let run = () => {
 
   /**
    * Push built images to configured registries
+   * Usage: tsdocker push [Dockerfile_patterns...] [--platform=linux/arm64] [--timeout=600] [--registry=url]
    */
   tsdockerCli.addCommand('push').subscribe(async argvArg => {
     try {
@@ -50,11 +69,27 @@ export let run = () => {
       // Login first
       await manager.login();
 
-      // Build images first (if not already built)
-      await manager.build();
+      // Parse build options from positional args and flags
+      const buildOptions: IBuildCommandOptions = {};
+      const patterns = argvArg._.slice(1) as string[];
+      if (patterns.length > 0) {
+        buildOptions.patterns = patterns;
+      }
+      if (argvArg.platform) {
+        buildOptions.platform = argvArg.platform as string;
+      }
+      if (argvArg.timeout) {
+        buildOptions.timeout = Number(argvArg.timeout);
+      }
+      if (argvArg.cache === false) {
+        buildOptions.noCache = true;
+      }
 
-      // Get registry from arguments if specified
-      const registryArg = argvArg._[1]; // e.g., tsdocker push registry.gitlab.com
+      // Build images first (if not already built)
+      await manager.build(buildOptions);
+
+      // Get registry from --registry flag
+      const registryArg = argvArg.registry as string | undefined;
       const registries = registryArg ? [registryArg] : undefined;
 
       await manager.push(registries);
@@ -101,7 +136,11 @@ export let run = () => {
       await manager.prepare();
 
       // Build images first
-      await manager.build();
+      const buildOptions: IBuildCommandOptions = {};
+      if (argvArg.cache === false) {
+        buildOptions.noCache = true;
+      }
+      await manager.build(buildOptions);
 
       // Run tests
       await manager.test();