Add NerdctlClient for Finch and nerdctl support

[tinovyatkin]

Summary

This PR adds support for Finch and other nerdctl-based container runtimes, enabling the VS Code Docker extension to work with these alternative container engines.

• NerdctlClient - Configurable container client for nerdctl-based CLIs (Finch, nerdctl, etc.)
• NerdctlComposeClient - Compose support with overrides for nerdctl-specific limitations
• Event streaming - Handles containerd native event format with client-side filtering
• File operations - Read/write support using temp file workaround
• Full E2E test coverage - All operations tested and passing for Docker, Podman, and Finch

Architecture

Following reviewer feedback, the implementation uses a generic NerdctlClient with configurable command name rather than a Finch-specific client. This allows supporting any nerdctl-based CLI:

// For Finch
const finchClient = new NerdctlClient('finch', 'Finch', 'Runs container commands using the Finch CLI');

// For nerdctl directly
const nerdctlClient = new NerdctlClient(); // defaults to 'nerdctl'

What is Finch?

Finch is an open source tool for local container development, originally released by AWS in November 2022. It uses containerd and nerdctl under the hood.

Documentation:

• Finch Homepage & Docs
• Finch GitHub
• nerdctl (underlying CLI)

Key Implementation Details

containerd Native Events

Finch/nerdctl outputs containerd native events (NOT Docker-compatible):

{
  "Timestamp": "2026-01-10T23:38:26.737324778Z",
  "Topic": "/containers/create",
  "Event": "{\"id\":\"...\",\"image\":\"...\"}"
}

The client translates between these formats and performs client-side filtering since nerdctl doesn't support --since/--until flags.

Compose Limitations

NerdctlComposeClient overrides command generation to exclude unsupported flags:

• up: excludes --timeout, --no-start, --wait, --watch
• down: excludes --timeout
• config: only --services is supported (not --images, --profiles, --volumes)

File Operations Workaround

Nerdctl's cp command advertises stdin/stdout support (-) but it's not fully implemented. This PR uses a temp file workaround.

Test Results

All E2E tests pass for all three container clients:

Client	Passing	Pending
Docker	55	2
Podman	46	11
Finch	47	10

Test Coverage

• Container lifecycle (create, start, stop, remove, exec, attach, logs)
• Image operations (pull, build, tag, push, remove, inspect)
• Network and volume management
• File system operations (stat, read, write)
• Event streaming with containerd format parsing
• Compose operations (up, down, start, stop, restart, logs, config)

Known Limitations (reflected in pending tests)

• Context commands skipped (Docker-only feature)
• Some compose config options skipped for Podman/Finch (unsupported flags)
• Login/logout skipped (requires registry credentials)

🤖 Generated with Claude Code

[tinovyatkin]

@microsoft-github-policy-service agree

[bwateratmsft]

Given that Finch is basically just nerdctl, I think it would make more sense for this to be a nerdctl client, but with the ability to accept a different configured command name (i.e. finch instead of nerdctl). DockerClient supports something similar to this now, by way of accepting the base command to run as a constructor argument. This is primarily to allow users to set a specific absolute path instead of resolving docker from the PATH env var, but this same capability could be used for nerdctl vs finch.

nerdctl support has also been requested previously: microsoft/vscode-containers#119

Can you rename the classes/etc. accordingly?

[tinovyatkin]

Thanks @bwateratmsft! Great suggestion - you're right that Finch is essentially nerdctl under the hood.

I've refactored as suggested:

• Renamed FinchClient → NerdctlClient with configurable command name (defaults to 'nerdctl')
• Renamed FinchComposeClient → NerdctlComposeClient with the same pattern
• Updated all record schemas and related files accordingly

The client can now support any nerdctl-based CLI:

// For Finch
new NerdctlClient('finch', 'Finch', 'Runs container commands using the Finch CLI');

// For nerdctl directly  
new NerdctlClient(); // defaults to 'nerdctl'

I also added overrides in NerdctlComposeClient for compose flags that nerdctl doesn't support (--timeout for up/down, --no-start, --wait, --watch).

All E2E tests pass for Docker, Podman, and Finch.