@git.zone/tsdocker 2.0.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tsdocker",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "private": false,
   "description": "develop npm modules cross platform with docker",
   "main": "dist_ts/index.js",
@@ -27,22 +27,22 @@
   },
   "homepage": "https://gitlab.com/gitzone/tsdocker#readme",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.1.2",
+    "@git.zone/tsbuild": "^4.3.0",
     "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.1.6",
-    "@types/node": "^25.0.9"
+    "@git.zone/tstest": "^3.3.2",
+    "@types/node": "^25.5.0"
   },
   "dependencies": {
-    "@push.rocks/lik": "^6.2.2",
+    "@push.rocks/lik": "^6.3.1",
     "@push.rocks/npmextra": "^5.3.3",
     "@push.rocks/projectinfo": "^5.0.2",
     "@push.rocks/smartcli": "^4.0.20",
-    "@push.rocks/smartfs": "^1.3.1",
+    "@push.rocks/smartfs": "^1.5.0",
     "@push.rocks/smartinteract": "^2.0.16",
-    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/smartlog": "^3.2.1",
     "@push.rocks/smartlog-destination-local": "^9.0.2",
     "@push.rocks/smartlog-source-ora": "^1.0.9",
-    "@push.rocks/smartshell": "^3.3.0"
+    "@push.rocks/smartshell": "^3.3.7"
   },
   "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34",
   "type": "module",

package/readme.md

@@ -93,6 +93,7 @@ tsdocker push --no-build Dockerfile_api Dockerfile_web
 | `tsdocker test` | Build + run container test scripts (`test_*.sh`) |
 | `tsdocker login` | Authenticate with configured registries |
 | `tsdocker list` | Display discovered Dockerfiles and their dependencies |
+| `tsdocker config` | Manage global tsdocker configuration (remote builders, etc.) |
 | `tsdocker clean` | Interactively clean Docker environment |
 
 ### Build Flags
@@ -117,6 +118,24 @@ tsdocker push --no-build Dockerfile_api Dockerfile_web
 | `--registry=<url>` | Push to a single specific registry instead of all configured |
 | `--no-build` | Skip the build phase; only push existing images from local registry |
 
+### Config Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `add-builder` | Add or update a remote builder node |
+| `remove-builder` | Remove a remote builder by name |
+| `list-builders` | List all configured remote builders |
+| `show` | Show the full global configuration |
+
+**`add-builder` flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--name=<name>` | Builder name (e.g. `arm64-builder`) |
+| `--host=<user@ip>` | SSH host (e.g. `armbuilder@192.168.1.100`) |
+| `--platform=<p>` | Target platform (e.g. `linux/arm64`) |
+| `--ssh-key=<path>` | SSH key path (optional, uses SSH agent/config by default) |
+
 ### Clean Flags
 
 | Flag | Description |
@@ -294,6 +313,51 @@ tsdocker automatically:
 - Pushes multi-platform images to the local registry via `buildx --push`
 - Copies the full manifest list (including all platform variants) to remote registries on `tsdocker push`
 
+### 🖥️ Native Remote Builders
+
+Instead of relying on slow QEMU emulation for cross-platform builds, tsdocker can use **native remote machines** via SSH as build nodes. For example, use a real arm64 machine for `linux/arm64` builds:
+
+```bash
+# Add a remote arm64 builder
+tsdocker config add-builder \
+  --name=arm64-builder \
+  --host=armbuilder@192.168.1.100 \
+  --platform=linux/arm64 \
+  --ssh-key=~/.ssh/id_ed25519
+
+# List configured builders
+tsdocker config list-builders
+
+# Remove a builder
+tsdocker config remove-builder --name=arm64-builder
+
+# Show full global config
+tsdocker config show
+```
+
+Global configuration is stored at `~/.git.zone/tsdocker/config.json`.
+
+**How it works:**
+
+When remote builders are configured and the project's `platforms` includes a matching platform, tsdocker automatically:
+
+1. Creates a **multi-node buildx builder** — local node for `linux/amd64`, remote SSH node for `linux/arm64`
+2. Opens **SSH reverse tunnels** so the remote builder can push to the local staging registry
+3. Builds natively on each platform's hardware — no QEMU overhead
+4. Tears down tunnels after the build completes
+
+```
+[Local machine]                        [Remote arm64 machine]
+  registry:2 on localhost:PORT  <──── SSH reverse tunnel ──── localhost:PORT
+  BuildKit (amd64) ──push──>            BuildKit (arm64) ──push──>
+     localhost:PORT                        localhost:PORT (tunneled)
+```
+
+**Prerequisites for the remote machine:**
+- Docker installed and running
+- A user with Docker group access (no sudo needed)
+- SSH key access configured
+
 ### ⚡ Parallel Builds
 
 Speed up builds by building independent images concurrently:

package/ts/00_commitinfo_data.ts

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

package/ts/classes.dockerfile.ts

@@ -266,12 +266,15 @@ export class Dockerfile {
   public static async buildDockerfiles(
     sortedArrayArg: Dockerfile[],
     session: TsDockerSession,
-    options?: { platform?: string; timeout?: number; noCache?: boolean; verbose?: boolean; isRootless?: boolean; parallel?: boolean; parallelConcurrency?: number },
+    options?: { platform?: string; timeout?: number; noCache?: boolean; pull?: boolean; verbose?: boolean; isRootless?: boolean; parallel?: boolean; parallelConcurrency?: number; onRegistryStarted?: () => Promise<void>; onBeforeRegistryStop?: () => Promise<void> },
   ): Promise<Dockerfile[]> {
     const total = sortedArrayArg.length;
     const overallStart = Date.now();
 
     await Dockerfile.startLocalRegistry(session, options?.isRootless);
+    if (options?.onRegistryStarted) {
+      await options.onRegistryStarted();
+    }
 
     try {
       if (options?.parallel) {
@@ -351,6 +354,9 @@ export class Dockerfile {
         }
       }
     } finally {
+      if (options?.onBeforeRegistryStop) {
+        await options.onBeforeRegistryStop();
+      }
       await Dockerfile.stopLocalRegistry(session);
     }
 
@@ -662,13 +668,14 @@ export class Dockerfile {
   /**
    * Builds the Dockerfile
    */
-  public async build(options?: { platform?: string; timeout?: number; noCache?: boolean; verbose?: boolean }): Promise<number> {
+  public async build(options?: { platform?: string; timeout?: number; noCache?: boolean; pull?: boolean; verbose?: boolean }): Promise<number> {
     const startTime = Date.now();
     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' : '';
+    const pullFlag = options?.pull !== false ? ' --pull' : '';
     const verbose = options?.verbose ?? false;
 
     let buildContextFlag = '';
@@ -683,23 +690,24 @@ export class Dockerfile {
     }
 
     let buildCommand: string;
+    const builderFlag = this.managerRef.currentBuilderName ? ` --builder ${this.managerRef.currentBuilderName}` : '';
 
     if (platformOverride) {
       // Single platform override via buildx
-      buildCommand = `docker buildx build --progress=plain --platform ${platformOverride}${noCacheFlag}${buildContextFlag} --load -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
+      buildCommand = `docker buildx build${builderFlag} --progress=plain --platform ${platformOverride}${noCacheFlag}${pullFlag}${buildContextFlag} --load -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
       logger.log('info', `Build: buildx --platform ${platformOverride} --load`);
     } else if (config.platforms && config.platforms.length > 1) {
       // Multi-platform build using buildx — always push to local registry
       const platformString = config.platforms.join(',');
       const registryHost = this.session?.config.registryHost || 'localhost:5234';
       const localTag = `${registryHost}/${this.buildTag}`;
-      buildCommand = `docker buildx build --progress=plain --platform ${platformString}${noCacheFlag}${buildContextFlag} -t ${localTag} -f ${this.filePath} ${buildArgsString} --push .`;
+      buildCommand = `docker buildx build${builderFlag} --progress=plain --platform ${platformString}${noCacheFlag}${pullFlag}${buildContextFlag} -t ${localTag} -f ${this.filePath} ${buildArgsString} --push .`;
       this.localRegistryTag = localTag;
       logger.log('info', `Build: buildx --platform ${platformString} --push to local registry`);
     } else {
       // Standard build
       const versionLabel = this.managerRef.projectInfo?.npm?.version || 'unknown';
-      buildCommand = `docker build --progress=plain --label="version=${versionLabel}"${noCacheFlag} -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
+      buildCommand = `docker build --progress=plain --label="version=${versionLabel}"${noCacheFlag}${pullFlag} -t ${this.buildTag} -f ${this.filePath} ${buildArgsString} .`;
       logger.log('info', 'Build: docker build (standard)');
     }
 

package/ts/classes.globalconfig.ts

@@ -0,0 +1,76 @@
+import * as fs from 'fs';
+import * as plugins from './tsdocker.plugins.js';
+import { logger } from './tsdocker.logging.js';
+import type { IGlobalConfig, IRemoteBuilder } from './interfaces/index.js';
+
+const CONFIG_DIR = plugins.path.join(
+  process.env.HOME || process.env.USERPROFILE || '~',
+  '.git.zone',
+  'tsdocker',
+);
+const CONFIG_PATH = plugins.path.join(CONFIG_DIR, 'config.json');
+
+const DEFAULT_CONFIG: IGlobalConfig = {
+  remoteBuilders: [],
+};
+
+export class GlobalConfig {
+  static getConfigPath(): string {
+    return CONFIG_PATH;
+  }
+
+  static load(): IGlobalConfig {
+    try {
+      const raw = fs.readFileSync(CONFIG_PATH, 'utf-8');
+      const parsed = JSON.parse(raw);
+      return {
+        ...DEFAULT_CONFIG,
+        ...parsed,
+      };
+    } catch {
+      return { ...DEFAULT_CONFIG };
+    }
+  }
+
+  static save(config: IGlobalConfig): void {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  }
+
+  static addBuilder(builder: IRemoteBuilder): void {
+    const config = GlobalConfig.load();
+    const existing = config.remoteBuilders.findIndex((b) => b.name === builder.name);
+    if (existing >= 0) {
+      config.remoteBuilders[existing] = builder;
+      logger.log('info', `Updated remote builder: ${builder.name}`);
+    } else {
+      config.remoteBuilders.push(builder);
+      logger.log('info', `Added remote builder: ${builder.name}`);
+    }
+    GlobalConfig.save(config);
+  }
+
+  static removeBuilder(name: string): void {
+    const config = GlobalConfig.load();
+    const before = config.remoteBuilders.length;
+    config.remoteBuilders = config.remoteBuilders.filter((b) => b.name !== name);
+    if (config.remoteBuilders.length < before) {
+      logger.log('info', `Removed remote builder: ${name}`);
+    } else {
+      logger.log('warn', `Remote builder not found: ${name}`);
+    }
+    GlobalConfig.save(config);
+  }
+
+  static getBuilders(): IRemoteBuilder[] {
+    return GlobalConfig.load().remoteBuilders;
+  }
+
+  /**
+   * Returns remote builders that match any of the requested platforms
+   */
+  static getBuildersForPlatforms(platforms: string[]): IRemoteBuilder[] {
+    const builders = GlobalConfig.getBuilders();
+    return builders.filter((b) => platforms.includes(b.platform));
+  }
+}

package/ts/classes.sshtunnel.ts

@@ -0,0 +1,77 @@
+import * as plugins from './tsdocker.plugins.js';
+import { logger } from './tsdocker.logging.js';
+import type { IRemoteBuilder } from './interfaces/index.js';
+
+const smartshellInstance = new plugins.smartshell.Smartshell({
+  executor: 'bash',
+});
+
+/**
+ * Manages SSH reverse tunnels for remote builder nodes.
+ * Opens tunnels so that the local staging registry (localhost:<port>)
+ * is accessible as localhost:<port> on each remote machine.
+ */
+export class SshTunnelManager {
+  private tunnelPids: number[] = [];
+
+  /**
+   * Opens a reverse SSH tunnel to make localPort accessible on the remote machine.
+   * ssh -f -N -o StrictHostKeyChecking=no -o ExitOnForwardFailure=yes
+   *     -R <localPort>:localhost:<localPort> [-i keyPath] user@host
+   */
+  async openTunnel(builder: IRemoteBuilder, localPort: number): Promise<void> {
+    const keyOpt = builder.sshKeyPath ? `-i ${builder.sshKeyPath} ` : '';
+    const cmd = [
+      'ssh -f -N',
+      '-o StrictHostKeyChecking=no',
+      '-o ExitOnForwardFailure=yes',
+      `-R ${localPort}:localhost:${localPort}`,
+      `${keyOpt}${builder.host}`,
+    ].join(' ');
+
+    logger.log('info', `Opening SSH tunnel to ${builder.host} for port ${localPort}...`);
+    const result = await smartshellInstance.exec(cmd);
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Failed to open SSH tunnel to ${builder.host}: ${result.stderr || 'unknown error'}`
+      );
+    }
+
+    // Find the PID of the tunnel process we just started
+    const pidResult = await smartshellInstance.exec(
+      `pgrep -f "ssh.*-R ${localPort}:localhost:${localPort}.*${builder.host}" | tail -1`
+    );
+    if (pidResult.exitCode === 0 && pidResult.stdout.trim()) {
+      const pid = parseInt(pidResult.stdout.trim(), 10);
+      if (!isNaN(pid)) {
+        this.tunnelPids.push(pid);
+        logger.log('ok', `SSH tunnel to ${builder.host} established (PID ${pid})`);
+      }
+    }
+  }
+
+  /**
+   * Opens tunnels for all provided remote builders
+   */
+  async openTunnels(builders: IRemoteBuilder[], localPort: number): Promise<void> {
+    for (const builder of builders) {
+      await this.openTunnel(builder, localPort);
+    }
+  }
+
+  /**
+   * Closes all tunnel processes
+   */
+  async closeAll(): Promise<void> {
+    for (const pid of this.tunnelPids) {
+      try {
+        process.kill(pid, 'SIGTERM');
+        logger.log('info', `Closed SSH tunnel (PID ${pid})`);
+      } catch {
+        // Process may have already exited
+      }
+    }
+    this.tunnelPids = [];
+  }
+}

package/ts/classes.tsdockermanager.ts

@@ -8,7 +8,9 @@ import { TsDockerCache } from './classes.tsdockercache.js';
 import { DockerContext } from './classes.dockercontext.js';
 import { TsDockerSession } from './classes.tsdockersession.js';
 import { RegistryCopy } from './classes.registrycopy.js';
-import type { ITsDockerConfig, IBuildCommandOptions } from './interfaces/index.js';
+import { GlobalConfig } from './classes.globalconfig.js';
+import { SshTunnelManager } from './classes.sshtunnel.js';
+import type { ITsDockerConfig, IBuildCommandOptions, IRemoteBuilder } from './interfaces/index.js';
 
 const smartshellInstance = new plugins.smartshell.Smartshell({
   executor: 'bash',
@@ -23,7 +25,10 @@ export class TsDockerManager {
   public projectInfo: any;
   public dockerContext: DockerContext;
   public session!: TsDockerSession;
+  public currentBuilderName?: string;
   private dockerfiles: Dockerfile[] = [];
+  private activeRemoteBuilders: IRemoteBuilder[] = [];
+  private sshTunnelManager?: SshTunnelManager;
 
   constructor(config: ITsDockerConfig) {
     this.config = config;
@@ -235,6 +240,7 @@ export class TsDockerManager {
       const total = toBuild.length;
       const overallStart = Date.now();
       await Dockerfile.startLocalRegistry(this.session, this.dockerContext.contextInfo?.isRootless);
+      await this.openRemoteTunnels();
 
       try {
         if (options?.parallel) {
@@ -261,6 +267,7 @@ export class TsDockerManager {
                     platform: options?.platform,
                     timeout: options?.timeout,
                     noCache: options?.noCache,
+                    pull: options?.pull,
                     verbose: options?.verbose,
                   });
                   logger.log('ok', `${progress} Built ${df.cleanTag} in ${formatDuration(elapsed)}`);
@@ -306,6 +313,7 @@ export class TsDockerManager {
                 platform: options?.platform,
                 timeout: options?.timeout,
                 noCache: options?.noCache,
+                pull: options?.pull,
                 verbose: options?.verbose,
               });
               logger.log('ok', `${progress} Built ${dockerfileArg.cleanTag} in ${formatDuration(elapsed)}`);
@@ -332,6 +340,7 @@ export class TsDockerManager {
           }
         }
       } finally {
+        await this.closeRemoteTunnels();
         await Dockerfile.stopLocalRegistry(this.session);
       }
 
@@ -343,10 +352,13 @@ export class TsDockerManager {
         platform: options?.platform,
         timeout: options?.timeout,
         noCache: options?.noCache,
+        pull: options?.pull,
         verbose: options?.verbose,
         isRootless: this.dockerContext.contextInfo?.isRootless,
         parallel: options?.parallel,
         parallelConcurrency: options?.parallelConcurrency,
+        onRegistryStarted: () => this.openRemoteTunnels(),
+        onBeforeRegistryStop: () => this.closeRemoteTunnels(),
       });
     }
 
@@ -373,35 +385,120 @@ export class TsDockerManager {
   }
 
   /**
-   * Ensures Docker buildx is set up for multi-architecture builds
+   * Ensures Docker buildx is set up for multi-architecture builds.
+   * When remote builders are configured in the global config, creates a multi-node
+   * builder with native nodes instead of relying on QEMU emulation.
    */
   private async ensureBuildx(): Promise<void> {
     const builderName = this.dockerContext.getBuilderName() + (this.session?.config.builderSuffix || '');
     const platforms = this.config.platforms?.join(', ') || 'default';
     logger.log('info', `Setting up Docker buildx [${platforms}]...`);
     logger.log('info', `Builder: ${builderName}`);
+
+    // Check for remote builders matching our target platforms
+    const requestedPlatforms = this.config.platforms || ['linux/amd64'];
+    const remoteBuilders = GlobalConfig.getBuildersForPlatforms(requestedPlatforms);
+
+    if (remoteBuilders.length > 0) {
+      await this.ensureBuildxWithRemoteNodes(builderName, requestedPlatforms, remoteBuilders);
+    } else {
+      await this.ensureBuildxLocal(builderName);
+    }
+
+    this.currentBuilderName = builderName;
+    logger.log('ok', `Docker buildx ready (builder: ${builderName}, platforms: ${platforms})`);
+  }
+
+  /**
+   * Creates a multi-node buildx builder with local + remote SSH nodes.
+   */
+  private async ensureBuildxWithRemoteNodes(
+    builderName: string,
+    requestedPlatforms: string[],
+    remoteBuilders: IRemoteBuilder[],
+  ): Promise<void> {
+    const remotePlatforms = new Set(remoteBuilders.map((b) => b.platform));
+    const localPlatforms = requestedPlatforms.filter((p) => !remotePlatforms.has(p));
+
+    logger.log('info', `Remote builders: ${remoteBuilders.map((b) => `${b.name} (${b.platform} @ ${b.host})`).join(', ')}`);
+    if (localPlatforms.length > 0) {
+      logger.log('info', `Local platforms: ${localPlatforms.join(', ')}`);
+    }
+
+    // Always recreate the builder to ensure correct node topology
+    await smartshellInstance.execSilent(`docker buildx rm ${builderName} 2>/dev/null || true`);
+
+    // Create the local node
+    const localPlatformFlag = localPlatforms.length > 0 ? ` --platform ${localPlatforms.join(',')}` : '';
+    await smartshellInstance.exec(
+      `docker buildx create --name ${builderName} --driver docker-container --driver-opt network=host${localPlatformFlag}`
+    );
+
+    // Append remote nodes
+    for (const builder of remoteBuilders) {
+      logger.log('info', `Appending remote node: ${builder.name} (${builder.platform}) via ssh://${builder.host}`);
+      const appendResult = await smartshellInstance.exec(
+        `docker buildx create --append --name ${builderName} --driver docker-container --driver-opt network=host --platform ${builder.platform} --node ${builder.name} ssh://${builder.host}`
+      );
+      if (appendResult.exitCode !== 0) {
+        throw new Error(`Failed to append remote builder ${builder.name}: ${appendResult.stderr}`);
+      }
+    }
+
+    // Bootstrap all nodes
+    await smartshellInstance.exec(`docker buildx inspect --builder ${builderName} --bootstrap`);
+
+    // Store active remote builders for SSH tunnel setup during build
+    this.activeRemoteBuilders = remoteBuilders;
+  }
+
+  /**
+   * Creates a single-node local buildx builder (original behavior, uses QEMU for cross-platform).
+   */
+  private async ensureBuildxLocal(builderName: string): Promise<void> {
     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 ${builderName} --driver docker-container --driver-opt network=host --use`
+        `docker buildx create --name ${builderName} --driver docker-container --driver-opt network=host`
       );
-      await smartshellInstance.exec('docker buildx inspect --bootstrap');
+      await smartshellInstance.exec(`docker buildx inspect --builder ${builderName} --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 ${builderName} 2>/dev/null`);
         await smartshellInstance.exec(
-          `docker buildx create --name ${builderName} --driver docker-container --driver-opt network=host --use`
+          `docker buildx create --name ${builderName} --driver docker-container --driver-opt network=host`
         );
-        await smartshellInstance.exec('docker buildx inspect --bootstrap');
-      } else {
-        await smartshellInstance.exec(`docker buildx use ${builderName}`);
+        await smartshellInstance.exec(`docker buildx inspect --builder ${builderName} --bootstrap`);
       }
     }
-    logger.log('ok', `Docker buildx ready (builder: ${builderName}, platforms: ${platforms})`);
+    this.activeRemoteBuilders = [];
+  }
+
+  /**
+   * Opens SSH reverse tunnels for remote builders so they can reach the local registry.
+   */
+  private async openRemoteTunnels(): Promise<void> {
+    if (this.activeRemoteBuilders.length === 0) return;
+
+    this.sshTunnelManager = new SshTunnelManager();
+    await this.sshTunnelManager.openTunnels(
+      this.activeRemoteBuilders,
+      this.session.config.registryPort,
+    );
+  }
+
+  /**
+   * Closes any active SSH tunnels.
+   */
+  private async closeRemoteTunnels(): Promise<void> {
+    if (this.sshTunnelManager) {
+      await this.sshTunnelManager.closeAll();
+      this.sshTunnelManager = undefined;
+    }
   }
 
   /**

package/ts/classes.tsdockersession.ts

@@ -4,6 +4,7 @@ import { logger } from './tsdocker.logging.js';
 
 export interface ISessionConfig {
   sessionId: string;
+  projectHash: string;
   registryPort: number;
   registryHost: string;
   registryContainerName: string;
@@ -17,8 +18,8 @@ export interface ISessionConfig {
  * Generates unique ports, container names, and builder names so that
  * concurrent CI jobs on the same Docker host don't collide.
  *
- * In local (non-CI) dev the builder suffix is empty, preserving the
- * persistent builder behavior.
+ * In local (non-CI) dev the builder suffix contains a project hash so
+ * that concurrent runs in different project directories use separate builders.
  */
 export class TsDockerSession {
   public config: ISessionConfig;
@@ -34,16 +35,18 @@ export class TsDockerSession {
   public static async create(): Promise<TsDockerSession> {
     const sessionId =
       process.env.TSDOCKER_SESSION_ID || crypto.randomBytes(4).toString('hex');
+    const projectHash = crypto.createHash('sha256').update(process.cwd()).digest('hex').substring(0, 8);
 
     const registryPort = await TsDockerSession.allocatePort();
     const registryHost = `localhost:${registryPort}`;
     const registryContainerName = `tsdocker-registry-${sessionId}`;
 
     const { isCI, ciSystem } = TsDockerSession.detectCI();
-    const builderSuffix = isCI ? `-${sessionId}` : '';
+    const builderSuffix = isCI ? `-${projectHash}-${sessionId}` : `-${projectHash}`;
 
     const config: ISessionConfig = {
       sessionId,
+      projectHash,
       registryPort,
       registryHost,
       registryContainerName,
@@ -99,9 +102,10 @@ export class TsDockerSession {
     logger.log('info', '=== TSDOCKER SESSION ===');
     logger.log('info', `Session ID:     ${c.sessionId}`);
     logger.log('info', `Registry:       ${c.registryHost} (container: ${c.registryContainerName})`);
+    logger.log('info', `Project hash:   ${c.projectHash}`);
+    logger.log('info', `Builder suffix: ${c.builderSuffix}`);
     if (c.isCI) {
       logger.log('info', `CI detected:    ${c.ciSystem}`);
-      logger.log('info', `Builder suffix: ${c.builderSuffix}`);
     }
   }
 }

package/ts/interfaces/index.ts

@@ -69,6 +69,7 @@ export interface IBuildCommandOptions {
   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)
+  pull?: boolean;       // Pull fresh base images before building (default: true)
   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)
@@ -95,3 +96,20 @@ export interface IDockerContextInfo {
   dockerHost?: string;   // value of DOCKER_HOST env var, if set
   topology?: 'socket-mount' | 'dind' | 'local';
 }
+
+/**
+ * A remote builder node for native cross-platform builds
+ */
+export interface IRemoteBuilder {
+  name: string;        // e.g., "arm64-builder"
+  host: string;        // e.g., "armbuilder@192.168.190.216"
+  platform: string;    // e.g., "linux/arm64"
+  sshKeyPath?: string; // e.g., "~/.ssh/id_ed25519"
+}
+
+/**
+ * Global tsdocker configuration stored at ~/.git.zone/tsdocker/config.json
+ */
+export interface IGlobalConfig {
+  remoteBuilders: IRemoteBuilder[];
+}