wslc-wip 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a32d5a9003a7197fd47fa4b81b7ca764b495ea7955ccc523cda29330f0e4e5b2
-  data.tar.gz: 9d47155b5a53497dc9e5ad16cbd48f402ee0ea9d3865cfd932f577d6a1f4a746
+  metadata.gz: 00dbc091bf03ff619a8d2096e87a7c9fea05194829a5378448b0547d1b3133a9
+  data.tar.gz: 4a44f1a28d3dc37a4f58f4b171e5034c714c83fe123b4870ac30862fbe0a10d4
 SHA512:
-  metadata.gz: 167b4aa726f99b28e2ce78087c07e10c122382a82e61db43820f43f7a28ca3bb8cfc24ab4aabb27d2577018f586257aec4a8bd3c18ae13dfcabc70be53ce2108
-  data.tar.gz: c4c9c0a6766fa93fcf5b40365d22526b40ff7d9cf22615484f030d5043b4b851878e9e36cfc70e1402943296592ed69074b1b813ea372332e4a3a2002cc13bc9
+  metadata.gz: f9d78416a789d166c2db523d2b4f6e32e54e3e099f6f6cb369b5d7e1c46b8bc95c3a2088cb211add014a9fc59313985bdbef9f573de70cd86b41f0b936df4cbd
+  data.tar.gz: 7131cba0e0935a53bb7966ddd5ce2254374d78d08093b7ef0ccd987848184a2be834938bee169aaad78cfaeb77b9317af94df65c9127fe05559a8f926c51fef2

data/README.md

@@ -50,7 +50,8 @@ mode: container # default. This example is container mode end-to-end — see "Co
                 # 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
-container: app # optional; which dependencies: entry `up`/`exec`/`run`/`build`/`commands:` target (default: app)
+container: app # required once dependencies: has entries; which one `up`/`exec`/`run`/`build`/`commands:`
+               # target. No default — a project must say which entry is the primary one explicitly.
 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
@@ -129,10 +130,11 @@ directly with no copying.
 
 ### Dependency containers
 
-`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."
+`dependencies:` holds every container uniformly — the primary one `container:` points at 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." `container:` has no default; once `dependencies:` has any entries,
+wip needs to be told explicitly which one is primary rather than guessing a name.
 
 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
@@ -167,9 +169,16 @@ 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)
+  image: null        # image for the mirror container; unused under mode: container unless set
+                      # (falls back to the primary container's own image). Under mode: compose,
+                      # one of image or build is required (there's no dependencies: entry to fall
+                      # back to)
+  build:              # optional; has wip build the mirror image itself instead of requiring one to
+                       # already exist. build.tag wins over image if both are set.
+    dockerfile: |
+      FROM alpine:latest
+      RUN apk add --no-cache rsync
+    tag: null          # optional (default: "wip-sync-<container>:latest")
 ```
 
 Everything below `sync:` is optional — `sync: {}` alone already works. With it in place:
@@ -187,6 +196,8 @@ Everything below `sync:` is optional — `sync: {}` alone already works. With it
 - `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.
+- With `sync.build` configured, `wip build`s that image once per `wip up`/`wip sync` invocation
+  (including once before a `--watch` loop starts, not on every tick) before mirroring with it.
 
 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.
@@ -215,14 +226,33 @@ or set `delete: false`.
   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.
+  `sync.image` or `sync.build` 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.
 
+Since `sync.mode: run` boots a fresh container on every mirror, reusing your app's full image here
+just adds startup overhead for something that only ever runs `rsync`. A dedicated, minimal image is
+worth it — `wip` doesn't publish or default to one itself (same reasoning as `compose.command`:
+picking a specific third-party image for you isn't its call to make), but `sync.build` covers it
+without needing to manage a separate image yourself:
+
+```yaml
+sync:
+  build:
+    dockerfile: |
+      FROM alpine:latest
+      RUN apk add --no-cache rsync
+```
+
+wip builds this once per `wip up`/`wip sync` invocation (not on every `--watch` tick — see above)
+and uses the result, tagged `wip-sync-<container>:latest` by default (`build.tag` overrides it).
+Prefer managing the image yourself instead? Build and tag it however you like, then set `sync.image`
+to that tag directly — `sync.build`'s tag wins if both are set, so don't configure both at once.
+
 ### Compose mode
 
 If your project already has a real `compose.yml`, don't duplicate it in `dependencies:` — point
@@ -274,7 +304,7 @@ found, its version, and which compose file `wip` resolved.
 | `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 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 up [-d] [--no-sync]` | Start the primary `dependencies:` entry (`container:` names which one) 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) |

data/lib/wip/cli.rb

@@ -5,6 +5,7 @@ require 'yaml'
 require 'json'
 require 'stringio'
 require 'shellwords'
+require 'tmpdir'
 
 module Wip
   # Thor-based command-line interface for wip.
@@ -93,6 +94,7 @@ module Wip
     def sync
       settings = sync_settings!
       warn_shadowed_command('sync')
+      ensure_sync_image(settings)
       return run_sync unless options[:watch]
 
       interval = watch_interval(settings)
@@ -270,6 +272,18 @@ module Wip
       load_config.sync || raise(ConfigError, '`wip sync` needs a sync: block in wip.yml')
     end
 
+    # Builds sync.build's image once per invocation (not per --watch tick, which
+    # would pay Docker build-cache-lookup overhead on every mirror for no reason).
+    # A no-op unless sync.build is configured.
+    def ensure_sync_image(settings)
+      return unless settings.build
+
+      Dir.mktmpdir('wip-sync-build-') do |dir|
+        File.write(File.join(dir, 'Dockerfile'), settings.build['dockerfile'])
+        execute(builder.sync_build(dir))
+      end
+    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)
@@ -300,6 +314,7 @@ module Wip
       settings = load_config.sync
       return unless settings
 
+      ensure_sync_image(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"

data/lib/wip/command_builder.rb

@@ -16,7 +16,7 @@ module Wip
       # 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)
+      values = primary_values.merge('container' => required_container).merge(settings)
       command = [@wslc, 'exec']
       command << '-it' if tty?(interactive)
       command.concat(options(values, include_container: true, include_publish: false)).concat(arguments)
@@ -32,7 +32,7 @@ module Wip
 
     def up(detach: false)
       values = primary_values
-      command = [@wslc, 'run', '--name', @config.container]
+      command = [@wslc, 'run', '--name', required_container]
       command.push('--network', @config.network) if @config.network
       command << '-d' if detach
       command << '-it' if !detach && tty?(true)
@@ -42,25 +42,38 @@ module Wip
     end
 
     def start(detach: false)
-      command = [@wslc, 'start', @config.container]
+      command = [@wslc, 'start', required_container]
       command.push('-a', '-i') unless detach
       command
     end
 
     def find
-      [@wslc, 'list', '--all', '--filter', "name=#{@config.container}", '--format', 'json']
+      [@wslc, 'list', '--all', '--filter', "name=#{required_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). 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).
+    # container isn't running yet — e.g. just before `up` boots it). The image
+    # comes from sync.build's tag (once built via sync_build), else sync.image,
+    # else the primary dependencies: entry; compose mode requires one of the
+    # first two, since it has no dependencies: entry to fall back to.
     def sync_run
       sync = required_sync
       command = [@wslc, 'run', '--rm']
       sync.volume_specs.each { |spec| command.push('-v', spec) }
-      command.push(sync.image || required(primary_values, 'image')).concat(sync.mirror_command)
+      image = sync.build&.fetch('tag') || sync.image || required(primary_values, 'image')
+      command.push(image).concat(sync.mirror_command)
+    end
+
+    # Builds sync.build's image from a Dockerfile staged in `context` (a caller-
+    # managed directory, since the build only reads it once `wslc build` runs).
+    # Doesn't touch dependencies: at all, so it works the same under compose
+    # mode as it does under container mode.
+    def sync_build(context)
+      sync = required_sync
+      raise ConfigError, 'No sync.build configured in wip.yml' unless sync.build
+
+      [@wslc, 'build', '-t', sync.build['tag'], context]
     end
 
     # Mirrors from inside the already-running container. Only valid for
@@ -68,15 +81,15 @@ module Wip
     # itself booted is guaranteed to have both the read-only source mount and
     # the volume attached.
     def sync_exec
-      [@wslc, 'exec', @config.container, *required_sync.mirror_command]
+      [@wslc, 'exec', required_container, *required_sync.mirror_command]
     end
 
     def down
-      [@wslc, 'stop', @config.container]
+      [@wslc, 'stop', required_container]
     end
 
     def remove
-      [@wslc, 'remove', '-f', @config.container]
+      [@wslc, 'remove', '-f', required_container]
     end
 
     def network_create
@@ -183,9 +196,17 @@ module Wip
       @config.dependency(name) || raise(ConfigError, "Unknown dependency: #{name}")
     end
 
+    def required_container
+      container = @config.container
+      raise ConfigError, 'container: must be set in wip.yml' if container.to_s.empty?
+
+      container
+    end
+
     def primary_values
-      @config.primary || raise(ConfigError, "No dependencies.#{@config.container} entry " \
-                                            '(set container: to name a different one)')
+      container = required_container
+      @config.dependency(container) || raise(ConfigError, "No dependencies.#{container} entry " \
+                                                          '(check container: in wip.yml)')
     end
   end
 end

data/lib/wip/config.rb

@@ -25,8 +25,11 @@ module Wip
     def dependencies = @raw['dependencies'] || {}
     # 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'
+    # else in dependencies: is a sidecar wip only starts and stops. No default:
+    # guessing a name here (the old default was "app") either matches by luck or
+    # fails in a way that doesn't point at the real problem (a differently-named
+    # entry), so a project with any dependencies: must say which one explicitly.
+    def container = presence(@raw['container'])
     def network = @raw['network']
     def mode = @raw['mode'] || 'container'
     def compose = @raw['compose']
@@ -107,6 +110,13 @@ module Wip
 
     def validate_dependencies!
       raise ConfigError, 'dependencies must be a mapping' unless dependencies.is_a?(Hash)
+      # Under compose mode, populated dependencies: is already an error on its own
+      # (validate_compose!, below) — this only needs to fire for the mode: container
+      # case, where dependencies: having entries but no container: is otherwise valid.
+      if dependencies.any? && !container && !compose?
+        raise ConfigError,
+              'container: must be set when dependencies: has entries'
+      end
 
       dependencies.each { |name, entry| validate_dependency!(name, entry) }
     end

data/lib/wip/initializer.rb

@@ -11,9 +11,10 @@ module Wip
     CONTAINER_TEMPLATE = <<~YAML
       version: 1
       mode: container
+      container: app # TODO: rename freely, as long as it matches a key under dependencies: below
 
       dependencies:
-        app: # TODO: this is the container wip creates, execs into, and runs commands in
+        app: # 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
 
@@ -40,6 +41,8 @@ module Wip
       <<~YAML
         version: 1
         mode: compose
+        container: app # TODO: rename freely; only used to name sync's volume ("<container>-src"),
+                        # since compose.yml — not dependencies: — owns this service's own definition
 
         compose:
           service: app # TODO: which service in #{compose_file} wip run/exec/NAME target
@@ -49,9 +52,9 @@ module Wip
       YAML
     end
 
-    # sync: needs sync.image (mode: compose has no dependencies: entry to borrow one from) and a
-    # named volume the compose service mounts, matching sync.volume ("app-src" by default). Checked
-    # against the detected compose file so the hint doesn't repeat what's already set up.
+    # sync: needs sync.image or sync.build (mode: compose has no dependencies: entry to borrow an
+    # image from) and a named volume the compose service mounts, matching sync.volume ("app-src" by
+    # default). Checked against the detected compose file so the hint doesn't repeat what's set up.
     def sync_hint
       return sync_hint_configured if compose_volume_mounted?
 
@@ -61,14 +64,17 @@ module Wip
     def sync_hint_configured
       <<~COMMENT.chomp
         # #{compose_file} already mounts a volume matching sync.volume's default (app-src).
-        # sync: # add sync.image too (required under mode: compose) — see README
+        # sync: # add sync.build or sync.image too (one's required under mode: compose) — see README
       COMMENT
     end
 
     def sync_hint_todo
       <<~COMMENT.chomp
         # sync: # optional; mirrors the source into a named volume instead of bind-mounting it live
-        #   image: your/image:tag # required under mode: compose (no dependencies: entry to borrow one from)
+        #   build: # required under mode: compose (no dependencies: entry to borrow an image from)
+        #     dockerfile: |
+        #       FROM alpine:latest
+        #       RUN apk add --no-cache rsync
         #   # the service above must also mount a volume named "app-src" (sync.volume's default) at the
         #   # path your app expects — add to #{compose_file}:
         #   #   volumes:

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, :image
+    attr_reader :target, :mount, :volume, :exclude, :binary, :extra_options, :interval, :mode, :image, :build
 
     def initialize(raw, base: nil, workdir: nil, container: nil, compose: false)
       raise ConfigError, 'sync must be a mapping' unless raw.is_a?(Hash)
@@ -40,6 +40,7 @@ module Wip
       @base = base
       assign_paths(raw, workdir: workdir, container: container)
       assign_mirror(raw)
+      assign_build(raw)
       assign_mode(raw, compose: compose)
       validate!
     end
@@ -76,7 +77,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, 'image' => image }
+        'interval' => interval, 'mode' => mode, 'image' => image, 'build' => build }
     end
 
     private
@@ -85,7 +86,8 @@ module Wip
       @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"
+      @container_name = presence(container) || 'wip'
+      @volume = presence(raw['volume']) || "#{@container_name}-src"
     end
 
     def assign_mirror(raw)
@@ -96,12 +98,29 @@ module Wip
       @interval = raw.key?('interval') ? raw['interval'] : DEFAULT_INTERVAL
     end
 
+    # sync.build lets wip build a small, dedicated mirror image itself (e.g. alpine
+    # + rsync) instead of requiring one to already exist — handy since sync.mode:
+    # run boots a fresh container per mirror and reusing the app's full image just
+    # adds startup overhead for something that only ever runs rsync.
+    def assign_build(raw)
+      build = raw['build']
+      @build = nil
+      return unless build
+
+      raise ConfigError, 'sync.build must be a mapping' unless build.is_a?(Hash)
+
+      dockerfile = presence(build['dockerfile'])
+      raise ConfigError, 'sync.build.dockerfile must not be empty' unless dockerfile
+
+      @build = { 'dockerfile' => dockerfile, 'tag' => presence(build['tag']) || "wip-sync-#{@container_name}:latest" }
+    end
+
     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)
+      validate_image_source!(compose)
       return unless compose && exec?
 
       raise ConfigError, 'sync.mode: exec needs mode: container (compose owns its services’ mounts, ' \
@@ -109,12 +128,13 @@ module Wip
     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
+    # container's image, so it can't be left implicit there — sync.image or
+    # sync.build must name one explicitly.
+    def validate_image_source!(compose)
+      return if !compose || @image || @build
 
-      raise ConfigError, 'sync.image is required under mode: compose (there’s no dependencies: entry ' \
-                         'to borrow the mirror container’s image from)'
+      raise ConfigError, 'sync.image or sync.build is required under mode: compose (there’s no ' \
+                         'dependencies: entry to borrow the mirror container’s image from)'
     end
 
     def validate!

data/lib/wip/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wslc-wip
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Wip contributors