wslc-wip 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91983f52ddbbc2b2ce8eff75cd94534f9e32525d006ff7388152ac24a199ee15
-  data.tar.gz: c50b1311d33cbe16d94b1e050ce63f31c054bdd4850285728a3680d0c87e3390
+  metadata.gz: e2bffbab317006bdd799443ef1dc7e16d9527219261f91c9758504ae85aef638
+  data.tar.gz: b1e0f8f72d44878564573fcc8076af18defe14375d1bee4cd4946c72139bcc1e
 SHA512:
-  metadata.gz: 1f5fd382e2c88dbee58c8835be090e6aefd885f4d938d1d4543ac821f1822e4fc55c8f0da384e69d4d874b40382dcfc9e1914aec4c330b0a8b1173ff1518cff1
-  data.tar.gz: 9751c65c89c31c0d0f7e27ed28f27c4deece06ed15c780a900f608ba89df3cd9b16aae3c85faad058a4fb3363e5fe30ee30b29030fca6cdd22f828cad8bcc1a0
+  metadata.gz: d16eda21cb080e2dd7decc2522c4dac7c99536f3c720c1de7d64f0065edd7487c633450db9eeb687b12138b2763d3093628e0d169b82d7896c781e7c8298bb3c
+  data.tar.gz: 5f668930355e17877237892da08dc440630f2015253b072c715e324c38045598765c58cb84d9657d7769527d3f27774f8d4f03f6bec2cc1bb785bca9a308cce2

data/README.md

@@ -7,6 +7,15 @@
 
 Homepage: https://wslc-wip.slidict.com/
 
+`wip` is a Ruby-built OSS CLI wrapper that brings a [`dip`](https://github.com/bibendi/dip)-like
+workflow to Microsoft WSLC. It collects a project's container, image, environment variables, and
+commands into a single `wip.yml`, and forwards them to `wslc.exe` / `wslc` as safe argument arrays
+(no shell interpolation).
+
+![wip demo](https://raw.githubusercontent.com/slidict/wip/main/docs/demo.gif)
+
+> **Status:** early release. Expect to track WSLC's own interface as it evolves.
+
 ## Contents
 
 - [Which mode should you use?](#which-mode-should-you-use)
@@ -22,20 +31,12 @@ Homepage: https://wslc-wip.slidict.com/
 - [Commands](#commands)
 - [doctor](#doctor)
 - [Common errors](#common-errors)
+- [FAQ](#faq)
 - [Development](#development)
 - [Contributing](#contributing)
 - [Roadmap](#roadmap)
 - [License](#license)
 
-`wip` is a Ruby-built OSS CLI wrapper that brings a [`dip`](https://github.com/bibendi/dip)-like
-workflow to Microsoft WSLC. It collects a project's container, image, environment variables, and
-commands into a single `wip.yml`, and forwards them to `wslc.exe` / `wslc` as safe argument arrays
-(no shell interpolation).
-
-![wip demo](https://raw.githubusercontent.com/slidict/wip/main/docs/demo.gif)
-
-> **Status:** early release. Expect to track WSLC's own interface as it evolves.
-
 ## Which mode should you use?
 
 `wip.yml` runs in one of three modes, set with `mode:`. Pick the one that matches your project:
@@ -86,7 +87,7 @@ version: 1
 mode: container # default
 wslc:
   command: auto # tries wslc.exe, wslc, then System32; an absolute path also works
-container: app # required once dependencies: has entries; which one `up`/`exec`/`run`/`build`/`commands:`
+container: app # required once dependencies: has entries; which one `up`/`exec`/`run`/`build`/`interaction:`
                # 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:
@@ -112,7 +113,7 @@ dependencies:
     env:
       MYSQL_ROOT_PASSWORD: password
       MYSQL_DATABASE: development
-commands:
+interaction:
   rails:
     type: exec
     command: bin/rails
@@ -137,6 +138,7 @@ commands:
     type: build
     context: .
     tag: slidict/slidict:development
+    shadow_context: /mnt/c/Users/me/AppData/Local/wip/build-contexts
 sync: # optional; mirror the source into a named volume instead of bind-mounting it live
   exclude:
     - .git
@@ -148,6 +150,11 @@ sync: # optional; mirror the source into a named volume instead of bind-mounting
 credential, or auth. Keep real secrets out of the config file and in your runtime environment
 instead.
 
+`interaction:` can also be spelled `commands:` — the same block under a different name, e.g. for
+projects that already use `commands:`. `wip config` prints the effective config using `commands:`.
+The two are aliases for the same feature, not separate ones: pick whichever name you like, but declaring both
+`commands:` and `interaction:` in the same `wip.yml` is a `ConfigError`.
+
 #### Dependency containers
 
 `dependencies:` holds every container uniformly — the primary one `container:` points at and any
@@ -161,7 +168,7 @@ entry by name first (creating `network:` beforehand if it doesn't exist and set)
 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
+in place). Only the primary container is a target for `exec`/`run`/`build`/`interaction:` — sidecars
 are only ever started and stopped, matching Compose's own service-vs-you-exec-into-one-of-them
 split.
 
@@ -198,13 +205,13 @@ the Compose CLI vocabulary `wip` drives. `wip doctor` reports whether the config
 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
+- `wip exec`/`wip NAME` (custom `interaction:`) run inside `compose.service`.
+- `wip shell` also goes through the bridge: unless `interaction.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
+- `interaction:` 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.
 
 ### Compose mode (native)
@@ -263,10 +270,15 @@ to load a different file instead.
 
 ### .dockerignore
 
-`wip build` reads `.dockerignore` from the build context and stages a filtered copy of the
-context (skipping anything it matches) before handing it to `wslc build`, since `wslc` sends the
-context as-is otherwise. If there's no `.dockerignore`, the original context directory is used
-directly with no copying.
+`wip build` reads `.dockerignore` from the build context and excludes anything it matches before
+handing the context to `wslc build`, since `wslc` sends the context as-is otherwise. Set
+`commands.build.shadow_context` in `wip.yml` to a directory on the Windows filesystem to enable a
+persistent shadow context for projects outside `/mnt/<drive>`. The first build copies every
+included file; later builds only copy added or changed files and remove deleted or newly ignored
+files. Without this setting the optimization is disabled, and it only applies under WSL2 — on WSL1
+(or anywhere else) the context is handed to `wslc build` directly. Projects already on `/mnt/c` (or
+another mounted Windows drive) also continue to build directly even when the setting is present.
+The path must live outside the build context itself, or `wip build` refuses it.
 
 ### Source sync
 
@@ -344,7 +356,7 @@ Everything below `sync:` is optional — `sync: {}` alone already works. With it
 - 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
+Like every built-in command, `wip sync` takes precedence over an `interaction:` 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
@@ -415,7 +427,7 @@ to that tag directly — `sync.build`'s tag wins if both are set, so don't confi
 | `wip shell` | Open the configured shell, falling back to `bash` then `sh` |
 | `wip logs [-f] [SERVICE...]` | Follow compose service logs (compose modes only; mode: compose-native takes at most one `SERVICE`) |
 | `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 |
+| `wip NAME ARGS...` | Run `interaction.NAME`, appending any extra arguments |
 
 TTY allocation is decided by combining the command's config, the CLI option, and whether both
 stdin and stdout are real TTYs.
@@ -510,6 +522,74 @@ docker buildx build \
   --push .
 ```
 
+## FAQ
+
+**Which mode should I start with?**
+Pick whichever `mode:` fits your project — see [Which mode should you use?](#which-mode-should-you-use)
+for the breakdown.
+
+**Can I use `dependencies:` and `compose:` together?**
+No — `compose:` is mutually exclusive with `dependencies:`/`network`. Pick one orchestration path
+per project; see [Configuration](#configuration).
+
+**What's the difference between `mode: compose` and `mode: compose-native`?**
+`compose` delegates to a third-party compose-for-`wslc` binary you install yourself
+(`compose.command`); `compose-native` parses `compose.yml` itself and drives `wslc` directly, no
+external tool required. `compose-native`'s Compose coverage isn't frozen at whatever it handles
+today — it keeps growing until `wslc` ships native Compose support of its own. See
+[Compose mode](#compose-mode) and [Compose mode (native)](#compose-mode-native).
+
+**`dependencies:` already gives me sidecar containers — why would I need `compose-native` too?**
+`dependencies:` and `compose-native` aren't really alternatives to each other — they're for two
+different starting points. No `compose.yml`? Declare containers directly in `wip.yml`'s own shape
+with `dependencies:`. Already have a `compose.yml`? Reusing it is where `compose-native` and
+`mode: compose` both come in, so the real comparison is between those two, not against
+`dependencies:`: `mode: compose` reuses it too, but only by delegating to a third-party
+compose-for-`wslc` binary you install yourself; `compose-native` reuses the same `compose.yml`
+without installing anything external, parsing it and driving `wslc` directly — and gets a real
+`wslc run --rm` for `wip run` instead of the `exec` fallback `mode: compose` falls back to.
+`mode: compose`'s coverage is whatever the external tool you point it at supports; `compose-native`'s
+is maintained in this repo and actively extended, not treated as a permanent ceiling. See
+[Which mode should you use?](#which-mode-should-you-use) for the full picture.
+
+**What happens to `compose-native` once `wslc` gets official Compose support?**
+`compose-native` exists to close the gap for as long as `wslc` has no native Compose support of its
+own (tracked upstream in [microsoft/WSL#40948](https://github.com/microsoft/WSL/issues/40948)), and
+we intend to keep extending its Compose coverage until that lands — see
+[Compose mode (native)](#compose-mode-native) and [Roadmap](#roadmap). `wip.yml`'s shape (`mode:`,
+`compose:`) isn't planned to change for existing `container`/`compose`/`compose-native` setups, so
+whatever we do once `wslc` catches up won't require rewriting your config.
+
+**Is `sync:` required?**
+No, it's entirely optional. Add it if boot times feel slow with a bind-mounted app directory — see
+[Slow boot when the app directory is bind-mounted](#slow-boot-when-the-app-directory-is-bind-mounted).
+
+**How does `wip` actually fix the slow bind-mount boot problem?**
+The slowness comes from `.:/app`-style bind mounts going through virtiofs, where frameworks that
+stat/open many small files at startup (e.g. Ruby's Zeitwerk) pay a round trip per file. A `sync:`
+block moves the app off that path entirely: the host source is mounted read-only, the app itself
+runs off a named volume (fast native storage inside the VM), and `wip` mirrors the read-only
+source into that volume with `rsync` — once before boot, and on demand afterward via `wip sync`
+(or continuously with `wip sync --watch`). Since the app never touches the bind mount directly, its
+own file access is no longer paying the virtiofs cost; the trade-off is a one-way, slightly-delayed
+mirror instead of an always-live view of host edits. See [Source sync](#source-sync) for the full
+config and [Slow boot when the app directory is bind-mounted](#slow-boot-when-the-app-directory-is-bind-mounted)
+for the root cause.
+
+**Is it safe to put passwords/secrets in `wip.yml`?**
+`wip config` masks any key matching token/password/secret/credential/auth when printing, but the
+raw file itself is not encrypted. Keep real secrets in your runtime environment or `.env` instead
+of committing them in `wip.yml` — but `.env` is only safe if it's actually untracked: add `.env` to
+`.gitignore` (and confirm with `git check-ignore .env`) before putting anything sensitive in it.
+
+**`wslc.exe`/`wslc` isn't found — what do I do?**
+See [WSLC not found](#wslc-not-found) under Common errors.
+
+**I'm migrating from `dip` — do I have to rename `interaction:`?**
+No, `wip.yml` accepts `interaction:` as-is — it's the primary spelling, same as in `dip`. `commands:`
+also works as an alias if you prefer it, but not both in the same file (that's a `ConfigError`). See
+[Container mode](#container-mode).
+
 ## Development
 
 ```bash
@@ -522,7 +602,8 @@ bundle exec rake
 ```
 
 The test suite doesn't need WSLC — the resolution, build, and execution layers are all
-swappable. GitHub Actions runs RSpec and RuboCop on Ruby 3.2, 3.3, 3.4, and 4.0.
+swappable. This project uses RuboCop for Ruby style and static analysis; `bundle exec rake` runs
+both RSpec and RuboCop. GitHub Actions checks them on Ruby 3.2, 3.3, 3.4, and 4.0.
 
 ## Contributing
 
@@ -533,7 +614,7 @@ checklist.
 ## 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
+named commands (`interaction:`), `run`/`exec` hidden behind a single verb, `.env` passthrough, and
 sidecar services via `dependencies:` + `network:`. Rather than waiting on `wslc`'s own Compose
 support ([microsoft/WSL#40948](https://github.com/microsoft/WSL/issues/40948)) or an external
 compose-for-`wslc` tool staying complete, `mode: compose-native` (see
@@ -547,7 +628,7 @@ compose-for-`wslc` tool in [compose mode](#compose-mode) — which of those actu
 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`).
+and its current limitations (`run`, and `interaction:` of type `run`/`build`).
 
 Beyond Compose parity, a resident/daemon process, a GUI, PowerShell-specific tuning, direct
 registry API/manifest parsing, self-update, and plugins are all unimplemented and not currently

data/lib/wip/build_context.rb

@@ -1,33 +1,175 @@
 # frozen_string_literal: true
 
-require 'find'
+require 'digest'
 require 'fileutils'
+require 'find'
+require 'json'
 require 'pathname'
 require 'tmpdir'
 
 module Wip
-  # Stages a build context into a scratch directory with anything matched by
-  # .dockerignore left out, since wslc build (unlike `docker build`) sends the
-  # context as-is instead of filtering it itself.
+  # Filters build contexts for wslc and keeps WSL-hosted sources in a fast,
+  # persistent Windows-side shadow directory.
   class BuildContext
-    def initialize(context, ignore: nil)
+    def initialize(context, ignore: nil, environment: Environment.new, shadow_root: nil)
       @root = Pathname(context).expand_path
       @ignore = ignore || DockerIgnore.load(@root.join('.dockerignore'))
+      @environment = environment
+      @shadow_root = validated_shadow_root(shadow_root) if shadow_root
     end
 
     # on_progress fires before copying and after each file, as `|count, total|`,
     # so a caller can report elapsed progress even while copying one large file.
-    def stage(on_progress: nil)
-      return yield @root.to_s if @ignore.empty?
+    def stage(on_progress: nil, &block)
+      return stage_shadow(on_progress, &block) if shadow_required?
+      return block.call(@root.to_s) if @ignore.empty?
 
       Dir.mktmpdir('wip-build-context-') do |dir|
         copy_included_files(Pathname(dir), on_progress)
-        yield dir
+        block.call(dir)
       end
     end
 
     private
 
+    # A shadow root under the context would itself be walked by included_files
+    # on the next build and copied into itself at ever-deeper paths, so the
+    # cache would grow without bound and the build would eventually fail.
+    def validated_shadow_root(shadow_root)
+      root = Pathname(shadow_root).expand_path
+      if root == @root || root.to_s.start_with?("#{@root}/")
+        raise ConfigError, "shadow_context (#{root}) must not be inside the build context (#{@root})"
+      end
+
+      root
+    end
+
+    def shadow_required?
+      return false unless @shadow_root
+
+      @environment.wsl2? && !@root.to_s.match?(%r{\A/mnt/[a-z](?:/|\z)}i)
+    end
+
+    # Keep one stable Windows-side context per source path. Its manifest lives
+    # beside (rather than inside) the context so it is never sent to wslc.
+    def stage_shadow(on_progress)
+      key = Digest::SHA256.hexdigest(@root.to_s)
+      cache = @shadow_root.join(key)
+      context = cache.join('context')
+      FileUtils.mkdir_p(cache)
+
+      File.open(cache.join('lock'), File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        synchronize_shadow(context, cache.join('manifest.json'), on_progress)
+        # Keep the shadow immutable until wslc has finished reading it.
+        yield context.to_s
+      end
+    end
+
+    def synchronize_shadow(context, manifest_path, on_progress)
+      current = included_files.to_h { |entry| [entry, fingerprint(@root.join(entry))] }
+      previous = previous_manifest(context, manifest_path)
+      changed = current.keys.reject { |entry| current[entry] == previous[entry] }
+      removed = previous.keys - current.keys
+
+      apply_shadow_changes(context, changed, removed, on_progress)
+      FileUtils.mkdir_p(context)
+      write_manifest(manifest_path, current)
+    end
+
+    # A context we can't describe is a context we can't update incrementally:
+    # with no manifest there is no way to tell which of its entries are stale,
+    # so it gets discarded and rebuilt rather than left holding deleted or
+    # newly ignored files.
+    def previous_manifest(context, manifest_path)
+      return {} unless context.directory?
+
+      manifest = load_manifest(manifest_path)
+      return manifest if manifest
+
+      FileUtils.rm_rf(context)
+      {}
+    end
+
+    def apply_shadow_changes(context, changed, removed, on_progress)
+      total = changed.size + removed.size
+      on_progress&.call(0, total)
+
+      removed.each_with_index do |entry, index|
+        FileUtils.rm_rf(context.join(entry))
+        prune_empty_parents(context.join(entry).dirname, context)
+        on_progress&.call(index + 1, total)
+      end
+      changed.each_with_index do |entry, index|
+        copy_entry_atomically(@root.join(entry), context.join(entry))
+        on_progress&.call(removed.size + index + 1, total)
+      end
+    end
+
+    # Returns nil — not an empty manifest — when the manifest is missing,
+    # unreadable, or not a manifest at all, so callers can tell "nothing was
+    # synced yet" apart from "we no longer know what was synced".
+    def load_manifest(path)
+      manifest = JSON.parse(path.read)
+      manifest if manifest.is_a?(Hash)
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def write_manifest(path, contents)
+      temporary = Pathname("#{path}.tmp-#{Process.pid}")
+      temporary.write(JSON.generate(contents))
+      File.rename(temporary, path)
+    ensure
+      FileUtils.rm_f(temporary) if temporary
+    end
+
+    def fingerprint(path)
+      stat = path.lstat
+      if stat.symlink?
+        { 'type' => 'link', 'target' => path.readlink.to_s }
+      else
+        { 'type' => 'file', 'size' => stat.size, 'mtime_ns' => stat.mtime.nsec + (stat.mtime.to_i * 1_000_000_000),
+          'mode' => stat.mode }
+      end
+    end
+
+    # preserve: true keeps the source mode, so an executable stays executable
+    # even when the shadow lives on a DrvFs mount whose fmask would otherwise
+    # strip the bit and break a `RUN ./script` in the image build.
+    def copy_entry_atomically(source, target)
+      FileUtils.mkdir_p(target.dirname)
+      temporary = target.dirname.join(".#{target.basename}.wip-#{Process.pid}")
+      FileUtils.rm_rf(temporary)
+      FileUtils.copy_entry(source, temporary, true, false, false)
+      replace_atomically(temporary, target)
+    ensure
+      FileUtils.rm_rf(temporary) if temporary
+    end
+
+    # rename replaces an existing entry in a single step, so an interrupted
+    # update leaves the previous copy in place instead of no copy at all. Only
+    # a target rename can't overwrite — a directory where a file now lives, or
+    # a filesystem without overwrite semantics — needs the unsafe fallback.
+    def replace_atomically(temporary, target)
+      File.rename(temporary, target)
+    rescue Errno::EISDIR, Errno::ENOTDIR, Errno::ENOTEMPTY, Errno::EEXIST, Errno::EPERM, Errno::EACCES
+      FileUtils.rm_rf(target)
+      File.rename(temporary, target)
+    end
+
+    def prune_empty_parents(directory, root)
+      while empty_descendant?(directory, root)
+        directory.rmdir
+        directory = directory.dirname
+      end
+    end
+
+    def empty_descendant?(directory, root)
+      directory != root && directory.to_s.start_with?("#{root}/") &&
+        directory.directory? && directory.children.empty?
+    end
+
     def copy_included_files(destination, on_progress)
       files = included_files
       on_progress&.call(0, files.size)
@@ -37,7 +179,7 @@ module Wip
         # Keep links as links. Dereferencing a link here could copy arbitrary
         # host files outside the build context (for example, ~/.ssh/id_rsa)
         # into the staged directory and expose them to the image build.
-        FileUtils.copy_entry(@root.join(relative_path), target, false, false, false)
+        FileUtils.copy_entry(@root.join(relative_path), target, true, false, false)
         on_progress&.call(index + 1, files.size)
       end
     end

data/lib/wip/cli.rb

@@ -73,7 +73,8 @@ module Wip
       context = Pathname(load_config.path).dirname.join(settings['context'] || '.').to_s
       warn "wip: staging build context (#{context})"
       progress = StagingProgress.new
-      BuildContext.new(context).stage(on_progress: progress.method(:tick)) do |staged_context|
+      build_context = BuildContext.new(context, shadow_root: settings['shadow_context'])
+      build_context.stage(on_progress: progress.method(:tick)) do |staged_context|
         progress.finish
         built = builder.build(settings: settings.merge('context' => staged_context), extra: extra)
         execute(built, interactive: tty?(true))

data/lib/wip/config.rb

@@ -27,7 +27,18 @@ module Wip
     end
 
     def wslc_command = @raw.dig('wslc', 'command') || 'auto'
-    def commands = @raw['commands'] || {}
+
+    # interaction: is dip's name for the same concept — accepted as an alias so a
+    # dip.yml can be renamed to wip.yml with fewer edits. The two are mutually
+    # exclusive (validate_commands!) rather than merged, so a project doesn't end up
+    # with the same command split across both keys.
+    def commands
+      return @raw['commands'] if @raw.key?('commands')
+      return @raw['interaction'] if @raw.key?('interaction')
+
+      {}
+    end
+
     # Raw dependencies: block as written in wip.yml. Under compose-native mode this stays
     # empty by construction (validate_compose! forbids combining the two) — #dependencies
     # below is what callers actually want, since it's synthesized from compose.yml there.
@@ -126,6 +137,8 @@ module Wip
     end
 
     def validate_commands!
+      raise ConfigError, 'commands is mutually exclusive with interaction — pick one' \
+        if @raw.key?('commands') && @raw.key?('interaction')
       raise ConfigError, 'commands must be a mapping' unless commands.is_a?(Hash)
 
       commands.each { |name, entry| validate_command!(name, entry) }
@@ -175,9 +188,22 @@ module Wip
       type = entry['type'] || (name == 'build' ? 'build' : 'exec')
       raise ConfigError, "Invalid command type for #{name}: #{type}" unless %w[exec run build].include?(type)
 
+      validate_shadow_context!(name, entry, type)
+
       entry['env']&.transform_values!(&:to_s)
     end
 
+    # shadow_context names a Windows-side mirror of the build context, so it only
+    # means anything on a build command — and only as a real path.
+    def validate_shadow_context!(name, entry, type)
+      return unless entry.key?('shadow_context')
+
+      shadow_context = entry['shadow_context']
+      return if type == 'build' && shadow_context.is_a?(String) && !shadow_context.empty?
+
+      raise ConfigError, "commands.#{name}.shadow_context must be a non-empty path for a build command"
+    end
+
     def validate_dependency!(name, entry)
       raise ConfigError, "dependencies.#{name} must be a mapping" unless entry.is_a?(Hash)
       raise ConfigError, "dependencies.#{name} must set image" if entry['image'].to_s.empty?

data/lib/wip/initializer.rb

@@ -31,17 +31,18 @@ module Wip
     # example uses.
     FALLBACK_EXCLUDES = %w[.git tmp/ node_modules/].freeze
 
-    # Appended to both templates after dependencies/compose. commands: itself is left
-    # commented since an empty commands: {} is indistinguishable from omitting the key.
+    # Appended to both templates after dependencies/compose. interaction: itself is left
+    # commented since an empty interaction: {} is indistinguishable from omitting the key.
     COMMANDS_EXAMPLE = <<~YAML.chomp
       # optional; custom subcommands, e.g. `wip test` — see README
-      # commands:
+      # (interaction: is the primary key; commands: is accepted as an alias — the two are
+      # mutually exclusive, so pick one)
+      # interaction:
       #   test:
       #     optional; exec (default, runs in the running container) | run (fresh container) | build
       #     type: exec
 
-      #     TODO
-      #     command: bundle exec rspec
+      #     command: ls
     YAML
 
     def initialize(dir: Dir.pwd, template: nil)

data/lib/wip/version.rb

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

metadata

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