wslc-wip 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0845dfb67f17323b8a99e6f2f92ef06c17bc03fd1316680cf5f43f2640d73da3'
-  data.tar.gz: 6eea9bb520aed0fff5b401b71a20dccdade6b50d9a71403037e59e4e5b83ab2e
+  metadata.gz: b0fdc63759c329dc9cbc9a60a0ef184db31087d454070871bc3f39a1982d7426
+  data.tar.gz: 447d4f3206b3662def93d376b950de99564f3efbfc85e8607bbaad6fb432545d
 SHA512:
-  metadata.gz: 1b522d206ba3070244f51bda9d4e144dfe95df63ab01bb92b35d0fe0e84a29035c997d7b061c2ec23286c8bd9f586c69e276b7304abd1c8ad81fe808293599b5
-  data.tar.gz: d7fc237820edfcc734f55775e027133c5f9877c24b16f5b1ca6aa98304b35fdea5825a179ff7f64b4d22fe2634d52d11761777284b68a86e76faa56432d33230
+  metadata.gz: fc07a96116a3c737332a313447663a1730d6d15729c329b6e121a356de2bf62ba696b7386a854c685a7bb2415fc5b7c0edc42437ec86b80b2d13de99b6075cad
+  data.tar.gz: 61b8a28cd2953335ca38a97cf15f52302aa070698d183d95fefc1edcd7d85d661cb8461ebe1de830969f4b9480734dfeb13c6431821925a500377eb56b1a4221

data/README.md

@@ -97,6 +97,11 @@ commands:
     type: build
     context: .
     tag: slidict/slidict:development
+sync: # optional; mirror the source into a named volume instead of bind-mounting it live
+  exclude:
+    - .git
+    - tmp/
+    - node_modules/
 ```
 
 `env` values are stringified. `wip config` masks any key matching token, password, secret,
@@ -129,6 +134,97 @@ the same way Compose's service names resolve. `wip down` tears the main containe
 dependencies down (the network itself is left in place). Each dependency entry accepts `image`
 (required), `command`, `env`, `ports`, `volumes`, and `workdir` — the same shape as `defaults`.
 
+### Source sync
+
+Bind-mounting the app directory (`.:/app`) is what usually makes a container boot crawl under
+wslc — see [Slow boot when the app directory is
+bind-mounted](#slow-boot-when-the-app-directory-is-bind-mounted) for why. A `sync:` block hands
+that problem to `wip`: the source is mounted read-only, the app runs off a named volume, and wip
+mirrors one into the other with `rsync`.
+
+```yaml
+sync:
+  source: .          # host path, relative to wip.yml (default: the wip.yml directory)
+  target: /app       # container path served by the volume (default: defaults.workdir, else /app)
+  volume: app-src    # named volume holding the mirror (default: "<defaults.container>-src")
+  mount: /host-src   # where the source is bind-mounted read-only (default: /host-src)
+  exclude:           # rsync --exclude patterns
+    - .git
+    - tmp/
+    - node_modules/
+  delete: true       # rsync --delete (default: true)
+  command: rsync     # binary that does the mirroring (default: rsync)
+  options: []        # extra flags appended to the rsync invocation
+  interval: 2        # seconds between syncs for `wip sync --watch` (default: 2)
+```
+
+Everything below `sync:` is optional — `sync: {}` alone already works. With it in place:
+
+- Any `defaults.volumes` entry mounting `target` (the usual `.:/app`) is replaced by
+  `<source>:/host-src:ro` plus `app-src:/app`, so the running app only ever touches the volume.
+  Other volumes (`bundle:/usr/local/bundle`, ...) are passed through untouched, and
+  `dependencies:` keep mounting whatever they declare.
+- `wip up` mirrors the source into the volume before the container boots; `wip up --no-sync`
+  skips that step.
+- `wip sync` mirrors on demand — `wslc exec`ing rsync inside the container when it's running, and
+  falling back to a throwaway container with the same mounts when it isn't.
+- `wip sync --watch [--interval N]` keeps re-syncing until Ctrl-C, so host edits reach the
+  container with a short delay. Run it in a second terminal alongside `wip up -d`.
+- `wip doctor` reports the resolved source, volume, and target, and fails if the source is missing.
+
+Like every built-in command, `wip sync` takes precedence over a `commands:` entry of the same
+name; wip says so and points at `wip dispatch sync`, which still runs yours.
+
+Two things to keep in mind. The mirror runs `rsync` *inside* the container, so the image needs it
+(`RUN apt-get update && apt-get install -y rsync`) — or point `sync.command` at a copy tool the
+image already has. And the mirror is one-way (host → volume): anything the app writes under
+`target` is removed by the next `--delete` pass unless you `exclude` it, give it its own volume,
+or set `delete: false`.
+
+`sync:` is mutually exclusive with `compose:` — in compose mode the compose file owns the volume
+layout.
+
+### Compose mode
+
+If your project already has a real `compose.yml`, don't duplicate it in `dependencies:` — point
+`wip` at it instead:
+
+```yaml
+version: 1
+compose:
+  service: app             # required: which compose service wip run/exec/NAME target
+  command: wslc-compose    # required: the compose-for-wslc binary/path you have installed
+  file: compose.yml        # optional; auto-detected next to wip.yml otherwise
+  project: myapp            # optional; omitted lets the compose tool pick its own default
+```
+
+`compose:` is mutually exclusive with `dependencies:`/`defaults.network` — pick one orchestration
+path per project. In compose mode, `wip` becomes a thin bridge to an external compose-for-`wslc`
+CLI rather than reimplementing Compose itself.
+
+`wslc` itself has no native Compose support yet (tracked upstream in
+[microsoft/WSL#40948](https://github.com/microsoft/WSL/issues/40948)), and until it does,
+independent third-party tools fill the gap — for example
+[bacarndiaye/wslc-compose](https://github.com/bacarndiaye/wslc-compose) (Python) and
+[inuyume/wslc-compose](https://github.com/inuyume/wslc-compose) (Go), among others. `wslc` is new
+and still evolving, so expect more of these to show up (and existing ones to change) over time.
+`wip` deliberately doesn't pick a winner or default to any of them (unlike `wslc.command`, which
+defaults to `auto` and searches for `wslc.exe`/`wslc`): `compose.command` is required and treats
+every implementation equally — set it to whichever binary name or absolute path you've installed.
+Whichever one you use needs to understand `-f FILE [-p PROJECT] up|down|exec|logs`, the subset of
+the Compose CLI vocabulary `wip` drives. `wip doctor` reports whether the configured command is
+found, its version, and which compose file `wip` resolved.
+
+- `wip up`/`wip down` delegate straight to `<compose command> up -d`/`down`.
+- `wip exec`/`wip NAME` (custom `commands:`) run inside `compose.service`.
+- `wip shell` also goes through the bridge: unless `commands.shell` is defined in `wip.yml`, it
+  `exec`s `bash` against `compose.service`, falling back to `sh`.
+- `wip logs [-f] [SERVICE...]` is only available in compose mode.
+- `wip run` has no ephemeral-container equivalent in this exec-only vocabulary, so it falls back
+  to `exec` against the already-running `compose.service` (wip warns when this happens).
+- `commands:` entries with `type: run`/`type: build` aren't supported in compose mode — use your
+  compose tool's own `build`/`up --build` directly; compose owns builds for its own services.
+
 ## Commands
 
 | Command | Description |
@@ -137,11 +233,13 @@ dependencies down (the network itself is left in place). Each dependency entry a
 | `wip doctor` | Diagnose WSL2, interop, WSLC, config, architecture, and Git |
 | `wip config` | Print the effective configuration (secrets masked) |
 | `wip build -- --no-cache` | Build the image from the `build` definition |
-| `wip up [-d]` | Start `defaults.container` and its `dependencies` (creating any that are missing, on `defaults.network` if set). `-d` runs the main container in the background |
+| `wip up [-d] [--no-sync]` | Start `defaults.container` and its `dependencies` (creating any that are missing, on `defaults.network` if set). `-d` runs the main container in the background; with `sync:` configured, the source is mirrored into the volume first unless `--no-sync` |
 | `wip down` | Stop and remove `defaults.container` and its `dependencies` |
 | `wip exec [--no-interactive] COMMAND...` | Run a command in the existing container |
-| `wip run [--no-interactive] COMMAND...` | Run a command in a new `--rm` container |
+| `wip run [--no-interactive] COMMAND...` | Run a command in a new `--rm` container (compose mode: `exec`s into `compose.service` instead) |
 | `wip shell` | Open the configured shell, falling back to `bash` then `sh` |
+| `wip logs [-f] [SERVICE...]` | Follow compose service logs (compose mode only) |
+| `wip sync [-w] [--interval N]` | Mirror the source into the sync volume once, or keep re-syncing with `--watch` (needs `sync:`) |
 | `wip NAME ARGS...` | Run `commands.NAME`, appending any extra arguments |
 
 TTY allocation is decided by combining the command's config, the CLI option, and whether both
@@ -209,6 +307,22 @@ When `pull access denied` (or similar) is detected, wip suggests how to log in:
 wslc registry login -u <username> docker.io
 ```
 
+### Slow boot when the app directory is bind-mounted
+
+wslc containers run in their own VM, so a bind-mounted host directory (`.:/app`) is always shared
+in over virtiofs, even when the host path is already on WSL's native filesystem. Frameworks that
+scan large directory trees at startup (Ruby's Zeitwerk autoloader, for example) issue many small
+per-file stat/open calls, and each one is a round trip through that layer — CPU on the Windows
+side can look busy while almost no data is actually transferred, and the process can appear hung
+for minutes with barely any resource usage to show for it.
+
+If a debug log shows a boot-time command "stuck" with low CPU/mem/IO in `resource_monitor`'s
+output, this is worth checking before assuming the app itself is broken. The fix is to stop
+bind-mounting the source live and mirror it into a named volume instead, so the app only ever
+touches fast native storage once it's running. `wip` does that for you — add a `sync:` block and
+it rewrites the mounts, mirrors before boot, and re-syncs on demand. See [Source
+sync](#source-sync).
+
 ### CPU architecture mismatch
 
 Check the image and publish a multi-arch (amd64/arm64) image:
@@ -243,10 +357,44 @@ checklist.
 
 ## Not in the initial release
 
-Full Compose compatibility (multiple networks, `depends_on` ordering/health checks, profiles), a
-resident/daemon process, a GUI, PowerShell-specific tuning, direct registry API/manifest parsing,
-self-update, and plugins are all unimplemented. Likely future additions: a richer config schema,
-lifecycle hooks, platform selection, and more detailed diagnostics.
+Full Compose compatibility isn't reimplemented in `wip` itself, but is available by delegating to
+a third-party compose-for-`wslc` tool — see [Compose mode](#compose-mode). A resident/daemon
+process, a GUI, PowerShell-specific tuning, direct registry API/manifest parsing, self-update, and
+plugins are all unimplemented.
+
+## Roadmap
+
+`wip` already covers most of what [`dip`](https://github.com/bibendi/dip) adds on top of Compose —
+named commands (`commands:`), `run`/`exec` hidden behind a single verb, `.env` passthrough, and
+sidecar services via `dependencies:` + `defaults.network`. Fuller Compose semantics
+(`depends_on` ordering/health checks, log aggregation, named volumes, profiles, scaling) are now
+handled by delegating to a separate compose-for-`wslc` tool in [compose mode](#compose-mode)
+rather than being reimplemented in `wip` itself. Which of those actually work is entirely up to
+the external tool you point `compose.command` at — `wip` only forwards
+`-f FILE [-p PROJECT] up|down|exec|logs`, so treat that list as what Compose offers, not as
+something `wip` guarantees. See that section for what compose mode covers
+and its current limitations (`run`, and `commands:` of type `run`/`build`). What's still planned
+for `wip`, roughly in priority order:
+
+1. **`wip provision`** — a dip-style one-shot bootstrap hook (build → up deps → install deps →
+   create/migrate/seed DB) so a new contributor can go from `git clone` to a working environment
+   in two commands (`wip provision && wip up`).
+2. **Config file merging** — `--config` currently accepts one file; support layering
+   (`wip.yml` + `wip.override.yml`, or a `WIP_CONFIG` list) for dev/CI/debug variants without
+   duplicating the whole file, plus a `wip config --resolved` view of the merged result.
+3. **Bind-mount boot time (`rails c`, `bundle`, ...)** — commands like `wip rails c` still start
+   noticeably slower than the equivalent under `docker compose`, mostly from WSL2 bind-mounted
+   (`.:/app`-style) volumes doing many small reads for gems/`node_modules` (use `--debug` to
+   confirm it's disk I/O and not `wip`'s own overhead). [Source sync](#source-sync) works around
+   this today by running the app off a named volume and mirroring the host tree into it, at the
+   cost of a one-way sync with a short delay. A tighter loop (host-side file watching instead of
+   interval polling, two-way sync) is the natural next step. We're also hoping for improvements on
+   the `wslc` side itself (faster bind-mount/cache behavior); `wip` will pick those up for free as
+   soon as they land.
+
+Each of these should stay additive to the existing `wip.yml` shape — no breaking changes to
+`defaults`, `commands`, `dependencies`, or `compose` are planned. A resident daemon and a GUI
+remain out of scope; see "Not in the initial release" above.
 
 ## License
 

data/lib/wip/cli.rb

@@ -4,6 +4,7 @@ require 'thor'
 require 'yaml'
 require 'json'
 require 'stringio'
+require 'shellwords'
 
 module Wip
   # Thor-based command-line interface for wip.
@@ -62,14 +63,41 @@ module Wip
 
     desc 'up', 'Start the configured container and its dependencies, creating them if necessary'
     option :detach, type: :boolean, default: false, aliases: '-d'
+    option :sync, type: :boolean, default: true, desc: 'Mirror the source into the sync volume first (--no-sync skips)'
     def up
+      if load_config.compose?
+        return execute(compose_bridge.up(detach: options[:detach]), interactive: tty?(!options[:detach]))
+      end
+
       ensure_network
       load_config.dependencies.each_key { |name| ensure_dependency(name) }
+      sync_before_boot if options[:sync]
       ensure_container
     end
 
+    desc 'sync', 'Mirror the source tree into the sync volume'
+    option :watch, type: :boolean, default: false, aliases: '-w', desc: 'Keep re-syncing until interrupted'
+    option :interval, type: :numeric, desc: 'Seconds between syncs when watching (default: sync.interval)'
+    def sync
+      settings = sync_settings!
+      warn_shadowed_command('sync')
+      return run_sync unless options[:watch]
+
+      interval = watch_interval(settings)
+      warn "wip: syncing #{settings.source} -> #{settings.volume}:#{settings.target} " \
+           "every #{interval}s (Ctrl-C to stop)"
+      loop do
+        run_sync(exit_on_failure: false)
+        sleep interval
+      end
+    rescue Interrupt
+      warn "\nwip: sync stopped"
+    end
+
     desc 'down', 'Stop and remove the configured container and its dependencies'
     def down
+      return execute(compose_bridge.down, exit_on_failure: false) if load_config.compose?
+
       execute(builder.down, exit_on_failure: false)
       execute(builder.remove, exit_on_failure: false)
       load_config.dependencies.each_key do |name|
@@ -81,41 +109,51 @@ module Wip
     desc 'exec COMMAND...', 'Execute a command in the running container'
     option :interactive, type: :boolean, default: true
     def exec(*command)
-      tty = builder.tty?(options[:interactive])
-      execute(builder.exec(command, interactive: options[:interactive]), interactive: tty)
+      execute(exec_target(command, interactive: options[:interactive]), interactive: tty?(options[:interactive]))
     end
 
     desc 'run COMMAND...', 'Run a command in a new container'
     option :interactive, type: :boolean, default: true
     def run_command(*command)
-      tty = builder.tty?(options[:interactive])
-      execute(builder.run(command, interactive: options[:interactive]), interactive: tty)
+      if load_config.compose?
+        warn "wip: compose mode has no ephemeral 'run'; executing in the running " \
+             "'#{load_config.compose_service}' service instead"
+        return execute(exec_target(command, interactive: options[:interactive]),
+                       interactive: tty?(options[:interactive]))
+      end
+
+      execute(builder.run(command, interactive: options[:interactive]), interactive: tty?(options[:interactive]))
     end
     map 'run' => :run_command
 
     desc 'shell', 'Open a shell in the configured container'
     def shell_command
       configured = load_config.command('shell')
-      if configured
-        tty = builder.tty?(configured.fetch('interactive', false))
-        return execute(builder.custom('shell', []), interactive: tty)
-      end
+      return dispatch('shell') if configured
 
-      tty = builder.tty?(true)
-      code = execute(builder.exec(['bash'], settings: { 'interactive' => true }, interactive: true),
-                     interactive: tty, exit_on_failure: false)
+      code = execute(exec_target(['bash'], interactive: true), interactive: tty?(true), exit_on_failure: false)
       return if code.zero?
 
-      execute(builder.exec(['sh'], settings: { 'interactive' => true }, interactive: true), interactive: tty)
+      execute(exec_target(['sh'], interactive: true), interactive: tty?(true))
     end
     map 'shell' => :shell_command
 
+    desc 'logs [SERVICE...]', 'Follow logs from compose services (compose mode only)'
+    option :follow, type: :boolean, default: true, aliases: '-f'
+    def logs(*services)
+      raise ConfigError, '`wip logs` is only available in compose mode' unless load_config.compose?
+
+      execute(compose_bridge.logs(services: services, follow: options[:follow]), interactive: true)
+    end
+
     desc 'dispatch COMMAND [ARGS...]', 'Run a command defined in wip.yml'
     def dispatch(name = nil, *arguments)
       raise ConfigError, 'A command is required' unless name
 
       values = load_config.command(name) || raise(ConfigError, "Unknown command: #{name}")
-      execute(builder.custom(name, arguments), interactive: builder.tty?(values.fetch('interactive', false)))
+      return dispatch_compose(name, values, arguments) if load_config.compose?
+
+      execute(builder.custom(name, arguments), interactive: tty?(values.fetch('interactive', false)))
     end
 
     private
@@ -134,6 +172,31 @@ module Wip
       CommandBuilder.new(wslc: resolver.resolve(load_config.wslc_command), config: load_config, dotenv: dotenv)
     end
 
+    def compose_bridge = @compose_bridge ||= ComposeBridge.for(load_config)
+
+    def tty?(requested) = requested && Environment.new.interactive?
+
+    def exec_target(arguments, interactive:)
+      if load_config.compose?
+        return compose_bridge.exec(load_config.compose_service, arguments,
+                                   interactive: interactive)
+      end
+
+      builder.exec(arguments, interactive: interactive)
+    end
+
+    def dispatch_compose(name, values, arguments)
+      type = values['type'] || 'exec'
+      unless type == 'exec'
+        raise ConfigError, "commands.#{name}: type '#{type}' is not supported in compose mode " \
+                           '(use `wslc-compose build`/`up --build` directly)'
+      end
+
+      command = Shellwords.split(values['command'].to_s) + arguments
+      interactive = values.fetch('interactive', false)
+      execute(exec_target(command, interactive: interactive), interactive: tty?(interactive))
+    end
+
     def execute(command, interactive: false, exit_on_failure: true)
       runner = CommandRunner.new(debug: debug?)
       code = reporter.step("running: #{CommandDisplay.for_debug(command)}", live: !interactive) do
@@ -186,9 +249,49 @@ module Wip
       end
     end
 
+    def sync_settings!
+      load_config.sync || raise(ConfigError, '`wip sync` needs a sync: block in wip.yml')
+    end
+
+    # `sync.interval` is validated when the config loads; --interval isn't, and
+    # a negative one would only surface as an ArgumentError from `sleep`.
+    def watch_interval(settings)
+      interval = options[:interval] || settings.interval
+      raise ConfigError, '--interval must be a positive number' unless interval.positive?
+
+      interval
+    end
+
+    # A built-in command wins over a `commands:` entry of the same name, so
+    # point at `wip dispatch` rather than letting the custom one vanish.
+    def warn_shadowed_command(name)
+      return unless load_config.commands.key?(name)
+
+      warn "wip: commands.#{name} in wip.yml is shadowed by the built-in `wip #{name}`; " \
+           "run it with `wip dispatch #{name}`"
+    end
+
+    # Inside the running container the mirror is a plain `exec`; otherwise it
+    # takes a throwaway container that mounts the same source and volume.
+    def run_sync(exit_on_failure: true)
+      command = container_running? ? builder.sync_exec : builder.sync_run
+      execute(command, exit_on_failure: exit_on_failure)
+    end
+
+    def container_running? = resource_exists?(builder.find_running)
+
+    def sync_before_boot
+      settings = load_config.sync
+      return unless settings
+
+      warn "wip: syncing #{settings.source} -> #{settings.volume}:#{settings.target}"
+      execute(builder.sync_run)
+      warn "wip: run `wip sync --watch` in another terminal to keep #{settings.target} up to date"
+    end
+
     def ensure_container
       container = load_config.defaults['container']
-      interactive = builder.tty?(!options[:detach])
+      interactive = tty?(!options[:detach])
       if resource_exists?(builder.find)
         warn "wip: starting existing container '#{container}'"
         execute(builder.start(detach: options[:detach]), interactive: interactive)

data/lib/wip/command_builder.rb

@@ -49,6 +49,26 @@ module Wip
       [@wslc, 'list', '--all', '--filter', "name=#{container}", '--format', 'json']
     end
 
+    def find_running
+      container = required(@config.defaults, 'container')
+      [@wslc, 'list', '--filter', "name=#{container}", '--format', 'json']
+    end
+
+    # Mirrors into the volume from a throwaway container, for when the app
+    # container isn't running yet (or at all) — e.g. just before `up` boots it.
+    def sync_run
+      sync = required_sync
+      command = [@wslc, 'run', '--rm']
+      sync.volume_specs.each { |spec| command.push('-v', spec) }
+      command.push(required(@config.defaults, 'image')).concat(sync.mirror_command)
+    end
+
+    # Mirrors from inside the running container, which already has both the
+    # read-only source mount and the volume attached.
+    def sync_exec
+      [@wslc, 'exec', required(@config.defaults, 'container'), *required_sync.mirror_command]
+    end
+
     def down
       [@wslc, 'stop', required(@config.defaults, 'container')]
     end
@@ -70,7 +90,7 @@ module Wip
       command = [@wslc, 'run', '--name', name.to_s]
       command.push('--network', @config.network) if @config.network
       command << '-d' if detach
-      command.concat(options(values)).push(required(values, 'image'))
+      command.concat(options(values, sync: false)).push(required(values, 'image'))
       command.concat(Shellwords.split(values['command'].to_s)) unless values['command'].to_s.empty?
       command
     end
@@ -113,18 +133,29 @@ module Wip
 
     private
 
-    def options(values, include_container: false, include_publish: true)
+    def options(values, include_container: false, include_publish: true, sync: true)
       result = []
       result.push('-w', values['workdir']) unless values['workdir'].to_s.empty?
       merged_env(values).each { |key, value| result.push('-e', "#{key}=#{value}") }
       if include_publish
         Array(values['ports']).each { |port| result.push('-p', port.to_s) }
-        Array(values['volumes']).each { |volume| result.push('-v', volume.to_s) }
+        volume_specs(values, sync: sync).each { |volume| result.push('-v', volume) }
       end
       result << required(values, 'container') if include_container
       result
     end
 
+    # With sync configured, a live bind mount of the target (`.:/app`) is
+    # swapped for the read-only source mount plus the named volume, so the
+    # running app only ever touches the volume.
+    def volume_specs(values, sync: true)
+      specs = Array(values['volumes']).map(&:to_s)
+      settings = sync ? @config.sync : nil
+      return specs unless settings
+
+      specs.reject { |spec| settings.replaces?(spec) } + settings.volume_specs
+    end
+
     # .env supplies defaults; env set in wip.yml (defaults or per-command) wins on conflict.
     def merged_env(values) = @dotenv.merge(values.fetch('env', {}))
 
@@ -142,6 +173,10 @@ module Wip
       network
     end
 
+    def required_sync
+      @config.sync || raise(ConfigError, 'No sync: block configured in wip.yml')
+    end
+
     def dependency_values(name)
       @config.dependency(name) || raise(ConfigError, "Unknown dependency: #{name}")
     end

data/lib/wip/command_resolver.rb

@@ -1,20 +1,29 @@
 # frozen_string_literal: true
 
 module Wip
-  # Locates the wslc/wslc.exe executable on the current system.
+  # Locates an executable on the current system, trying a list of candidates.
   class CommandResolver
     CANDIDATES = ['wslc.exe', 'wslc', '/mnt/c/Windows/System32/wslc.exe'].freeze
+    DEFAULT_INSTALL_HINT = <<~HINT.chomp
+      Install or update the WSL container tooling, then run:
 
-    def initialize(path: ENV.fetch('PATH', ''), executable: nil)
+        wip doctor
+    HINT
+
+    def initialize(path: ENV.fetch('PATH', ''), executable: nil, candidates: CANDIDATES, label: 'WSLC',
+                   install_hint: DEFAULT_INSTALL_HINT)
       @path = path
       @executable = executable || method(:executable?)
+      @candidates = candidates
+      @label = label
+      @install_hint = install_hint
     end
 
     def resolve(configured = 'auto')
       return configured if configured != 'auto' && @executable.call(configured)
-      return raise_not_found if configured != 'auto'
+      return raise_not_found([configured]) if configured != 'auto'
 
-      CANDIDATES.find { |candidate| @executable.call(candidate) } || raise_not_found
+      @candidates.find { |candidate| @executable.call(candidate) } || raise_not_found(@candidates)
     end
 
     private
@@ -25,16 +34,14 @@ module Wip
       @path.split(File::PATH_SEPARATOR).any? { |directory| File.executable?(File.join(directory, command)) }
     end
 
-    def raise_not_found
+    def raise_not_found(attempted)
       raise CommandNotFoundError, <<~MESSAGE
-        WSLC was not found.
+        #{@label} was not found.
 
         Checked:
-          #{CANDIDATES.join("\n  ")}
-
-        Install or update the WSL container tooling, then run:
+          #{attempted.join("\n  ")}
 
-          wip doctor
+        #{@install_hint}
       MESSAGE
     end
   end

data/lib/wip/compose_bridge.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Wip
+  # Builds argument arrays for wslc-compose invocations, delegating orchestration
+  # to a real compose.yml instead of wip's own dependencies:/network handling.
+  class ComposeBridge
+    FILENAMES = %w[compose.yml compose.yaml docker-compose.yml docker-compose.yaml].freeze
+    # No default candidates: wip doesn't favor any one compose-for-wslc implementation.
+    # compose.command must name the one you've installed.
+    INSTALL_HINT = <<~HINT.chomp
+      wip doesn't bundle or pin a compose-for-wslc implementation — install one and set
+      compose.command in wip.yml to its binary name or path, e.g.:
+
+        https://github.com/bacarndiaye/wslc-compose
+        https://github.com/inuyume/wslc-compose
+    HINT
+
+    def self.for(config, resolver: CommandResolver.new(candidates: [], label: 'compose command',
+                                                       install_hint: INSTALL_HINT))
+      new(compose_command: resolver.resolve(config.compose_command), file: file_path(config),
+          project: config.compose_project)
+    end
+
+    def self.file_path(config)
+      base = Pathname(config.path).dirname
+      configured = config.compose_file
+      # Relative compose.file is resolved against wip.yml, not the current directory,
+      # so `wip` behaves the same from any subdirectory (matching auto-detection below).
+      return base.join(configured).expand_path if configured
+
+      FILENAMES.map { |name| base.join(name) }.find(&:file?) ||
+        raise(ConfigError, "compose mode: no compose file found next to #{config.path} " \
+                           "(looked for #{FILENAMES.join(', ')})")
+    end
+
+    def initialize(compose_command:, file:, project: nil)
+      @compose_command = compose_command
+      @file = file
+      @project = project
+    end
+
+    def up(detach: true)
+      command = base.push('up')
+      command << '-d' if detach
+      command
+    end
+
+    def down = base.push('down')
+
+    def exec(service, arguments, interactive: true)
+      command = base.push('exec')
+      command << '-T' unless interactive
+      command.push(service.to_s).concat(arguments)
+    end
+
+    def logs(services: [], follow: true)
+      command = base.push('logs')
+      command << '-f' if follow
+      command.concat(services.map(&:to_s))
+    end
+
+    private
+
+    def base
+      command = [@compose_command, '-f', @file.to_s]
+      command.push('-p', @project) if @project
+      command
+    end
+  end
+end

data/lib/wip/config.rb

@@ -20,6 +20,19 @@ module Wip
     def up_command = @raw.dig('up', 'command')
     def dependencies = @raw['dependencies'] || {}
     def network = defaults['network']
+    def compose = @raw['compose']
+    def compose? = !!compose
+    def compose_service = compose && compose['service']
+    def compose_file = compose && compose['file']
+    def compose_project = compose && compose['project']
+    def compose_command = compose && compose['command']
+    def sync? = !!sync
+
+    def sync
+      return @sync if defined?(@sync)
+
+      @sync = @raw.key?('sync') ? build_sync : nil
+    end
 
     def command(name)
       entry = commands[name.to_s]
@@ -37,7 +50,8 @@ module Wip
 
     def to_h(redact: true)
       value = { 'version' => 1, 'wslc' => { 'command' => wslc_command }, 'defaults' => defaults,
-                'up' => { 'command' => up_command }, 'dependencies' => dependencies,
+                'up' => { 'command' => up_command }, 'dependencies' => dependencies, 'compose' => compose,
+                'sync' => sync&.to_h,
                 'commands' => commands.transform_values { |entry| defaults.merge('type' => 'exec').merge(entry) } }
       redact ? redact_secrets(value) : value
     end
@@ -50,6 +64,18 @@ module Wip
 
       validate_commands!
       validate_dependencies!
+      validate_compose!
+      validate_sync!
+    end
+
+    def build_sync
+      SyncSettings.new(@raw['sync'], base: path && File.dirname(path.to_s),
+                                     workdir: defaults['workdir'], container: defaults['container'])
+    end
+
+    def validate_sync!
+      return unless sync
+      raise ConfigError, 'sync is mutually exclusive with compose' if compose?
     end
 
     def validate_commands!
@@ -64,6 +90,15 @@ module Wip
       dependencies.each { |name, entry| validate_dependency!(name, entry) }
     end
 
+    def validate_compose!
+      return unless @raw.key?('compose')
+      raise ConfigError, 'compose must be a mapping' unless compose.is_a?(Hash)
+      raise ConfigError, 'compose.service must not be empty' if compose_service.to_s.empty?
+      raise ConfigError, 'compose.command must not be empty' if compose_command.to_s.empty?
+      raise ConfigError, 'compose is mutually exclusive with dependencies' if dependencies.any?
+      raise ConfigError, 'compose is mutually exclusive with defaults.network' if network
+    end
+
     def validate_command!(name, entry)
       raise ConfigError, "commands.#{name} must be a mapping" unless entry.is_a?(Hash)
 

data/lib/wip/doctor.rb

@@ -7,10 +7,13 @@ module Wip
   class Doctor
     Result = Data.define(:level, :message)
 
-    def initialize(loader:, resolver: CommandResolver.new, environment: Environment.new)
+    def initialize(loader:, resolver: CommandResolver.new, environment: Environment.new,
+                   compose_resolver: CommandResolver.new(candidates: [], label: 'compose command',
+                                                         install_hint: ComposeBridge::INSTALL_HINT))
       @loader = loader
       @resolver = resolver
       @environment = environment
+      @compose_resolver = compose_resolver
     end
 
     def call
@@ -18,9 +21,7 @@ module Wip
       results << result(@environment.wsl2? ? :ok : :fail, *wsl2_messages)
       results << interop_result unless @environment.windows?
       results << Result.new(:ok, "Architecture: #{@environment.architecture}")
-      config = load_config(results)
-      command = resolve(config, results) if config
-      check_version(command, results) if command
+      check_config(load_config(results), results)
       results << result(command_available?('git') ? :ok : :warn, 'Git is available',
                         'Git is not available to the WSLC build environment')
       results
@@ -41,7 +42,7 @@ module Wip
 
     def load_config(results)
       config = @loader.load
-      invalid = %w[container image].select { |key| config.defaults[key].to_s.empty? }
+      invalid = config.compose? ? [] : %w[container image].select { |key| config.defaults[key].to_s.empty? }
       results << Result.new(invalid.empty? ? :ok : :fail,
                             invalid.empty? ? 'Loaded wip.yml' : "Empty defaults: #{invalid.join(', ')}")
       config
@@ -50,6 +51,19 @@ module Wip
       nil
     end
 
+    def check_config(config, results)
+      return unless config
+
+      check_wslc(config, results)
+      check_compose(config, results) if config.compose?
+      check_sync(config, results) if config.sync?
+    end
+
+    def check_wslc(config, results)
+      command = resolve(config, results)
+      check_version(command, results) if command
+    end
+
     def resolve(config, results)
       command = @resolver.resolve(config.wslc_command)
       results << Result.new(:ok, "Found #{command}")
@@ -59,12 +73,42 @@ module Wip
       nil
     end
 
-    def check_version(command, results)
+    def check_version(command, results, label: 'WSLC')
       _output, status = Open3.capture2e(command, 'version')
       results << Result.new(status.success? ? :ok : :fail,
-                            status.success? ? 'WSLC is available' : 'WSLC version failed')
+                            status.success? ? "#{label} is available" : "#{label} version failed")
     rescue Errno::ENOENT
-      results << Result.new(:fail, 'WSLC version failed')
+      results << Result.new(:fail, "#{label} version failed")
+    end
+
+    def check_compose(config, results)
+      command = resolve_compose(config, results)
+      check_version(command, results, label: 'compose command') if command
+      check_compose_file(config, results)
+    end
+
+    def resolve_compose(config, results)
+      command = @compose_resolver.resolve(config.compose_command)
+      results << Result.new(:ok, "Found #{command}")
+      command
+    rescue CommandNotFoundError => e
+      results << Result.new(:fail, e.message)
+      nil
+    end
+
+    def check_compose_file(config, results)
+      path = ComposeBridge.file_path(config)
+      results << result(path.file? ? :ok : :fail, "Found compose file #{path}",
+                        "Compose file not found: #{path}")
+    rescue ConfigError => e
+      results << Result.new(:fail, e.message)
+    end
+
+    def check_sync(config, results)
+      sync = config.sync
+      results << result(File.directory?(sync.source) ? :ok : :fail,
+                        "Sync source #{sync.source} mirrors into volume #{sync.volume} at #{sync.target}",
+                        "Sync source not found: #{sync.source}")
     end
 
     def result(condition, ok_message, fail_message)

data/lib/wip/error_interpreter.rb

@@ -3,6 +3,14 @@
 module Wip
   # Translates raw WSLC error output into friendlier hints.
   class ErrorInterpreter
+    # Shells report a missing rsync as "rsync: not found", while the container
+    # runtime names the executable either before or after its own phrasing.
+    RSYNC_MISSING = Regexp.union(
+      /rsync: (?:command )?not found/i,
+      /rsync[^\n]*executable file not found/i,
+      /executable file not found[^\n]*rsync/i
+    )
+
     def initialize(architecture: Environment.new.architecture)
       @architecture = architecture
     end
@@ -11,11 +19,24 @@ module Wip
       case output
       when /pull access denied|insufficient_scope|authorization failed/i then registry_message
       when %r{no matching manifest for linux/(?:amd64|arm64)}i then architecture_message
+      when RSYNC_MISSING then rsync_message
       end
     end
 
     private
 
+    def rsync_message
+      <<~TEXT
+        `wip sync` needs rsync inside the image.
+
+        Install it in your Dockerfile:
+
+          RUN apt-get update && apt-get install -y rsync
+
+        Or point sync.command at a tool the image already has.
+      TEXT
+    end
+
     def registry_message
       <<~TEXT
         The container registry rejected the request.

data/lib/wip/sync_settings.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Wip
+  # Validated access to the `sync:` block, which mirrors the host source tree
+  # into a named volume instead of bind-mounting it live.
+  #
+  # A bind-mounted app directory is shared into the container's VM over
+  # virtiofs, so every stat/open a boot-time directory scan makes is a round
+  # trip. Mirroring the tree into a named volume (native storage inside the VM)
+  # and re-running the mirror on demand keeps the edit-on-the-host workflow
+  # while leaving the running app on fast disk.
+  class SyncSettings
+    DEFAULT_MOUNT = '/host-src'
+    DEFAULT_TARGET = '/app'
+    DEFAULT_BINARY = 'rsync'
+    DEFAULT_INTERVAL = 2
+    # -a preserves modes and timestamps so file watchers and bundler see a
+    # faithful copy rather than a tree that looks freshly written every sync.
+    BASE_OPTIONS = %w[-a].freeze
+    # Trailing mount options wslc/docker accept after the container path.
+    VOLUME_MODES = %w[ro rw z Z cached delegated consistent].freeze
+
+    attr_reader :target, :mount, :volume, :exclude, :binary, :extra_options, :interval
+
+    def initialize(raw, base: nil, workdir: nil, container: nil)
+      raise ConfigError, 'sync must be a mapping' unless raw.is_a?(Hash)
+
+      @base = base
+      assign_paths(raw, workdir: workdir, container: container)
+      assign_mirror(raw)
+      validate!
+    end
+
+    def delete? = !!@delete
+
+    # Expanded against the wip.yml directory so the mirror covers the same tree
+    # no matter which subdirectory wip was invoked from.
+    def source
+      @source ||= @base ? Pathname(@base).join(@raw_source).expand_path.to_s : @raw_source
+    end
+
+    # What `-v` specs the main container needs: the source read-only, and the
+    # named volume where the app actually runs.
+    def volume_specs = ["#{source}:#{mount}:ro", "#{volume}:#{target}"]
+
+    # True for a configured volume that sync replaces, so `.:/app` in
+    # `defaults.volumes` quietly becomes the read-only mount plus the volume.
+    def replaces?(spec)
+      [target.chomp('/'), mount.chomp('/')].include?(container_path(spec))
+    end
+
+    # Trailing slashes matter to rsync: they copy the *contents* of the mount
+    # into the target rather than nesting it one directory deeper.
+    def mirror_command
+      command = [binary, *BASE_OPTIONS]
+      command << '--delete' if delete?
+      command.concat(exclude.map { |pattern| "--exclude=#{pattern}" })
+      command.concat(extra_options)
+      command.push("#{mount.chomp('/')}/", "#{target.chomp('/')}/")
+    end
+
+    def to_h
+      { 'source' => source, 'target' => target, 'mount' => mount, 'volume' => volume,
+        'delete' => delete?, 'exclude' => exclude, 'command' => binary, 'options' => extra_options,
+        'interval' => interval }
+    end
+
+    private
+
+    def assign_paths(raw, workdir:, container:)
+      @raw_source = presence(raw['source']) || '.'
+      @target = presence(raw['target']) || presence(workdir) || DEFAULT_TARGET
+      @mount = presence(raw['mount']) || DEFAULT_MOUNT
+      @volume = presence(raw['volume']) || "#{presence(container) || 'wip'}-src"
+    end
+
+    def assign_mirror(raw)
+      @delete = raw.fetch('delete', true)
+      @exclude = Array(raw['exclude']).map(&:to_s)
+      @binary = presence(raw['command']) || DEFAULT_BINARY
+      @extra_options = Array(raw['options']).map(&:to_s)
+      @interval = raw.key?('interval') ? raw['interval'] : DEFAULT_INTERVAL
+    end
+
+    def validate!
+      raise ConfigError, 'sync.target must be an absolute path' unless @target.start_with?('/')
+      raise ConfigError, 'sync.mount must be an absolute path' unless @mount.start_with?('/')
+      raise ConfigError, 'sync.mount must differ from sync.target' if @mount.chomp('/') == @target.chomp('/')
+      return if @interval.is_a?(Numeric) && @interval.positive?
+
+      raise ConfigError, 'sync.interval must be a positive number'
+    end
+
+    def container_path(spec)
+      parts = spec.to_s.split(':')
+      parts.pop if parts.size > 2 && VOLUME_MODES.include?(parts.last)
+      parts.last.to_s.chomp('/')
+    end
+
+    def presence(value) = value.to_s.empty? ? nil : value.to_s
+  end
+end

data/lib/wip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wip
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end

data/lib/wip.rb

@@ -2,6 +2,7 @@
 
 require_relative 'wip/version'
 require_relative 'wip/errors'
+require_relative 'wip/sync_settings'
 require_relative 'wip/config'
 require_relative 'wip/config_loader'
 require_relative 'wip/environment'
@@ -11,6 +12,7 @@ require_relative 'wip/build_context'
 require_relative 'wip/command_resolver'
 require_relative 'wip/error_interpreter'
 require_relative 'wip/command_builder'
+require_relative 'wip/compose_bridge'
 require_relative 'wip/command_display'
 require_relative 'wip/command_runner'
 require_relative 'wip/resource_monitor'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wslc-wip
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Wip contributors
@@ -39,6 +39,7 @@ files:
 - lib/wip/command_display.rb
 - lib/wip/command_resolver.rb
 - lib/wip/command_runner.rb
+- lib/wip/compose_bridge.rb
 - lib/wip/config.rb
 - lib/wip/config_loader.rb
 - lib/wip/debug_reporter.rb
@@ -49,6 +50,7 @@ files:
 - lib/wip/error_interpreter.rb
 - lib/wip/errors.rb
 - lib/wip/resource_monitor.rb
+- lib/wip/sync_settings.rb
 - lib/wip/version.rb
 homepage: https://wslc-wip.slidict.com/
 licenses: