wslc-wip 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37c2e70c286c4dd7b163201674eff9b4111fbe3f05ef032500a5b7ac516f97b5
-  data.tar.gz: fbad7b94e10bb0cbd9efc8c70f1a2546830ac0c20f276a925b48e0d668679902
+  metadata.gz: 585bcc92d8ab78eb38c134e779738c6eb527dd57b8aad87bbfae18a724a10974
+  data.tar.gz: 908afba4af5470c777896379a143a6759ab08ef453f6d8baf727e22ff4a8adf2
 SHA512:
-  metadata.gz: 70319980be04f8abdbb6d5e167e8941ca4fa3a8ab65b0cd71ec884daff639205a70935b4c5a756ec3403678982c2859423051930379aa3d79f302506b0f88326
-  data.tar.gz: f100b5622d566ab77da4437cb028138a7fa33f47d4d19ff70874c683e2995e9c3213bc95b0109c03c82556827a26ee22b47a034bf7fc96895effc2c8fcb3950f
+  metadata.gz: c01879ea531294531b0283b53a7fdfe01586a8c9c17dbd83814ad92c11d915cecd5f141a0ffd6f94f96dd633e0e63657f15a10ec4f1e372cc53ea0207a8b22be
+  data.tar.gz: e3cb38ab627b56487b8965f9107c03f7081fd24defb2a731415af8e9533cd51e5af1eea5da3f0075d854371cbb77ed6e1b75c8843737df4528e806965bfc5137

data/README.md

@@ -1,3 +1,5 @@
+<img src="docs/logo.png" alt="wip logo" width="120" align="left">
+
 # wip
 
 [![Tests](https://github.com/slidict/wip/actions/workflows/test.yml/badge.svg)](https://github.com/slidict/wip/actions/workflows/test.yml)
@@ -5,7 +7,7 @@
 [![License: MIT](https://img.shields.io/github/license/slidict/wip.svg)](LICENSE)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](wslc-wip.gemspec)
 
-Homepage: https://wslc-wip.slidict.com/
+Homepage: https://wslc-wip.slidict.com/ · **[Full documentation: wip Wiki](https://github.com/slidict/wip/wiki)**
 
 `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
@@ -16,25 +18,19 @@ 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.
 
+This README covers the fastest path to a running `wip.yml`. For everything else — every config
+key, every command's flags, guides, and troubleshooting — see the **[wip Wiki](https://github.com/slidict/wip/wiki)**.
+
 ## 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?
@@ -43,12 +39,14 @@ commands into a single `wip.yml`, and forwards them to `wslc.exe` / `wslc` as sa
 
 | 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) |
+| No `compose.yml` — wip manages containers directly | `mode: container` (default) |
+| Have `compose.yml`, don't want to install a third-party tool | `mode: compose-native` |
+| Have `compose.yml` and already use/prefer a third-party compose-for-`wslc` tool | `mode: compose` |
 
-`wip init` picks `compose-native` automatically when it finds a `compose.yml`/`docker-compose.yml`
-next to it, and `container` otherwise — see [Commands](#commands).
+`wip init` picks `compose-native` automatically when it finds a `compose.yml`, `compose.yaml`,
+`docker-compose.yml`, or `docker-compose.yaml` next to it, and `container` otherwise — see
+[Commands](#commands). For the full breakdown and trade-offs, see
+[Choosing a Mode](https://github.com/slidict/wip/wiki/Choosing-a-Mode) on the wiki.
 
 ## Requirements & installation
 
@@ -63,7 +61,8 @@ 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.
+[Which mode should you use?](#which-mode-should-you-use) first, or read the wiki's
+[Getting Started](https://github.com/slidict/wip/wiki/Getting-Started) guide.
 
 ```bash
 gem install wslc-wip
@@ -80,8 +79,6 @@ wip rails console
 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
@@ -148,450 +145,67 @@ sync: # optional; mirror the source into a named volume instead of bind-mounting
 
 `env` values are stringified. `wip config` masks any key matching token, password, secret,
 credential, or auth. Keep real secrets out of the config file and in your runtime environment
-instead.
+instead — see [Secret Masking](https://github.com/slidict/wip/wiki/Secret-Masking).
 
 `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
-sidecar services (a database, Redis, ...) alongside it. Each entry accepts `image` (required),
-`command`, `env`, `ports`, `volumes`, and `workdir`; there's no separate, differently-shaped block
-for "the one you exec into." `container:` has no default; once `dependencies:` has any entries,
-wip needs to be told explicitly which one is primary rather than guessing a name.
-
-What sets the primary entry apart is operational, not structural: `wip up` brings up every other
-entry by name first (creating `network:` beforehand if it doesn't exist and set), then boots or
-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`/`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:, 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
-  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` (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
-
-Bind-mounting the app directory (`.:/app`) is what usually makes a container boot crawl under
-wslc — see [Slow boot when the app directory is
-bind-mounted](#slow-boot-when-the-app-directory-is-bind-mounted) for why. A `sync:` block hands
-that problem to `wip`: the source is mounted read-only, the app runs off a named volume, and wip
-mirrors one into the other with `rsync`.
-
-`wip up`'s pre-boot mirror always uses a throwaway container (the primary one isn't running yet),
-so `sync.image`/`sync.build` apply there regardless of `sync.mode` — falling back to the primary
-container's own image if neither is set under `mode: container`/`compose-native` (both have a
-`dependencies:` entry to borrow it from); `mode: compose` has no such entry, so one of
-`sync.image`/`sync.build` is required there. Where `sync.mode` actually matters is every mirror
-*after* that: under `sync.mode: exec` (the default for `mode: container`/`compose-native`), `wip
-sync`/`wip sync --watch` run `rsync` inside the already-running primary container instead, so
-*that* image needs `rsync` installed — `sync.image`/`sync.build` are ignored for these. Under
-`sync.mode: run`, every mirror (pre-boot included) uses a throwaway container, so `sync.image`/
-`sync.build` (or the primary image fallback, where available) need `rsync` throughout.
-
-```yaml
-sync:
-  source: .          # host path, relative to wip.yml (default: the wip.yml directory)
-  target: /app       # container path served by the volume (default: the primary container's workdir, else /app)
-  volume: app-src    # named volume holding the mirror (default: "<container>-src")
-  mount: /host-src   # where the source is bind-mounted read-only (default: /host-src)
-  exclude:           # rsync --exclude patterns
-    - .git
-    - tmp/
-    - node_modules/
-  delete: true       # rsync --delete (default: true)
-  command: rsync     # binary that does the mirroring (default: rsync)
-  options: []        # extra flags appended to the rsync invocation
-  interval: 2        # seconds between syncs for `wip sync --watch` (default: 2)
-  mode: exec         # exec (mirror inside the running container) or run (a throwaway one);
-                      # default: exec for `mode: container`, run for `mode: compose`
-  image: null        # image for the mirror container; unused under mode: container unless set
-                      # (falls back to the primary container's own image). Under mode: compose,
-                      # one of image or build is required (there's no dependencies: entry to fall
-                      # back to)
-  build:              # optional; has wip build the mirror image itself instead of requiring one to
-                       # already exist. build.tag wins over image if both are set.
-    dockerfile: |
-      FROM alpine:latest
-      RUN apk add --no-cache rsync
-    tag: null          # optional (default: "wip-sync-<container>:latest")
-```
-
-`wip init --template NAME` writes `exclude`'s default list live, picked from that stack's own
-`github/gitignore` template:
-
-| `--template` | Stack | Default `exclude` |
-|---|---|---|
-| `rails` | Rails | `.git`, `log/`, `tmp/`, `storage/`, `public/assets/`, `public/packs/`, `.bundle/`, `vendor/bundle/`, `coverage/`, `node_modules/` |
-| `node` | Node.js | `.git`, `node_modules/`, `dist/`, `build/`, `.next/`, `.cache/`, `coverage/` |
-| `rust` | Rust | `.git`, `target/` |
-| `csharp` | C# | `.git`, `bin/`, `obj/`, `.vs/`, `packages/` |
-| (omitted) | — | `.git`, `tmp/`, `node_modules/` |
-
-Everything below `sync:` is optional — `sync: {}` alone already works. With it in place:
-
-- Any `volumes` entry on the primary container mounting `target` (the usual `.:/app`) is replaced
-  by `<source>:/host-src:ro` plus `app-src:/app`, so the running app only ever touches the volume.
-  Other volumes (`bundle:/usr/local/bundle`, ...) are passed through untouched, and sidecar
-  `dependencies:` entries keep mounting whatever they declare.
-- `wip up` mirrors the source into the volume before the container boots; `wip up --no-sync`
-  skips that step.
-- `wip sync` mirrors on demand: `sync.mode: exec` (the default under `mode: container`) execs
-  rsync inside the already-running container; `sync.mode: run` always uses a throwaway container
-  with the same mounts instead. Which one runs is fixed by config, not guessed at from whether a
-  container happens to be up.
-- `wip sync --watch [--interval N]` keeps re-syncing until Ctrl-C, so host edits reach the
-  container with a short delay. Run it in a second terminal alongside `wip up -d`.
-- `wip doctor` reports the resolved source, volume, and target, and fails if the source is missing.
-- 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 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
-(`RUN apt-get update && apt-get install -y rsync`) — or point `sync.command` at a copy tool the
-image already has. And the mirror is one-way (host → volume): anything the app writes under
-`target` is removed by the next `--delete` pass unless you `exclude` it, give it its own volume,
-or set `delete: false`.
-
-`sync:` works alongside `mode: compose` too, but two things change:
-
-- Compose still owns the volume layout, so wip doesn't rewrite any mounts for you: the compose
-  service that runs your app must itself declare a named volume with the exact same name as
-  `sync.volume` (`<container>-src` by default) mounted at the path your app expects, e.g.:
-  ```yaml
-  # compose.yml
-  services:
-    app:
-      volumes:
-        - app-src:/app
-  volumes:
-    app-src:
-  ```
-  wip's mirror writes into that volume from a separate, disposable container; it never touches
-  the compose service directly.
-- `sync.mode` defaults to `run` and can't be set to `exec` (only a container wip itself booted is
-  guaranteed to have the read-only source mount attached, which compose services never do), and
-  `sync.image` or `sync.build` becomes required, since that disposable container needs an image
-  from somewhere — under `mode: container` it borrows the primary `dependencies:` entry's image,
-  but compose mode has no such entry to borrow from.
-
-`wip up`'s pre-boot mirror (and the `--no-sync` flag that skips it) works the same way under
-`mode: compose` as it does otherwise: the source is mirrored into the volume before
-`compose up` starts the service that mounts it.
-
-Since `sync.mode: run` boots a fresh container on every mirror, reusing your app's full image here
-just adds startup overhead for something that only ever runs `rsync`. A dedicated, minimal image is
-worth it — `wip` doesn't publish or default to one itself (same reasoning as `compose.command`:
-picking a specific third-party image for you isn't its call to make), but `sync.build` covers it
-without needing to manage a separate image yourself:
-
-```yaml
-sync:
-  build:
-    dockerfile: |
-      FROM alpine:latest
-      RUN apk add --no-cache rsync
-```
-
-wip builds this once per `wip up`/`wip sync` invocation (not on every `--watch` tick — see above)
-and uses the result, tagged `wip-sync-<container>:latest` by default (`build.tag` overrides it).
-Prefer managing the image yourself instead? Build and tag it however you like, then set `sync.image`
-to that tag directly — `sync.build`'s tag wins if both are set, so don't configure both at once.
+projects that already use `commands:`. The two are aliases for the same feature; declaring both in
+the same `wip.yml` is a `ConfigError`. See [Interactions](https://github.com/slidict/wip/wiki/Interactions).
+
+Every key above is covered across the wiki's feature pages, with the full behavior, edge cases,
+and examples — start at the
+**[Configuration Reference](https://github.com/slidict/wip/wiki/Configuration-Reference)**. Notably:
+
+- [Dependencies](https://github.com/slidict/wip/wiki/Dependencies) — the primary container vs. sidecars
+- [Restart Policies](https://github.com/slidict/wip/wiki/Restart-Policies) /
+  [Auto Restarting Containers](https://github.com/slidict/wip/wiki/Auto-Restarting-Containers) — `restart:` and `wip up --watch`
+- [Compose Mode](https://github.com/slidict/wip/wiki/Compose-Mode) — bridging to a third-party compose-for-`wslc` tool
+- [Compose Native Mode](https://github.com/slidict/wip/wiki/Compose-Native-Mode) — wip parsing `compose.yml` itself
+- [Env Files](https://github.com/slidict/wip/wiki/Env-Files) — `.env` loading and precedence
+- [Dockerignore](https://github.com/slidict/wip/wiki/Dockerignore) / [Shadow Build Context](https://github.com/slidict/wip/wiki/Shadow-Build-Context)
+- [Source Sync](https://github.com/slidict/wip/wiki/Source-Sync) / [Sync Modes](https://github.com/slidict/wip/wiki/Sync-Modes) / [Continuous Sync](https://github.com/slidict/wip/wiki/Continuous-Sync)
 
 ## Commands
 
 | Command | Description |
 |---|---|
-| `wip init [--force] [--template NAME]` | Write a starter `wip.yml`: `mode: compose-native` if a `compose.yml`/`docker-compose.yml` is found next to it, `mode: container` otherwise. `--template` picks `sync.exclude`'s default patterns for a stack (`rails`, `node`, `rust`, `csharp`); omitted, it falls back to `.git`/`tmp/`/`node_modules/`. Refuses to overwrite an existing `wip.yml` unless `--force` |
+| `wip init [--force] [--template NAME]` | Write a starter `wip.yml`: `mode: compose-native` if a `compose.yml`, `compose.yaml`, `docker-compose.yml`, or `docker-compose.yaml` is found next to it, `mode: container` otherwise |
 | `wip version` | wip's version, plus WSLC's if it can be detected |
 | `wip doctor` | Diagnose WSL2, interop, WSLC, config, architecture, and Git |
 | `wip config` | Print the effective configuration (secrets masked) |
-| `wip build [--no-cache] [-- OPTIONS]` | Build the image from the `build` definition. `wslc build` reuses matching local layers by default; `--no-cache` disables that. |
-| `wip up [-d] [--no-sync] [--no-cache]` | Start the primary `dependencies:` entry (`container:` names which one) and its sidecars (creating any that are missing, on `network:` if set). `-d` runs the main container in the background; with `sync:` configured, the source is mirrored into the volume first unless `--no-sync` |
-| `wip stop` | Stop the primary container and its sidecar `dependencies:` without removing them |
-| `wip down` | Stop and remove the primary container and its sidecar `dependencies:` |
+| `wip build [--no-cache] [-- OPTIONS]` | Build the image from the `build` definition |
+| `wip up [-d] [--no-sync] [--no-cache] [--watch] [--interval N]` | Start the configured stack, creating it if necessary |
+| `wip stop` | Stop the configured stack without removing it |
+| `wip down` | Stop and remove the configured stack |
 | `wip exec [--no-interactive] COMMAND...` | Run a command in the existing container |
-| `wip run [--no-interactive] COMMAND...` | Run a command in a new `--rm` container (mode: compose `exec`s into `compose.service` instead — see "Compose mode" above) |
+| `wip run [--no-interactive] COMMAND...` | Run a command in a new `--rm` container (`mode: compose` has no ephemeral run — falls back to `exec` in the running service, with a warning) |
 | `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 logs [-f] [SERVICE...]` | Follow compose service logs (compose modes only; under `mode: compose-native`, at most one `SERVICE`) |
+| `wip sync [-w\|--watch] [--interval N]` | Mirror the source into the sync volume once, or keep re-syncing with `--watch` (needs `sync:`) |
 | `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.
-
-Pass `--debug` (or set `WIP_DEBUG=1`) to see where time is going: wip prints each step it takes —
-checking for an existing network/container/dependency, and running the resolved `wslc`/`docker`
-command — along with how long that step took, e.g.:
-
-```console
-$ wip rails c --debug
-wip: [debug] running: wslc.exe exec -it -w /app app bin/rails c
-+ wslc.exe exec -it -w /app app bin/rails c
-...
-wip: [debug] done in 4.32s: running: wslc.exe exec -it -w /app app bin/rails c
-```
-
-For long-running interactive commands (like `rails c`), the "done" line only prints after you
-exit, but the timestamp of the `+ ...` line tells you when wip finished its own setup and handed
-off to `wslc`/`docker` — useful for telling wip-side overhead apart from time spent booting inside
-the container.
-
-While a step is still running, wip also prints a host resource snapshot (load average, memory,
-disk I/O, and the top CPU-consuming processes) every 5 seconds, so a hang is visible even before
-the command has produced any output of its own:
+Every command has flags, per-mode behavior, and examples on its own wiki page — see the
+**[CLI Command Reference](https://github.com/slidict/wip/wiki/CLI-Command-Reference)**.
 
-```console
-wip: [debug] still running (load 3.42 2.10 1.05 | mem 6.1G/15.6G | io read 12000KB/s write 400KB/s | top: wslc.exe(8842) cpu 61.0%/mem 3.2%, ...): running: wslc.exe exec -it -w /app app bin/rails c
-```
-
-The disk I/O figure is worth watching first if the host's CPU and memory look idle — a slow
-`bundle`/`rails` boot is often WSL2's bind-mounted (`.:/app`-style) volumes doing a lot of small
-reads, not the container starving for CPU.
-
-For commands that hand the real terminal to the child (`-it`, e.g. `rails c`), these periodic
-snapshots go to a log file instead of your terminal — wip prints the path once at the start —
-since writing into a terminal the child controls in raw mode would garble both outputs. Commands
-that don't need a TTY still get the snapshots printed live.
-
-Override that choice with `--debug-log`:
+Pass `--debug` (or set `WIP_DEBUG=1`) to see where time is going: wip prints each step it takes,
+along with a periodic host resource snapshot (load, memory, disk I/O, top processes), so a hang is
+visible even before a command produces output. See
+[Debug Output](https://github.com/slidict/wip/wiki/Debug-Output) for the full behavior and the
+`--debug-log` option.
 
-- `--debug-log=-` forces snapshots inline even for `-it` commands (only useful if you know your
-  terminal/pager can tolerate the interleaving).
-- `--debug-log=PATH` always writes snapshots to `PATH`, including for non-TTY commands, e.g. to
-  keep every run's snapshots in one place: `wip rails c --debug --debug-log=/tmp/wip-debug.log`.
-
-## doctor
-
-Each check prints as `[OK]`, `[WARN]`, or `[FAIL]`. Warnings alone exit 0; a WSL2, interop, WSLC,
-or config problem that blocks execution exits 1. Git being unreachable from the real build
-environment is only a warning.
+`wip doctor` prints `[OK]`/`[WARN]`/`[FAIL]` per check; warnings alone exit 0, a blocking problem
+exits 1. See [`wip doctor`](https://github.com/slidict/wip/wiki/wip-doctor).
 
 ## Common errors
 
-### WSLC not found
-
-Install or update the WSL container tooling, then run `wip doctor`. `auto` looks for `wslc.exe`,
-`wslc`, then `/mnt/c/Windows/System32/wslc.exe`, in that order.
+- [WSLC not found](https://github.com/slidict/wip/wiki/WSLC-Not-Found)
+- [Docker Hub / registry authentication](https://github.com/slidict/wip/wiki/Registry-Authentication)
+- [Slow boot when the app directory is bind-mounted](https://github.com/slidict/wip/wiki/Fixing-a-Slow-Boot)
+- [CPU architecture mismatch](https://github.com/slidict/wip/wiki/Architecture-Mismatch)
 
-### Docker Hub authentication
-
-When `pull access denied` (or similar) is detected, wip suggests how to log in:
-
-```bash
-wslc registry login -u <username> docker.io
-```
-
-### Slow boot when the app directory is bind-mounted
-
-wslc containers run in their own VM, so a bind-mounted host directory (`.:/app`) is always shared
-in over virtiofs, even when the host path is already on WSL's native filesystem. Frameworks that
-scan large directory trees at startup (Ruby's Zeitwerk autoloader, for example) issue many small
-per-file stat/open calls, and each one is a round trip through that layer — CPU on the Windows
-side can look busy while almost no data is actually transferred, and the process can appear hung
-for minutes with barely any resource usage to show for it.
-
-If a debug log shows a boot-time command "stuck" with low CPU/mem/IO in `resource_monitor`'s
-output, this is worth checking before assuming the app itself is broken. The fix is to stop
-bind-mounting the source live and mirror it into a named volume instead, so the app only ever
-touches fast native storage once it's running. `wip` does that for you — add a `sync:` block and
-it rewrites the mounts, mirrors before boot, and re-syncs on demand. See [Source
-sync](#source-sync).
-
-### CPU architecture mismatch
-
-Check the image and publish a multi-arch (amd64/arm64) image:
-
-```bash
-docker buildx imagetools inspect <image>
-docker buildx build \
-  --platform linux/amd64,linux/arm64 \
-  -t <image> \
-  --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).
+More errors, causes, and fixes are indexed on the wiki's
+**[Troubleshooting & FAQ](https://github.com/slidict/wip/wiki/Troubleshooting-and-FAQ)** page,
+including [Configuration Errors](https://github.com/slidict/wip/wiki/Configuration-Errors) (every
+`ConfigError` and what triggers it).
 
 ## Development
 
@@ -606,7 +220,9 @@ bundle exec rake
 
 The test suite doesn't need WSLC — the resolution, build, and execution layers are all
 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.
+both RSpec and RuboCop. GitHub Actions checks them on Ruby 3.2, 3.3, 3.4, and 4.0. See
+[Development](https://github.com/slidict/wip/wiki/Development) and
+[Architecture](https://github.com/slidict/wip/wiki/Architecture) on the wiki for more.
 
 ## Contributing
 
@@ -614,49 +230,6 @@ 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.
 
-## Roadmap
-
-`wip` already covers most of what [`dip`](https://github.com/bibendi/dip) adds on top of Compose —
-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
-[Compose mode (native)](#compose-mode-native)) parses `compose.yml` itself and drives `wslc`
-directly — no external binary in the loop, `wip run` gets a real `--rm` container, and iterating
-on the parser is faster than chasing a third-party tool's own bugs. It's still a deliberately
-minimal subset (`depends_on` ordering but no health checks, single-container `logs`, no named
-volumes/scaling), and `dependencies:` + `network:` remains the escape hatch for sidecars it
-doesn't model. Fuller Compose semantics beyond that subset stay behind delegating to a separate
-compose-for-`wslc` tool in [compose mode](#compose-mode) — which of those actually work is
-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 `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
-   in two commands (`wip provision && wip up`).
-2. **Config file merging** — `--config` currently accepts one file; support layering
-   (`wip.yml` + `wip.override.yml`, or a `WIP_CONFIG` list) for dev/CI/debug variants without
-   duplicating the whole file, plus a `wip config --resolved` view of the merged result.
-3. **Bind-mount boot time (`rails c`, `bundle`, ...)** — commands like `wip rails c` still start
-   noticeably slower than the equivalent under `docker compose`, mostly from WSL2 bind-mounted
-   (`.:/app`-style) volumes doing many small reads for gems/`node_modules` (use `--debug` to
-   confirm it's disk I/O and not `wip`'s own overhead). [Source sync](#source-sync) works around
-   this today by running the app off a named volume and mirroring the host tree into it, at the
-   cost of a one-way sync with a short delay. A tighter loop (host-side file watching instead of
-   interval polling, two-way sync) is the natural next step. We're also hoping for improvements on
-   the `wslc` side itself (faster bind-mount/cache behavior); `wip` will pick those up for free as
-   soon as they land.
-
-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.
-
 ## License
 
 [MIT License](LICENSE)

data/lib/wip/cli.rb

@@ -16,6 +16,42 @@ module Wip
     class_option :debug_log, type: :string, desc: 'Where --debug snapshots go: a file path, or "-" for inline'
     default_task :dispatch
 
+    # Thor only recognizes class_options (--config, --debug, ...) once they
+    # appear after the command name (`wip up --config foo`). Pull a leading
+    # run of them off the front of ARGV and reinsert it right after the
+    # command name so `wip --config foo up` works too.
+    GLOBAL_SWITCHES = {
+      '--config' => :value,
+      '--env-file' => :value,
+      '--debug' => :flag,
+      '--debug-log' => :value
+    }.freeze
+
+    def self.start(given_args = ARGV, config = {})
+      super(reorder_global_options(given_args), config)
+    end
+
+    def self.reorder_global_options(args)
+      remaining = args.dup
+      extracted = []
+
+      until remaining.empty?
+        name, _, inline_value = remaining.first.to_s.partition('=')
+        kind = GLOBAL_SWITCHES[name]
+        break unless kind
+
+        switch = remaining.shift
+        extracted << switch
+        extracted << remaining.shift if kind == :value && inline_value.empty? && !remaining.empty?
+      end
+
+      command_index = remaining.index { |arg| !arg.start_with?('-') }
+      return args if command_index.nil?
+
+      remaining.insert(command_index + 1, *extracted)
+      remaining
+    end
+
     def self.exit_on_failure? = true
 
     # Thor only falls back to the default task when no command name is given at
@@ -82,21 +118,41 @@ module Wip
       progress&.finish
     end
 
+    # Real Compose values that trigger a restart when a container's exited; `no` (the default)
+    # and anything unrecognized both mean "leave it alone." Exact match only — a typo'd value
+    # like "always-invalid" must stay inert, not accidentally match via a loose prefix check.
+    AUTO_RESTART_POLICIES = %w[always unless-stopped].freeze
+    ON_FAILURE_POLICY = /\Aon-failure(?::\d+)?\z/ # optional `:MAX_RETRIES` suffix, e.g. "on-failure:3"
+
+    # WSLC's `WslcContainerState` (confirmed via microsoft/WSL's own docs and
+    # ContainerModel.h — ContainerInformation#State has no custom JSON enum serializer, so
+    # nlohmann::json emits its raw ordinal): 0 invalid, 1 created, 2 running, 3 exited, 4
+    # deleted. Unlike Docker, there's no separate "dead" state — only `exited` is a live,
+    # restartable exit; `deleted` means the container itself is gone (needs `wip up` to
+    # recreate it, not `start`).
+    WSLC_CONTAINER_STATE_EXITED = 3
+
     desc 'up', 'Start the configured container and its dependencies, creating them if necessary'
     option :detach, type: :boolean, default: false, aliases: '-d'
     option :sync, type: :boolean, default: true, desc: 'Mirror the source into the sync volume first (--no-sync skips)'
     option :no_cache, type: :boolean, default: false, desc: 'Build compose-native images without cached layers'
+    option :watch, type: :boolean, default: false, aliases: '-w',
+                   desc: 'Poll dependencies and restart any exited one whose restart: allows it (implies -d)'
+    option :interval, type: :numeric, default: 5, desc: 'Seconds between --watch polls (default: 5)'
     def up
-      if load_config.compose?
-        sync_before_boot if options[:sync]
-        return execute(compose_bridge.up(detach: options[:detach]), interactive: tty?(!options[:detach]))
-      end
+      return up_via_compose_bridge if load_config.compose?
+
+      # Validated up front, before any startup side effect (image build, network/dependency/
+      # container creation) — otherwise a bad --interval would only surface as a ConfigError
+      # after already bringing everything up.
+      interval = restart_interval if options[:watch]
 
       ensure_compose_images
       ensure_network
       sidecar_names.each { |name| ensure_dependency(name) }
       sync_before_boot if options[:sync]
       ensure_container
+      watch_restarts(interval) if options[:watch]
     end
 
     desc 'sync', 'Mirror the source tree into the sync volume'
@@ -194,7 +250,7 @@ module Wip
 
     desc 'dispatch COMMAND [ARGS...]', 'Run a command defined in wip.yml'
     def dispatch(name = nil, *arguments)
-      raise ConfigError, 'A command is required' unless name
+      return help if name.nil?
 
       values = load_config.command(name) || raise(ConfigError, "Unknown command: #{name}")
       return dispatch_compose(name, values, arguments) if load_config.compose?
@@ -407,16 +463,79 @@ module Wip
       warn "wip: run `wip sync --watch` in another terminal to keep #{settings.target} up to date"
     end
 
+    def up_via_compose_bridge
+      if options[:watch]
+        raise ConfigError, '`wip up --watch` is not supported under mode: compose (wip never parses a ' \
+                           'compose.yml service list in that mode, so there is nothing to poll)'
+      end
+
+      sync_before_boot if options[:sync]
+      execute(compose_bridge.up(detach: options[:detach]), interactive: tty?(!options[:detach]))
+    end
+
     def ensure_container
       container = load_config.container
-      interactive = tty?(!options[:detach])
+      interactive = tty?(!detach?)
       if resource_exists?(builder.find)
         warn "wip: starting existing container '#{container}'"
-        execute(builder.start(detach: options[:detach]), interactive: interactive)
+        execute(builder.start(detach: detach?), interactive: interactive)
       else
         warn "wip: container '#{container}' not found, creating it"
-        execute(builder.up(detach: options[:detach]), interactive: interactive)
+        execute(builder.up(detach: detach?), interactive: interactive)
+      end
+    end
+
+    # --watch polls in a loop after boot, which can't share this one thread with an attached
+    # (`-it`) primary container — force the same effective behavior `-d` gives ensure_container.
+    def detach? = options[:detach] || options[:watch]
+
+    # Approximates Docker Compose's `restart:` policy via a foreground poll loop — not a
+    # background daemon/service (see README "Roadmap"); the same opt-in, keep-a-terminal-open
+    # shape as `wip sync --watch`.
+    def watch_restarts(interval)
+      names = load_config.dependencies.keys
+      warn "wip: watching #{names.join(', ')} for exited restart: containers every #{interval}s " \
+           '(running detached; Ctrl-C to stop)'
+      loop do
+        names.each { |name| restart_if_exited(name) }
+        sleep interval
       end
+    rescue Interrupt
+      warn "\nwip: watch stopped"
+    end
+
+    def restart_interval
+      raise ConfigError, '--interval must be a positive number' unless options[:interval].positive?
+
+      options[:interval]
+    end
+
+    # Status-based, not transition-based: each tick checks current state, not whether it *just*
+    # exited. Can't distinguish "crashed on its own" from "you ran `wip stop`/`wip down` in
+    # another terminal" — Ctrl-C this loop first if you're about to do either (see README).
+    def restart_if_exited(name)
+      policy = load_config.dependency(name)['restart']
+      return unless auto_restart?(policy)
+      return unless container_status(name) == WSLC_CONTAINER_STATE_EXITED
+
+      warn "wip: '#{name}' has exited, restarting it (restart: #{policy})"
+      execute(builder.dependency_start(name), exit_on_failure: false)
+    end
+
+    def auto_restart?(policy) = AUTO_RESTART_POLICIES.include?(policy) || ON_FAILURE_POLICY.match?(policy.to_s)
+
+    # Isolated to this one method: if a future wslc release changes this shape, fixing it here
+    # is a one-line change. Logs the raw entry under --debug so that's immediately visible
+    # instead of silently no-op'ing forever.
+    def container_status(name)
+      code, output = probe(builder.dependency_find(name))
+      return nil unless code.zero?
+
+      entry = JSON.parse(output).first
+      warn "wip: [debug] '#{name}': #{entry.inspect}" if debug?
+      entry&.fetch('State', nil)
+    rescue JSON::ParserError
+      nil
     end
   end
 end

data/lib/wip/compose_file.rb

@@ -15,15 +15,17 @@ module Wip
   # "Compose mode (native)") — once wslc ships that support, or a
   # compose-for-wslc tool reliably supports `run`.
   class ComposeFile
-    Service = Struct.new(:image, :build, :command, :env, :ports, :volumes, :workdir, :user, :depends_on, :profiles,
-                         keyword_init: true)
+    Service = Struct.new(:image, :build, :command, :env, :ports, :volumes, :workdir, :user, :restart, :depends_on,
+                         :profiles, keyword_init: true)
 
-    SERVICE_KEYS = %w[image build command environment ports volumes working_dir user depends_on profiles].freeze
+    SERVICE_KEYS = %w[image build command environment ports volumes working_dir user restart depends_on
+                      profiles].freeze
     # Real Compose keys that read as meaningful here but have nothing to map onto: TTY/stdin
     # allocation is decided per invocation (CommandBuilder#tty?), not per service; every
     # 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
+    # capability flag to forward `cap_add:` to. (`restart:` used to be here too, silently
+    # ignored — it's parsed below now and approximated by `wip up --watch`, see cli.rb.)
+    IGNORED_SERVICE_KEYS = %w[tty stdin_open networks cap_add].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'
@@ -65,14 +67,14 @@ module Wip
       end.to_h
     end
 
-    # Shaped like Config::DEPENDENCY_DEFAULTS expects: image/command/env/ports/volumes/workdir,
+    # Shaped like Config::DEPENDENCY_DEFAULTS expects: image/command/env/ports/volumes/workdir/restart,
     # in dependency order so callers iterating sidecars start them before their dependents.
     def to_dependencies_hash
       startable_order.to_h do |name|
         service = @services.fetch(name)
         [name, { 'image' => service.build ? image_tag(name, service) : service.image, 'command' => service.command,
                  'env' => service.env, 'ports' => service.ports, 'volumes' => service.volumes,
-                 'workdir' => service.workdir, 'user' => service.user }]
+                 'workdir' => service.workdir, 'user' => service.user, 'restart' => service.restart }]
       end
     end
 
@@ -97,6 +99,7 @@ module Wip
       Service.new(image: image, build: build, command: normalize_command(entry['command']),
                   env: normalize_env(name, entry['environment']), **normalize_service_lists(name, entry),
                   workdir: presence(entry['working_dir']), user: presence(entry['user']),
+                  restart: normalize_restart(entry['restart']),
                   depends_on: normalize_depends_on(name, entry['depends_on']))
     end
 
@@ -250,6 +253,20 @@ module Wip
       order << name
     end
 
+    # Compose's own default (`no`) applies whether restart: is absent or explicitly falsy —
+    # including the very common unquoted `restart: no`, which YAML resolves to the boolean
+    # `false`, not the string "no" (confirmed against this repo's own Psych: `YAML.safe_load
+    # ("restart: no")` => {"restart"=>false}). Every other value is accepted as-is, even ones
+    # outside always/unless-stopped/on-failure[:N]: this parser's job is to read what's in
+    # compose.yml, not police it — `wip up --watch` (cli.rb) decides which values it acts on.
+    # Rejecting a real, valid Compose value here would break projects that already work today
+    # (compose.yml predates wip, unlike wip.yml itself).
+    def normalize_restart(value)
+      return 'no' if value == false
+
+      presence(value) || 'no'
+    end
+
     def presence(value) = value.to_s.empty? ? nil : value.to_s
   end
 end

data/lib/wip/config.rb

@@ -8,7 +8,7 @@ module Wip
     # Applied to every dependencies: entry, primary container included — there
     # is no separate, differently-shaped bucket for "the one you exec into."
     DEPENDENCY_DEFAULTS = { 'workdir' => nil, 'user' => nil, 'interactive' => false, 'remove' => true,
-                            'env' => {}, 'ports' => [], 'volumes' => [] }.freeze
+                            'env' => {}, 'ports' => [], 'volumes' => [], 'restart' => 'no' }.freeze
     SECRET_PATTERN = /token|password|secret|credential|auth/i
     # Which orchestration path `up`/`down`/`sync`/etc. take. Explicit rather than
     # inferred from a `compose:` block's presence, so a config reader doesn't have
@@ -209,6 +209,16 @@ module Wip
       raise ConfigError, "dependencies.#{name} must set image" if entry['image'].to_s.empty?
 
       entry['env']&.transform_values!(&:to_s)
+      normalize_dependency_restart!(entry)
+    end
+
+    # Mirrors ComposeFile#normalize_restart: an unquoted `restart: no` parses as the boolean
+    # false rather than the string "no", and an explicit nil/"" should default the same way an
+    # absent key does (DEPENDENCY_DEFAULTS only fills in a genuinely *missing* key).
+    def normalize_dependency_restart!(entry)
+      return unless entry.key?('restart')
+
+      entry['restart'] = 'no' if entry['restart'] == false || entry['restart'].to_s.empty?
     end
 
     def stringify(object)

data/lib/wip/initializer.rb

@@ -11,6 +11,7 @@ module Wip
     # --template values wip init accepts, and the label used in the exclude: comment.
     TEMPLATE_LABELS = {
       'rails' => 'Rails',
+      'ruby' => 'Ruby',
       'node' => 'Node.js',
       'rust' => 'Rust',
       'csharp' => 'C#'
@@ -22,6 +23,7 @@ module Wip
     TEMPLATE_EXCLUDES = {
       'rails' => %w[.git log/ tmp/ storage/ public/assets/ public/packs/ .bundle/ vendor/bundle/
                     coverage/ node_modules/],
+      'ruby' => %w[.git log/ tmp/ .bundle/ vendor/bundle/ coverage/],
       'node' => %w[.git node_modules/ dist/ build/ .next/ .cache/ coverage/],
       'rust' => %w[.git target/],
       'csharp' => %w[.git bin/ obj/ .vs/ packages/]
@@ -159,6 +161,10 @@ module Wip
             # optional; remove the container after each run
             remove: true
 
+            # optional; restart policy `wip up --watch` polls for — always/unless-stopped/on-failure
+            # restart an exited container; "no" (the default) never does — see README
+            restart: "no"
+
             # optional; environment variables passed to the container, e.g. {FOO: bar}
             env: {}
 

data/lib/wip/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wslc-wip
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Wip contributors
@@ -56,15 +56,14 @@ files:
 - lib/wip/sync_settings.rb
 - lib/wip/variable_interpolation.rb
 - lib/wip/version.rb
-homepage: https://wslc-wip.slidict.com/
+homepage: https://github.com/slidict/wip
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  homepage_uri: https://wslc-wip.slidict.com/
-  source_code_uri: https://github.com/slidict/wip
+  homepage_uri: https://github.com/slidict/wip
   changelog_uri: https://github.com/slidict/wip/releases
-  bug_tracker_uri: https://github.com/slidict/wip/issues
+  source_code_uri: https://github.com/slidict/wip/tree/v1.1.4
 rdoc_options: []
 require_paths:
 - lib