# tsdocker Project Hints

## Module Purpose

tsdocker is a comprehensive Docker development and building tool. It provides:
- Testing npm modules in clean Docker environments (legacy feature)
- Building Dockerfiles with dependency ordering
- Multi-registry push/pull support
- Multi-architecture builds (amd64/arm64)

## New CLI Commands (2026-01-19)

| Command | Description |
|---------|-------------|
| `tsdocker` | Run tests in container (legacy default behavior) |
| `tsdocker build` | Build all Dockerfiles with dependency ordering |
| `tsdocker push [registry]` | Push images to configured registries |
| `tsdocker pull <registry>` | Pull images from registry |
| `tsdocker test` | Run container tests (test scripts) |
| `tsdocker login` | Login to configured registries |
| `tsdocker list` | List discovered Dockerfiles and dependencies |
| `tsdocker clean --all` | Clean up Docker environment |
| `tsdocker vscode` | Start VS Code in Docker |

## Configuration

Configure in `package.json` under `@git.zone/tsdocker`:

```json
{
  "@git.zone/tsdocker": {
    "registries": ["registry.gitlab.com", "docker.io"],
    "registryRepoMap": {
      "registry.gitlab.com": "host.today/ht-docker-node"
    },
    "buildArgEnvMap": {
      "NODE_VERSION": "NODE_VERSION"
    },
    "platforms": ["linux/amd64", "linux/arm64"],
    "push": false,
    "testDir": "./test"
  }
}
```

### Configuration Options

- `baseImage`: Base Docker image for testing (legacy)
- `command`: Command to run in container (legacy)
- `dockerSock`: Mount Docker socket (legacy)
- `registries`: Array of registry URLs to push to
- `registryRepoMap`: Map registry URLs to different repo paths
- `buildArgEnvMap`: Map Docker build ARGs to environment variables
- `platforms`: Target architectures for buildx
- `push`: Auto-push after build
- `testDir`: Directory containing test scripts

## Registry Authentication

Set environment variables for registry login:

```bash
# Pipe-delimited format (numbered 1-10)
export DOCKER_REGISTRY_1="registry.gitlab.com|username|password"
export DOCKER_REGISTRY_2="docker.io|username|password"

# Or individual registry format
export DOCKER_REGISTRY_URL="registry.gitlab.com"
export DOCKER_REGISTRY_USER="username"
export DOCKER_REGISTRY_PASSWORD="password"
```

## File Structure

```
ts/
├── index.ts                      (entry point)
├── tsdocker.cli.ts               (CLI commands)
├── tsdocker.config.ts            (configuration)
├── tsdocker.plugins.ts           (plugin imports)
├── tsdocker.docker.ts            (legacy test runner)
├── tsdocker.snippets.ts          (Dockerfile generation)
├── classes.dockerfile.ts         (Dockerfile management)
├── classes.dockerregistry.ts     (registry authentication)
├── classes.registrystorage.ts    (registry storage)
├── classes.tsdockermanager.ts    (orchestrator)
└── interfaces/
    └── index.ts                  (type definitions)
```

## Dependencies

- `@push.rocks/lik`: Object mapping utilities
- `@push.rocks/smartfs`: Filesystem operations
- `@push.rocks/smartshell`: Shell command execution
- `@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).

## OCI Distribution API Push (v1.16+)

All builds now go through a persistent local registry (`localhost:5234`) with volume storage at `.nogit/docker-registry/`. Pushes use the `RegistryCopy` class (`ts/classes.registrycopy.ts`) which implements the OCI Distribution API to copy images (including multi-arch manifest lists) from the local registry to remote registries. This replaces the old `docker tag + docker push` approach that only worked for single-platform images.

Key classes:
- `RegistryCopy` — HTTP-based OCI image copy (auth, blob transfer, manifest handling)
- `Dockerfile.push()` — Now delegates to `RegistryCopy.copyImage()`
- `Dockerfile.needsLocalRegistry()` — Always returns true
- `Dockerfile.startLocalRegistry()` — Uses persistent volume mount

The `config.push` field is now a no-op (kept for backward compat).

## Build Status

- Build: ✅ Passes
- Legacy test functionality preserved
- New Docker build functionality added

## Previous Upgrades (2025-11-22)

- Updated all @git.zone/_ dependencies to @git.zone/_ scope
- Updated all @pushrocks/_ dependencies to @push.rocks/_ scope
- Migrated from smartfile v8 to smartfs v1.1.0