docker2wslc 0.1.0__tar.gz

docker2wslc-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.vscode-test/
+*.vsix
+.DS_Store
+*.log
+.env

docker2wslc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WSL Containers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docker2wslc-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: docker2wslc
+Version: 0.1.0
+Summary: Translate Docker commands and Compose files to wslc, the native WSL container runtime
+Project-URL: Homepage, https://wslcontainers.com
+Project-URL: Documentation, https://wslcontainers.com/reference/cheatsheet/
+Project-URL: Repository, https://github.com/ylwl1997/docker2wslc
+Project-URL: Issues, https://github.com/ylwl1997/docker2wslc/issues
+Author: WSL Containers
+License: MIT
+License-File: LICENSE
+Keywords: compose,containers,devcontainer,docker,windows,wsl,wslc
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# docker2wslc
+
+Translate Docker commands, Compose files and dev container configs to
+[**wslc**](https://wslcontainers.com) — the native Linux container runtime built into the
+Windows Subsystem for Linux, which runs containers on Windows 11 without Docker Desktop.
+
+No network calls, no daemon, no telemetry. Pure rule-driven translation.
+
+```bash
+pip install docker2wslc          # translation only
+pip install 'docker2wslc[yaml]'  # + Compose analysis
+```
+
+## Convert a command
+
+```console
+$ docker2wslc convert docker run --gpus all --restart always -p 8080:80 nginx
+wslc run --device nvidia.com/gpu=all -p 8080:80 nginx
+
+Migration notes
+  WARN  Restart policies are not implemented in the wslc preview. Flag dropped — use a
+        Windows scheduled task or a wrapper script for auto-restart.
+  INFO  GPU access in wslc goes through the Container Device Interface. Use
+        `--device nvidia.com/gpu=all` instead of `--gpus`.
+```
+
+Commands come from arguments, a file, or stdin:
+
+```bash
+docker2wslc convert docker ps -a
+docker2wslc convert --file deploy.sh
+cat deploy.sh | docker2wslc convert
+```
+
+## Analyse a Compose file
+
+wslc has **no Compose runtime**. This turns each service into an equivalent `wslc run`
+and tells you exactly what cannot be carried over:
+
+```console
+$ docker2wslc compose docker-compose.yml
+# wslc has no Compose runtime. Equivalent commands:
+
+wslc volume create pgdata
+wslc network create backend
+
+# service: web
+wslc run -d --name web -e NGINX_HOST=localhost -p 8080:80 --network backend nginx:alpine
+  x depends_on: No dependency ordering. Start services in order yourself and add readiness waits.
+  x restart: No restart policies in the wslc preview.
+
+# service: db
+wslc run -d --name db -v pgdata:/var/lib/postgresql/data postgres:16-alpine
+  x healthcheck: wslc has no healthcheck support; depends_on conditions relying on it cannot work.
+```
+
+## Lint a repository
+
+Scans for `docker-compose.y*ml`, `compose.y*ml` and `devcontainer.json`:
+
+```bash
+docker2wslc lint .
+```
+
+## Use in CI
+
+Exit codes are meaningful, so this works as a gate:
+
+| Code | Meaning |
+|------|---------|
+| `0` | Fully compatible |
+| `1` | Degraded — flags dropped or rewritten, still runnable |
+| `2` | Unmigratable — Compose, Swarm, buildx, or a parse failure |
+
+```yaml
+- run: pip install 'docker2wslc[yaml]'
+- run: docker2wslc lint .        # fails the job on exit 2
+```
+
+## Python API
+
+```python
+from docker2wslc import translate, analyse
+
+result = translate("docker run --platform linux/amd64 -it ubuntu bash")
+print(result.output)      # wslc run -it ubuntu bash
+print(result.exit_code)   # 1
+for note in result.notes:
+    print(note.severity, note.text)
+
+report = analyse(open("docker-compose.yml").read())
+print(report.as_dict())
+```
+
+`--json` on any subcommand gives the same structure for shell pipelines.
+
+## What wslc cannot do
+
+Worth knowing before you migrate. These are runtime limitations, not gaps in this tool:
+
+- **No Compose runtime** — translate services by hand, see the [migration guide](https://wslcontainers.com/guides/compose/)
+- **No restart policies** — use a scheduled task
+- **No `--platform`** — host architecture only
+- **No healthchecks** — so `depends_on` conditions cannot work
+- **No Docker socket or Engine API** — [Testcontainers, Portainer and act cannot attach](https://wslcontainers.com/guides/testcontainers/)
+- **No buildx / bake** — single-platform `wslc build` only
+- **GPU via CDI** — `--device nvidia.com/gpu=all`, not `--gpus all`
+
+CLI-driven tooling ports to wslc. API-driven tooling does not. That single distinction
+explains most migration surprises — including why
+[VS Code Dev Containers *does* work](https://wslcontainers.com/guides/vscode-dev-containers/)
+once you set `dev.containers.dockerPath` to `wslc`.
+
+## Docs
+
+- Interactive converter — <https://wslcontainers.com>
+- Command cheat sheet — <https://wslcontainers.com/reference/cheatsheet/>
+- Install guide — <https://wslcontainers.com/guides/install/>
+- wslc vs Docker Desktop — <https://wslcontainers.com/guides/vs-docker-desktop/>
+
+## Accuracy
+
+Rules target the **2026-07 wslc public preview** and live in a single
+[`rules.json`](https://github.com/ylwl1997/docker2wslc/blob/main/rules.json) shared by the
+Python package, the npm CLI, the MCP server and the VS Code extension. wslc is a moving
+target; if you hit a mapping that is wrong,
+[open an issue](https://github.com/ylwl1997/docker2wslc/issues) with the command and the
+actual `wslc` output.
+
+MIT licensed.

docker2wslc-0.1.0/README.md

@@ -0,0 +1,130 @@
+# docker2wslc
+
+Translate Docker commands, Compose files and dev container configs to
+[**wslc**](https://wslcontainers.com) — the native Linux container runtime built into the
+Windows Subsystem for Linux, which runs containers on Windows 11 without Docker Desktop.
+
+No network calls, no daemon, no telemetry. Pure rule-driven translation.
+
+```bash
+pip install docker2wslc          # translation only
+pip install 'docker2wslc[yaml]'  # + Compose analysis
+```
+
+## Convert a command
+
+```console
+$ docker2wslc convert docker run --gpus all --restart always -p 8080:80 nginx
+wslc run --device nvidia.com/gpu=all -p 8080:80 nginx
+
+Migration notes
+  WARN  Restart policies are not implemented in the wslc preview. Flag dropped — use a
+        Windows scheduled task or a wrapper script for auto-restart.
+  INFO  GPU access in wslc goes through the Container Device Interface. Use
+        `--device nvidia.com/gpu=all` instead of `--gpus`.
+```
+
+Commands come from arguments, a file, or stdin:
+
+```bash
+docker2wslc convert docker ps -a
+docker2wslc convert --file deploy.sh
+cat deploy.sh | docker2wslc convert
+```
+
+## Analyse a Compose file
+
+wslc has **no Compose runtime**. This turns each service into an equivalent `wslc run`
+and tells you exactly what cannot be carried over:
+
+```console
+$ docker2wslc compose docker-compose.yml
+# wslc has no Compose runtime. Equivalent commands:
+
+wslc volume create pgdata
+wslc network create backend
+
+# service: web
+wslc run -d --name web -e NGINX_HOST=localhost -p 8080:80 --network backend nginx:alpine
+  x depends_on: No dependency ordering. Start services in order yourself and add readiness waits.
+  x restart: No restart policies in the wslc preview.
+
+# service: db
+wslc run -d --name db -v pgdata:/var/lib/postgresql/data postgres:16-alpine
+  x healthcheck: wslc has no healthcheck support; depends_on conditions relying on it cannot work.
+```
+
+## Lint a repository
+
+Scans for `docker-compose.y*ml`, `compose.y*ml` and `devcontainer.json`:
+
+```bash
+docker2wslc lint .
+```
+
+## Use in CI
+
+Exit codes are meaningful, so this works as a gate:
+
+| Code | Meaning |
+|------|---------|
+| `0` | Fully compatible |
+| `1` | Degraded — flags dropped or rewritten, still runnable |
+| `2` | Unmigratable — Compose, Swarm, buildx, or a parse failure |
+
+```yaml
+- run: pip install 'docker2wslc[yaml]'
+- run: docker2wslc lint .        # fails the job on exit 2
+```
+
+## Python API
+
+```python
+from docker2wslc import translate, analyse
+
+result = translate("docker run --platform linux/amd64 -it ubuntu bash")
+print(result.output)      # wslc run -it ubuntu bash
+print(result.exit_code)   # 1
+for note in result.notes:
+    print(note.severity, note.text)
+
+report = analyse(open("docker-compose.yml").read())
+print(report.as_dict())
+```
+
+`--json` on any subcommand gives the same structure for shell pipelines.
+
+## What wslc cannot do
+
+Worth knowing before you migrate. These are runtime limitations, not gaps in this tool:
+
+- **No Compose runtime** — translate services by hand, see the [migration guide](https://wslcontainers.com/guides/compose/)
+- **No restart policies** — use a scheduled task
+- **No `--platform`** — host architecture only
+- **No healthchecks** — so `depends_on` conditions cannot work
+- **No Docker socket or Engine API** — [Testcontainers, Portainer and act cannot attach](https://wslcontainers.com/guides/testcontainers/)
+- **No buildx / bake** — single-platform `wslc build` only
+- **GPU via CDI** — `--device nvidia.com/gpu=all`, not `--gpus all`
+
+CLI-driven tooling ports to wslc. API-driven tooling does not. That single distinction
+explains most migration surprises — including why
+[VS Code Dev Containers *does* work](https://wslcontainers.com/guides/vscode-dev-containers/)
+once you set `dev.containers.dockerPath` to `wslc`.
+
+## Docs
+
+- Interactive converter — <https://wslcontainers.com>
+- Command cheat sheet — <https://wslcontainers.com/reference/cheatsheet/>
+- Install guide — <https://wslcontainers.com/guides/install/>
+- wslc vs Docker Desktop — <https://wslcontainers.com/guides/vs-docker-desktop/>
+
+## Accuracy
+
+Rules target the **2026-07 wslc public preview** and live in a single
+[`rules.json`](https://github.com/ylwl1997/docker2wslc/blob/main/rules.json) shared by the
+Python package, the npm CLI, the MCP server and the VS Code extension. wslc is a moving
+target; if you hit a mapping that is wrong,
+[open an issue](https://github.com/ylwl1997/docker2wslc/issues) with the command and the
+actual `wslc` output.
+
+MIT licensed.

docker2wslc-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "docker2wslc"
+version = "0.1.0"
+description = "Translate Docker commands and Compose files to wslc, the native WSL container runtime"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "WSL Containers" }]
+keywords = ["docker", "wsl", "wslc", "containers", "windows", "compose", "devcontainer"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = []
+
+[project.optional-dependencies]
+yaml = ["PyYAML>=6.0"]
+
+[project.urls]
+Homepage = "https://wslcontainers.com"
+Documentation = "https://wslcontainers.com/reference/cheatsheet/"
+Repository = "https://github.com/ylwl1997/docker2wslc"
+Issues = "https://github.com/ylwl1997/docker2wslc/issues"
+
+[project.scripts]
+docker2wslc = "docker2wslc.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docker2wslc"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "README.md", "LICENSE"]

docker2wslc-0.1.0/src/docker2wslc/__init__.py

@@ -0,0 +1,21 @@
+"""docker2wslc — translate Docker commands and Compose files to wslc.
+
+wslc is the native Linux container runtime in the Windows Subsystem for Linux.
+Docs and an interactive converter: https://wslcontainers.com
+"""
+
+__version__ = "0.1.0"
+
+from .compose import ComposeReport, analyse
+from .translate import Note, Result, load_rules, translate, translate_line
+
+__all__ = [
+    "__version__",
+    "translate",
+    "translate_line",
+    "analyse",
+    "load_rules",
+    "Result",
+    "Note",
+    "ComposeReport",
+]

docker2wslc-0.1.0/src/docker2wslc/cli.py

@@ -0,0 +1,233 @@
+"""docker2wslc command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .compose import analyse
+from .translate import RULES, translate
+
+SITE = RULES["links"]["site"]
+
+C = {
+    "reset": "\033[0m", "dim": "\033[2m", "bold": "\033[1m",
+    "red": "\033[31m", "yellow": "\033[33m", "cyan": "\033[36m", "green": "\033[32m",
+}
+
+
+def _paint(enabled: bool):
+    if enabled:
+        return lambda s, c: f"{C[c]}{s}{C['reset']}"
+    return lambda s, c: s
+
+
+def _read(source: str | None) -> str:
+    if source in (None, "-"):
+        return sys.stdin.read()
+    return Path(source).read_text(encoding="utf-8")
+
+
+SEV_COLOR = {"error": "red", "warn": "yellow", "info": "cyan"}
+
+
+def cmd_convert(args: argparse.Namespace) -> int:
+    text = " ".join(args.command) if args.command else _read(args.file)
+    res = translate(text)
+    if args.json:
+        print(json.dumps(res.as_dict(), indent=2))
+        return res.exit_code
+
+    paint = _paint(not args.no_color and sys.stdout.isatty())
+    print(res.output)
+    if res.notes and not args.quiet:
+        print(file=sys.stderr)
+        print(paint("Migration notes", "bold"), file=sys.stderr)
+        for note in res.notes:
+            tag = paint(note.severity.upper().ljust(5), SEV_COLOR.get(note.severity, "dim"))
+            print(f"  {tag} {note.text}", file=sys.stderr)
+        if res.compose_hit:
+            print(f"\n  See {RULES['links']['compose']}", file=sys.stderr)
+    return res.exit_code
+
+
+def cmd_compose(args: argparse.Namespace) -> int:
+    report = analyse(_read(args.file))
+    if args.json:
+        print(json.dumps(report.as_dict(), indent=2))
+        return report.exit_code
+
+    paint = _paint(not args.no_color and sys.stdout.isatty())
+    if report.parse_error:
+        print(paint(f"error: {report.parse_error}", "red"), file=sys.stderr)
+        return report.exit_code
+
+    print(paint("# wslc has no Compose runtime. Equivalent commands:", "dim"))
+    if report.prelude:
+        print()
+        for line in report.prelude:
+            print(line)
+    for svc in report.services:
+        print()
+        print(paint(f"# service: {svc.name}", "bold"))
+        print(svc.command)
+        for key, note in svc.partial:
+            print(paint(f"  ! {key}: {note}", "yellow"), file=sys.stderr)
+        for key, note in svc.missing:
+            print(paint(f"  x {key}: {note}", "red"), file=sys.stderr)
+        if svc.unknown:
+            print(paint(f"  ? unrecognised keys: {', '.join(svc.unknown)}", "dim"), file=sys.stderr)
+    print(f"\n{paint('Guide:', 'dim')} {RULES['links']['compose']}", file=sys.stderr)
+    return report.exit_code
+
+
+LINT_TARGETS = ("docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml")
+
+
+def cmd_lint(args: argparse.Namespace) -> int:
+    root = Path(args.path)
+    paint = _paint(not args.no_color and sys.stdout.isatty())
+    worst = 0
+    found = False
+
+    if root.is_file():
+        candidates = [root]
+    else:
+        # rglob("*") does not descend into dot-directories, so the standard
+        # .devcontainer/devcontainer.json location must be globbed explicitly.
+        patterns = [f"**/{name}" for name in LINT_TARGETS]
+        patterns += ["**/devcontainer.json", ".devcontainer/**/devcontainer.json"]
+        seen: set[Path] = set()
+        candidates = []
+        for pattern in patterns:
+            for path in root.glob(pattern):
+                if not path.is_file():
+                    continue
+                if "node_modules" in path.parts or ".git" in path.parts:
+                    continue
+                resolved = path.resolve()
+                if resolved in seen:
+                    continue
+                seen.add(resolved)
+                candidates.append(path)
+        candidates.sort()
+
+    for path in candidates:
+        found = True
+        rel = path.relative_to(root) if root.is_dir() else path
+        if path.name == "devcontainer.json":
+            code = _lint_devcontainer(path, rel, paint)
+        else:
+            report = analyse(path.read_text(encoding="utf-8"))
+            code = report.exit_code
+            issues = [(k, n, "x") for s in report.services for k, n in s.missing]
+            issues += [(k, n, "!") for s in report.services for k, n in s.partial]
+            if issues:
+                print(paint(str(rel), "bold"))
+                for key, note, mark in issues:
+                    col = "red" if mark == "x" else "yellow"
+                    print(paint(f"  {mark} {key}: {note}", col))
+        worst = max(worst, code)
+
+    if not found:
+        print("No compose or devcontainer files found.", file=sys.stderr)
+        return 0
+    if worst == 0:
+        print(paint("All checked files are wslc-compatible.", "green"))
+    return worst
+
+
+def _lint_devcontainer(path: Path, rel: Path, paint) -> int:
+    keys = RULES["devcontainer"]["keys"]
+    try:
+        raw = path.read_text(encoding="utf-8")
+        # devcontainer.json permits // comments
+        stripped = "\n".join(
+            line for line in raw.splitlines() if not line.strip().startswith("//")
+        )
+        doc = json.loads(stripped)
+    except Exception as exc:
+        print(paint(f"{rel}: cannot parse ({exc})", "red"))
+        return 2
+    code = 0
+    header = False
+    for key in doc:
+        spec = keys.get(key)
+        if not spec or spec["status"] == "ok":
+            continue
+        if not header:
+            print(paint(str(rel), "bold"))
+            header = True
+        if spec["status"] == "missing":
+            print(paint(f"  x {key}: {spec.get('note','unsupported')}", "red"))
+            code = 2
+        else:
+            print(paint(f"  ! {key}: {spec.get('note','differs')}", "yellow"))
+            code = max(code, 1)
+    return code
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="docker2wslc",
+        description=f"Translate Docker commands and Compose files to wslc. Docs: {SITE}",
+        epilog="Exit codes: 0 clean, 1 degraded, 2 unmigratable.",
+    )
+    p.add_argument("--version", action="version", version=f"docker2wslc {__version__}")
+    p.add_argument("--no-color", action="store_true", help="disable ANSI colour")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("convert", help="translate a docker command or script")
+    c.add_argument("command", nargs="*", help="docker command (or use --file/stdin)")
+    c.add_argument("-f", "--file", help="read commands from a file, - for stdin")
+    c.add_argument("--json", action="store_true", help="machine-readable output")
+    c.add_argument("-q", "--quiet", action="store_true", help="suppress migration notes")
+    c.add_argument("--no-color", action="store_true", help=argparse.SUPPRESS)
+    c.set_defaults(func=cmd_convert)
+
+    m = sub.add_parser("compose", help="analyse a compose file for wslc migration")
+    m.add_argument("file", nargs="?", default="docker-compose.yml")
+    m.add_argument("--json", action="store_true", help="machine-readable output")
+    m.add_argument("--no-color", action="store_true", help=argparse.SUPPRESS)
+    m.set_defaults(func=cmd_compose)
+
+    l = sub.add_parser("lint", help="scan a repo for wslc incompatibilities")
+    l.add_argument("path", nargs="?", default=".")
+    l.add_argument("--no-color", action="store_true", help=argparse.SUPPRESS)
+    l.set_defaults(func=cmd_lint)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+
+    # `convert docker run --gpus all ...` — everything after the first `docker`/`podman`
+    # token belongs to the command being translated, not to argparse. Without this,
+    # argparse rejects `--gpus`/`--platform`/`-p` as unrecognised options.
+    passthrough: list[str] = []
+    for i, tok in enumerate(raw):
+        if tok in ("docker", "podman", "sudo"):
+            passthrough = raw[i:]
+            raw = raw[:i]
+            break
+
+    parser = build_parser()
+    args = parser.parse_args(raw)
+    if passthrough:
+        args.command = passthrough
+    try:
+        return args.func(args)
+    except FileNotFoundError as exc:
+        print(f"error: {exc.filename}: no such file", file=sys.stderr)
+        return 2
+    except BrokenPipeError:  # pragma: no cover
+        return 0
+    except KeyboardInterrupt:  # pragma: no cover
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

docker2wslc-0.1.0/src/docker2wslc/compose.py

@@ -0,0 +1,167 @@
+"""Compose migration analyser: docker-compose.yml -> wslc run equivalents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .translate import RULES
+
+COMPOSE_KEYS: dict[str, dict[str, Any]] = RULES["compose"]["keys"]
+
+
+@dataclass
+class ServiceReport:
+    name: str
+    command: str = ""
+    ok: list[str] = field(default_factory=list)
+    partial: list[tuple[str, str]] = field(default_factory=list)
+    missing: list[tuple[str, str]] = field(default_factory=list)
+    unknown: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ComposeReport:
+    services: list[ServiceReport] = field(default_factory=list)
+    prelude: list[str] = field(default_factory=list)
+    parse_error: str | None = None
+
+    @property
+    def exit_code(self) -> int:
+        if self.parse_error:
+            return 2
+        if any(s.missing for s in self.services):
+            return 2
+        if any(s.partial for s in self.services):
+            return 1
+        return 0
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "parseError": self.parse_error,
+            "prelude": self.prelude,
+            "services": [
+                {
+                    "name": s.name,
+                    "command": s.command,
+                    "ok": s.ok,
+                    "partial": [{"key": k, "note": n} for k, n in s.partial],
+                    "missing": [{"key": k, "note": n} for k, n in s.missing],
+                    "unknown": s.unknown,
+                }
+                for s in self.services
+            ],
+            "exitCode": self.exit_code,
+        }
+
+
+def _as_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    if isinstance(value, dict):
+        return [f"{k}={v}" for k, v in value.items()]
+    return [str(value)]
+
+
+def _build_run(name: str, svc: dict[str, Any]) -> str:
+    args: list[str] = ["wslc", "run", "-d", "--name", svc.get("container_name") or name]
+
+    for env in _as_list(svc.get("environment")):
+        args += ["-e", env]
+    for env_file in _as_list(svc.get("env_file")):
+        args += ["--env-file", env_file]
+    for port in _as_list(svc.get("ports")):
+        args += ["-p", port.strip('"')]
+    for vol in _as_list(svc.get("volumes")):
+        args += ["-v", vol]
+    for net in _as_list(svc.get("networks")):
+        args += ["--network", net]
+    for cap in _as_list(svc.get("cap_add")):
+        args += ["--cap-add", cap]
+    for dev in _as_list(svc.get("devices")):
+        args += ["--device", dev]
+    for label in _as_list(svc.get("labels")):
+        args += ["--label", label]
+    for tmp in _as_list(svc.get("tmpfs")):
+        args += ["--tmpfs", tmp]
+
+    if svc.get("working_dir"):
+        args += ["-w", str(svc["working_dir"])]
+    if svc.get("user"):
+        args += ["-u", str(svc["user"])]
+    if svc.get("hostname"):
+        args += ["--hostname", str(svc["hostname"])]
+    if svc.get("entrypoint"):
+        ep = svc["entrypoint"]
+        args += ["--entrypoint", ep if isinstance(ep, str) else " ".join(ep)]
+    if svc.get("stdin_open"):
+        args.append("-i")
+    if svc.get("tty"):
+        args.append("-t")
+
+    image = svc.get("image")
+    if not image and svc.get("build"):
+        image = f"{name}:local"
+    args.append(str(image or "<image>"))
+
+    cmd = svc.get("command")
+    if cmd:
+        args += cmd.split() if isinstance(cmd, str) else [str(c) for c in cmd]
+
+    return " ".join(args)
+
+
+def analyse(text: str) -> ComposeReport:
+    """Analyse a compose file. Requires PyYAML; reports cleanly if absent."""
+    report = ComposeReport()
+    try:
+        import yaml
+    except ImportError:  # pragma: no cover
+        report.parse_error = "PyYAML is required: pip install 'docker2wslc[yaml]'"
+        return report
+
+    try:
+        doc = yaml.safe_load(text) or {}
+    except Exception as exc:
+        report.parse_error = f"YAML parse error: {exc}"
+        return report
+
+    if not isinstance(doc, dict):
+        report.parse_error = "Compose file did not parse to a mapping."
+        return report
+
+    for vol in (doc.get("volumes") or {}):
+        report.prelude.append(f"wslc volume create {vol}")
+    for net in (doc.get("networks") or {}):
+        report.prelude.append(f"wslc network create {net}")
+
+    services = doc.get("services") or {}
+    if not isinstance(services, dict):
+        report.parse_error = "`services` is not a mapping."
+        return report
+
+    for name, svc in services.items():
+        if not isinstance(svc, dict):
+            continue
+        sr = ServiceReport(name=str(name))
+        for key in svc:
+            spec = COMPOSE_KEYS.get(str(key))
+            if spec is None:
+                sr.unknown.append(str(key))
+            elif spec["status"] == "ok":
+                sr.ok.append(str(key))
+            elif spec["status"] == "partial":
+                sr.partial.append((str(key), spec.get("note", "")))
+            else:
+                sr.missing.append((str(key), spec.get("note", "")))
+        sr.command = _build_run(str(name), svc)
+        report.services.append(sr)
+
+    # depends_on ordering hint
+    ordered = [s.name for s in report.services]
+    if any("depends_on" in dict(s.missing) for s in report.services):
+        report.prelude.append(f"# start order matters: {' -> '.join(ordered)}")
+
+    return report

docker2wslc-0.1.0/src/docker2wslc/rules.json

@@ -0,0 +1,167 @@
+{
+  "$comment": "Single source of truth for Docker -> wslc translation. Consumed by the Python package, the npm CLI, the MCP server and the VS Code extension. Do not fork this logic per language.",
+  "schemaVersion": 1,
+  "wslcPreview": "2026-07",
+  "identical": [
+    "run", "build", "pull", "push", "stop", "start", "restart", "exec", "logs",
+    "inspect", "stats", "cp", "tag", "login", "logout", "kill", "pause",
+    "unpause", "version", "info", "top", "wait", "port", "rename", "diff",
+    "commit", "save", "load", "attach"
+  ],
+  "renamed": {
+    "ps": "container list",
+    "images": "image list",
+    "rmi": "image remove",
+    "rm": "container remove",
+    "create": "container create",
+    "history": "image history",
+    "search": "image search"
+  },
+  "renamedFlags": {
+    "ps": { "-a": "--all", "--all": "--all", "-q": "--quiet", "--quiet": "--quiet" },
+    "images": { "-a": "--all", "--all": "--all" },
+    "rm": { "-f": "--force", "--force": "--force" },
+    "rmi": { "-f": "--force", "--force": "--force" }
+  },
+  "unsupported": {
+    "swarm": "Swarm orchestration has no wslc equivalent. Use Kubernetes or keep Docker for this workload.",
+    "service": "Swarm services are not supported by wslc.",
+    "stack": "Swarm stacks are not supported by wslc.",
+    "node": "Swarm node management is not supported by wslc.",
+    "secret": "Swarm secrets are not supported. Pass values with -e or mount a file.",
+    "config": "Swarm configs are not supported by wslc.",
+    "plugin": "Docker plugins are not supported by wslc.",
+    "context": "wslc has a single local runtime, so there are no contexts to switch.",
+    "buildx": "buildx / bake is not available. Use wslc build for single-platform images.",
+    "manifest": "Manifest lists cannot be created with wslc in the preview.",
+    "trust": "Docker Content Trust is Docker-specific and has no wslc equivalent.",
+    "checkpoint": "Checkpoint/restore is not implemented in wslc."
+  },
+  "flags": {
+    "--platform": {
+      "action": "drop",
+      "takesValue": true,
+      "severity": "warn",
+      "note": "`--platform` is dropped: wslc builds and runs for the host architecture only in the preview."
+    },
+    "--restart": {
+      "action": "drop",
+      "takesValue": true,
+      "severity": "warn",
+      "note": "Restart policies are not implemented in the wslc preview. Flag dropped — use a Windows scheduled task or a wrapper script for auto-restart."
+    },
+    "--gpus": {
+      "action": "rewrite",
+      "takesValue": true,
+      "replaceWith": "--device nvidia.com/gpu=all",
+      "severity": "info",
+      "note": "GPU access in wslc goes through the Container Device Interface. Use `--device nvidia.com/gpu=all` instead of `--gpus`."
+    },
+    "--network": {
+      "action": "conditional",
+      "takesValue": true,
+      "whenValue": {
+        "host": {
+          "action": "drop",
+          "severity": "info",
+          "note": "`--network host` behaves differently: wslc routes container traffic through the Windows host stack already, so host networking is implicit. Flag dropped."
+        }
+      },
+      "severity": "info",
+      "note": "Custom networks are supported but bridge-only. Create it first with `wslc network create`."
+    },
+    "--volume": {
+      "action": "keep",
+      "takesValue": true,
+      "aliases": ["-v", "--mount"],
+      "severity": "info",
+      "noteWhenWindowsPath": "Windows host paths are shared over VirtioFS. Use forward slashes (`C:/work:/app`) and expect Linux-style permissions on the container side."
+    }
+  },
+  "compose": {
+    "supported": false,
+    "note": "wslc has no built-in Compose runtime. Translate each service into a wslc run call, or drive them from a PowerShell/bash script.",
+    "docsUrl": "https://wslcontainers.com/guides/compose/",
+    "keys": {
+      "image":        { "status": "ok",      "maps": "positional image argument" },
+      "build":        { "status": "ok",      "maps": "wslc build -t <name>" },
+      "command":      { "status": "ok",      "maps": "trailing command args" },
+      "entrypoint":   { "status": "ok",      "maps": "--entrypoint" },
+      "environment":  { "status": "ok",      "maps": "-e KEY=VALUE" },
+      "env_file":     { "status": "ok",      "maps": "--env-file" },
+      "ports":        { "status": "ok",      "maps": "-p HOST:CONTAINER" },
+      "volumes":      { "status": "partial", "maps": "-v", "note": "Named volumes must be created first with wslc volume create. Windows paths go over VirtioFS." },
+      "networks":     { "status": "partial", "maps": "--network", "note": "Bridge-only. Create with wslc network create before running." },
+      "working_dir":  { "status": "ok",      "maps": "-w" },
+      "user":         { "status": "ok",      "maps": "-u" },
+      "hostname":     { "status": "ok",      "maps": "--hostname" },
+      "container_name": { "status": "ok",    "maps": "--name" },
+      "labels":       { "status": "ok",      "maps": "--label" },
+      "cap_add":      { "status": "partial", "maps": "--cap-add", "note": "Some capabilities are restricted inside the utility VM." },
+      "devices":      { "status": "partial", "maps": "--device", "note": "CDI syntax differs from Docker for GPUs." },
+      "tmpfs":        { "status": "ok",      "maps": "--tmpfs" },
+      "stdin_open":   { "status": "ok",      "maps": "-i" },
+      "tty":          { "status": "ok",      "maps": "-t" },
+      "restart":      { "status": "missing", "note": "No restart policies in the wslc preview." },
+      "healthcheck":  { "status": "missing", "note": "wslc has no healthcheck support; depends_on conditions relying on it cannot work." },
+      "depends_on":   { "status": "missing", "note": "No dependency ordering. Start services in order yourself and add readiness waits." },
+      "deploy":       { "status": "missing", "note": "Swarm-only section, ignored entirely." },
+      "profiles":     { "status": "missing", "note": "Compose-only concept." },
+      "extends":      { "status": "missing", "note": "Compose-only concept." },
+      "configs":      { "status": "missing", "note": "Swarm configs are unsupported; mount a file instead." },
+      "secrets":      { "status": "missing", "note": "Swarm secrets are unsupported; use -e or a mounted file." }
+    }
+  },
+  "devcontainer": {
+    "keys": {
+      "image":             { "status": "ok" },
+      "build.dockerfile":  { "status": "ok" },
+      "build.args":        { "status": "ok",      "maps": "--build-arg" },
+      "build.platform":    { "status": "missing", "note": "Host architecture only." },
+      "workspaceMount":    { "status": "partial", "note": "VirtioFS; use forward slashes for Windows paths." },
+      "workspaceFolder":   { "status": "ok" },
+      "containerEnv":      { "status": "ok",      "maps": "-e" },
+      "remoteEnv":         { "status": "ok" },
+      "forwardPorts":      { "status": "ok",      "maps": "-p" },
+      "postCreateCommand": { "status": "ok",      "maps": "wslc exec" },
+      "postStartCommand":  { "status": "ok" },
+      "postAttachCommand": { "status": "ok" },
+      "remoteUser":        { "status": "ok",      "maps": "-u" },
+      "containerUser":     { "status": "ok" },
+      "mounts":            { "status": "partial", "note": "VirtioFS path rules apply." },
+      "runArgs":           { "status": "partial", "note": "Passed through verbatim; unsupported flags will fail at runtime." },
+      "dockerComposeFile": { "status": "missing", "note": "No Compose runtime. Replace with a single image or build entry." },
+      "features":          { "status": "missing", "note": "Requires BuildKit metadata that wslc build does not emit." },
+      "runServices":       { "status": "missing", "note": "Compose-only key." },
+      "shutdownAction":    { "status": "partial", "note": "stopCompose is meaningless without Compose." }
+    },
+    "requiredSetting": {
+      "key": "dev.containers.dockerPath",
+      "value": "wslc",
+      "note": "Point the Dev Containers extension at wslc. Prefer workspace scope over global."
+    }
+  },
+  "apiIncompatible": {
+    "note": "CLI-driven tooling ports to wslc. API-driven tooling cannot, because wslc is daemonless and exposes no Docker Engine API or socket.",
+    "tools": [
+      { "name": "Testcontainers", "via": "Engine API", "works": false },
+      { "name": "Docker-in-Docker sidecars", "via": "mounted socket", "works": false },
+      { "name": "Portainer", "via": "Engine API", "works": false },
+      { "name": "Lazydocker", "via": "Engine API", "works": false },
+      { "name": "LocalStack (docker mode)", "via": "Engine API", "works": false },
+      { "name": "act", "via": "Engine API", "works": false },
+      { "name": "VS Code Dev Containers", "via": "CLI binary", "works": true },
+      { "name": "shell scripts calling docker", "via": "CLI binary", "works": true }
+    ]
+  },
+  "links": {
+    "site": "https://wslcontainers.com",
+    "converter": "https://wslcontainers.com/",
+    "cheatsheet": "https://wslcontainers.com/reference/cheatsheet/",
+    "compose": "https://wslcontainers.com/guides/compose/",
+    "install": "https://wslcontainers.com/guides/install/",
+    "vsDocker": "https://wslcontainers.com/guides/vs-docker-desktop/",
+    "devcontainers": "https://wslcontainers.com/guides/vscode-dev-containers/",
+    "testcontainers": "https://wslcontainers.com/guides/testcontainers/"
+  }
+}

docker2wslc-0.1.0/src/docker2wslc/translate.py

@@ -0,0 +1,267 @@
+"""Docker -> wslc command translation, driven by the shared rules.json."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from importlib.resources import files
+from typing import Any
+
+WINDOWS_PATH = re.compile(r"^[A-Za-z]:[\\/]")
+
+
+def load_rules() -> dict[str, Any]:
+    """Load the bundled rules.json (single source of truth across languages)."""
+    data = files("docker2wslc").joinpath("rules.json").read_text(encoding="utf-8")
+    return json.loads(data)
+
+
+RULES = load_rules()
+
+SEV_ORDER = {"info": 0, "warn": 1, "error": 2}
+
+
+@dataclass
+class Note:
+    severity: str
+    text: str
+
+    def __str__(self) -> str:  # pragma: no cover - display helper
+        return f"[{self.severity}] {self.text}"
+
+
+@dataclass
+class Result:
+    """Outcome of translating one or more lines."""
+
+    output: str = ""
+    notes: list[Note] = field(default_factory=list)
+    compose_hit: bool = False
+    unsupported_hit: bool = False
+
+    @property
+    def exit_code(self) -> int:
+        """0 clean, 1 degraded (flags dropped/rewritten), 2 unmigratable."""
+        if self.unsupported_hit or self.compose_hit:
+            return 2
+        if any(n.severity in ("warn", "error") for n in self.notes):
+            return 1
+        return 0
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "output": self.output,
+            "notes": [{"severity": n.severity, "text": n.text} for n in self.notes],
+            "composeHit": self.compose_hit,
+            "unsupportedHit": self.unsupported_hit,
+            "exitCode": self.exit_code,
+        }
+
+
+def tokenize(line: str) -> list[str]:
+    """Split a shell-ish line, keeping quoted spans intact (quotes preserved)."""
+    out: list[str] = []
+    cur = ""
+    quote: str | None = None
+    for ch in line:
+        if quote:
+            cur += ch
+            if ch == quote:
+                quote = None
+        elif ch in ("'", '"'):
+            quote = ch
+            cur += ch
+        elif ch.isspace():
+            if cur:
+                out.append(cur)
+                cur = ""
+        else:
+            cur += ch
+    if cur:
+        out.append(cur)
+    return out
+
+
+def _flag_spec(flag: str) -> tuple[str, dict[str, Any]] | tuple[None, None]:
+    flags = RULES["flags"]
+    if flag in flags:
+        return flag, flags[flag]
+    for canonical, spec in flags.items():
+        if flag in spec.get("aliases", []):
+            return canonical, spec
+    return None, None
+
+
+def _translate_args(args: list[str], notes: list[Note]) -> list[str]:
+    out: list[str] = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        bare, _, inline = arg.partition("=")
+        canonical, spec = _flag_spec(bare)
+
+        if spec is None:
+            out.append(arg)
+            i += 1
+            continue
+
+        takes_value = spec.get("takesValue", False)
+        has_inline = "=" in arg
+        value = inline if has_inline else (args[i + 1] if i + 1 < len(args) else "")
+        consumed = 1 if has_inline or not takes_value else 2
+
+        action = spec["action"]
+
+        if action == "conditional":
+            branch = spec.get("whenValue", {}).get(value)
+            if branch:
+                if branch["action"] == "drop":
+                    notes.append(Note(branch.get("severity", "info"), branch["note"]))
+                    i += consumed
+                    continue
+            notes.append(Note(spec.get("severity", "info"), spec["note"]))
+            out.append(f"{bare}={value}" if has_inline else bare)
+            if not has_inline and takes_value and value:
+                out.append(value)
+            i += consumed
+            continue
+
+        if action == "drop":
+            notes.append(Note(spec.get("severity", "warn"), spec["note"]))
+            i += consumed
+            continue
+
+        if action == "rewrite":
+            notes.append(Note(spec.get("severity", "info"), spec["note"]))
+            out.extend(spec["replaceWith"].split())
+            i += consumed
+            continue
+
+        # action == "keep"
+        note_win = spec.get("noteWhenWindowsPath")
+        if note_win and (WINDOWS_PATH.match(value) or value.startswith("/mnt/")):
+            notes.append(Note(spec.get("severity", "info"), note_win))
+        out.append(arg)
+        if not has_inline and takes_value and value:
+            out.append(value)
+        i += consumed
+    return out
+
+
+def translate_line(raw: str) -> Result | None:
+    """Translate a single line. Returns None for blank lines."""
+    line = raw.strip()
+    if not line:
+        return None
+    if line.startswith("#"):
+        return Result(output=line)
+
+    notes: list[Note] = []
+    tokens = tokenize(line)
+
+    if tokens and tokens[0] == "sudo":
+        tokens.pop(0)
+        notes.append(
+            Note(
+                "info",
+                "Dropped sudo — wslc runs as your Windows user, no elevation needed "
+                "for normal container operations.",
+            )
+        )
+
+    if not tokens or tokens[0] not in ("docker", "podman"):
+        return Result(
+            output=f"# not a docker command: {line}",
+            notes=[Note("info", "Only docker/podman commands are translated. Line left unchanged.")],
+        )
+
+    if tokens[0] == "podman":
+        notes.append(
+            Note("info", "Treated podman as Docker-compatible; flag coverage is nearly identical.")
+        )
+    tokens.pop(0)
+
+    if not tokens:
+        return Result(output="wslc", notes=notes)
+
+    if tokens[0] in ("compose", "docker-compose"):
+        compose = RULES["compose"]
+        notes.append(Note("error", compose["note"]))
+        return Result(
+            output="# No native Compose runtime in wslc.", notes=notes, compose_hit=True
+        )
+
+    two = f"{tokens[0]} {tokens[1]}" if len(tokens) > 1 else ""
+    if two and two in (RULES["renamed"].values()):
+        rest = _translate_args(tokens[2:], notes)
+        return Result(output=" ".join(["wslc", two, *rest]).strip(), notes=notes)
+
+    verb = tokens[0]
+
+    if verb in RULES["unsupported"]:
+        notes.append(Note("error", RULES["unsupported"][verb]))
+        return Result(
+            output=f"# {verb}: not supported by wslc", notes=notes, unsupported_hit=True
+        )
+
+    if verb in RULES["renamed"]:
+        mapped = RULES["renamed"][verb]
+        flag_map = RULES["renamedFlags"].get(verb, {})
+        rest: list[str] = []
+        for arg in tokens[1:]:
+            rest.append(flag_map.get(arg, arg))
+        rest = _translate_args(rest, notes)
+        notes.append(
+            Note(
+                "info",
+                f"`docker {verb}` is grouped under a noun in wslc: `wslc {mapped}`. "
+                f"Recent previews accept `wslc {verb}` as an alias, but the noun form is stable.",
+            )
+        )
+        return Result(output=" ".join(["wslc", mapped, *rest]).strip(), notes=notes)
+
+    if verb in RULES["identical"]:
+        rest = _translate_args(tokens[1:], notes)
+        return Result(output=" ".join(["wslc", verb, *rest]).strip(), notes=notes)
+
+    notes.append(
+        Note(
+            "warn",
+            f"Unknown docker subcommand `{verb}` — passed through unchanged. "
+            "Verify against `wslc --help`.",
+        )
+    )
+    rest = _translate_args(tokens[1:], notes)
+    return Result(output=" ".join(["wslc", verb, *rest]).strip(), notes=notes)
+
+
+def translate(text: str) -> Result:
+    """Translate a multi-line script, de-duplicating notes."""
+    lines: list[str] = []
+    notes: list[Note] = []
+    seen: set[str] = set()
+    compose_hit = False
+    unsupported_hit = False
+
+    for raw in str(text).split("\n"):
+        res = translate_line(raw)
+        if res is None:
+            lines.append("")
+            continue
+        lines.append(res.output)
+        compose_hit = compose_hit or res.compose_hit
+        unsupported_hit = unsupported_hit or res.unsupported_hit
+        for note in res.notes:
+            if note.text not in seen:
+                seen.add(note.text)
+                notes.append(note)
+
+    joined = re.sub(r"\n{3,}", "\n\n", "\n".join(lines)).strip()
+    notes.sort(key=lambda n: -SEV_ORDER.get(n.severity, 0))
+    return Result(
+        output=joined,
+        notes=notes,
+        compose_hit=compose_hit,
+        unsupported_hit=unsupported_hit,
+    )