wslc-wip 0.7.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39d1c4da0d3b7446f90692ccf3d16ed693613edce14fafc4941d9fd51732486b
-  data.tar.gz: bdd0f8e5b7a5a18ffd833d77844c5d0acf5638f0e0e2f2a337c0129b9cb0682a
+  metadata.gz: d16349112264f413d1492541731ec704d56616ccb4b05cef1f505d667a5d823d
+  data.tar.gz: 05f7f5819345079aa82e062ee368a3255f93bdeaa62cf55fda2621c2bd36c4ed
 SHA512:
-  metadata.gz: c5e3824808f307422ad5e6e402309242bb884bbcc2b3d708e8f576a97100a66fda81e20e5b63922b5123160c7348987716ca951e8de37f8a4875b522cd23d471
-  data.tar.gz: a187b673ed8efea261c2c8218e69940e1e5fd64cdc911ea2b217f2276eb72193d674c4933709ce1437f67359ac46376a3280b04c397d3f7e98d78f2492141624
+  metadata.gz: cdbeea98b7472f9ec6e1ccec8883bf136dfcb76164c2ba2d2ddbd63fe52f22c20f72a994a2a85527b1d9e7a7511016fe1b54ab64e678aca009530616887435f1
+  data.tar.gz: a6f524f41b20fe20af6262e3e22e2dafa924d37e31279ff21ed94268824587017ad94670084ae81aeb79513369a923d37011fd95bd9471a1e357551b90701769

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,6 +45,7 @@ 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)
 wslc:
   command: auto # tries wslc.exe, wslc, then System32; an absolute path also works
 defaults:
@@ -156,6 +158,8 @@ sync:
   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)
+  mode: exec         # exec (mirror inside the running container) or run (a throwaway one);
+                      # default: exec for `mode: container`, run for `mode: compose`
 ```
 
 Everything below `sync:` is optional — `sync: {}` alone already works. With it in place:
@@ -166,8 +170,10 @@ Everything below `sync:` is optional — `sync: {}` alone already works. With it
   `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` mirrors on demand: `sync.mode: exec` (the default under `mode: container`) execs
+  rsync inside the already-running container; `sync.mode: run` always uses a throwaway container
+  with the same mounts instead. Which one runs is fixed by config, not guessed at from whether a
+  container happens to be up.
 - `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.
@@ -181,8 +187,11 @@ 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:` is mutually exclusive with `compose:` — in compose mode the compose file owns the volume
-layout.
+`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).
 
 ### Compose mode
 
@@ -191,6 +200,7 @@ If your project already has a real `compose.yml`, don't duplicate it in `depende
 
 ```yaml
 version: 1
+mode: compose              # required to enable compose mode; a compose: block with no mode: compose is an error
 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
@@ -229,6 +239,7 @@ 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) |

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
@@ -271,15 +282,14 @@ module Wip
            "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.
+    # sync.mode picks the path explicitly (default: exec for mode: container,
+    # run for mode: compose) rather than probing whether a container happens
+    # to be running under a matching name.
     def run_sync(exit_on_failure: true)
-      command = container_running? ? builder.sync_exec : builder.sync_run
+      command = sync_settings!.exec? ? 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

data/lib/wip/command_builder.rb

@@ -49,13 +49,9 @@ 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.
+    # 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).
     def sync_run
       sync = required_sync
       command = [@wslc, 'run', '--rm']
@@ -63,8 +59,10 @@ module Wip
       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.
+    # Mirrors from inside the already-running container. Only valid for
+    # sync.mode: exec (mode: container's default), since only a container 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]
     end

data/lib/wip/config.rb

@@ -6,6 +6,10 @@ module Wip
     DEFAULTS = { 'container' => 'app', 'workdir' => '/app', '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
+    # to know that rule to predict which mode wip runs in.
+    MODES = %w[container compose].freeze
     attr_reader :path
 
     def initialize(raw, path = nil)
@@ -20,8 +24,9 @@ module Wip
     def up_command = @raw.dig('up', 'command')
     def dependencies = @raw['dependencies'] || {}
     def network = defaults['network']
+    def mode = @raw['mode'] || 'container'
     def compose = @raw['compose']
-    def compose? = !!compose
+    def compose? = mode == 'compose'
     def compose_service = compose && compose['service']
     def compose_file = compose && compose['file']
     def compose_project = compose && compose['project']
@@ -50,8 +55,8 @@ module Wip
 
     def to_h(redact: true)
       value = { 'version' => 1, 'wslc' => { 'command' => wslc_command }, 'defaults' => defaults,
-                'up' => { 'command' => up_command }, 'dependencies' => dependencies, 'compose' => compose,
-                'sync' => sync&.to_h,
+                '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) } }
       redact ? redact_secrets(value) : value
     end
@@ -62,6 +67,7 @@ module Wip
       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!
       validate_dependencies!
       validate_compose!
@@ -70,12 +76,20 @@ module Wip
 
     def build_sync
       SyncSettings.new(@raw['sync'], base: path && File.dirname(path.to_s),
-                                     workdir: defaults['workdir'], container: defaults['container'])
+                                     workdir: defaults['workdir'], container: defaults['container'],
+                                     compose: compose?)
     end
 
+    def validate_mode!
+      raise ConfigError, "mode must be one of #{MODES.join(', ')}" unless MODES.include?(mode)
+      raise ConfigError, 'mode: compose requires a compose: block' if compose? && !@raw.key?('compose')
+      raise ConfigError, 'a compose: block requires mode: compose' if @raw.key?('compose') && !compose?
+    end
+
+    # Forces SyncSettings to build (and so run its own validation, including
+    # sync.mode vs. mode) at load time instead of on first access.
     def validate_sync!
-      return unless sync
-      raise ConfigError, 'sync is mutually exclusive with compose' if compose?
+      sync if @raw.key?('sync')
     end
 
     def validate_commands!

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
+
+      defaults:
+        container: app # TODO: name of the container wip creates
+        image: your/image:tag # TODO: image to run
+        workdir: /app
+
+      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

@@ -26,19 +26,26 @@ module Wip
     BASE_OPTIONS = %w[-r -l -t --whole-file].freeze
     # Trailing mount options wslc/docker accept after the container path.
     VOLUME_MODES = %w[ro rw z Z cached delegated consistent].freeze
+    # exec mirrors inside the already-running, wip-managed container (fast,
+    # but only correct when wip itself created that container with the sync
+    # mounts attached). run always mirrors from a disposable container, since
+    # 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
+    attr_reader :target, :mount, :volume, :exclude, :binary, :extra_options, :interval, :mode
 
-    def initialize(raw, base: nil, workdir: nil, container: nil)
+    def initialize(raw, base: nil, workdir: nil, container: nil, compose: false)
       raise ConfigError, 'sync must be a mapping' unless raw.is_a?(Hash)
 
       @base = base
       assign_paths(raw, workdir: workdir, container: container)
       assign_mirror(raw)
+      assign_mode(raw, compose: compose)
       validate!
     end
 
     def delete? = !!@delete
+    def exec? = mode == 'exec'
 
     # Expanded against the wip.yml directory so the mirror covers the same tree
     # no matter which subdirectory wip was invoked from.
@@ -69,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 }
+        'interval' => interval, 'mode' => mode }
     end
 
     private
@@ -89,6 +96,15 @@ module Wip
       @interval = raw.key?('interval') ? raw['interval'] : DEFAULT_INTERVAL
     end
 
+    def assign_mode(raw, compose:)
+      @mode = presence(raw['mode']) || (compose ? 'run' : 'exec')
+      raise ConfigError, "sync.mode must be one of #{SYNC_MODES.join(', ')}" unless SYNC_MODES.include?(@mode)
+      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
+
     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.7.4'
+  VERSION = '0.9.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.7.4
+  version: 0.9.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