wslc-wip 0.18.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f4750c407f5fe6be96d5e079e090d8d8a9aea434479bbbfcfe628db1ba1b993
-  data.tar.gz: e3a71ba96464b059bcfb04e48c4512848f56564efa91aa0a05f6efbf4380e8aa
+  metadata.gz: e2bffbab317006bdd799443ef1dc7e16d9527219261f91c9758504ae85aef638
+  data.tar.gz: b1e0f8f72d44878564573fcc8076af18defe14375d1bee4cd4946c72139bcc1e
 SHA512:
-  metadata.gz: adf6898a0e0bb8f15cc755fd64f6d7a86abfcadb915c2cf934171276ea80a76671fb423c57778c89b120684a4db211dc540f6e87e3d154b9c989e24bdbfe2904
-  data.tar.gz: a871127bfbc45d40c43e08efe282e134b2e021df7af7c9209fe60c443e1158b13a8b7f7328664c453fe1ffce30c51b3ee8cc77d2b39a78c92298de303e8be7bc
+  metadata.gz: d16eda21cb080e2dd7decc2522c4dac7c99536f3c720c1de7d64f0065edd7487c633450db9eeb687b12138b2763d3093628e0d169b82d7896c781e7c8298bb3c
+  data.tar.gz: 5f668930355e17877237892da08dc440630f2015253b072c715e324c38045598765c58cb84d9657d7769527d3f27774f8d4f03f6bec2cc1bb785bca9a308cce2

data/README.md

@@ -16,6 +16,40 @@ commands into a single `wip.yml`, and forwards them to `wslc.exe` / `wslc` as sa
 
 > **Status:** early release. Expect to track WSLC's own interface as it evolves.
 
+## Contents
+
+- [Which mode should you use?](#which-mode-should-you-use)
+- [Requirements & installation](#requirements--installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+  - [Container mode](#container-mode)
+  - [Compose mode](#compose-mode)
+  - [Compose mode (native)](#compose-mode-native)
+  - [.env](#env)
+  - [.dockerignore](#dockerignore)
+  - [Source sync](#source-sync)
+- [Commands](#commands)
+- [doctor](#doctor)
+- [Common errors](#common-errors)
+- [FAQ](#faq)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Roadmap](#roadmap)
+- [License](#license)
+
+## Which mode should you use?
+
+`wip.yml` runs in one of three modes, set with `mode:`. Pick the one that matches your project:
+
+| Situation | Use |
+|---|---|
+| No `compose.yml` — wip manages containers directly | [`mode: container`](#container-mode) (default) |
+| Have `compose.yml`, don't want to install a third-party tool | [`mode: compose-native`](#compose-mode-native) |
+| Have `compose.yml` and already use/prefer a third-party compose-for-`wslc` tool | [`mode: compose`](#compose-mode) |
+
+`wip init` picks `compose-native` automatically when it finds a `compose.yml`/`docker-compose.yml`
+next to it, and `container` otherwise — see [Commands](#commands).
+
 ## Requirements & installation
 
 Ruby 3.2+, WSL2, and Microsoft WSLC.
@@ -28,6 +62,9 @@ From source: `bundle install && bundle exec exe/wip version`.
 
 ## Quick start
 
+This walks through `mode: container` (the default). Already have a `compose.yml`? See
+[Which mode should you use?](#which-mode-should-you-use) first.
+
 ```bash
 gem install wslc-wip
 cd my-project
@@ -38,19 +75,19 @@ wip up -d
 wip rails console
 ```
 
-## Full configuration example
+## Configuration
 
 Put a `wip.yml` in your project root. Running from a subdirectory walks up to find it, or pass
 `--config PATH` to point at one explicitly.
 
+### Container mode
+
 ```yaml
 version: 1
-mode: container # default. This example is container mode end-to-end — see "Compose mode" below
-                # for mode: compose, which replaces container:/network:/dependencies: with a
-                # compose: block instead; the two don't mix within one wip.yml.
+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:
@@ -76,7 +113,7 @@ dependencies:
     env:
       MYSQL_ROOT_PASSWORD: password
       MYSQL_DATABASE: development
-commands:
+interaction:
   rails:
     type: exec
     command: bin/rails
@@ -101,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
@@ -112,23 +150,12 @@ 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.
 
-### .env
+`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`.
 
-Like `docker compose`, `wip` automatically loads a `.env` file next to `wip.yml` (one `KEY=VALUE`
-per line; `#` comments, blank lines, `export` prefixes, and quoted values are all supported) and
-passes its keys through as container environment variables on `build`, `up`, `run`, `exec`, and
-custom commands. `.env` only fills in keys that aren't already set by the primary container's
-`env` or a command/dependency's own `env` — those always win on conflict. Pass `--env-file PATH`
-to load a different file instead.
-
-### .dockerignore
-
-`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.
-
-### Dependency containers
+#### Dependency containers
 
 `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),
@@ -141,10 +168,118 @@ 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.
 
+### Compose mode
+
+If your project already has a real `compose.yml`, don't duplicate it in `dependencies:` — point
+`wip` at it instead:
+
+```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
+  file: compose.yml        # optional; auto-detected next to wip.yml otherwise
+  project: myapp            # optional; omitted lets the compose tool pick its own default
+```
+
+`compose:` is mutually exclusive with `dependencies:`/`network` — pick one orchestration path per
+project. In compose mode, `wip` becomes a thin bridge to an external compose-for-`wslc` CLI rather
+than reimplementing Compose itself.
+
+`wslc` itself has no native Compose support yet (tracked upstream in
+[microsoft/WSL#40948](https://github.com/microsoft/WSL/issues/40948)), and until it does,
+independent third-party tools fill the gap — for example
+[bacarndiaye/wslc-compose](https://github.com/bacarndiaye/wslc-compose) (Python) and
+[inuyume/wslc-compose](https://github.com/inuyume/wslc-compose) (Go), among others. `wslc` is new
+and still evolving, so expect more of these to show up (and existing ones to change) over time.
+`wip` deliberately doesn't pick a winner or default to any of them (unlike `wslc.command`, which
+defaults to `auto` and searches for `wslc.exe`/`wslc`): `compose.command` is required and treats
+every implementation equally — set it to whichever binary name or absolute path you've installed.
+Whichever one you use needs to understand `-f FILE [-p PROJECT] up|down|exec|logs`, the subset of
+the Compose CLI vocabulary `wip` drives. `wip doctor` reports whether the configured command is
+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 `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).
+- `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)
+
+Don't want to install a third-party compose-for-`wslc` tool at all? `mode: compose-native` parses
+`compose.yml` itself and drives `wslc` directly, the same way `mode: container` +`dependencies:`
+already does — no external binary, and `wip run` gets a real ephemeral `wslc run --rm` instead of
+the `exec` fallback above:
+
+```yaml
+version: 1
+mode: compose-native
+
+compose:
+  service: app    # required: which compose service wip run/exec/NAME target
+  file: compose.yml # optional; auto-detected next to wip.yml otherwise
+  project: myapp    # optional; also names wip's own project network (defaults to the wip.yml
+                    # directory's name) so services can reach each other by name
+```
+
+There's no `compose.command` here (no external binary to name), and no top-level `container:` —
+`compose.service` already names it.
+
+This is explicitly a stopgap for as long as `wslc` itself has no native Compose support (tracked
+upstream in [microsoft/WSL#40948](https://github.com/microsoft/WSL/issues/40948)) and third-party
+compose-for-`wslc` tools stay incomplete. It only understands a minimal subset of the Compose spec.
+Within `services.<name>:`, anything outside that subset is a load-time `ConfigError` naming the
+offending key, rather than silently ignored — but everything *outside* `services:` at the document's
+top level (`networks:`, `volumes:`, `configs:`, `secrets:`, ...) is the one exception: it's read by
+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`
+  (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
+  than `service_started` is rejected, since there's no health-check support). `tty`, `stdin_open`,
+  and `networks` are accepted but silently ignored: TTY/stdin allocation is already decided per
+  invocation (see "TTY allocation" below), not fixed per service, and every service already shares
+  the one project network `compose.project` sets up.
+- `wip logs` takes at most one `SERVICE` (defaulting to `compose.service`) — `wslc logs`, like
+  `docker logs`, follows a single container, unlike a real compose tool's multi-service view.
+- `sync:` behaves exactly like `mode: container`'s (falls back to the primary service's own image,
+  defaults to `sync.mode: exec`) — none of the external bridge's `sync.image`/`sync.build`
+  requirement applies, since wip itself boots every container here.
+
+### .env
+
+Like `docker compose`, `wip` automatically loads a `.env` file next to `wip.yml` (one `KEY=VALUE`
+per line; `#` comments, blank lines, `export` prefixes, and quoted values are all supported) and
+passes its keys through as container environment variables on `build`, `up`, `run`, `exec`, and
+custom commands. `.env` only fills in keys that aren't already set by the primary container's
+`env` or a command/dependency's own `env` — those always win on conflict. Pass `--env-file PATH`
+to load a different file instead.
+
+### .dockerignore
+
+`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
 
 Bind-mounting the app directory (`.:/app`) is what usually makes a container boot crawl under
@@ -221,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
@@ -275,93 +410,6 @@ and uses the result, tagged `wip-sync-<container>:latest` by default (`build.tag
 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
-`wip` at it instead:
-
-```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
-  file: compose.yml        # optional; auto-detected next to wip.yml otherwise
-  project: myapp            # optional; omitted lets the compose tool pick its own default
-```
-
-`compose:` is mutually exclusive with `dependencies:`/`network` — pick one orchestration path per
-project. In compose mode, `wip` becomes a thin bridge to an external compose-for-`wslc` CLI rather
-than reimplementing Compose itself.
-
-`wslc` itself has no native Compose support yet (tracked upstream in
-[microsoft/WSL#40948](https://github.com/microsoft/WSL/issues/40948)), and until it does,
-independent third-party tools fill the gap — for example
-[bacarndiaye/wslc-compose](https://github.com/bacarndiaye/wslc-compose) (Python) and
-[inuyume/wslc-compose](https://github.com/inuyume/wslc-compose) (Go), among others. `wslc` is new
-and still evolving, so expect more of these to show up (and existing ones to change) over time.
-`wip` deliberately doesn't pick a winner or default to any of them (unlike `wslc.command`, which
-defaults to `auto` and searches for `wslc.exe`/`wslc`): `compose.command` is required and treats
-every implementation equally — set it to whichever binary name or absolute path you've installed.
-Whichever one you use needs to understand `-f FILE [-p PROJECT] up|down|exec|logs`, the subset of
-the Compose CLI vocabulary `wip` drives. `wip doctor` reports whether the configured command is
-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
-  `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
-  compose tool's own `build`/`up --build` directly; compose owns builds for its own services.
-
-### Compose mode (native)
-
-Don't want to install a third-party compose-for-`wslc` tool at all? `mode: compose-native` parses
-`compose.yml` itself and drives `wslc` directly, the same way `mode: container` +`dependencies:`
-already does — no external binary, and `wip run` gets a real ephemeral `wslc run --rm` instead of
-the `exec` fallback above:
-
-```yaml
-version: 1
-mode: compose-native
-
-compose:
-  service: app    # required: which compose service wip run/exec/NAME target
-  file: compose.yml # optional; auto-detected next to wip.yml otherwise
-  project: myapp    # optional; also names wip's own project network (defaults to the wip.yml
-                    # directory's name) so services can reach each other by name
-```
-
-There's no `compose.command` here (no external binary to name), and no top-level `container:` —
-`compose.service` already names it.
-
-This is explicitly a stopgap for as long as `wslc` itself has no native Compose support (tracked
-upstream in [microsoft/WSL#40948](https://github.com/microsoft/WSL/issues/40948)) and third-party
-compose-for-`wslc` tools stay incomplete. It only understands a minimal subset of the Compose spec.
-Within `services.<name>:`, anything outside that subset is a load-time `ConfigError` naming the
-offending key, rather than silently ignored — but everything *outside* `services:` at the document's
-top level (`networks:`, `volumes:`, `configs:`, `secrets:`, ...) is the one exception: it's read by
-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`
-  (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
-  than `service_started` is rejected, since there's no health-check support). `tty`, `stdin_open`,
-  and `networks` are accepted but silently ignored: TTY/stdin allocation is already decided per
-  invocation (see "TTY allocation" below), not fixed per service, and every service already shares
-  the one project network `compose.project` sets up.
-- `wip logs` takes at most one `SERVICE` (defaulting to `compose.service`) — `wslc logs`, like
-  `docker logs`, follows a single container, unlike a real compose tool's multi-service view.
-- `sync:` behaves exactly like `mode: container`'s (falls back to the primary service's own image,
-  defaults to `sync.mode: exec`) — none of the external bridge's `sync.image`/`sync.build`
-  requirement applies, since wip itself boots every container here.
-
 ## Commands
 
 | Command | Description |
@@ -379,7 +427,7 @@ valid compose.yml over sections it doesn't need to look at:
 | `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.
@@ -474,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
@@ -486,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
 
@@ -494,19 +611,10 @@ Bug reports and pull requests are welcome on [GitHub](https://github.com/slidict
 [CONTRIBUTING.md](CONTRIBUTING.md) for commit conventions, versioning policy, and the PR
 checklist.
 
-## Not in the initial release
-
-Full Compose compatibility isn't reimplemented in `wip` itself — `mode: compose-native` parses
-`compose.yml` and drives `wslc` directly, but only covers a minimal subset (see
-[Compose mode (native)](#compose-mode-native)); full parity is otherwise available by delegating
-to a third-party compose-for-`wslc` tool (see [Compose mode](#compose-mode)). A resident/daemon
-process, a GUI, PowerShell-specific tuning, direct registry API/manifest parsing, self-update, and
-plugins are all unimplemented.
-
 ## 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
@@ -520,8 +628,11 @@ 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`). What's still planned
-for `wip`, roughly in priority order:
+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
+planned. What's still planned for `wip`, roughly in priority order:
 
 1. **`wip provision`** — a dip-style one-shot bootstrap hook (build → up deps → install deps →
    create/migrate/seed DB) so a new contributor can go from `git clone` to a working environment
@@ -541,7 +652,7 @@ for `wip`, roughly in priority order:
 
 Each of these should stay additive to the existing `wip.yml` shape — no breaking changes to
 `container`, `network`, `commands`, `dependencies`, or `compose` are planned. A resident daemon
-and a GUI remain out of scope; see "Not in the initial release" above.
+and a GUI remain out of scope.
 
 ## License
 

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 = '0.18.2'
+  VERSION = '1.1.0'
 end

metadata

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