wslc-wip 0.14.2 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f9b53bdcacc5491c788acf9af933f377cc0afe046ef133391ae866700145c83
-  data.tar.gz: b4ad717fba296d8082bc272238a8dd83afa206f7aaca67628e47186a0551c531
+  metadata.gz: c93fe67017509908d6ea81f4a80555ef193991504fb9f19cba7e598bd231635b
+  data.tar.gz: a19a5d66f81bfa19be592a778cba3369301f2f1c7f3c1a24a6a111513a2cceca
 SHA512:
-  metadata.gz: d65e654b92b30b19a987c2b239014bb0071b92bd99d0fdb09728e23ce3948488a330ebbf61878d7c81c7b4f588888d87720e41542f91e947c7358a02e495fbe2
-  data.tar.gz: 3008f5c32bfaa6771ef60a75d8445a427b3ddcbc9ef19f226602275a3b4eb997a6f9b7d99fc649dcc481dcfacbeea8b32e0c03a6902934f82d6c7534a08901af
+  metadata.gz: a3a6bd4bae10abee5389f7314dbbf7693882e7559412c9207569a7bed16206aceef5ed781b01ab96b94791dfe2a20bb16944b4fad7d2bfcd3e5fa74667576343
+  data.tar.gz: 439b070a2f3f00f9396b595dd939c251d1854cf8ba65ee3d6b93c55c512d90d85090e2be2b77cd2d68a8fc0aae149125b235fbba3fbd4d57a943dad7dc512410

data/README.md

@@ -181,6 +181,17 @@ sync:
     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
@@ -329,8 +340,11 @@ valid compose.yml over sections it doesn't need to look at:
   `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`, `depends_on` (ordering only — a `condition:` other than
-  `service_started` is rejected, since there's no health-check support).
+  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,
@@ -341,7 +355,7 @@ valid compose.yml over sections it doesn't need to look at:
 
 | Command | Description |
 |---|---|
-| `wip init [--force]` | Write a starter `wip.yml`: `mode: compose-native` if a `compose.yml`/`docker-compose.yml` is found next to it, `mode: container` otherwise. 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`/`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 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) |
@@ -470,21 +484,28 @@ checklist.
 
 ## Not in the initial release
 
-Full Compose compatibility isn't reimplemented in `wip` itself — `mode: compose-native` only
-covers a minimal subset (see [Compose mode (native)](#compose-mode-native)), and 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.
+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
-sidecar services via `dependencies:` + `network:`. Fuller Compose semantics
-(`depends_on` ordering/health checks, log aggregation, named volumes, profiles, scaling) are now
-handled by delegating to a separate compose-for-`wslc` tool in [compose mode](#compose-mode)
-rather than being reimplemented in `wip` itself. Which of those actually work is entirely up to
-the external tool you point `compose.command` at — `wip` only forwards
+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 `commands:` of type `run`/`build`). What's still planned

data/lib/wip/cli.rb

@@ -42,11 +42,13 @@ module Wip
 
     desc 'init', 'Create a starter wip.yml (detects an existing compose.yml/docker-compose.yml)'
     option :force, type: :boolean, default: false, desc: 'Overwrite an existing wip.yml'
+    option :template, type: :string,
+                      desc: "sync.exclude preset: #{Initializer::TEMPLATE_LABELS.keys.join(', ')} (default: none)"
     def init
       path = Pathname(options[:config] || ConfigLoader::FILENAME).expand_path
       raise Error, "#{path} already exists (use --force to overwrite)" if path.file? && !options[:force]
 
-      initializer = Initializer.new(dir: path.dirname)
+      initializer = Initializer.new(dir: path.dirname, template: options[:template])
       path.write(initializer.call)
       warn "wip: wrote #{path} (mode: #{initializer.compose? ? 'compose-native' : 'container'})"
     end
@@ -292,6 +294,7 @@ module Wip
     def ensure_compose_images
       load_config.compose_build_specs.each_value do |spec|
         extra = spec['dockerfile'] ? ['-f', spec['dockerfile']] : []
+        spec['args']&.each { |key, value| extra.push('--build-arg', "#{key}=#{value}") }
         execute(builder.build(settings: { 'context' => spec['context'], 'tag' => spec['tag'] }, extra: extra))
       end
     end

data/lib/wip/command_builder.rb

@@ -159,17 +159,26 @@ module Wip
     private
 
     def options(values, include_container: false, include_publish: true, sync: true)
-      result = []
-      result.push('-w', values['workdir']) unless values['workdir'].to_s.empty?
+      result = scalar_options(values)
       merged_env(values).each { |key, value| result.push('-e', "#{key}=#{value}") }
-      if include_publish
-        Array(values['ports']).each { |port| result.push('-p', port.to_s) }
-        volume_specs(values, sync: sync).each { |volume| result.push('-v', volume) }
-      end
+      result.concat(publish_options(values, sync: sync)) if include_publish
       result << required(values, 'container') if include_container
       result
     end
 
+    def scalar_options(values)
+      result = []
+      result.push('-w', values['workdir']) unless values['workdir'].to_s.empty?
+      result.push('-u', values['user']) unless values['user'].to_s.empty?
+      result
+    end
+
+    def publish_options(values, sync:)
+      result = Array(values['ports']).flat_map { |port| ['-p', port.to_s] }
+      volume_specs(values, sync: sync).each { |volume| result.push('-v', volume) }
+      result
+    end
+
     # With sync configured, a live bind mount of the target (`.:/app`) is
     # swapped for the read-only source mount plus the named volume, so the
     # running app only ever touches the volume.

data/lib/wip/compose_file.rb

@@ -15,10 +15,19 @@ 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, :depends_on, keyword_init: true)
-
-    SERVICE_KEYS = %w[image build command environment ports volumes working_dir depends_on].freeze
-    BUILD_KEYS = %w[context dockerfile].freeze
+    Service = Struct.new(:image, :build, :command, :env, :ports, :volumes, :workdir, :user, :depends_on,
+                         keyword_init: true)
+
+    SERVICE_KEYS = %w[image build command environment ports volumes working_dir user depends_on].freeze
+    # Real Compose keys that read as meaningful here but have nothing to map onto: TTY/stdin
+    # allocation is already decided per invocation (see CommandBuilder#tty?), not fixed per
+    # service; there's no per-service network to join beyond the one project network `network`
+    # (config.rb) already puts every service on; `wslc run`/`exec` has no restart-policy or
+    # capability flag to forward `restart:`/`cap_add:` to; and `profiles:` gates which services a
+    # real `docker compose up` starts by default, which doesn't apply here since wip never starts
+    # "every service" — only `compose.service` and whatever it reaches via `depends_on`.
+    IGNORED_SERVICE_KEYS = %w[tty stdin_open networks restart cap_add profiles].freeze
+    BUILD_KEYS = %w[context dockerfile args].freeze
     SUPPORTED_CONDITIONS = %w[service_started].freeze
 
     def self.load(path)
@@ -44,10 +53,10 @@ module Wip
     # name => {context:, dockerfile:, tag:} for every service with a build:.
     def build_specs
       @order.filter_map do |name|
-        build = @services.fetch(name).build
-        next unless build
+        service = @services.fetch(name)
+        next unless service.build
 
-        [name, build.merge('tag' => image_tag(name))]
+        [name, service.build.merge('tag' => image_tag(name, service))]
       end.to_h
     end
 
@@ -56,35 +65,41 @@ module Wip
     def to_dependencies_hash
       @order.to_h do |name|
         service = @services.fetch(name)
-        [name, { 'image' => service.build ? image_tag(name) : service.image, 'command' => service.command,
+        [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 }]
+                 'workdir' => service.workdir, 'user' => service.user }]
       end
     end
 
     private
 
-    def image_tag(name) = "wip-compose-#{name}:latest"
+    # A service naming both `build:` and `image:` builds via the former and tags the
+    # result with the latter (real Compose's own rule for that combination), instead
+    # of the auto-generated tag a build:-only service gets.
+    def image_tag(name, service) = service.image || "wip-compose-#{name}:latest"
 
     def build_service(name, entry)
       raise ConfigError, "#{@path}: services.#{name} must be a mapping" unless entry.is_a?(Hash)
 
-      unknown = entry.keys.map(&:to_s) - SERVICE_KEYS
+      unknown = entry.keys.map(&:to_s) - SERVICE_KEYS - IGNORED_SERVICE_KEYS
       raise ConfigError, "#{@path}: services.#{name} has unsupported key(s): #{unknown.join(', ')}" if unknown.any?
 
       image, build = image_or_build(name, entry)
       Service.new(image: image, build: build, command: normalize_command(entry['command']),
-                  env: normalize_env(name, entry['environment']),
-                  ports: normalize_list(name, entry['ports'], 'ports'),
-                  volumes: normalize_list(name, entry['volumes'], 'volumes'),
-                  workdir: presence(entry['working_dir']), depends_on: normalize_depends_on(name, entry['depends_on']))
+                  env: normalize_env(name, entry['environment']), **normalize_service_lists(name, entry),
+                  workdir: presence(entry['working_dir']), user: presence(entry['user']),
+                  depends_on: normalize_depends_on(name, entry['depends_on']))
+    end
+
+    def normalize_service_lists(name, entry)
+      { ports: normalize_list(name, entry['ports'], 'ports'),
+        volumes: normalize_list(name, entry['volumes'], 'volumes') }
     end
 
     def image_or_build(name, entry)
       image = presence(entry['image'])
       build = normalize_build(name, entry['build'])
       raise ConfigError, "#{@path}: services.#{name} must set image or build" unless image || build
-      raise ConfigError, "#{@path}: services.#{name} must not set both image and build" if image && build
 
       [image, build]
     end
@@ -118,27 +133,33 @@ module Wip
 
       context = resolve_context(presence(value['context']) || '.')
       dockerfile = presence(value['dockerfile'])
-      { 'context' => context, 'dockerfile' => dockerfile && Pathname(context).join(dockerfile).to_s }.compact
+      { 'context' => context, 'dockerfile' => dockerfile && Pathname(context).join(dockerfile).to_s,
+        'args' => normalize_kv(name, value['args'], 'build.args') }.compact
     end
 
     # build.context is relative to compose.yml's own directory (Compose's own rule),
     # not wherever `wip` happens to be invoked from.
     def resolve_context(raw) = Pathname(@path).expand_path.dirname.join(raw).to_s
 
-    def normalize_env(name, value)
+    def normalize_env(name, value) = normalize_kv(name, value, 'environment')
+
+    # Shared by `environment:` and `build.args:` — both accept a mapping or a
+    # KEY=VALUE array, and neither supports host environment pass-through (a
+    # null mapping value, or a bare KEY with no `=`).
+    def normalize_kv(name, value, label)
       return {} unless value
 
       case value
-      when Hash then normalize_env_mapping(name, value)
-      when Array then normalize_env_array(name, value)
-      else raise ConfigError, "#{@path}: services.#{name}.environment must be a mapping or an array of KEY=VALUE"
+      when Hash then normalize_kv_mapping(name, value, label)
+      when Array then normalize_kv_array(name, value, label)
+      else raise ConfigError, "#{@path}: services.#{name}.#{label} must be a mapping or an array of KEY=VALUE"
       end
     end
 
-    def normalize_env_mapping(name, value)
+    def normalize_kv_mapping(name, value, label)
       value.to_h do |key, val|
         if val.nil?
-          raise ConfigError, "#{@path}: services.#{name}.environment.#{key} must have a value " \
+          raise ConfigError, "#{@path}: services.#{name}.#{label}.#{key} must have a value " \
                              '(host environment pass-through is not supported)'
         end
 
@@ -146,10 +167,10 @@ module Wip
       end
     end
 
-    def normalize_env_array(name, value)
+    def normalize_kv_array(name, value, label)
       value.to_h do |item|
         key, val = item.to_s.split('=', 2)
-        raise ConfigError, "#{@path}: services.#{name}.environment entries must be KEY=VALUE" unless val
+        raise ConfigError, "#{@path}: services.#{name}.#{label} entries must be KEY=VALUE" unless val
 
         [key, val]
       end

data/lib/wip/config.rb

@@ -7,7 +7,7 @@ module Wip
   class Config
     # 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, 'interactive' => false, 'remove' => true,
+    DEPENDENCY_DEFAULTS = { 'workdir' => nil, 'user' => nil, 'interactive' => false, 'remove' => true,
                             'env' => {}, 'ports' => [], 'volumes' => [] }.freeze
     SECRET_PATTERN = /token|password|secret|credential|auth/i
     # Which orchestration path `up`/`down`/`sync`/etc. take. Explicit rather than

data/lib/wip/initializer.rb

@@ -8,72 +8,54 @@ module Wip
   # mode: compose-native and mode: container, since that's the one decision
   # `wip init` can't leave to a placeholder.
   class Initializer
-    # Appended to sync: in both templates. Every key here is either a plain constant
-    # default (safe to state literally) or, where commented, a value SyncSettings
-    # derives from another key (target from workdir, volume from the container/service
-    # name) — those stay unset so they keep tracking that key instead of going stale.
-    SYNC_EXTRAS = <<~YAML.chomp.gsub(/^/, '  ')
-      source: . # optional; host path to mirror (default: wip.yml directory)
-      # target: /app # optional; in-container mount point for the mirror (default: the container's workdir, else /app)
-      mount: /host-src # optional; read-only host mount inside the container
-      # volume: app-src # optional; named volume holding the mirrored tree (default: "<container>-src")
-      delete: true # optional; rsync --delete so removals on the host are mirrored too
-      exclude: [] # optional; rsync --exclude patterns, e.g. ["node_modules", "*.log"]
-      command: rsync # optional; mirror binary to shell out to
-      options: [] # optional; extra flags appended to the mirror command
-      interval: 2 # optional; seconds between mirrors
-      mode: exec # optional; exec (default, mirrors into the running container) | run (always a fresh container)
-      # image: your/image:tag # only needed if sync.mode: run (or under mode: compose); image the mirror container runs
-      # build: # alternative to image — let wip build a small dedicated mirror image itself
-      #   dockerfile: |
-      #     FROM alpine:latest
-      #     RUN apk add --no-cache rsync
-      #   tag: wip-sync-app:latest # optional (default: wip-sync-<container>:latest)
-    YAML
+    # --template values wip init accepts, and the label used in the exclude: comment.
+    TEMPLATE_LABELS = {
+      'rails' => 'Rails',
+      'node' => 'Node.js',
+      'rust' => 'Rust',
+      'csharp' => 'C#'
+    }.freeze
+
+    # sync.exclude patterns written live for each --template. They mirror that
+    # stack's own github/gitignore template — directories that are either
+    # regenerated inside the container or too large/irrelevant to mirror over rsync.
+    TEMPLATE_EXCLUDES = {
+      'rails' => %w[.git log/ tmp/ storage/ public/assets/ public/packs/ .bundle/ vendor/bundle/
+                    coverage/ node_modules/],
+      'node' => %w[.git node_modules/ dist/ build/ .next/ .cache/ coverage/],
+      'rust' => %w[.git target/],
+      'csharp' => %w[.git bin/ obj/ .vs/ packages/]
+    }.freeze
+
+    # Used when --template is omitted — the same starting point the README's own
+    # 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.
     COMMANDS_EXAMPLE = <<~YAML.chomp
-      # commands: # optional; custom subcommands, e.g. `wip test` — see README
+      # optional; custom subcommands, e.g. `wip test` — see README
+      # commands:
       #   test:
-      #     type: exec # optional; exec (default, runs in the running container) | run (fresh container) | build
-      #     command: bundle exec rspec # TODO
-    YAML
-
-    CONTAINER_TEMPLATE = <<~YAML.freeze
-      version: 1
-      mode: container # container | compose | compose-native (see README)
-      container: app # TODO: rename freely, as long as it matches a key under dependencies: below
-
-      wslc:
-        command: auto # optional; wslc binary/path wip shells out to ("auto" resolves it for you)
+      #     optional; exec (default, runs in the running container) | run (fresh container) | build
+      #     type: exec
 
-      # network: my-network # optional; container network name (mode: container only)
-
-      dependencies:
-        app: # this is the container wip creates, execs into, and runs commands in
-          image: your/image:tag # TODO: image to run
-          workdir: /app # TODO: adjust to match your image, or delete this line
-          interactive: false # optional; keep stdin open / allocate a tty
-          remove: true # optional; remove the container after each run
-          env: {} # optional; environment variables passed to the container, e.g. {FOO: bar}
-          ports: [] # optional; published ports, e.g. ["3000:3000"]
-          volumes: [] # optional; extra -v specs beyond the sync mounts below
-
-      #{COMMANDS_EXAMPLE}
-
-      sync: # optional; mirrors the source into a named volume instead of bind-mounting it live
-      #{SYNC_EXTRAS}
+      #     TODO
+      #     command: bundle exec rspec
     YAML
 
-    def initialize(dir: Dir.pwd)
+    def initialize(dir: Dir.pwd, template: nil)
+      raise Error, "unknown --template #{template.inspect} (valid: #{TEMPLATE_LABELS.keys.join(', ')})" \
+        if template && !TEMPLATE_LABELS.key?(template)
+
       @dir = dir
+      @template = template
     end
 
     def compose? = !!compose_file
 
     def call
-      compose? ? compose_template : CONTAINER_TEMPLATE
+      compose? ? compose_template : container_template
     end
 
     private
@@ -87,29 +69,156 @@ module Wip
     # without duplicating it as a live value that would go stale if the directory moves.
     def compose_project_default = Pathname(@dir).basename.to_s
 
+    def exclude_comment
+      if @template
+        "# optional; rsync --exclude patterns picked for --template #{@template} (#{TEMPLATE_LABELS[@template]})"
+      else
+        '# optional; rsync --exclude patterns, e.g. ["node_modules", "*.log"]'
+      end
+    end
+
+    def exclude_list
+      patterns = @template ? TEMPLATE_EXCLUDES.fetch(@template) : FALLBACK_EXCLUDES
+      patterns.map { |pattern| "  - #{pattern}" }.join("\n")
+    end
+
+    # Appended to sync: in both templates. Every key here is either a plain constant
+    # default (safe to state literally) or, where commented, a value SyncSettings
+    # derives from another key (target from workdir, volume from the container/service
+    # name) — those stay unset so they keep tracking that key instead of going stale.
+    # A blank line separates every key from its neighbor; the gsub only indents
+    # non-blank lines so those separators stay actual blank lines, not trailing
+    # whitespace.
+    def sync_extras
+      <<~YAML.chomp.gsub(/^(?=.)/, '  ')
+        # optional; host path to mirror (default: wip.yml directory)
+        source: .
+
+        # optional; in-container mount point for the mirror (default: the container's workdir, else /app)
+        # target: /app
+
+        # optional; read-only host mount inside the container
+        mount: /host-src
+
+        # optional; named volume holding the mirrored tree (default: "<container>-src")
+        # volume: app-src
+
+        # optional; rsync --delete so removals on the host are mirrored too
+        delete: true
+
+        #{exclude_comment}
+        exclude:
+        #{exclude_list}
+
+        # optional; mirror binary to shell out to
+        command: rsync
+
+        # optional; extra flags appended to the mirror command
+        options: []
+
+        # optional; seconds between mirrors
+        interval: 2
+
+        # optional; exec (default, mirrors into the running container) | run (always a fresh container)
+        mode: exec
+
+        # only needed if sync.mode: run (or under mode: compose); image the mirror container runs
+        # image: your/image:tag
+
+        # alternative to image — let wip build a small dedicated mirror image itself
+        # build:
+        #   dockerfile: |
+        #     FROM alpine:latest
+        #     RUN apk add --no-cache rsync
+
+        #   optional (default: wip-sync-<container>:latest)
+        #   tag: wip-sync-app:latest
+      YAML
+    end
+
+    def container_template
+      <<~YAML
+        version: 1
+
+        # container | compose | compose-native (see README)
+        mode: container
+
+        # TODO: rename freely, as long as it matches a key under dependencies: below
+        container: app
+
+        wslc:
+          # optional; wslc binary/path wip shells out to ("auto" resolves it for you)
+          command: auto
+
+        # optional; container network name (mode: container only)
+        # network: my-network
+
+        dependencies:
+          # this is the container wip creates, execs into, and runs commands in
+          app:
+            # TODO: image to run
+            image: your/image:tag
+
+            # TODO: adjust to match your image, or delete this line
+            workdir: /app
+
+            # optional; keep stdin open / allocate a tty
+            interactive: false
+
+            # optional; remove the container after each run
+            remove: true
+
+            # optional; environment variables passed to the container, e.g. {FOO: bar}
+            env: {}
+
+            # optional; published ports, e.g. ["3000:3000"]
+            ports: []
+
+            # optional; extra -v specs beyond the sync mounts below
+            volumes: []
+
+        #{COMMANDS_EXAMPLE}
+
+        # optional; mirrors the source into a named volume instead of bind-mounting it live
+        sync:
+        #{sync_extras}
+      YAML
+    end
+
     def compose_template
       <<~YAML
         version: 1
-        mode: compose-native # wip parses #{compose_file} itself and drives wslc directly — no external
-                              # compose-for-wslc binary needed. Prefer a real compose tool instead? Use
-                              # mode: compose (see README "Compose mode") and set compose.command.
+
+        # wip parses #{compose_file} itself and drives wslc directly — no external
+        # compose-for-wslc binary needed. Prefer a real compose tool instead? Use
+        # mode: compose (see README "Compose mode") and set compose.command.
+        mode: compose-native
 
         wslc:
-          command: auto # optional; wslc binary/path wip shells out to ("auto" resolves it for you)
+          # optional; wslc binary/path wip shells out to ("auto" resolves it for you)
+          command: auto
 
         compose:
-          service: app # TODO: which service in #{compose_file} wip run/exec/NAME target
-          # file: #{compose_file} # optional; override which compose file wip parses (default: auto-detected)
-          # project: #{compose_project_default} # optional; project/network name (default: this directory's name)
-          # command: # only used under mode: compose (external compose-for-wslc binary); unused here under compose-native
+          # TODO: which service in #{compose_file} wip run/exec/NAME target
+          service: app
+
+          # optional; override which compose file wip parses (default: auto-detected)
+          # file: #{compose_file}
+
+          # optional; project/network name (default: this directory's name)
+          # project: #{compose_project_default}
+
+          # only used under mode: compose (external compose-for-wslc binary); unused here under compose-native
+          # command:
 
         # network: is derived from compose.project above (or this directory's name) — setting it
         # directly conflicts with compose: (ConfigError), so it's intentionally left out here.
 
         #{COMMANDS_EXAMPLE}
 
-        sync: # optional; mirrors the source into a named volume instead of bind-mounting it live
-        #{SYNC_EXTRAS}
+        # optional; mirrors the source into a named volume instead of bind-mounting it live
+        sync:
+        #{sync_extras}
       YAML
     end
   end

data/lib/wip/version.rb

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

metadata

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