wslc-wip 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afc914ac16e4359e48e682f5dab523827ad782251365abee7abd60b6eee89044
-  data.tar.gz: dcc97ec1bace3262bc1c419162085de6a3f5e24f0dde8babb2532ef9bdd6446c
+  metadata.gz: f34ba1e90b936146999504b8db29e2b0376efd4b1bf8faa65a398e8ae7758a6c
+  data.tar.gz: 94945faa2bb0d04ed9cc5159ab21d9ad1811bf8bdbd8e1049b22e91acf282f24
 SHA512:
-  metadata.gz: 526f9730c15eb6beabda31c3df3ee95cac2f8058c6da2dddf27100aadb48276bb68d66a3ede2b7383f49ecb6cd6fd45604b39ec1130058718cfbf439e7629f5a
-  data.tar.gz: 87a5f6c40e948fabdc79eeaf3e81cb73fac3cdb0fdd306189a72a437f459de22deeb57fbd92167411c157485d66dd82f40734f72316f46cb65fe6aa74b111511
+  metadata.gz: e3420daa82aa13024e1c8d4331170be74e76249fe044c4f051a58e412bba33ea0b3481c0bccdab813868b719dba61c0f30c8af7becb4b37a0f6bb35eb9edfab7
+  data.tar.gz: 23b08e3581ff3ffc6967125a339c02d82197f0247070f57ff0cff6b62c7065558ad36c18524c682a870d6c093d5ff7485fb00962d350bc341c41bcd203442c13

data/README.md

@@ -31,6 +31,7 @@ From source: `bundle install && bundle exec exe/wip version`.
 ```bash
 gem install wslc-wip
 cd my-project
+wip init   # writes a starter wip.yml; edit the TODOs, then:
 wip doctor
 wip build
 wip up -d
@@ -44,27 +45,28 @@ Put a `wip.yml` in your project root. Running from a subdirectory walks up to fi
 
 ```yaml
 version: 1
-mode: container # or compose; picks the orchestration path `up`/`down`/`sync`/etc. take (default: container)
+mode: container # default. This example is container mode end-to-end — see "Compose mode" below
+                # for mode: compose, which replaces container:/network:/dependencies: with a
+                # compose: block instead; the two don't mix within one wip.yml.
 wslc:
   command: auto # tries wslc.exe, wslc, then System32; an absolute path also works
-defaults:
-  container: app
-  image: slidict/slidict:development
-  workdir: /app
-  interactive: false
-  remove: true
-  network: app-tier # optional; shared with `dependencies` so containers can resolve each other by name
-  env:
-    RAILS_ENV: development
-    PORT: "3000"
-  ports:
-    - "3000:3000"
-  volumes:
-    - ".:/app"
-up:
-  command: server # command `wip up` passes to the image when it creates the container
-                   # (omit to use the image's default CMD)
+container: app # optional; which dependencies: entry `up`/`exec`/`run`/`build`/`commands:` target (default: app)
+network: app-tier # optional; shared by every dependencies: entry so containers can resolve each other by name
 dependencies:
+  app: # container: points here — the one container wip execs into and runs commands in
+    image: slidict/slidict:development
+    workdir: /app
+    interactive: false
+    remove: true
+    command: server # extra args appended when `wip up` creates the container
+                     # (omit to use the image's default CMD)
+    env:
+      RAILS_ENV: development
+      PORT: "3000"
+    ports:
+      - "3000:3000"
+    volumes:
+      - ".:/app"
   redis:
     image: redis:latest
   development.mysql:
@@ -114,9 +116,9 @@ instead.
 Like `docker compose`, `wip` automatically loads a `.env` file next to `wip.yml` (one `KEY=VALUE`
 per line; `#` comments, blank lines, `export` prefixes, and quoted values are all supported) and
 passes its keys through as container environment variables on `build`, `up`, `run`, `exec`, and
-custom commands. `.env` only fills in keys that aren't already set by `defaults.env` or a
-command/dependency's own `env` — those always win on conflict. Pass `--env-file PATH` to load a
-different file instead.
+custom commands. `.env` only fills in keys that aren't already set by the primary container's
+`env` or a command/dependency's own `env` — those always win on conflict. Pass `--env-file PATH`
+to load a different file instead.
 
 ### .dockerignore
 
@@ -127,13 +129,19 @@ directly with no copying.
 
 ### Dependency containers
 
-If your app needs sidecar services (a database, Redis, ...), declare them under `dependencies`
-and set `defaults.network`. `wip up` creates the network first (if it doesn't exist), then brings
-up each dependency by name before the main container — so `bin/rails c` (or anything else run
-inside the main container) can reach `development.mysql`/`redis`/etc. by their dependency name,
-the same way Compose's service names resolve. `wip down` tears the main container and all
-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`.
+`dependencies:` holds every container uniformly — the primary one `container:` points at (`app`
+by default) and any sidecar services (a database, Redis, ...) alongside it. Each entry accepts
+`image` (required), `command`, `env`, `ports`, `volumes`, and `workdir`; there's no separate,
+differently-shaped block for "the one you exec into."
+
+What sets the primary entry apart is operational, not structural: `wip up` brings up every other
+entry by name first (creating `network:` beforehand if it doesn't exist and set), then boots or
+starts the primary one — so `bin/rails c` (or anything else run inside it) can reach
+`development.mysql`/`redis`/etc. by their dependency name, the same way Compose's service names
+resolve. `wip down` tears the primary container and all sidecars down (the network itself is left
+in place). Only the primary container is a target for `exec`/`run`/`build`/`commands:` — sidecars
+are only ever started and stopped, matching Compose's own service-vs-you-exec-into-one-of-them
+split.
 
 ### Source sync
 
@@ -146,8 +154,8 @@ 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")
+  target: /app       # container path served by the volume (default: the primary container's workdir, else /app)
+  volume: app-src    # named volume holding the mirror (default: "<container>-src")
   mount: /host-src   # where the source is bind-mounted read-only (default: /host-src)
   exclude:           # rsync --exclude patterns
     - .git
@@ -159,14 +167,17 @@ sync:
   interval: 2        # seconds between syncs for `wip sync --watch` (default: 2)
   mode: exec         # exec (mirror inside the running container) or run (a throwaway one);
                       # default: exec for `mode: container`, run for `mode: compose`
+  image: null        # image for the mirror container; required under mode: compose (there's no
+                      # dependencies: entry to borrow one from there), unused under mode: container
+                      # unless set (falls back to the primary container's own image)
 ```
 
 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.
+- Any `volumes` entry on the primary container 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 sidecar
+  `dependencies:` entries 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: `sync.mode: exec` (the default under `mode: container`) execs
@@ -186,11 +197,31 @@ image already has. And the mirror is one-way (host → volume): anything the app
 `target` is removed by the next `--delete` pass unless you `exclude` it, give it its own volume,
 or set `delete: false`.
 
-`sync:` works alongside `mode: compose` too. Compose still owns the volume layout — a compose
-service must mount the same named volume `sync.volume` names — but wip's mirror runs as its own
-throwaway container (`sync.mode` defaults to `run` and can't be set to `exec` under `mode:
-compose`, since only a container wip itself booted is guaranteed to have the read-only source
-mount attached).
+`sync:` works alongside `mode: compose` too, but two things change:
+
+- Compose still owns the volume layout, so wip doesn't rewrite any mounts for you: the compose
+  service that runs your app must itself declare a named volume with the exact same name as
+  `sync.volume` (`<container>-src` by default) mounted at the path your app expects, e.g.:
+  ```yaml
+  # compose.yml
+  services:
+    app:
+      volumes:
+        - app-src:/app
+  volumes:
+    app-src:
+  ```
+  wip's mirror writes into that volume from a separate, disposable container; it never touches
+  the compose service directly.
+- `sync.mode` defaults to `run` and can't be set to `exec` (only a container wip itself booted is
+  guaranteed to have the read-only source mount attached, which compose services never do), and
+  `sync.image` becomes required, since that disposable container needs an image from somewhere —
+  under `mode: container` it borrows the primary `dependencies:` entry's image, but compose mode
+  has no such entry to borrow from.
+
+`wip up`'s pre-boot mirror (and the `--no-sync` flag that skips it) works the same way under
+`mode: compose` as it does otherwise: the source is mirrored into the volume before
+`compose up` starts the service that mounts it.
 
 ### Compose mode
 
@@ -207,9 +238,9 @@ compose:
   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.
+`compose:` is mutually exclusive with `dependencies:`/`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,
@@ -238,12 +269,13 @@ found, its version, and which compose file `wip` resolved.
 
 | Command | Description |
 |---|---|
+| `wip init [--force]` | Write a starter `wip.yml`: `mode: compose` if a `compose.yml`/`docker-compose.yml` is found next to it, `mode: container` otherwise. Refuses to overwrite an existing `wip.yml` unless `--force` |
 | `wip version` | wip's version, plus WSLC's if it can be detected |
 | `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] [--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 up [-d] [--no-sync]` | Start the primary `dependencies:` entry (`container:`, default `app`) and its sidecars (creating any that are missing, on `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 the primary container and its sidecar `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 (compose mode: `exec`s into `compose.service` instead) |
 | `wip shell` | Open the configured shell, falling back to `bash` then `sh` |
@@ -375,7 +407,7 @@ plugins are all unimplemented.
 
 `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
+sidecar services via `dependencies:` + `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
@@ -402,8 +434,8 @@ for `wip`, roughly in priority order:
    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.
+`container`, `network`, `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

@@ -39,6 +39,17 @@ module Wip
       nil
     end
 
+    desc 'init', 'Create a starter wip.yml (detects an existing compose.yml/docker-compose.yml)'
+    option :force, type: :boolean, default: false, desc: 'Overwrite an existing wip.yml'
+    def init
+      path = Pathname(options[:config] || ConfigLoader::FILENAME).expand_path
+      raise Error, "#{path} already exists (use --force to overwrite)" if path.file? && !options[:force]
+
+      initializer = Initializer.new(dir: path.dirname)
+      path.write(initializer.call)
+      warn "wip: wrote #{path} (mode: #{initializer.compose? ? 'compose' : 'container'})"
+    end
+
     desc 'doctor', 'Diagnose the development environment'
     def doctor
       results = Doctor.new(loader: loader).call
@@ -55,7 +66,7 @@ module Wip
     def build(*extra)
       extra.shift if extra.first == '--'
       settings = load_config.command('build') || {}
-      context = settings['context'] || load_config.defaults['context'] || '.'
+      context = settings['context'] || '.'
       BuildContext.new(context).stage do |staged_context|
         execute(builder.build(settings: settings.merge('context' => staged_context), extra: extra))
       end
@@ -66,11 +77,12 @@ module Wip
     option :sync, type: :boolean, default: true, desc: 'Mirror the source into the sync volume first (--no-sync skips)'
     def up
       if load_config.compose?
+        sync_before_boot if options[:sync]
         return execute(compose_bridge.up(detach: options[:detach]), interactive: tty?(!options[:detach]))
       end
 
       ensure_network
-      load_config.dependencies.each_key { |name| ensure_dependency(name) }
+      sidecar_names.each { |name| ensure_dependency(name) }
       sync_before_boot if options[:sync]
       ensure_container
     end
@@ -100,7 +112,7 @@ module Wip
 
       execute(builder.down, exit_on_failure: false)
       execute(builder.remove, exit_on_failure: false)
-      load_config.dependencies.each_key do |name|
+      sidecar_names.each do |name|
         execute(builder.dependency_down(name), exit_on_failure: false)
         execute(builder.dependency_remove(name), exit_on_failure: false)
       end
@@ -239,6 +251,11 @@ module Wip
       false
     end
 
+    # dependencies: holds every container uniformly, including the primary one
+    # `container:` points at; that one gets its own up/down/start/find via
+    # ensure_container, so it's excluded here to avoid double-starting it.
+    def sidecar_names = load_config.dependencies.keys - [load_config.container]
+
     def ensure_dependency(name)
       if resource_exists?(builder.dependency_find(name))
         warn "wip: starting existing dependency '#{name}'"
@@ -289,7 +306,7 @@ module Wip
     end
 
     def ensure_container
-      container = load_config.defaults['container']
+      container = load_config.container
       interactive = tty?(!options[:detach])
       if resource_exists?(builder.find)
         warn "wip: starting existing container '#{container}'"

data/lib/wip/command_builder.rb

@@ -13,14 +13,17 @@ module Wip
     end
 
     def exec(arguments, settings: {}, interactive: true)
-      values = @config.defaults.merge(settings)
+      # dependencies: entries don't carry their own name (it's the hash key), so the
+      # exec target defaults to @config.container; a commands: entry can still
+      # redirect it by setting its own `container:`.
+      values = primary_values.merge('container' => @config.container).merge(settings)
       command = [@wslc, 'exec']
       command << '-it' if tty?(interactive)
       command.concat(options(values, include_container: true, include_publish: false)).concat(arguments)
     end
 
     def run(arguments, settings: {}, interactive: true)
-      values = @config.defaults.merge(settings)
+      values = primary_values.merge(settings)
       command = [@wslc, 'run']
       command << '--rm' if values['remove']
       command << '-it' if tty?(interactive)
@@ -28,35 +31,36 @@ module Wip
     end
 
     def up(detach: false)
-      values = @config.defaults
-      command = [@wslc, 'run', '--name', required(values, 'container')]
+      values = primary_values
+      command = [@wslc, 'run', '--name', @config.container]
       command.push('--network', @config.network) if @config.network
       command << '-d' if detach
       command << '-it' if !detach && tty?(true)
       command.concat(options(values)).push(required(values, 'image'))
-      command.concat(Shellwords.split(@config.up_command.to_s)) if @config.up_command
+      command.concat(Shellwords.split(values['command'].to_s)) unless values['command'].to_s.empty?
       command
     end
 
     def start(detach: false)
-      command = [@wslc, 'start', required(@config.defaults, 'container')]
+      command = [@wslc, 'start', @config.container]
       command.push('-a', '-i') unless detach
       command
     end
 
     def find
-      container = required(@config.defaults, 'container')
-      [@wslc, 'list', '--all', '--filter', "name=#{container}", '--format', 'json']
+      [@wslc, 'list', '--all', '--filter', "name=#{@config.container}", '--format', 'json']
     end
 
     # Mirrors into the volume from a throwaway container. Used for sync.mode:
     # run (compose's default, and mode: container's fallback for when the app
-    # container isn't running yet — e.g. just before `up` boots it).
+    # container isn't running yet — e.g. just before `up` boots it). sync.image
+    # overrides the mirror container's image; compose mode requires it, since
+    # there's no dependencies: entry to fall back to (compose owns those).
     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)
+      command.push(sync.image || required(primary_values, 'image')).concat(sync.mirror_command)
     end
 
     # Mirrors from inside the already-running container. Only valid for
@@ -64,15 +68,15 @@ module Wip
     # itself booted is guaranteed to have both the read-only source mount and
     # the volume attached.
     def sync_exec
-      [@wslc, 'exec', required(@config.defaults, 'container'), *required_sync.mirror_command]
+      [@wslc, 'exec', @config.container, *required_sync.mirror_command]
     end
 
     def down
-      [@wslc, 'stop', required(@config.defaults, 'container')]
+      [@wslc, 'stop', @config.container]
     end
 
     def remove
-      [@wslc, 'remove', '-f', required(@config.defaults, 'container')]
+      [@wslc, 'remove', '-f', @config.container]
     end
 
     def network_create
@@ -110,7 +114,7 @@ module Wip
     end
 
     def build(settings:, extra: [])
-      values = @config.defaults.merge(settings)
+      values = primary_values.merge(settings)
       context = values['context'] || '.'
       tag = values['tag'] || values['image']
       raise ConfigError, 'Build image/tag must not be empty' if tag.to_s.empty?
@@ -154,7 +158,7 @@ module Wip
       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.
+    # .env supplies defaults; env set in wip.yml (primary or per-command) wins on conflict.
     def merged_env(values) = @dotenv.merge(values.fetch('env', {}))
 
     def required(values, key)
@@ -178,5 +182,10 @@ module Wip
     def dependency_values(name)
       @config.dependency(name) || raise(ConfigError, "Unknown dependency: #{name}")
     end
+
+    def primary_values
+      @config.primary || raise(ConfigError, "No dependencies.#{@config.container} entry " \
+                                            '(set container: to name a different one)')
+    end
   end
 end

data/lib/wip/config.rb

@@ -3,8 +3,10 @@
 module Wip
   # Validated, defaulted access to a parsed wip.yml document.
   class Config
-    DEFAULTS = { 'container' => 'app', 'workdir' => '/app', 'interactive' => false,
-                 'remove' => true, 'env' => {}, 'ports' => [], 'volumes' => [] }.freeze
+    # Applied to every dependencies: entry, primary container included — there
+    # is no separate, differently-shaped bucket for "the one you exec into."
+    DEPENDENCY_DEFAULTS = { 'workdir' => nil, 'interactive' => false, 'remove' => true,
+                            'env' => {}, 'ports' => [], 'volumes' => [] }.freeze
     SECRET_PATTERN = /token|password|secret|credential|auth/i
     # Which orchestration path `up`/`down`/`sync`/etc. take. Explicit rather than
     # inferred from a `compose:` block's presence, so a config reader doesn't have
@@ -20,10 +22,12 @@ module Wip
 
     def wslc_command = @raw.dig('wslc', 'command') || 'auto'
     def commands = @raw['commands'] || {}
-    def defaults = DEFAULTS.merge(@raw['defaults'] || {})
-    def up_command = @raw.dig('up', 'command')
     def dependencies = @raw['dependencies'] || {}
-    def network = defaults['network']
+    # Which dependencies: entry `up`/`down`/`exec`/`run`/`build`/`commands:` target
+    # by default — the one container wip itself considers "the app." Everything
+    # else in dependencies: is a sidecar wip only starts and stops.
+    def container = presence(@raw['container']) || 'app'
+    def network = @raw['network']
     def mode = @raw['mode'] || 'container'
     def compose = @raw['compose']
     def compose? = mode == 'compose'
@@ -39,25 +43,29 @@ module Wip
       @sync = @raw.key?('sync') ? build_sync : nil
     end
 
+    # The dependencies: entry `container` points at, or nil if it isn't defined.
+    def primary = dependency(container)
+
     def command(name)
       entry = commands[name.to_s]
       return unless entry
 
-      defaults.merge('type' => 'exec').merge(entry)
+      (primary || {}).merge('type' => 'exec').merge(entry)
     end
 
     def dependency(name)
       entry = dependencies[name.to_s]
       return unless entry
 
-      { 'workdir' => nil, 'env' => {}, 'ports' => [], 'volumes' => [] }.merge(entry)
+      DEPENDENCY_DEFAULTS.merge(entry)
     end
 
     def to_h(redact: true)
-      value = { 'version' => 1, 'wslc' => { 'command' => wslc_command }, 'defaults' => defaults,
-                'up' => { 'command' => up_command }, 'mode' => mode, 'dependencies' => dependencies,
-                'compose' => compose, 'sync' => sync&.to_h,
-                'commands' => commands.transform_values { |entry| defaults.merge('type' => 'exec').merge(entry) } }
+      value = { 'version' => 1, 'wslc' => { 'command' => wslc_command }, 'mode' => mode, 'container' => container,
+                'network' => network, 'dependencies' => dependencies, 'compose' => compose, 'sync' => sync&.to_h,
+                'commands' => commands.transform_values do |entry|
+                  (primary || {}).merge('type' => 'exec').merge(entry)
+                end }
       redact ? redact_secrets(value) : value
     end
 
@@ -65,7 +73,6 @@ module Wip
 
     def validate!
       raise ConfigError, "Unsupported configuration version: #{@raw['version']}" unless (@raw['version'] || 1) == 1
-      raise ConfigError, 'up must be a mapping' if @raw.key?('up') && !@raw['up'].is_a?(Hash)
 
       validate_mode!
       validate_commands!
@@ -76,7 +83,7 @@ module Wip
 
     def build_sync
       SyncSettings.new(@raw['sync'], base: path && File.dirname(path.to_s),
-                                     workdir: defaults['workdir'], container: defaults['container'],
+                                     workdir: primary && primary['workdir'], container: container,
                                      compose: compose?)
     end
 
@@ -110,7 +117,7 @@ module Wip
       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
+      raise ConfigError, 'compose is mutually exclusive with network' if network
     end
 
     def validate_command!(name, entry)
@@ -143,5 +150,7 @@ module Wip
 
       object.to_h { |key, value| [key, key.match?(SECRET_PATTERN) ? '[REDACTED]' : redact_secrets(value)] }
     end
+
+    def presence(value) = value.to_s.empty? ? nil : value.to_s
   end
 end

data/lib/wip/doctor.rb

@@ -42,15 +42,22 @@ module Wip
 
     def load_config(results)
       config = @loader.load
-      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(', ')}")
+      results << Result.new(*container_result(config))
       config
     rescue ConfigError => e
       results << Result.new(:fail, e.message)
       nil
     end
 
+    # dependencies.<container> having an empty image is already a load-time
+    # ConfigError (validate_dependency!), so the only way to reach here with a
+    # broken primary container is `container:` naming an entry that isn't defined.
+    def container_result(config)
+      return [:ok, 'Loaded wip.yml'] if config.compose? || config.primary
+
+      [:fail, "No dependencies.#{config.container} entry"]
+    end
+
     def check_config(config, results)
       return unless config
 

data/lib/wip/initializer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Wip
+  # Builds a starter wip.yml. Detects an existing compose file next to the
+  # target (the same filenames ComposeBridge auto-detects) to decide between
+  # mode: compose and mode: container, since that's the one decision `wip
+  # init` can't leave to a placeholder.
+  class Initializer
+    CONTAINER_TEMPLATE = <<~YAML
+      version: 1
+      mode: container
+
+      dependencies:
+        app: # TODO: this is the container wip creates, execs into, and runs commands in
+          image: your/image:tag # TODO: image to run
+          workdir: /app # TODO: adjust to match your image, or delete this line
+
+      sync: {} # optional; mirrors the source into a named volume instead of bind-mounting it live
+    YAML
+
+    def initialize(dir: Dir.pwd)
+      @dir = dir
+    end
+
+    def compose? = !!compose_file
+
+    def call
+      compose? ? compose_template : CONTAINER_TEMPLATE
+    end
+
+    private
+
+    def compose_file
+      @compose_file ||= ComposeBridge::FILENAMES.find { |name| File.file?(File.join(@dir, name)) }
+    end
+
+    def compose_template
+      <<~YAML
+        version: 1
+        mode: compose
+
+        compose:
+          service: app # TODO: which service in #{compose_file} wip run/exec/NAME target
+          command: wslc-compose # TODO: the compose-for-wslc binary/path you have installed
+      YAML
+    end
+  end
+end

data/lib/wip/sync_settings.rb

@@ -32,7 +32,7 @@ module Wip
     # compose owns its own services' mounts and never guarantees that shape.
     SYNC_MODES = %w[exec run].freeze
 
-    attr_reader :target, :mount, :volume, :exclude, :binary, :extra_options, :interval, :mode
+    attr_reader :target, :mount, :volume, :exclude, :binary, :extra_options, :interval, :mode, :image
 
     def initialize(raw, base: nil, workdir: nil, container: nil, compose: false)
       raise ConfigError, 'sync must be a mapping' unless raw.is_a?(Hash)
@@ -57,8 +57,8 @@ module Wip
     # 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.
+    # True for a configured volume that sync replaces, so `.:/app` in the
+    # primary container's `volumes` quietly becomes the read-only mount plus the volume.
     def replaces?(spec)
       [target.chomp('/'), mount.chomp('/')].include?(container_path(spec))
     end
@@ -76,7 +76,7 @@ module Wip
     def to_h
       { 'source' => source, 'target' => target, 'mount' => mount, 'volume' => volume,
         'delete' => delete?, 'exclude' => exclude, 'command' => binary, 'options' => extra_options,
-        'interval' => interval, 'mode' => mode }
+        'interval' => interval, 'mode' => mode, 'image' => image }
     end
 
     private
@@ -98,13 +98,25 @@ module Wip
 
     def assign_mode(raw, compose:)
       @mode = presence(raw['mode']) || (compose ? 'run' : 'exec')
+      @image = presence(raw['image'])
       raise ConfigError, "sync.mode must be one of #{SYNC_MODES.join(', ')}" unless SYNC_MODES.include?(@mode)
+
+      validate_image!(compose)
       return unless compose && exec?
 
       raise ConfigError, 'sync.mode: exec needs mode: container (compose owns its services’ mounts, ' \
                          'so it can’t guarantee the running container has the sync mounts attached)'
     end
 
+    # compose mode has no dependencies: entry to fall back to for the mirror
+    # container's image, so sync.image can't be left implicit there.
+    def validate_image!(compose)
+      return if !compose || @image
+
+      raise ConfigError, 'sync.image is required under mode: compose (there’s no dependencies: entry ' \
+                         'to borrow the mirror container’s image from)'
+    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?('/')

data/lib/wip/version.rb

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

data/lib/wip.rb

@@ -13,6 +13,7 @@ require_relative 'wip/command_resolver'
 require_relative 'wip/error_interpreter'
 require_relative 'wip/command_builder'
 require_relative 'wip/compose_bridge'
+require_relative 'wip/initializer'
 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.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Wip contributors
@@ -49,6 +49,7 @@ files:
 - lib/wip/environment.rb
 - lib/wip/error_interpreter.rb
 - lib/wip/errors.rb
+- lib/wip/initializer.rb
 - lib/wip/resource_monitor.rb
 - lib/wip/sync_settings.rb
 - lib/wip/version.rb