wslc-wip 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91983f52ddbbc2b2ce8eff75cd94534f9e32525d006ff7388152ac24a199ee15
-  data.tar.gz: c50b1311d33cbe16d94b1e050ce63f31c054bdd4850285728a3680d0c87e3390
+  metadata.gz: 49996dea1b8ae083cceb0caaafc0b8ddcc6de0a3ab8a7f5f4f856156948840d3
+  data.tar.gz: cca5758770d9f4364427c1ae7519ee8026c598b1002206fc9af8f22f5ffc0a64
 SHA512:
-  metadata.gz: 1f5fd382e2c88dbee58c8835be090e6aefd885f4d938d1d4543ac821f1822e4fc55c8f0da384e69d4d874b40382dcfc9e1914aec4c330b0a8b1173ff1518cff1
-  data.tar.gz: 9751c65c89c31c0d0f7e27ed28f27c4deece06ed15c780a900f608ba89df3cd9b16aae3c85faad058a4fb3363e5fe30ee30b29030fca6cdd22f828cad8bcc1a0
+  metadata.gz: df63da254bbbb1b6dedf5e56b5a78d8fbb09fd7d6dfa41ae0b3b58db600f07e8703ea3d729a4bb125e8d1a29e498ce8c3e4504e93d74ad51ce37b7d4a3bad0db
+  data.tar.gz: 8b8607bdda225610b7c7389210c16a04764aa95ba45748f9bcd3c384f9b6eb3ccb371342cea89a12749d7c4226f9fe6b94729c191513690b40168b339d21dd7b

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)
@@ -237,8 +244,10 @@ top level (`networks:`, `volumes:`, `configs:`, `secrets:`, ...) is the one exce
 real Compose tools, not by `wip`, so `wip` silently ignores it rather than rejecting an otherwise
 valid compose.yml over sections it doesn't need to look at:
 
-- Per service: `image`, `build` (string or `{context:, dockerfile:}`; resolved relative to
-  `compose.yml`, not wherever `wip` is invoked from), `command` (shell or exec form), `environment`
+- Per service: `image`, `build` (string or `{context:, dockerfile:, args:, shadow_context:}`;
+  `context` is resolved relative to `compose.yml`, not wherever `wip` is invoked from; `dockerfile`
+  stays relative to `context` itself — see [.dockerignore](#dockerignore) for what `shadow_context`
+  does), `command` (shell or exec form), `environment`
   (mapping or `KEY=VALUE` array — a mapping value must not be null; host environment pass-through
   isn't supported), `ports`/`volumes` (short syntax only — `"host:container"` strings, not
   long-syntax mappings), `working_dir`, `user`, `depends_on` (ordering only — a `condition:` other
@@ -263,10 +272,16 @@ 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` (or `build.shadow_context` on a compose-native
+`build:` service in `compose.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`/`wip up` refuses it.
 
 ### Source sync
 
@@ -344,7 +359,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 +430,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 +525,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 +605,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 +617,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 +631,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,180 @@
 # 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
 
+    # Whether the upcoming stage will use the Windows-side shadow directory
+    # (configured shadow_root, on WSL2, with a context outside /mnt) rather
+    # than staging in place or under a WSL-side tmpdir.
+    def shadow? = shadow_required?
+
     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 +184,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,10 +73,10 @@ 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))
+        run_staged_build(build_context, staged_context, settings, extra)
       end
     ensure
       progress&.finish
@@ -247,10 +247,12 @@ module Wip
       execute(exec_target(command, interactive: interactive), interactive: tty?(interactive))
     end
 
-    def execute(command, interactive: false, exit_on_failure: true)
+    def execute(command, interactive: false, exit_on_failure: true, chdir: nil)
       runner = CommandRunner.new(debug: debug?)
+      run_options = { interactive: interactive }
+      run_options[:chdir] = chdir if chdir
       code = reporter.step("running: #{CommandDisplay.for_debug(command)}", live: !interactive) do
-        runner.run(command, interactive: interactive)
+        runner.run(command, **run_options)
       end
       exit(code) if exit_on_failure && !code.zero?
       code
@@ -321,15 +323,23 @@ module Wip
       extra = compose_build_extra(spec)
       warn "wip: building service '#{name}' (tag: #{spec['tag']}) from #{spec['context']}"
       progress = StagingProgress.new
-      BuildContext.new(spec['context']).stage(on_progress: progress.method(:tick)) do |staged_context|
+      build_context = BuildContext.new(spec['context'], shadow_root: spec['shadow_context'])
+      build_context.stage(on_progress: progress.method(:tick)) do |staged_context|
         progress.finish
-        settings = { 'context' => staged_context, 'tag' => spec['tag'] }
-        execute(builder.build(settings: settings, extra: extra), interactive: tty?(true))
+        run_staged_build(build_context, staged_context, { 'tag' => spec['tag'] }, extra)
       end
     ensure
       progress&.finish
     end
 
+    # wslc build crashes (ERROR_UNHANDLED_EXCEPTION) when handed an absolute
+    # context path; running from inside the context and passing "." avoids it.
+    def run_staged_build(build_context, staged_context, settings, extra)
+      warn "wip: using shadow build context at #{staged_context}" if build_context.shadow?
+      built = builder.build(settings: settings.merge('context' => '.'), extra: extra)
+      execute(built, interactive: tty?(true), chdir: staged_context)
+    end
+
     def build_extra_options(extra)
       extra = extra.dup
       extra.shift if extra.first == '--'
@@ -355,7 +365,9 @@ module Wip
 
       Dir.mktmpdir('wip-sync-build-') do |dir|
         File.write(File.join(dir, 'Dockerfile'), settings.build['dockerfile'])
-        execute(builder.sync_build(dir))
+        # wslc build crashes (ERROR_UNHANDLED_EXCEPTION) when handed an absolute
+        # context path; running from inside the context and passing "." avoids it.
+        execute(builder.sync_build('.'), chdir: dir)
       end
     end
 

data/lib/wip/command_runner.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'open3'
+require 'pty'
+require 'io/console'
 
 module Wip
   # Executes a built command, pumping its I/O and returning the exit status.
@@ -14,13 +16,14 @@ module Wip
       @debug = debug
     end
 
-    def run(command, env: {}, interactive: false)
+    def run(command, env: {}, interactive: false, chdir: nil)
       @stderr.puts "+ #{CommandDisplay.for_debug(command)}" if @debug
-      return run_attached(command, env) if interactive
+      return run_attached(command, env, chdir) if interactive
 
+      opts = chdir ? { chdir: chdir } : {}
       captured = +''
       status = nil
-      Open3.popen3(env, *command) do |input, output, error, wait|
+      Open3.popen3(env, *command, opts) do |input, output, error, wait|
         input.close
         threads = [pump(output, @stdout, captured), pump(error, @stderr, captured)]
         threads.each(&:join)
@@ -52,15 +55,84 @@ module Wip
 
     # Piping stdin/stdout/stderr (as `run` does above) closes the child's
     # stdin immediately, which breaks anything that reads from the terminal
-    # (a shell, `rails console`, ...). Inherit the real file descriptors
-    # instead so the child gets a genuine TTY.
-    def run_attached(command, env)
-      pid = Process.spawn(env, *command)
-      _, status = Process.wait2(pid)
+    # (a shell, `rails console`, ...). Run it behind a pseudo-terminal instead
+    # of inheriting wip's real fds directly: a pty still gives the child a
+    # genuine controlling terminal (job control, Ctrl-C -> SIGINT, isatty-gated
+    # rendering all work the same as direct inheritance), but routes output
+    # through wip first, so report_hint can still see it — inherited fds go
+    # straight to the terminal and wip never would. wip's own terminal is
+    # switched to raw mode for the duration so only the pty's line discipline
+    # echoes input; without that, every keystroke would echo twice.
+    def run_attached(command, env, chdir)
+      opts = chdir ? { chdir: chdir } : {}
+      captured = +''
+      status = nil
+      PTY.spawn(env, *command, opts) do |output, input, pid|
+        sync_winsize(output)
+        with_winsize_sync(output) { with_raw_stdin { pump_attached(output, input, captured) } }
+        _, status = Process.wait2(pid)
+      end
+      report_hint(captured) unless status.success?
       exitstatus(status)
     rescue Errno::ENOENT => e
       @stderr.puts e.message
       127
+    rescue Interrupt
+      @stderr.puts "\nwip: interrupted"
+      130
+    end
+
+    def pump_attached(output, input, captured)
+      stdin_thread = forward_stdin(input)
+      loop do
+        chunk = output.readpartial(4096)
+        @stdout.write(chunk)
+        captured << chunk
+      end
+    rescue Errno::EIO, IOError
+      # the pty's slave side closed when the child exited
+    ensure
+      stdin_thread.kill
+    end
+
+    # Keeps the child's pty sized to wip's real terminal so full-screen
+    # programs (an editor, `less`, ...) render correctly. A non-tty @stdout
+    # (piped output, tests) has no size to read, so the pty keeps its default.
+    def sync_winsize(output)
+      output.winsize = @stdout.winsize if @stdout.respond_to?(:winsize) && @stdout.tty?
+    end
+
+    # The child's pty only gets the terminal size wip had at spawn time
+    # (sync_winsize, above) — it's a separate pty from wip's own real one, so
+    # later resizes of wip's terminal don't reach it on their own. Trap
+    # SIGWINCH for the duration to re-sync it live, restoring whatever handler
+    # was already installed (if any) once the command finishes.
+    def with_winsize_sync(output)
+      return yield unless @stdout.respond_to?(:winsize) && @stdout.tty?
+
+      previous = Signal.trap('WINCH') { sync_winsize(output) }
+      yield
+    ensure
+      Signal.trap('WINCH', previous) if previous
+    end
+
+    # A non-tty @stdin (piped input, tests) has no raw mode to switch to, so
+    # it's forwarded to the child as-is.
+    def with_raw_stdin(&)
+      return yield unless @stdin.respond_to?(:raw) && @stdin.tty?
+
+      @stdin.raw(&)
+    end
+
+    def forward_stdin(input)
+      Thread.new do
+        loop do
+          chunk = @stdin.readpartial(4096)
+          input.write(chunk)
+        end
+      rescue IOError, Errno::EIO, Errno::EBADF
+        nil
+      end
     end
 
     # An Interrupt during the main thread's `join` closes these pipes out from

data/lib/wip/compose_file.rb

@@ -24,7 +24,7 @@ module Wip
     # service already shares one project network (config.rb); and `wslc run`/`exec` has no
     # restart-policy or capability flag to forward `restart:`/`cap_add:` to.
     IGNORED_SERVICE_KEYS = %w[tty stdin_open networks restart cap_add].freeze
-    BUILD_KEYS = %w[context dockerfile args].freeze
+    BUILD_KEYS = %w[context dockerfile args shadow_context].freeze
     SUPPORTED_CONDITIONS = %w[service_started].freeze
     LIST_HINT = 'only supports short syntax ("host:container"), not long-syntax mappings'
 
@@ -140,9 +140,11 @@ module Wip
         unless unknown.empty?
 
       context = resolve_context(presence(value['context']) || '.')
-      dockerfile = presence(value['dockerfile'])
-      { 'context' => context, 'dockerfile' => dockerfile && Pathname(context).join(dockerfile).to_s,
-        'args' => normalize_kv(name, value['args'], 'build.args') }.compact
+      # Kept relative to context (not resolved against it) so `-f` still finds it once
+      # `wip up`/`wip build` chdir into a staged or shadowed copy of that context.
+      { 'context' => context, 'dockerfile' => presence(value['dockerfile']),
+        'args' => normalize_kv(name, value['args'], 'build.args'),
+        'shadow_context' => presence(value['shadow_context']) }.compact
     end
 
     # build.context is relative to compose.yml's own directory (Compose's own rule),

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.1'
 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.1
 platform: ruby
 authors:
 - Wip contributors