v1.14.0

changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2026-02-07 - 1.14.0 - feat(build)
+add level-based parallel builds with --parallel and configurable concurrency
+
+- Introduces --parallel and --parallel=<n> CLI flags to enable level-based parallel Docker builds (default concurrency 4).
+- Adds Dockerfile.computeLevels() to group topologically-sorted Dockerfiles into dependency levels.
+- Adds Dockerfile.runWithConcurrency() implementing a bounded-concurrency worker-pool (fast-fail via Promise.all).
+- Integrates parallel build mode into Dockerfile.buildDockerfiles() and TsDockerManager.build() for both cached and non-cached flows, including tagging and pushing for dependency resolution after each level.
+- Adds options.parallel and options.parallelConcurrency to the build interface and wires them through the CLI and manager.
+- Updates documentation (readme.hints.md) with usage examples and implementation notes.
+
+## 2026-02-07 - 1.13.0 - feat(docker)
+add Docker context detection, rootless support, and context-aware buildx registry handling
+
+- Introduce DockerContext class to detect current Docker context and rootless mode and to log warnings and context info
+- Add IDockerContextInfo interface and a new context option on build/config to pass explicit Docker context
+- Propagate --context CLI flag into TsDockerManager.prepare so CLI commands can set an explicit Docker context
+- Make buildx builder name context-aware (tsdocker-builder-<sanitized-context>) and log builder name/platforms
+- Pass isRootless into local registry startup and build pipeline; emit rootless-specific warnings and registry reachability hint
+
 ## 2026-02-06 - 1.12.0 - feat(docker)
 add detailed logging for buildx, build commands, local registry, and local dependency info
 

package.json

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

readme.hints.md

@@ -96,6 +96,18 @@ ts/
 - `@push.rocks/smartcli`: CLI framework
 - `@push.rocks/projectinfo`: Project metadata
 
+## Parallel Builds
+
+`--parallel` flag enables level-based parallel Docker builds:
+
+```bash
+tsdocker build --parallel           # parallel, default concurrency (4)
+tsdocker build --parallel=8         # parallel, concurrency 8
+tsdocker build --parallel --cached  # works with both modes
+```
+
+Implementation: `Dockerfile.computeLevels()` groups topologically sorted Dockerfiles into dependency levels. `Dockerfile.runWithConcurrency()` provides a worker-pool pattern for bounded concurrency. Both are public static methods on the `Dockerfile` class. The parallel logic exists in both `Dockerfile.buildDockerfiles()` (standard mode) and `TsDockerManager.build()` (cached mode).
+
 ## Build Status
 
 - Build: ✅ Passes

ts/00_commitinfo_data.ts

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

ts/classes.dockercontext.ts

@@ -0,0 +1,69 @@
+import * as plugins from './tsdocker.plugins.js';
+import { logger } from './tsdocker.logging.js';
+import type { IDockerContextInfo } from './interfaces/index.js';
+
+const smartshellInstance = new plugins.smartshell.Smartshell({ executor: 'bash' });
+
+export class DockerContext {
+  public contextInfo: IDockerContextInfo | null = null;
+
+  /** Sets DOCKER_CONTEXT env var for explicit context selection. */
+  public setContext(contextName: string): void {
+    process.env.DOCKER_CONTEXT = contextName;
+    logger.log('info', `Docker context explicitly set to: ${contextName}`);
+  }
+
+  /** Detects current Docker context via `docker context inspect` and rootless via `docker info`. */
+  public async detect(): Promise<IDockerContextInfo> {
+    let name = 'default';
+    let endpoint = 'unknown';
+
+    const contextResult = await smartshellInstance.execSilent(
+      `docker context inspect --format '{{json .}}'`
+    );
+    if (contextResult.exitCode === 0 && contextResult.stdout) {
+      try {
+        const parsed = JSON.parse(contextResult.stdout.trim());
+        const data = Array.isArray(parsed) ? parsed[0] : parsed;
+        name = data.Name || 'default';
+        endpoint = data.Endpoints?.docker?.Host || 'unknown';
+      } catch { /* fallback to defaults */ }
+    }
+
+    let isRootless = false;
+    const infoResult = await smartshellInstance.execSilent(
+      `docker info --format '{{json .SecurityOptions}}'`
+    );
+    if (infoResult.exitCode === 0 && infoResult.stdout) {
+      isRootless = infoResult.stdout.includes('name=rootless');
+    }
+
+    this.contextInfo = { name, endpoint, isRootless, dockerHost: process.env.DOCKER_HOST };
+    return this.contextInfo;
+  }
+
+  /** Logs context info prominently. */
+  public logContextInfo(): void {
+    if (!this.contextInfo) return;
+    const { name, endpoint, isRootless, dockerHost } = this.contextInfo;
+    logger.log('info', '=== DOCKER CONTEXT ===');
+    logger.log('info', `Context:  ${name}`);
+    logger.log('info', `Endpoint: ${endpoint}`);
+    if (dockerHost) logger.log('info', `DOCKER_HOST: ${dockerHost}`);
+    logger.log('info', `Rootless: ${isRootless ? 'yes' : 'no'}`);
+  }
+
+  /** Emits rootless-specific warnings. */
+  public logRootlessWarnings(): void {
+    if (!this.contextInfo?.isRootless) return;
+    logger.log('warn', '[rootless] network=host in buildx is namespaced by rootlesskit');
+    logger.log('warn', '[rootless] Local registry may have localhost vs 127.0.0.1 resolution quirks');
+  }
+
+  /** Returns context-aware builder name: tsdocker-builder-<context> */
+  public getBuilderName(): string {
+    const contextName = this.contextInfo?.name || 'default';
+    const sanitized = contextName.replace(/[^a-zA-Z0-9_-]/g, '-');
+    return `tsdocker-builder-${sanitized}`;
+  }
+}

ts/classes.dockerfile.ts

@@ -151,7 +151,7 @@ export class Dockerfile {
   }
 
   /** Starts a temporary registry:2 container on port 5234. */
-  public static async startLocalRegistry(): Promise<void> {
+  public static async startLocalRegistry(isRootless?: boolean): Promise<void> {
     await smartshellInstance.execSilent(
       `docker rm -f ${LOCAL_REGISTRY_CONTAINER} 2>/dev/null || true`
     );
@@ -164,6 +164,9 @@ export class Dockerfile {
     // registry:2 starts near-instantly; brief wait for readiness
     await new Promise(resolve => setTimeout(resolve, 1000));
     logger.log('info', `Started local registry at ${LOCAL_REGISTRY_HOST} (buildx dependency bridge)`);
+    if (isRootless) {
+      logger.log('warn', `[rootless] Registry on port ${LOCAL_REGISTRY_PORT} — if buildx cannot reach localhost:${LOCAL_REGISTRY_PORT}, try 127.0.0.1:${LOCAL_REGISTRY_PORT}`);
+    }
   }
 
   /** Stops and removes the temporary local registry container. */
@@ -186,22 +189,118 @@ export class Dockerfile {
     logger.log('info', `Pushed ${dockerfile.buildTag} to local registry as ${registryTag}`);
   }
 
+  /**
+   * Groups topologically sorted Dockerfiles into dependency levels.
+   * Level 0 = no local dependencies; level N = depends on something in level N-1.
+   * Images within the same level are independent and can build in parallel.
+   */
+  public static computeLevels(sortedDockerfiles: Dockerfile[]): Dockerfile[][] {
+    const levelMap = new Map<Dockerfile, number>();
+    for (const df of sortedDockerfiles) {
+      if (!df.localBaseImageDependent || !df.localBaseDockerfile) {
+        levelMap.set(df, 0);
+      } else {
+        const depLevel = levelMap.get(df.localBaseDockerfile) ?? 0;
+        levelMap.set(df, depLevel + 1);
+      }
+    }
+    const maxLevel = Math.max(...Array.from(levelMap.values()), 0);
+    const levels: Dockerfile[][] = [];
+    for (let l = 0; l <= maxLevel; l++) {
+      levels.push(sortedDockerfiles.filter(df => levelMap.get(df) === l));
+    }
+    return levels;
+  }
+
+  /**
+   * Runs async tasks with bounded concurrency (worker-pool pattern).
+   * Fast-fail: if any task throws, Promise.all rejects immediately.
+   */
+  public static async runWithConcurrency<T>(
+    tasks: (() => Promise<T>)[],
+    concurrency: number,
+  ): Promise<T[]> {
+    const results: T[] = new Array(tasks.length);
+    let nextIndex = 0;
+    async function worker(): Promise<void> {
+      while (true) {
+        const idx = nextIndex++;
+        if (idx >= tasks.length) break;
+        results[idx] = await tasks[idx]();
+      }
+    }
+    const workers = Array.from(
+      { length: Math.min(concurrency, tasks.length) },
+      () => worker(),
+    );
+    await Promise.all(workers);
+    return results;
+  }
+
   /**
    * Builds the corresponding real docker image for each Dockerfile class instance
    */
   public static async buildDockerfiles(
     sortedArrayArg: Dockerfile[],
-    options?: { platform?: string; timeout?: number; noCache?: boolean; verbose?: boolean },
+    options?: { platform?: string; timeout?: number; noCache?: boolean; verbose?: boolean; isRootless?: boolean; parallel?: boolean; parallelConcurrency?: number },
   ): Promise<Dockerfile[]> {
     const total = sortedArrayArg.length;
     const overallStart = Date.now();
     const useRegistry = Dockerfile.needsLocalRegistry(sortedArrayArg, options);
 
     if (useRegistry) {
-      await Dockerfile.startLocalRegistry();
+      await Dockerfile.startLocalRegistry(options?.isRootless);
     }
 
     try {
+      if (options?.parallel) {
+        // === PARALLEL MODE: build independent images concurrently within each level ===
+        const concurrency = options.parallelConcurrency ?? 4;
+        const levels = Dockerfile.computeLevels(sortedArrayArg);
+
+        logger.log('info', `Parallel build: ${levels.length} level(s), concurrency ${concurrency}`);
+        for (let l = 0; l < levels.length; l++) {
+          const level = levels[l];
+          logger.log('info', `  Level ${l} (${level.length}): ${level.map(df => df.cleanTag).join(', ')}`);
+        }
+
+        let built = 0;
+        for (let l = 0; l < levels.length; l++) {
+          const level = levels[l];
+          logger.log('info', `--- Level ${l}: building ${level.length} image(s) in parallel ---`);
+
+          const tasks = level.map((df) => {
+            const myIndex = ++built;
+            return async () => {
+              const progress = `(${myIndex}/${total})`;
+              logger.log('info', `${progress} Building ${df.cleanTag}...`);
+              const elapsed = await df.build(options);
+              logger.log('ok', `${progress} Built ${df.cleanTag} in ${formatDuration(elapsed)}`);
+              return df;
+            };
+          });
+
+          await Dockerfile.runWithConcurrency(tasks, concurrency);
+
+          // After the entire level completes, tag + push for dependency resolution
+          for (const df of level) {
+            const dependentBaseImages = new Set<string>();
+            for (const other of sortedArrayArg) {
+              if (other.localBaseDockerfile === df && other.baseImage !== df.buildTag) {
+                dependentBaseImages.add(other.baseImage);
+              }
+            }
+            for (const fullTag of dependentBaseImages) {
+              logger.log('info', `Tagging ${df.buildTag} as ${fullTag} for local dependency resolution`);
+              await smartshellInstance.exec(`docker tag ${df.buildTag} ${fullTag}`);
+            }
+            if (useRegistry && sortedArrayArg.some(other => other.localBaseDockerfile === df)) {
+              await Dockerfile.pushToLocalRegistry(df);
+            }
+          }
+        }
+      } else {
+        // === SEQUENTIAL MODE: build one at a time ===
         for (let i = 0; i < total; i++) {
           const dockerfileArg = sortedArrayArg[i];
           const progress = `(${i + 1}/${total})`;
@@ -227,6 +326,7 @@ export class Dockerfile {
             await Dockerfile.pushToLocalRegistry(dockerfileArg);
           }
         }
+      }
     } finally {
       if (useRegistry) {
         await Dockerfile.stopLocalRegistry();

ts/classes.tsdockermanager.ts

@@ -5,6 +5,7 @@ import { Dockerfile } from './classes.dockerfile.js';
 import { DockerRegistry } from './classes.dockerregistry.js';
 import { RegistryStorage } from './classes.registrystorage.js';
 import { TsDockerCache } from './classes.tsdockercache.js';
+import { DockerContext } from './classes.dockercontext.js';
 import type { ITsDockerConfig, IBuildCommandOptions } from './interfaces/index.js';
 
 const smartshellInstance = new plugins.smartshell.Smartshell({
@@ -18,17 +19,27 @@ export class TsDockerManager {
   public registryStorage: RegistryStorage;
   public config: ITsDockerConfig;
   public projectInfo: any;
+  public dockerContext: DockerContext;
   private dockerfiles: Dockerfile[] = [];
 
   constructor(config: ITsDockerConfig) {
     this.config = config;
     this.registryStorage = new RegistryStorage();
+    this.dockerContext = new DockerContext();
   }
 
   /**
    * Prepares the manager by loading project info and registries
    */
-  public async prepare(): Promise<void> {
+  public async prepare(contextArg?: string): Promise<void> {
+    // Detect Docker context
+    if (contextArg) {
+      this.dockerContext.setContext(contextArg);
+    }
+    await this.dockerContext.detect();
+    this.dockerContext.logContextInfo();
+    this.dockerContext.logRootlessWarnings();
+
     // Load project info
     try {
       const projectinfoInstance = new plugins.projectinfo.ProjectInfo(paths.cwd);
@@ -156,6 +167,16 @@ export class TsDockerManager {
       logger.log('info', 'Cache: disabled (--no-cache)');
     }
 
+    if (options?.parallel) {
+      const concurrency = options.parallelConcurrency ?? 4;
+      const levels = Dockerfile.computeLevels(toBuild);
+      logger.log('info', `Parallel build: ${levels.length} level(s), concurrency ${concurrency}`);
+      for (let l = 0; l < levels.length; l++) {
+        const level = levels[l];
+        logger.log('info', `  Level ${l} (${level.length}): ${level.map(df => df.cleanTag).join(', ')}`);
+      }
+    }
+
     logger.log('info', `Building ${toBuild.length} Dockerfile(s)...`);
 
     if (options?.cached) {
@@ -169,10 +190,65 @@ export class TsDockerManager {
       const useRegistry = Dockerfile.needsLocalRegistry(toBuild, options);
 
       if (useRegistry) {
-        await Dockerfile.startLocalRegistry();
+        await Dockerfile.startLocalRegistry(this.dockerContext.contextInfo?.isRootless);
       }
 
       try {
+        if (options?.parallel) {
+          // === PARALLEL CACHED MODE ===
+          const concurrency = options.parallelConcurrency ?? 4;
+          const levels = Dockerfile.computeLevels(toBuild);
+
+          let built = 0;
+          for (let l = 0; l < levels.length; l++) {
+            const level = levels[l];
+            logger.log('info', `--- Level ${l}: building ${level.length} image(s) in parallel ---`);
+
+            const tasks = level.map((df) => {
+              const myIndex = ++built;
+              return async () => {
+                const progress = `(${myIndex}/${total})`;
+                const skip = await cache.shouldSkipBuild(df.cleanTag, df.content);
+
+                if (skip) {
+                  logger.log('ok', `${progress} Skipped ${df.cleanTag} (cached)`);
+                } else {
+                  logger.log('info', `${progress} Building ${df.cleanTag}...`);
+                  const elapsed = await df.build({
+                    platform: options?.platform,
+                    timeout: options?.timeout,
+                    noCache: options?.noCache,
+                    verbose: options?.verbose,
+                  });
+                  logger.log('ok', `${progress} Built ${df.cleanTag} in ${formatDuration(elapsed)}`);
+                  const imageId = await df.getId();
+                  cache.recordBuild(df.cleanTag, df.content, imageId, df.buildTag);
+                }
+                return df;
+              };
+            });
+
+            await Dockerfile.runWithConcurrency(tasks, concurrency);
+
+            // After the entire level completes, tag + push for dependency resolution
+            for (const df of level) {
+              const dependentBaseImages = new Set<string>();
+              for (const other of toBuild) {
+                if (other.localBaseDockerfile === df && other.baseImage !== df.buildTag) {
+                  dependentBaseImages.add(other.baseImage);
+                }
+              }
+              for (const fullTag of dependentBaseImages) {
+                logger.log('info', `Tagging ${df.buildTag} as ${fullTag} for local dependency resolution`);
+                await smartshellInstance.exec(`docker tag ${df.buildTag} ${fullTag}`);
+              }
+              if (useRegistry && toBuild.some(other => other.localBaseDockerfile === df)) {
+                await Dockerfile.pushToLocalRegistry(df);
+              }
+            }
+          }
+        } else {
+          // === SEQUENTIAL CACHED MODE ===
           for (let i = 0; i < total; i++) {
             const dockerfileArg = toBuild[i];
             const progress = `(${i + 1}/${total})`;
@@ -210,6 +286,7 @@ export class TsDockerManager {
               await Dockerfile.pushToLocalRegistry(dockerfileArg);
             }
           }
+        }
       } finally {
         if (useRegistry) {
           await Dockerfile.stopLocalRegistry();
@@ -225,6 +302,9 @@ export class TsDockerManager {
         timeout: options?.timeout,
         noCache: options?.noCache,
         verbose: options?.verbose,
+        isRootless: this.dockerContext.contextInfo?.isRootless,
+        parallel: options?.parallel,
+        parallelConcurrency: options?.parallelConcurrency,
       });
     }
 
@@ -254,30 +334,32 @@ export class TsDockerManager {
    * Ensures Docker buildx is set up for multi-architecture builds
    */
   private async ensureBuildx(): Promise<void> {
+    const builderName = this.dockerContext.getBuilderName();
     const platforms = this.config.platforms?.join(', ') || 'default';
-    logger.log('info', `Setting up Docker buildx for multi-platform builds [${platforms}]...`);
+    logger.log('info', `Setting up Docker buildx [${platforms}]...`);
-    const inspectResult = await smartshellInstance.exec('docker buildx inspect tsdocker-builder 2>/dev/null');
+    logger.log('info', `Builder: ${builderName}`);
+    const inspectResult = await smartshellInstance.exec(`docker buildx inspect ${builderName} 2>/dev/null`);
 
     if (inspectResult.exitCode !== 0) {
       logger.log('info', 'Creating new buildx builder with host network...');
       await smartshellInstance.exec(
-        'docker buildx create --name tsdocker-builder --driver docker-container --driver-opt network=host --use'
+        `docker buildx create --name ${builderName} --driver docker-container --driver-opt network=host --use`
       );
       await smartshellInstance.exec('docker buildx inspect --bootstrap');
     } else {
       const inspectOutput = inspectResult.stdout || '';
       if (!inspectOutput.includes('network=host')) {
         logger.log('info', 'Recreating buildx builder with host network (migration)...');
-        await smartshellInstance.exec('docker buildx rm tsdocker-builder 2>/dev/null');
+        await smartshellInstance.exec(`docker buildx rm ${builderName} 2>/dev/null`);
         await smartshellInstance.exec(
-          'docker buildx create --name tsdocker-builder --driver docker-container --driver-opt network=host --use'
+          `docker buildx create --name ${builderName} --driver docker-container --driver-opt network=host --use`
         );
         await smartshellInstance.exec('docker buildx inspect --bootstrap');
       } else {
-        await smartshellInstance.exec('docker buildx use tsdocker-builder');
+        await smartshellInstance.exec(`docker buildx use ${builderName}`);
       }
     }
-    logger.log('ok', `Docker buildx ready (platforms: ${platforms})`);
+    logger.log('ok', `Docker buildx ready (builder: ${builderName}, platforms: ${platforms})`);
   }
 
   /**

ts/interfaces/index.ts

@@ -79,6 +79,9 @@ export interface IBuildCommandOptions {
   noCache?: boolean;    // Force rebuild without Docker layer cache (--no-cache)
   cached?: boolean;     // Skip builds when Dockerfile content hasn't changed
   verbose?: boolean;    // Stream raw docker build output (default: silent)
+  context?: string;      // Explicit Docker context name (--context flag)
+  parallel?: boolean;            // Enable parallel builds within dependency levels
+  parallelConcurrency?: number;  // Max concurrent builds per level (default 4)
 }
 
 export interface ICacheEntry {
@@ -92,3 +95,10 @@ export interface ICacheData {
   version: 1;
   entries: { [cleanTag: string]: ICacheEntry };
 }
+
+export interface IDockerContextInfo {
+  name: string;          // 'default', 'rootless', 'colima', etc.
+  endpoint: string;      // 'unix:///var/run/docker.sock'
+  isRootless: boolean;
+  dockerHost?: string;   // value of DOCKER_HOST env var, if set
+}

ts/tsdocker.cli.ts

@@ -33,7 +33,7 @@ export let run = () => {
     try {
       const config = await ConfigModule.run();
       const manager = new TsDockerManager(config);
-      await manager.prepare();
+      await manager.prepare(argvArg.context as string | undefined);
 
       const buildOptions: IBuildCommandOptions = {};
       const patterns = argvArg._.slice(1) as string[];
@@ -55,6 +55,12 @@ export let run = () => {
       if (argvArg.verbose) {
         buildOptions.verbose = true;
       }
+      if (argvArg.parallel) {
+        buildOptions.parallel = true;
+        if (typeof argvArg.parallel === 'number') {
+          buildOptions.parallelConcurrency = argvArg.parallel;
+        }
+      }
 
       await manager.build(buildOptions);
       logger.log('success', 'Build completed successfully');
@@ -72,7 +78,7 @@ export let run = () => {
     try {
       const config = await ConfigModule.run();
       const manager = new TsDockerManager(config);
-      await manager.prepare();
+      await manager.prepare(argvArg.context as string | undefined);
 
       // Login first
       await manager.login();
@@ -95,6 +101,12 @@ export let run = () => {
       if (argvArg.verbose) {
         buildOptions.verbose = true;
       }
+      if (argvArg.parallel) {
+        buildOptions.parallel = true;
+        if (typeof argvArg.parallel === 'number') {
+          buildOptions.parallelConcurrency = argvArg.parallel;
+        }
+      }
 
       // Build images first (if not already built)
       await manager.build(buildOptions);
@@ -124,7 +136,7 @@ export let run = () => {
 
       const config = await ConfigModule.run();
       const manager = new TsDockerManager(config);
-      await manager.prepare();
+      await manager.prepare(argvArg.context as string | undefined);
 
       // Login first
       await manager.login();
@@ -144,7 +156,7 @@ export let run = () => {
     try {
       const config = await ConfigModule.run();
       const manager = new TsDockerManager(config);
-      await manager.prepare();
+      await manager.prepare(argvArg.context as string | undefined);
 
       // Build images first
       const buildOptions: IBuildCommandOptions = {};
@@ -157,6 +169,12 @@ export let run = () => {
       if (argvArg.verbose) {
         buildOptions.verbose = true;
       }
+      if (argvArg.parallel) {
+        buildOptions.parallel = true;
+        if (typeof argvArg.parallel === 'number') {
+          buildOptions.parallelConcurrency = argvArg.parallel;
+        }
+      }
       await manager.build(buildOptions);
 
       // Run tests
@@ -175,7 +193,7 @@ export let run = () => {
     try {
       const config = await ConfigModule.run();
       const manager = new TsDockerManager(config);
-      await manager.prepare();
+      await manager.prepare(argvArg.context as string | undefined);
       await manager.login();
       logger.log('success', 'Login completed successfully');
     } catch (err) {
@@ -191,7 +209,7 @@ export let run = () => {
     try {
       const config = await ConfigModule.run();
       const manager = new TsDockerManager(config);
-      await manager.prepare();
+      await manager.prepare(argvArg.context as string | undefined);
       await manager.list();
     } catch (err) {
       logger.log('error', `List failed: ${(err as Error).message}`);